## 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>
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
- Install and authenticate the external agent according to its own version.
Ensure its executable is on the resident Raven process's
PATH. - Configure it from the WebUI's agent setup, or add a row to
subagents.agentsin the host config. Preserve existing rows and settings. - 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.
- Run a harmless task such as “Reply with one sentence; do not edit files.” Then verify any required file, tool, or resume capability separately.
- 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.