Chat Channel

Reference for the ahp-chat:/<uuid> channel — per-chat state, the turn lifecycle, tool-call state machine, attachments, pending messages, and input requests. A chat belongs to a session (see Session Channel); a session may contain multiple chats. See Chat Channel specification for the wire-level overview.

JSON Schema: state.schema.json

State Types

ChatState

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

The lightweight catalog representation of a chat is {@link ChatSummary}, carried in {@link SessionState.chats | SessionState.chats}. ChatStatedenormalizes every {@link ChatSummary} field directly onto itself so subscribers receive one flat object instead of having to merge a nested summary sub-object. Producers MUST keep the two representations consistent: any change to the inlined fields below SHOULD also be announced on the parent session via the matching {@link SessionChatUpdatedAction | session/chatUpdated} action.

Field	Type	Required	Description
resource	URI	Yes	Chat URI
title	string	Yes	Chat title
status	SessionStatus	Yes	Current chat status (reuses SessionStatus shape)
activity	string	No	Human-readable description of what the chat is currently doing
modifiedAt	string	Yes	Last modification timestamp (ISO 8601, e.g. "2025-03-10T18:42:03.123Z")
model	ModelSelection	No	Optional per-chat model override (defaults to the session's model)
agent	AgentSelection	No	Optional per-chat agent override (defaults to the session's agent)
origin	ChatOrigin	No	How this chat came into existence
interactivity	ChatInteractivity	No	How the user can interact with this chat. See {@link ChatInteractivity}. Supports agent-team patterns where worker chats are read-only or hidden. Absence defaults to {@link ChatInteractivity.Full} for backward compatibility.
workingDirectory	URI	No	Optional per-chat working directory. If absent, the chat inherits {@link SessionSummary.workingDirectory | the session's working directory}. Hosts MAY override this for individual chats — for example, to give a subordinate chat its own git worktree so multiple chats in a session can make independent edits that the orchestrator later merges back.
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	ChatInputRequest[]	No	Requests for user input that are currently blocking or informing chat progress
_meta	Record<string, unknown>	No	Additional provider-specific metadata for this chat.

ChatSummary

Lightweight catalog entry for a chat, carried in {@link SessionState.chats | SessionState.chats}. The full conversation lives in {@link ChatState}, which inlines (denormalizes) every field below.

Field	Type	Required	Description
resource	URI	Yes	Chat URI
title	string	Yes	Chat title
status	SessionStatus	Yes	Current chat status (reuses SessionStatus shape)
activity	string	No	Human-readable description of what the chat is currently doing
modifiedAt	string	Yes	Last modification timestamp (ISO 8601, e.g. "2025-03-10T18:42:03.123Z")
model	ModelSelection	No	Optional per-chat model override (defaults to the session's model)
agent	AgentSelection	No	Optional per-chat agent override (defaults to the session's agent)
origin	ChatOrigin	No	How this chat came into existence
interactivity	ChatInteractivity	No	How the user can interact with this chat. See {@link ChatInteractivity}. Supports agent-team patterns where worker chats are read-only or hidden. Absence defaults to {@link ChatInteractivity.Full} for backward compatibility.
workingDirectory	URI	No	Optional per-chat working directory. If absent, the chat inherits {@link SessionSummary.workingDirectory | the session's working directory}. See {@link ChatState.workingDirectory} for usage notes.

ChatOriginKind

Discriminant for {@link ChatOrigin} — how a chat came into existence.

Member	Value	Description
User	'user'	User created the chat explicitly (e.g. via the host UI).
Fork	'fork'	Forked from an existing chat at a specific turn.
Tool	'tool'	Spawned by a tool call running in another chat (e.g. a sub-agent delegation).

ChatOrigin

How a chat came into existence. Clients MAY use it to render contextual UI (parent indicators, fork markers, "spawned by tool" badges).

The tool variant records a tool-spawned worker from the worker's side: its chat/toolCallId identify the spawning tool call in the parent chat. This is the canonical record of the spawn relationship. The same edge is surfaced from the parent's side by {@link ToolResultSubagentContent}, whose resource is this chat's URI; hosts MUST keep the two consistent.

{ kind: ChatOriginKind.User } | { kind: ChatOriginKind.Fork; chat: URI; turnId: string } | { kind: ChatOriginKind.Tool; chat: URI; toolCallId: string }

ChatInteractivity

How a user can interact with a chat.

• Full — user can send messages and watch (default when absent)
• ReadOnly — user can watch but not send messages (e.g. agent team workers)
• Hidden — internal worker not shown in UI at all

Supports the agent-team pattern where a lead chat is fully interactive and worker chats are read-only (visible for observability) or hidden (internal implementation detail). The harness sets this based on the chat's role; the UI uses it to show appropriate controls.

Member	Value	Description
Full	'full'	User can send messages and watch (default when absent)
ReadOnly	'read-only'	User can watch but not send messages
Hidden	'hidden'	Internal worker not shown in UI at all

PendingMessageKind

Discriminant for pending message kinds.

Member	Value	Description
Steering	'steering'	Injected into the current turn at a convenient point
Queued	'queued'	Sent automatically as a new turn after the current turn finishes

PendingMessage

A message queued for future delivery to the agent.

Steering messages are injected into the current turn mid-flight. Queued messages are automatically started as new turns after the current turn naturally finishes.

Field	Type	Description
id	string	Unique identifier for this pending message
message	Message	The message that will start the next turn

ChatInputResponseKind

How a client completed an input request.

Member	Value
Accept	'accept'
Decline	'decline'
Cancel	'cancel'

ChatInputQuestionKind

Question/input control kind.

Member	Value
Text	'text'
Number	'number'
Integer	'integer'
Boolean	'boolean'
SingleSelect	'single-select'
MultiSelect	'multi-select'

ChatInputOption

A choice in a select-style question.

Field	Type	Required	Description
id	string	Yes	Stable option identifier; for MCP enum values this is the enum string
label	string	Yes	Display label
description	string	No	Optional secondary text
recommended	boolean	No	Whether this option is the recommended/default choice

ChatInputTextQuestion

Text question within a chat input request.

Field	Type	Required	Description
kind	ChatInputQuestionKind.Text	Yes
format	string	No	Format hint for text questions, such as email, uri, date, or date-time
min	number	No	Minimum string length
max	number	No	Maximum string length
defaultValue	string	No	Default text

ChatInputNumberQuestion

Numeric question within a chat input request.

Field	Type	Required	Description
kind	ChatInputQuestionKind.Number | ChatInputQuestionKind.Integer	Yes
min	number	No	Minimum value
max	number	No	Maximum value
defaultValue	number	No	Default numeric value

ChatInputBooleanQuestion

Boolean question within a chat input request.

Field	Type	Required	Description
kind	ChatInputQuestionKind.Boolean	Yes
defaultValue	boolean	No	Default boolean value

ChatInputSingleSelectQuestion

Single-select question within a chat input request.

Field	Type	Required	Description
kind	ChatInputQuestionKind.SingleSelect	Yes
options	ChatInputOption[]	Yes	Options the user may select from
allowFreeformInput	boolean	No	Whether the user may enter text instead of selecting an option

ChatInputMultiSelectQuestion

Multi-select question within a chat input request.

Field	Type	Required	Description
kind	ChatInputQuestionKind.MultiSelect	Yes
options	ChatInputOption[]	Yes	Options the user may select from
allowFreeformInput	boolean	No	Whether the user may enter text in addition to selecting options
min	number	No	Minimum selected item count
max	number	No	Maximum selected item count

ChatInputQuestion

One question within a chat input request.

ChatInputTextQuestion | ChatInputNumberQuestion | ChatInputBooleanQuestion | ChatInputSingleSelectQuestion | ChatInputMultiSelectQuestion

ChatInputRequest

A live request for user input.

The server creates or replaces requests with chat/inputRequested. Clients sync drafts with chat/inputAnswerChanged and complete requests with chat/inputCompleted.

Field	Type	Required	Description
id	string	Yes	Stable request identifier
message	string	No	Display message for the request as a whole
url	URI	No	URL the user should review or open, for URL-style elicitations
questions	ChatInputQuestion[]	No	Ordered questions to ask the user
answers	Record<string, ChatInputAnswer>	No	Current draft or submitted answers, keyed by question ID

ChatInputAnswerValueKind

Answer value kind.

Member	Value
Text	'text'
Number	'number'
Boolean	'boolean'
Selected	'selected'
SelectedMany	'selected-many'

ChatInputTextAnswerValue

Value captured for one answer.

Field	Type	Description
kind	ChatInputAnswerValueKind.Text
value	string

ChatInputNumberAnswerValue

Field	Type	Description
kind	ChatInputAnswerValueKind.Number
value	number

ChatInputBooleanAnswerValue

Field	Type	Description
kind	ChatInputAnswerValueKind.Boolean
value	boolean

ChatInputSelectedAnswerValue

Field	Type	Required	Description
kind	ChatInputAnswerValueKind.Selected	Yes
value	string	Yes
freeformValues	string[]	No	Free-form text entered instead of selecting an option

ChatInputSelectedManyAnswerValue

Field	Type	Required	Description
kind	ChatInputAnswerValueKind.SelectedMany	Yes
value	string[]	Yes
freeformValues	string[]	No	Free-form text entered in addition to selected options

ChatInputAnswerValue

ChatInputTextAnswerValue | ChatInputNumberAnswerValue | ChatInputBooleanAnswerValue | ChatInputSelectedAnswerValue | ChatInputSelectedManyAnswerValue

ChatInputAnswered

Field	Type	Description
state	ChatInputAnswerState.Draft | ChatInputAnswerState.Submitted	Answer state
value	ChatInputAnswerValue	Answer value

ChatInputSkipped

Field	Type	Required	Description
state	ChatInputAnswerState.Skipped	Yes	Answer state
freeformValues	string[]	No	Free-form reason or value captured while skipping, if any

ChatInputAnswerState

Answer lifecycle state.

Member	Value
Draft	'draft'
Submitted	'submitted'
Skipped	'skipped'

ChatInputAnswer

Draft, submitted, or skipped answer for one question.

ChatInputAnswered | ChatInputSkipped

TurnState

How a turn ended.

Member	Value
Complete	'complete'
Cancelled	'cancelled'
Error	'error'

MessageAttachmentKind

Discriminant for {@link MessageAttachment} variants.

Member	Value	Description
Simple	'simple'	A simple, opaque attachment whose representation is described by the producer.
EmbeddedResource	'embeddedResource'	An attachment whose data is embedded inline as a base64 string.
Resource	'resource'	An attachment that references a resource by URI.
Annotations	'annotations'	An attachment that references annotations on an annotations channel.

Turn

A completed request/response cycle.

Field	Type	Required	Description
id	string	Yes	Turn identifier
message	Message	Yes	The message that initiated the turn
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
message	Message	The message that initiated the turn
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

MessageKind

Discriminant for {@link MessageOrigin} — identifies who produced a message.

Member	Value	Description
User	'user'	Sent directly by the user.
Agent	'agent'	Produced by the agent itself rather than the user — for example, an agent that seeds the first message of a chat it spawned.
Tool	'tool'	Produced by a tool rather than the user — for example, a tool that spawns a worker chat whose first message carries a seed prompt.
SystemNotification	'systemNotification'	A system-generated notification rather than a direct user message.

MessageOrigin

Identifies the origin of a {@link Message} — who produced it. For the message that initiates a turn ({@link Turn.message}), this is also the origin of the turn; for steering or queued messages it is just the origin of that message.

Field	Type	Description
kind	MessageKind	The kind of actor that produced the message.

Message

A message that initiates or steers a turn. Messages can originate from the user, the agent, a tool, or be system-generated (see {@link MessageOrigin}).

Attachments MAY be referenced inside {@link Message.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
origin	MessageOrigin	Yes	The origin of the message
attachments	MessageAttachment[]	No	File/selection attachments
_meta	Record<string, unknown>	No	Additional provider-specific metadata for this message. Clients MAY look for well-known keys here to provide enhanced UI, and agent hosts MAY use it to carry context that does not fit any other field. Mirrors the MCP _meta convention.

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 Message.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.

MessageAnnotationsAttachment

An attachment that references annotations on a session's annotations channel (see {@link AnnotationsState}).

When {@link annotationIds} is omitted the attachment references every annotation on the channel; when present it references only the listed {@link Annotation.id | annotation ids}.

Field	Type	Required	Description
type	MessageAttachmentKind.Annotations	Yes	Discriminant
resource	URI	Yes	The annotations channel URI (typically ahp-session:/<uuid>/annotations). Matches {@link AnnotationsSummary.resource}.
annotationIds	string[]	No	Specific {@link Annotation.id | annotation ids} to reference. When omitted, the attachment references all annotations on the channel.

MessageAttachment

An attachment associated with a {@link Message}.

SimpleMessageAttachment | MessageEmbeddedResourceAttachment | MessageResourceAttachment | MessageAnnotationsAttachment

ResponsePartKind

Discriminant for response part types.

Member	Value
Markdown	'markdown'
ContentRef	'contentRef'
ToolCall	'toolCall'
Reasoning	'reasoning'
SystemNotification	'systemNotification'

MarkdownResponsePart

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

ResourceReponsePart

A content part that's a reference to large content stored outside the state tree.

Field	Type	Description
kind	ResponsePartKind.ContentRef	Discriminant

ToolCallResponsePart

A tool call represented as a response part.

Tool calls are part of the response stream, interleaved with text and reasoning. The toolCall.toolCallId serves as the part identifier for actions that target this part.

Field	Type	Description
kind	ResponsePartKind.ToolCall	Discriminant
toolCall	ToolCallState	Full tool call lifecycle state

ReasoningResponsePart

Reasoning/thinking content from the model.

Field	Type	Description
kind	ResponsePartKind.Reasoning	Discriminant
id	string	Part identifier, used by chat/reasoning to target this part for content appends
content	string	Accumulated reasoning text

ResponsePart

MarkdownResponsePart | ResourceReponsePart | ToolCallResponsePart | ReasoningResponsePart | SystemNotificationResponsePart

SystemNotificationResponsePart

A system notification surfaced as part of the response stream.

System notifications are messages authored by the agent harness that need to be visible to both the agent (for situational awareness) and the user (for transcript continuity). Examples include "background subagent X completed" or "task Y was cancelled".

Field	Type	Description
kind	ResponsePartKind.SystemNotification	Discriminant
content	StringOrMarkdown	The text of the system notification

ToolCallStatus

Status of a tool call in the lifecycle state machine.

Member	Value
Streaming	'streaming'
PendingConfirmation	'pending-confirmation'
Running	'running'
PendingResultConfirmation	'pending-result-confirmation'
Completed	'completed'
Cancelled	'cancelled'

ToolCallConfirmationReason

How a tool call was confirmed for execution.

• NotNeeded — No confirmation required (auto-approved)
• UserAction — User explicitly approved
• Setting — Approved by a persistent user setting

Member	Value
NotNeeded	'not-needed'
UserAction	'user-action'
Setting	'setting'

ToolCallCancellationReason

Why a tool call was cancelled.

Member	Value
Denied	'denied'
Skipped	'skipped'
ResultDenied	'result-denied'

ConfirmationOptionKind

Whether a confirmation option represents an approval or denial action.

Member	Value
Approve	'approve'
Deny	'deny'

ConfirmationOption

A confirmation option that the server offers for a tool call awaiting approval. Allows richer choices beyond simple approve/deny — for example, "Approve in this Session" or "Deny with reason."

Field	Type	Required	Description
id	string	Yes	Unique identifier for the option, returned in the confirmed action
label	string	Yes	Human-readable label displayed to the user
kind	ConfirmationOptionKind	Yes	Whether this option represents an approval or denial
group	number	No	Logical group number for visual categorisation. Clients SHOULD display options in the order they are defined and MAY use differing group numbers to insert dividers between logical clusters of options.

ToolCallContributorKind

Member	Value
Client	'client'
MCP	'mcp'

ToolCallClientContributor

Field	Type	Description
kind	ToolCallContributorKind.Client
clientId	string	If this tool is provided by a client, the clientId of the owning client. Absent for server-side tools. When set, the identified client is responsible for executing the tool and dispatching chat/toolCallComplete with the result.

ToolCallMcpContributor

Field	Type	Description
kind	ToolCallContributorKind.MCP
customizationId	string	Customization ID of the corresponding MCP server in {@link SessionState.customizations}.

ToolCallContributor

ToolCallClientContributor | ToolCallMcpContributor

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	Message	No	What the user suggested doing instead
selectedOption	ConfirmationOption	No	The confirmation option the user selected, if confirmation options were provided

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

ToolResultContentType

Discriminant for tool result content types.

Member	Value
Text	'text'
EmbeddedResource	'embeddedResource'
Resource	'resource'
FileEdit	'fileEdit'
Terminal	'terminal'
Subagent	'subagent'

ToolResultTextContent

Text content in a tool result.

Mirrors MCP TextContent.

Field	Type	Description
type	ToolResultContentType.Text
text	string	The text content

ToolResultEmbeddedResourceContent

Base64-encoded binary content embedded in a tool result.

Mirrors MCP EmbeddedResource for inline binary data.

Field	Type	Description
type	ToolResultContentType.EmbeddedResource
data	string	Base64-encoded data
contentType	string	Content type (e.g. "image/png", "application/pdf")

ToolResultResourceContent

A reference to a resource stored outside the tool result.

Wraps {@link ContentRef} for lazy-loading large results.

Field	Type	Description
type	ToolResultContentType.Resource

ToolResultFileEditContent

Describes a file modification performed by a tool.

Field	Type	Description
type	ToolResultContentType.FileEdit

ToolResultTerminalContent

A reference to a terminal whose output is relevant to this tool result.

Clients can subscribe to the terminal's URI to stream its output in real time, providing live feedback while a tool is executing.

Field	Type	Description
type	ToolResultContentType.Terminal
resource	URI	Terminal URI (subscribable for full terminal state)
title	string	Display title for the terminal content

ToolResultSubagentContent

A reference, embedded in a tool result, to a worker chat spawned by the tool call (a sub-agent delegation), referenced by a chat URI (ahp-chat:/...).

This is the spawning tool call's forward view of the worker. The worker chat records the same edge in reverse via its {@link ChatOrigin} (kind: 'tool'), whose toolCallId identifies the tool call that emitted this content.

Field	Type	Required	Description
type	ToolResultContentType.Subagent	Yes
resource	URI	Yes	Worker chat URI (subscribable for full chat 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

ToolResultContent

Content block in a tool result.

Mirrors the content blocks in MCP CallToolResult.content, plus ToolResultResourceContent for lazy-loading large results, ToolResultFileEditContent for file edit diffs, ToolResultTerminalContent for live terminal output, and ToolResultSubagentContent for tool-spawned worker chats (AHP extensions).

ToolResultTextContent | ToolResultEmbeddedResourceContent | ToolResultResourceContent | ToolResultFileEditContent | ToolResultTerminalContent | ToolResultSubagentContent

Actions

Mutate ChatState. Scoped to a chat URI via the enclosing ActionEnvelope.channel.

JSON Schema: actions.schema.json

chat/turnStarted

A new message has been sent to the agent, and a new turn starts.

A client is only allowed to send {@link MessageKind.User} messages.

Field	Type	Required	Description
type	ActionType.ChatTurnStarted	Yes
turnId	string	Yes	Turn identifier
message	Message	Yes	The new message
queuedMessageId	string	No	If this turn was auto-started from a queued message, the ID of that message
_meta	Record<string, unknown>	No	Additional provider-specific metadata for this action. Clients MAY look for well-known keys here to provide enhanced UI, and agent hosts MAY use it to carry per-event context that does not fit any other field — for example, attributing the event to a specific agent (such as a sub-agent acting within the turn). Mirrors the MCP _meta convention.

chat/delta

Streaming text chunk from the assistant, appended to a specific response part.

The server MUST first emit a chat/responsePart to create the target part (markdown or reasoning), then use this action to append text to it.

Field	Type	Required	Description
type	ActionType.ChatDelta	Yes
turnId	string	Yes	Turn identifier
partId	string	Yes	Identifier of the response part to append to
content	string	Yes	Text chunk
_meta	Record<string, unknown>	No	Additional provider-specific metadata for this action. Clients MAY look for well-known keys here to provide enhanced UI, and agent hosts MAY use it to carry per-event context that does not fit any other field — for example, attributing the event to a specific agent (such as a sub-agent acting within the turn). Mirrors the MCP _meta convention.

chat/responsePart

Structured content appended to the response.

Field	Type	Required	Description
type	ActionType.ChatResponsePart	Yes
turnId	string	Yes	Turn identifier
part	ResponsePart	Yes	Response part (markdown or content ref)
_meta	Record<string, unknown>	No	Additional provider-specific metadata for this action. Clients MAY look for well-known keys here to provide enhanced UI, and agent hosts MAY use it to carry per-event context that does not fit any other field — for example, attributing the event to a specific agent (such as a sub-agent acting within the turn). Mirrors the MCP _meta convention.

chat/toolCallStart

A tool call begins — parameters are streaming from the LM.

The server sets {@link ToolCallContributor | contributor} to identify the origin of the tool. For client-provided tools, the named client is responsible for executing the tool once it reaches the running state and dispatching chat/toolCallComplete. For MCP-served tools, the server executes the call against the named McpServerCustomization.

Field	Type	Required	Description
type	ActionType.ChatToolCallStart	Yes
toolName	string	Yes	Internal tool name (for debugging/logging)
displayName	string	Yes	Human-readable tool name
contributor	ToolCallContributor	No	Reference to the contributor of the tool being called. Absent for server-side tools that are not contributed by a client or MCP server.

chat/toolCallDelta

Streaming partial parameters for a tool call.

Field	Type	Required	Description
type	ActionType.ChatToolCallDelta	Yes
content	string	Yes	Partial parameter content to append
invocationMessage	StringOrMarkdown	No	Updated progress message

chat/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 chat/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.ChatToolCallReady	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.

chat/toolCallConfirmed (approved)

Client approves a pending tool call. The tool transitions to running.

Field	Type	Required	Description
type	ActionType.ChatToolCallConfirmed	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

chat/toolCallConfirmed (denied)

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.ChatToolCallConfirmed	Yes
approved	false	Yes	The tool call was denied
reason	ToolCallCancellationReason.Denied | ToolCallCancellationReason.Skipped	Yes	Why the tool was cancelled
userSuggestion	Message	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

ChatToolCallConfirmedAction

Client confirms or denies a pending tool call.

ChatToolCallApprovedAction | ChatToolCallDeniedAction

chat/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.ChatToolCallComplete	Yes
result	ToolCallResult	Yes	Execution result
requiresResultConfirmation	boolean	No	If true, the result requires client approval before finalizing

chat/toolCallResultConfirmed

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.ChatToolCallResultConfirmed
approved	boolean	Whether the result was approved

chat/toolCallContentChanged

Partial content produced while a tool is still executing.

Replaces the content array on the running tool call state. Clients can use this to display live feedback (e.g. a terminal reference) before the tool completes.

For client-provided tools (where toolClientId is set on the tool call state), the owning client dispatches this action to stream intermediate content while executing. The server SHOULD reject this action if the dispatching client does not match toolClientId.

Field	Type	Description
type	ActionType.ChatToolCallContentChanged
content	ToolResultContent[]	The current partial content for the running tool call

chat/turnComplete

Turn finished — the assistant is idle.

Field	Type	Required	Description
type	ActionType.ChatTurnComplete	Yes
turnId	string	Yes	Turn identifier
_meta	Record<string, unknown>	No	Additional provider-specific metadata for this action. Clients MAY look for well-known keys here to provide enhanced UI, and agent hosts MAY use it to carry per-event context that does not fit any other field — for example, attributing the event to a specific agent (such as a sub-agent acting within the turn). Mirrors the MCP _meta convention.

chat/turnCancelled

Turn was aborted; server stops processing.

Field	Type	Required	Description
type	ActionType.ChatTurnCancelled	Yes
turnId	string	Yes	Turn identifier
_meta	Record<string, unknown>	No	Additional provider-specific metadata for this action. Clients MAY look for well-known keys here to provide enhanced UI, and agent hosts MAY use it to carry per-event context that does not fit any other field — for example, attributing the event to a specific agent (such as a sub-agent acting within the turn). Mirrors the MCP _meta convention.

chat/error

Error during turn processing.

Field	Type	Required	Description
type	ActionType.ChatError	Yes
turnId	string	Yes	Turn identifier
error	ErrorInfo	Yes	Error details
_meta	Record<string, unknown>	No	Additional provider-specific metadata for this action. Clients MAY look for well-known keys here to provide enhanced UI, and agent hosts MAY use it to carry per-event context that does not fit any other field — for example, attributing the event to a specific agent (such as a sub-agent acting within the turn). Mirrors the MCP _meta convention.

chat/usage

Token usage report for a turn.

Field	Type	Required	Description
type	ActionType.ChatUsage	Yes
turnId	string	Yes	Turn identifier
usage	UsageInfo	Yes	Token usage data
_meta	Record<string, unknown>	No	Additional provider-specific metadata for this action. Clients MAY look for well-known keys here to provide enhanced UI, and agent hosts MAY use it to carry per-event context that does not fit any other field — for example, attributing the event to a specific agent (such as a sub-agent acting within the turn). Mirrors the MCP _meta convention.

chat/reasoning

Reasoning/thinking text from the model, appended to a specific reasoning response part.

The server MUST first emit a chat/responsePart to create the target reasoning part, then use this action to append text to it.

Field	Type	Required	Description
type	ActionType.ChatReasoning	Yes
turnId	string	Yes	Turn identifier
partId	string	Yes	Identifier of the reasoning response part to append to
content	string	Yes	Reasoning text chunk
_meta	Record<string, unknown>	No	Additional provider-specific metadata for this action. Clients MAY look for well-known keys here to provide enhanced UI, and agent hosts MAY use it to carry per-event context that does not fit any other field — for example, attributing the event to a specific agent (such as a sub-agent acting within the turn). Mirrors the MCP _meta convention.

chat/truncated

Truncates a session's history. If turnId is provided, all turns after that turn are removed and the specified turn is kept. If turnId is omitted, all turns are removed.

If there is an active turn it is silently dropped and the chat status returns to idle.

Common use-case: truncate old data then dispatch a new chat/turnStarted with an edited message.

Field	Type	Required	Description
type	ActionType.ChatTruncated	Yes
turnId	string	No	Keep turns up to and including this turn. Omit to clear all turns.

chat/pendingMessageSet

A pending message was set (upsert semantics: creates or replaces).

For steering messages, this always replaces the single steering message. For queued messages, if a message with the given id already exists it is updated in place; otherwise it is appended to the queue. If the chat is idle when a queued message is set, the server SHOULD immediately consume it and start a new turn.

A client is only allowed to send {@link MessageKind.User} messages.

Field	Type	Description
type	ActionType.ChatPendingMessageSet
kind	PendingMessageKind	Whether this is a steering or queued message
id	string	Unique identifier for this pending message
message	Message	The message content

chat/pendingMessageRemoved

A pending message was removed (steering or queued).

Dispatched by clients to cancel a pending message, or by the server when it consumes a message (e.g. starting a turn from a queued message or injecting a steering message into the current turn).

Field	Type	Description
type	ActionType.ChatPendingMessageRemoved
kind	PendingMessageKind	Whether this is a steering or queued message
id	string	Identifier of the pending message to remove

chat/queuedMessagesReordered

Reorder the queued messages.

The order array contains the IDs of queued messages in their new desired order. IDs not present in the current queue are ignored. Queued messages whose IDs are absent from order are appended at the end in their original relative order (so a client with a stale view of the queue never silently drops messages).

Field	Type	Description
type	ActionType.ChatQueuedMessagesReordered
order	string[]	Queued message IDs in the desired order

chat/inputRequested

A session requested input from the user.

Full-request upsert semantics: the request replaces any existing request with the same id, or is appended if it is new. Answer drafts are preserved unless request.answers is provided.

Field	Type	Description
type	ActionType.ChatInputRequested
request	ChatInputRequest	Input request to create or replace

chat/inputAnswerChanged

A client updated, submitted, skipped, or removed a single in-progress answer.

Dispatching with answer: undefined removes that question's answer draft.

Field	Type	Required	Description
type	ActionType.ChatInputAnswerChanged	Yes
requestId	string	Yes	Input request identifier
questionId	string	Yes	Question identifier within the input request
answer	ChatInputAnswer	No	Updated answer, or undefined to clear an answer draft

chat/inputCompleted

A client accepted, declined, or cancelled a session input request.

If accepted, the server uses answers (when provided) plus the request's synced answer state to resume the blocked operation.

Field	Type	Required	Description
type	ActionType.ChatInputCompleted	Yes
requestId	string	Yes	Input request identifier
response	ChatInputResponseKind	Yes	Completion outcome
answers	Record<string, ChatInputAnswer>	No	Optional final answer replacement, keyed by question ID

ChatAction

ChatTurnStartedAction | ChatDeltaAction | ChatResponsePartAction | ChatToolCallStartAction | ChatToolCallDeltaAction | ChatToolCallReadyAction | ChatToolCallConfirmedAction | ChatToolCallCompleteAction | ChatToolCallResultConfirmedAction | ChatToolCallContentChangedAction | ChatTurnCompleteAction | ChatTurnCancelledAction | ChatErrorAction | ChatUsageAction | ChatReasoningAction | ChatTruncatedAction | ChatPendingMessageSetAction | ChatPendingMessageRemovedAction | ChatQueuedMessagesReorderedAction | ChatInputRequestedAction | ChatInputAnswerChangedAction | ChatInputCompletedAction

Commands

JSON Schema: commands.schema.json

createChat

Creates a new chat within a session.

Property	Value
Direction	Client → Server
Type	Request

Parameters:

Field	Type	Required	Description
channel	URI	Yes	Session URI containing the new chat.
chat	URI	Yes	Chat URI (client-chosen, e.g. ahp-chat:/<uuid>).
initialMessage	Message	No	Optional initial message for the new chat.
model	ModelSelection	No	Optional per-chat model override.
agent	AgentSelection	No	Optional per-chat agent override.
source	ChatForkSource	No	Optional source chat and turn to fork from.

Result: null on success.

---

disposeChat

Disposes a chat and cleans up server-side resources.

Property	Value
Direction	Client → Server
Type	Request

Parameters:

No parameters.

Result: null on success.

---