microsoft/agent-host-protocol spec/v0.4.0

AHP Spec v0.4.0

Repository: microsoft/agent-host-protocol

Tag: spec/v0.4.0

Published: 2026-06-19T18:25:59Z

Prerelease: no

Release notes:

[0.4.0] — 2026-06-19

Spec version: 0.4.0

Added

• MessageOrigin — Message.origin is now a named type (was an inline

{ kind } object), and its MessageKind gains Agent and Tool kinds for turns initiated by the agent or a tool rather than the user (e.g. a tool seeding the first message of a worker chat it spawned), so a host no longer has to misrepresent such a message as User or SystemNotification.

• ConfigPropertySchema.additionalProperties — optional JSON Schema field

(ConfigPropertySchema) describing the schema for object-typed config properties beyond those listed in properties.

• changeset/contentChanged — full-replacement changeset action for sending

batched files, optional operations, and error details on initial snapshots or bulk refreshes.

• ChangesetOperationStatus.Disabled — signals that a changeset operation is

currently unavailable and cannot be invoked, so clients can render the control as disabled rather than hiding it.

• ChangesetOperation.group — optional identifier for grouping related

changeset operations together in the UI.

• _meta slot on the per-turn chat actions (chat/turnStarted, chat/delta,

chat/responsePart, chat/reasoning, chat/usage, chat/turnComplete, chat/turnCancelled, chat/error) — optional provider-specific metadata so agent hosts can carry portable per-event context, such as attributing an event to a specific agent (e.g. a sub-agent acting within the turn). The tool-call actions already exposed _meta; this extends the same convention to the remaining turn-scoped actions.

• annotations/updated (AnnotationsUpdatedAction) — a client-dispatchable

action that partially updates an existing annotation's own properties (turnId, resource, range, resolved) without resending its entries. Resolving or re-anchoring an annotation no longer requires replacing the whole annotation via annotations/set. Omitted fields are left unchanged; the annotation's entries, id, and _meta are never touched.

• ahp-chat: channel for per-chat conversation state; SessionState.chats[] catalog; SessionState.defaultChat? input-routing hint; ChatOrigin provenance union; createChat / disposeChat commands.
• ChatSummary.workingDirectory? — optional per-chat working directory. When absent, chats inherit the session's workingDirectory. Enables agent-swarm patterns where multiple chats in one session operate on independent worktrees.
• ChatInteractivity enum ("full" / "read-only" / "hidden") plus the optional ChatSummary.interactivity / ChatState.interactivity field describing how the user can interact with a chat, supporting agent-team patterns where worker chats are read-only or hidden. Absent defaults to "full".
• Three discrete chat-catalog actions on the session channel — session/chatAdded (upsert by summary.resource), session/chatRemoved, and session/chatUpdated (partial-update with Partial) — mirroring the root-channel root/sessionAdded / root/sessionRemoved / root/sessionSummaryChanged pattern.
• session/defaultChatChanged action — updates SessionState.defaultChat to steer new input to the designated chat; absent value clears the hint.
• ErrorInfo._meta?: Record — optional provider-specific metadata bag on error payloads, mirroring the existing _meta convention on UsageInfo and other protocol types. Clients MAY inspect well-known keys here for richer, localised error UI.
• RootState now carries an optional _meta property bag for

implementation-defined metadata about the agent host itself, mirroring the MCP _meta convention. A well-known hostBuild key may carry build information (version, commit, date) about the program hosting the agent host.

Changed

• ToolResultSubagentContent.resource is now specified as the spawned worker

chat URI (ahp-chat:/), not a session URI — a tool-spawned sub-agent is a chat. Its doc now describes the correspondence with the worker chat's ChatOrigin record (kind: 'tool', matching toolCallId), which remains the canonical representation of the spawn relationship.

• Snapshot.state now accepts ResourceWatchState, so initialize /

reconnect / subscribe can seed an ahp-resource-watch: channel from a point-in-time snapshot. Existing variants (root, session, terminal, changeset, annotations) are unchanged.

• fetchTurns and completions now target an ahp-chat: channel; PROTOCOL_VERSION bumped to 0.4.0.
• ChatState is now flat — the previous summary: ChatSummary sub-object has been replaced by inlined resource / title / status / activity / modifiedAt / model / agent / origin / workingDirectory fields. ChatSummary remains as the standalone catalog entry on SessionState.chats.
• ChatSummary.modifiedAt and ChatState.modifiedAt are now ISO 8601 strings instead of numeric milliseconds.
• SessionSummary now documents how its aggregate fields (status, activity, modifiedAt) are derived from the session's chats, including InputNeeded / Error promotion when any chat raises the flag.

Fixed

• Session reducers now apply _meta updates from every tool-call-scoped

action, not only session/toolCallStart.

Removed

• SessionState.turns, SessionState.activeTurn, SessionState.steeringMessage, SessionState.queuedMessages, SessionState.inputRequests (moved to ChatState).
• session/chatsChanged full-replacement action (replaced by session/chatAdded / session/chatRemoved / session/chatUpdated).