Add optional _meta slot to SystemNotificationResponsePart

CHANGELOG.md

@@ -41,6 +41,10 @@ Spec version: `0.5.2`
   optional `title`), so either side of the handshake can identify its
   implementation and build. Informational only — mirrors LSP/MCP and MUST NOT
   be used for feature detection.
+- Optional `_meta` slot on `SystemNotificationResponsePart`, following the MCP
+  `_meta` convention. A host MAY attach a machine-readable descriptor of what
+  triggered the notification so clients can categorize, icon, group, filter, or
+  localize it without parsing `content`.
 
 ### Changed
 

clients/go/CHANGELOG.md

@@ -30,6 +30,9 @@ Implements AHP 0.5.2.
   `Version`, optional `Title`), identifying the implementation and build behind
   either side of the handshake. Informational only — MUST NOT be used for
   feature detection.
+- `SystemNotificationResponsePart.Meta` (wire `_meta`) — optional
+  provider-specific metadata bag (`map[string]json.RawMessage`) carrying a
+  machine-readable descriptor of what triggered the notification.
 
 ### Changed
 

clients/go/ahptypes/state.generated.go

@@ -1643,6 +1643,14 @@ type SystemNotificationResponsePart struct {
 	Kind ResponsePartKind `json:"kind"`
 	// The text of the system notification
 	Content StringOrMarkdown `json:"content"`
+	// Additional provider-specific metadata for this notification.
+	//
+	// A host MAY attach a machine-readable descriptor of what triggered the
+	// notification so clients can categorize, icon, group, filter, or localize
+	// it without parsing `content`. Clients MAY look for well-known keys here to
+	// provide enhanced UI, and MUST render coherently from `content` alone when
+	// `_meta` is absent or unrecognized.
+	Meta map[string]json.RawMessage `json:"_meta,omitempty"`
 }
 
 // Tool execution result details, available after execution completes.

clients/kotlin/CHANGELOG.md

@@ -30,6 +30,9 @@ Implements AHP 0.5.2.
   `InitializeParams`, each an `Implementation` (`name`, optional `version`,
   optional `title`), identifying the implementation and build behind either side
   of the handshake. Informational only — MUST NOT be used for feature detection.
+- `SystemNotificationResponsePart.meta` (serialized as `_meta`) — optional
+  provider-specific metadata bag (`Map<String, JsonElement>?`) carrying a
+  machine-readable descriptor of what triggered the notification.
 
 ### Changed
 

clients/kotlin/src/main/kotlin/com/microsoft/agenthostprotocol/generated/State.generated.kt

@@ -2285,7 +2285,18 @@ data class SystemNotificationResponsePart(
     /**
      * The text of the system notification
      */
-    val content: StringOrMarkdown
+    val content: StringOrMarkdown,
+    /**
+     * Additional provider-specific metadata for this notification.
+     *
+     * A host MAY attach a machine-readable descriptor of what triggered the
+     * notification so clients can categorize, icon, group, filter, or localize
+     * it without parsing `content`. Clients MAY look for well-known keys here to
+     * provide enhanced UI, and MUST render coherently from `content` alone when
+     * `_meta` is absent or unrecognized.
+     */
+    @SerialName("_meta")
+    val meta: Map<String, JsonElement>? = null
 )
 
 @Serializable

clients/rust/CHANGELOG.md

@@ -32,6 +32,9 @@ Implements AHP 0.5.2.
   `version`, optional `title`), identifying the implementation and build behind
   either side of the handshake. Informational only — MUST NOT be used for
   feature detection.
+- `SystemNotificationResponsePart.meta` (`_meta` on the wire) — optional
+  provider-specific metadata bag (`Option<JsonObject>`) carrying a
+  machine-readable descriptor of what triggered the notification.
 
 ### Changed
 

clients/rust/crates/ahp-types/src/state.rs

