Add optional _meta slot to SystemNotificationResponsePart

clients/go/ahptypes/state.generated.go

@@ -1645,6 +1645,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"`
 }
 
 // A resolved input request (elicitation) recorded in the turn transcript.

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

@@ -2289,7 +2289,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/crates/ahp-types/src/state.rs

@@ -2062,6 +2062,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>,
 }
 
 /// A resolved input request (elicitation) recorded in the turn transcript.

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

@@ -2291,13 +2291,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
     }
 }
 

docs/.changes/20260709-system-notification-meta-slot.json

@@ -0,0 +1,5 @@
+{
+  "type": "added",
+  "message": "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`.",
+  "issues": [308]
+}

docs/guide/state-model.md

@@ -324,6 +324,7 @@ ContentRef {
 SystemNotificationResponsePart {
   kind: 'systemNotification'
   content: StringOrMarkdown
+  _meta?: Record<string, unknown>   // machine-readable trigger metadata; see below
 }
 
 // Durable record of a resolved input request (see Input Requests below)
@@ -334,6 +335,8 @@ InputRequestResponsePart {
 }
 ```
 
+`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 `chat/responsePart` action to create a new markdown (or reasoning) part with an `id`, then streams text into it via `chat/delta` (or `chat/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

@@ -5221,6 +5221,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

@@ -4509,6 +4509,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

@@ -3300,6 +3300,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

@@ -3460,6 +3460,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

@@ -3211,6 +3211,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

@@ -884,6 +884,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>;
 }