Protocol Reference

Ante uses a typed message-passing protocol between the client and daemon. Messages are exchanged over bounded async channels (in-process) or as JSON Lines over stdin/stdout (external clients).

Wire format

External clients communicate with the daemon using JSON Lines (JSONL) — one JSON object per line over stdin/stdout.

Client → Daemon: Send OpMsg objects as JSON lines to stdin
Daemon → Client: Receive EventMsg objects as JSON lines from stdout

OpMsg envelope

Every operation is wrapped in an OpMsg:

{
  "op": { "StartSession": { "model": "claude-sonnet-5", "provider": "anthropic" } },
  "id": "op_01ARZ3NDEKTSV4RRFFQ69G5FAV"
}

EventMsg envelope

Every event is wrapped in an EventMsg:

{
  "timestamp": "2025-06-01T12:00:00Z",
  "id": "evt_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "event": { "AgentMessage": "Here is the result..." },
  "parent": "op_01ARZ3NDEKTSV4RRFFQ69G5FAV"
}

The parent field links an event back to the operation that triggered it. It is null when not applicable.

Message IDs

Every message has a typed Id consisting of a prefix (up to 4 bytes) and a ULID. The string format is {prefix}_{ulid}.

Prefix	Usage
`op_`	Operations (client → daemon)
`evt_`	Events (daemon → client)
`ses_`	Session identifiers
`step_`	Step identifiers

Example: op_01J5A3B7C9D0E1F2G3H4J5K6M7

Operations (Client → Daemon)

StartSession

Initialize a new session, replacing any session already running. A field supplied by the client is pinned; an omitted or null field resolves from the host's settings at this session boundary, or from Ante's built-in default when the setting is absent.

{
  "op": {
    "StartSession": {
      "model": "claude-sonnet-5",
      "provider": "anthropic",
      "permission_mode": null,
      "system_prompt": null,
      "append_system_prompt": null,
      "tools": null,
      "include_tools": null,
      "exclude_tools": null,
      "cwd": null,
      "effort": null,
      "enable_auto_memory": null,
      "short_prompt": null,
      "no_skills": null,
      "save_session": null,
      "title": null
    }
  },
  "id": "op_..."
}

SessionRequest fields:

Field	Type	Description
`model`	`string?`	Model name (e.g. `"claude-sonnet-5"`); `null` uses the host default
`provider`	`string?`	Provider name (e.g. `"anthropic"`, `"openai"`, `"gemini"`, `"xai"`, `"openrouter"`, `"local"`); `null` uses the host default
`permission_mode`	`PermissionMode?`	Tool approval mode: `"strict"`, `"auto"`, or `"yolo"`; `null` uses the host default
`system_prompt`	`string?`	Override the default system prompt entirely
`append_system_prompt`	`string?`	Append content to the default system prompt
`tools`	`string[]?`	Exactly these tools, replacing the default tool set as the base. Also gates dynamically registered (MCP) tools
`include_tools`	`string[]?`	Tools added on top of the base set (`tools`, or the default set)
`exclude_tools`	`string[]?`	Tools removed from the session; wins over `tools` and `include_tools`
`cwd`	`string?`	Working directory. Defaults to daemon's process directory
`effort`	`Effort?`	Effort override: `"min"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`, or `"max"`. `null` resolves from the catalog
`enable_auto_memory`	`bool?`	Whether the agent records and recalls auto-memory. `null` leaves the daemon default (on for interactive sessions)
`short_prompt`	`bool?`	Use compact tool descriptions and system prompt to shrink the context footprint. `null` leaves the settings default
`no_skills`	`bool?`	When `true`, skip all skill discovery so no skills are advertised or invocable. `null` leaves the session default
`save_session`	`bool?`	Whether to write a transcript and resumable snapshot. `null` leaves the host's session-saving default
`title`	`string?`	A display name for the session, shown in place of the first message in resume pickers. Trimmed; empty after trimming means no title. `null` starts the session untitled

SessionRequest replaced the former SessionOverrides name in v0.preview.92. The JSON field names stayed the same, but absence now has one explicit meaning for StartSession: resolve the host's default now, never “leave the previous session unchanged.” A client implementing /clear should retain and resend its own request, applying any model or permission-mode changes it made; there is no separate restart operation.

