feat: Add unstable model config category (#1455)

Author: benbrandt

Cargo.toml

@@ -38,6 +38,7 @@ unstable = [
     "unstable_session_fork",
     "unstable_end_turn_token_usage",
     "unstable_boolean_config",
+    "unstable_model_config_category",
 ]
 # Protocol v2 is intentionally NOT part of the `unstable` umbrella.
 # It introduces a parallel `v2` module and (eventually) a different wire
@@ -54,6 +55,7 @@ unstable_plan_operations = []
 unstable_session_fork = []
 unstable_end_turn_token_usage = []
 unstable_boolean_config = []
+unstable_model_config_category = []
 
 # Emit `tracing::warn!` events when `VecSkipError` drops a malformed list
 # entry during deserialization. When disabled (the default), the inspector

docs/protocol/v1/draft/schema.mdx

@@ -7075,6 +7075,15 @@ Category names that do not begin with `_` are reserved for the ACP spec.
   Model selector.
 </ResponseField>
 
+<ResponseField name="model_config" type="string">
+**UNSTABLE**
+
+This capability is not part of the spec yet, and may be removed or changed at any point.
+
+Model-related configuration parameter.
+
+</ResponseField>
+
 <ResponseField name="thought_level" type="string">
   Thought/reasoning level selector.
 </ResponseField>

docs/protocol/v1/draft/session-config-options.mdx

@@ -3,7 +3,7 @@ title: "Session Config Options"
 description: "Flexible configuration selectors for agent sessions"
 ---
 
-Agents can provide an arbitrary list of configuration options for a session, allowing Clients to offer users customizable selectors for things like models, modes, reasoning levels, and more.
+Agents can provide an arbitrary list of configuration options for a session, allowing Clients to offer users customizable selectors for things like models, model parameters, modes, reasoning levels, and more.
 
 <Info>
   Session Config Options are the preferred way to expose session-level
@@ -61,6 +61,23 @@ During [Session Setup](/protocol/v1/draft/session-setup) the Agent **MAY** retur
             "description": "The most powerful model"
           }
         ]
+      },
+      {
+        "id": "context_size",
+        "name": "Context Size",
+        "category": "model_config",
+        "type": "select",
+        "currentValue": "200k",
+        "options": [
+          {
+            "value": "200k",
+            "name": "200K"
+          },
+          {
+            "value": "1m",
+            "name": "1M"
+          }
+        ]
       }
     ]
   }
@@ -129,11 +146,14 @@ Each config option **MAY** include a `category` field. Categories are semantic m
 
 Category names beginning with `_` are free for custom use (e.g., `_my_custom_category`). Category names that do not begin with `_` are reserved for the ACP spec.
 
-| Category        | Description                      |
-| --------------- | -------------------------------- |
-| `mode`          | Session mode selector            |
-| `model`         | Model selector                   |
-| `thought_level` | Thought/reasoning level selector |
+| Category        | Description                                                              |
+| --------------- | ------------------------------------------------------------------------ |
+| `mode`          | Session mode selector                                                    |
+| `model`         | Model selector                                                           |
+| `model_config`  | Model-related parameter, such as context size or speed/quality trade-off |
+| `thought_level` | Thought/reasoning level selector                                         |
+
+Clients **SHOULD** render `model_config` options near the `model` selector, such as in the same popover or panel. No capability negotiation is required for category values.
 
 When multiple options share the same category, Clients **SHOULD** use the array ordering to resolve ties, preferring earlier options in the list for prominent placement or keyboard shortcuts.
 

docs/protocol/v2/draft/schema.mdx

@@ -6912,6 +6912,15 @@ Category names that do not begin with `_` are reserved for the ACP spec.
   Model selector.
 </ResponseField>
 
+<ResponseField name="model_config" type="string">
+**UNSTABLE**
+
+This capability is not part of the spec yet, and may be removed or changed at any point.
+
+Model-related configuration parameter.
+
+</ResponseField>
+
 <ResponseField name="thought_level" type="string">
   Thought/reasoning level selector.
 </ResponseField>

docs/protocol/v2/draft/session-config-options.mdx

@@ -3,7 +3,7 @@ title: "Session Config Options"
 description: "Flexible configuration selectors for agent sessions"
 ---
 
-Agents can provide an arbitrary list of configuration options for a session, allowing Clients to offer users customizable selectors for things like modes, models, reasoning levels, and more.
+Agents can provide an arbitrary list of configuration options for a session, allowing Clients to offer users customizable selectors for things like modes, models, model parameters, reasoning levels, and more.
 
 ## Initial State
 
@@ -54,6 +54,23 @@ During [Session Setup](/protocol/v2/draft/session-setup) the Agent **MAY** retur
             "description": "The most powerful model"
           }
         ]
