---
title: RPC protocol
description: Every RPC command, event, type, and error contract.
---

# RPC protocol

## Commands

### Stored summaries and workflow history

These read-only commands do not start a model turn. Stored summaries remain available when `sessionSummary.enabled` is false.

| Command | Response `data` | TypeScript `RpcClient` method |
| --- | --- | --- |
| `{"type":"get_session_summary"}` | `{ summary: SessionSummaryEntry \| null }`, including `summary` and `summarizedThroughId` | `getSessionSummary()` |
| `{"type":"list_sessions"}` | `{ sessions: RpcSessionInfo[] }` for the current project/session directory, including `summary` and `summarizedThroughId`; `created` and `modified` are ISO strings | `listSessions()` |
| `{"type":"list_workflow_runs"}` | `{ runs: WorkflowRunSummary[] }`, including live runs and current-project resumable and completed history | `listWorkflowRuns(status?)` |
| `{"type":"get_workflow_run_summary","runId":"<uuid>"}` | `WorkflowRunDetail` for that run | `getWorkflowRunSummary(runId)` |

Workflow records include `runId`, `name`, `status`, `label`, `identity`, `summary`, and `summarizedThrough` (Unix milliseconds). Optional summary fields are absent when no summary has been saved. `list_workflow_runs` accepts an optional `status` filter. Run detail requests accept full UUIDs for earlier sessions; a missing run returns the normal error response. Summaries describe progress through their marker and may be stale.

Stored history follows the SDK's run-detail access rules: top-level runs with a recorded session owner launched from the current project directory. Runs from other project directories are not included.

### Prompting

#### prompt

Send a user prompt to the agent. The command response is emitted after the prompt is accepted, queued, or handled. Events continue streaming asynchronously after acceptance.

```json
{"id": "req-1", "type": "prompt", "message": "Hello, world!"}
```

With images:
```json
{"type": "prompt", "message": "What's in this image?", "images": [{"type": "image", "data": "base64-encoded-data", "mimeType": "image/png"}]}
```

**During streaming**: If the agent is already streaming, you must specify `streamingBehavior` to queue the message:

```json
{"type": "prompt", "message": "New instruction", "streamingBehavior": "steer"}
```

- `"steer"`: Queue the message while the agent is running. It is delivered after the current assistant turn finishes executing its tool calls, before the next LLM call.
- `"followUp"`: Wait until the agent finishes. Message is delivered only when agent stops.

If the agent is streaming and no `streamingBehavior` is specified, the command returns an error.

**Extension commands**: If the message is an extension command (e.g., `/mycommand`), it executes immediately even during streaming. Extension commands manage their own LLM interaction via `pi.sendMessage()`.

**Input expansion**: Skill commands (`/skill:name`) and prompt templates (`/template`) are expanded before sending/queueing.

Response:
```json
{"id": "req-1", "type": "response", "command": "prompt", "success": true, "data": {"disposition": "started"}}
```

`data.disposition` is `"handled"` if an extension command or input handler consumed the prompt, `"queued"` if Atomic queued it during a run or held it because the message queue was paused before its run began, or `"started"` if Atomic started a run for it. This describes the submitted prompt, not independent work started by an extension or a guarantee of completion. If it is `"handled"`, no run started for this prompt, so don't wait for `agent_end` or `agent_settled`.

`success: true` means the prompt was accepted, queued, or handled immediately. `success: false` means the prompt was rejected before acceptance. Failures after acceptance are reported through the normal event and message stream, not as a second `response` for the same request id.

The `images` field is optional. Each image uses `ImageContent` format: `{"type": "image", "data": "base64-encoded-data", "mimeType": "image/png"}`.

#### steer

Queue a steering message while the agent is running. It is delivered after the current assistant turn finishes executing its tool calls, before the next LLM call. If no run is active when it arrives and the session already has messages, Atomic starts a turn to deliver it, so a `prompt` sent while that turn runs needs `streamingBehavior`. On a session with no messages yet, or after a run was stopped with `abort`, it stays queued until the next `prompt`. Skill commands and prompt templates are expanded. Extension commands are not allowed (use `prompt` instead).

```json
{"type": "steer", "message": "Stop and do this instead"}
```

With images:
```json
{"type": "steer", "message": "Look at this instead", "images": [{"type": "image", "data": "base64-encoded-data", "mimeType": "image/png"}]}
```

The `images` field is optional. Each image uses `ImageContent` format (same as `prompt`).

Response:
```json
{"type": "response", "command": "steer", "success": true, "data": {"disposition": "queued"}}
```

`data.disposition` is `"handled"` if an input handler consumed this steer, or `"queued"` if Atomic queued it (including after a handler transformed it). It does not guarantee this message remains queued.