UpdateSession

Update the active session without restarting it (e.g. switch models or permission mode mid-session). Each field is optional; an absent field is left unchanged. A permission-mode change — what Shift+Tab cycling sends from the TUI — takes effect immediately, applying to the turn already in flight as well as later ones; a model change applies on the next turn. A title change applies at once and is echoed back on the SessionUpdated event. Other session options must be set at StartSession time.

{
  "op": {
    "UpdateSession": {
      "model": { "id": "gpt-5.4", "temperature": 0.2, "effort": "high" },
      "permission_mode": "auto",
      "title": "auth refactor"
    }
  },
  "id": "op_..."
}

SessionUpdate fields:

Field	Type	Description
`model`	`ModelSpec?`	New model specification to use. Carries the whole request, `effort` included: a set `effort` overrides the catalog default; unset fields resolve from the catalog
`permission_mode`	`PermissionMode?`	New permission mode (`"strict"`, `"auto"`, or `"yolo"`)
`title`	`string?`	Rename the session. The text is trimmed; an empty or whitespace-only string clears the title

ResumeSession

Resume a previously persisted session by its ID. The daemon restores the saved dialog and pinned model, provider, and effort, resolves anything the snapshot did not pin from the host's current defaults, re-discovers extensions, and replays recent events so the client can rebuild its view.

{ "op": { "ResumeSession": { "session_id": "ses_01ARZ..." } }, "id": "op_..." }

Field	Type	Description
`session_id`	`Id`	The session identifier to resume

On success the daemon emits SessionEnd for the current session (if any), then SessionStart and ExtensionRefreshed for the resumed session, followed by up to 200 replayed historical events. On failure it emits an Error event.

Steer

Provide additional guidance to the agent during an active turn without starting a new one.

{ "op": { "Steer": "focus on the auth module first" }, "id": "op_..." }

UserInput

Submit user text input to the agent.

{ "op": { "UserInput": "explain what this project does" }, "id": "op_..." }

ShellInput

Run a shell command on the daemon side without starting a turn — the !command path in the TUI. The daemon answers with a ShellOutput event and queues the output into the agent's context for the next turn.

{ "op": { "ShellInput": "git status" }, "id": "op_..." }

ApprovalResponse

Respond to a tool approval request (sent after receiving a TurnPause event with Approval reason).

{
  "op": {
    "ApprovalResponse": {
      "turn_id": "step_01ARZ...",
      "responses": [
        { "tool_use_id": "tool_use_abc123", "decision": "Accept" },
        {
          "tool_use_id": "tool_use_def456",
          "decision": "Deny",
          "message": "use the read-only endpoint"
        }
      ]
    }
  },
  "id": "op_..."
}

ToolDecision fields:

Field	Type	Description
`tool_use_id`	`string`	Tool call being decided (matches `ToolStart.id`)
`decision`	`ReviewDecision`	One of the values below
`message`	`string?`	Feedback returned with a denial. Omit for every other decision

ReviewDecision values:

Decision	Description
`Accept`	Allow this tool call
`Deny`	Deny this tool call. The agent receives a failed tool result — `Tool call denied by user: <message>` when a `message` is present, otherwise `Tool call denied by user and was not executed.`
`AcceptForSession`	Grant this call for the rest of the session (scoped — see Session grants)
`AcceptAlways`	Grant for the session and persist an allow rule to `settings.json` ("always allow")

SlashCommand

Invoke a skill by name.

{ "op": { "SlashCommand": { "name": "commit", "args": "-m 'fix bug'" } }, "id": "op_..." }

Compact

Manually trigger conversation compaction on the active session (what /compact sends). Optional instructions steer what the replacement summary emphasizes or preserves; they are ignored when the reducer can reclaim enough context without writing a summary. The daemon emits CompactStart and CompactEnd around the operation.

{ "op": { "Compact": {} }, "id": "op_..." }
{ "op": { "Compact": { "instructions": "focus on the API changes" } }, "id": "op_..." }

