# Reference: Agent Client Protocol surface

> Neutral description of what `mm -acp` exposes over JSON-RPC 2.0 on stdio, through `github.com/coder/acp-go-sdk` v0.13.5.

## Transport

| Aspect | Value |
|--------|-------|
| Input | stdin, one JSON-RPC message per line. |
| Output | stdout, JSON-RPC messages only. |
| Logs | stderr: banner, warnings, `[acp] …` lines, SDK logger. |
| Lifetime | Until the client closes stdin or the process context is cancelled. |

## `initialize` response

| Field | Value |
|-------|-------|
| `protocolVersion` | `1` |
| `agentCapabilities` | All absent (false): no `loadSession`, no image or audio prompts, no HTTP MCP. |
| `agentInfo.name` | `bob` |
| `agentInfo.title` | `Bob (bash-first agent)` |
| `agentInfo.version` | `0.11.0` |
| `authMethods` | `[]` |

## Methods

| Method | Behaviour |
|--------|-----------|
| `initialize` | Logs the client name and protocol version on stderr; returns the values above. |
| `authenticate` | Returns an empty response. |
| `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). |
| `session/prompt` | Runs one generation on the session's history, or executes a slash command without consulting the model. Turns are serialised process-wide. |
| `session/cancel` | Cancels the turn in flight for that session. |
| `session/set_mode`, `session/set_config_option`, `session/list`, `session/resume`, `session/close`, `logout` | `method not found`. |

## `session/prompt`

| Aspect | Behaviour |
|--------|-----------|
| Unknown `sessionId` | `invalid params` error carrying the `sessionId`. |
| 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>`. |
| 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`. |
| `/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`. |
| `/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>`. |
| 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. |
| Success | `stopReason: end_turn`. |
| Cancelled | `stopReason: cancelled`. |
| Failure | `internal error` with `error: <one-line explanation>`. |
| Log line | `[acp] turn done: N command(s) · N file op(s) · N skill(s)` on stderr. |

## `session/update` notifications sent

| Update | When |
|--------|------|
| `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. |
| `agent_message_chunk` (text) | Each streamed chunk of the model's answer, whitespace preserved; also the one-line confirmation of a slash command. |
| `tool_call` status `pending` | Before a tool runs; carries `title`, `kind`, `rawInput`, and `locations` with the absolute path when a file is involved. |
| `tool_call_update` status `in_progress` | Permission granted, tool executing. |
| `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. |

## Available commands

| `name` | `description` | `input` |
|--------|---------------|---------|
| `new` | `Clear the history and start a new session` | none |
| `compact` | `Compress the history now, keeping the last turns` | none |

Clients display the name with a leading slash and send it back as the text of a `session/prompt`.

## `session/request_permission` requests sent

Sent before `bash`, `read_file`, `write_file` and `edit_file` run; never for `read_skill`.

| Option id | Kind | Effect |
|-----------|------|--------|
| `allow` | `allow_once` | Runs the tool. |
| `allow_always` | `allow_always` | Runs the tool and skips the dialog for that tool name for the rest of the session. |
| `reject` | `reject_once` | Does not run; the model receives `[command rejected by the user]`. |

A transport error or a `cancelled` outcome counts as a rejection.

## Tool kinds

| `mm` kind | ACP `ToolKind` | Tools |
|-----------|----------------|-------|
| `execute` | `execute` | `bash` (and any unknown kind) |
| `read` | `read` | `read_skill`, `read_file` |
| `edit` | `edit` | `write_file`, `edit_file` |

## Tool call identifiers

`call_1`, `call_2`, … numbered per process and never reset.