feat(unstable): Add config option type for boolean on/off toggles (#576)

* Add flag config option type for boolean on/off toggles

* Update to make this less breaking

---------

Co-authored-by: Ben Brandt <benjamin.j.brandt@gmail.com>

Author: fscarponi

Cargo.toml

@@ -25,6 +25,7 @@ unstable = [
     "unstable_session_stop",
     "unstable_session_usage",
     "unstable_message_id",
+    "unstable_boolean_config",
 ]
 unstable_auth_methods = []
 unstable_cancel_request = []
@@ -36,6 +37,7 @@ unstable_session_resume = []
 unstable_session_stop = []
 unstable_session_usage = []
 unstable_message_id = []
+unstable_boolean_config = []
 
 [[bin]]
 name = "generate"

docs/protocol/draft/schema.mdx

@@ -726,26 +726,41 @@ Sets the current value for a session configuration option.
 
 Request parameters for setting a session configuration option.
 
-**Type:** Object
-
-**Properties:**
+**Type:** Union
 
-<ResponseField name="_meta" type={"object | null"} >
-  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.
+<ResponseField name="boolean" type="object">
+A boolean value (`type: "boolean"`).
 
-See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)
+<Expandable title="Properties">
 
+<ResponseField name="type" type={"string"} required>
+  The discriminator value. Must be `"boolean"`.
 </ResponseField>
-<ResponseField name="configId" type={<a href="#sessionconfigid">SessionConfigId</a>} required>
-  The ID of the configuration option to set.
+<ResponseField name="value" type={"boolean"} required>
+  The boolean value.
 </ResponseField>
-<ResponseField name="sessionId" type={<a href="#sessionid">SessionId</a>} required>
-  The ID of the session to set the configuration option for.
+
+</Expandable>
 </ResponseField>
-<ResponseField name="value" type={<a href="#sessionconfigvalueid">SessionConfigValueId</a>} required>
-  The ID of the configuration option value to set.
+
+<ResponseField name="Object" type="object">
+A `SessionConfigValueId` string value.
+
+This is the default when `type` is absent on the wire. Unknown `type`
+values with string payloads also gracefully deserialize into this
+variant.
+
+<Expandable title="Properties">
+
+<ResponseField
+  name="value"
+  type={<a href="#sessionconfigvalueid">SessionConfigValueId</a>}
+  required
+>
+  The value ID.
+</ResponseField>
+
+</Expandable>
 </ResponseField>
 
 #### <span class="font-mono">SetSessionConfigOptionResponse</span>
@@ -3381,6 +3396,22 @@ Whether the agent supports `session/stop`.
 
 </ResponseField>
 
+## <span class="font-mono">SessionConfigBoolean</span>
+
+**UNSTABLE**
+
+This capability is not part of the spec yet, and may be removed or changed at any point.
+
+A boolean on/off toggle session configuration option payload.
+
+**Type:** Object
+
+**Properties:**
+
+<ResponseField name="currentValue" type={"boolean"} required>
+  The current value of the boolean option.
+</ResponseField>
+
 ## <span class="font-mono">SessionConfigGroupId</span>
 
 Unique identifier for a session configuration option value group.
@@ -3397,11 +3428,12 @@ Unique identifier for a session configuration option.
 
 A session configuration option selector and its current state.
 
-Single-value selector (dropdown).
+**Type:** Union
 
-**Type:** Object
+<ResponseField name="select" type="object">
+Single-value selector (dropdown).
 
-**Properties:**
+<Expandable title="Properties">
 
 <ResponseField
   name="currentValue"
@@ -3417,6 +3449,31 @@ Single-value selector (dropdown).
 >
   The set of selectable options.
 </ResponseField>
+<ResponseField name="type" type={"string"} required>
+  The discriminator value. Must be `"select"`.
+</ResponseField>
+
+</Expandable>
+</ResponseField>
+
+<ResponseField name="boolean" type="object">
+**UNSTABLE**
+
+This capability is not part of the spec yet, and may be removed or changed at any point.
+
+Boolean on/off toggle.
+
+<Expandable title="Properties">
+
+<ResponseField name="currentValue" type={"boolean"} required>
+  The current value of the boolean option.
+</ResponseField>
+<ResponseField name="type" type={"string"} required>
+  The discriminator value. Must be `"boolean"`.
+</ResponseField>
+
+</Expandable>
+</ResponseField>
 
 ## <span class="font-mono">SessionConfigOptionCategory</span>
 