Compact is a struct variant in v0.preview.90; clients must send the empty object form when they have no instructions rather than the older bare string form.

ContextReport

Request a per-category breakdown of the active session's context-window occupancy (what /context sends). Answered with a ContextReport event.

{ "op": "ContextReport", "id": "op_..." }

Goal

Set, clear, or report a goal-driven execution loop on the active session. A set goal keeps the session working — re-running turns and judging the condition after each one — until it is met, judged unreachable, or cleared.

{ "op": { "Goal": { "Set": "all tests pass" } }, "id": "op_..." }
{ "op": { "Goal": "Clear" }, "id": "op_..." }
{ "op": { "Goal": "Status" }, "id": "op_..." }

AmbientPhrase / AmbientSuggestion

Request an ad-hoc ambient prediction off the conversation's critical path on a cheap model: AmbientPhrase predicts a spinner "thinking phrase" for the in-progress draft, and AmbientSuggestion predicts a next-prompt suggestion from the last exchange. Both answer with an Ambient event; the monotonic req_id lets the client discard stale results.

{ "op": { "AmbientPhrase": { "draft": "refactor the parser to...", "req_id": 3 } }, "id": "op_..." }
{ "op": { "AmbientSuggestion": { "recent_user": "fix the bug", "recent_agent": "Fixed — the cause was...", "req_id": 7 } }, "id": "op_..." }

Interrupt

Abort whatever is currently running.

{ "op": "Interrupt", "id": "op_..." }

Shutdown

Request a graceful shutdown.

{ "op": "Shutdown", "id": "op_..." }

RegisterLocalProvider

Register a running local inference server (e.g. an offline llama-server started by the client) as the local provider for this daemon. The model is optional — if provided, it pins the local provider to a specific ModelSpec; otherwise the local provider serves whatever model the server is hosting.

{
  "op": {
    "RegisterLocalProvider": {
      "port": 8080,
      "model": null
    }
  },
  "id": "op_..."
}

Field	Type	Description
`port`	`u16`	Port the local llama-server is listening on
`model`	`ModelSpec?`	Optional model spec to pin the provider to

RestoreLocalProvider

Restore the previously registered local provider configuration after a session-level provider switch. Useful when the daemon needs to revert to a previously registered local server without re-supplying its port and model.

{ "op": "RestoreLocalProvider", "id": "op_..." }

Events (Daemon → Client)

Session events

SessionStart

Emitted when a session is initialized. It announces the session identity, mutable settings, and the skills and subagents equipped for the session. ExtensionRefreshed immediately repeats those capability lists alongside MCP state for clients that replace all extension state from one event.

{
  "event": {
    "SessionStart": {
      "model": { "id": "claude-sonnet-5", "max_tokens": 8192 },
      "provider": {
        "id": "anthropic",
        "display_name": "Anthropic",
        "base_url": "https://api.anthropic.com/v1"
      },
      "session_id": "ses_01ARZ...",
      "cwd": "/home/user/project",
      "permission_mode": "strict",
      "skills": [],
      "subagents": []
    }
  }
}

SessionInfo fields:

Field	Type	Description
`model`	`ModelSpec`	Active model specification
`provider`	`ProviderSpec`	Active provider (see below)
`session_id`	`Id`	Unique session identifier
`cwd`	`string`	Working directory path
`permission_mode`	`PermissionMode`	Active permission mode (`"strict"`, `"auto"`, or `"yolo"`)
`skills`	`SkillMetadata[]`	Skills the user can invoke in this session. Defaults to an empty list when absent for backward compatibility
`subagents`	`SubagentMetadata[]`	Subagents this session can delegate to. Defaults to an empty list when absent for backward compatibility
`title`	`string?`	The session's title when one is set — chosen by the user or the client, never derived from the conversation. Omitted from the payload entirely when unset

The embedded ModelSpec uses the model fields documented in the Catalog Reference. Since v0.preview.92, its optional supported_efforts field carries a custom model's accepted effort ladder; it replaces the old output-only effort_options field.

ProviderSpec fields:

