Session Config Options

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 the Agent MAY return a list of configuration options and their current values:

{
  "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
      }
    ]
  }
}

configOptions

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.

ConfigOption

configId

string

required

Unique identifier for this configuration option. Used when setting values.

name

string

required

Human-readable label for the option

description

string

Optional description providing more details about what this option controls

ConfigOptionValue

value

string

required

The value identifier used when setting this option

name

string

required

Human-readable name to display

description

string

Optional description of what this value does

Boolean Config Options

Boolean config options use type: "boolean" for simple on/off toggles:

{
  "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:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "session/set_config_option",
  "params": {
    "sessionId": "sess_abc123def456",
    "configId": "mode",
    "type": "id",
    "value": "code"
  }
}

sessionId

SessionId

required

The ID of the session

configId

string

required

The configId of the configuration option to change

type

"id" | "boolean"

required

The shape of the value. Use id for select and other id-based options. Use boolean for boolean options.

value

string | boolean

required

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:

{
  "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:

{
  "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:

{
  "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

Get Started

Protocol

Libraries

Initial State

ConfigOption

ConfigOptionValue

Boolean Config Options

Option Categories

Option Ordering

Default Values and Graceful Degradation

Setting a Config Option

From the Client

From the Agent

​Initial State

​ConfigOption

​ConfigOptionValue

​Boolean Config Options

​Option Categories

​Option Ordering

​Default Values and Graceful Degradation

​Setting a Config Option

​From the Client

​From the Agent

Initial State

ConfigOption

ConfigOptionValue

Boolean Config Options

Option Categories

Option Ordering

Default Values and Graceful Degradation

Setting a Config Option

From the Client

From the Agent