feat(runtime): production ACP adapter for opencode and Claude Code

[FreshlyBrewedCode]

What

This PR turns the finding-13 spike adapter into the production ACP adapter (ADR 0013 §1, §3–§6). It runs beside the opencode adapter, and #64 makes it the default.

• src/runtime/acp-agents.ts: the agent definitions and the availability check.
  • claudeAgent() launches the bundled claude-agent-acp on the daemon's own bun. opencodeAgent() launches opencode acp. acpAgent(kind, { hostSettings }) picks one of the two.
  • Host settings default to "ignore":
    • Claude: _meta.claudeCode.options.settingSources: ["project","local"].
    • opencode: XDG_CONFIG_HOME and OPENCODE_TEST_HOME point at empty directories that factory owns. A factory plugin (acp-opencode-plugin.ts, opencode's shell.env hook) hands the host's XDG_CONFIG_HOME back to every shell command, so gh and git keep their config. The host's OPENCODE_CONFIG* variables are dropped.
  • Environment scrub: CLAUDECODE and CLAUDE_* are removed from the agent's environment. The credential variables stay: CLAUDE_CONFIG_DIR, CLAUDE_CODE_OAUTH_TOKEN and CLAUDE_CODE_USE_BEDROCK/_VERTEX.
  • checkAgents(kinds) returns {agent, problem}[]. It reports opencode missing from PATH, and Claude not logged in (read from the bundled CLI's auth status --json).
• src/runtime/acp-adapter.ts: acpAdapter(definition, { onDiagnostic?, cancelGraceMs? }).
  • Model: required. If the agent doesn't offer it, the step fails before the prompt, and the error names the agent and gives a sample of the ids it does offer.
  • Permission: answered with allow_always, falling back to allow_once.
  • Usage: each usage_update becomes a CUSTOM acp.usage chunk carrying a new usage signal (context: {used,size}, cost?: {amount,currency}), in arrival order.
  • Cancel: session/cancel, then a kill after a grace period, and always a kill in finally (SIGKILL if the process lingers).
  • Exit mid-turn: the step fails with the exit code and the tail of stderr.
• AgentSignal gains usage. The runtime ignores it for now; feat(events): context and cost per agent step, ACP-aware run detail #65 records it.
• AgentStepChunkError now starts with the adapter's message, so AgentStepFinished.error reads AgentStepChunkError: claude has no model "…" instead of a bare stack.
• spikes/13-acp-agents.ts is adapted to the production API and has a new isolation mode.
• Finding 13, addendum 2 records the isolation results.

Tests

bun run check is green (377 tests). The new unit tests run against a fake ACP agent over stdio, built on the SDK's AgentSideConnection (test/fixtures/fake-acp-agent.ts). They cover:

• model selection and rejection, a missing model, and an agent with no model option;
• the allow_always answer;
• usage chunks and signals, and their order;
• structured output;
• refusal surfacing as RUN_ERROR;
• the environment scrub;
• cancel that settles as cancelled, an agent that ignores cancel and is killed after the grace period, and a crash mid-turn that carries the exit code and stderr;
• a start failure;
• a run cancelled through startRun that leaves no process behind.

Separate tests cover the definitions, the plugin hook and the auth parsing.

Live validation (this host)

run	result
run claude sonnet	completed. implement 7.8 s, report 5.7 s. Model switched from haiku to sonnet. One ask (Edit math.ts), answered allow_always. Structured output on tier 1. Per-step cost 0.039 / 0.027 USD in acp.usage
run opencode opencode/big-pickle	completed. implement 8.3 s, report 6.6 s. Structured output on tier 1. (One earlier run took 244 s on slow provider calls; a rerun was 10.8 s.)
cancel claude sonnet	RunCancelled 2 ms, settled 22 ms, 0 of 2 processes alive
cancel opencode …	RunCancelled 2 ms, settled 83 ms, 0 of 1 processes alive
bad-model claude / opencode	failed at 0.8 s / 1.5 s, before the prompt, with the offered ids
env scrub (run from inside Claude Code)	12 CLAUDE* vars in the parent, 0 passed to the agent. Parent sentinel values appeared 0 times in either agent's shell
checkAgents	[] on this host (0.25 s). With HOME pointed at an empty dir and opencode off PATH, both problems are reported

Isolation (finding 13, addendum 2):

• Claude: settingSources: ["project","local"] hides the user's skills, the anthropic-skills plugin and the user CLAUDE.md. 47 skills are listed with include and 14 with ignore. The project's CLAUDE.md and skills stay.
• opencode: OPENCODE_CONFIG_DIR only adds a directory; with it set, 715 models were still offered. What hides the host config is XDG_CONFIG_HOME, the plugin and OPENCODE_TEST_HOME:
  • skills drop from 51 to 3 (the built-in one and the two project skills);
  • models drop from 715 to 39 (the host's omniroute provider is gone);
  • in the shell, XDG_CONFIG_HOME=/home/karl/.config is restored, gh auth status is logged in, and git's global config is read;
  • the step's cached input fell from ~13.9k to ~7.7k tokens.

Deviations / notes for later layers

• OPENCODE_TEST_HOME is undocumented. It is a test hook, and it is the only way I found to hide opencode's home-level reads (~/.claude/skills, ~/.agents/skills, ~/.claude/CLAUDE.md). If opencode drops it, the host's skills come back into runs, but nothing breaks. OPENCODE_DISABLE_CLAUDE_CODE* would also hide the project's Claude files. ADR 0013 §3 left the mechanism to this ticket; test(e2e): live validation of ACP agents, docs and ADR acceptance #67 can fold it into the ADR.
• The scrub keeps four credential-related CLAUDE_* variables (listed above). This follows ADR §3: "credentials are not settings".
• Deferred:
  • feat(workflow): choose agent and model separately, ACP as the default runtime #64: the config knob (hostSettings), agent in AgentAdapterOptions, and calling checkAgents at daemon start.
  • feat(events): context and cost per agent step, ACP-aware run detail #65: recording usage in AgentStepFinished.
  • refactor(runtime): remove the opencode adapter and in-sandbox serve #66: removing the opencode adapter, prepareWorkspace, and the abort-chain commentary in agent-step.ts.
  • test(e2e): live validation of ACP agents, docs and ADR acceptance #67: live crash, external_directory and RUN_ERROR scenarios.

Closes #63
Part of #62

🤖 Generated with Claude Code

[FreshlyBrewedCode]

Two fixes landed on this branch from the layer above (#71), both found in live runs through the daemon:

• 7f9e998 fix(runtime): send ACP an absolute cwd for a relative workspace. The default .factory/workspaces root is relative, and claude-agent-acp rejects a relative session/new cwd.
• 61856f2 fix(runtime): always pin the session's model over ACP. With host settings ignored, claude-agent-acp still reports the user's model setting as current, so skipping set_config_option on a match ran haiku steps on a 1M-context model.

🤖 Generated with Claude Code