spec/v0.4.0

## [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<ChatSummary>`) — 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<string, unknown>` — 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:/<cid>`), 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`).