tai/research/cap-protocol/agentclientprotocol-session-config-options.md

ACP: Session Config Options

Metadata

Field	Value
Institute	Molodetz Institute — Research & Retrieval Division
Subject	cap-protocol
Document type	Source Dossier
Tier	1
Source title	ACP: Session Config Options
Source URL	https://agentclientprotocol.com/protocol/session-config-options
Source publisher / author	Agent Client Protocol project
Source type	standard
Source date (published)	Unknown — not stated
Date researched	2026-10-25
Researched by	tai (agent), model: Claude Sonnet 5, on behalf of retoor
Research method	direct page fetch
Confidence	High
Status	Active

Summary

The ACP mechanism by which an agent advertises per-session selectors (model, mode, reasoning level) and a client changes them. It is the closest existing standard to 'list an agent's models and pick one'.

Key findings

• Each config option has id, name, optional description, optional category, type (select by default, boolean only if the client advertised support), currentValue, and options (flat values or groups, not mixed).
• Reserved categories: mode, model, model_config, thought_level; names starting with _ are custom; clients MUST handle missing or unknown categories gracefully.
• The agent MAY return configOptions during session setup; the client sets one with session/set_config_option (sessionId, configId, value) and the agent MUST answer with the complete list of options and values.
• The agent announces changes with a session/update of sessionUpdate: config_option_update carrying the full configOptions array.
• Agents MUST always provide a default for every option; a client that meets an unknown type SHOULD ignore that option and the agent keeps its default.
• Order is significant: higher-priority options first; clients use the order to break ties within a category.
• If an agent provides configOptions, clients SHOULD use them instead of modes, which will be removed.

Pros / strengths

Normative (MUST/SHOULD) and small; gives a live, per-agent, per-session model list instead of a static one, with a defined default and ordering.

Cons / limitations / caveats

Only exists for agents that speak ACP; the page does not say how large option lists should be capped; the model_config category is separate RFD territory.

Relevance to tai

tai's catalog reads a manifest list or a --cap-models probe, both static. For acp_stdio agents the live truth is the model-category config option from session setup. Recommended as the first discovery source for that binding, with ACP's default-on-unknown rule as the error-resistance model.

Changelog

Date	Change
2026-10-25	Initial dossier created.