State Types

Complete reference for all state types in the Agent Host Protocol.

JSON Schema: state.schema.json

Root State

RootState 📄

Global state shared with every client subscribed to agenthost:/root.

Field	Type	Required	Description
agents	AgentInfo[]	Yes	Available agent backends and their models
activeSessions	number	No	Number of active (non-disposed) sessions on the server
terminals	TerminalInfo[]	No	Known terminals on the server. Subscribe to individual terminal URIs for full state.
config	RootConfigState	No	Agent host configuration schema and current values

AgentInfo 📄

Field	Type	Required	Description
provider	string	Yes	Agent provider ID (e.g. 'copilot')
displayName	string	Yes	Human-readable name
description	string	Yes	Description string
models	SessionModelInfo[]	Yes	Available models for this agent
protectedResources	ProtectedResourceMetadata[]	No	Protected resources this agent requires authentication for.

Each entry describes an OAuth 2.0 protected resource using RFC 9728 semantics. Clients should obtain tokens from the declared authorization_servers and push them via the authenticate command before creating sessions with this agent. | | customizations | CustomizationRef[] | No | Customizations (Open Plugins) associated with this agent.

Each entry is a reference to an Open Plugins plugin that the agent host can activate for sessions using this agent. |

SessionModelInfo 📄

Field	Type	Required	Description
id	string	Yes	Model identifier
provider	string	Yes	Provider this model belongs to
name	string	Yes	Human-readable model name
maxContextWindow	number	No	Maximum context window size
supportsVision	boolean	No	Whether the model supports vision
policyState	PolicyState	No	Policy configuration state
configSchema	ConfigSchema	No	Configuration schema describing model-specific options (e.g. thinking
level). Clients present this as a form and pass the resolved values in
{@link ModelSelection.config} when creating or changing sessions.
_meta	Record<string, unknown>	No	Additional provider-specific metadata for this model.

Clients MAY look for well-known keys here to provide enhanced UI. For example, a pricing key may carry model pricing metadata. |

Session State

SessionState 📄

Full state for a single session, loaded when a client subscribes to the session's URI.

Field	Type	Required	Description
summary	SessionSummary	Yes	Lightweight session metadata
lifecycle	SessionLifecycle	Yes	Session initialization state
creationError	ErrorInfo	No	Error details if creation failed
serverTools	ToolDefinition[]	No	Tools provided by the server (agent host) for this session
activeClient	SessionActiveClient	No	The client currently providing tools and interactive capabilities to this session
turns	Turn[]	Yes	Completed turns
activeTurn	ActiveTurn	No	Currently in-progress turn
steeringMessage	PendingMessage	No	Message to inject into the current turn at a convenient point
queuedMessages	PendingMessage[]	No	Messages to send automatically as new turns after the current turn finishes
inputRequests	SessionInputRequest[]	No	Requests for user input that are currently blocking or informing session progress
config	SessionConfigState	No	Session configuration schema and current values
customizations	SessionCustomization[]	No	Server-provided customizations active in this session.

Client-provided customizations are available on {@link SessionActiveClient.customizations | activeClient.customizations}. | | _meta | Record<string, unknown> | No | Additional provider-specific metadata for this session.

Clients MAY look for well-known keys here to provide enhanced UI. For example, a git key may provide extra git metadata about the session's workingDirectory. |

SessionSummary 📄

Field	Type	Required	Description
resource	URI	Yes	Session URI
provider	string	Yes	Agent provider ID
title	string	Yes	Session title
status	SessionStatus	Yes	Current session status
activity	string	No	Human-readable description of what the session is currently doing
createdAt	number	Yes	Creation timestamp
modifiedAt	number	Yes	Last modification timestamp
project	ProjectInfo	No	Server-owned project for this session
model	ModelSelection	No	Currently selected model
workingDirectory	URI	No	The working directory URI for this session
diffs	FileEdit[]	No	Files changed during this session with diff statistics

Turn Types

Turn 📄

A completed request/response cycle.

Field	Type	Required	Description
id	string	Yes	Turn identifier
userMessage	UserMessage	Yes	The user's input
responseParts	ResponsePart[]	Yes	All response content in stream order: text, tool calls, reasoning, and content refs.

