Session Channel

Reference for the ahp-session:/<uuid> channel — per-session state, the turn lifecycle, tool-call state machine, attachments, pending messages, input requests, and per-session customizations. See Session Channel specification for the wire-level overview.

JSON Schema: state.schema.json

State Types

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
userMessage	UserMessage	The message content

SessionLifecycle

Session initialization state.

Member	Value
Creating	'creating'
Ready	'ready'
CreationFailed	'creationFailed'

SessionStatus

Bitset of summary-level session status flags.

Use bitwise checks instead of equality for non-terminal activity. For example, status & SessionStatus.InProgress matches both ordinary in-progress turns and turns that are paused waiting for input.

Member	Value	Description
Idle	1	Session is idle — no turn is active.
Error	1 << 1	Session ended with an error.
InProgress	1 << 3	A turn is actively streaming.
InputNeeded	(1 << 3) | (1 << 4)	A turn is in progress but blocked waiting for user input or tool confirmation.
IsRead	1 << 5	The client has viewed this session since its last modification.
IsArchived	1 << 6	The session has been archived by the client.

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	Customization[]	No	Top-level customizations active in this session. Always container customizations — {@link PluginCustomization} or {@link DirectoryCustomization}. Children (agents, skills, prompts, rules, hooks, MCP servers) live in each container's {@link ContainerCustomizationBase.children | children} array. Client-published plugins arrive via {@link SessionActiveClient.customizations | activeClient.customizations} and the host propagates them into this list (typically with the container's clientId set and children populated).
_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.

SessionActiveClient

The client currently providing tools and interactive capabilities to a session.

Only one client may be active per session at a time. The server SHOULD automatically unset the active client if that client disconnects.

Field	Type	Required	Description
clientId	string	Yes	Client identifier (matches clientId from initialize)
displayName	string	No	Human-readable client name (e.g. "VS Code")
tools	ToolDefinition[]	Yes	Tools this client provides to the session
customizations	ClientPluginCustomization[]	No	Plugin customizations this client contributes to the session. Clients publish in Open Plugins format — i.e. always container-shaped plugins. They MAY synthesize virtual plugins in memory and rely on the host to expand them into concrete children inside {@link SessionState.customizations}.

ProjectInfo

Server-owned project metadata for a session.

Field	Type	Description
uri	URI	Project URI
displayName	string	Human-readable project name

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
agent	AgentSelection	No	Currently selected custom agent. Absent (undefined) means no custom agent is selected for this session — the session uses the provider's default behavior.
workingDirectory	URI	No	The working directory URI for this session
changesets	ChangesetSummary[]	No	Catalogue of changesets the server can produce for this session. Each entry advertises a subscribable view of file changes (uncommitted, session-wide, per-turn, etc.) and the URI template the client expands before subscribing. See {@link ChangesetSummary} for the full shape and {@link /guide/changesets | Changesets} for an overview of the model.

AgentSelection

A selected custom agent for a session.

