Raven-1/docs-site/docs/agent-integrations.md
userName20260323 259d1f52fc
fix(*): regenerate sub-agent prompt files on every launch (#987)
## Summary

The research, code, oncall and ppt agents keep prompt files in their
workspace that the model reads on every turn:
`agent_memory/profile/soul.md`, `agent_memory/profile/agent.md` and
`TOOLS.md`. They were written only when absent (`seed_once`), so after a
raven upgrade or a config change the model kept reading the text of the
first launch while the gates enforced the current release. A
Raven-Research install seeded before the reader layout still asked the
model for the `## Answer` / `## Findings` / `## Limitations` report
while its shape gate checked the reader layout.

These files are now generated output:

- `write_generated()` in `raven/config/product_render.py` rewrites a
product-owned file from the release and the rendered config on every
launch.
- An operator's own lines go in the sibling `*.local.md` file
(`agent_memory/profile/agent.local.md`, `soul.local.md`,
`TOOLS.local.md`) and are appended after the product text at the next
launch. They must be UTF-8: one in another encoding (an editor's legacy
code page, GBK for example) raises a decode error that names the
`*.local.md` and asks for UTF-8, rather than one naming the generated
file.
- A receipt beside each file (`.<name>.generated.sha256`) records
`<owner> <digest>` for the last text written. A file the caller's own
receipt lines do not name (edited in place, written by another product,
or left by an older release) is backed up to `<name>.bak-<time>-<pid>`
before it is replaced, and the log says which of those it is when the
receipt can tell. A backup is never readable by more accounts than the
original: on POSIX an owner-only copy; on Windows, where a new file
takes its folder's inherited ACL whatever mode it is created with, a
hard link to the file itself, so it keeps the file's security descriptor
and no bytes are written. A Windows volume that cannot hard-link refuses
the backup, and a failed backup leaves the file untouched. While the
target changes, the receipt names both texts, so a failure between the
two writes never leaves a file the next launch cannot recognise.
- `product_text=None` (raven-code's `CODE_CONDUCT=off`) removes only a
file this product wrote; an edited one, or another product's file and
receipt, is left alone.
- The launchers pass `adopt=True`, since their home is the product's own
ACP home, and refuse to start with the file named when a prompt cannot
be written. On a raven without `write_generated` they fall back to
seeding once and log that the file will not be refreshed.
- The ppt engine writes into whatever home its plugin is granted, which
can be a host's or another product's, so it passes `adopt=False`: it
replaces only a seat its own receipt, or the digest of a prompt it has
shipped, shows it wrote. A test fails when a ppt prompt changes without
its digest being added. It marks its identity written only once the
write lands and retries on the next turn otherwise. A seat that fails
does not stop the other seats; the host's template sync waits for the
retry, since it would fill the failed seat and a seat the engine did not
write is never replaced. A seat it leaves alone is logged at DEBUG, not
WARNING: in a host's home those are the host's own, every process, with
nothing to act on. The notice says how to hand a seat back (move the
lines into `*.local.md`, delete the file), which is what a seat edited
in Raven-PPT's own home before this release needs; the docs name that
exception.
- raven-code's earlier per-file receipts and legacy digests are still
honoured, so untouched copies are refreshed without a backup.
- `atomic_replace()` takes a `newline` argument so generated files stay
LF on every platform. It also removes its temp file when the replace
fails, and removes a temp file already present before it writes,
clearing the read-only attribute first: Windows refuses to replace a
read-only target once the temp file has taken its mode, and the
read-only temp file left behind used to fail every later launch even
after the target was made writable again.
- The temp file `atomic_replace()` writes is created no more open than
the target from its first byte. On Windows a new file takes its folder's
inherited ACL and `os.replace` (`MoveFileExW`) moves that descriptor
onto the target, so a prompt kept private in a folder other accounts may
read came back readable by them, `*.local.md` lines included. When the
target exists, the temp file is now made by `CreateFileW` with the
target's DACL as `GetFileSecurityW` reads it, and the save is refused
when that DACL cannot be read. On POSIX it is created with the target's
mode rather than the umask default, closing the span in which the new
text sat in a wider file until the chmod. This holds for every caller
that passes no explicit mode, `config.json` included. The Win32 bindings
behind it are declared once per process, behind a cache: a structure
defined per call left a new ctypes pointer type, about 6 KB, alive for
every save.

Docs: `agents/README.md` (the seed-once contract becomes "Regenerated
prompts", with rollback steps), `docs-site` agent integrations (en and
zh), `CONTEXT-MAP.md`, and `CHANGELOG.md` (an unreleased entry that
promised the old behaviour, plus a Fixed entry).

Tests whose meaning changed: seven existing tests asserted that an
edited prompt is never overwritten; they now assert it is backed up and
regenerated. The raven-code launcher test fixture now pins
`CODE_CONDUCT` and `CODE_CONDUCT_DISCIPLINE` to `on`: a deleted switch
fell back to the developer's `.env`, and two conduct tests on main
already failed with `CODE_CONDUCT_DISCIPLINE=off` for that reason.

Checked and deliberately not changed (documented in `agents/README.md`):

- The processes of one product (one per model binding) share these
files, so a launch can change what an older process still running reads
on its next turn. Closing that needs a per-process snapshot or
in-process injection of the prompt, which is a separate change.
- Backups are never deleted automatically.
- Host workspace templates (`USER.md`, `HEARTBEAT.md` and the rest) are
the user's files and stay write-if-missing.
- A file removed from a release is not removed from an installed
`~/.raven/agents` copy. Nothing loads such a leftover today: modes are
read by label, tools are imported by name, and no release has removed a
skill directory.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Run at the head of this branch, rebased on the current main:

- `uv run pytest -q`: 32739 passed, 17 failed, 147 skipped, 2 xfailed.
The same 17 test IDs fail on the current main in a clean worktree with
the same interpreter and the same fetched tokenizer dictionary (proxy
redaction, tokenizer data, network-safety resolution, install script,
document converters, node runtime, trajectory time zone); none is
introduced here.
- `uv run pytest tests/test_agents_code_launcher.py -q` with
`CODE_CONDUCT` and `CODE_CONDUCT_DISCIPLINE` each set to `off` in the
environment, alone and together: 79 passed in all four runs.
- `make lint-python lint-imports lint-types lint-deps`: all pass, 10
import contracts kept, no dependency issues.
- `scripts/check_commit_messages.py`, `scripts/check_source_language.py`
and `scripts/check_large_files.py` over `origin/main..HEAD`, and `git
diff --check`: pass.
- Each fix was reverted on its own and its test went red: the receipt
written after the target, a failed target write, the backup mode, the
ppt `adopt=False` guard, receipts without an owner, an undeletable
earlier receipt, the `*.local.md` read-back from the assembled system
prompt, the temp file a failed replace leaves behind, and the temp
file's mode while it holds the new text.
- Windows review findings:
`test_a_windows_backup_is_the_edited_file_itself_so_its_acl_comes_with_it`
and `test_a_windows_backup_the_volume_cannot_link_is_refused_not_copied`
force the link path on Linux;
`test_a_failed_replace_takes_its_tmp_with_it` and
`test_a_read_only_tmp_a_dead_writer_left_does_not_block_the_replace`
cover the temp file on every platform;
`test_the_tmp_is_never_more_open_than_the_target_while_it_holds_the_new_bytes`
pins the POSIX mode from creation;
`test_a_read_only_prompt_regenerates_once_it_is_writable_again`
(read-only retry) and
`test_a_private_windows_prompt_keeps_its_own_dacl_when_regenerated_and_backed_up`
(a private prompt in a folder every local user may read keeps its own
DACL through regeneration and backup, read back with `icacls /save`) run
on Windows only.
- The `Windows ACP stdio` CI job gains a step that runs
`tests/test_config_product_render.py` and the two temp-file tests
natively. On the Windows runner: 158 passed, 2 skipped (the two
POSIX-mode tests), the DACL, read-only retry and hard-link backup tests
among the passes.
- Diff coverage over `raven/` with the related suites: 94.12%, above the
90% gate.
- Second-round review findings, each test red without its fix:
`test_an_addendum_that_is_not_utf8_is_named_and_nothing_is_written`,
`test_a_local_file_that_is_not_utf8_is_named_when_the_launch_stops` and
`test_an_addendum_that_is_not_utf8_names_itself_and_holds_back_no_other_seat`
(the decode error names the addendum; the ppt engine writes the other
seats and holds the sync);
`test_a_hosts_own_seats_are_left_alone_without_a_warning_in_every_process`
and `test_a_seat_left_alone_says_how_to_hand_it_back` (DEBUG level, and
the notice's instructions);
`test_the_windows_bindings_are_declared_once_not_per_save` (Win32
stand-ins on Linux, two saves load each DLL once).

Windows is covered by the CI step above, not by a local run. The CRLF
fold of an older copy is reasoned, not run. `npx commitlint` is not
installed on the machine this was run on; the Python commit check above
was run instead.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

- User-visible: on the first launch after upgrading, each agent rewrites
its prompt files. A file edited in place, or left by an older release
without a receipt, is copied to `<name>.bak-*` and the launcher log
names the copy; an in-place edit stops taking effect until its lines are
moved into `*.local.md`. A `*.local.md` that is not UTF-8 stops the
launch with the file named. In Raven-PPT's own home a seat edited before
this release keeps the edit, and its `*.local.md` is not applied, until
the seat is deleted. A Raven-Research install seeded before the reader
layout switches to it at that launch.
- Security: a backup is never readable by more accounts than the file it
keeps (an owner-only copy on POSIX, a hard link keeping the file's ACL
on Windows), and a replaced file keeps its own mode, and on Windows its
DACL, from the temp file's first byte; receipts hold product names and
digests only; `*.local.md` is operator-owned and carries the same trust
as editing `agent.md` did before.
- Compatibility: a launcher running on a raven without `write_generated`
seeds once and logs it; the ppt engine on such a raven keeps
write-if-missing. On a Windows volume that cannot hard-link (FAT32,
exFAT, some network shares), an edited prompt file stops the launch with
the file named, until its lines move to `*.local.md` and the file is
deleted. On Windows, a save through `atomic_replace()` whose target's
DACL cannot be read is refused rather than made with the folder's ACL.
- Rollback: revert this change, then stop the product's processes,
delete each generated file whose `.<name>.generated.sha256` receipt
still names its current text, and relaunch so the older code seeds its
own. `*.local.md` files, backups and edited files are left as they are.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A

---------

Co-authored-by: userName20260323 <270284818+userName20260323@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
2026-10-19 17:36:03 +08:00

23 KiB

Agent Integrations

Use this guide to connect and operate existing agents. If you are building a new Raven agent, see Building an Agent; if you are implementing an ACP, CLI, HTTP, or other backend, see Protocol and Backend Integration. For wire messages and lifecycle details, see Agent Protocols.

Agent origin and runtime

“Raven agent” and “external agent” describe who supplies the agent. kind describes the runtime backend Raven uses. These are independent axes: a Raven-shipped agent can use ACP, and an external agent can use ACP, CLI, or HTTP.

Integration Runtime configuration Execution boundary
In-process backend kind: builtin A Raven loop in the host process
Raven-shipped agent Discovered folder, kind: acp Launcher starts Raven with the agent's own configuration
External local agent kind: acp or kind: cli in subagents.agents Another product's process and native policy
OpenAI-compatible HTTP agent kind: openai in subagents.agents Remote endpoint; no local tool loop in this backend
A2A peer a2a.peers plus a2a_send An independent host, outside the sub-agent roster

spawn and DAG nodes select from one roster. A node must use a name or worker label actually advertised by the current tool; a familiar product name alone does not install, enable, or authenticate an agent.

Raven-native agents

Agent Best for Important boundary
Raven-Code Coding, debugging, and verification Edits real files; partition parallel writers' files, and treat todo completion as a claim rather than test evidence.
Raven-Design Visual design, review, and presentation work Requires design/media readiness; routes deck requests to hidden Raven-PPT.
Raven-Oncall Running and watching multi-round or remote work Needs target-machine access, budget, and stop conditions; the first response does not mean the job finished.
Raven-PPT Producing .pptx decks Normally enters through Raven-Design; needs deck engine, templates, rendering, and media requirements.
Raven-Research Live-web research and sourced reports Needs the research profile and credentials; it is not a general coding or chat delegate.

These five definitions are not necessarily five visible roster entries. The shipped Raven-PPT manifest is hidden behind Raven-Design's routing; an operator's local manifest may differ. Routing also considers declared requirements, attachments, and tier, so a task does not always run on the same implementation as the visible entry.

Definitions are discovered from agent folders, including the user-owned $RAVEN_HOME/agents/ tree. Readiness depends on the runtime and any declared engine wheel being installed in the interpreter that launches the agent. Restart the resident host after changing a definition to ensure its live roster is rebuilt. Do not assume that changing a display name creates a new identity. Set them up through raven onboard or the WebUI agent settings.

From a TUI, WebUI, or configured channel, name the desired roster entry in the request and state the workspace, allowed side effects, and evidence you expect. For a DAG node, set subagent to the currently advertised roster name; a generated worker label is valid only for the current run_subagent_dag call. Stored Playbooks must use a registered roster name, not a turn-local label. A display name that is not in the current roster does not select an agent.

Calling the five native agents

Calling surface Support Notes
Host delegation through spawn All five, when enabled and ready Ask from the TUI, WebUI, or a configured channel; use the advertised roster name. Raven-PPT normally enters through Raven-Design's route.
Stateful instance chat ACP agents that advertise stateful sessions Continue an instance from the WebUI instance panel or the corresponding RPC; check the live capability snapshot before relying on resume.
run_subagent_dag node Advertised roster agents Put the roster name in subagent; generated Worker Table labels are turn-local and cannot be used in stored Playbooks.
Playbook Registered roster agents A Playbook ultimately dispatches through the same DAG registry; use Raven-Design for the normal Raven-PPT route.
Direct ACP over stdio All five Start the product launcher and speak newline-delimited JSON-RPC. Raven-Research starts ACP without an --acp flag.
One-shot CLI hosting Raven-Code only Use its launcher with --task or --prompt-file; --session continues the CLI conversation.
Messaging channels All host-delegated agents The channel reaches Raven first; delegation then uses the same roster and permissions.
Direct A2A call to one native agent Not supported A2A exposes a Raven host, not five independent native-agent endpoints.

The first four surfaces are host-level ways to delegate work; only direct ACP and Raven-Code's CLI hosting start a native product launcher explicitly. A successful readiness probe or delegation receipt is not evidence that the task completed; inspect the result, files, and tests or report artifacts.

Minimal ACP invocation

Each shipped entry is started by its launcher. Use the corresponding command:

Agent Launcher command Note
Raven-Code python agents/raven-code/run.py --acp Also supports one-shot CLI hosting.
Raven-Design python agents/raven-design/run.py --acp Requires the design engine.
Raven-Oncall python agents/raven-oncall/run.py --acp Requires registered target-machine access for operational work.
Raven-PPT python agents/raven-ppt/run.py --acp Normally reached through Raven-Design; requires the PPT engine.
Raven-Research python agents/raven-research/run.py ACP is the default hosting; this launcher has no --acp flag.

Use the interpreter that has Raven and the agent's declared engine wheel installed. Request a deck through Raven-Design in normal use rather than selecting the hidden Raven-PPT route directly.

For example, start Raven-Code:

python /absolute/path/to/Raven/agents/raven-code/run.py --acp

The launcher renders that agent's config and starts raven acp over stdin and stdout. Send one JSON-RPC object per line; keep logs and wrapper output off stdout. After the process starts, the smallest useful request sequence is:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{}}}
{"jsonrpc":"2.0","id":2,"method":"session/new","params":{"cwd":"/absolute/path/to/project","mcpServers":[]}}
{"jsonrpc":"2.0","id":3,"method":"session/prompt","params":{"sessionId":"<session-id-from-session-new>","prompt":[{"type":"text","text":"Reply with one sentence; do not edit files."}]}}
Field or argument Meaning
--acp Serve the agent over stdio ACP; it is not an HTTP listener.
python Use the interpreter that has Raven and the agent's declared engine wheel installed.
protocolVersion ACP protocol version requested during the handshake; Raven currently uses 1.
clientCapabilities Features the caller can handle; {} is the minimal declaration.
cwd Absolute task workspace for the session; it is not the agent's ACP home.
mcpServers Per-session stdio MCP attachments; use [] when none are needed.
sessionId The identifier returned by session/new; reuse it for later prompts.
prompt An array of content blocks; the minimal block has type: "text" and text.

The server may emit session/update notifications between these requests. Read them, and handle permission or question requests before waiting for the final prompt response. The full lifecycle and negotiated capabilities are in Agent Protocols.

Task prompt templates

Use the advertised roster name and state the scope, allowed side effects, and evidence you expect. These one-line templates are starting points, not proof that a task can run or has completed:

Agent Example request
Raven-Code Raven-Code: inspect the parser in src/parser.py; edit only the parser files; run the matching tests; report the command output. Do not commit or push.
Raven-Design Raven-Design: review this dashboard for hierarchy and accessibility; propose concrete visual changes and save the feedback to the project workspace.
Raven-Oncall Raven-Oncall: run this parameter sweep on the registered lab machine; use a two-hour budget; stop failed workers; compare each round and report the final artifacts.
Raven-PPT Raven-PPT: create a .pptx product-review deck from these notes; use Raven-Design when possible; render every slide and return unresolved issues.
Raven-Research Raven-Research: compare these approaches using sources from the last year; cite material claims with URLs and write the report to the requested workspace file.

For every agent, verify readiness before a real task and inspect the final answer, generated files, and task evidence afterward. ACP readiness or a listed roster row proves that the process can be started; it does not prove that the task completed successfully.

Raven-Code: workspace and verification boundaries

Raven-Code's code-flow adds product behavior beyond an identity prompt. Give each task a bound project directory, explicit file ownership, allowed side effects, and a verification command; inspect the files, command output, and Harness Manifest afterward.

Area Boundary
Project instructions AGENTS.md, CLAUDE.md, and CONTEXT.md are read from the working directory under configured selection, path confinement, and prompt budget; they are not Agent-home bootstrap files.
File and workspace state File tools track versions read by the session; with read-before-edit, unread or externally changed versions are refused. Shared checkouts expose the same HEAD and changes; notices and the read ledger are not file locks or worktree isolation, and full writes are not universally guarded.
Task state todo persists per session; completion is a model claim, not test evidence. Existing sessions restore their checklist, while a new task needs a genuinely new session; in-place /new retains the session key and may not reset this product checklist.
Git evidence The Harness Manifest reports changes, commits, blockers, and shared-workspace attribution in ACP response metadata; do not infer Git facts from “ready”.
Product configuration The Raven-Code launcher enables its product configuration. Installing code-flow elsewhere does not enable every capability; notices/reports and the replacement tool face have separate gates.

Request example: “Inspect project instructions, fix this parser bug in the owned files only, run matching tests, and report remaining changes or blockers. Do not commit or push.”

For follow-ups read Working with sub-agents; for background jobs read Long-running work (Oncall). See the implementation case study for the launcher and harness details.

Connect external agents

The following presets are declared in the current source. This is a list of supported configuration paths, not a claim that every vendor release or your local installation has passed a live task.

Preset key Transport and launcher Check before use
claude_code ACP adapter via npx Adapter download/runtime and the child's authentication
codex ACP adapter via npx Preset sets INITIAL_AGENT_MODE=agent-full-access; assess host and network access
opencode opencode acp Current preset withholds session MCP delivery via sessionMcp: false
hermes hermes acp --accept-hooks Native authentication; the flag accepts previously unseen shell hooks
openclaw openclaw acp Its gateway and authentication; startup has a longer handshake allowance
mirothinker OpenAI-compatible HTTP Endpoint/model/key; preset opts out of stateful replay
mirasim_<agent> Raven's own ACP adapter over the Mirasim host's protocol Mirasim running on this machine, the agent installed inside it, and the mirasim CLI on the login shell's PATH (the check that offers the rows); session MCP withheld via sessionMcp: false

GitHub Copilot, Qwen Code, CodeBuddy, Qoder, Grok Build, Kimi Code, and Pi also have preset entries. Adapter versions and exact commands are maintained in raven/agent/subagent/presets.py and raven/agent/subagent/acp_registry_presets.py. Prefer the installed version's preset instead of reconstructing its flags.

The mirasim_* presets reach the agents Mirasim runs, one row each: Claude Code, Codex, Kimi Code, Antigravity, Qwen Code, Grok Build, DSH, Pi and ZCode CLI, named Claude Code-Mirasim and so on. Such a row is the agent on the accounts and model routes set in Mirasim, which is why it can sit beside the same agent's own preset. The adapter ships with Raven (raven/acp/mirasim/), so nothing is downloaded; the {PYTHON} in its command becomes Raven's interpreter when the row is written to config; if that interpreter is later gone, as after an install moves, the row is pointed at the one serving Raven the next time the config is read. Its model list is Mirasim's for that agent, grouped under the agent's own name, Mirasim (the platform's quota) and Own key (keys you added to Mirasim). Mirasim's platform also runs the own models of Claude Code, Codex, Kimi Code and ZCode CLI, so for those four each such model is listed in both of the first two groups: under the agent's name it runs on your own account, under Mirasim on the platform's quota. Every turn names the route its model runs on, so choosing the other one moves an existing conversation to that route from its next turn. A session with no model chosen runs on Mirasim's default for the agent, route included.

The adapter is one more client of the Mirasim host already running on the machine -- the desktop app's, or the one Mirasim keeps on a machine it reaches over SSH -- so it starts nothing of its own, and Raven's turns show in the Mirasim app as they run. A turn streams: its thinking, text, tool calls, plan and the files it delivers reach Raven as they happen, and the context it used is reported when it ends. A cancel stops the turn. Text sent to a running turn is taken into it for Claude Code, Codex, DSH, Pi and ZCode CLI. Images reach Claude Code inline; another agent gets an image linked as a local file as that file's path, and refuses one sent inline. Sessions can be listed -- this agent's conversations in the given directory, including ones begun in Mirasim itself -- resumed, loaded with their whole history, closed and deleted. Deleting one also deletes its Mirasim conversation; the agent's own transcript files stay where it keeps them. A turn Mirasim starts on its own in a session Raven holds, such as a background job's report, is forwarded to Raven too, and what it stops to ask is left to the Mirasim app.

The adapter looks for the host in this order: the socket of the host Mirasim keeps on a machine it reaches over SSH (~/.mirasim-remote/run/server.sock, Linux and macOS only), then the desktop app on 127.0.0.1:4970 with the token it writes to run/local-4970.token under Mirasim's state directory (MIRASIM_HOME, else ~/.mirasim). When the host listens anywhere else, RAVEN_MIRASIM_HOST names it: unix:<path> for a socket (not on Windows, where the desktop app's port is the way in), or a loopback port as <port>, 127.0.0.1:<port>, localhost:<port> or [::1]:<port>. On Linux and macOS the adapter runs with the login shell's environment plus the row's own env, not Raven's, so set the variable in your shell profile, or in the env of the Mirasim rows that should use it; exported only in the shell that starts Raven, it does not reach them. On Windows the adapter inherits Raven's own environment, so setting it where Raven starts is enough.

What a turn Raven started stops to ask is put to Raven while the turn waits: a tool approval as a permission request, and a question -- Claude Code's AskUserQuestion when Mirasim's askTool setting is on, or an MCP server's form -- as an elicitation, answered by you or by Raven's question autofill. A client without forms has the question skipped and named in the reply. Question text, choices, replies and error details retain the sending agent's content. Raven leaves redaction decisions to that agent, including when a returned value matches a credential Raven itself holds.

Distinguish three claims when assessing compatibility:

  • Preset declared: Raven has a configuration template.
  • Handshake/probe successful: this installation starts and reports capabilities.
  • Task verified: a real task exercised authentication, tools, and output.

Hand-written integrations need their own checks at all three applicable levels.

Connect and verify

  1. Install and authenticate the external agent according to its own version. Ensure its executable is on the resident Raven process's PATH.
  2. Configure it from the WebUI's agent setup, or add a row to subagents.agents in the host config. Preserve existing rows and settings.
  3. Inspect the configured row and readiness result. ACP probing may launch a process and a shim may download code; a full task test can spend provider quota.
  4. Run a harmless task such as “Reply with one sentence; do not edit files.” Then verify any required file, tool, or resume capability separately.
  5. Enable broader delegation only after checking permissions and isolation.

A minimal custom ACP entry using an already installed Hermes executable:

{
  "subagents": {
    "agents": [
      {
        "name": "Hermes Agent",
        "preset": "hermes",
        "kind": "acp",
        "enabled": true,
        "command": "hermes acp --accept-hooks",
        "cwd": "/absolute/path/to/project",
        "readyTimeoutMs": 30000,
        "timeout": 600
      }
    ]
  }
}

This is a fragment to merge, not a replacement for your config. The hook flag has the security consequence stated above. ACP command launches a server: do not put {prompt}, {prompt_file}, or {agent_id} into it. readyTimeoutMs limits the handshake; timeout limits a task. The latter defaults to no automatic deadline when omitted.

For a CLI backend, command is an argv template. {prompt} is substituted as one argument, {prompt_file} names a prompt file, and no placeholder means stdin delivery. A resumeCommand must use {agent_id}; id provisioning and transcript parsing must agree with the CLI. Do not copy those fields into ACP.

For an HTTP backend, configure baseUrl, model, and credentials instead of a command. Host-side replay may provide conversation history, but it is not a remote native session. This backend cannot read local paths or accept MCP delivery. An OpenAI-compatible agent endpoint is distinct from changing Raven's main model provider.

Files, state, and credentials

Location or handle Responsibility
User working directory Files the task is authorized to read or change
Host Agent home Host identity, sessions, skills, and memory
Agent state root Launcher-rendered config and agent working state
Agent ACP home The child engine's identity, transcripts, and skill pool
instance Continue a child session where that backend supports it
Node id Address a recorded task/output in the host conversation

A CLI's readsLocalFiles is a declaration about its environment. ACP capabilities are negotiated and interpreted by its adapter. The HTTP backend has no local file access: send bounded content, not a host path. Configure memory identities only when that agent actually supports the intended memory path; adding metadata does not make an external product share Raven's memory.

Keep credentials out of prompts and shared manifests. A2A credentials are matched by origin, not by agent display name; its peer list is not an egress firewall. Follow the A2A guide.

The prompt files a native agent keeps in its ACP home -- soul.md and agent.md under agent_memory/profile/, and TOOLS.md -- are regenerated from the release and its config on every launch, so editing them in place does not last. Put your own lines in the sibling *.local.md file (agent_memory/profile/agent.local.md, for example); the next launch appends it after the product text. Copy in only what you still need: text from an older release can contradict the current one. Save it as UTF-8; a file in another encoding (an editor's legacy code page, GBK for example) stops the launch, and the error names it. A file that was edited in place, or that an older release left behind, is saved as <name>.bak-<time>-<pid> before it is replaced, and the launcher log names the backup. The regenerated file keeps the access rights the old one had. On Windows the backup is a hard link to the file, so it keeps them too; on a volume that cannot hard-link, the launch stops and names the file instead. Backups are not deleted for you.

Raven-PPT differs in one respect: its deck engine can share a home with the host, so it replaces only a file it can show it wrote. A soul.md, agent.md or TOOLS.md edited before this release is left as it is, without a backup, and its *.local.md is not applied. Move the lines you still need into the *.local.md file and delete the edited one; the next turn writes it fresh. A write the engine cannot make is logged and retried on the next turn instead of stopping it.

Security and troubleshooting

Outbound ACP automatically prefers an offered allow option. The parent's permission mode does not provide per-tool human review inside every external agent. Review native permissions, account privileges, writable mounts, hooks, and network access before using unattended delegation.

Symptom Check
Agent absent from the selectable roster Discovery, enabled/hidden status, routing, readiness
Engine unavailable Required wheel in the child interpreter, not merely another virtualenv
Handshake passes, task fails Provider credentials, tool prerequisites, child stderr
CLI output missing or garbled Exit status, transcript format, output parser
Instance does not continue Resume contract and negotiated session support
MCP selection not delivered Backend support and sessionMcp isolation policy
Remote agent cannot open a file Content versus host-path transfer

For graph failures see DAG Orchestration. For permissions and isolation see Permissions and Security.