From 112c8f634031a2e5e9c89f8823655e9173f323fd Mon Sep 17 00:00:00 2001 From: "fabrizio.scarponi" Date: Thu, 19 Feb 2026 11:24:19 +0100 Subject: [PATCH] RFD:Add flag config option type for boolean on/off toggles --- docs/rfds/flag-config-option.mdx | 53 ++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 docs/rfds/flag-config-option.mdx diff --git a/docs/rfds/flag-config-option.mdx b/docs/rfds/flag-config-option.mdx new file mode 100644 index 00000000..fbd1f85d --- /dev/null +++ b/docs/rfds/flag-config-option.mdx @@ -0,0 +1,53 @@ +--- +title: "Flag Config Option Type" +--- + +Author(s): [fscarponi](https://github.com/fscarponi) + +## Elevator pitch + +Add a new `flag` type to session configuration options, enabling agents to expose simple boolean ON/OFF toggles (e.g., "Brave Mode", "Read Only", "Produce Report") as first-class config options alongside the existing `select` type. + +## Status quo + +Currently, `SessionConfigKind` only supports the `select` type, which allows agents to expose dropdown-style selectors with a list of named values. This works well for choosing models, modes, or reasoning levels. + +However, there is no native way to represent a simple boolean on/off toggle. To expose a flag-like option today, agents must use a `select` with two artificial options (e.g., "on"/"off"), and clients need custom, non-agnostic logic to detect that a particular select is actually a boolean toggle. This defeats the purpose of a standardized protocol. + +## What we propose to do about it + +- Add a `SessionConfigFlag` struct with a `current_value: bool` field +- Add a `Flag(SessionConfigFlag)` variant to the `SessionConfigKind` enum, discriminated by `"type": "flag"` +- Add a `SessionConfigOptionValue` enum (untagged: `String` | `Bool`) so that `SetSessionConfigOptionRequest.value` can accept both string values (for `select`) and boolean values (for `flag`) +- Provide convenience constructors and `From` impls for ergonomic usage +- Update documentation and regenerate schema files + +## Shiny future + +Clients can natively render boolean config options as toggle switches or checkboxes, without any custom logic. Agents can expose flags like "Brave Mode", "Produce Report", or "Read Only" in a standardized way that any ACP-compliant client understands out of the box. + +## Implementation details and plan + +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 + +## Frequently asked questions + +### 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. + +### 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. + +## Revision history + +- Initial proposal