The ACP bridge — dispatching agent workers

The Agent Client Protocol (ACP) bridge turns the platform into a client of real coding agents: it dispatches headless workers — opencode, zcode, Claude Code — as supervised, identity-scoped sessions, driven by a brief and observed through a trace.

Why delegate at all

Context is the scarce resource. A cold worker session costs roughly 21k tokens before its first useful token; a full structural survey of a 3,000-line project dispatched to a worker costs about 230 fresh tokens in your own context. The rule of thumb: long briefs, few of them — and answer one-line questions yourself.

The moving parts

Piece What it is
Worker A headless agent session (opencode, zcode, Claude Code) executed under the bridge
Brief The self-contained task file the worker executes. Long, specific, with pointers to files and a required NOT CHECKED section
Trace The narration log of the dispatch. Always --trace FILE — a dispatch buffers its narration until it exits, so without a trace you are blind
Identity key The worker acts as an identity. Keys are scoped per identity; a worker holding your key could author memories and close tasks as you
Sandbox --cwd is the worker's world. Anything outside is denied unless explicitly allowed

Modes

  • --mode plan — read-only: edit tools are disallowed. Use for surveys, reviews and validation passes.
  • --mode build — full access inside the sandbox. Use for implementation work, ideally in a dedicated worktree.

Harnesses

--harness picks the worker runtime (default opencode):

Harness Protocol Notes
opencode ACP native The default. Model ids as opencode names them (provider/model)
dsh ACP native Requires DSH_REPO to name the dsh checkout
zcode Proprietary (translated) ZCode Protocol bridged to ACP by a translator — the platform's client code stays protocol-agnostic. Drives GLM on the z.ai coding plan

For zcode, --model uses the format <providerId>/<modelId>[$<reasoningLevel>], e.g. the default account:zai-individual-coding-plan/GLM-5.3-Flash$low — the reasoning level is required for Flash (low is valid, enabled is rejected by the protocol schema).

The zcode harness needs a built checkout of the zcode CLI source (override with ZCODE_REPO); traces record the raw native protocol for every harness, so a zcode trace shows ZCode Protocol frames, not ACP.

Dispatching

atamaia acp run \
  --brief ./brief.md \
  --cwd /repo/worktree \
  --identity worker-name \
  --mode build \
  --trace ./run.trace

Watch it live (or after the fact):

atamaia acp watch --trace ./run.trace --follow
atamaia acp ps --all

Writing a brief

A brief is a task for a capable stranger who cannot see your screen:

  1. State the outcome, not the journey — what exists when the work is done.
  2. Name the files and entry points up front; workers cannot guess your layout.
  3. Ask for citations, not verdicts — findings are cheap, verifications are worthless until you repeat them yourself. Verify the success path, not just that failures fail.
  4. Require a mandatory NOT CHECKED section and read it first.
  5. Never put credentials in a brief. Briefs are data; data gets copied.

Lane ownership

When multiple agents work the same repository, lanes keep them from colliding: one owner per workstream, hand-offs in writing, prod deploys recorded. See CLI & editor integration for the tool wiring and the atamaia CLI for the command surface.

Last updated