From c11cfebbd5cec038d1caa4bb3b886208c9cfabbe Mon Sep 17 00:00:00 2001 From: Ben Brandt Date: Tue, 10 Nov 2026 23:00:37 +0100 Subject: [PATCH] feat(unstable): accept initial config options on session/fork and clarify notifications Feedback from implementing the Session options RFD in the Claude adapter: - `session/fork` takes `configOptions` too. The RFD required them on every session setup request, but the schema left fork out. Clients read the options for a fork from `session/options` with the source session's id. - Besides `config_option_update`, the Agent holds back other `session/update` notifications that applying the entries causes until the `session/new` or `session/fork` response. - In v2, a `session/resume` with entries sends `config_option_update` on the other connections where the session is active. - A value the runtime refuses when it is applied is ignored, like any other value that is not allowed. - An Agent may start its runtime to answer `session/options`. Clients should not call it on a timer. --- agent-client-protocol-schema/src/v1/agent.rs | 98 +++++++++++++++- agent-client-protocol-schema/src/v2/agent.rs | 106 +++++++++++++++++- docs/protocol/v1/draft/schema.mdx | 28 ++++- .../v1/draft/session-config-options.mdx | 13 ++- docs/protocol/v1/draft/session-setup.mdx | 2 +- docs/protocol/v2/draft/schema.mdx | 32 +++++- .../v2/draft/session-config-options.mdx | 12 +- docs/protocol/v2/draft/session-setup.mdx | 2 +- docs/rfds/session-options.mdx | 36 +++++- schema/v1/schema.unstable.json | 12 +- schema/v2/schema.unstable.json | 14 ++- 11 files changed, 318 insertions(+), 37 deletions(-) diff --git a/agent-client-protocol-schema/src/v1/agent.rs b/agent-client-protocol-schema/src/v1/agent.rs index 3425a81c9..7d34294d2 100644 --- a/agent-client-protocol-schema/src/v1/agent.rs +++ b/agent-client-protocol-schema/src/v1/agent.rs @@ -1274,7 +1274,9 @@ pub struct NewSessionRequest { /// entries and duplicate `configId` values fail the request with `-32602`. The Agent MUST /// ignore an entry whose `configId` is unknown, whose `type` does not match the option, /// or whose value is not allowed when it is applied. The `configOptions` in the response contain the values the session actually - /// has. The Agent SHOULD NOT send `config_option_update` notifications for these entries. + /// has. The Agent SHOULD NOT send `config_option_update` notifications for these entries, + /// and SHOULD NOT send other `session/update` notifications caused by applying them + /// before it responds. #[cfg(feature = "unstable_session_options")] #[serde_as(deserialize_as = "DefaultOnNull")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))] @@ -1342,7 +1344,9 @@ impl NewSessionRequest { /// entries and duplicate `configId` values fail the request with `-32602`. The Agent MUST /// ignore an entry whose `configId` is unknown, whose `type` does not match the option, /// or whose value is not allowed when it is applied. The `configOptions` in the response contain the values the session actually - /// has. The Agent SHOULD NOT send `config_option_update` notifications for these entries. + /// has. The Agent SHOULD NOT send `config_option_update` notifications for these entries, + /// and SHOULD NOT send other `session/update` notifications caused by applying them + /// before it responds. #[cfg(feature = "unstable_session_options")] #[must_use] pub fn config_options(mut self, config_options: Vec) -> Self { @@ -1710,6 +1714,29 @@ pub struct ForkSessionRequest { /// for the source session. #[serde(default)] pub system_prompt: Option, + /// **UNSTABLE** + /// + /// This capability is not part of the spec yet, and may be removed or changed at any point. + /// + /// Initial values for the forked session's config options. + /// + /// Optional. Omitted and `null` are equivalent to an empty list. Clients MUST only send + /// this when the Agent advertises `sessionCapabilities.options`. + /// + /// The Agent applies the entries in list order on top of the configuration the fork + /// starts with, as if the Client had called `session/set_config_option` for each entry + /// after the session was set up. Malformed entries and duplicate `configId` values fail + /// the request with `-32602`. The Agent MUST ignore an entry whose `configId` is unknown, + /// whose `type` does not match the option, or whose value is not allowed when it is + /// applied. The `configOptions` in the response contain the values the session actually + /// has. The Agent SHOULD NOT send `config_option_update` notifications for these entries, + /// and SHOULD NOT send other `session/update` notifications caused by applying them + /// before it responds. + #[cfg(feature = "unstable_session_options")] + #[serde_as(deserialize_as = "DefaultOnNull")] + #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))] + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub config_options: Vec, /// The _meta property is reserved by ACP to allow clients and agents to attach additional /// metadata to their interactions. Implementations MUST NOT make assumptions about values at /// these keys. @@ -1733,6 +1760,8 @@ impl ForkSessionRequest { additional_directories: vec![], mcp_servers: vec![], system_prompt: None, + #[cfg(feature = "unstable_session_options")] + config_options: vec![], meta: None, } } @@ -1758,6 +1787,31 @@ impl ForkSessionRequest { self } + /// **UNSTABLE** + /// + /// This capability is not part of the spec yet, and may be removed or changed at any point. + /// + /// Initial values for the forked session's config options. + /// + /// Optional. Omitted and `null` are equivalent to an empty list. Clients MUST only send + /// this when the Agent advertises `sessionCapabilities.options`. + /// + /// The Agent applies the entries in list order on top of the configuration the fork + /// starts with, as if the Client had called `session/set_config_option` for each entry + /// after the session was set up. Malformed entries and duplicate `configId` values fail + /// the request with `-32602`. The Agent MUST ignore an entry whose `configId` is unknown, + /// whose `type` does not match the option, or whose value is not allowed when it is + /// applied. The `configOptions` in the response contain the values the session actually + /// has. The Agent SHOULD NOT send `config_option_update` notifications for these entries, + /// and SHOULD NOT send other `session/update` notifications caused by applying them + /// before it responds. + #[cfg(feature = "unstable_session_options")] + #[must_use] + pub fn config_options(mut self, config_options: Vec) -> Self { + self.config_options = config_options; + self + } + /// The _meta property is reserved by ACP to allow clients and agents to attach additional /// metadata to their interactions. Implementations MUST NOT make assumptions about values at /// these keys. @@ -2324,7 +2378,8 @@ pub enum SessionStatus { /// /// `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 -/// SHOULD NOT connect to MCP servers to answer it. +/// SHOULD NOT connect to MCP servers to answer it. Agents MAY start their runtime to resolve +/// the options. The rules above still hold for it. #[cfg(feature = "unstable_session_options")] #[serde_as] #[skip_serializing_none] @@ -7811,6 +7866,43 @@ mod test_serialization { serde_json::to_value(SessionOptionsResponse::new()).unwrap(), json!({}) ); + #[cfg(feature = "unstable_session_fork")] + { + let fork = + ForkSessionRequest::new("sess_abc123", "/home/user/project").config_options(vec![ + InitialSessionConfigOption::new( + "model", + SessionConfigOptionValue::value_id("model-2"), + ), + ]); + let value = serde_json::to_value(&fork).unwrap(); + assert_eq!( + value["configOptions"], + json!([{"configId": "model", "value": "model-2"}]) + ); + assert_eq!( + serde_json::from_value::(value).unwrap(), + fork + ); + // `null` is an empty list, and a malformed entry fails the request. + assert_eq!( + serde_json::from_value::(json!({ + "sessionId": "sess_abc123", + "cwd": "/home/user/project", + "configOptions": null + })) + .unwrap(), + ForkSessionRequest::new("sess_abc123", "/home/user/project") + ); + assert!( + serde_json::from_value::(json!({ + "sessionId": "sess_abc123", + "cwd": "/home/user/project", + "configOptions": [{"type": "boolean", "value": true}] + })) + .is_err() + ); + } assert_eq!( serde_json::to_value( SessionCapabilities::new().options(SessionOptionsCapabilities::new()) diff --git a/agent-client-protocol-schema/src/v2/agent.rs b/agent-client-protocol-schema/src/v2/agent.rs index bb77187d6..3587254a1 100644 --- a/agent-client-protocol-schema/src/v2/agent.rs +++ b/agent-client-protocol-schema/src/v2/agent.rs @@ -1318,7 +1318,9 @@ pub struct NewSessionRequest { /// entries and duplicate `configId` values fail the request with `-32602`. The Agent MUST /// ignore an entry whose `configId` is unknown, whose `type` does not match the option, /// or whose value is not allowed when it is applied. The `configOptions` in the response contain the values the session actually - /// has. The Agent SHOULD NOT send `config_option_update` notifications for these entries. + /// has. The Agent SHOULD NOT send `config_option_update` notifications for these entries, + /// and SHOULD NOT send other `session/update` notifications caused by applying them + /// before it responds. #[cfg(feature = "unstable_session_options")] #[serde_as(deserialize_as = "DefaultOnNull")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))] @@ -1390,7 +1392,9 @@ impl NewSessionRequest { /// entries and duplicate `configId` values fail the request with `-32602`. The Agent MUST /// ignore an entry whose `configId` is unknown, whose `type` does not match the option, /// or whose value is not allowed when it is applied. The `configOptions` in the response contain the values the session actually - /// has. The Agent SHOULD NOT send `config_option_update` notifications for these entries. + /// has. The Agent SHOULD NOT send `config_option_update` notifications for these entries, + /// and SHOULD NOT send other `session/update` notifications caused by applying them + /// before it responds. #[cfg(feature = "unstable_session_options")] #[must_use] pub fn config_options(mut self, config_options: Vec) -> Self { @@ -1549,6 +1553,29 @@ pub struct ForkSessionRequest { /// source session. #[serde(default)] pub system_prompt: Option, + /// **UNSTABLE** + /// + /// This capability is not part of the spec yet, and may be removed or changed at any point. + /// + /// Initial values for the forked session's config options. + /// + /// Optional. Omitted and `null` are equivalent to an empty list. Clients MUST only send + /// this when the Agent advertises `session.options`. + /// + /// The Agent applies the entries in list order on top of the configuration the fork + /// starts with, as if the Client had called `session/set_config_option` for each entry + /// after the session was set up. Malformed entries and duplicate `configId` values fail + /// the request with `-32602`. The Agent MUST ignore an entry whose `configId` is unknown, + /// whose `type` does not match the option, or whose value is not allowed when it is + /// applied. The `configOptions` in the response contain the values the session actually + /// has. The Agent SHOULD NOT send `config_option_update` notifications for these entries, + /// and SHOULD NOT send other `session/update` notifications caused by applying them + /// before it responds. + #[cfg(feature = "unstable_session_options")] + #[serde_as(deserialize_as = "DefaultOnNull")] + #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))] + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub config_options: Vec, /// The _meta property is reserved by ACP to allow clients and agents to attach additional /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. /// Implementations MUST NOT assign meaning to keys they do not recognize. @@ -1572,6 +1599,8 @@ impl ForkSessionRequest { additional_directories: vec![], mcp_servers: vec![], system_prompt: None, + #[cfg(feature = "unstable_session_options")] + config_options: vec![], meta: None, } } @@ -1601,6 +1630,31 @@ impl ForkSessionRequest { self } + /// **UNSTABLE** + /// + /// This capability is not part of the spec yet, and may be removed or changed at any point. + /// + /// Initial values for the forked session's config options. + /// + /// Optional. Omitted and `null` are equivalent to an empty list. Clients MUST only send + /// this when the Agent advertises `session.options`. + /// + /// The Agent applies the entries in list order on top of the configuration the fork + /// starts with, as if the Client had called `session/set_config_option` for each entry + /// after the session was set up. Malformed entries and duplicate `configId` values fail + /// the request with `-32602`. The Agent MUST ignore an entry whose `configId` is unknown, + /// whose `type` does not match the option, or whose value is not allowed when it is + /// applied. The `configOptions` in the response contain the values the session actually + /// has. The Agent SHOULD NOT send `config_option_update` notifications for these entries, + /// and SHOULD NOT send other `session/update` notifications caused by applying them + /// before it responds. + #[cfg(feature = "unstable_session_options")] + #[must_use] + pub fn config_options(mut self, config_options: Vec) -> Self { + self.config_options = config_options; + self + } + /// The _meta property is reserved by ACP to allow clients and agents to attach additional /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they /// do not recognize. @@ -1777,7 +1831,9 @@ pub struct ResumeSessionRequest { /// entries and duplicate `configId` values fail the request with `-32602`. The Agent MUST /// ignore an entry whose `configId` is unknown, whose `type` does not match the option, /// or whose value is not allowed when it is applied. The `configOptions` in the response contain the values the session actually - /// has. The Agent SHOULD NOT send `config_option_update` notifications for these entries. + /// has. The Agent SHOULD NOT send `config_option_update` notifications for these entries + /// on the requesting connection. If the session is active on other connections, the + /// Agent SHOULD send `config_option_update` on those connections. /// /// The Agent applies the entries before it replays history for `replayFrom` and before /// it responds. @@ -1867,7 +1923,9 @@ impl ResumeSessionRequest { /// entries and duplicate `configId` values fail the request with `-32602`. The Agent MUST /// ignore an entry whose `configId` is unknown, whose `type` does not match the option, /// or whose value is not allowed when it is applied. The `configOptions` in the response contain the values the session actually - /// has. The Agent SHOULD NOT send `config_option_update` notifications for these entries. + /// has. The Agent SHOULD NOT send `config_option_update` notifications for these entries + /// on the requesting connection. If the session is active on other connections, the + /// Agent SHOULD send `config_option_update` on those connections. #[cfg(feature = "unstable_session_options")] #[must_use] pub fn config_options(mut self, config_options: Vec) -> Self { @@ -2393,7 +2451,8 @@ pub enum SessionStatus { /// /// `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 -/// SHOULD NOT connect to MCP servers to answer it. +/// SHOULD NOT connect to MCP servers to answer it. Agents MAY start their runtime to resolve +/// the options. The rules above still hold for it. #[cfg(feature = "unstable_session_options")] #[serde_as] #[skip_serializing_none] @@ -8918,6 +8977,43 @@ mod test_serialization { serde_json::to_value(SessionOptionsResponse::new()).unwrap(), json!({}) ); + #[cfg(feature = "unstable_session_fork")] + { + let fork = + ForkSessionRequest::new("sess_abc123", "/home/user/project").config_options(vec![ + InitialSessionConfigOption::new( + "model", + SessionConfigOptionValue::id("model-2"), + ), + ]); + let value = serde_json::to_value(&fork).unwrap(); + assert_eq!( + value["configOptions"], + json!([{"configId": "model", "type": "id", "value": "model-2"}]) + ); + assert_eq!( + serde_json::from_value::(value).unwrap(), + fork + ); + // `null` is an empty list, and a malformed entry fails the request. + assert_eq!( + serde_json::from_value::(json!({ + "sessionId": "sess_abc123", + "cwd": "/home/user/project", + "configOptions": null + })) + .unwrap(), + ForkSessionRequest::new("sess_abc123", "/home/user/project") + ); + assert!( + serde_json::from_value::(json!({ + "sessionId": "sess_abc123", + "cwd": "/home/user/project", + "configOptions": [{"type": "boolean", "value": true}] + })) + .is_err() + ); + } assert_eq!( serde_json::to_value( SessionCapabilities::new().options(SessionOptionsCapabilities::new()) diff --git a/docs/protocol/v1/draft/schema.mdx b/docs/protocol/v1/draft/schema.mdx index b272cd841..8285c6f3f 100644 --- a/docs/protocol/v1/draft/schema.mdx +++ b/docs/protocol/v1/draft/schema.mdx @@ -754,6 +754,27 @@ When omitted or empty, no additional roots are activated. When non-empty, this is the complete resulting additional-root list for the forked session. + +InitialSessionConfigOption[]} > + **UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Initial values for the forked session's config options. + +Optional. Omitted and `null` are equivalent to an empty list. Clients MUST only send +this when the Agent advertises `sessionCapabilities.options`. + +The Agent applies the entries in list order on top of the configuration the fork +starts with, as if the Client had called `session/set_config_option` for each entry +after the session was set up. Malformed entries and duplicate `configId` values fail +the request with `-32602`. The Agent MUST ignore an entry whose `configId` is unknown, +whose `type` does not match the option, or whose value is not allowed when it is +applied. The `configOptions` in the response contain the values the session actually +has. The Agent SHOULD NOT send `config_option_update` notifications for these entries, +and SHOULD NOT send other `session/update` notifications caused by applying them +before it responds. + The working directory for this session. Must be an absolute path. @@ -1044,7 +1065,9 @@ The Agent applies the entries in list order, as if the Client had called entries and duplicate `configId` values fail the request with `-32602`. The Agent MUST ignore an entry whose `configId` is unknown, whose `type` does not match the option, or whose value is not allowed when it is applied. The `configOptions` in the response contain the values the session actually -has. The Agent SHOULD NOT send `config_option_update` notifications for these entries. +has. The Agent SHOULD NOT send `config_option_update` notifications for these entries, +and SHOULD NOT send other `session/update` notifications caused by applying them +before it responds. @@ -1120,7 +1143,8 @@ Only available if the Agent supports the `sessionCapabilities.options` capabilit `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 -SHOULD NOT connect to MCP servers to answer it. +SHOULD NOT connect to MCP servers to answer it. Agents MAY start their runtime to resolve +the options. The rules above still hold for it. **Type:** Object diff --git a/docs/protocol/v1/draft/session-config-options.mdx b/docs/protocol/v1/draft/session-config-options.mdx index d44493a35..8c7aed8f3 100644 --- a/docs/protocol/v1/draft/session-config-options.mdx +++ b/docs/protocol/v1/draft/session-config-options.mdx @@ -491,7 +491,7 @@ Clients call `session/options` with the same workspace parameters as `session/ne 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`) or `session/resume` (`sessionCapabilities.resume`). +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. @@ -521,11 +521,11 @@ 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. The response is a snapshot. The options a session actually starts with are the ones in the setup response. +`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`, and `session/resume`. 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`. +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`. ```json { @@ -543,15 +543,16 @@ Clients send the values the user picked in `configOptions` on `session/new`, `se } ``` -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. +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. The option keeps its default value, or the value the Agent resolved from earlier entries. +- 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 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 diff --git a/docs/protocol/v1/draft/session-setup.mdx b/docs/protocol/v1/draft/session-setup.mdx index 3619ec9af..ba4e03f6a 100644 --- a/docs/protocol/v1/draft/session-setup.mdx +++ b/docs/protocol/v1/draft/session-setup.mdx @@ -444,7 +444,7 @@ Content delivered at system level carries more weight with the model than user t ## Initial config option values (unstable) -Agents that advertise `sessionCapabilities.options` accept a `configOptions` list on `session/new`, `session/load`, and `session/resume`. The Agent applies the entries in order, as if the Client had called `session/set_config_option` for each one after setup, and returns the resulting values in the response. Clients can get the options and allowed values before setup with `session/options`. See [Options before a session exists](/protocol/v1/draft/session-config-options#options-before-a-session-exists-unstable). +Agents that advertise `sessionCapabilities.options` accept a `configOptions` list on `session/new`, `session/load`, `session/resume`, and, when supported, `session/fork`. The Agent applies the entries in order, as if the Client had called `session/set_config_option` for each one after setup, and returns the resulting values in the response. Clients can get the options and allowed values before setup with `session/options`. See [Options before a session exists](/protocol/v1/draft/session-config-options#options-before-a-session-exists-unstable). ## Session ID diff --git a/docs/protocol/v2/draft/schema.mdx b/docs/protocol/v2/draft/schema.mdx index 16a45959e..abfbae772 100644 --- a/docs/protocol/v2/draft/schema.mdx +++ b/docs/protocol/v2/draft/schema.mdx @@ -801,6 +801,27 @@ When omitted or empty, no additional roots are activated. When non-empty, this is the complete resulting additional-root list for the forked session. + +InitialSessionConfigOption[]} > + **UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Initial values for the forked session's config options. + +Optional. Omitted and `null` are equivalent to an empty list. Clients MUST only send +this when the Agent advertises `session.options`. + +The Agent applies the entries in list order on top of the configuration the fork +starts with, as if the Client had called `session/set_config_option` for each entry +after the session was set up. Malformed entries and duplicate `configId` values fail +the request with `-32602`. The Agent MUST ignore an entry whose `configId` is unknown, +whose `type` does not match the option, or whose value is not allowed when it is +applied. The `configOptions` in the response contain the values the session actually +has. The Agent SHOULD NOT send `config_option_update` notifications for these entries, +and SHOULD NOT send other `session/update` notifications caused by applying them +before it responds. + AbsolutePath} required> The working directory for this session. Must be an absolute path. @@ -996,7 +1017,9 @@ The Agent applies the entries in list order, as if the Client had called entries and duplicate `configId` values fail the request with `-32602`. The Agent MUST ignore an entry whose `configId` is unknown, whose `type` does not match the option, or whose value is not allowed when it is applied. The `configOptions` in the response contain the values the session actually -has. The Agent SHOULD NOT send `config_option_update` notifications for these entries. +has. The Agent SHOULD NOT send `config_option_update` notifications for these entries, +and SHOULD NOT send other `session/update` notifications caused by applying them +before it responds. AbsolutePath} required> @@ -1083,7 +1106,8 @@ Only available if the Agent supports the `session.options` capability. `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 -SHOULD NOT connect to MCP servers to answer it. +SHOULD NOT connect to MCP servers to answer it. Agents MAY start their runtime to resolve +the options. The rules above still hold for it. **Type:** Object @@ -1315,7 +1339,9 @@ The Agent applies the entries in list order, as if the Client had called entries and duplicate `configId` values fail the request with `-32602`. The Agent MUST ignore an entry whose `configId` is unknown, whose `type` does not match the option, or whose value is not allowed when it is applied. The `configOptions` in the response contain the values the session actually -has. The Agent SHOULD NOT send `config_option_update` notifications for these entries. +has. The Agent SHOULD NOT send `config_option_update` notifications for these entries +on the requesting connection. If the session is active on other connections, the +Agent SHOULD send `config_option_update` on those connections. The Agent applies the entries before it replays history for `replayFrom` and before it responds. diff --git a/docs/protocol/v2/draft/session-config-options.mdx b/docs/protocol/v2/draft/session-config-options.mdx index a22b5e15c..19536a8fa 100644 --- a/docs/protocol/v2/draft/session-config-options.mdx +++ b/docs/protocol/v2/draft/session-config-options.mdx @@ -533,11 +533,11 @@ The response contains the options the session would start with: `configOptions` uses the same type and rules as on `NewSessionResponse`. `availableCommands` uses the same type as on `NewSessionResponse` and is advisory. Commands can depend on state the Agent only has once the session exists, such as MCP prompts. Agents **MAY** return a partial list or omit it. Clients **MUST** use the commands from the setup response and later `available_commands_update` notifications for the session itself. -`session/options` **MUST NOT** create or resume a session, send `session/update` notifications, add an entry to `session/list`, or change an existing session. The response is a snapshot. The options a session actually starts with are the ones in the setup response. +`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` and `session/resume`. Each entry has the same shape as `session/set_config_option` without `sessionId`. Entries **MUST** include `type`, as on `session/set_config_option`. +Clients send the values the user picked in `configOptions` on `session/new`, `session/resume`, and, when the Agent supports it, `session/fork`. Each entry has the same shape as `session/set_config_option` without `sessionId`. Entries **MUST** include `type`, as on `session/set_config_option`. ```json { @@ -554,7 +554,7 @@ Clients send the values the user picked in `configOptions` on `session/new` and } ``` -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. +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. For `session/resume`, the Agent applies the entries before it replays history for `replayFrom` and before it responds. @@ -563,6 +563,8 @@ Initial values are handled differently from `session/set_config_option`, because - 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`. - An entry with a value `type` the Agent does not support **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. The option keeps its default value, or the value the Agent resolved from earlier entries. +- 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 Agent **SHOULD NOT** send `config_option_update` notifications for these entries on the requesting connection. 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 (see [Creating a session](/protocol/v2/draft/session-setup#initial-session-state)). It sends them after the response. +- A `session/resume` can reach a session that is active on other connections. The entries change its configuration, so the Agent **SHOULD** send `config_option_update` on those connections, as for any other change. See [From the Agent](#from-the-agent). diff --git a/docs/protocol/v2/draft/session-setup.mdx b/docs/protocol/v2/draft/session-setup.mdx index 2dd7cbf5f..e1066c250 100644 --- a/docs/protocol/v2/draft/session-setup.mdx +++ b/docs/protocol/v2/draft/session-setup.mdx @@ -508,7 +508,7 @@ Content delivered at system level carries more weight with the model than user t ## Initial config option values (unstable) -Agents that advertise `session.options` accept a `configOptions` list on `session/new` and `session/resume`. The Agent applies the entries in order, as if the Client had called `session/set_config_option` for each one after setup, and returns the resulting values in the response. Clients can get the options and allowed values before setup with `session/options`. See [Options before a session exists](/protocol/v2/draft/session-config-options#options-before-a-session-exists-unstable). +Agents that advertise `session.options` accept a `configOptions` list on `session/new`, `session/resume`, and, when supported, `session/fork`. The Agent applies the entries in order, as if the Client had called `session/set_config_option` for each one after setup, and returns the resulting values in the response. Clients can get the options and allowed values before setup with `session/options`. See [Options before a session exists](/protocol/v2/draft/session-config-options#options-before-a-session-exists-unstable). ## Session ID diff --git a/docs/rfds/session-options.mdx b/docs/rfds/session-options.mdx index e902cfa15..b2204ccae 100644 --- a/docs/rfds/session-options.mdx +++ b/docs/rfds/session-options.mdx @@ -114,6 +114,8 @@ The response contains the config options the session would start with: `session/options` **MUST NOT** create or resume a session. The Agent **MUST NOT** send `session/update` notifications for it, and the call **MUST NOT** add an entry to `session/list` or change an existing session. The Agent **MAY** read workspace files and its own configuration to resolve options. It **SHOULD NOT** connect to MCP servers to answer `session/options`. +Some Agents only know their options from a running runtime, such as a subprocess that reports its models. Such an Agent **MAY** start that runtime to answer `session/options`. The rules above still hold for it: it stores no session, writes nothing to the history of the session named by `sessionId`, and adds no entry to `session/list`. Clients **SHOULD NOT** call `session/options` on a timer, because such an Agent may start its runtime for each call. See [What if the Agent has to start its runtime to know its options?](#what-if-the-agent-has-to-start-its-runtime-to-know-its-options) + The response is a snapshot. The options a session actually starts with are the ones in the session setup response. ### Initial values on session setup @@ -142,13 +144,19 @@ Clients **SHOULD** send entries in the order the Agent listed the options in the For resumed or loaded sessions, the entries apply on top of the session's restored configuration. -The Agent **SHOULD NOT** send `config_option_update` notifications for these entries, because the response already contains the resulting values. +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. + +Notifications: + +- 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 mode change or a notice that a value fell back. It sends them after the response. +- In v2, a `session/resume` can reach a session that is active on other connections. See [Version differences](#version-differences). Error handling: - An entry that does not match the schema (for example, a missing `configId` or a `value` that does not match its `type`) **MUST** fail the request with `-32602` (Invalid params). - Two entries with the same `configId` **MUST** fail the request with `-32602`. -- A well-formed entry whose `configId` is unknown, whose `type` does not match the option's type (for example, a `boolean` entry for a `select` option), or whose value is not allowed at the point it is applied, **MUST** be ignored. Options can change type between `session/options` and session setup, so this is stale state, not a Client bug. The option keeps its default value, or the value the Agent resolved from earlier entries. +- A well-formed entry whose `configId` is unknown, whose `type` does not match the option's type (for example, a `boolean` entry for a `select` option), or whose value is not allowed at the point it is applied, **MUST** be ignored. Options can change type between `session/options` and session setup, so this is stale state, not a Client bug. The option keeps its default value, or the value the Agent resolved from earlier entries. A value the option lists but the Agent's runtime refuses when it is applied, such as a model the provider no longer serves, is not allowed either. The Agent ignores it and does not fail the request, since the session already exists. - The `configOptions` in the response **MUST** contain the values the session actually has after all entries are applied. Clients compare them with what they sent to find entries the Agent ignored. ### Version differences @@ -157,18 +165,19 @@ Error handling: - The capability is `sessionCapabilities.options`, behind an unstable feature. - `session/options` returns `configOptions` and `modes`, with the same types and optionality as on `NewSessionResponse`. -- `configOptions` is accepted on `session/new`, `session/load`, and `session/resume`. As on v1 `session/set_config_option`, `type` is optional and defaults to `id`. +- `configOptions` is accepted on `session/new`, `session/load`, `session/resume`, and, when the Agent supports it, `session/fork`. As on v1 `session/set_config_option`, `type` is optional and defaults to `id`. - The existing rules for boolean options still apply. Agents only return `type: "boolean"` options from `session/options`, and Clients only send `type: "boolean"` entries in `configOptions`, when the Client advertises `sessionCapabilities.configOptions.boolean`. -- Clients **MUST NOT** send `sessionId` on `session/options` unless the Agent supports `session/load` (`loadSession`) or `session/resume` (`sessionCapabilities.resume`). +- Clients **MUST NOT** send `sessionId` on `session/options` unless the Agent supports `session/load` (`loadSession`), `session/resume` (`sessionCapabilities.resume`), or `session/fork` (`sessionCapabilities.fork`). - Modes do not get an initial value field. Agents that expose modes as a config option (category `mode`) can receive the mode through `configOptions`. - There is no `availableCommands` in the response. v1 session setup responses do not include `availableCommands`. Agents send them in a `session/update` notification after the session exists. #### v2 - The capability is `capabilities.session.options`. Supplying `{}` means supported. Omission or `null` means unsupported. -- `configOptions` is accepted on `session/new` and `session/resume`. Entries **MUST** include the `type` discriminator, as on v2 `session/set_config_option`. +- `configOptions` is accepted on `session/new`, `session/resume`, and, when the Agent supports it, `session/fork`. Entries **MUST** include the `type` discriminator, as on v2 `session/set_config_option`. - An entry with a value `type` the Agent does not support **MUST** fail the request with `-32602`, as on v2 `session/set_config_option`. - For `session/resume`, the Agent applies the entries before it replays history for `replayFrom` and before it responds. +- A `session/resume` can reach a session that is active on other connections. The entries change its configuration, so the Agent **SHOULD** send `config_option_update` on those connections, as for any other configuration change. The requesting connection gets the values in the response. The response includes optional `availableCommands`, with the same type and rules as on `NewSessionResponse`: @@ -203,7 +212,7 @@ A Client can also call `session/options` with a `sessionId` from its session lis > Tell me more about your implementation. What is your detailed implementation plan? 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. +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. @@ -235,6 +244,20 @@ Config options rarely depend on which MCP servers are connected, and starting se Clients still pass `mcpServers` on session setup requests. If a later use case needs them, an optional `mcpServers` parameter can be added to `session/options` without breaking existing Clients. +### What if the Agent has to start its runtime to know its options? + +That is allowed. An Agent that wraps another program may only learn the models, modes, and other options from a running process. It can start one for `session/options` and stop it once it has the answer. The process must not store a session, write to the history of the session named by `sessionId`, or leave anything behind that `session/list` shows. + +Such an Agent pays the start cost on every call, and anything the runtime does at startup, such as user-configured startup hooks, runs for each call too. This is why Clients should not poll. The rules constrain what the call leaves behind, not the process. An Agent can keep the started runtime and use it for the next `session/new` with the same parameters, as long as no session exists until then. + +### Why no notifications for initial values? + +The setup response carries the resulting values, so a `config_option_update` for them repeats it. + +For `session/new` and `session/fork`, the Client also learns the session ID from the response. A `session/update` sent before it names a session the Client cannot place, and v2 lets Clients drop such notifications. Anything else the Agent wants to report can follow the response. + +A v2 session can be active on several connections. The other connections do not see the response, so they get `config_option_update` like for any other change. + ### Why a list instead of a map from `configId` to value? The order of entries matters because options can depend on each other. JSON object key order is not reliable across implementations. @@ -261,3 +284,4 @@ Commands are not settings. The Client runs a command by sending it in a prompt a ## Revision history - 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. diff --git a/schema/v1/schema.unstable.json b/schema/v1/schema.unstable.json index 338ebc58a..b24ca2c1f 100644 --- a/schema/v1/schema.unstable.json +++ b/schema/v1/schema.unstable.json @@ -7100,7 +7100,7 @@ ] }, "configOptions": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nInitial values for the session's config options.\n\nOptional. Omitted and `null` are equivalent to an empty list. Clients MUST only send\nthis when the Agent advertises `sessionCapabilities.options`.\n\nThe Agent applies the entries in list order, as if the Client had called\n`session/set_config_option` for each entry after the session was set up. Malformed\nentries and duplicate `configId` values fail the request with `-32602`. The Agent MUST\nignore an entry whose `configId` is unknown, whose `type` does not match the option,\nor whose value is not allowed when it is applied. The `configOptions` in the response contain the values the session actually\nhas. The Agent SHOULD NOT send `config_option_update` notifications for these entries.", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nInitial values for the session's config options.\n\nOptional. Omitted and `null` are equivalent to an empty list. Clients MUST only send\nthis when the Agent advertises `sessionCapabilities.options`.\n\nThe Agent applies the entries in list order, as if the Client had called\n`session/set_config_option` for each entry after the session was set up. Malformed\nentries and duplicate `configId` values fail the request with `-32602`. The Agent MUST\nignore an entry whose `configId` is unknown, whose `type` does not match the option,\nor whose value is not allowed when it is applied. The `configOptions` in the response contain the values the session actually\nhas. The Agent SHOULD NOT send `config_option_update` notifications for these entries,\nand SHOULD NOT send other `session/update` notifications caused by applying them\nbefore it responds.", "type": "array", "items": { "$ref": "#/$defs/InitialSessionConfigOption" @@ -7609,6 +7609,14 @@ } ] }, + "configOptions": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nInitial values for the forked session's config options.\n\nOptional. Omitted and `null` are equivalent to an empty list. Clients MUST only send\nthis when the Agent advertises `sessionCapabilities.options`.\n\nThe Agent applies the entries in list order on top of the configuration the fork\nstarts with, as if the Client had called `session/set_config_option` for each entry\nafter the session was set up. Malformed entries and duplicate `configId` values fail\nthe request with `-32602`. The Agent MUST ignore an entry whose `configId` is unknown,\nwhose `type` does not match the option, or whose value is not allowed when it is\napplied. The `configOptions` in the response contain the values the session actually\nhas. The Agent SHOULD NOT send `config_option_update` notifications for these entries,\nand SHOULD NOT send other `session/update` notifications caused by applying them\nbefore it responds.", + "type": "array", + "items": { + "$ref": "#/$defs/InitialSessionConfigOption" + }, + "x-deserialize-default-on-null": true + }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility)", "type": ["object", "null"], @@ -7690,7 +7698,7 @@ "x-method": "session/status" }, "SessionOptionsRequest": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest parameters for `session/options`, which returns the config options a session\nwould start with, without creating or resuming a session.\n\nOnly available if the Agent supports the `sessionCapabilities.options` capability.\n\n`session/options` MUST NOT create or resume a session, send `session/update`\nnotifications, add an entry to `session/list`, or change an existing session. Agents\nSHOULD NOT connect to MCP servers to answer it.", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest parameters for `session/options`, which returns the config options a session\nwould start with, without creating or resuming a session.\n\nOnly available if the Agent supports the `sessionCapabilities.options` capability.\n\n`session/options` MUST NOT create or resume a session, send `session/update`\nnotifications, add an entry to `session/list`, or change an existing session. Agents\nSHOULD NOT connect to MCP servers to answer it. Agents MAY start their runtime to resolve\nthe options. The rules above still hold for it.", "type": "object", "properties": { "cwd": { diff --git a/schema/v2/schema.unstable.json b/schema/v2/schema.unstable.json index 1c555091e..8650366c8 100644 --- a/schema/v2/schema.unstable.json +++ b/schema/v2/schema.unstable.json @@ -8338,7 +8338,7 @@ ] }, "configOptions": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nInitial values for the session's config options.\n\nOptional. Omitted and `null` are equivalent to an empty list. Clients MUST only send\nthis when the Agent advertises `session.options`.\n\nThe Agent applies the entries in list order, as if the Client had called\n`session/set_config_option` for each entry after the session was set up. Malformed\nentries and duplicate `configId` values fail the request with `-32602`. The Agent MUST\nignore an entry whose `configId` is unknown, whose `type` does not match the option,\nor whose value is not allowed when it is applied. The `configOptions` in the response contain the values the session actually\nhas. The Agent SHOULD NOT send `config_option_update` notifications for these entries.", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nInitial values for the session's config options.\n\nOptional. Omitted and `null` are equivalent to an empty list. Clients MUST only send\nthis when the Agent advertises `session.options`.\n\nThe Agent applies the entries in list order, as if the Client had called\n`session/set_config_option` for each entry after the session was set up. Malformed\nentries and duplicate `configId` values fail the request with `-32602`. The Agent MUST\nignore an entry whose `configId` is unknown, whose `type` does not match the option,\nor whose value is not allowed when it is applied. The `configOptions` in the response contain the values the session actually\nhas. The Agent SHOULD NOT send `config_option_update` notifications for these entries,\nand SHOULD NOT send other `session/update` notifications caused by applying them\nbefore it responds.", "type": "array", "items": { "$ref": "#/$defs/InitialSessionConfigOption" @@ -8860,6 +8860,14 @@ } ] }, + "configOptions": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nInitial values for the forked session's config options.\n\nOptional. Omitted and `null` are equivalent to an empty list. Clients MUST only send\nthis when the Agent advertises `session.options`.\n\nThe Agent applies the entries in list order on top of the configuration the fork\nstarts with, as if the Client had called `session/set_config_option` for each entry\nafter the session was set up. Malformed entries and duplicate `configId` values fail\nthe request with `-32602`. The Agent MUST ignore an entry whose `configId` is unknown,\nwhose `type` does not match the option, or whose value is not allowed when it is\napplied. The `configOptions` in the response contain the values the session actually\nhas. The Agent SHOULD NOT send `config_option_update` notifications for these entries,\nand SHOULD NOT send other `session/update` notifications caused by applying them\nbefore it responds.", + "type": "array", + "items": { + "$ref": "#/$defs/InitialSessionConfigOption" + }, + "x-deserialize-default-on-null": true + }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Omitted and `null` are equivalent and mean no metadata.\nImplementations MUST NOT assign meaning to keys they do not recognize.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", "type": ["object", "null"], @@ -8941,7 +8949,7 @@ "x-method": "session/status" }, "SessionOptionsRequest": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest parameters for `session/options`, which returns the config options a session\nwould start with, without creating or resuming a session.\n\nOnly available if the Agent supports the `session.options` capability.\n\n`session/options` MUST NOT create or resume a session, send `session/update`\nnotifications, add an entry to `session/list`, or change an existing session. Agents\nSHOULD NOT connect to MCP servers to answer it.", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest parameters for `session/options`, which returns the config options a session\nwould start with, without creating or resuming a session.\n\nOnly available if the Agent supports the `session.options` capability.\n\n`session/options` MUST NOT create or resume a session, send `session/update`\nnotifications, add an entry to `session/list`, or change an existing session. Agents\nSHOULD NOT connect to MCP servers to answer it. Agents MAY start their runtime to resolve\nthe options. The rules above still hold for it.", "type": "object", "properties": { "cwd": { @@ -9068,7 +9076,7 @@ ] }, "configOptions": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nInitial values for the session's config options.\n\nOptional. Omitted and `null` are equivalent to an empty list. Clients MUST only send\nthis when the Agent advertises `session.options`.\n\nThe Agent applies the entries in list order, as if the Client had called\n`session/set_config_option` for each entry after the session was set up. Malformed\nentries and duplicate `configId` values fail the request with `-32602`. The Agent MUST\nignore an entry whose `configId` is unknown, whose `type` does not match the option,\nor whose value is not allowed when it is applied. The `configOptions` in the response contain the values the session actually\nhas. The Agent SHOULD NOT send `config_option_update` notifications for these entries.\n\nThe Agent applies the entries before it replays history for `replayFrom` and before\nit responds.", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nInitial values for the session's config options.\n\nOptional. Omitted and `null` are equivalent to an empty list. Clients MUST only send\nthis when the Agent advertises `session.options`.\n\nThe Agent applies the entries in list order, as if the Client had called\n`session/set_config_option` for each entry after the session was set up. Malformed\nentries and duplicate `configId` values fail the request with `-32602`. The Agent MUST\nignore an entry whose `configId` is unknown, whose `type` does not match the option,\nor whose value is not allowed when it is applied. The `configOptions` in the response contain the values the session actually\nhas. The Agent SHOULD NOT send `config_option_update` notifications for these entries\non the requesting connection. If the session is active on other connections, the\nAgent SHOULD send `config_option_update` on those connections.\n\nThe Agent applies the entries before it replays history for `replayFrom` and before\nit responds.", "type": "array", "items": { "$ref": "#/$defs/InitialSessionConfigOption"