/acp (bro)
All mechanics live in the bro CLI. This skill is policy only.
Agent mode — bro acp (spec bro-tegz2)
Bare bro acp IS the agent — the client's "custom agent" argv is just
bro acp; no client-side plugin, no * acp naming convention.
- The CLI contract (
bro contract dump --json) is announced per
session as available_commands — /act status, /next, /drill,
the whole non-hidden surface minus commands that can never be a turn
(protocol servers, daemons, watchers). A leading /name args…
prompt runs the real bro child inside session/new's cwd and
streams stdout back as chunks; failures report in-band.
- Free-form prompts forward to the configured downstream provider and
stream its updates verbatim. Provider selection is
fleet.routing
class → chain head: --class <name> picks a lane (default
default), --provider <name> pins an entry (exclusive), and with
no routing table the first acp entry answers. The head must be an
acp-type entry — a wrong kind is a config error, never a silent
re-route.
- Cancel dies the running turn (SIGTERM→SIGKILL to a slash child, or the
downstream's own
session/cancel); a slash command's stdout never
crosses after its cancel.
The generic stdio-facade-over-a-provider surface is brouter acp
(spec bro-te3yf) — this mode is bro's own identity: its commands, its
seam, its routing.
Proxy mode — bro acp proxy -- <agent cmd> (specs bro-rs8sp.md, bro-bhyo1.md)
The client spawns bro as the agent, bro spawns the real agent, and
every JSON-RPC message crosses untouched — requests, notifications,
_-methods, _meta, and error envelopes, verbatim in both
directions. The one rewrite is the seam: the session's first
session/prompt gets ONE prepended text block carrying the same
session-start + prompt-submit context bro hooks emits, probed inside
session/new's cwd. Later prompts carry prompt-submit context only.
Command
| Command |
What it does |
bro acp [--provider <name> | --class <name>] |
Agent mode — bro IS the agent. Slash commands from the CLI contract run locally; free-form prompts forward to the routed provider. Exit 0 = client closed the wire; 1 = downstream died or config error; 2 = usage |
bro acp proxy -- <agent cmd…> |
Foreground proxy — stdin/stdout IS the upstream wire. -- is mandatory; the tail is exec'd directly (no shell), env BRO_HOOKS=0 so the downstream tree never re-runs hooks. Exit 0 = client ended the wire; 1 = downstream died first; 2 = usage |
Wiring a client
Point the client's "custom agent" at bro the same way it would name
any ACP server — agent mode needs no downstream in argv:
- agent mode:
bro acp (or bro acp --class work) — bro's slash
surface plus the routed provider behind free-form prompts.
- kilo via the cascade:
bro acp proxy -- kilo acp.
- Zed / JetBrains / Neovim: add bro as an external agent with the
same argv shape — the client's own config syntax for a stdio ACP
server.
Run the proxy anywhere — the seam probes session/new's cwd, not
the proxy's own, so a session opened in another repo gets THAT repo's
context or nothing (fail-open, same as the hook).
What crosses the seam — and what doesn't
- Session context collects in-process (the hook collectors as a
library — no
bro hooks subprocess), once per session, on the first
prompt only. A session/cancel landing while the seam collects
answers the held prompt stopReason:'cancelled' — the wire never
shows a prompt after its cancel.
tool_call updates run the post-tool hook in-process too (spec
bro-u2eps): the session-marker arming and post-tool guard defs
bro hooks runs per tool call — no run.sh subprocess per call.
Guard say lines and gate hints buffer onto the next crossed
session/prompt as prepended text — never a fabricated wire
message.
- The turn end is the stop gate: a
session/prompt response held by
an armed blocking contribution gets exactly ONE follow-up prompt
carrying the gate's message, and the gate turn's own end passes
unconditionally — gates, not loops.
BRO_HOOKS=0 makes the proxy a pure transport — no arming, no
guards, no gate, no permission policy (the spawned agent already
runs with it, which is why the child env pins it).
session/request_permission runs the same policy the
PermissionRequest hook does (spec bro-9qopj): session-cap refusals
and connector preTool blocks deny (reject_once, or cancelled
when no reject is offered), bro/bd self-tool commands approve
(allow_once), everything else forwards to the client verbatim and
the client's own answer relays back. Guard warn verdicts ride the
next prompt as advisory text. Every decision journals —
kind:'permission' rows with decidedBy:'proxy'|'client' in the
session's events archive (<git-common>/bro/proxy/ unbadged).
Telemetry
acp.proxy.session / acp.proxy.turn otel spans wrap each session
and prompt; session/update feeds agentTurnPlane (by: 'acp proxy').
- An unbadged run (no
BRO_AGENT_ID — a human driving the proxy)
still journals: <git-common>/bro/proxy/acp-<session>.events.jsonl.
1---23name: acp4description: "Use when an ACP client (Zed, JetBrains, Neovim, or any `* acp` agent binary) should reach bro's surface or sit behind bro's hook seam — bare `bro acp` is bro-as-agent (CLI contract as slash commands, free-form prompts routed to the configured provider); `bro acp proxy -- <agent cmd>` is the cascading edge: verbatim forwarding plus session context on the first prompt. Thin wrapper over the bro CLI — mechanics live in the CLI."5metadata:6 source: https://skillmd.com/skills/theplenkov/acp7---89# /acp (bro)1011**All mechanics live in the `bro` CLI.** This skill is policy only.1213## Agent mode — `bro acp` (spec bro-tegz2)1415Bare `bro acp` IS the agent — the client's "custom agent" argv is just16`bro acp`; no client-side plugin, no `* acp` naming convention.1718- The CLI contract (`bro contract dump --json`) is announced per19 session as `available_commands` — `/act status`, `/next`, `/drill`,20 the whole non-hidden surface minus commands that can never be a turn21 (protocol servers, daemons, watchers). A leading `/name args…`22 prompt runs the real `bro` child inside `session/new`'s `cwd` and23 streams stdout back as chunks; failures report in-band.24- Free-form prompts forward to the configured downstream provider and25 stream its updates verbatim. Provider selection is `fleet.routing`26 class → chain head: `--class <name>` picks a lane (default27 `default`), `--provider <name>` pins an entry (exclusive), and with28 no routing table the first `acp` entry answers. The head must be an29 `acp`-type entry — a wrong kind is a config error, never a silent30 re-route.31- Cancel dies the running turn (SIGTERM→SIGKILL to a slash child, or the32 downstream's own `session/cancel`); a slash command's stdout never33 crosses after its cancel.3435The generic stdio-facade-over-a-provider surface is `brouter acp`36(spec bro-te3yf) — this mode is bro's own identity: its commands, its37seam, its routing.3839## Proxy mode — `bro acp proxy -- <agent cmd>` (specs bro-rs8sp.md, bro-bhyo1.md)4041The client spawns bro as the agent, bro spawns the real agent, and42every JSON-RPC message crosses untouched — requests, notifications,43`_`-methods, `_meta`, and error envelopes, verbatim in both44directions. The one rewrite is the seam: the session's first45`session/prompt` gets ONE prepended text block carrying the same46session-start + prompt-submit context `bro hooks` emits, probed inside47`session/new`'s cwd. Later prompts carry prompt-submit context only.4849## Command5051| Command | What it does |52| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |53| `bro acp [--provider <name> \| --class <name>]` | Agent mode — bro IS the agent. Slash commands from the CLI contract run locally; free-form prompts forward to the routed provider. Exit 0 = client closed the wire; 1 = downstream died or config error; 2 = usage |54| `bro acp proxy -- <agent cmd…>` | Foreground proxy — stdin/stdout IS the upstream wire. `--` is mandatory; the tail is exec'd directly (no shell), env `BRO_HOOKS=0` so the downstream tree never re-runs hooks. Exit 0 = client ended the wire; 1 = downstream died first; 2 = usage |5556## Wiring a client5758Point the client's "custom agent" at bro the same way it would name59any ACP server — agent mode needs no downstream in argv:6061- **agent mode**: `bro acp` (or `bro acp --class work`) — bro's slash62 surface plus the routed provider behind free-form prompts.63- **kilo via the cascade**: `bro acp proxy -- kilo acp`.64- **Zed / JetBrains / Neovim**: add bro as an external agent with the65 same argv shape — the client's own config syntax for a stdio ACP66 server.6768Run the proxy anywhere — the seam probes `session/new`'s `cwd`, not69the proxy's own, so a session opened in another repo gets THAT repo's70context or nothing (fail-open, same as the hook).7172## What crosses the seam — and what doesn't7374- Session context collects in-process (the hook collectors as a75 library — no `bro hooks` subprocess), once per session, on the first76 prompt only. A `session/cancel` landing while the seam collects77 answers the held prompt `stopReason:'cancelled'` — the wire never78 shows a prompt after its cancel.79- `tool_call` updates run the post-tool hook in-process too (spec80 bro-u2eps): the session-marker arming and post-tool guard defs81 `bro hooks` runs per tool call — no run.sh subprocess per call.82 Guard `say` lines and gate hints buffer onto the next crossed83 `session/prompt` as prepended text — never a fabricated wire84 message.85- The turn end is the stop gate: a `session/prompt` response held by86 an armed blocking contribution gets exactly ONE follow-up prompt87 carrying the gate's message, and the gate turn's own end passes88 unconditionally — gates, not loops.89- `BRO_HOOKS=0` makes the proxy a pure transport — no arming, no90 guards, no gate, no permission policy (the spawned agent already91 runs with it, which is why the child env pins it).92- `session/request_permission` runs the same policy the93 PermissionRequest hook does (spec bro-9qopj): session-cap refusals94 and connector `preTool` blocks deny (reject_once, or `cancelled`95 when no reject is offered), bro/bd self-tool commands approve96 (allow_once), everything else forwards to the client verbatim and97 the client's own answer relays back. Guard `warn` verdicts ride the98 next prompt as advisory text. Every decision journals —99 `kind:'permission'` rows with `decidedBy:'proxy'|'client'` in the100 session's events archive (`<git-common>/bro/proxy/` unbadged).101102## Telemetry103104- `acp.proxy.session` / `acp.proxy.turn` otel spans wrap each session105 and prompt; `session/update` feeds `agentTurnPlane` (`by: 'acp proxy'`).106- An unbadged run (no `BRO_AGENT_ID` — a human driving the proxy)107 still journals: `<git-common>/bro/proxy/acp-<session>.events.jsonl`.