feat(unstable): Add a category to session config options (#366)

This is to allow clients to better distinguish between different types
of options, for example to have a keyboard shortcut or special placement
for the first of a given category.

Co-authored-by: neel <neel@chot.ai>

Author: benbrandt

docs/protocol/draft/schema.mdx

@@ -3032,6 +3032,37 @@ Single-value selector (dropdown).
 </Expandable>
 </ResponseField>
 
+## <span class="font-mono">SessionConfigOptionCategory</span>
+
+**UNSTABLE**
+
+This capability is not part of the spec yet, and may be removed or changed at any point.
+
+Semantic category for a session configuration option.
+
+This is intended to help Clients distinguish broadly common selectors (e.g. model selector vs
+session mode selector vs thought/reasoning level) for UX purposes (keyboard shortcuts, icons,
+placement). It MUST NOT be required for correctness. Clients MUST handle missing or unknown
+categories gracefully (treat as `Other`).
+
+**Type:** Union
+
+<ResponseField name="mode" type="string">
+  Session mode selector.
+</ResponseField>
+
+<ResponseField name="model" type="string">
+  Model selector.
+</ResponseField>
+
+<ResponseField name="thought_level" type="string">
+  Thought/reasoning level selector.
+</ResponseField>
+
+<ResponseField name="other" type="string">
+  Unknown / uncategorized selector.
+</ResponseField>
+
 ## <span class="font-mono">SessionConfigSelect</span>
 
 **UNSTABLE**

docs/rfds/session-config-options.mdx

@@ -28,6 +28,8 @@ Since this space is moving fast, we ideally would find a more flexible option wi
 
 Instead, we can allow Agents to provide configuration options in the `session/new` response that not only provide a list of options, but also a `key` of some kind that is a unique identifier for that selector.
 
+Additionally, we can optionally allow an Agent to mark each option with a semantic category so that Clients can reliably distinguish broadly common option types (e.g. model selector vs session mode selector vs thought/reasoning level), without needing to infer meaning from the option `id` or `name`. This is intended for UX only (e.g. keyboard shortcuts, icons, preferred placement), and MUST NOT be required for correctness.
+
 When the Client receives or sends an update to this selector, it would require both the selector key and the key for the new value.
 
 To start, we could continue offering single-value selectors (dropdowns), but allow for the Agent to decide what those are for.
@@ -61,6 +63,7 @@ Something like an `InitializeResponse` that looks like:
         "id": "mode", // this is the unique `key` for communication about which option is being used
         "name": "Session Mode", // Human-readable label for the option
         "description": "Optional description for the Client to display to the user."
+        "category": "mode",
         "type": "select",
         "currentValue": "ask",
         "options": [
@@ -79,6 +82,7 @@ Something like an `InitializeResponse` that looks like:
       {
         "id": "models",
         "name": "Model",
+        "category": "model",
         "type": "select",
         "currentValue": "ask",
         "options": [
@@ -99,6 +103,21 @@ Something like an `InitializeResponse` that looks like:
 }
 ```
 
+### Option category (optional)
+
+Each top-level config option MAY include an optional `category` field. This is intended to help Clients distinguish broadly common selectors and provide a consistent UX (for example, attaching keyboard shortcuts to the first option of a given category).
+
+In addition to `category`, Clients SHOULD use the ordering of the `configOptions` array as provided by the Agent as the primary way to establish priority and resolve ties. For example, if multiple options share the same `category`, a Client can prefer the first matching option in the list when assigning keyboard shortcuts or deciding which options to surface most prominently.
+
+`category` is semantic metadata and MUST NOT be required for correctness. Clients MUST handle missing or unknown categories gracefully (treat as `other`).
+
+Proposed enum:
+
+- `mode` - Session mode selector
+- `model` - Model selector
+- `thought_level` - Thought/reasoning level selector
+- `other` - Unknown / uncategorized selector
+
 When we introduce this, we could also allow for grouped options, in case there are logical sub-headers and groupings for the options in an individual selector.
 
 ```json

schema/schema.unstable.json

@@ -2508,6 +2508,17 @@
           "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
           "type": ["object", "null"]
         },
+        "category": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/SessionConfigOptionCategory"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Optional semantic category for this option (UX only)."
+        },
         "description": {
           "description": "Optional description for the Client to display to the user.",
           "type": ["string", "null"]
@@ -2528,6 +2539,31 @@
       "required": ["id", "name"],
       "type": "object"
     },
+    "SessionConfigOptionCategory": {
+      "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nSemantic category for a session configuration option.\n\nThis is intended to help Clients distinguish broadly common selectors (e.g. model selector vs\nsession mode selector vs thought/reasoning level) for UX purposes (keyboard shortcuts, icons,\nplacement). It MUST NOT be required for correctness. Clients MUST handle missing or unknown\ncategories gracefully (treat as `Other`).",
+      "oneOf": [
+        {
+          "const": "mode",
+          "description": "Session mode selector.",
+          "type": "string"
+        },
+        {
+          "const": "model",
+          "description": "Model selector.",
+          "type": "string"
+        },
+        {
+          "const": "thought_level",
+          "description": "Thought/reasoning level selector.",
+          "type": "string"
+        },
+        {
+          "const": "other",
+          "description": "Unknown / uncategorized selector.",
+          "type": "string"
+        }
+      ]
+    },
     "SessionConfigSelect": {
       "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA single-value selector (dropdown) session configuration option payload.",
       "properties": {

src/agent.rs

@@ -1557,6 +1557,32 @@ impl SessionConfigSelect {
     }
 }
 
+/// **UNSTABLE**
+///
+/// This capability is not part of the spec yet, and may be removed or changed at any point.
+///
+/// Semantic category for a session configuration option.
+///
+/// This is intended to help Clients distinguish broadly common selectors (e.g. model selector vs
+/// session mode selector vs thought/reasoning level) for UX purposes (keyboard shortcuts, icons,
+/// placement). It MUST NOT be required for correctness. Clients MUST handle missing or unknown
+/// categories gracefully (treat as `Other`).
+#[cfg(feature = "unstable_session_config_options")]
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+#[non_exhaustive]
+pub enum SessionConfigOptionCategory {
+    /// Session mode selector.
+    Mode,
+    /// Model selector.
+    Model,
+    /// Thought/reasoning level selector.
+    ThoughtLevel,
+    /// Unknown / uncategorized selector.
+    #[serde(other)]
+    Other,
+}
+
 /// **UNSTABLE**
 ///
 /// This capability is not part of the spec yet, and may be removed or changed at any point.
@@ -1589,6 +1615,9 @@ pub struct SessionConfigOption {
     /// Optional description for the Client to display to the user.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub description: Option<String>,
+    /// Optional semantic category for this option (UX only).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub category: Option<SessionConfigOptionCategory>,
     /// Type-specific fields for this configuration option.
     #[serde(flatten)]
     pub kind: SessionConfigKind,
@@ -1613,6 +1642,7 @@ impl SessionConfigOption {
             id: id.into(),
             name: name.into(),
             description: None,
+            category: None,
             kind,
             meta: None,
         }
@@ -1638,6 +1668,12 @@ impl SessionConfigOption {
         self
     }
 
+    #[must_use]
+    pub fn category(mut self, category: impl IntoOption<SessionConfigOptionCategory>) -> Self {
+        self.category = category.into_option();
+        self
+    }
+
     /// The _meta property is reserved by ACP to allow clients and agents to attach additional
     /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
     /// these keys.