+      },
+      {
+        "id": "context_size",
+        "name": "Context Size",
+        "category": "model_config",
+        "type": "select",
+        "currentValue": "200k",
+        "options": [
+          {
+            "value": "200k",
+            "name": "200K"
+          },
+          {
+            "value": "1m",
+            "name": "1M"
+          }
+        ]
       }
     ]
   }
@@ -122,11 +139,14 @@ Each config option **MAY** include a `category` field. Categories are semantic m
 
 Category names beginning with `_` are free for custom use (e.g., `_my_custom_category`). Category names that do not begin with `_` are reserved for the ACP spec.
 
-| Category        | Description                      |
-| --------------- | -------------------------------- |
-| `mode`          | Session mode selector            |
-| `model`         | Model selector                   |
-| `thought_level` | Thought/reasoning level selector |
+| Category        | Description                                                              |
+| --------------- | ------------------------------------------------------------------------ |
+| `mode`          | Session mode selector                                                    |
+| `model`         | Model selector                                                           |
+| `model_config`  | Model-related parameter, such as context size or speed/quality trade-off |
+| `thought_level` | Thought/reasoning level selector                                         |
+
+Clients **SHOULD** render `model_config` options near the `model` selector, such as in the same popover or panel. No capability negotiation is required for category values.
 
 When multiple options share the same category, Clients **SHOULD** use the array ordering to resolve ties, preferring earlier options in the list for prominent placement or keyboard shortcuts.
 

schema/v1/schema.unstable.json

@@ -3696,6 +3696,11 @@
           "type": "string",
           "const": "model"
         },
+        {
+          "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nModel-related configuration parameter.",
+          "type": "string",
+          "const": "model_config"
+        },
         {
           "description": "Thought/reasoning level selector.",
           "type": "string",

schema/v2/schema.unstable.json

@@ -4057,6 +4057,11 @@
           "type": "string",
           "const": "model"
         },
