docs(rfd): Session Config Options to Preview stage (#378)

benbrandt · web-flow · commit 539d15929890 · 2026-01-15T11:42:01.000+01:00
* docs(rfd): Session Config Options to Preview stage

With several implementations in place, it feels like this is ready for preview.
I added this in Zed + Codex ACP, and the JetBrains folks have this in their Kotlin SDK. So let's move this to preview stage for final feedback!

* Allow for custom categories
diff --git a/docs/docs.json b/docs/docs.json
@@ -80,6 +80,7 @@
                 "hidden": true,
                 "pages": [
                   "protocol/draft/cancellation",
+                  "protocol/draft/session-config-options",
                   "protocol/draft/schema"
                 ]
               }
@@ -105,7 +106,6 @@
             "group": "Draft",
             "pages": [
               "rfds/session-list",
-              "rfds/session-config-options",
               "rfds/session-fork",
               "rfds/request-cancellation",
               "rfds/session-resume",
@@ -119,7 +119,7 @@
               "rfds/auth-methods"
             ]
           },
-          { "group": "Preview", "pages": [] },
+          { "group": "Preview", "pages": ["rfds/session-config-options"] },
           { "group": "Completed", "pages": ["rfds/introduce-rfd-process"] }
         ]
       },
diff --git a/docs/protocol/draft/schema.mdx b/docs/protocol/draft/schema.mdx
@@ -3043,7 +3043,10 @@ 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`).
+categories gracefully.
+
+Category names beginning with `_` are free for custom use, like other ACP extension methods.
+Category names that do not begin with `_` are reserved for the ACP spec.
 
 **Type:** Union
 
@@ -3059,7 +3062,7 @@ categories gracefully (treat as `Other`).
   Thought/reasoning level selector.
 </ResponseField>
 
-<ResponseField name="other" type="string">
+<ResponseField name="string" type="string">
   Unknown / uncategorized selector.
 </ResponseField>
 
diff --git a/docs/protocol/draft/session-config-options.mdx b/docs/protocol/draft/session-config-options.mdx
@@ -0,0 +1,281 @@
+---
+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.
+
+<Info>
+  Session Config Options are the preferred way to expose session-level
+  configuration. If an Agent provides `configOptions`, Clients **SHOULD** use
+  them instead of the deprecated [`modes`](../session-modes) field.
+</Info>
+
+## Initial State
+
+During [Session Setup](../session-setup) the Agent **MAY** return a list of configuration options and their current values:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "sessionId": "sess_abc123def456",
+    "configOptions": [
+      {
+        "id": "mode",
+        "name": "Session Mode",
+        "description": "Controls how the agent requests permission",
+        "category": "mode",
+        "type": "select",
+        "currentValue": "ask",
+        "options": [
+          {
+            "value": "ask",
+            "name": "Ask",
+            "description": "Request permission before making any changes"
+          },
+          {
+            "value": "code",
+            "name": "Code",
+            "description": "Write and modify code with full tool access"
+          }
+        ]
+      },
+      {
+        "id": "model",
+        "name": "Model",
+        "category": "model",
+        "type": "select",
+        "currentValue": "model-1",
+        "options": [
+          {
+            "value": "model-1",
+            "name": "Model 1",
+            "description": "The fastest model"
+          },
+          {
+            "value": "model-2",
+            "name": "Model 2",
+            "description": "The most powerful model"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+<ResponseField name="configOptions" type="ConfigOption[]">
+  The list of configuration options available for this session. The order of
+  this array represents the Agent's preferred priority. Clients **SHOULD**
+  respect this ordering when displaying options.
+</ResponseField>
+
+### ConfigOption
+
+<ResponseField name="id" type="string" required>
+  Unique identifier for this configuration option. Used when setting values.
+</ResponseField>
+
+<ResponseField name="name" type="string" required>
+  Human-readable label for the option
+</ResponseField>
+
+<ResponseField name="description" type="string">
+  Optional description providing more details about what this option controls
+</ResponseField>
+
+<ResponseField name="category" type="ConfigOptionCategory">
+  Optional [semantic category](#option-categories) to help Clients provide
+  consistent UX
+</ResponseField>
+
+<ResponseField name="type" type="ConfigOptionType" required>
+  The type of input control. Currently only `select` is supported.
+</ResponseField>
+
+<ResponseField name="currentValue" type="string" required>
+  The currently selected value for this option
+</ResponseField>
+
+<ResponseField name="options" type="ConfigOptionValue[]" required>
+  The available values for this option
+</ResponseField>
+
+### ConfigOptionValue
+
+<ResponseField name="value" type="string" required>
+  The value identifier used when setting this option
+</ResponseField>
+
+<ResponseField name="name" type="string" required>
+  Human-readable name to display
+</ResponseField>
+
+<ResponseField name="description" type="string">
+  Optional description of what this value does
+</ResponseField>
+
+## Option Categories
+
+Each config option **MAY** include a `category` field. Categories are semantic metadata intended to help Clients provide consistent UX, such as attaching keyboard shortcuts, choosing icons, or deciding placement.
+
+<Warning>
+  Categories are for UX purposes only and **MUST NOT** be required for
+  correctness. Clients **MUST** handle missing or unknown categories gracefully.
+</Warning>
+
+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 |
+
+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.
+
+## Option Ordering
+
+The order of the `configOptions` array is significant. Agents **SHOULD** place higher-priority options first in the list.
+
+Clients **SHOULD**:
+
+- Display options in the order provided by the Agent
+- Use ordering to resolve ties when multiple options share the same category
+- If displaying a limited number of options, prefer those at the beginning of the list
+
+## Default Values and Graceful Degradation
+
+Agents **MUST** always provide a default value for every configuration option. This ensures the Agent can operate correctly even if:
+
+- The Client doesn't support configuration options
+- The Client chooses not to display certain options
+- The Client receives an option type it doesn't recognize
+
+If a Client receives an option with an unrecognized `type`, it **SHOULD** ignore that option. The Agent will continue using its default value.
+
+## Setting a Config Option
+
+The current value of a config option can be changed at any point during a session, whether the Agent is idle or generating a response.
+
+### From the Client
+
+Clients can change a config option value by calling the `session/set_config_option` method:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "session/set_config_option",
+  "params": {
+    "sessionId": "sess_abc123def456",
+    "configId": "mode",
+    "value": "code"
+  }
+}
+```
+
+<ParamField path="sessionId" type="SessionId" required>
+  The ID of the session
+</ParamField>
+
+<ParamField path="configId" type="string" required>
+  The `id` of the configuration option to change
+</ParamField>
+
+<ParamField path="value" type="string" required>
+  The new value to set. Must be one of the values listed in the option's
+  `options` array.
+</ParamField>
+
+The Agent **MUST** respond with the complete list of all configuration options and their current values:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "result": {
+    "configOptions": [
+      {
+        "id": "mode",
+        "name": "Session Mode",
+        "type": "select",
+        "currentValue": "code",
+        "options": [...]
+      },
+      {
+        "id": "model",
+        "name": "Model",
+        "type": "select",
+        "currentValue": "model-1",
+        "options": [...]
+      }
+    ]
+  }
+}
+```
+
+<Note>
+  The response always contains the **complete** configuration state. This allows
+  Agents to reflect dependent changes. For example, if changing the model
+  affects available reasoning options, or if an option's available values change
+  based on another selection.
+</Note>
+
+### From the Agent
+
+The Agent can also change configuration options and notify the Client by sending a `config_options_update` session notification:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "session/update",
+  "params": {
+    "sessionId": "sess_abc123def456",
+    "update": {
+      "sessionUpdate": "config_options_update",
+      "configOptions": [
+        {
+          "id": "mode",
+          "name": "Session Mode",
+          "type": "select",
+          "currentValue": "code",
+          "options": [...]
+        },
+        {
+          "id": "model",
+          "name": "Model",
+          "type": "select",
+          "currentValue": "model-2",
+          "options": [...]
+        }
+      ]
+    }
+  }
+}
+```
+
+This notification also contains the complete configuration state. Common reasons an Agent might update configuration options include:
+
+- Switching modes after completing a planning phase
+- Falling back to a different model due to rate limits or errors
+- Adjusting available options based on context discovered during execution
+
+## Relationship to Session Modes
+
+Session Config Options supersede the older [Session Modes](../session-modes) API. However, during the transition period, Agents that provide mode-like configuration **SHOULD** send both:
+
+- `configOptions` with a `category: "mode"` option for Clients that support config options
+- `modes` for Clients that only support the older API
+
+If an Agent provides both `configOptions` and `modes` in the session response:
+
+- Clients that support config options **SHOULD** use `configOptions` exclusively and ignore `modes`
+- Clients that don't support config options **SHOULD** fall back to `modes`
+- Agents **SHOULD** keep both in sync to ensure consistent behavior regardless of which field the Client uses
+
+<Card icon="toggle-on" horizontal href="../session-modes">
+  Learn about the deprecated Session Modes API
+</Card>
diff --git a/docs/rfds/session-config-options.mdx b/docs/rfds/session-config-options.mdx
@@ -109,14 +109,16 @@ Each top-level config option MAY include an optional `category` field. This is i
 
 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`).
+`category` is semantic metadata and MUST NOT be required for correctness. Clients MUST handle missing or unknown categories gracefully.
+
+Category names beginning with `_` are free for custom use. Category names that do not begin with `_` are reserved for the ACP spec.
 
 Proposed enum:
 
 - `mode` - Session mode selector
 - `model` - Model selector
 - `thought_level` - Thought/reasoning level selector
-- `other` - Unknown / uncategorized selector
+- Any string beginning with `_` - Custom category (e.g., `_my_custom_category`)
 
 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.
 
diff --git a/package.json b/package.json
@@ -28,7 +28,7 @@
     "format:check": "prettier --check . && cargo fmt -- --check",
     "spellcheck": "./scripts/spellcheck.sh",
     "spellcheck:fix": "./scripts/spellcheck.sh --write-changes",
-    "check": "cargo clippy --all-features && npm run format:check && npm run spellcheck && cargo test",
+    "check": "cargo clippy --all-features && npm run format:check && npm run spellcheck && cargo test --all-features",
     "docs": "cd docs && npx mint dev"
   },
   "devDependencies": {
diff --git a/schema/schema.unstable.json b/schema/schema.unstable.json
@@ -2548,8 +2548,7 @@
       "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": [
+      "anyOf": [
         {
           "const": "mode",
           "description": "Session mode selector.",
@@ -2566,11 +2565,11 @@
           "type": "string"
         },
         {
-          "const": "other",
           "description": "Unknown / uncategorized selector.",
           "type": "string"
         }
-      ]
+      ],
+      "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.\n\nCategory names beginning with `_` are free for custom use, like other ACP extension methods.\nCategory names that do not begin with `_` are reserved for the ACP spec."
     },
     "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.",
diff --git a/src/agent.rs b/src/agent.rs

Original file line number	Diff line number	Diff line change
`@@ -80,6 +80,7 @@`
`80`	`80`	`"hidden": true,`
`81`	`81`	`"pages": [`
`82`	`82`	`"protocol/draft/cancellation",`
	`83`	`+ "protocol/draft/session-config-options",`
`83`	`84`	`"protocol/draft/schema"`
`84`	`85`	`]`
`85`	`86`	`}`
`@@ -105,7 +106,6 @@`
`105`	`106`	`"group": "Draft",`
`106`	`107`	`"pages": [`
`107`	`108`	`"rfds/session-list",`
`108`		`- "rfds/session-config-options",`
`109`	`109`	`"rfds/session-fork",`
`110`	`110`	`"rfds/request-cancellation",`
`111`	`111`	`"rfds/session-resume",`
`@@ -119,7 +119,7 @@`
`119`	`119`	`"rfds/auth-methods"`
`120`	`120`	`]`
`121`	`121`	`},`
`122`		`- { "group": "Preview", "pages": [] },`
	`122`	`+ { "group": "Preview", "pages": ["rfds/session-config-options"] },`
`123`	`123`	`{ "group": "Completed", "pages": ["rfds/introduce-rfd-process"] }`
`124`	`124`	`]`
`125`	`125`	`},`