Field	Type	Description
`id`	`string`	Provider key, e.g. `"anthropic"` (accepts `name` as a legacy alias)
`display_name`	`string`	Friendly name for display
`base_url`	`string`	Endpoint actually in use for this session — environment overrides can move it away from the catalog default

The payload type was named SessionInitialized before v0.preview.94 and is now SessionInfo. This is a Rust type name only — the event names (SessionStart, SessionUpdated) and the JSON are unchanged, so no client needs to adapt.

ProviderSpec deliberately carries only what a client cannot look up for itself. The provider's model list is not on the wire; it is identical for every session and is published by ante catalog. Unknown fields are ignored, so payloads from older daemons that still send preferred_models decode fine.

SessionUpdated

Emitted when the active session is updated in place (e.g. model changed via UpdateSession). Carries the same fields as SessionStart.

{
  "event": {
    "SessionUpdated": {
      "model": { "id": "gpt-5.4" },
      "provider": {
        "id": "openai",
        "display_name": "OpenAI",
        "base_url": "https://api.openai.com/v1"
      },
      "session_id": "ses_01ARZ...",
      "cwd": "/home/user/project",
      "permission_mode": "strict",
      "skills": [],
      "subagents": []
    }
  }
}

SessionEnd

Emitted when the session span closes. Mirrors TurnEnd: it carries the session's identity, why it ended, and its final usage accounting.

{
  "event": {
    "SessionEnd": {
      "session_id": "ses_01ARZ...",
      "reason": "Shutdown",
      "usage": { "input_tokens": 15000, "output_tokens": 3000 }
    }
  }
}

SessionEndReason variants:

Variant	Description
`Replaced`	The session was replaced by a new or resumed session
`Shutdown`	The daemon is shutting down

Turn lifecycle events

TurnStart

Emitted when a new turn begins processing.

{ "event": { "TurnStart": { "turn_id": "step_01ARZ..." } } }

TurnPause

Emitted when a turn is paused waiting for user input (e.g. tool approval).

{
  "event": {
    "TurnPause": {
      "turn_id": "step_01ARZ...",
      "reason": {
        "Approval": {
          "tools": [
            { "id": "tool_use_abc123", "name": "Bash", "input": { "command": "ls -la" } }
          ],
          "message": "Allow running shell command?"
        }
      }
    }
  }
}

TurnPauseReason variants:

Variant	Fields	Description
`Approval`	`tools: ToolUse[]`, `message: string`	Waiting for tool approval

TurnResume

Emitted when the turn resumes after a TurnPause (e.g. the approval was answered or a steer arrived), so clients never have to infer resumption from the next tool event.

{ "event": { "TurnResume": { "turn_id": "step_01ARZ..." } } }

TurnEnd

Emitted when a turn completes. steps is the number of turn-loop steps attempted before the turn ended.

{ "event": { "TurnEnd": { "turn_id": "step_01ARZ...", "status": "Completed", "steps": 4 } } }

TurnEndStatus variants:

Variant	Fields	Description
`Completed`	—	Turn finished successfully
`Interrupted`	`reason?: string`	Turn was interrupted
`Error`	`kind?: string`, `headline: string`, `details: string[]`	Turn ended with an error. `kind` is a stable machine-readable LLM error kind when available — notably `"oauth"` means the provider sign-in is missing, expired, or revoked. `headline` is a one-line summary; `details` are expanded cause lines

Message streaming events

AgentMessage

Complete agent text response (non-streaming).

{ "event": { "AgentMessage": "The project is a web server that..." } }

Thinking

Complete chain-of-thought block (non-streaming).

{ "event": { "Thinking": "Let me analyze the codebase structure..." } }

MessageDelta

Streaming chunk of the agent's message. Concatenate all deltas to build the full message.

{ "event": { "MessageDelta": "The project" } }

ThinkingDelta

Streaming chunk of the agent's thinking. Concatenate all deltas to build the full thinking block.

{ "event": { "ThinkingDelta": "Let me" } }

Tool events

ToolStart

Emitted when a tool invocation begins.

{
  "event": {
    "ToolStart": {
      "id": "tool_use_abc123",
      "name": "Read",
      "input": { "file_path": "/src/main.rs" }
    }
  }
}

