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, 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, 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.

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.