Expose generic ACP session configuration options through Agent Server

[neubig]

Problem

ACP agents can advertise session-scoped configOptions and accept updates through session/set_config_option. The SDK currently recognizes the model option (plus Codex reasoning effort as part of model selection), but it does not retain or expose other advertised options.

This means provider capabilities are lost between the ACP subprocess and Agent Server clients. A concrete example is @agentclientprotocol/codex-acp@1.1.2, which advertises a fast-mode option for models whose Codex catalog supports the fast service tier. The adapter accepts updates to that option and applies serviceTier: "fast" to subsequent turns, but Agent Canvas cannot discover or change it.

This is intentionally out of scope for #4056, which updates the Codex ACP adapter and GPT-5.6 model support.

Proposed direction

• Add a provider-agnostic representation for ACP session configuration options, including at least select and boolean options.
• Preserve the options returned by session/new, session/load, and session/resume.
• Expose current values and available choices through Agent Server APIs.
• Add a generic operation for applying an option by config ID and value through session/set_config_option.
• Define persistence and resume behavior so the serialized state matches the live ACP session.
• Keep model selection as a typed convenience API built on the generic mechanism where appropriate.
• Add focused coverage using a mock ACP server that advertises a non-model option.

Downstream work

Once Agent Server exposes these options, the TypeScript client and Agent Canvas should render suitable controls from the advertised schema. For Codex, that would surface fast-mode as a toggle or select only when the selected model supports it.

Non-goals

• Do not encode Fast mode as a separate model ID such as gpt-5.6-fast.
• Do not require provider-specific environment mutation to select a runtime session option.
• Do not add this work to fix: support GPT-5.6 across Codex authentication #4056.

References

• Codex Fast mode documentation: https://learn.chatgpt.com/docs/agent-configuration/speed
• Related adapter/model update: fix: support GPT-5.6 across Codex authentication #4056

[all-hands-bot]

#4062 proposes a generic framework for all ACP session configOptions (e.g. fast-mode). #3699 requests exposing one specific ACP config option (reasoning effort) as a typed field. Both address ACP session configuration capabilities being lost between the subprocess and Agent Server clients, but #4062 is a structural/generic approach while #3699 is an incremental typed-field approach. They should cross-reference each other but remain separate issues.

Found 3 possible duplicate issues:

1. #3699 — [Feature]: Expose reasoning "effort" as a first-class parameter for ACP agents (Claude Code, Codex)
2. #3736 — Track ACP model selection method compatibility
3. #3771 — ACP: deprecate the session/new _meta model-selection path (set_session_model is now universal)

These may not be exact duplicates, but the scope appears to overlap enough that keeping discussion in one place may be more useful.

This comment was created by an AI assistant (OpenHands) on behalf of the repository maintainer.