ACP runtimes

Use ACP when a supported external agent CLI should supply the coding-agent behavior for an Awaken Agent. The CLI reasons and requests tools; Awaken keeps the Session ledger, permission decision, credential staging, placement, recovery, and final commit.

ACP is an inward-facing Brain protocol. It is not another frontend ingress. Managed Agents, AI SDK, AG-UI, A2A server, and MCP export project Awaken outward to callers; ACP adapts one supervised process into the neutral execution contract.

Choose the Brain separately from its isolation

Two independent choices define an ACP attempt:

1. acp:<id> selects the exact cataloged CLI contract.
2. sandbox_tier selects the process and filesystem boundary.

For example, acp:codex can run in a namespace or container. Codex is not an isolation tier. Placement validates both exact capabilities and fails closed when either is unavailable.

Static structure

flowchart LR
  Publication[Published ModelBinding<br/>backend_ref = acp:id] --> Registry[AttemptExecutorRegistry]
  Registry --> Executor[AcpRunExecutor]
  Executor --> Source[AgentChannelSource]
  Source --> Environment[Session Environment<br/>selected Sandbox tier]
  Environment --> CLI[Cataloged ACP CLI]
  CLI -->|ACP JSON-RPC| Executor
  Executor --> Policy[ToolPermissionPolicy]
  Executor --> Commit[claim-fenced Session commit]

ModelBinding.backend_ref is the immutable execution selector. It must match an executor registered for the exact value. AttemptExecutorRegistry does not guess a near match or fall back to Native. AcpRunExecutor opens an AgentSession through AgentChannelSource; a model change is ModelSwitch::Relaunch, not an in-place mutation of an opaque process.

The catalog is the single source of truth for supported commands, capability probes, model and credential delivery, Memory entry files, and portable CLI state. Adding a runtime is a catalog and capability-contract change, not an arbitrary executable setting.

Supported runtime matrix

Claude Code and Codex use the pinned ACP wrappers shown above. Gemini, OpenCode, and Hermes expose the listed direct entrypoints.

Model, credential, and Session differences

A runtime uses either its backend-owned login and model, or an Awaken-managed provider route. These launch modes are mutually exclusive. Backend-owned mode leaves provider material with the CLI. Managed mode projects the resolved endpoint, model, and brokered credential according to the catalog row.

For a LocalDir row, a configured SessionHomeProvider restores the eligible, credential-excluding subtree before launch and harvests it afterward. Without that host binding, execution still recovers from committed Awaken thread history, but native CLI state does not move across machines. None never means the Awaken Session is lost.

Sandbox tiers

Choose the tier from code trust, filesystem access, network policy, and the deployment’s available capabilities. Do not infer the tier from the CLI name.

Dynamic behavior

sequenceDiagram
  participant C as Coordinator
  participant W as Worker
  participant E as Session Environment
  participant A as ACP CLI
  participant L as Session ledger

  C->>W: claim attempt with backend_ref and lease epoch
  W->>W: check exact executor, capability, and Sandbox tier
  W->>E: realize Environment and stage non-ambient credentials
  E->>A: launch pinned command and initialize ACP Session
  W->>A: prompt, model/session options, and exact MCP projection
  A->>W: content, tool requests, permission requests, terminal result
  W->>W: apply neutral permission policy and supervise cancellation
  W->>L: append projected events through claim-fenced commit
  W->>E: harvest eligible CLI state and reap the process

The executor opens a fresh channel for each turn. Cancellation reaps the child process. Permission requests pass through the same neutral ToolPermissionPolicy as Native runs. The production path uses the ACP JSON-RPC codec; the newline codec is a fixture transport behind the same projection boundary.

Discovery runs bounded version and login probes and emits secret-free observations. Missing, timed-out, or unrecognized evidence fails admission. It does not copy a developer’s credential files or silently select another Brain.

What the system resolves without manual repair

These are lifecycle behavior, not troubleshooting steps. External action is not needed for them. The executor also relaunches once when the ACP handshake drops before session/new returns an id, before the prompt is sent, and before any Agent fact exists. That bounded retry is automatic.

Conditions to correct before starting a new Run

An ACP permission wait is not a failure: answer its committed resume ticket so the same Run can continue. A refusal or deadline is a terminal task outcome, not by itself evidence of a broken CLI. Never attach access tokens, credential files, generated provider configuration, or raw environment dumps to a diagnostic. Do not change backend_ref merely to force a fallback.

Select and verify a runtime

• Choose Claude Code or Codex when their coding-agent behavior and pinned wrapper contract are required.
• Choose Gemini when native ACP mode and its exact backend model flag fit the provider route.
• Choose OpenCode or Hermes when their listed API dialect fits, without promising exact backend-owned model selection.
• Select the Sandbox tier independently.

Verify awaken.runtime=acp:<id>, the resolved model route, credential mode, Sandbox policy, and committed Session events. Request shapes belong in Select models and ACP runtimes through the API.

The source includes a gated real-CLI, cross-directory recovery test. It requires a matching CLI and provider credentials and is not a default CI result. The documented mechanism therefore establishes an implemented recovery path, not a claim that every runtime/version combination is continuously exercised in a public environment.

See Execution modes and Brain, Hand, and Session Environment for the larger execution boundary.