Consumers should derive display text by concatenating markdown parts, and find tool calls by filtering for ToolCall parts. | | usage | UsageInfo \| undefined | Yes | Token usage info | | state | TurnState | Yes | How the turn ended | | error | ErrorInfo | No | Error details if state is 'error' |

ActiveTurn 📄

An in-progress turn — the assistant is actively streaming.

Field	Type	Description
id	string	Turn identifier
userMessage	UserMessage	The user's input
responseParts	ResponsePart[]	All response content in stream order: text, tool calls, reasoning, and content refs.

Tool call parts include pendingPermissions when permissions are awaiting user approval. | | usage | UsageInfo \| undefined | Token usage info |

UserMessage 📄

A user message and its associated attachments.

Attachments MAY be referenced inside {@link UserMessage.text} via their {@link MessageAttachmentBase.range} field. Attachments without a range are still associated with the message but do not correspond to a specific span in the text.

Field	Type	Required	Description
text	string	Yes	Message text
attachments	MessageAttachment[]	No	File/selection attachments

MessageAttachmentBase 📄

Common fields shared by all {@link MessageAttachment} variants.

Field	Type	Required	Description
label	string	Yes	A human-readable label for the attachment (e.g. the filename of a file
attachment). Used for display in UI.
range	TextRange	No	If defined, the range in {@link UserMessage.text} that references this
attachment. This is a text range, not a byte range.
displayKind	string	No	Advisory display hint for clients rendering this attachment. Recognized
values include:

• 'image': the attachment is an image
• 'document': the attachment is a textual document
• 'symbol': the attachment is a code symbol (e.g. a function or class)
• 'directory': the attachment is a folder
• 'selection': the attachment is a selection within a document

Implementations MAY provide additional values; clients SHOULD fall back to a reasonable default when an unknown value is encountered. | | _meta | Record<string, unknown> | No | Additional implementation-defined metadata for the attachment.

If the attachment was produced by the completions command, the client MUST preserve every property of _meta originally returned by the agent host when sending the user message containing the accepted completion. |

SimpleMessageAttachment 📄

A simple, opaque attachment whose model representation is described by the producer.

Field	Type	Required	Description
type	MessageAttachmentKind.Simple	Yes	Discriminant
modelRepresentation	string	No	Representation of the attachment as it should be shown to the model.

If the attachment was produced by the client, this property MUST be defined so the agent host can correctly interpret the attachment. This property MAY be omitted when the attachment originated from a completions response. |

MessageEmbeddedResourceAttachment 📄

An attachment whose data is embedded inline as a base64 string.

Use this for small binary payloads (e.g. a pasted image) that should be delivered with the user message itself rather than fetched separately.

Field	Type	Required	Description
type	MessageAttachmentKind.EmbeddedResource	Yes	Discriminant
data	string	Yes	Base64-encoded binary data
contentType	string	Yes	Content MIME type (e.g. "image/png", "application/pdf")
selection	TextSelection	No	Optional selection within the attached textual resource.

Only meaningful for textual resources. |

MessageResourceAttachment 📄

An attachment that references a resource by URI. The content is not delivered inline; consumers can fetch it via resourceRead when needed.

Field	Type	Required	Description
type	MessageAttachmentKind.Resource	Yes	Discriminant
selection	TextSelection	No	Optional selection within the referenced textual resource.

Only meaningful for textual resources. |

MessageAttachment 📄

An attachment associated with a {@link UserMessage}.

| SimpleMessageAttachment | MessageEmbeddedResourceAttachment | MessageResourceAttachment

Response Parts

MarkdownResponsePart 📄

Field	Type	Description
kind	ResponsePartKind.Markdown	Discriminant
id	string	Part identifier, used by session/delta to target this part for content appends
content	string	Markdown content

ContentRef 📄

A reference to large content stored outside the state tree.

Field	Type	Required	Description
uri	URI	Yes	Content URI
sizeHint	number	No	Approximate size in bytes
contentType	string	No	Content MIME type

ResponsePart 📄