ToolUpdate

Progress update during tool execution.

{
  "event": {
    "ToolUpdate": {
      "tool_use_id": "tool_use_abc123",
      "seq": 0,
      "message": "Reading file..."
    }
  }
}

Field	Type	Description
`tool_use_id`	`string`	Tool call identifier (matches `ToolStart.id`)
`seq`	`u64`	Monotonically increasing sequence number
`message`	`string`	Progress message

ToolEnd

Emitted when a tool execution completes.

{
  "event": {
    "ToolEnd": {
      "tool_use_id": "tool_use_abc123",
      "status": "Completed",
      "result_json": { "content": "fn main() { ... }" },
      "is_error": false
    }
  }
}

ToolEndStatus variants:

Variant	Description
`Completed`	Tool ran successfully
`Cancelled`	Tool execution was cancelled
`Denied`	Tool was denied by the user
`Failed`	Tool execution failed

Compaction events

CompactStart

Emitted when dialog compaction begins.

{ "event": "CompactStart" }

CompactEnd

Emitted when dialog compaction completes. summary is the text that replaced the compacted history and carries forward as the session's context; it is null when compaction failed (history unchanged) or produced no displayable text.

{ "event": { "CompactEnd": { "summary": "The user asked to..." } } }

Extension events

ExtensionRefreshed

Emitted when skills, subagents, or MCP servers are refreshed. It is sent once immediately after SessionStart with the same skills/subagents and mcp_servers: []. When MCP servers are configured, a second event follows after warm-up with the discovered servers and tools; with no MCP configuration, the initial event is the only one.

{
  "event": {
    "ExtensionRefreshed": {
      "session_id": "ses_01ARZ...",
      "skills": [
        { "name": "commit", "description": "Create a git commit", "scope": "user", "argument_hint": "-m 'message'" }
      ],
      "subagents": [
        { "name": "explore", "description": "Explore the codebase", "scope": "project" }
      ],
      "mcp_servers": [
        {
          "name": "filesystem",
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
          "tools": [
            {
              "name": "read_text_file",
              "qualified_name": "mcp__filesystem__read_text_file",
              "description": "Read the contents of a text file",
              "parameters": [
                { "name": "path", "param_type": "string", "required": true, "description": "Path to the file" }
              ]
            }
          ]
        }
      ]
    }
  }
}

Each entry in mcp_servers reflects what was actually launched and discovered: the tools list is empty for servers that failed to connect, and qualified_name is the mcp__<server>__<tool> form the agent uses to call the tool.

Informational events

UsageUpdate

Token usage statistics for the session. context is omitted before the first response or when the model context limit is unknown. It carries raw measurements only — used_tokens (cache-inclusive window occupancy) and limit_tokens (the raw model context limit); any percentage is derived by the client. usage may also include cache_read_tokens and cache_creation_tokens when the provider reports them.

{
  "event": {
    "UsageUpdate": {
      "usage": { "input_tokens": 1500, "output_tokens": 300 },
      "context": { "used_tokens": 1800, "limit_tokens": 200000 }
    }
  }
}

ContextReport

Answer to the ContextReport operation: a per-category breakdown of the session's context-window occupancy at the time of the request.

{
  "event": {
    "ContextReport": {
      "system_prompt_tokens": 3200,
      "system_tools_tokens": 4100,
      "mcp_tools_tokens": 900,
      "memory_tokens": 600,
      "skills_tokens": 450,
      "messages_tokens": 12000,
      "used_tokens": 21250,
      "limit_tokens": 200000,
      "compact_buffer_tokens": 20000
    }
  }
}

Field	Type	Description
`system_prompt_tokens`	`u32`	System prompt, excluding the skills and memory sections counted separately
`system_tools_tokens`	`u32`	Built-in tool schemas
`mcp_tools_tokens`	`u32`	MCP tool schemas
`memory_tokens`	`u32`	Project/user instruction files and the auto-memory prompt
`skills_tokens`	`u32`	The available-skills listing
`messages_tokens`	`u32`	Conversation messages — everything not attributed to a category above
`used_tokens`	`u32`	Total context-window occupancy
`limit_tokens`	`u32?`	Model context limit; `null` when unverified
`compact_buffer_tokens`	`u32`	Tokens reserved at the top of the window; auto-compaction triggers once occupancy grows into this reserve

