feat(acp): serve the agent client protocol over stdio

[ZuyiZhou]

Summary

raven acp is now an agent an editor can launch: it negotiates, mints and reloads sessions, runs a turn, streams the reply and its tool calls, asks before acting, and answers a cancel while a turn is in flight.

Four commits, each one concern: the wire framing, the lane-to-session mapping, the shell approval families this surface needs, and the protocol layer itself.

The process model is a self-contained engine, not a client of a resident gateway. An ACP agent IS a stdio child of the editor, so there is nothing to mount onto unless a gateway happens to be running, and an agent that only works when another service is up is not an agent an editor can launch.

Notes on the parts that are not obvious:

• Every inbound frame is handled in its own task, because session/prompt is suspended for as long as the turn takes and session/cancel has to be read during it. Shutdown answers instead of cancelling: on EOF the pending prompts are settled as cancelled and the handlers return through their own code, so a finite input (a scripted client, a smoke test) still gets its replies.
• A prompt is never answered with a JSON-RPC error. A failed turn is explained as message content and then ends with a stop reason. Measured from the other side on another implementation: an error in reply to a turn-shaped request makes clients tear the whole turn down.
• The schema is vendored and pinned, and its blindness is measured rather than assumed: additionalProperties appears 118 times and is true in every one, method is an unconstrained string, and params accepts null. Validating a frame against the union therefore accepts an invented method name, so the tests validate payloads against their own definition and check method names against the metaschema separately.
• Questions take one of two paths by what the client declared. With elicitation forms, a question with no preset answers can come back as text. Without them it rides a permission request and a synthesised tool call, which the payload marks as synthesised rather than dressing up as a real one. The case that has no answer at all, a free-text question to a client with no elicitation, is recorded in the compatibility matrix instead of being papered over.
• Secrets are redacted before anything reaches the client, including the value under a key whose name says it is a secret. A credential file's path is deliberately NOT redacted: a path is not a secret, and hiding it would hide that the agent read credentials at all.
• Six command families ask before running on this surface. What that does not reach is written down: a sub-agent builds its own tool with its own policy and no responder, so a delegated command still runs unprompted.

The write tools now publish what they changed. Until now the diff field declared on tool.complete had no producer here, so it was always null. The file tools return a ToolResult carrying both the unified diff and the two file versions, and the registry, the loop and the outlet carry them through. The protocol needs the second form specifically: its diff content block is {path, newText, oldText}, which a rendered diff cannot fill. A reply's files reach the client the same way, as a media event carrying paths rather than bytes.

Divergences from the same layer in the sibling runtime, each measured rather than assumed:

• The compatibility matrix is corrected for this build in two rows. A model change during a turn is not refused, because config.set here has no busy guard. A sub-agent's output is untagged, because there is no direct sub-agent chat for the tag to distinguish.
• The self-verification suite is not included. It drives the ACP client's own capability probe, which this repo does not have, and porting a client subsystem to run one test file is the tail wagging the dog.
• The session/load smoke test is not included either, and the reason is worth knowing: nothing here can point a spawned agent at a throwaway session store. RAVEN_HOME steers tracing and the terminal runtime root only, and the config path has no override at all, so that test would either read the developer's real store or prove nothing. Load and replay keep their unit coverage; what is lost is the leg that read an actual file.
• The working-directory guard is checked against the configured home for the same reason, rather than against a temporary one.

Known fidelity losses, all in docs/specs/2026-08-21-acp-agent-compatibility.md: tool_call_update always reports completed because the event carries no success flag; rawInput is not sent because it carries a command line verbatim; there is no plan because its priority field is required and has no source here.

Stacked on #357, which is stacked on #356, which is stacked on #353. Merge order: 353, 356, 357, then this.

Reviewers: 0xKT, gloryfromca.

Type

• Fix
• Feature
• Docs
• CI / tooling
• Refactor
• Other

Verification

Commands run and their results:

• uv run --frozen --all-extras pytest -q -> 7375 passed, 19 failed. The same 19 that fail on the base branch: test_provider_rates.py (15) and test_agent_loop_usage_sink.py (4), pricing-table and network-cache tests unrelated to this change. Zero new failures.

• uv run --frozen python scripts/coverage_gate.py diff --base-ref feat/rpc_engine_assembly -> 100.00% (1718/1718 executable changed lines). The first run was 99.30%; the twelve uncovered lines were the framing module's public API and the oversized-diff branch, and cases were added for both.

• uv run --frozen python scripts/coverage_gate.py ratchet -> line +2.03pp, branch +3.08pp, PASS.

• raven/acp/ unit coverage: 100 percent line and 100 percent branch across 540 tests.

• Integration against the real binary, run with -m "": test_acp_stdio_smoke.py (6) and test_acp_adversarial_smoke.py (26) pass.

• uv run --frozen ruff check raven/ tests/ and ruff format --check -> clean.

• cd ui-tui && npm run lint:rpc -> generated.ts in sync. npm run type-check -> exit 0. npm test -> 998 tests passed.

• raven acp --help resolves through the real CLI app.

• Relevant tests pass locally

• Relevant lint / type checks pass locally

• User-facing docs or screenshots are updated when needed

Risk

A new CLI surface plus three optional wire fields and one new event variant, all defaulted, so a client that ignores them behaves as before.

Two changes reach beyond the new surface and deserve a second look. The file tools now return a ToolResult where they returned a string: the model-facing text is unchanged and the registry already accepted both shapes, but every caller of write_file and edit_file goes through that boundary. And shell approval gains six command families, though only for a surface that registers them; the terminal registers none and behaves exactly as before.

One dodge in the approval walk stays open and is pinned by a test: a command runner (timeout 60 npm install) hides its inner command. Verified that the same wrapper already hides a delete from the existing check, so the new gate is no weaker than the surface it joins, and no stronger.

Rollback is a plain revert: no data migration and no persisted format change.

• Security impact considered
• Backward compatibility considered
• Rollback path is clear for risky changes

Related Issues

N/A