> ## Documentation Index
> Fetch the complete documentation index at: https://agentclientprotocol.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Session Config Options
> 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, model parameters, reasoning levels, and more.
## Initial State
During [Session Setup](/protocol/v2/draft/session-setup) the Agent **MAY** return a list of configuration options and their current values:
```json theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"sessionId": "sess_abc123def456",
"configOptions": [
{
"configId": "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"
}
]
},
{
"configId": "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"
}
]
},
{
"configId": "context_size",
"name": "Context Size",
"category": "model_config",
"type": "select",
"currentValue": "200k",
"options": [
{
"value": "200k",
"name": "200K"
},
{
"value": "1m",
"name": "1M"
}
]
},
{
"configId": "brave_mode",
"name": "Brave Mode",
"description": "Skip confirmation prompts and act autonomously",
"type": "boolean",
"currentValue": false
}
]
}
}
```
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. `select` and `boolean` are supported.
The current value for this option. For `select` options this is a string value
ID. For `boolean` options this is a boolean.
The available values for a `select` option. Required when `type` is `"select"`
and omitted when `type` is `"boolean"`.
### ConfigOptionValue
The value identifier used when setting this option
Human-readable name to display
Optional description of what this value does
### Boolean Config Options
Boolean config options use `type: "boolean"` for simple on/off toggles:
```json theme={null}
{
"configId": "brave_mode",
"name": "Brave Mode",
"description": "Skip confirmation prompts and act autonomously",
"type": "boolean",
"currentValue": true
}
```
## 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.
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 |
| `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.
## 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
Option `type` values can be custom or future variants. Custom option types **MUST** begin with `_`; unknown non-underscore option types are reserved for future ACP variants. If a Client receives an option with an unrecognized `type`, it **SHOULD** preserve the raw option when storing, replaying, proxying, or forwarding session state, and otherwise 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.
### From the Client
Clients can change a config option value by calling the `session/set_config_option` method:
```json theme={null}
{
"jsonrpc": "2.0",
"id": 2,
"method": "session/set_config_option",
"params": {
"sessionId": "sess_abc123def456",
"configId": "mode",
"type": "id",
"value": "code"
}
}
```
The ID of the session
The `configId` of the configuration option to change
The shape of the value. Use `id` for `select` and other id-based options. Use
`boolean` for boolean options.
The new value to set. For `select` options, this must be one of the values
listed in the option's `options` array. For `boolean` options, this must be a
boolean.
For boolean options, Clients send `type: "boolean"` with a boolean `value`:
```json theme={null}
{
"jsonrpc": "2.0",
"id": 3,
"method": "session/set_config_option",
"params": {
"sessionId": "sess_abc123def456",
"configId": "brave_mode",
"type": "boolean",
"value": true
}
}
```
The Agent **MUST** respond with the complete list of all configuration options and their current values:
```json theme={null}
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"configOptions": [
{
"configId": "mode",
"name": "Session Mode",
"type": "select",
"currentValue": "code",
"options": [
{
"value": "ask",
"name": "Ask"
},
{
"value": "code",
"name": "Code"
}
]
},
{
"configId": "model",
"name": "Model",
"type": "select",
"currentValue": "model-1",
"options": [
{
"value": "model-1",
"name": "Model 1"
},
{
"value": "model-2",
"name": "Model 2"
}
]
}
]
}
}
```
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_option_update` session notification:
```json theme={null}
{
"jsonrpc": "2.0",
"method": "session/update",
"params": {
"sessionId": "sess_abc123def456",
"update": {
"sessionUpdate": "config_option_update",
"configOptions": [
{
"configId": "mode",
"name": "Session Mode",
"type": "select",
"currentValue": "code",
"options": [
{
"value": "ask",
"name": "Ask"
},
{
"value": "code",
"name": "Code"
}
]
},
{
"configId": "model",
"name": "Model",
"type": "select",
"currentValue": "model-2",
"options": [
{
"value": "model-1",
"name": "Model 1"
},
{
"value": "model-2",
"name": "Model 2"
}
]
}
]
}
}
}
```
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