Info

General informational message.

{ "event": { "Info": "Compacting conversation history..." } }

InfoBlockStart

Opens a grouped Info entry with a header. Subsequent InfoBlockAppend events sharing the same id render as tree-indented child lines under it — used for multi-step background notifications (e.g. MCP warm-up) that should visually cluster. When loading is true the renderer animates a ./../... suffix on the header until the first InfoBlockAppend arrives.

{
  "event": {
    "InfoBlockStart": {
      "id": "mcp-warmup-ses_01ARZ...",
      "header": "Warming up 4 MCP servers in the background — tools will become available as they connect.",
      "loading": true
    }
  }
}

InfoBlockAppend

Appends a child detail line to the InfoBlockStart with the same id. Drops silently if the matching block isn't present.

{
  "event": {
    "InfoBlockAppend": {
      "id": "mcp-warmup-ses_01ARZ...",
      "detail": "MCP ready: 4/4 servers connected, 60 tools registered."
    }
  }
}

Error

Error message.

{ "event": { "Error": "Authentication failed: invalid API key" } }

Goodbye

Final message before the daemon disconnects. After receiving this, no more events will be sent.

{ "event": "Goodbye" }

UserInput

User input recorded for session replay. This variant is written to the persisted event log but is not emitted during live sessions — you will only see it in events replayed by ResumeSession.

{ "event": { "UserInput": "explain what this project does" } }

ShellOutput

Answer to a ShellInput operation: the command that ran and what it produced.

{
  "event": {
    "ShellOutput": {
      "command": "git status",
      "stdout": "On branch main...",
      "stderr": "",
      "exit_code": 0
    }
  }
}

Ambient

An ephemeral ambient hint produced off the main conversation on a cheap model — a predicted "thinking phrase" for the current draft, or a suggested next prompt shown as input ghost text. Requested with the AmbientPhrase / AmbientSuggestion operations; req_id lets clients drop superseded results. Never persisted to the event log.

{ "event": { "Ambient": { "kind": "PromptSuggestion", "req_id": 7, "text": "run the tests" } } }

Offline mode and the protocol

Local-model management (engine installation, model discovery, llama-server lifecycle) is client-side. It is driven through the in-process OfflineSubsystem API, not through the daemon protocol. The only daemon-facing surface for offline mode is RegisterLocalProvider / RestoreLocalProvider — the client starts a llama-server itself, then registers its port (and an optional ModelSpec) with the daemon.

See the Offline Mode page for the user-facing flows and the --offline-model CLI flag.

Transport

In-process channels

When the client and daemon run in the same process (TUI or headless mode), they communicate via bounded Tokio mpsc channels:

Channel	Direction	Buffer size
Op channel	Client → Daemon	256 messages
Event channel	Daemon → Client	4096 messages

Stdio transport (JSONL)

For external clients using ante serve (or ante serve --stdio), StdioTransport bridges JSON Lines over stdin/stdout to the internal channel pair:

stdin → Parse each line as OpMsg → forward to daemon
daemon events → Serialize as JSON → write to stdout (one line per event)
EOF on stdin → Automatically sends Op::Shutdown
Evt::Goodbye received → Transport exits
JSON parse errors → An Evt::Error is sent back on stdout

Unix socket transport

For clients that dial a host someone else is running, ante serve --sock [PATH] listens on a Unix domain socket (default run/serve.sock in the Ante home) and exchanges the same JSONL protocol over the stream:

Each client gets its own connection and at most one active session on the shared host
Op::Shutdown ends only that connection; the host keeps accepting new ones
The host process exits on SIGINT or SIGTERM
Ownership is an exclusive lock on a .lock file beside the socket, so a second host on the same path refuses to start rather than displacing the live one; a stale socket left by a crashed host holds no lock and is replaced

WebSocket transport

For networked or browser-based clients using ante serve --ws <ADDR>, WsTransport exchanges the same JSONL protocol over WebSocket frames:

Each WebSocket client gets its own connection and session on the shared host
Messages are the same OpMsg and EventMsg JSON objects, sent as text frames
Client disconnect → That connection and session shut down; the server accepts the next client
Op::Shutdown received → Connection and server both exit
The server loops accepting new connections until a Shutdown is received

Complete flow example

A full session lifecycle from start to shutdown:

Client                                  Daemon
  │                                       │
  │─── OpMsg { StartSession(...) } ──────▶│
  │◀── EventMsg { SessionStart(...) } ────│
  │                                       │
  │─── OpMsg { UserInput("fix bug") } ───▶│
  │◀── EventMsg { TurnStart { turn_id } } │
  │◀── EventMsg { ThinkingDelta("...") }  │
  │◀── EventMsg { ThinkingDelta("...") }  │
  │◀── EventMsg { Thinking("...") }       │
  │◀── EventMsg { MessageDelta("...") }   │
  │◀── EventMsg { ToolStart(ToolUse) }    │
  │◀── EventMsg { TurnPause(Approval) }   │
  │                                       │
  │─── OpMsg { ApprovalResponse(...) } ──▶│
  │◀── EventMsg { ToolUpdate(...) }       │
  │◀── EventMsg { ToolEnd(...) }          │
  │◀── EventMsg { MessageDelta("...") }   │
  │◀── EventMsg { AgentMessage("...") }   │
  │◀── EventMsg { UsageUpdate(...) }      │
  │◀── EventMsg { TurnEnd(Completed) }    │
  │                                       │
  │─── OpMsg { Shutdown } ───────────────▶│
  │◀── EventMsg { SessionEnd }            │
  │◀── EventMsg { Goodbye }               │
  │                                       │

Wire format​

OpMsg envelope​

EventMsg envelope​

Message IDs​

Operations (Client → Daemon)​

StartSession​

UpdateSession​

ResumeSession​

Steer​

UserInput​

ShellInput​

ApprovalResponse​

SlashCommand​

Compact​

ContextReport​

Goal​

AmbientPhrase / AmbientSuggestion​

Interrupt​

Shutdown​

RegisterLocalProvider​

RestoreLocalProvider​

Events (Daemon → Client)​

Session events​

SessionStart​

SessionUpdated​

SessionEnd​

Turn lifecycle events​

TurnStart​

TurnPause​

TurnResume​

TurnEnd​

Message streaming events​

AgentMessage​

Thinking​

MessageDelta​

ThinkingDelta​

Tool events​

ToolStart​

ToolUpdate​

ToolEnd​

Compaction events​

CompactStart​

CompactEnd​

Extension events​

ExtensionRefreshed​

Informational events​

UsageUpdate​

ContextReport​

Info​

InfoBlockStart​

InfoBlockAppend​

Error​

Goodbye​

UserInput​

ShellOutput​

Ambient​

Offline mode and the protocol​

Transport​

In-process channels​

Stdio transport (JSONL)​

Unix socket transport​

WebSocket transport​

Complete flow example​

Wire format

OpMsg envelope

EventMsg envelope

Message IDs

Operations (Client → Daemon)

StartSession

UpdateSession

ResumeSession

Steer

UserInput

ShellInput

ApprovalResponse

SlashCommand

Compact

ContextReport

Goal

AmbientPhrase / AmbientSuggestion

Interrupt

Shutdown

RegisterLocalProvider

RestoreLocalProvider

Events (Daemon → Client)

Session events

SessionStart

SessionUpdated

SessionEnd

Turn lifecycle events

TurnStart

TurnPause

TurnResume

TurnEnd

Message streaming events

AgentMessage

Thinking

MessageDelta

ThinkingDelta

Tool events

ToolStart

ToolUpdate

ToolEnd

Compaction events

CompactStart

CompactEnd

Extension events

ExtensionRefreshed

Informational events

UsageUpdate

ContextReport

Info

InfoBlockStart

InfoBlockAppend

Error

Goodbye

UserInput

ShellOutput

Ambient

Offline mode and the protocol

Transport

In-process channels

Stdio transport (JSONL)

Unix socket transport

WebSocket transport

Complete flow example