+        {
+          "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nModel-related configuration parameter.",
+          "type": "string",
+          "const": "model_config"
+        },
         {
           "description": "Thought/reasoning level selector.",
           "type": "string",

src/v1/agent.rs

@@ -2298,6 +2298,13 @@ pub enum SessionConfigOptionCategory {
     Mode,
     /// Model selector.
     Model,
+    /// **UNSTABLE**
+    ///
+    /// This capability is not part of the spec yet, and may be removed or changed at any point.
+    ///
+    /// Model-related configuration parameter.
+    #[cfg(feature = "unstable_model_config_category")]
+    ModelConfig,
     /// Thought/reasoning level selector.
     ThoughtLevel,
     /// Unknown / uncategorized selector.
@@ -5248,6 +5255,11 @@ mod test_serialization {
             serde_json::to_value(&SessionConfigOptionCategory::Model).unwrap(),
             json!("model")
         );
+        #[cfg(feature = "unstable_model_config_category")]
+        assert_eq!(
+            serde_json::to_value(&SessionConfigOptionCategory::ModelConfig).unwrap(),
+            json!("model_config")
+        );
         assert_eq!(
             serde_json::to_value(&SessionConfigOptionCategory::ThoughtLevel).unwrap(),
             json!("thought_level")
@@ -5262,6 +5274,11 @@ mod test_serialization {
             serde_json::from_str::<SessionConfigOptionCategory>("\"model\"").unwrap(),
             SessionConfigOptionCategory::Model
         );
+        #[cfg(feature = "unstable_model_config_category")]
+        assert_eq!(
+            serde_json::from_str::<SessionConfigOptionCategory>("\"model_config\"").unwrap(),
+            SessionConfigOptionCategory::ModelConfig
+        );
         assert_eq!(
             serde_json::from_str::<SessionConfigOptionCategory>("\"thought_level\"").unwrap(),
             SessionConfigOptionCategory::ThoughtLevel
@@ -5283,6 +5300,17 @@ mod test_serialization {
         assert_eq!(json, json!("some_future_category"));
     }
 
+    #[cfg(not(feature = "unstable_model_config_category"))]
+    #[test]
+    fn test_session_config_option_model_config_is_unknown_without_feature() {
+        let unknown: SessionConfigOptionCategory =
+            serde_json::from_str("\"model_config\"").unwrap();
+        assert_eq!(
+            unknown,
+            SessionConfigOptionCategory::Other("model_config".to_string())
+        );
+    }
+
     #[test]
     fn test_session_config_option_category_custom_categories() {
         // Category names beginning with `_` are free for custom use

src/v2/agent.rs

@@ -2188,6 +2188,13 @@ pub enum SessionConfigOptionCategory {
     Mode,
     /// Model selector.
     Model,
+    /// **UNSTABLE**
+    ///
+    /// This capability is not part of the spec yet, and may be removed or changed at any point.
+    ///
+    /// Model-related configuration parameter.
+    #[cfg(feature = "unstable_model_config_category")]
+    ModelConfig,
     /// Thought/reasoning level selector.
     ThoughtLevel,
     /// Custom or future category.
@@ -5490,6 +5497,11 @@ mod test_serialization {
             serde_json::to_value(&SessionConfigOptionCategory::Model).unwrap(),
             json!("model")
         );
+        #[cfg(feature = "unstable_model_config_category")]
+        assert_eq!(
+            serde_json::to_value(&SessionConfigOptionCategory::ModelConfig).unwrap(),
+            json!("model_config")
+        );
         assert_eq!(
             serde_json::to_value(&SessionConfigOptionCategory::ThoughtLevel).unwrap(),
             json!("thought_level")
@@ -5504,6 +5516,11 @@ mod test_serialization {
             serde_json::from_str::<SessionConfigOptionCategory>("\"model\"").unwrap(),
             SessionConfigOptionCategory::Model
         );
+        #[cfg(feature = "unstable_model_config_category")]
+        assert_eq!(
+            serde_json::from_str::<SessionConfigOptionCategory>("\"model_config\"").unwrap(),
+            SessionConfigOptionCategory::ModelConfig
+        );
         assert_eq!(
             serde_json::from_str::<SessionConfigOptionCategory>("\"thought_level\"").unwrap(),
             SessionConfigOptionCategory::ThoughtLevel
@@ -5525,6 +5542,17 @@ mod test_serialization {
         assert_eq!(json, json!("some_future_category"));
     }
 
+    #[cfg(not(feature = "unstable_model_config_category"))]
+    #[test]
+    fn test_session_config_option_model_config_is_unknown_without_feature() {
+        let unknown: SessionConfigOptionCategory =
+            serde_json::from_str("\"model_config\"").unwrap();
+        assert_eq!(
+            unknown,
+            SessionConfigOptionCategory::Other("model_config".to_string())
+        );
+    }
+
     #[test]
     fn test_session_config_option_category_custom_categories() {
         // Category names beginning with `_` are free for custom use

src/v2/conversion.rs

@@ -3875,6 +3875,8 @@ impl IntoV1 for super::SessionConfigOptionCategory {
         Ok(match self {
             Self::Mode => crate::v1::SessionConfigOptionCategory::Mode,
             Self::Model => crate::v1::SessionConfigOptionCategory::Model,
+            #[cfg(feature = "unstable_model_config_category")]
+            Self::ModelConfig => crate::v1::SessionConfigOptionCategory::ModelConfig,
             Self::ThoughtLevel => crate::v1::SessionConfigOptionCategory::ThoughtLevel,
             Self::Other(value) => crate::v1::SessionConfigOptionCategory::Other(value.into_v1()?),
         })
@@ -3888,6 +3890,8 @@ impl IntoV2 for crate::v1::SessionConfigOptionCategory {
         Ok(match self {
             Self::Mode => super::SessionConfigOptionCategory::Mode,
             Self::Model => super::SessionConfigOptionCategory::Model,
+            #[cfg(feature = "unstable_model_config_category")]
+            Self::ModelConfig => super::SessionConfigOptionCategory::ModelConfig,
             Self::ThoughtLevel => super::SessionConfigOptionCategory::ThoughtLevel,
             Self::Other(value) => super::SessionConfigOptionCategory::Other(value.into_v2()?),
         })
@@ -9009,6 +9013,35 @@ mod tests {
         assert_eq!(error.message(), expected);
     }
 
+    #[test]
+    fn round_trips_session_config_option_categories() {
+        for category in [
+            v1::SessionConfigOptionCategory::Mode,
+            v1::SessionConfigOptionCategory::Model,
+            #[cfg(feature = "unstable_model_config_category")]
+            v1::SessionConfigOptionCategory::ModelConfig,
+            v1::SessionConfigOptionCategory::ThoughtLevel,
+            v1::SessionConfigOptionCategory::Other("_custom_category".to_string()),
+        ] {
+            assert_v1_round_trip::<v1::SessionConfigOptionCategory, v2::SessionConfigOptionCategory>(
+                category,
+            );
+        }
+
+        for category in [
+            v2::SessionConfigOptionCategory::Mode,
+            v2::SessionConfigOptionCategory::Model,
+            #[cfg(feature = "unstable_model_config_category")]
+            v2::SessionConfigOptionCategory::ModelConfig,
+            v2::SessionConfigOptionCategory::ThoughtLevel,
+            v2::SessionConfigOptionCategory::Other("_custom_category".to_string()),
+        ] {
+            assert_v2_round_trip::<v2::SessionConfigOptionCategory, v1::SessionConfigOptionCategory>(
+                category,
+            );
+        }
+    }
+
     #[test]
     fn converts_v2_initialize_request_to_v1_without_serde() {
         let request = v2::InitializeRequest::new(ProtocolVersion::V2);