See [set_steering_mode](#set_steering_mode) for controlling how steering messages are processed.

#### follow_up

Queue a follow-up message to be processed after the agent finishes. Delivered only when agent has no more tool calls or steering messages. If no run is active when it arrives and the session already has messages, Atomic starts a turn to deliver it, so a `prompt` sent while that turn runs needs `streamingBehavior`. On a session with no messages yet, or after a run was stopped with `abort`, it stays queued until the next `prompt`. Skill commands and prompt templates are expanded. Extension commands are not allowed (use `prompt` instead).

```json
{"type": "follow_up", "message": "After you're done, also do this"}
```

With images:
```json
{"type": "follow_up", "message": "Also check this image", "images": [{"type": "image", "data": "base64-encoded-data", "mimeType": "image/png"}]}
```

The `images` field is optional. Each image uses `ImageContent` format (same as `prompt`).

Response:
```json
{"type": "response", "command": "follow_up", "success": true, "data": {"disposition": "queued"}}
```

`data.disposition` has the same `"handled"` or `"queued"` meaning as for `steer`, applied to this follow-up.

See [set_follow_up_mode](#set_follow_up_mode) for controlling how follow-up messages are processed.

#### abort

Abort the current operation and wait for the session to become idle before responding.

```json
{"type": "abort"}
```

Response:
```json
{"type": "response", "command": "abort", "success": true}
```

#### clear_queue

Remove queued steering and follow-up messages and return their text.

```json
{"type": "clear_queue"}
```

Response:
```json
{
  "type": "response",
  "command": "clear_queue",
  "success": true,
  "data": {
    "steering": ["Change direction"],
    "followUp": ["Summarize when finished"]
  }
}
```

To implement interactive Esc behavior, send `clear_queue` before `abort`, then restore the returned text in the client editor. `abort` continues queued messages when they remain in the session.

#### new_session

Start a fresh session. Can be cancelled by a `session_before_switch` extension event handler.

```json
{"type": "new_session"}
```

With optional parent session tracking:
```json
{"type": "new_session", "parentSession": "parent-session-id"}
```

Response:
```json
{"type": "response", "command": "new_session", "success": true, "data": {"cancelled": false}}
```

If an extension cancelled:
```json
{"type": "response", "command": "new_session", "success": true, "data": {"cancelled": true}}
```

#### delete_session

Delete a stored session and its entries from the active session store (SQLite or JSONL). Use `list_sessions` to find IDs.

```json
{"id": "req-2", "type": "delete_session", "sessionId": "019fdf86-cf98-7327-8a73-21365028f6ae"}
```

`sessionId` names the session to delete. `id` is the request ID that every command carries and is echoed in the response. When `sessionId` is omitted, `id` is also used as the session ID, so `{"type": "delete_session", "id": "019fdf86-cf98-7327-8a73-21365028f6ae"}` deletes that session and the response echoes the same `id`. When both are present, `sessionId` wins. Omitting both returns an error response (`delete_session requires sessionId`) and changes nothing.

Response:
```json
{"id": "req-2", "type": "response", "command": "delete_session", "success": true}
```

The session currently open in this process cannot be deleted. The command returns an error response and the session stays intact; start or switch to another session first. Deleting an ID that is not in the store succeeds without changing anything.

```json
{"id": "req-2", "type": "response", "command": "delete_session", "success": false, "error": "Cannot delete the session that is currently open: 019fdf86-cf98-7327-8a73-21365028f6ae"}
```

TypeScript `RpcClient` method: `deleteSession(sessionId)`, which rejects on an error response.

### State

#### get_state

Get current session state.

```json
{"type": "get_state"}
```

Response:
```json
{
  "type": "response",
  "command": "get_state",
  "success": true,
  "data": {
    "model": {...},
    "thinkingLevel": "medium",
    "isStreaming": false,
    "isCompacting": false,
    "steeringMode": "all",
    "followUpMode": "one-at-a-time",
    "sessionLocation": "/path/to/session.jsonl",
    "sessionId": "abc123",
    "sessionName": "my-feature-work",
    "autoCompactionEnabled": true,
    "messageCount": 5,
    "pendingMessageCount": 0
  }
}
```

The `model` field is a full [Model](#model) object or `null`. Its `contextWindow` is the model's token budget. The `sessionName` field is the display name set via `set_session_name`, or omitted if not set.

#### get_messages

Get all messages in the conversation.

```json
{"type": "get_messages"}
```

Response:
```json
{
  "type": "response",
  "command": "get_messages",
  "success": true,
  "data": {"messages": [...]}
}
```

Messages are `AgentMessage` objects (see [Types](#types)).

### Model

#### set_model

Switch to a specific model. Omit `persist` (or set it false) to change only the current session. Set `"persist": true` to also save `defaultProvider`, `defaultModel`, and the effective thinking level in settings, matching an interactive `/model` selection.

```json
{"type": "set_model", "provider": "anthropic", "modelId": "claude-sonnet-4-20250514"}
```

Persist as the startup default:
```json
{"type": "set_model", "provider": "anthropic", "modelId": "claude-sonnet-4-20250514", "persist": true}
```

Response contains the full [Model](/rpc/protocol#model) object:
```json
{
  "type": "response",
  "command": "set_model",
  "success": true,
  "data": {...}
}
```

#### cycle_model

Cycle to the next available model. Returns `null` when fewer than two authenticated models are available in the active scope or catalog. When an unsupported saved default is blocking prompts, a successful cycle that returns a different model clears that condition; a `null` or unchanged result does not. Set `"persist": true` to also write the cycled model as the startup default.

```json
{"type": "cycle_model"}
```

Response:
```json
{
  "type": "response",
  "command": "cycle_model",
  "success": true,
  "data": {
    "model": {...},
    "thinkingLevel": "medium",
    "isScoped": false
  }
}
```

The `model` field is a full [Model](#model) object.

#### get_available_models

List all configured models.

```json
{"type": "get_available_models"}
```

Response contains an array of full [Model](#model) objects:
```json
{
  "type": "response",
  "command": "get_available_models",
  "success": true,
  "data": {
    "models": [...]
  }
}
```

`data` also carries `scopedModels`, `oauthProviders`, `customAuthProviders`, and `providerAuthStatuses`. `customAuthProviders` lists extension-registered providers (`{ id, name }`) that accept an API key through `login_provider`. `providerAuthStatuses` lists the authentication status of extension-registered providers (`{ provider, status }`, where `status` is `{ configured, source?, label? }`) when it does not come from a credential stored in `auth.json`, for example an environment variable. `refresh_models` responses carry the same fields.

The subprocess protocol returns full `Model` objects. The exported TypeScript `RpcClient.getAvailableModels()` keeps its smaller backward-compatible `ModelInfo` shape (`provider`, `id`, `contextWindow`, `reasoning`) and adds optional `compat`. When present, `compat` exposes constrained-sampling capability claims including `supportsStrictTools`, `supportsStrictMode`, canonical `supportsOpenAIGrammarTools`, and Atomic's synchronized `supportsGrammarTools` alias. Treat absence as unknown/unsupported; do not infer enforcement from the provider name.

```typescript
const models = await client.getAvailableModels();
const capabilities = models[0]?.compat;
if (capabilities?.supportsStrictTools) {
  // The selected model advertises Anthropic/Bedrock strict-tool support.
}
```

#### logout_provider

Remove a provider's stored credential in the authoritative agent process, refresh its available-model catalog, and return the remaining authentication status and new catalog. Environment variables and `models.json` authentication are reported but are not modified.

```json
{"type": "logout_provider", "provider": "github-copilot"}
```

Response:

```json
{
  "type": "response",
  "command": "logout_provider",
  "success": true,
  "data": {
    "provider": "github-copilot",
    "authStatus": {"configured": false},
    "models": [],
    "scopedModels": []
  }
}
```

`models` preserves the refreshed catalog order. `scopedModels` is optional. If authentication remains through an environment variable, `authStatus.source` is `"environment"` and `authStatus.label` names the variable.

### Thinking

#### set_thinking_level

Set the reasoning/thinking level for models that support it. Omit `persist` (or set it false) to change only the current session. Set `"persist": true` to also save `defaultThinkingLevel` and, when a model is active, its per-model override. Interactive `/thinking` choices request persistence automatically.

```json
{"type": "set_thinking_level", "level": "high"}
```

Persist as the startup default:
```json
{"type": "set_thinking_level", "level": "high", "persist": true}
```

Levels: `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"`.

`xhigh` and `max` are available only when the active model's capability mapping supports them; unsupported levels are clamped by the session model controls.

Response may omit `data` for compatibility with older clients:
```json
{"type": "response", "command": "set_thinking_level", "success": true}
```

Current engines include the effective level after capability clamping and, when a model is active, the provider/model the engine persisted against:
```json
{"type": "response", "command": "set_thinking_level", "success": true, "data": {"level": "high", "provider": "anthropic", "modelId": "claude-sonnet-4-20250514"}}
```

Use the acknowledgement's provider/model when recording a persisted thinking override, not whichever model is active when your callback runs. Keep newer `thinking_level_changed` state if an older acknowledgement arrives later. `RpcClient.setThinkingLevel(level)` remains a one-argument `Promise<void>` method.

#### cycle_thinking_level

Cycle through available thinking levels. Returns `null` data if model doesn't support thinking.

```json
{"type": "cycle_thinking_level"}
```

Response:
```json
{
  "type": "response",
  "command": "cycle_thinking_level",
  "success": true,
  "data": {"level": "high"}
}
```

#### get_available_thinking_levels

Return the thinking levels supported by the current model, in cycle order.

```json
{"type": "get_available_thinking_levels"}
```

Response:
```json
{
  "type": "response",
  "command": "get_available_thinking_levels",
  "success": true,
  "data": {"levels": ["off", "low", "medium", "high"]}
}
```

### Queue Modes

#### set_steering_mode

Control how steering messages (from `steer`) are delivered.

```json
{"type": "set_steering_mode", "mode": "one-at-a-time"}
```

Modes:
- `"all"`: Deliver all steering messages after the current assistant turn finishes executing its tool calls
- `"one-at-a-time"`: Deliver one steering message per completed assistant turn (default)

Response:
```json
{"type": "response", "command": "set_steering_mode", "success": true}
```

#### set_follow_up_mode

Control how follow-up messages (from `follow_up`) are delivered.

```json
{"type": "set_follow_up_mode", "mode": "one-at-a-time"}
```

Modes:
- `"all"`: Deliver all follow-up messages when agent finishes
- `"one-at-a-time"`: Deliver one follow-up message per agent completion (default)

Response:
```json
{"type": "response", "command": "set_follow_up_mode", "success": true}
```

### Compaction

#### compact

Run verbatim line compaction with the session model. It preserves exactly the newest `preserve_recent` context-visible messages, default two, without aligning to user turns. Zero compacts the whole active transcript and returns `firstKeptEntryId: null`. The resulting durable entry uses `details.strategy: "verbatim-lines"`; see [Compaction](/compaction) for behavior and settings.

```json
{"type": "compact"}
```

Response:
```json
{
  "type": "response",
  "command": "compact",
  "success": true,
  "data": {
    "compactedText": "[User]: fix the test\n(filtered 42 lines)\n[Assistant]: Fixed.",
    "firstKeptEntryId": "m7",
    "tokensBefore": 150000,
    "promptVersion": 3,
    "parameters": {
      "compression_ratio": 0.5,
      "preserve_recent": 2,
      "query": "fix the test"
    },
    "rung": "planned",
    "stats": {
      "linesBefore": 812,
      "linesDeleted": 417,
      "linesKept": 395,
      "rangeCount": 63,
      "tokensBefore": 150000,
      "tokensAfter": 72000,
      "percentReduction": 52
    },
    "backupPath": "/path/to/session.jsonl.2026-06-06T00-00-00-000Z.compact.bak"
  }
}
```

`firstKeptEntryId` is a string when at least one ordinary message remains outside compaction and `null` when none does. RPC clients must accept both values.

#### set_auto_compaction

Enable or disable automatic compaction when context is nearly full.

```json
{"type": "set_auto_compaction", "enabled": true}
```

Response:
```json
{"type": "response", "command": "set_auto_compaction", "success": true}
```

### Retry

#### set_auto_retry

Enable or disable automatic retry on transient errors (overloaded, rate limit, 5xx).

```json
{"type": "set_auto_retry", "enabled": true}
```

Response:
```json
{"type": "response", "command": "set_auto_retry", "success": true}
```

#### abort_retry

Abort an in-progress retry (cancel the delay and stop retrying).

```json
{"type": "abort_retry"}
```

Response:
```json
{"type": "response", "command": "abort_retry", "success": true}
```

### Bash

#### bash

Execute a shell command and add output to conversation context.

```json
{"type": "bash", "command": "ls -la"}
```

Response:
```json
{
  "type": "response",
  "command": "bash",
  "success": true,
  "data": {
    "output": "total 48\ndrwxr-xr-x ...",
    "exitCode": 0,
    "cancelled": false,
    "truncated": false
  }
}
```

While the command runs, Atomic emits ordered deltas correlated by the command `id`:

```json
{"type":"bash_execution_update","id":"req-1","channel":"stdout","delta":"building...\n"}
{"type":"bash_execution_update","id":"req-1","channel":"stderr","delta":"warning\n"}
```

`channel` is exactly `"stdout"` or `"stderr"`. Deltas preserve the observed order for each request. Concurrent bash requests may interleave globally but never share IDs.

Request ownership survives `new_session`, `switch_session`, `import_session`, fork, and clone while the command runs. Later deltas keep the original ID and do not contaminate the replacement session. Exactly one ordinary `response` is the terminal record for completion, cancellation, or error.

If output was truncated, includes `fullOutputPath`. Persisted bash output lives in the owner- and session-scoped temp tree (`<tmpdir>/atomic-<uid>/<session-id>/`), not at the temp root — see [Tools](/tools#persisted-tool-output) for the layout, permissions, size cap, and retention:
```json
{
  "type": "response",
  "command": "bash",
  "success": true,
  "data": {
    "output": "truncated output...",
    "exitCode": 0,
    "cancelled": false,
    "truncated": true,
    "fullOutputPath": "/tmp/atomic-501/019fdf86-cf98-7327-8a73-21365028f6ae/atomic-bash-abc123.log"
  }
}
```

`fullOutputPath` is `null` when the temp directory could not be created or the write was refused; treat it as absent rather than assuming a path exists.

**How bash results reach the LLM:**

The `bash` command returns a `BashResult` and saves output in the session where the request started, even if another session becomes active before completion. The saved `BashExecutionMessage` emits no event of its own.

The initiating session's next prompt includes the output as user context in this format:

````
Ran `ls -la`
```
total 48
drwxr-xr-x ...
```
````

This means:
1. Bash output is included in the LLM context on the **next prompt**, not immediately
2. Multiple bash commands can be executed before a prompt; all outputs will be included
3. No event is emitted for the `BashExecutionMessage` itself

#### abort_bash

Abort running bash commands. Omit `requestId` to retain the legacy behavior of aborting every active RPC-owned bash request, including requests that began before a session replacement, or provide the target bash command's `id` to cancel only that request. Targeted and legacy cancellation remain isolated across concurrent IDs. Closing RPC cancels and drains remaining owned requests before shutdown.

```json
{"id":"cancel-1","type":"abort_bash","requestId":"req-1"}
```

Response:
```json
{"id":"cancel-1","type":"response","command":"abort_bash","success":true}
```

### Session

#### get_session_stats

Get token usage, cost statistics, and current context window usage.

```json
{"type": "get_session_stats"}
```

Response:
```json
{
  "type": "response",
  "command": "get_session_stats",
  "success": true,
  "data": {
    "sessionFile": "/path/to/session.jsonl",
    "sessionId": "abc123",
    "userMessages": 5,
    "assistantMessages": 5,
    "toolCalls": 12,
    "toolResults": 12,
    "totalMessages": 22,
    "tokens": {
      "input": 50000,
      "output": 10000,
      "cacheRead": 40000,
      "cacheWrite": 5000,
      "total": 105000
    },
    "cost": 0.45,
    "contextUsage": {
      "tokens": 60000,
      "contextWindow": 200000,
      "percent": 30
    },
    "latestAssistantUsage": {
      "input": 200,
      "output": 800,
      "cacheRead": 59000,
      "cacheWrite": 0,
      "totalTokens": 60000,
      "cost": {"input": 0.0006, "output": 0.012, "cacheRead": 0.0177, "cacheWrite": 0, "total": 0.0303}
    }
  }
}
```

`tokens` contains assistant usage totals for the current session state. `contextUsage` contains the actual current context-window estimate used for compaction and footer display.

`contextUsage` is omitted when no model or context window is available. `contextUsage.tokens` and `contextUsage.percent` are `null` immediately after compaction until a fresh post-compaction assistant response provides valid usage data.

`latestAssistantUsage` is the usage reported by the newest assistant message, including an aborted or failed one; the interactive footer reads its cache-hit rate from it. It is omitted until the session has an assistant message.

#### get_tools

Explain which tools are active, which are not and why, and which selected tool names nothing registered.

```json
{"type": "get_tools"}
```

Response, shortened to three tools, for `"defaultTools": ["+codemode", "+tool-search"]`:
```json
{
  "type": "response",
  "command": "get_tools",
  "success": true,
  "data": {
    "selection": {
      "source": "default-tools-setting",
      "description": "the defaultTools setting",
      "names": ["read", "bash", "kill", "edit", "write", "find", "search", "ask_user_question", "todo", "codemode", "tool-search"],
      "modifiers": []
    },
    "tools": [
      {
        "name": "read",
        "active": true,
        "exposure": "direct",
        "source": "built-in",
        "sourcePath": "<builtin:read>",
        "summary": "Read files, directories, archives, SQLite databases, internal resources, images, documents, and URLs through one path string."
      },
      {
        "name": "codemode",
        "active": true,
        "exposure": "model-only",
        "source": "built-in extension \"codemode\"",
        "sourcePath": "builtin:codemode",
        "summary": "Run JavaScript that composes tool calls in a fresh QuickJS worker sandbox."
      },
      {
        "name": "tool_search",
        "active": false,
        "exposure": "model-only",
        "source": "built-in extension \"tool-search\"",
        "sourcePath": "builtin:tool-search",
        "summary": "Search deferred tool metadata with BM25 and load matching tools for the next model call. Some tools may not have been provided upfront; use tool_search to discover currently registered tools.",
        "inactiveReason": "opt-in; add \"+tool_search\" to defaultTools or --tools to enable it"
      }
    ],
    "missing": [
      {
        "name": "tool-search",
        "reason": "selected by the defaultTools setting, but no built-in, extension, SDK custom tool, or MCP server has registered a tool named \"tool-search\"; did you mean \"tool_search\"?"
      }
    ],
    "excluded": []
  }
}
```

`selection.source` is one of `default-tools-setting`, `built-in-defaults`, `tools-allowlist`, `explicit-selection`, `no-built-in-tools`, or `no-tools`; `modifiers` lists `+name`/`-name` entries from `--tools`. `tools` lists active tools first. `excluded` lists selected names that `--exclude-tools` or a mode without user input removed. The command waits until extensions finish loading, so the report includes their tools. `RpcClient.getTools()` returns the same `data`.

#### export_html

Export session to an HTML file.

```json
{"type": "export_html"}
```

With custom path:
```json
{"type": "export_html", "outputPath": "/tmp/session.html"}
```

Response:
```json
{
  "type": "response",
  "command": "export_html",
  "success": true,
  "data": {"path": "/tmp/session.html"}
}
```

#### switch_session

Load a different session by its exact ID. Can be cancelled by a `session_before_switch` extension event handler. `sessionLocation` in `get_state` is optional display text, not a switch target.

```json
{"type": "switch_session", "sessionId": "abc123"}
```

When choosing a session from another project's JSONL store, pass `sessionDirectory` to bind the ID lookup to that directory. IDs may repeat in different project stores; an explicitly selected directory never falls back to another store. `cwdOverride` changes the resumed working directory, not the store used for lookup.

```json
{"type": "switch_session", "sessionId": "abc123", "sessionDirectory": "/path/to/project-sessions"}
```

Response:
```json
{"type": "response", "command": "switch_session", "success": true, "data": {"cancelled": false}}
```

If an extension cancelled the switch:
```json
{"type": "response", "command": "switch_session", "success": true, "data": {"cancelled": true}}
```

#### start_pending_recovery

Recover work an earlier process left unfinished in the current session. Send it after you have shown the transcript, at startup or after `switch_session`.

Loading or switching a session never recovers anything by itself. Until a client sends this command, interrupted deliveries stay pending in the session. The command runs once per loaded session; repeating it returns the same report. It does not block other commands, so prompts and `abort` keep working while it runs.

```json
{"type": "start_pending_recovery", "reason": "resume"}
```

`reason` is optional and accepts `"startup"`, `"resume"`, or `"workflow_stage_resume"`.

Extensions first restore their background work. Interrupted deliveries that are still wanted are then replayed in a turn, which streams like any other turn. Notices and undelivered background task results are appended without starting a turn.

The response arrives when recovery has finished:
```json
{"type": "response", "command": "start_pending_recovery", "success": true, "data": {"replayed": 1, "dropped": 1, "completions": 0, "notices": ["Worker reviewer is gone."]}}
```

#### fork

Create a new fork from a previous user message on the active branch. Can be cancelled by a `session_before_fork` extension event handler. Returns the text of the message being forked from.

```json
{"type": "fork", "entryId": "abc123"}
```

Response:
```json
{
  "type": "response",
  "command": "fork",
  "success": true,
  "data": {"text": "The original prompt text...", "cancelled": false}
}
```

If an extension cancelled the fork:
```json
{
  "type": "response",
  "command": "fork",
  "success": true,
  "data": {"text": "The original prompt text...", "cancelled": true}
}
```

#### clone

Duplicate the current active branch into a new session at the current position. Can be cancelled by a `session_before_fork` extension event handler.

```json
{"type": "clone"}
```

Response:
```json
{
  "type": "response",
  "command": "clone",
  "success": true,
  "data": {"cancelled": false}
}
```

If an extension cancelled the clone:
```json
{
  "type": "response",
  "command": "clone",
  "success": true,
  "data": {"cancelled": true}
}
```

#### get_fork_messages

Get user messages available for forking.

```json
{"type": "get_fork_messages"}
```

Response:
```json
{
  "type": "response",
  "command": "get_fork_messages",
  "success": true,
  "data": {
    "messages": [
      {"entryId": "abc123", "text": "First prompt..."},
      {"entryId": "def456", "text": "Second prompt..."}
    ]
  }
}
```

#### get_entries

Get all session entries in append order, excluding the session header. Unlike `get_messages`, this includes pre-compaction history and abandoned branches.

Entry IDs are stable in the append-only tree. Use the last entry ID you have seen as `since` to get only entries strictly after it, even across client restarts.

```json
{"type": "get_entries"}
```

With a cursor:
```json
{"type": "get_entries", "since": "abc123"}
```

Response:
```json
{
  "type": "response",
  "command": "get_entries",
  "success": true,
  "data": {
    "entries": [
      {"type": "message", "id": "def456", "parentId": "abc123", "timestamp": "...", "message": {"role": "user", "...": "..."}}
    ],
    "leafId": "def456"
  }
}
```

`leafId` is the id of the current leaf entry (`null` for an empty session), so a client can tell in one round trip whether the active branch moved. If `since` does not match any entry id, the response is `success: false`.

#### get_tree

Get the session as a tree of entries. Each node is `{entry, children, label?, labelTimestamp?}`. A well-formed session has a single root; orphaned entries (broken parent chain) also appear as roots.

```json
{"type": "get_tree"}
```

Response:
```json
{
  "type": "response",
  "command": "get_tree",
  "success": true,
  "data": {
    "tree": [
      {
        "entry": {"type": "message", "id": "abc123", "parentId": null, "...": "..."},
        "children": [
          {"entry": {"type": "message", "id": "def456", "parentId": "abc123", "...": "..."}, "children": []}
        ]
      }
    ],
    "leafId": "def456"
  }
}
```

#### get_last_assistant_text

Get the text content of the last assistant message.

```json
{"type": "get_last_assistant_text"}
```

Response:
```json
{
  "type": "response",
  "command": "get_last_assistant_text",
  "success": true,
  "data": {"text": "The assistant's response..."}
}
```

Returns `{"text": null}` if no assistant messages exist.

#### set_session_name

Set a display name for the current session. The name appears in session listings and helps identify sessions.

```json
{"type": "set_session_name", "name": "my-feature-work"}
```

Response:
```json
{
  "type": "response",
  "command": "set_session_name",
  "success": true
}
```

The current session name is available via `get_state` in the `sessionName` field. To set the initial name when starting RPC mode, pass `--name <name>` or `-n <name>` to the `atomic --mode rpc` process.

### Commands

#### get_commands

Get available commands (extension commands, prompt templates, and skills). These can be invoked via the `prompt` command by prefixing with `/`.

```json
{"type": "get_commands"}
```

Response:
```json
{
  "type": "response",
  "command": "get_commands",
  "success": true,
  "data": {
    "commands": [
      {"name": "session-name", "description": "Set or clear session name", "source": "extension", "path": "/home/user/.atomic/agent/extensions/session.ts"},
      {"name": "fix-tests", "description": "Fix failing tests", "source": "prompt", "location": "project", "path": "/home/user/myproject/.atomic/prompts/fix-tests.md"},
      {"name": "skill:brave-search", "description": "Web search via Brave API", "source": "skill", "location": "user", "path": "/home/user/.atomic/agent/skills/brave-search/SKILL.md"}
    ]
  }
}
```

Each command has:
- `name`: Command name (invoke with `/name`)
- `description`: Human-readable description (optional for extension commands)
- `source`: What kind of command:
  - `"extension"`: Registered via `pi.registerCommand()` in an extension
  - `"prompt"`: Loaded from a prompt template `.md` file
  - `"skill"`: Loaded from a skill directory (name is prefixed with `skill:`)
- `location`: Where it was loaded from (optional, not present for extensions):
  - `"user"`: User-level (`~/.atomic/agent/`)
  - `"project"`: Project-level (`./.atomic/`)
  - `"path"`: Explicit path via CLI or settings
- `path`: Absolute file path to the command source (optional)

**Note**: Built-in TUI commands (`/settings`, `/hotkeys`, etc.) are not included. They are handled only in interactive mode and would not execute if sent via `prompt`.

## Events

Events are streamed to stdout as JSON lines. Most events do not include an `id`; `bash_execution_update` is the deliberate exception and uses the originating bash request ID.

### Event Types

| Event | Description |
|-------|-------------|
| `agent_start` | Agent begins processing |
| `agent_end` | Agent completes (includes all generated messages) |
| `turn_start` | New turn begins |
| `turn_end` | Turn completes (includes assistant message and tool results) |
| `message_start` | Message begins |
| `message_update` | Streaming update (text/thinking/toolcall deltas) |
| `message_end` | Message completes |
| `tool_execution_start` | Tool begins execution; includes `toolCallId`, `toolName`, and initial arguments |
| `tool_execution_update` | Tool execution progress (streaming output) |
| `tool_execution_end` | Tool completes |
| `bash_execution_update` | Correlated direct-bash stdout/stderr delta |
| `queue_update` | Pending steering/follow-up queue changed |
| `compaction_start` | Verbatim line compaction begins |
| `compaction_end` | Verbatim line compaction completes |
| `auto_retry_start` | Auto-retry begins (after transient error) |
| `auto_retry_end` | Auto-retry completes (success or final failure) |
| `summarization_retry_scheduled` | Retry scheduled for a transient compaction or branch-summary provider error |
| `summarization_retry_attempt_start` | Retried summarization request starts |
| `summarization_retry_finished` | Summarization retry loop completes |
| `extension_error` | Extension threw an error |

### agent_start

Emitted when the agent begins processing a prompt.

```json
{"type": "agent_start"}
```

### agent_end

Emitted when the agent completes. Contains all messages generated during this run.

```json
{
  "type": "agent_end",
  "messages": [...]
}
```

### turn_start / turn_end

A turn consists of one assistant response plus any resulting tool calls and results.

```json
{"type": "turn_start"}
```

```json
{
  "type": "turn_end",
  "message": {...},
  "toolResults": [...]
}
```

### message_start / message_end

Emitted when a message begins and completes. The `message` field contains an `AgentMessage`.

```json
{"type": "message_start", "message": {...}}
{"type": "message_end", "message": {...}}
```

### message_update (Streaming)

Emitted during streaming of assistant messages. Carries the streaming delta plus the latest cumulative usage.

`message_update` has no cumulative `message`, and `assistantMessageEvent` has no `partial`. Build your message from `message_start` and deltas, then use `message_end` as the final authoritative message.

The top-level `usage` field carries the latest cumulative provider-reported usage; it may
remain zero until completion when a provider does not report usage during streaming. When
the provider reports an explicit end-of-turn signal (pi-ai's `AssistantMessage.endTurn`,
for example OpenAI Codex `end_turn`), the update carries it as a top-level `endTurn`
boolean — present only when the provider reported one.

```json
{
  "type": "message_update",
  "usage": {
    "input": 100,
    "output": 1,
    "cacheRead": 0,
    "cacheWrite": 0,
    "totalTokens": 101,
    "cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0, "total": 0}
  },
  "assistantMessageEvent": {
    "type": "text_delta",
    "contentIndex": 0,
    "delta": "Hello "
  }
}
```

The `assistantMessageEvent` field contains one of these delta types:

| Type | Description |
|------|-------------|
| `start` | Message generation started |
| `text_start` | Text content block started |
| `text_delta` | Text content chunk |
| `text_end` | Text content block ended |
| `thinking_start` | Thinking block started |
| `thinking_delta` | Thinking content chunk |
| `thinking_end` | Thinking block ended |
| `toolcall_start` | Tool call started |
| `toolcall_delta` | Tool call arguments chunk |
| `toolcall_end` | Tool call ended (includes full `toolCall` object) |
| `done` | Message complete (reason: `"stop"`, `"length"`, `"toolUse"`) |
| `error` | Error occurred (reason: `"aborted"`, `"error"`) |

Example streaming a text response:
```json
{"type":"message_update","usage":{...},"assistantMessageEvent":{"type":"text_start","contentIndex":0}}
{"type":"message_update","usage":{...},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":"Hello"}}
{"type":"message_update","usage":{...},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":" world"}}
{"type":"message_update","usage":{...},"assistantMessageEvent":{"type":"text_end","contentIndex":0,"content":"Hello world"}}
```

### tool_execution_start / tool_execution_update / tool_execution_end

Emitted when a tool begins, streams progress, and completes execution.

```json
{
  "type": "tool_execution_start",
  "toolCallId": "call_abc123",
  "toolName": "bash",
  "args": {"command": "ls -la"}
}
```

During execution, `tool_execution_update` events stream partial results (e.g., bash output as it arrives):

```json
{
  "type": "tool_execution_update",
  "toolCallId": "call_abc123",
  "toolName": "bash",
  "args": {"command": "ls -la"},
  "partialResult": {
    "content": [{"type": "text", "text": "partial output so far..."}],
    "details": {"truncation": null, "fullOutputPath": null}
  }
}
```

When complete:

```json
{
  "type": "tool_execution_end",
  "toolCallId": "call_abc123",
  "toolName": "bash",
  "result": {
    "content": [{"type": "text", "text": "total 48\n..."}],
    "details": {...}
  },
  "isError": false
}
```

Use `toolCallId` to correlate events. The `partialResult` in `tool_execution_update` contains the accumulated output so far (not just the delta), allowing clients to simply replace their display on each update.

### bash_execution_update

Emitted only for direct `bash` and non-intercepted `user_bash` RPC execution. Each event is `{type, id?, channel, delta}` where `channel` is `"stdout"` or `"stderr"`; use `id` to keep concurrent streams separate. Tool-call bash continues to use `tool_execution_update` and its `toolCallId`.

### queue_update

Emitted whenever the pending steering or follow-up queue changes.

```json
{
  "type": "queue_update",
  "steering": ["Focus on error handling"],
  "followUp": ["After that, summarize the result"]
}
```

### compaction_start / compaction_end

Emitted when default Verbatim Compaction runs, whether manual or automatic. The result records deletion targets and stats rather than a generated summary.

```json
{"type": "compaction_start", "reason": "threshold"}
```

The `reason` field is `"manual"`, `"threshold"`, or `"overflow"`.

```json
{
  "type": "compaction_end",
  "reason": "threshold",
  "result": {
    "compactedText": "[User]: fix the test\n(filtered 42 lines)",
    "firstKeptEntryId": "m7",
    "tokensBefore": 150000,
    "promptVersion": 3,
    "parameters": {"compression_ratio": 0.5, "preserve_recent": 2, "query": "fix the test"},
    "rung": "planned",
    "stats": {
      "linesBefore": 812,
      "linesDeleted": 417,
      "linesKept": 395,
      "rangeCount": 63,
      "tokensBefore": 150000,
      "tokensAfter": 72000,
      "percentReduction": 52
    }
  },
  "aborted": false,
  "willRetry": false
}
```

If `reason` was `"overflow"` and compaction succeeds, `willRetry` is `true` and the agent will automatically retry the prompt. Public prompt/RPC callers wait for that post-compaction continuation before the prompt is considered complete.

If compaction was aborted, `result` is `null` and `aborted` is `true`.

If compaction failed (e.g., API quota exceeded), `result` is `null`, `aborted` is `false`, and `errorMessage` contains the error description.

`result` and `errorMessage` are independent. A mid-turn post-tool compaction can commit a boundary and *then* fail the provider hard-input-limit gate, so one `compaction_end` may carry both a non-null `result` and an `errorMessage`. Treat the result as a committed durable boundary in that case; the error describes the follow-up request that was not sent.

If overflow recovery exhausts the same-model compact-and-retry attempt, `compaction_end` includes `"unresolvedOverflow": true` and an `errorMessage`. Workflow orchestration treats that signal as a context-length failure that can advance configured model fallback tiers.

There is no `context_compact` command; Atomic reports it as an unknown command. Use `compact`. Only `compaction_start` and `compaction_end` events are emitted.

### auto_retry_start / auto_retry_end

Emitted when automatic retry is triggered after a transient error (overloaded, rate limit, 5xx).

```json
{
  "type": "auto_retry_start",
  "attempt": 1,
  "maxAttempts": 3,
  "delayMs": 2000,
  "errorMessage": "529 {\"type\":\"error\",\"error\":{\"type\":\"overloaded_error\",\"message\":\"Overloaded\"}}"
}
```

```json
{
  "type": "auto_retry_end",
  "success": true,
  "attempt": 2
}
```

On final failure (max retries exceeded):
```json
{
  "type": "auto_retry_end",
  "success": false,
  "attempt": 3,
  "finalError": "529 overloaded_error: Overloaded"
}
```

### summarization_retry_scheduled / summarization_retry_attempt_start / summarization_retry_finished

Emitted when compaction planning or branch summarization retries after a transient provider error. These events use the same retry settings as automatic assistant-turn retries.

```json
{
  "type": "summarization_retry_scheduled",
  "attempt": 1,
  "maxAttempts": 3,
  "delayMs": 2000,
  "errorMessage": "terminated"
}
```

```json
{
  "type": "summarization_retry_attempt_start",
  "source": "compaction",
  "reason": "threshold"
}
```

For branch summaries, `source` is `"branchSummary"` and no `reason` is present. The loop then emits:

```json
{"type": "summarization_retry_finished"}
```

### extension_error

Emitted when an extension throws an error.

```json
{
  "type": "extension_error",
  "extensionPath": "/path/to/extension.ts",
  "event": "tool_call",
  "error": "Error message..."
}
```

## Error Handling

Failed commands return a response with `success: false`:

```json
{
  "type": "response",
  "command": "set_model",
  "success": false,
  "error": "Model not found: invalid/model"
}
```

Parse errors:

```json
{
  "type": "response",
  "command": "parse",
  "success": false,
  "error": "Failed to parse command: Unexpected token..."
}
```

## Types

Source files and installed definitions:
- `node_modules/@bastani/pi-ai/dist/types.d.ts` - `Model`, `UserMessage`, `AssistantMessage`, `ToolResultMessage`
- `node_modules/@earendil-works/pi-agent-core/dist/types.d.ts` - `AgentMessage`, `AgentEvent`
- [`src/core/messages.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/messages.ts) - `BashExecutionMessage`
- [`src/modes/rpc/rpc-types.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/modes/rpc/rpc-types.ts) - RPC command/response types, extension UI request/response types

### Model

```json
{
  "id": "claude-sonnet-4-20250514",
  "name": "Claude Sonnet 4",
  "api": "anthropic-messages",
  "provider": "anthropic",
  "baseUrl": "https://api.anthropic.com",
  "reasoning": true,
  "input": ["text", "image"],
  "contextWindow": 200000,
  "maxTokens": 16384,
  "cost": {
    "input": 3.0,
    "output": 15.0,
    "cacheRead": 0.3,
    "cacheWrite": 3.75
  }
}
```

`contextWindow` is the model's token budget used by Atomic's local budgeting, footer/stats, and compaction logic.

### UserMessage

```json
{
  "role": "user",
  "content": "Hello!",
  "timestamp": 1733234567890
}
```

The `content` field can be a string or an array of `TextContent`/`ImageContent` blocks.

### AssistantMessage

```json
{
  "role": "assistant",
  "content": [
    {"type": "text", "text": "Hello! How can I help?"},
    {"type": "thinking", "thinking": "User is greeting me..."},
    {"type": "toolCall", "id": "call_123", "name": "bash", "arguments": {"command": "ls"}}
  ],
  "api": "anthropic-messages",
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "usage": {
    "input": 100,
    "output": 50,
    "cacheRead": 0,
    "cacheWrite": 0,
    "cost": {"input": 0.0003, "output": 0.00075, "cacheRead": 0, "cacheWrite": 0, "total": 0.00105}
  },
  "stopReason": "stop",
  "timestamp": 1733234567890
}
```

Stop reasons: `"stop"`, `"length"`, `"toolUse"`, `"error"`, `"aborted"`. A streaming message carries `"pending"` until the terminal event replaces it, so a client that switches on the reason needs that case; a completed message never carries it. On the wire the pending reason appears on the `message_start` message — `message_update` frames carry no message at all — and `message_end` carries the terminal reason. A provider that reports an explicit end-of-turn signal (pi-ai's `AssistantMessage.endTurn`, for example OpenAI Codex `end_turn`) sets `endTurn: true` on the assistant message; `message_update` frames echo it as a top-level boolean only when the provider reported one.

### ToolResultMessage

```json
{
  "role": "toolResult",
  "toolCallId": "call_123",
  "toolName": "bash",
  "content": [{"type": "text", "text": "total 48\ndrwxr-xr-x ..."}],
  "isError": false,
  "timestamp": 1733234567890
}
```

### BashExecutionMessage

Created by the `bash` RPC command (not by LLM tool calls):

```json
{
  "role": "bashExecution",
  "command": "ls -la",
  "output": "total 48\ndrwxr-xr-x ...",
  "exitCode": 0,
  "cancelled": false,
  "truncated": false,
  "fullOutputPath": null,
  "timestamp": 1733234567890
}
```

### Attachment

```json
{
  "id": "img1",
  "type": "image",
  "fileName": "photo.jpg",
  "mimeType": "image/jpeg",
  "size": 102400,
  "content": "base64-encoded-data...",
  "extractedText": null,
  "preview": null
}
```