| MarkdownResponsePart | ResourceReponsePart | ToolCallResponsePart | ReasoningResponsePart | SystemNotificationResponsePart

Tool Call Types

ToolCallState 📄

Discriminated union of all tool call lifecycle states.

See the state model guide for the full state machine diagram.

| ToolCallStreamingState | ToolCallPendingConfirmationState | ToolCallRunningState | ToolCallPendingResultConfirmationState | ToolCallCompletedState | ToolCallCancelledState

ToolCallResult 📄

Tool execution result details, available after execution completes.

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 |

ToolCallStreamingState 📄

LM is streaming the tool call parameters.

Field	Type	Required	Description
status	ToolCallStatus.Streaming	Yes
partialInput	string	No	Partial parameters accumulated so far
invocationMessage	StringOrMarkdown	No	Progress message shown while parameters are streaming

ToolCallPendingConfirmationState 📄

Parameters are complete, or a running tool requires re-confirmation (e.g. a mid-execution permission check).

Field	Type	Required	Description
status	ToolCallStatus.PendingConfirmation	Yes
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
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.

ToolCallRunningState 📄

Tool is actively executing.

Field	Type	Required	Description
status	ToolCallStatus.Running	Yes
confirmed	ToolCallConfirmationReason	Yes	How the tool was confirmed for execution
selectedOption	ConfirmationOption	No	The confirmation option the user selected, if confirmation options were provided
content	ToolResultContent[]	No	Partial content produced while the tool is still executing.

For example, a terminal content block lets clients subscribe to live output before the tool completes. |

ToolCallPendingResultConfirmationState 📄

Tool finished executing, waiting for client to approve the result.

Field	Type	Required	Description
status	ToolCallStatus.PendingResultConfirmation	Yes
confirmed	ToolCallConfirmationReason	Yes	How the tool was confirmed for execution
selectedOption	ConfirmationOption	No	The confirmation option the user selected, if confirmation options were provided

ToolCallCompletedState 📄

Tool completed successfully or with an error.

Field	Type	Required	Description
status	ToolCallStatus.Completed	Yes
confirmed	ToolCallConfirmationReason	Yes	How the tool was confirmed for execution
selectedOption	ConfirmationOption	No	The confirmation option the user selected, if confirmation options were provided

ToolCallCancelledState 📄

Tool call was cancelled before execution.

Field	Type	Required	Description
status	ToolCallStatus.Cancelled	Yes
reason	ToolCallCancellationReason	Yes	Why the tool was cancelled
reasonMessage	StringOrMarkdown	No	Optional message explaining the cancellation
userSuggestion	UserMessage	No	What the user suggested doing instead
selectedOption	ConfirmationOption	No	The confirmation option the user selected, if confirmation options were provided

ToolResultSubagentContent 📄

A reference to a subagent session spawned by a tool.

Clients can subscribe to the subagent's session URI to stream its progress in real time, including inner tool calls and responses.

Field	Type	Required	Description
type	ToolResultContentType.Subagent	Yes
resource	URI	Yes	Subagent session URI (subscribable for full session state)
title	string	Yes	Display title for the subagent
agentName	string	No	Internal agent name
description	string	No	Human-readable description of the subagent's task

Common Types

UsageInfo 📄

Field	Type	Required	Description
inputTokens	number	No	Input tokens consumed
outputTokens	number	No	Output tokens generated
model	string	No	Model used
cacheReadTokens	number	No	Tokens read from cache
_meta	Record<string, unknown>	No	Additional provider-specific metadata for this usage report.
Clients MAY look for well-known optional keys here to provide enhanced UI.

ErrorInfo 📄

Field	Type	Required	Description
errorType	string	Yes	Error type identifier
message	string	Yes	Human-readable error message
stack	string	No	Stack trace

Snapshot 📄

A point-in-time snapshot of a subscribed resource's state, returned by initialize, reconnect, and subscribe.

Field	Type	Description
resource	URI	The subscribed resource URI (e.g. agenthost:/root or copilot:/<uuid>)
state	RootState | SessionState | TerminalState	The current state of the resource
fromSeq	number	The serverSeq at which this snapshot was taken. Subsequent actions will have serverSeq > fromSeq.