Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions docs/docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -232,15 +232,14 @@
"rfds/session-status",
"rfds/session-set-title",
"rfds/session-archive",
"rfds/session-options",
"rfds/prompt-suggestions",
"rfds/agent-skills",
"rfds/session-cursors"
]
},
{
"group": "Preview",
"pages": ["rfds/speed-config-category"]
"pages": ["rfds/session-options", "rfds/speed-config-category"]
},
{
"group": "Completed",
Expand Down
2 changes: 1 addition & 1 deletion docs/protocol/v1/draft/session-config-options.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -472,7 +472,7 @@ This notification also contains the complete configuration state. Common reasons

## 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](/rfds/session-options).
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 each setup method they support: `session/new`, `session/load`, `session/resume`, and `session/fork`. Clients **MUST NOT** call `session/options` or send `configOptions` on session setup requests unless the Agent advertises the capability. See the [RFD](/rfds/session-options).

### Querying options

Expand Down
24 changes: 12 additions & 12 deletions docs/protocol/v2/draft/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -325,18 +325,18 @@ See [Extensibility](/protocol/v2/draft/extensibility) for details.

The draft schema also defines experimental features that may change or be removed before they stabilize. Each is negotiated separately, as described in [Experimental Features and Negotiation](/protocol/v2/draft/extensibility#experimental-features-and-negotiation). Where the draft pages don't describe a feature yet, its RFD is the reference.

| Feature | Methods and updates | Negotiation | Details |
| --------------- | ------------------------------------------------------------------------ | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| LLM providers | `providers/list`, `providers/set`, `providers/disable` | Agent `providers` capability | [Initialization](/protocol/v2/draft/initialization#agent-capabilities), [RFD](/rfds/custom-llm-endpoint) |
| Session fork | `session/fork` | Agent `session.fork` | [RFD](/rfds/session-fork) |
| Session archive | `session/archive`, `session/unarchive`, `archived` on `session/list` | Agent `session.archive` | [Archived Sessions](/protocol/v2/draft/session-list#archived-sessions-unstable), [RFD](/rfds/session-archive) |
| Session status | `session/status` | Agent `session.status` | [RFD](/rfds/session-status) |
| Session options | `session/options`, `configOptions` on `session/new` and `session/resume` | Agent `session.options` | [Options before a session exists](/protocol/v2/draft/session-config-options#options-before-a-session-exists-unstable), [RFD](/rfds/session-options) |
| Session titles | `session/set_title` | Agent `session.title` | [RFD](/rfds/session-set-title) |
| Auth status | `auth/status`, `auth/status_update` | Agent `auth.status` | [RFD](/rfds/get-auth-state) |
| MCP over ACP | `mcp/message` in both directions, `acp` MCP server transport | Agent `session.mcp.acp` | [RFD](/rfds/mcp-over-acp) |
| End-turn usage | `usage` on the idle `state_update` | None | [End-Turn Token Usage](/protocol/v2/draft/prompt-lifecycle#end-turn-token-usage-unstable) |
| Proxy chains | `proxy/initialize`, `proxy/successor` | Conductors and proxies only | [RFD](/rfds/proxy-chains) |
| Feature | Methods and updates | Negotiation | Details |
| --------------- | ----------------------------------------------------------------------------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| LLM providers | `providers/list`, `providers/set`, `providers/disable` | Agent `providers` capability | [Initialization](/protocol/v2/draft/initialization#agent-capabilities), [RFD](/rfds/custom-llm-endpoint) |
| Session fork | `session/fork` | Agent `session.fork` | [RFD](/rfds/session-fork) |
| Session archive | `session/archive`, `session/unarchive`, `archived` on `session/list` | Agent `session.archive` | [Archived Sessions](/protocol/v2/draft/session-list#archived-sessions-unstable), [RFD](/rfds/session-archive) |
| Session status | `session/status` | Agent `session.status` | [RFD](/rfds/session-status) |
| Session options | `session/options`, `configOptions` on `session/new`, `session/resume`, and `session/fork` | Agent `session.options` | [Options before a session exists](/protocol/v2/draft/session-config-options#options-before-a-session-exists-unstable), [RFD](/rfds/session-options) |
| Session titles | `session/set_title` | Agent `session.title` | [RFD](/rfds/session-set-title) |
| Auth status | `auth/status`, `auth/status_update` | Agent `auth.status` | [RFD](/rfds/get-auth-state) |
| MCP over ACP | `mcp/message` in both directions, `acp` MCP server transport | Agent `session.mcp.acp` | [RFD](/rfds/mcp-over-acp) |
| End-turn usage | `usage` on the idle `state_update` | None | [End-Turn Token Usage](/protocol/v2/draft/prompt-lifecycle#end-turn-token-usage-unstable) |
| Proxy chains | `proxy/initialize`, `proxy/successor` | Conductors and proxies only | [RFD](/rfds/proxy-chains) |

## Next steps

Expand Down
2 changes: 1 addition & 1 deletion docs/protocol/v2/draft/session-config-options.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -479,7 +479,7 @@ This notification also contains the complete configuration state. Common reasons

## Options before a session exists (unstable)

Agents that advertise `session.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` 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](/rfds/session-options).
Agents that advertise `session.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 each setup method they support: `session/new`, `session/resume`, and `session/fork`. Clients **MUST NOT** call `session/options` or send `configOptions` on session setup requests unless the Agent advertises the capability. See the [RFD](/rfds/session-options).

### Querying options

Expand Down
12 changes: 6 additions & 6 deletions docs/rfds/session-options.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -207,14 +207,13 @@ A Client opens a "new session" screen and calls `session/options` with the works

A Client can also call `session/options` with a `sessionId` from its session list to show which model a past session uses. The user can change it before resuming, and the Client passes the new value on `session/resume` (or `session/load` in v1).

## Implementation details and plan
## Implementations

> Tell me more about your implementation. What is your detailed implementation plan?
The v1 and v2 schemas keep `session/options` and initial `configOptions` behind `unstable_session_options` during Preview. The [v1 guide](/protocol/v1/draft/session-config-options#options-before-a-session-exists-unstable) and [v2 guide](/protocol/v2/draft/session-config-options#options-before-a-session-exists-unstable) show the wire requests and responses.

1. Add `SessionOptionsRequest` and `SessionOptionsResponse`, the `session/options` method constant, and the `options` session capability to the v1 and v2 schemas behind an `unstable_session_options` feature.
2. Add the optional `configOptions` field to the session setup requests for each version behind the same feature, including `session/fork`.
3. Document the method and the initial values on the `session-setup` and `session-config-options` pages in `docs/protocol/v1` and `docs/protocol/v2`, following the version differences above.
4. Update the example Agents and Clients.
- The [Rust SDK 5.3.0](https://github.com/agentclientprotocol/rust-sdk/releases/tag/v5.3.0) and [TypeScript SDK 2.7.0](https://github.com/agentclientprotocol/typescript-sdk/releases/tag/v2.7.0) expose the method and the `configOptions` field on setup requests, including `session/fork`, in both protocol versions. The TypeScript wire tests exercise `session/options` and `session/new` together in [v1](https://github.com/agentclientprotocol/typescript-sdk/blob/v2.7.0/src/v1/acp.test.ts#L4671) and [v2](https://github.com/agentclientprotocol/typescript-sdk/blob/v2.7.0/src/v2/acp.test.ts#L2725).
- To try both versions with the [Claude Agent adapter](https://github.com/agentclientprotocol/claude-agent-acp/pull/1592), use `npx -y @agentclientprotocol/claude-agent-acp@0.109.1-preview.5` as the Agent command. This build includes [initial values on fork](https://github.com/agentclientprotocol/claude-agent-acp/pull/1629) and [the v1 fix for querying a held session with different workspace roots](https://github.com/agentclientprotocol/claude-agent-acp/pull/1679).
- [Delta](https://delta.dev) uses `session/options` to show config options and slash commands before the first prompt. It sends the user's choices on `session/new`. [Zed](https://github.com/zed-industries/zed/pull/66832) sends saved defaults on `session/new` behind its `acp-beta` flag without calling `session/options`.

## Frequently asked questions

Expand Down Expand Up @@ -285,3 +284,4 @@ Commands are not settings. The Client runs a command by sending it in a prompt a

- 2026-11-03: Initial draft
- 2026-11-10: Accept `configOptions` on `session/fork`. Hold back other `session/update` notifications for initial values until the `session/new` or `session/fork` response. In v2, send `config_option_update` on other connections where a resumed session is active. A value the runtime refuses is ignored. An Agent may start its runtime to answer `session/options`, and Clients should not poll it.
- 2026-11-20: Moved to Preview. The feature remains unstable.
7 changes: 7 additions & 0 deletions docs/rfds/updates.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,13 @@ rss: true

This page tracks lifecycle changes for ACP Requests for Dialog. For broader ACP announcements, see [Updates](/updates).

<Update label="November 20, 2026" tags={["Preview"]}>
## Session options RFD moves to Preview

The [Session options RFD](/rfds/session-options) has moved to Preview. Clients can call `session/options` before creating or resuming a session and send the user's choices in `configOptions` on setup. Try selecting a model and a reasoning level together, then compare the choices you sent with the values the Agent returns.

</Update>

<Update label="November 20, 2026" tags={["Completed"]}>
## Subagent Sessions RFD moves to Completed

Expand Down