The uri identifies a specific custom agent (matching an {@link AgentCustomization.uri | AgentCustomization.uri} exposed via the session's effective customizations). Consumers resolve the agent's display name by looking up uri in the session's customization tree.

A session with no agent selected uses the provider's default behavior.

Field	Type	Description
uri	URI	Stable agent URI (matches an {@link AgentCustomization.uri}).

SessionConfigPropertySchema

A session configuration property descriptor.

Extends the generic {@link ConfigPropertySchema} with session-specific display extensions.

Field	Type	Required	Description
enumDynamic	boolean	No	Display extension: when true, the full set of allowed values is too large to enumerate statically. The client SHOULD use sessionConfigCompletions to fetch matching values based on user input. Any values in enum are seed/recent values for initial display.
sessionMutable	boolean	No	When true, the user may change this property after session creation

SessionConfigSchema

A JSON Schema object describing available session configuration metadata.

Field	Type	Required	Description
type	'object'	Yes	JSON Schema: always 'object'
properties	Record<string, SessionConfigPropertySchema>	Yes	JSON Schema: property descriptors keyed by property id
required	string[]	No	JSON Schema: list of required property ids

SessionConfigState

Live session configuration metadata.

The schema describes the available configuration properties and the values contain the current value for each resolved property.

Field	Type	Description
schema	SessionConfigSchema	JSON Schema describing available configuration properties
values	Record<string, unknown>	Current configuration values

SessionInputResponseKind

How a client completed an input request.

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

SessionInputQuestionKind

Question/input control kind.

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

SessionInputOption

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

SessionInputTextQuestion

Text question within a session input request.

Field	Type	Required	Description
kind	SessionInputQuestionKind.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

SessionInputNumberQuestion

Numeric question within a session input request.

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

SessionInputBooleanQuestion

Boolean question within a session input request.

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

SessionInputSingleSelectQuestion

Single-select question within a session input request.

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

SessionInputMultiSelectQuestion

Multi-select question within a session input request.

Field	Type	Required	Description
kind	SessionInputQuestionKind.MultiSelect	Yes
options	SessionInputOption[]	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

SessionInputQuestion

One question within a session input request.

SessionInputTextQuestion | SessionInputNumberQuestion | SessionInputBooleanQuestion | SessionInputSingleSelectQuestion | SessionInputMultiSelectQuestion

SessionInputRequest

A live request for user input.

The server creates or replaces requests with session/inputRequested. Clients sync drafts with session/inputAnswerChanged and complete requests with session/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	SessionInputQuestion[]	No	Ordered questions to ask the user
answers	Record<string, SessionInputAnswer>	No	Current draft or submitted answers, keyed by question ID

SessionInputAnswerValueKind

Answer value kind.

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

SessionInputTextAnswerValue

Value captured for one answer.

Field	Type	Description
kind	SessionInputAnswerValueKind.Text
value	string

SessionInputNumberAnswerValue

Field	Type	Description
kind	SessionInputAnswerValueKind.Number
value	number

SessionInputBooleanAnswerValue

Field	Type	Description
kind	SessionInputAnswerValueKind.Boolean
value	boolean

SessionInputSelectedAnswerValue

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

SessionInputSelectedManyAnswerValue

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

SessionInputAnswerValue

SessionInputTextAnswerValue | SessionInputNumberAnswerValue | SessionInputBooleanAnswerValue | SessionInputSelectedAnswerValue | SessionInputSelectedManyAnswerValue

SessionInputAnswered

Field	Type	Description
state	SessionInputAnswerState.Draft | SessionInputAnswerState.Submitted	Answer state
value	SessionInputAnswerValue	Answer value

SessionInputSkipped

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

SessionInputAnswerState

Answer lifecycle state.

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

SessionInputAnswer

Draft, submitted, or skipped answer for one question.

SessionInputAnswered | SessionInputSkipped

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.

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

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 session/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 session/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.

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

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

ToolDefinition

Describes a tool available in a session, provided by either the server or the active client.

Field	Type	Required	Description
name	string	Yes	Unique tool identifier
title	string	No	Human-readable display name
description	string	No	Description of what the tool does
inputSchema	{ type: 'object'; properties?: Record<string, object>; required?: string[]; }	No	JSON Schema defining the expected input parameters. Optional because client-provided tools may not have formal schemas. Mirrors MCP Tool.inputSchema.
outputSchema	{ type: 'object'; properties?: Record<string, object>; required?: string[]; }	No	JSON Schema defining the structure of the tool's output. Mirrors MCP Tool.outputSchema.
annotations	ToolAnnotations	No	Behavioral hints about the tool. All properties are advisory.
_meta	Record<string, unknown>	No	Additional provider-specific metadata. Mirrors the MCP _meta convention.

ToolAnnotations

Behavioral hints about a tool. All properties are advisory and not guaranteed to faithfully describe tool behavior.

Mirrors MCP ToolAnnotations from the Model Context Protocol specification.

Field	Type	Required	Description
title	string	No	Alternate human-readable title
readOnlyHint	boolean	No	Tool does not modify its environment (default: false)
destructiveHint	boolean	No	Tool may perform destructive updates (default: true)
idempotentHint	boolean	No	Repeated calls with the same arguments have no additional effect (default: false)
openWorldHint	boolean	No	Tool may interact with external entities (default: true)

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

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 subagent sessions (AHP extensions).

ToolResultTextContent | ToolResultEmbeddedResourceContent | ToolResultResourceContent | ToolResultFileEditContent | ToolResultTerminalContent | ToolResultSubagentContent

CustomizationType

Discriminant for the kind of customization.

Top-level entries in {@link SessionState.customizations} and {@link AgentInfo.customizations} are always {@link CustomizationType.Plugin | Plugin} or {@link CustomizationType.Directory | Directory}; the remaining types appear only as children of those containers.

Member	Value
Plugin	'plugin'
Directory	'directory'
Agent	'agent'
Skill	'skill'
Prompt	'prompt'
Rule	'rule'
Hook	'hook'
McpServer	'mcpServer'

ChildCustomizationType

Customization types that appear as children of a {@link PluginCustomization} or {@link DirectoryCustomization}.

CustomizationType.Agent | CustomizationType.Skill | CustomizationType.Prompt | CustomizationType.Rule | CustomizationType.Hook | CustomizationType.McpServer

CustomizationLoadStatus

Discriminant values for {@link CustomizationLoadState}.

Member	Value
Loading	'loading'
Loaded	'loaded'
Degraded	'degraded'
Error	'error'

CustomizationLoadingState

Container is being loaded by the host.

Field	Type	Description
kind	CustomizationLoadStatus.Loading

CustomizationLoadedState

Container loaded successfully.

Field	Type	Description
kind	CustomizationLoadStatus.Loaded

CustomizationDegradedState

Container partially loaded but has warnings.

Field	Type	Description
kind	CustomizationLoadStatus.Degraded
message	string	Human-readable description of the warning.

CustomizationErrorState

Container failed to load.

Field	Type	Description
kind	CustomizationLoadStatus.Error
message	string	Human-readable error message.

CustomizationLoadState

Discriminated load state for a container customization ({@link PluginCustomization} or {@link DirectoryCustomization}).

CustomizationLoadingState | CustomizationLoadedState | CustomizationDegradedState | CustomizationErrorState

PluginCustomization

An Open Plugins plugin.

Field	Type	Description
type	CustomizationType.Plugin

ClientPluginCustomization

A {@link PluginCustomization} as published by a client. Extends the server-facing shape with an opaque nonce so the host can detect when the client's view of a plugin has changed and re-parse only as needed.

Clients SHOULD include a nonce. Server-side fields like {@link ContainerCustomizationBase.children | children} and {@link ContainerCustomizationBase.load | load} are typically left absent on publication and populated by the host when the resolved plugin appears in {@link SessionState.customizations}.

Field	Type	Required	Description
nonce	string	No	Opaque version token used by the host to detect changes.

DirectoryCustomization

A directory the host watches for this session.

Presence in the customization list signals that the host may discover customizations from this directory. When writable is true, clients MAY persist new customizations into the directory using resourceWrite; the host will then surface the resulting child via the customization actions.

The directory may not yet exist on disk.

Field	Type	Description
type	CustomizationType.Directory
contents	ChildCustomizationType	Which child customization type this directory holds.
writable	boolean	Whether clients may write into this directory.

AgentCustomization

A custom agent contributed by a plugin or directory.

Mirrors the Open Plugins agent format: a markdown file with YAML frontmatter, where the body is the agent's system prompt.

Field	Type	Required	Description
type	CustomizationType.Agent	Yes
description	string	No	Short description of what the agent specializes in and when to invoke it. Sourced from the agent file's frontmatter description.

SkillCustomization

A skill contributed by a plugin or directory.

Covers both Open Plugins skill formats — the skills/ directory layout (one subdirectory per skill, each with a SKILL.md) and the flatter commands/ directory of slash-command skills.

Field	Type	Required	Description
type	CustomizationType.Skill	Yes
description	string	No	Short description used for help text and auto-invocation matching. Sourced from the skill's frontmatter description.
disableModelInvocation	boolean	No	When true, only the user can invoke this skill — the agent will not auto-invoke it. Sourced from the command skill's frontmatter disable-model-invocation flag.

PromptCustomization

A prompt contributed by a plugin or directory.

Field	Type	Required	Description
type	CustomizationType.Prompt	Yes
description	string	No	Short description of what the prompt does.

RuleCustomization

A rule contributed by a plugin or directory.

Mirrors the Open Plugins rule format: a markdown file (e.g. .mdc) whose body is injected into context while the rule is active. This type also covers tool-specific "instruction" formats (e.g. VS Code Copilot's .github/instructions/*.md), which differ only in naming — they share the same semantics of description, optional always-on activation, and optional glob scoping.

Field	Type	Required	Description
type	CustomizationType.Rule	Yes
description	string	No	Description of what the rule enforces.
alwaysApply	boolean	No	When true, the rule is always active (subject to globs if any). When false or absent, the agent or user decides whether to apply the rule.
globs	string[]	No	Glob patterns the rule applies to. When present, the rule is only active for matching files.

HookCustomization

A hook manifest contributed by a plugin or directory.

Field	Type	Description
type	CustomizationType.Hook

McpServerCustomization

An MCP manifest contributed by a plugin or directory.

When the server is declared inline in the containing plugin manifest, uri points at the manifest file and {@link CustomizationBase.range | range} narrows it to the declaration's span.

Field	Type	Description
type	CustomizationType.McpServer

ChildCustomization

Child customizations that live inside a {@link PluginCustomization} or {@link DirectoryCustomization}.

AgentCustomization | SkillCustomization | PromptCustomization | RuleCustomization | HookCustomization | McpServerCustomization

Customization

A top-level customization active in a session. Always a container ({@link PluginCustomization} or {@link DirectoryCustomization}); the remaining customization types appear inside the container's {@link ContainerCustomizationBase.children | children} array.

PluginCustomization | DirectoryCustomization

Actions

Mutate SessionState. Scoped to a session URI via the enclosing ActionEnvelope.channel.

JSON Schema: actions.schema.json

session/ready

Session backend initialized successfully.

Field	Type	Description
type	ActionType.SessionReady

session/creationFailed

Session backend failed to initialize.

Field	Type	Description
type	ActionType.SessionCreationFailed
error	ErrorInfo	Error details

session/turnStarted

User sent a message; server starts agent processing.

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

SessionToolCallConfirmedAction

Client confirms or denies a pending tool call.

SessionToolCallApprovedAction | SessionToolCallDeniedAction

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

session/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.SessionToolCallResultConfirmed
approved	boolean	Whether the result was approved

session/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.SessionToolCallContentChanged
content	ToolResultContent[]	The current partial content for the running tool call

session/turnComplete

Turn finished — the assistant is idle.

Field	Type	Description
type	ActionType.SessionTurnComplete
turnId	string	Turn identifier

session/turnCancelled

Turn was aborted; server stops processing.

Field	Type	Description
type	ActionType.SessionTurnCancelled
turnId	string	Turn identifier

session/error

Error during turn processing.

Field	Type	Description
type	ActionType.SessionError
turnId	string	Turn identifier
error	ErrorInfo	Error details

session/titleChanged

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
title	string	New title

session/usage

Token usage report for a turn.

Field	Type	Description
type	ActionType.SessionUsage
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
turnId	string	Turn identifier
partId	string	Identifier of the reasoning response part to append to
content	string	Reasoning text chunk

session/modelChanged

Model changed for this session.

Field	Type	Description
type	ActionType.SessionModelChanged
model	ModelSelection	New model selection

session/agentChanged

Custom agent selection changed for this session.

Omitting agent (or setting it to undefined) clears the selection and resets the session to no selected custom agent (provider default behavior).

When a turn is currently active, the server MUST defer the change until the active turn completes, then apply it for the next turn (same rule as {@link SessionModelChangedAction | session/modelChanged}).

Field	Type	Required	Description
type	ActionType.SessionAgentChanged	Yes
agent	AgentSelection	No	New agent selection, or undefined to clear the selection and reset the session to no selected custom agent.

session/isReadChanged

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
isRead	boolean	Whether the session has been read

session/isArchivedChanged

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
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
activity	string | undefined	Human-readable description of current activity, or undefined to clear

session/changesetsChanged

The {@link ChangesetSummary | catalogue of changesets} the agent host advertises for this session changed. Replaces state.summary.changesets entirely (full-replacement semantics) — set to undefined to clear the catalogue.

Producers dispatch this whenever entries are added, removed, or have their aggregate counts (additions / deletions / files) refreshed. The fan-out happens through this action so observers see catalogue mutations in the same {@link ChangesetAction | per-changeset} action stream they already follow for file-level updates.

Field	Type	Description
type	ActionType.SessionChangesetsChanged
changesets	ChangesetSummary[] | undefined	New catalogue, or undefined to clear it

session/serverToolsChanged

Server tools for this session have changed.

Full-replacement semantics: the tools array replaces the previous serverTools entirely.

Field	Type	Description
type	ActionType.SessionServerToolsChanged
tools	ToolDefinition[]	Updated server tools list (full replacement)

session/activeClientChanged

The active client for this session has changed.

A client dispatches this action with its own SessionActiveClient to claim the active role, or with null to release it. The server SHOULD reject if another client is already active. The server SHOULD automatically dispatch this action with activeClient: null when the active client disconnects.

Field	Type	Description
type	ActionType.SessionActiveClientChanged
activeClient	SessionActiveClient | null	The new active client, or null to unset

session/activeClientToolsChanged

The active client's tool list has changed.

Full-replacement semantics: the tools array replaces the active client's previous tools entirely. The server SHOULD reject if the dispatching client is not the current active client.

Field	Type	Description
type	ActionType.SessionActiveClientToolsChanged
tools	ToolDefinition[]	Updated client tools list (full replacement)

session/customizationsChanged

The session's customizations have changed.

Full-replacement semantics: the customizations array replaces the previous customizations entirely.

Field	Type	Description
type	ActionType.SessionCustomizationsChanged
customizations	Customization[]	Updated customization list (full replacement).

session/customizationToggled

A client toggled a container customization on or off.

Targets a top-level container (plugin or directory) by id. Only containers have an enabled flag; children are always active when their container is enabled. Is a no-op when no matching container is found.

Field	Type	Description
type	ActionType.SessionCustomizationToggled
id	string	The id of the container to toggle.
enabled	boolean	Whether to enable or disable the container.

session/customizationUpdated

Upserts a top-level customization (plugin or directory).

The reducer locates the existing entry by customization.id:

• If found, the entry is replaced entirely with customization, including its children array. To preserve existing children, the host must include them on the payload.
• If not found, the entry is appended.

Field	Type	Description
type	ActionType.SessionCustomizationUpdated
customization	Customization	The customization to upsert (matched by customization.id).

session/customizationRemoved

Removes a customization by id.

Searches every container and its children for the entry. If the entry is a container, its children are removed with it. Is a no-op when no matching id is found.

Field	Type	Description
type	ActionType.SessionCustomizationRemoved
id	string	The id of the customization to remove.

session/configChanged

Client changed a mutable config value mid-session.

Only properties with sessionMutable: true in the config schema may be changed. The server validates and broadcasts the action; the reducer merges the new values into state.config.values.

Field	Type	Required	Description
type	ActionType.SessionConfigChanged	Yes
config	Record<string, unknown>	Yes	Updated config values
replace	boolean	No	When true, replaces all config values instead of merging

session/metaChanged

The session's _meta side-channel changed. Replaces state._meta entirely (full-replacement semantics). Producers SHOULD merge any keys they wish to preserve into the new value before dispatching.

Field	Type	Description
type	ActionType.SessionMetaChanged
_meta	Record<string, unknown> | undefined	New _meta payload, or undefined to clear it

session/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 session status returns to idle.

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

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

session/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 session is idle when a queued message is set, the server SHOULD immediately consume it and start a new turn.

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

session/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.SessionPendingMessageRemoved
kind	PendingMessageKind	Whether this is a steering or queued message
id	string	Identifier of the pending message to remove

session/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.SessionQueuedMessagesReordered
order	string[]	Queued message IDs in the desired order

session/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.SessionInputRequested
request	SessionInputRequest	Input request to create or replace

session/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.SessionInputAnswerChanged	Yes
requestId	string	Yes	Input request identifier
questionId	string	Yes	Question identifier within the input request
answer	SessionInputAnswer	No	Updated answer, or undefined to clear an answer draft

session/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.SessionInputCompleted	Yes
requestId	string	Yes	Input request identifier
response	SessionInputResponseKind	Yes	Completion outcome
answers	Record<string, SessionInputAnswer>	No	Optional final answer replacement, keyed by question ID

Commands

JSON Schema: commands.schema.json

createSession

Property	Value
Direction	Client → Server
Type	Request

Parameters:

Field	Type	Required	Description
channel	URI	Yes	Session URI (client-chosen, e.g. ahp-session:/<uuid>)
provider	string	No	Agent provider ID
model	ModelSelection	No	Model selection (ID and optional model-specific configuration)
agent	AgentSelection	No	Initial custom agent selection for the new session. Omit to start the session with no custom agent selected (provider default).
workingDirectory	URI	No	Working directory for the session
fork	SessionForkSource	No	Fork from an existing session. The new session is populated with content from the source session up to and including the specified turn's response.
config	Record<string, unknown>	No	Agent-specific configuration values collected via resolveSessionConfig. Keys and values correspond to the schema returned by the server.
activeClient	SessionActiveClient	No	Eagerly claim the active client role for the new session. When provided, the server initializes the session with this client as the active client, equivalent to dispatching a session/activeClientChanged action immediately after creation. The clientId MUST match the clientId the creating client supplied in initialize.

Result: null on success.

---

disposeSession

Disposes a session and cleans up server-side resources.

The server broadcasts a root/sessionRemoved notification to all clients.

Property	Value
Direction	Client → Server
Type	Request

Parameters:

No parameters.

Result: null on success.

---

fetchTurns

Fetches historical turns for a session. Used for lazy loading of conversation history.

Property	Value
Direction	Client → Server
Type	Request

Parameters:

Field	Type	Required	Description
channel	URI	Yes	Session URI
before	string	No	Turn ID to fetch before (exclusive). Omit to fetch from the most recent turn.
limit	number	No	Maximum number of turns to return. Server MAY impose its own upper bound.

Result:

Field	Type	Description
turns	Turn[]	The requested turns, ordered oldest-first
hasMore	boolean	Whether more turns exist before the returned range

Example:

// Client → Server (fetch the 20 most recent turns)
{ "jsonrpc": "2.0", "id": 8, "method": "fetchTurns",
  "params": { "channel": "ahp-session:/<uuid>", "limit": 20 } }

// Server → Client
{ "jsonrpc": "2.0", "id": 8, "result": {
  "turns": [ { "id": "t1", ... }, { "id": "t2", ... } ],
  "hasMore": true
}}

// Client → Server (fetch 20 turns before t1)
{ "jsonrpc": "2.0", "id": 9, "method": "fetchTurns",
  "params": { "channel": "ahp-session:/<uuid>", "before": "t1", "limit": 20 } }

---

completions

Requests completion items for a partially-typed input (e.g. a user message the user is currently composing). Used to power @-mention pickers, file/symbol references, and similar inline-completion experiences.

Servers SHOULD treat this command as best-effort and return promptly. The client SHOULD debounce calls to avoid flooding the server with requests on every keystroke.

Property	Value
Direction	Client → Server
Type	Request

Parameters:

Field	Type	Description
kind	CompletionItemKind	What kind of completion is being requested.
channel	URI	The session URI the completion is being requested for.
text	string	The complete text of the input being completed (e.g. the full user message text typed so far).
offset	number	The character offset within text at which the completion is requested, measured in UTF-16 code units. MUST satisfy 0 <= offset <= text.length.

Result:

Field	Type	Description
items	CompletionItem[]	The completion items, in the order the server suggests displaying them.

Example:

// User has typed "look at

---