docs/rfds/boolean-config-option.mdx

@@ -19,7 +19,7 @@ However, there is no native way to represent a simple boolean on/off toggle. To
 
 - Add a `SessionConfigBoolean` struct with a `current_value: bool` field
 - Add a `Boolean(SessionConfigBoolean)` variant to the `SessionConfigKind` enum, discriminated by `"type": "boolean"`
-- Add a `SessionConfigOptionValue` enum (untagged: `String` | `Bool`) so that `SetSessionConfigOptionRequest.value` can accept both string values (for `select`) and boolean values (for `flag`)
+- Add a `SessionConfigOptionValue` internally-tagged enum so that `SetSessionConfigOptionRequest` can carry both string values (for `select`) and boolean values (for `boolean`) with an explicit `type` discriminator
 - Provide convenience constructors and `From` impls for ergonomic usage
 - Update documentation and regenerate schema files
 
@@ -65,7 +65,9 @@ In a `session/new` response (or any response containing `configOptions`):
 
 ### Wire format: setting a boolean option
 
-The `session/set_config_option` request uses a string value, consistent with `select` options:
+The `session/set_config_option` request carries a `type` discriminator alongside the `value`. The `type` field describes the _shape_ of the value, not the option kind.
+
+When `type` is absent the value is treated as a `SessionConfigValueId` string, preserving backwards compatibility with existing clients:
 
 ```json
 {
@@ -75,11 +77,27 @@ The `session/set_config_option` request uses a string value, consistent with `se
   "params": {
     "sessionId": "sess_abc123",
     "configId": "brave_mode",
+    "type": "boolean",
     "value": true
   }
 }
 ```
 
+For select options the `type` field can be omitted (defaults to `value_id`):
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "method": "session/set_config_option",
+  "params": {
+    "sessionId": "sess_abc123",
+    "configId": "mode",
+    "value": "code"
+  }
+}
+```
+
 The response returns the full set of config options with current values, as with `select`:
 
 ```json
@@ -108,15 +126,17 @@ The response returns the full set of config options with current values, as with
 }
 ```
 
-A working implementation is available at: https://github.com/fscarponi/agent-client-protocol/tree/fabrizio.scarponi/flag-config-option
-
 Key changes:
 
-1. `SessionConfigFlag` struct with `current_value: bool`
-2. `Flag` variant in `SessionConfigKind` (tagged via `"type": "flag"`)
-3. `SessionConfigOptionValue` untagged enum (`String` | `Bool`) replacing `SessionConfigValueId` in `SetSessionConfigOptionRequest.value`
-4. `From` impls ensure backward compatibility — existing code passing strings still compiles
-5. Wire-level backward compatible: existing JSON payloads with string values remain valid
+1. `SessionConfigBoolean` struct with `current_value: bool`
+2. `Boolean(SessionConfigBoolean)` variant in `SessionConfigKind` (tagged via `"type": "boolean"`)
+3. `SessionConfigOptionValue` enum using `#[serde(tag = "type")]` with a `#[serde(untagged)]` fallback variant — the same pattern as `AuthMethod`:
+   - `Boolean { value: bool }` — matched when `type` is `"boolean"`
+   - `ValueId { value: SessionConfigValueId }` — untagged fallback when `type` is absent or unrecognised
+4. `SessionConfigOptionValue` is flattened (`#[serde(flatten)]`) onto `SetSessionConfigOptionRequest`, producing top-level `type` and `value` fields on the wire
+5. The `value` field type change in `SetSessionConfigOptionRequest` is gated behind `#[cfg(feature = "unstable_boolean_config")]` — without the feature the field remains `SessionConfigValueId`
+6. `From` impls (`&str`, `SessionConfigValueId`, `bool`) ensure ergonomic construction
+7. Wire-level backward compatible: existing JSON payloads without a `type` field remain valid via the untagged fallback
 
 ### Client capabilities
 
@@ -126,12 +146,13 @@ Per the existing protocol design, clients that receive a config option with an u
 
 ### What alternative approaches did you consider, and why did you settle on this one?
 
