| 💾 Saved. d722711 k33g 8h ago | 1 | # Reference: Agent Client Protocol surface |
| 2 | |
| 3 | > Neutral description of what `mm -acp` exposes over JSON-RPC 2.0 on stdio, through `github.com/coder/acp-go-sdk` v0.13.5. |
| 4 | |
| 5 | ## Transport |
| 6 | |
| 7 | | Aspect | Value | |
| 8 | |--------|-------| |
| 9 | | Input | stdin, one JSON-RPC message per line. | |
| 10 | | Output | stdout, JSON-RPC messages only. | |
| 11 | | Logs | stderr: banner, warnings, `[acp] …` lines, SDK logger. | |
| 12 | | Lifetime | Until the client closes stdin or the process context is cancelled. | |
| 13 | |
| 14 | ## `initialize` response |
| 15 | |
| 16 | | Field | Value | |
| 17 | |-------|-------| |
| 18 | | `protocolVersion` | `1` | |
| 19 | | `agentCapabilities` | All absent (false): no `loadSession`, no image or audio prompts, no HTTP MCP. | |
| 20 | | `agentInfo.name` | `bob` | |
| 21 | | `agentInfo.title` | `Bob (bash-first agent)` | |
| 22 | | `agentInfo.version` | `0.11.0` | |
| 23 | | `authMethods` | `[]` | |
| 24 | |
| 25 | ## Methods |
| 26 | |
| 27 | | Method | Behaviour | |
| 28 | |--------|-----------| |
| 29 | | `initialize` | Logs the client name and protocol version on stderr; returns the values above. | |
| 30 | | `authenticate` | Returns an empty response. | |
| 31 | | `session/new` | Creates a session `bob-<pid>-<n>` with the request's `cwd`, a fresh history holding the system prompt, and an empty allow-always set. `mcpServers` are counted in the log and ignored. Once the response is written, sends an `available_commands_update` notification listing the slash commands (see below). | |
| 32 | | `session/prompt` | Runs one generation on the session's history, or executes a slash command without consulting the model. Turns are serialised process-wide. | |
| 33 | | `session/cancel` | Cancels the turn in flight for that session. | |
| 34 | | `session/set_mode`, `session/set_config_option`, `session/list`, `session/resume`, `session/close`, `logout` | `method not found`. | |
| 35 | |
| 36 | ## `session/prompt` |
| 37 | |
| 38 | | Aspect | Behaviour | |
| 39 | |--------|-----------| |
| 40 | | Unknown `sessionId` | `invalid params` error carrying the `sessionId`. | |
| 41 | | Prompt content | `text` blocks concatenated; a `resource_link` becomes `\n[attached file: <path without file://>]`; other block types are ignored. Then every `@path` in the text that names an existing file or directory under the session's `cwd` (or an absolute / `~` path) appends `\n[attached file: <absolute path>]` or `\n[attached directory: …]`, once per path, and is logged as `[acp] session <id>: attached <path>`. | |
| 42 | | Slash command | When the flattened text, trimmed, is exactly `/new` or `/compact`, no generation runs; the command answers with one `agent_message_chunk` and `stopReason: end_turn`. | |
| 43 | | `/new` | The session's history is reset to the system prompt alone, the engine's last input-token count is forgotten, the chunk is `🆕 New session: N message(s) forgotten.`. The session id, `cwd` and allow-always grants are kept. Logged as `[acp] session <id>: new session, N message(s) forgotten`. | |
| 44 | | `/compact` | The history is compressed with the `context` settings, forced (the threshold is ignored, `keepLastTurns` is honoured). The chunk is `🗜️ compressed N messages → 1 summary + N kept (… tokens, …s)`, or `🗜️ nothing to compact: N message(s), no turn older than the last K` (history unchanged), or `[compact: failed, history kept: <explanation>]` (history unchanged). The token count is forgotten only when the history changed. Waits for a running turn: turns are serialised. Logged as `[acp] session <id>: /compact — <line>`. | |
| 45 | | History | The full history returned by the engine is kept, even after a failure or a cancellation; a question with no answer at all is removed. | |
| 46 | | Success | `stopReason: end_turn`. | |
| 47 | | Cancelled | `stopReason: cancelled`. | |
| 48 | | Failure | `internal error` with `error: <one-line explanation>`. | |
| 49 | | Log line | `[acp] turn done: N command(s) · N file op(s) · N skill(s)` on stderr. | |
| 50 | |
| 51 | ## `session/update` notifications sent |
| 52 | |
| 53 | | Update | When | |
| 54 | |--------|------| |
| 55 | | `available_commands_update` | Once per session, right after the `session/new` response has been written (the editor must know the session id first, or it drops the update). Lists the slash commands `session/prompt` intercepts. | |
| 56 | | `agent_message_chunk` (text) | Each streamed chunk of the model's answer, whitespace preserved; also the one-line confirmation of a slash command. | |
| 57 | | `tool_call` status `pending` | Before a tool runs; carries `title`, `kind`, `rawInput`, and `locations` with the absolute path when a file is involved. | |
| 58 | | `tool_call_update` status `in_progress` | Permission granted, tool executing. | |
| 59 | | `tool_call_update` status `completed` or `failed` | Tool finished; `content` is a `diff` for file changes, else a `text` block with the output; `rawOutput.output` always carries the output. | |
| 60 | |
| 61 | ## Available commands |
| 62 | |
| 63 | | `name` | `description` | `input` | |
| 64 | |--------|---------------|---------| |
| 65 | | `new` | `Clear the history and start a new session` | none | |
| 66 | | `compact` | `Compress the history now, keeping the last turns` | none | |
| 67 | |
| 68 | Clients display the name with a leading slash and send it back as the text of a `session/prompt`. |
| 69 | |
| 70 | ## `session/request_permission` requests sent |
| 71 | |
| 72 | Sent before `bash`, `read_file`, `write_file` and `edit_file` run; never for `read_skill`. |
| 73 | |
| 74 | | Option id | Kind | Effect | |
| 75 | |-----------|------|--------| |
| 76 | | `allow` | `allow_once` | Runs the tool. | |
| 77 | | `allow_always` | `allow_always` | Runs the tool and skips the dialog for that tool name for the rest of the session. | |
| 78 | | `reject` | `reject_once` | Does not run; the model receives `[command rejected by the user]`. | |
| 79 | |
| 80 | A transport error or a `cancelled` outcome counts as a rejection. |
| 81 | |
| 82 | ## Tool kinds |
| 83 | |
| 84 | | `mm` kind | ACP `ToolKind` | Tools | |
| 85 | |-----------|----------------|-------| |
| 86 | | `execute` | `execute` | `bash` (and any unknown kind) | |
| 87 | | `read` | `read` | `read_skill`, `read_file` | |
| 88 | | `edit` | `edit` | `write_file`, `edit_file` | |
| 89 | |
| 90 | ## Tool call identifiers |
| 91 | |
| 92 | `call_1`, `call_2`, … numbered per process and never reset. |