> ## 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 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 [`modes`](./session-modes) field. Modes will be removed in
  a future version of the protocol.
</Info>

## Initial State

During [Session Setup](./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": [
      {
        "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 theme={null}
{
  "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 theme={null}
{
  "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_option_update` session notification:

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "config_option_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="gears" horizontal href="../session-modes">
  Learn about the Session Modes API
</Card>