Managoat.ACP

The client side of the Agent Client Protocol, as a session that outlives the turn. ACP is JSON-RPC 2.0 over newline-delimited JSON between a client (an editor, or a platform that runs agents for people) and an agent (claude-agent-acp, codex-acp, gemini, opencode). This package is the client: the peer that drives the handshake and the prompt, answers the agent's requests, keeps a permission request open for a human, reattaches to a turn that is still running after the client restarted, and reports everything to an owner process as plain messages. Plus the pieces a real deployment needs around it: a permission policy, block normalisation for rendering, usage accounting, and an OpenTelemetry tracer.

It is not a schema library. Messages are maps with the protocol's own wire names, and what the package adds is the part of a client the spec leaves to you. See How this relates to acpex and agent_client_protocol for the comparison and the recommendation.

# A writer is the whole transport: one function, bytes out.
writer = fn iodata -> Managoat.Sandbox.write_stdin(command, iodata) end

{:ok, peer} =
  Managoat.ACP.Peer.start(
    owner: self(),
    writer: writer,
    ref: command.ref,
    prompt: "run the tests and fix what fails",
    mode: :run,
    session_id: nil,
    cwd: "/home/sprite",
    mcp_servers: [%{name: "fs", command: "npx", args: ["-y", "@modelcontextprotocol/server-filesystem", "."]}],
    model: "claude-sonnet-4-6",
    permission_policy: %{"default" => "auto_allow", "execute" => "ask"}
  )

# Bytes in: from wherever the host's bytes arrive.
def handle_info({:stdout, %{ref: ref}, data}, state), do: Managoat.ACP.Peer.stdout(state.peer, data)

# Reports: every one is {:acp, ref, payload}.
def handle_info({:acp, ref, {:session, id}}, state), do: persist_session_id(id)
def handle_info({:acp, ref, {:lines, "acp", line}}, state), do: persist_line(line)
def handle_info({:acp, ref, {:permission_ask, request_id, tool, options}}, state), do: ask_a_human(...)
def handle_info({:acp, ref, {:done, stop_reason, usage}}, state), do: close_turn(stop_reason, usage)

# The next turn rides the same connection: no handshake, no resume.
:ok = Managoat.ACP.Peer.prompt(peer, "now open a PR")

The pieces

The transport is a callback

The peer's contract with the outside world is "bytes out by function, bytes in by cast". It takes a writer at start and is fed inbound bytes through Peer.stdout/2 from wherever the host's bytes come from — a sandbox owner forwards the sandbox's stdout message, a stdio host forwards a Port message, a test feeds a scripted reply. The library ships no transport, on purpose: every transport the peer has run over is push-shaped on the read side, so a behaviour with a read callback would be pretending to a symmetry that is not there, and a transport process would tie the peer's lifetime to it.

The writer must be total. A transport that has gone away answers {:error, reason}; the peer reports it once as {:failed, {:acp_write_failed, reason}} and stops writing. A writer that raised or exited instead would take the peer down without a report, and for a turn in flight that is a turn with no terminator.

The ref passed at start is echoed in every report, so an owner that runs several peers (or restarts one) matches on it and ignores a stale peer's messages without a second registry.

What the owner receives

Every message is {:acp, ref, payload}. The peer persists nothing and writes nothing but protocol; these are the whole contract.

Ten payloads, all from Peer. The two failure reasons at the end are worth matching on: one is the runtime's OAuth token belonging to an organisation that disabled subscription access, the other a provider refusing the model itself, and both reach the tenant as a sentence rather than an inspected tuple.

Permissions

A policy is a map of key to verdict plus a "default":

%{"default" => "auto_allow", "execute" => "ask", "rm -rf /" => "auto_deny"}

A request is matched most-specific-first: the tool card's title, then ACP's coarse kind (read, edit, delete, move, search, execute, think, fetch, switch_mode, other), then "default". Reach for kind unless you know the runtime's titles: claude-agent-acp titles a tool call with the command itself, so a title key matches exactly one invocation.

