diff --git a/docs/docs.json b/docs/docs.json
index 560ab50..2836282 100644
--- 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",
@@ -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"] }
]
},
diff --git a/docs/protocol/draft/session-config-options.mdx b/docs/protocol/draft/session-config-options.mdx
new file mode 100644
index 0000000..d972e0a
--- /dev/null
+++ 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.
+
+
+ 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.
+
+
+## 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"
+ }
+ ]
+ }
+ ]
+ }
+}
+```
+
+
+ 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.
+
+
+### ConfigOption
+
+
+ Unique identifier for this configuration option. Used when setting values.
+
+
+
+ Human-readable label for the option
+
+
+
+ Optional description providing more details about what this option controls
+
+
+
+ Optional [semantic category](#option-categories) to help Clients provide
+ consistent UX
+
+
+
+ The type of input control. Currently only `select` is supported.
+
+
+
+ The currently selected value for this option
+
+
+
+ The available values for this option
+
+
+### ConfigOptionValue
+
+
+ The value identifier used when setting this option
+
+
+
+ Human-readable name to display
+
+
+
+ Optional description of what this value does
+
+
+## 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.
+
+
+ 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`.
+
+
+| 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"
+ }
+}
+```
+
+
+ The ID of the session
+
+
+
+ The `id` of the configuration option to change
+
+
+
+ The new value to set. Must be one of the values listed in the option's
+ `options` array.
+
+
+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": [...]
+ }
+ ]
+ }
+}
+```
+
+
+ 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.
+
+
+### 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
+
+
+ Learn about the deprecated Session Modes API
+