ExperimentalThe opaque session ID identifying the child in all ACP messages.
OptionaltitleThe parent's human-readable display title for this child. It need not be unique.
Optional and nullable. Omitted means unchanged; null clears it. If no
title is set, the Client chooses a fallback presentation.
OptionaldescriptionThe parent's human-readable description of the child's role or purpose.
Optional and nullable. Omitted means unchanged; null clears it. This is
current display metadata, not the history of instructions sent to the child.
OptionalcapabilitiesClient-initiated session mutations permitted for this subagent session.
Read-only operations retain their normal protocol semantics and capability requirements.
OptionalstateThe child's current foreground state, mirrored onto its parent association.
Optional and nullable. Omitted means unchanged; null removes the
current report and leaves activity unconfirmed (not idle or cancelled).
A concrete [StateUpdate] replaces the entire previous snapshot.
Optional_The _meta property is reserved by ACP to allow clients and agents to attach additional
metadata to their interactions. Omitted leaves the stored metadata unchanged; null
clears it. An object patches the stored metadata by top-level key: keys it omits are
unchanged, a key set to null is removed, and any other value replaces that key's
stored value without merging nested objects. Beyond this patch rule, implementations
MUST NOT make assumptions about values at these keys.
See protocol docs: Metadata Patches
UNSTABLE
This capability is not part of the spec yet, and may be removed or changed at any point.
Notification that the enclosing parent session created and owns a child session.
Later updates modify the existing association's metadata, not its ownership.
Sent on the immediate parent session. The first update for an unknown [
SubagentUpdate::session_id] announces the child and MUST be sent before any live request or notification bearing the child's session ID, including messages naming it as sender or recipient. Child events are delivered automatically; no separate child load, resume, or subscription is needed. Understanding this update, registering child sessions, and applying their operation restrictions are baseline v2 requirements; no Client capability is required.Only [
SubagentUpdate::session_id] is required. Other fields have patch semantics: omitted fields leave the stored value unchanged,nullclears or unsets the value, and concrete values replace it. A concrete_metaobject instead patches the stored metadata by top-level key. Forstate,nullremoves the current state report and leaves activity unconfirmed; it does not report idle or cancellation. A child whose capabilities are unset permits no Client-initiated session mutations.The title and description provide the parent's display metadata for the child. Agents SHOULD mirror known child state changes in the parent's [
SubagentUpdate::state] using the same [StateUpdate] snapshot as the ordinarystate_updatenotification on the child session. This reports child state, not a separate parent-owned lifecycle. Consumers should treat duplicate reports idempotently. Completing or cancelling work does not end the association: the parent may message the same child again. Individual messages and their outcomes do not change this association.