RFD: Session Input Options

[chazcb]

Summary

Proposal for allowing Agents to declare input options they accept for session/new and session/load requests, advertised in InitializeResult capabilities.

Uses MCP elicitation's JSON Schema format for defining input schemas, providing ecosystem consistency.

Key Design Decisions

• Discovery at init time: Input schemas are advertised in InitializeResult.capabilities.sessions, enabling clients to show configuration UI before session creation
• Elicitation schema format: Uses the same JSON Schema subset as MCP elicitation for type definitions, encouraging ecosystem alignment
• Separate schemas: Distinct schemas for newSession vs loadSession operations
• All options optional: Agents must provide sensible defaults

Why not pure elicitation?

We considered using MCP elicitation directly (server requests input after session/new), but this has UX tradeoffs:

• Session enters "pending" state during elicitation
• Clients can't show configuration UI proactively
• Discovery requires starting a session first

By advertising schemas at init time, clients can build configuration UIs that feel native rather than reactive.

Related

• Uses schema format from MCP Elicitation
• Complements Session Config Options (runtime configuration during a session)

[chazcb]

Planning to update to:

1. Ensure that enums ("select") matches the select from Session Config Options feat: Stabilize Session Config Options #411
2. Change "hint" to "name" for consistency with Session Config Options
3. Update to clarify that there are two proposals in here: 1 for the richer options schema and 1 for session/new session/load config options

I might split the two proposals out in the near future depending on need!

[benbrandt]

Thanks for kicking this off! A few thoughts:

• Without a breaking change, we definitely would need to make sure no inputs are required (could revisit as a v2 protocol version)
• Session Config options were purposely a bit restricted since they need to encapsulate not only what config options are available, but also their current state, since they are "live" forms so to speak, and can be updated by both the user and the agent
• I wonder if we should somehow treat new/load options more similarly to MCP elicitation #376 since we likely want some more flexibility, and this is more of an input form to be filled out once that doesn't have the same state considerations of session config

MCP elicitation takes a JSON Schema approach, but is much more restricted to limit the client burden. We need to support it anyway for MCP support + other agent needs like asking users specific questions, so I guess my thought is: if the client supports elicitation, could we use the same thing to also support requesting additional inputs from the user when starting a session?

I like the approach of keeping this as similar as possible to session config, but I also wonder if this is a different enough use case, we can actually make it more similar to elicitation instead.

Another thought: could the agent do an elicitation post new thread happening to request more configuration if needed before the user sends a prompt?

And another: are these config options something we as clients should show on every new session? Or do some of these configuration options only need to be set on first load if configuration hasn't been set yet? And the defaults carry over unless a user wants to change them?

[benbrandt]

I wonder if we can somehow come up with a more structured way of handling this since we know which resources this affects, but maybe it is also fine to tie this to method names since those are stable enough. Just recording my indecision 😄

[chazcb]

100% agree 😂

[chazcb]

Maybe a better option is to have a discovery method like "session/new_options" and server returns the config.

[anna239]

we're currently working on ability to provide requestId in the elicitation request — #792 We need this functionality for things other then config options, will it maybe work for this scenario too?

[eamarucci]

Contextual pre-session model discovery, including startup and authentication guarantees

Following the suggestion of a discovery method, could this RFD cover a supported, negotiated contextual query for models and per-model reasoning options before creating a session, including an explicit refresh? A launcher needs choices for its intended working directory and provider/configuration context before the first launch. A connection-wide schema alone may not capture those differences.

In a static review of codex-acp at acc035a7444bf7550aabcc24597ed845ba3e593b, newSession creates a thread before fetching models. The adapter wraps App Server model/config reads, but that does not establish that a pre-session query would use the same context as a later launch. I have not run a reproduction.

Could the supported discovery path cover startup and initialize as well as the query, without creating or resuming an operational session, sending a prompt, running inference, mutating authentication, or exposing credentials? The current launcher starts App Server before ACP initialize, and initialize schedules an account-status read. Passing refreshToken:false to one read does not establish that the whole startup path preserves authentication. If these constraints cannot be met for a context, an explicit unavailable result would be useful. This is not a blanket objection to an internal ephemeral process or thread; its effects and lifecycle would need to satisfy the same constraints.

Partial information should remain explicit: unsupported discovery, an unavailable or empty catalog, and unqueried model-specific options should not become invented defaults or evidence that a model can execute. A default may be omitted; reasoning options need to remain associated with their model. Cancellation and resource-closure semantics should be documented, with process-exit observation remaining the client/supervisor’s responsibility.

Is this contextual query appropriate for this RFD, or should the adapter first define an optional extension? I am asking for a supported interface and clarification of its guarantees, without prescribing a method name, response schema, or timeout values.

[benbrandt]

I think we've discussed this a bit, and a better approach will probably be to have a session/config or something similar that is a request that takes a cwd, addl directories, etc and returns which config options would be available on a new/loaded session, so that you can pass them in to the session creation.

Since many of these values can resolve based on project configs, I think having the response be based on similar config as a session would make a lot of sense, but would also allow the client to know what would be available beforehand