Actions Reference
Complete reference for all action types in the Agent Host Protocol. Actions are the sole mutation mechanism for subscribable state.
JSON Schema: actions.schema.json
Action Envelope
Every action is wrapped in an ActionEnvelope:
interface ActionEnvelope {
readonly action: StateAction;
readonly serverSeq: number;
readonly origin: { clientId: string; clientSeq: number } | undefined;
readonly rejectionReason?: string;
}Root Actions
Mutate RootState. All are server-only.
root/agentsChanged 📄
Fired when available agent backends or their models change.
| Field | Type | Description |
|---|---|---|
type | ActionType.RootAgentsChanged | |
agents | AgentInfo[] | Updated agent list |
Session Actions
Mutate SessionState. Scoped to a session URI.
session/ready 📄
Session backend initialized successfully.
| Field | Type | Description |
|---|---|---|
type | ActionType.SessionReady | |
session | URI | Session URI |
session/creationFailed 📄
Session backend failed to initialize.
| Field | Type | Description |
|---|---|---|
type | ActionType.SessionCreationFailed | |
session | URI | Session URI |
error | ErrorInfo | Error details |
session/turnStarted 📄
Client-dispatchable. User sent a message; server starts agent processing.
| Field | Type | Required | Description |
|---|---|---|---|
type | ActionType.SessionTurnStarted | Yes | |
session | URI | Yes | Session URI |
turnId | string | Yes | Turn identifier |
userMessage | UserMessage | Yes | User's message |
queuedMessageId | string | No | If this turn was auto-started from a queued message, the ID of that message |
session/delta 📄
Streaming text chunk from the assistant, appended to a specific response part.
The server MUST first emit a session/responsePart to create the target part (markdown or reasoning), then use this action to append text to it.
| Field | Type | Description |
|---|---|---|
type | ActionType.SessionDelta | |
session | URI | Session URI |
turnId | string | Turn identifier |
partId | string | Identifier of the response part to append to |
content | string | Text chunk |
session/responsePart 📄
Structured content appended to the response.
| Field | Type | Description |
|---|---|---|
type | ActionType.SessionResponsePart | |
session | URI | Session URI |
turnId | string | Turn identifier |
part | ResponsePart | Response part (markdown or content ref) |
session/toolCallStart 📄
A tool call begins — parameters are streaming from the LM.
For client-provided tools, the server sets toolClientId to identify the owning client. That client is responsible for executing the tool once it reaches the running state and dispatching session/toolCallComplete.
| Field | Type | Required | Description |
|---|---|---|---|
type | ActionType.SessionToolCallStart | Yes | |
toolName | string | Yes | Internal tool name (for debugging/logging) |
displayName | string | Yes | Human-readable tool name |
toolClientId | string | No | If this tool is provided by a client, the clientId of the owning client. |
| Absent for server-side tools. |
session/toolCallDelta 📄
Streaming partial parameters for a tool call.
| Field | Type | Required | Description |
|---|---|---|---|
type | ActionType.SessionToolCallDelta | Yes | |
content | string | Yes | Partial parameter content to append |
invocationMessage | StringOrMarkdown | No | Updated progress message |
session/toolCallReady 📄
Tool call parameters are complete, or a running tool requires re-confirmation.
When dispatched for a streaming tool call, transitions to pending-confirmation or directly to running if confirmed is set.
When dispatched for a running tool call (e.g. mid-execution permission needed), transitions back to pending-confirmation. The invocationMessage and _meta SHOULD be updated to describe the specific confirmation needed. Clients use the standard session/toolCallConfirmed flow to approve or deny.
For client-provided tools, the server typically sets confirmed to 'not-needed' so the tool transitions directly to running, where the owning client can begin execution immediately.
| Field | Type | Required | Description |
|---|---|---|---|
type | ActionType.SessionToolCallReady | Yes | |
invocationMessage | StringOrMarkdown | Yes | Message describing what the tool will do or what confirmation is needed |
toolInput | string | No | Raw tool input |
confirmationTitle | StringOrMarkdown | No | Short title for the confirmation prompt (e.g. "Run in terminal", "Write file") |
edits | { items: FileEdit[] } | No | File edits that this tool call will perform, for preview before confirmation |
editable | boolean | No | Whether the agent host allows the client to edit the tool's input parameters before confirming |
confirmed | ToolCallConfirmationReason | No | If set, the tool was auto-confirmed and transitions directly to running |
options | ConfirmationOption[] | No | Options the server offers for this confirmation. When present, the client |
| SHOULD render these instead of a plain approve/deny UI. Each option | |||
| belongs to a {@link ConfirmationOptionGroup} so the client can still | |||
| categorise the choices. |
session/toolCallConfirmed (approved) 📄
Client-dispatchable. Client approves a pending tool call. The tool transitions to running.
| Field | Type | Required | Description |
|---|---|---|---|
type | ActionType.SessionToolCallConfirmed | Yes | |
approved | true | Yes | The tool call was approved |
confirmed | ToolCallConfirmationReason | Yes | How the tool was confirmed |
editedToolInput | string | No | Edited tool input parameters, if the client modified them before confirming |
selectedOptionId | string | No | ID of the selected confirmation option, if the server provided options |
session/toolCallConfirmed (denied) 📄
Client-dispatchable. Client denies a pending tool call. The tool transitions to cancelled.
For client-provided tools, the owning client MUST dispatch this if it does not recognize the tool or cannot execute it.
| Field | Type | Required | Description |
|---|---|---|---|
type | ActionType.SessionToolCallConfirmed | Yes | |
approved | false | Yes | The tool call was denied |
reason | ToolCallCancellationReason.Denied | ToolCallCancellationReason.Skipped | Yes | Why the tool was cancelled |
userSuggestion | UserMessage | No | What the user suggested doing instead |
reasonMessage | StringOrMarkdown | No | Optional explanation for the denial |
selectedOptionId | string | No | ID of the selected confirmation option, if the server provided options |
session/toolCallComplete 📄
Tool execution finished. Transitions to completed or pending-result-confirmation if requiresResultConfirmation is true.
For client-provided tools (where toolClientId is set on the tool call state), the owning client dispatches this action with the execution result. The server SHOULD reject this action if the dispatching client does not match toolClientId.
Servers waiting on a client tool call MAY time out after a reasonable duration if the implementing client disconnects or becomes unresponsive, and dispatch this action with result.success = false and an appropriate error.
| Field | Type | Required | Description |
|---|---|---|---|
type | ActionType.SessionToolCallComplete | Yes | |
result | ToolCallResult | Yes | Execution result |
requiresResultConfirmation | boolean | No | If true, the result requires client approval before finalizing |
ToolCallResult 📄
| Field | Type | Required | Description |
|---|---|---|---|
success | boolean | Yes | Whether the tool succeeded |
pastTenseMessage | StringOrMarkdown | Yes | Past-tense description of what the tool did |
content | ToolResultContent[] | No | Unstructured result content blocks. |
This mirrors the content field of MCP CallToolResult. | | structuredContent | Record<string, unknown> | No | Optional structured result object.
This mirrors the structuredContent field of MCP CallToolResult. | | error | { message: string; code?: string } | No | Error details if the tool failed |
session/toolCallResultConfirmed 📄
Client-dispatchable. Client approves or denies a tool's result.
If approved is false, the tool transitions to cancelled with reason result-denied.
| Field | Type | Description |
|---|---|---|
type | ActionType.SessionToolCallResultConfirmed | |
approved | boolean | Whether the result was approved |
session/turnComplete 📄
Turn finished — the assistant is idle.
| Field | Type | Description |
|---|---|---|
type | ActionType.SessionTurnComplete | |
session | URI | Session URI |
turnId | string | Turn identifier |
session/turnCancelled 📄
Client-dispatchable. Turn was aborted; server stops processing.
| Field | Type | Description |
|---|---|---|
type | ActionType.SessionTurnCancelled | |
session | URI | Session URI |
turnId | string | Turn identifier |
session/error 📄
Error during turn processing.
| Field | Type | Description |
|---|---|---|
type | ActionType.SessionError | |
session | URI | Session URI |
turnId | string | Turn identifier |
error | ErrorInfo | Error details |
session/titleChanged 📄
Client-dispatchable. Session title updated. Fired by the server when the title is auto-generated from conversation, or dispatched by a client to rename a session.
| Field | Type | Description |
|---|---|---|
type | ActionType.SessionTitleChanged | |
session | URI | Session URI |
title | string | New title |
session/usage 📄
Token usage report for a turn.
| Field | Type | Description |
|---|---|---|
type | ActionType.SessionUsage | |
session | URI | Session URI |
turnId | string | Turn identifier |
usage | UsageInfo | Token usage data |
session/reasoning 📄
Reasoning/thinking text from the model, appended to a specific reasoning response part.
The server MUST first emit a session/responsePart to create the target reasoning part, then use this action to append text to it.
| Field | Type | Description |
|---|---|---|
type | ActionType.SessionReasoning | |
session | URI | Session URI |
turnId | string | Turn identifier |
partId | string | Identifier of the reasoning response part to append to |
content | string | Reasoning text chunk |
session/modelChanged 📄
Client-dispatchable. Model changed for this session.
| Field | Type | Description |
|---|---|---|
type | ActionType.SessionModelChanged | |
session | URI | Session URI |
model | ModelSelection | New model selection |
session/isReadChanged 📄
Client-dispatchable. The read state of the session changed.
Dispatched by a client to mark a session as read (e.g. after viewing it) or unread (e.g. after new activity since the client last looked at it).
| Field | Type | Description |
|---|---|---|
type | ActionType.SessionIsReadChanged | |
session | URI | Session URI |
isRead | boolean | Whether the session has been read |
session/isArchivedChanged 📄
Client-dispatchable. The archived state of the session changed.
Dispatched by a client to archive a session (e.g. the task is complete) or to unarchive it.
| Field | Type | Description |
|---|---|---|
type | ActionType.SessionIsArchivedChanged | |
session | URI | Session URI |
isArchived | boolean | Whether the session is archived |
session/activityChanged 📄
The activity description of the session changed.
Dispatched by the server to indicate what the session is currently doing (e.g. running a tool, thinking). Clear activity by setting it to undefined.
| Field | Type | Description |
|---|---|---|
type | ActionType.SessionActivityChanged | |
session | URI | Session URI |
activity | string | undefined | Human-readable description of current activity, or undefined to clear |
Version Introduction
All actions listed above were introduced in protocol version 1.
| Action Type | Version |
|---|---|
root/agentsChanged | 1 |
session/ready | 1 |
session/creationFailed | 1 |
session/turnStarted | 1 |
session/delta | 1 |
session/responsePart | 1 |
session/toolCallStart | 1 |
session/toolCallDelta | 1 |
session/toolCallReady | 1 |
session/toolCallConfirmed (approved) | 1 |
session/toolCallConfirmed (denied) | 1 |
session/toolCallComplete | 1 |
session/toolCallResultConfirmed | 1 |
session/turnComplete | 1 |
session/turnCancelled | 1 |
session/error | 1 |
session/titleChanged | 1 |
session/usage | 1 |
session/reasoning | 1 |
session/modelChanged | 1 |
session/isReadChanged | 1 |
session/isArchivedChanged | 1 |
session/activityChanged | 1 |