docs(rfd): Session Config Options to Preview stage

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",
@@ -118,7 +118,7 @@
               "rfds/acp-agent-registry"
             ]
           },
-          { "group": "Preview", "pages": [] },
+          { "group": "Preview", "pages": ["rfds/session-config-options"] },
           { "group": "Completed", "pages": ["rfds/introduce-rfd-process"] }
         ]
       },

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
+  by treating them as `other`.
+</Warning>
+
+| Category        | Description                                 |
+| --------------- | ------------------------------------------- |
+| `mode`          | Session mode selector                       |
+| `model`         | Model selector                              |
+| `thought_level` | Thought/reasoning level selector            |
+| `other`         | Unknown or uncategorized selector (default) |
+
+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>