Permissions.effective(agent_policy, launch_policy) takes the stricter verdict for every key, so a launch may narrow a policy and never widen it, and Permissions.check_narrows/2 refuses a widening launch at the door with the key it would loosen. The ask timeout is the host's configuration, passed in: Permissions.ask_timeout_ms(configured_seconds) owns the default (five minutes) and the parsing, and a value it cannot read is the default, never "never deny". The library reads no configuration.

Blocks

Blocks.from_line/1 turns one stored protocol line into zero or more block maps; Blocks.from_update/1 takes the notification's params. Chunks are emitted one block per chunk and left for the renderer to concatenate.

user_message_chunk, plan, available_commands_update, usage_update and any variant a future adapter invents produce nothing: for a well-specified protocol, rendering every new notification kind as noise would be the bug.

Testing a host

Managoat.ACP.Testing.ScriptedAgent is the other end of the seam:

{:ok, agent} = ScriptedAgent.start_link(updates: [chunk("hello")], permission: request)
{:ok, peer} = Peer.start(owner: self(), writer: ScriptedAgent.writer(agent), ref: make_ref(), prompt: "hi", mode: :run, session_id: nil, permission_policy: %{"default" => "ask"})
:ok = ScriptedAgent.connect(agent, peer)

assert_receive {:acp, _, {:permission_ask, request_id, _tool, _options}}
:ok = Peer.answer_permission(peer, request_id, "yes")
assert_receive {:acp, _, {:done, "end_turn", nil}}

Every frame the peer writes is also reported to the test process as {:scripted_agent, :wrote, decoded}. The library's own peer tests script the agent by hand, one frame at a time, because they are about the frames; the scripted agent is for a host's tests, which are about turns.

How this relates to acpex and agent_client_protocol

Two ACP packages are on hex. This section is the evaluation Fountain's #1339 asked for, written after reading both source trees on 2026-09-02, and it ends with a recommendation. The protocol version to compare against is protocolVersion: 1, which is what agentclientprotocol.com says a client sends today; the spec bumps the number only for breaking changes, and the session methods beyond the baseline (session/resume, session/fork, session/set_model, session/set_config_option) are unstable extensions that the adapters in the wild already implement.

Side by side

Hex download counts are near-identical for both (17.5k and 17.1k, all-time) and say nothing about use; that shape is mirror traffic.

Recommendation

Publish managoat_acp as it is, the whole stack, and do not build it on either package.

• acpex cannot be the JSON-RPC layer (its connection owns the transport and blocks the caller) and cannot be the schema layer without taking Ecto into a library whose point is to be Repo-free. It also requires Elixir 1.20, which this umbrella does not run, and as a client it cannot answer a permission request or resume a session, which are the two things every adapter we run needs. There is nothing here to contribute the session layer to: it would be a rewrite of their connection, not an addition.
• agent_client_protocol is the better-shaped package — jason only, the unstable types, a real request_permission callback — but it is one day of commits by one person seven months ago, its SessionUpdate decoder crashes the connection on the first usage_update, and its transport is an IO device. Depending on it for 60 lines of encoding would trade a seam this repository controls for one nobody maintains. Contributing our session layer upstream would mean asking a dormant project to take a design (push-shaped transport, owner messages, a request id answerable from outside) that inverts its own, which is not a contribution they would take, and not one we could wait on.

What is worth revisiting: the typed schema. If agent_client_protocol shows a second release, its structs are the one thing worth adopting, as an optional decode step at the edges (Blocks, Usage, the permission request) rather than in the peer, and the unknown-variant crash would be the first patch to send. Until then, maps with the wire's own names are the cheaper contract, and every field the peer reads is one the adapters were measured sending.

Graduation to a managoat/acp repository is #1345's business and is not gated by this evaluation.

Origins

Extracted from Fountain under ADR 0037 (issue #1339), where the peer was built as gate 2 of ADR 0014 and the policy as gate 3. The issue numbers in the code are that repository's; each marks an agent behaviour that was measured live and that the code is shaped around. Apache-2.0.