Skip to main content
Agents can provide an arbitrary list of configuration options for a session, which Clients show to users as selectors. Options can cover models, model parameters, 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 modes field. Modes will be removed in a future version of the protocol.

Initial state

During Session Setup the Agent MAY return a list of configuration options and their current values:
SessionConfigOption[]
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.

SessionConfigOption

string
required
Unique identifier for this configuration option. Used when setting values.
string
required
Human-readable label for the option
string
Optional description providing more details about what this option controls
SessionConfigOptionCategory
Optional semantic category to help Clients provide consistent UX.
string
required
The type of input control. select is supported by default. boolean is only supported when the Client advertises session.configOptions.boolean: {} in clientCapabilities.
string | boolean
required
The current value for this option. For select options this is a string value ID. For boolean options this is a boolean.
SessionConfigSelectOption[] | SessionConfigSelectGroup[]
The available values for a select option. Required when type is "select" and omitted when type is "boolean". This is either a flat array of values or an array of groups. Values and groups are not mixed in the same array.

SessionConfigSelectOption

string
required
The value identifier used when setting this option
string
required
Human-readable name to display
string
Optional description of what this value does

Grouped select options

Select values may be organized into groups:
Each SessionConfigSelectGroup requires group (its unique string identifier), name (its human-readable label), and options (an array of SessionConfigSelectOption objects). A group may also include _meta. Each option still requires value and name. Its description and _meta fields are optional.

Boolean config options

Agents MAY include boolean config options only after the Client advertises support during initialization:
Omitting session, configOptions, or boolean means the Client does not advertise support. When support is advertised, a boolean option uses type: "boolean" and a boolean currentValue:
Agents MUST NOT include type: "boolean" options in configOptions payloads unless the Client advertised support. Agents that need to support older Clients should omit the boolean option or provide a select fallback.

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. 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.

Speed options (unstable)

Agents use the speed category for an option that changes how fast the model responds, such as a fast mode toggle or a speed selector. In a boolean speed option, true is the faster setting. See the RFD. Agents SHOULD list the values of a select speed option from slowest to fastest. Agents SHOULD NOT use speed for an option that mainly selects a model, reasoning level, or session mode, even when its values differ in speed. Use model, thought_level, or mode for those. A speed option can depend on other options. For example, an Agent can offer it only for some models. The Agent reports such changes in the complete configOptions list, as for any other option. Clients SHOULD render speed options near the model selector, as with model_config. Clients MAY also show the current speed outside the option list, such as an icon while a boolean speed option is true.

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

Every configuration option’s currentValue is the value the Agent uses until the Client changes it. Agents MUST be able to operate with it, 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 keeps using its currentValue.

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:
SessionId
required
The ID of the session
string
required
The id of the configuration option to change
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:
The Agent MUST respond with the complete list of all configuration options and their current values:
The response always contains the complete configuration state, so Agents can report dependent changes. For example, changing the model may change the available reasoning options.

From the Agent

The Agent can also change configuration options and notify the Client by sending a config_option_update session notification:
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

Options before a session exists (unstable)

Agents that advertise sessionCapabilities.options support session/options, which returns the config options a session would start with without creating or resuming it. They also accept initial values in configOptions on session/new, session/load, and session/resume. Clients MUST NOT call session/options or send configOptions on session setup requests unless the Agent advertises the capability. See the RFD.

Querying options

Clients call session/options with the same workspace parameters as session/new:
string
required
The working directory to resolve options for. Must be an absolute path.
string[]
Additional workspace roots to resolve options for. Omitted and null are equivalent to an empty list.
SessionId
An existing session to resolve options for. Omitted and null are equivalent and mean a new session.
When sessionId is present, the Agent returns what session/load or session/resume with the same cwd and additionalDirectories would return. The same cwd rules as those methods apply. A session the Agent does not know gets -32002. Clients MUST NOT send sessionId unless the Agent supports session/load (loadSession), session/resume (sessionCapabilities.resume), or session/fork (sessionCapabilities.fork). The request has no mcpServers parameter. Agents SHOULD NOT connect to MCP servers to answer it. The response contains the options the session would start with:
configOptions uses the same type and rules as on NewSessionResponse. modes uses the same type as on NewSessionResponse. Agents only return type: "boolean" options when the Client advertises sessionCapabilities.configOptions.boolean. session/options MUST NOT create or resume a session, send session/update notifications, add an entry to session/list, or change an existing session. Agents MAY start their runtime to resolve the options. These rules still hold for it: it stores no session, writes nothing to the history of sessionId, and adds no entry to session/list. Clients SHOULD NOT call session/options on a timer, because an Agent may start its runtime for each call. The response is a snapshot. The options a session actually starts with are the ones in the setup response.

Initial values

Clients send the values the user picked in configOptions on session/new, session/load, session/resume, and, when the Agent supports it, session/fork. Each entry has the same shape as session/set_config_option without sessionId. type is optional and defaults to id, as on session/set_config_option. Clients only send type: "boolean" entries when they advertise sessionCapabilities.configOptions.boolean.
The Agent applies the entries in list order, as if the Client had called session/set_config_option for each entry after the session was set up. Each entry is checked against the option set as it stands at that point, so an earlier entry (such as the model) can change which values a later entry (such as the reasoning level) allows. Clients SHOULD send entries in the order the Agent listed the options in the session/options response. For restored sessions, the entries apply on top of the session’s restored configuration. On session/fork, the entries apply on top of the configuration the fork would start with without them. To show the options before a fork, Clients call session/options with the sessionId of the source session. Initial values are handled differently from session/set_config_option, because options can change between session/options and session setup:
  • An entry that does not match the schema, such as a missing configId or a value that does not match its type, MUST fail the request with -32602.
  • Two entries with the same configId MUST fail the request with -32602.
  • An entry whose configId is unknown, whose type does not match the option’s type, or whose value is not allowed when it is applied MUST be ignored. This includes a value the Agent’s runtime refuses. The option keeps its default value, or the value the Agent resolved from earlier entries.
  • The configOptions in the setup response MUST contain the values the session actually has. Clients compare them with what they sent to find entries the Agent ignored.
  • The Agent SHOULD NOT send config_option_update notifications for these entries. The setup response contains the resulting values.
  • Until the session/new or session/fork response, the Client does not know the session. The Agent SHOULD NOT send other session/update notifications caused by applying the entries before that response, such as a notice that a value fell back or a current_mode_update. It sends them after the response.

Relationship to session modes

Session Config Options supersede the older 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 Session Modes API