-We considered reusing the existing `select` type with a convention (e.g., options named "on"/"off"), but this would require clients to implement non-agnostic detection logic, which contradicts the goal of a standardized protocol. A dedicated `flag` type is cleaner and lets clients render the appropriate UI control without guessing.
+We considered reusing the existing `select` type with a convention (e.g., options named "on"/"off"), but this would require clients to implement non-agnostic detection logic, which contradicts the goal of a standardized protocol. A dedicated `boolean` type is cleaner and lets clients render the appropriate UI control without guessing.
 
 ### Is this a breaking change?
 
-On the wire/JSON level: no. `SessionConfigOptionValue` uses `#[serde(untagged)]`, so existing string payloads deserialize correctly. On the Rust API level: the type of `SetSessionConfigOptionRequest.value` changed, but `From` impls ensure source compatibility for users of the `new()` constructor.
+On the wire/JSON level: no. When `type` is absent the value is treated as a `SessionConfigValueId`, so existing payloads deserialize correctly. On the Rust API level: the type of `SetSessionConfigOptionRequest.value` changes, but this is gated behind `unstable_boolean_config`. Without the feature flag the stable API is unchanged. With the feature flag, `From` impls ensure source compatibility for users of the `new()` constructor.
 
 ## Revision history
 
 - 2026-02-24: Initial proposal
+- 2026-03-05: Updated to reflect final implementation — `flag` renamed to `boolean`, value type changed from untagged `String | Bool` enum to internally-tagged enum with `type` discriminator and untagged `ValueId` fallback, feature-gated behind `unstable_boolean_config`

schema/schema.unstable.json

@@ -2882,6 +2882,17 @@
       },
       "type": "object"
     },
+    "SessionConfigBoolean": {
+      "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA boolean on/off toggle session configuration option payload.",
+      "properties": {
+        "currentValue": {
+          "description": "The current value of the boolean option.",
+          "type": "boolean"
+        }
+      },
+      "required": ["currentValue"],
+      "type": "object"
+    },
     "SessionConfigGroupId": {
       "description": "Unique identifier for a session configuration option value group.",
       "type": "string"
@@ -2911,6 +2922,22 @@
           },
           "required": ["type"],
           "type": "object"
+        },
+        {
+          "allOf": [
+            {
+              "$ref": "#/$defs/SessionConfigBoolean"
+            }
+          ],
+          "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nBoolean on/off toggle.",
+          "properties": {
+            "type": {
+              "const": "boolean",
+              "type": "string"
+            }
+          },
+          "required": ["type"],
+          "type": "object"
         }
       ],
       "properties": {
@@ -3475,6 +3502,39 @@
       ]
     },
     "SetSessionConfigOptionRequest": {
+      "anyOf": [
+        {
+          "description": "A boolean value (`type: \"boolean\"`).",
+          "properties": {
+            "type": {
+              "const": "boolean",
+              "type": "string"
+            },
+            "value": {
+              "description": "The boolean value.",
+              "type": "boolean"
+            }
+          },
+          "required": ["type", "value"],
+          "type": "object"
+        },
+        {
+          "description": "A [`SessionConfigValueId`] string value.\n\nThis is the default when `type` is absent on the wire. Unknown `type`\nvalues with string payloads also gracefully deserialize into this\nvariant.",
+          "properties": {
+            "value": {
+              "allOf": [
+                {
+                  "$ref": "#/$defs/SessionConfigValueId"
+                }
+              ],
+              "description": "The value ID."
+            }
+          },
+          "required": ["value"],
+          "title": "value_id",
+          "type": "object"
+        }
+      ],
       "description": "Request parameters for setting a session configuration option.",
       "properties": {
         "_meta": {
@@ -3497,17 +3557,9 @@
             }
           ],
           "description": "The ID of the session to set the configuration option for."
-        },
-        "value": {
-          "allOf": [
-            {
-              "$ref": "#/$defs/SessionConfigValueId"
-            }
-          ],
-          "description": "The ID of the configuration option value to set."
         }
       },
-      "required": ["sessionId", "configId", "value"],
+      "required": ["sessionId", "configId"],
       "type": "object",
       "x-method": "session/set_config_option",
       "x-side": "agent"