@@ -2058,6 +2058,15 @@ pub struct ReasoningResponsePart {
 pub struct SystemNotificationResponsePart {
     /// The text of the system notification
     pub content: StringOrMarkdown,
+    /// Additional provider-specific metadata for this notification.
+    ///
+    /// A host MAY attach a machine-readable descriptor of what triggered the
+    /// notification so clients can categorize, icon, group, filter, or localize
+    /// it without parsing `content`. Clients MAY look for well-known keys here to
+    /// provide enhanced UI, and MUST render coherently from `content` alone when
+    /// `_meta` is absent or unrecognized.
+    #[serde(rename = "_meta", default, skip_serializing_if = "Option::is_none")]
+    pub meta: Option<JsonObject>,
 }
 
 /// Tool execution result details, available after execution completes.

clients/swift/AgentHostProtocol/Sources/AgentHostProtocol/Generated/State.generated.swift

@@ -2289,13 +2289,29 @@ public struct SystemNotificationResponsePart: Codable, Sendable {
     public var kind: ResponsePartKind
     /// The text of the system notification
     public var content: StringOrMarkdown
+    /// Additional provider-specific metadata for this notification.
+    ///
+    /// A host MAY attach a machine-readable descriptor of what triggered the
+    /// notification so clients can categorize, icon, group, filter, or localize
+    /// it without parsing `content`. Clients MAY look for well-known keys here to
+    /// provide enhanced UI, and MUST render coherently from `content` alone when
+    /// `_meta` is absent or unrecognized.
+    public var meta: [String: AnyCodable]?
+
+    enum CodingKeys: String, CodingKey {
+        case kind
+        case content
+        case meta = "_meta"
+    }
 
     public init(
         kind: ResponsePartKind,
-        content: StringOrMarkdown
+        content: StringOrMarkdown,
+        meta: [String: AnyCodable]? = nil
     ) {
         self.kind = kind
         self.content = content
+        self.meta = meta
     }
 }
 

clients/swift/CHANGELOG.md

@@ -32,6 +32,9 @@ Implements AHP 0.5.2.
   `InitializeParams`, each an `Implementation` (`name`, optional `version`,
   optional `title`), identifying the implementation and build behind either side
   of the handshake. Informational only — MUST NOT be used for feature detection.
+- `SystemNotificationResponsePart.meta` (serialized as `_meta`) — optional
+  provider-specific metadata bag (`[String: AnyCodable]?`) carrying a
+  machine-readable descriptor of what triggered the notification.
 
 ### Changed
 

clients/typescript/CHANGELOG.md

@@ -35,6 +35,9 @@ Implements AHP 0.5.2.
   `InitializeParams`, each an `Implementation` (`name`, optional `version`,
   optional `title`), identifying the implementation and build behind either side
   of the handshake. Informational only — MUST NOT be used for feature detection.
+- `SystemNotificationResponsePart._meta?: Record<string, unknown>` — optional
+  provider-specific metadata bag carrying a machine-readable descriptor of what
+  triggered the notification, following the existing `_meta` convention.
 
 ### Changed
 

docs/guide/state-model.md

@@ -290,8 +290,18 @@ ContentRef {
   sizeHint?: number
   mimeType?: string
 }
+
+// A system notification surfaced in the response stream — an out-of-band
+// harness event (e.g. "background subagent completed", "task cancelled")
+SystemNotificationResponsePart {
+  kind: 'systemNotification'
+  content: StringOrMarkdown         // human-readable notification text
+  _meta?: Record<string, unknown>   // machine-readable trigger metadata; see below
+}
 ```
 
+`SystemNotificationResponsePart._meta` carries provider-specific metadata describing what triggered the notification. A host MAY attach a machine-readable descriptor so clients can categorize, icon, group, filter, or localize the notification without parsing `content`. Clients MAY inspect well-known keys for enhanced UI, and MUST render coherently from `content` alone when `_meta` is absent or unrecognized.
+
 Text content uses a **create-then-append** pattern: the server first emits a `session/responsePart` action to create a new markdown (or reasoning) part with an `id`, then streams text into it via `session/delta` (or `session/reasoning`) actions targeting that `partId`. This pattern is extensible to future streaming content types.
 
 Clients fetch `ContentRef` content separately via the `resourceRead(uri)` command. This keeps the state tree small and serializable.

schema/actions.schema.json

@@ -5078,6 +5078,11 @@
         "content": {
           "$ref": "#/$defs/StringOrMarkdown",
           "description": "The text of the system notification"
+        },
+        "_meta": {
+          "type": "object",
+          "additionalProperties": {},
+          "description": "Additional provider-specific metadata for this notification.\n\nA host MAY attach a machine-readable descriptor of what triggered the\nnotification so clients can categorize, icon, group, filter, or localize\nit without parsing `content`. Clients MAY look for well-known keys here to\nprovide enhanced UI, and MUST render coherently from `content` alone when\n`_meta` is absent or unrecognized."
         }
       },
       "required": [

schema/commands.schema.json

@@ -4419,6 +4419,11 @@
         "content": {
           "$ref": "#/$defs/StringOrMarkdown",
           "description": "The text of the system notification"
+        },
+        "_meta": {
+          "type": "object",
+          "additionalProperties": {},
+          "description": "Additional provider-specific metadata for this notification.\n\nA host MAY attach a machine-readable descriptor of what triggered the\nnotification so clients can categorize, icon, group, filter, or localize\nit without parsing `content`. Clients MAY look for well-known keys here to\nprovide enhanced UI, and MUST render coherently from `content` alone when\n`_meta` is absent or unrecognized."
         }
       },
       "required": [

schema/errors.schema.json

@@ -3214,6 +3214,11 @@
         "content": {
           "$ref": "#/$defs/StringOrMarkdown",
           "description": "The text of the system notification"
+        },
+        "_meta": {
+          "type": "object",
+          "additionalProperties": {},
+          "description": "Additional provider-specific metadata for this notification.\n\nA host MAY attach a machine-readable descriptor of what triggered the\nnotification so clients can categorize, icon, group, filter, or localize\nit without parsing `content`. Clients MAY look for well-known keys here to\nprovide enhanced UI, and MUST render coherently from `content` alone when\n`_meta` is absent or unrecognized."
         }
       },
       "required": [

schema/notifications.schema.json

@@ -3374,6 +3374,11 @@
         "content": {
           "$ref": "#/$defs/StringOrMarkdown",
           "description": "The text of the system notification"
+        },
+        "_meta": {
+          "type": "object",
+          "additionalProperties": {},
+          "description": "Additional provider-specific metadata for this notification.\n\nA host MAY attach a machine-readable descriptor of what triggered the\nnotification so clients can categorize, icon, group, filter, or localize\nit without parsing `content`. Clients MAY look for well-known keys here to\nprovide enhanced UI, and MUST render coherently from `content` alone when\n`_meta` is absent or unrecognized."
         }
       },
       "required": [

schema/state.schema.json

@@ -3125,6 +3125,11 @@
         "content": {
           "$ref": "#/$defs/StringOrMarkdown",
           "description": "The text of the system notification"
+        },
+        "_meta": {
+          "type": "object",
+          "additionalProperties": {},
+          "description": "Additional provider-specific metadata for this notification.\n\nA host MAY attach a machine-readable descriptor of what triggered the\nnotification so clients can categorize, icon, group, filter, or localize\nit without parsing `content`. Clients MAY look for well-known keys here to\nprovide enhanced UI, and MUST render coherently from `content` alone when\n`_meta` is absent or unrecognized."
         }
       },
       "required": [

types/channels-chat/state.ts

@@ -853,6 +853,16 @@ export interface SystemNotificationResponsePart {
   kind: ResponsePartKind.SystemNotification;
   /** The text of the system notification */
   content: StringOrMarkdown;
+  /**
+   * Additional provider-specific metadata for this notification.
+   *
+   * A host MAY attach a machine-readable descriptor of what triggered the
+   * notification so clients can categorize, icon, group, filter, or localize
+   * it without parsing `content`. Clients MAY look for well-known keys here to
+   * provide enhanced UI, and MUST render coherently from `content` alone when
+   * `_meta` is absent or unrecognized.
+   */
+  _meta?: Record<string, unknown>;
 }