From 7bc8db683905273a2c6323d308726bdb9a30cd76 Mon Sep 17 00:00:00 2001 From: Ben Brandt Date: Wed, 18 Nov 2026 10:12:30 +0100 Subject: [PATCH] feat(unstable-v2): remove pattern from elicitation string properties ACP added `pattern` on top of MCP's string schema, which the elicitation form schema is based on. A Client then evaluates a regular expression it did not write, and the Elicitation RFD had to require bounded evaluation for it. MCP's string schema has no `pattern`. - Remove `pattern` from `StringPropertySchema` in the v2 types and schema. The v2 type ignores a `pattern` it receives. - Drop the keyword from the elicitation page, stable and draft. - Add an Elicitation section and checklist items to the migration guide. - Record the removal in the tracking RFD and note it in the Elicitation RFD. v1 keeps `pattern`. --- .../src/v2/elicitation.rs | 55 +++++++------------ docs/protocol/v2/draft/elicitation.mdx | 19 +++---- docs/protocol/v2/draft/schema.mdx | 16 ------ docs/protocol/v2/elicitation.mdx | 19 +++---- docs/protocol/v2/migration.mdx | 55 +++++++++++-------- docs/protocol/v2/schema.mdx | 16 ------ docs/rfds/elicitation.mdx | 3 + docs/rfds/v2/overview.mdx | 2 + schema/v2/schema.json | 5 -- schema/v2/schema.unstable.json | 5 -- 10 files changed, 77 insertions(+), 118 deletions(-) diff --git a/agent-client-protocol-schema/src/v2/elicitation.rs b/agent-client-protocol-schema/src/v2/elicitation.rs index 8565dee01..5541203da 100644 --- a/agent-client-protocol-schema/src/v2/elicitation.rs +++ b/agent-client-protocol-schema/src/v2/elicitation.rs @@ -164,12 +164,6 @@ pub struct StringPropertySchema { /// Optional. Omitted and `null` are equivalent and mean there is no maximum length constraint. #[serde(default)] pub max_length: Option, - /// Pattern the string must match, in ECMA-262 regular expression syntax. - /// - /// Optional. Omitted and `null` are equivalent and mean there is no pattern constraint. - #[cfg_attr(feature = "schemars", schemars(extend("format" = "regex")))] - #[serde(default)] - pub pattern: Option, /// String format. /// /// Optional. Omitted and `null` are equivalent and mean there is no format constraint. @@ -281,13 +275,6 @@ impl StringPropertySchema { self } - /// Pattern the string must match, in ECMA-262 regular expression syntax. - #[must_use] - pub fn pattern(mut self, pattern: impl IntoOption) -> Self { - self.pattern = pattern.into_option(); - self - } - /// String format. #[must_use] pub fn format(mut self, format: impl IntoOption) -> Self { @@ -2897,29 +2884,29 @@ mod tests { } #[test] - fn schema_string_pattern_serialization() { - let schema = ElicitationSchema::new().property( - "name", - StringPropertySchema::new() - .min_length(1) - .max_length(64) - .pattern("^[a-zA-Z_][a-zA-Z0-9_]*$"), - true, - ); - - let json = serde_json::to_value(&schema).unwrap(); - assert_eq!(json["properties"]["name"]["type"], "string"); - assert_eq!( - json["properties"]["name"]["pattern"], - "^[a-zA-Z_][a-zA-Z0-9_]*$" - ); + fn schema_string_ignores_pattern() { + let schema: ElicitationSchema = serde_json::from_value(json!({ + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" + } + }, + "required": ["name"] + })) + .unwrap(); - let roundtripped: ElicitationSchema = serde_json::from_value(json).unwrap(); - if let ElicitationPropertySchema::String(s) = roundtripped.properties.get("name").unwrap() { - assert_eq!(s.pattern.as_deref(), Some("^[a-zA-Z_][a-zA-Z0-9_]*$")); - } else { + let ElicitationPropertySchema::String(name) = schema.properties.get("name").unwrap() else { panic!("expected String variant"); - } + }; + assert_eq!(name.min_length, Some(1)); + assert_eq!(name.max_length, Some(64)); + + let json = serde_json::to_value(&schema).unwrap(); + assert_eq!(json["properties"]["name"].get("pattern"), None); } #[test] diff --git a/docs/protocol/v2/draft/elicitation.mdx b/docs/protocol/v2/draft/elicitation.mdx index 1c1803a60..3092f31c5 100644 --- a/docs/protocol/v2/draft/elicitation.mdx +++ b/docs/protocol/v2/draft/elicitation.mdx @@ -129,16 +129,15 @@ progress actually resumes. `elicitation/complete` is not itself a state update. `requestedSchema` is a flat object with `type: "object"`, `properties`, and optional `required`, `title`, and `description`. Each property is one of: -| Property | Schema | Optional keywords | -| ------------- | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | -| Text | `type: "string"` | `minLength`, `maxLength`, `pattern`, `format` (`email`, `uri`, `date`, `date-time`), `default` | -| Single select | `type: "string"` with `enum` (values) or `oneOf` (`const` and `title` options) | `default` | -| Number | `type: "number"` or `type: "integer"` | `minimum`, `maximum`, `default` | -| Boolean | `type: "boolean"` | `default` | -| Multi select | `type: "array"` with `items` of `{ "type": "string", "enum": [...] }` or `{ "anyOf": [...] }` (`const` and `title` options) | `minItems`, `maxItems`, `default` | - -Every property may also have `title` and `description`. `pattern` uses -ECMA-262 regular expression syntax, as in JSON Schema. Clients treat an unknown +| Property | Schema | Optional keywords | +| ------------- | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | +| Text | `type: "string"` | `minLength`, `maxLength`, `format` (`email`, `uri`, `date`, `date-time`), `default` | +| Single select | `type: "string"` with `enum` (values) or `oneOf` (`const` and `title` options) | `default` | +| Number | `type: "number"` or `type: "integer"` | `minimum`, `maximum`, `default` | +| Boolean | `type: "boolean"` | `default` | +| Multi select | `type: "array"` with `items` of `{ "type": "string", "enum": [...] }` or `{ "anyOf": [...] }` (`const` and `title` options) | `minItems`, `maxItems`, `default` | + +Every property may also have `title` and `description`. Clients treat an unknown `format` as plain text. Accepted `content` maps each answered property name to its value: a string for text and single-select properties, a number for `number` and `integer`, a boolean for `boolean`, and an array of strings for multi-select. Unanswered properties are omitted, not set to `null`. Custom or future property types may use other JSON values. Clients **SHOULD** validate submitted values before responding, and Agents diff --git a/docs/protocol/v2/draft/schema.mdx b/docs/protocol/v2/draft/schema.mdx index cedd58c1d..511d9ab04 100644 --- a/docs/protocol/v2/draft/schema.mdx +++ b/docs/protocol/v2/draft/schema.mdx @@ -5484,14 +5484,6 @@ Optional. Omitted and `null` are equivalent and mean there is no minimum length Must contain at least one option when present. Optional. Omitted and `null` are equivalent and mean no titled single-select choices are declared by `oneOf`. - - - Pattern the string must match, in ECMA-262 regular expression syntax. - -Optional. Omitted and `null` are equivalent and mean there is no pattern constraint. - - - Format: `regex` - Optional title for the property. @@ -11505,14 +11497,6 @@ Optional. Omitted and `null` are equivalent and mean there is no minimum length Must contain at least one option when present. Optional. Omitted and `null` are equivalent and mean no titled single-select choices are declared by `oneOf`. - - - Pattern the string must match, in ECMA-262 regular expression syntax. - -Optional. Omitted and `null` are equivalent and mean there is no pattern constraint. - - - Format: `regex` - Optional title for the property. diff --git a/docs/protocol/v2/elicitation.mdx b/docs/protocol/v2/elicitation.mdx index 425297f08..066ed9a9e 100644 --- a/docs/protocol/v2/elicitation.mdx +++ b/docs/protocol/v2/elicitation.mdx @@ -129,16 +129,15 @@ progress actually resumes. `elicitation/complete` is not itself a state update. `requestedSchema` is a flat object with `type: "object"`, `properties`, and optional `required`, `title`, and `description`. Each property is one of: -| Property | Schema | Optional keywords | -| ------------- | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | -| Text | `type: "string"` | `minLength`, `maxLength`, `pattern`, `format` (`email`, `uri`, `date`, `date-time`), `default` | -| Single select | `type: "string"` with `enum` (values) or `oneOf` (`const` and `title` options) | `default` | -| Number | `type: "number"` or `type: "integer"` | `minimum`, `maximum`, `default` | -| Boolean | `type: "boolean"` | `default` | -| Multi select | `type: "array"` with `items` of `{ "type": "string", "enum": [...] }` or `{ "anyOf": [...] }` (`const` and `title` options) | `minItems`, `maxItems`, `default` | - -Every property may also have `title` and `description`. `pattern` uses -ECMA-262 regular expression syntax, as in JSON Schema. Clients treat an unknown +| Property | Schema | Optional keywords | +| ------------- | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | +| Text | `type: "string"` | `minLength`, `maxLength`, `format` (`email`, `uri`, `date`, `date-time`), `default` | +| Single select | `type: "string"` with `enum` (values) or `oneOf` (`const` and `title` options) | `default` | +| Number | `type: "number"` or `type: "integer"` | `minimum`, `maximum`, `default` | +| Boolean | `type: "boolean"` | `default` | +| Multi select | `type: "array"` with `items` of `{ "type": "string", "enum": [...] }` or `{ "anyOf": [...] }` (`const` and `title` options) | `minItems`, `maxItems`, `default` | + +Every property may also have `title` and `description`. Clients treat an unknown `format` as plain text. Accepted `content` maps each answered property name to its value: a string for text and single-select properties, a number for `number` and `integer`, a boolean for `boolean`, and an array of strings for multi-select. Unanswered properties are omitted, not set to `null`. Custom or future property types may use other JSON values. Clients **SHOULD** validate submitted values before responding, and Agents diff --git a/docs/protocol/v2/migration.mdx b/docs/protocol/v2/migration.mdx index b7ea5ba98..9c38ed994 100644 --- a/docs/protocol/v2/migration.mdx +++ b/docs/protocol/v2/migration.mdx @@ -35,28 +35,28 @@ v2 keeps the underlying JSON-RPC framing, except that request IDs can no longer ### Method changes -| v1 method | v2 | -| --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `initialize` | Unchanged name. Params and result restructured | -| `authenticate` | Renamed to `auth/login` for protocol-driven authentication methods | -| `logout` (gated by `agentCapabilities.auth.logout`) | Renamed to `auth/logout`. Required when `authMethods` is non-empty. No logout capability marker | -| `session/new` | `mcpServers` now optional. Response no longer includes `modes` | -| `session/load` | **Removed**. Use `session/resume` with `"replayFrom": { "type": "start" }` | -| `session/resume` | Gains optional `replayFrom`. Required (no capability marker) | -| `session/list` | Required. No capability | -| `session/close` | Required. No capability. Cancels ongoing work like `session/cancel`: the final updates and idle `cancelled` state come before the close response, and prompts not yet inserted get `-32800` | -| `session/delete` | Still optional via `session.delete`. Deleting a session active on any connection now cancels its work as if closed, and later requests for it, including `session/resume`, fail with `-32002` | -| `session/prompt` | Gains optional `idempotencyKey`. **Response semantics redesigned** (see [Prompt lifecycle](#the-new-prompt-lifecycle)) | -| `session/cancel` | Unchanged name. Completion now reported via `state_update` instead of the prompt response. Prompts not yet inserted get `-32800` | -| `session/set_mode` | **Removed**. Use `session/set_config_option` | -| `session/set_config_option` | Required when the Agent advertises config options. No capability. Params use `configId` and a required `type` discriminator (see [Config options](#session-modes-become-config-options)) | -| `session/request_permission` | Unchanged name. Params restructured (required `title`, optional `subject`) | -| `session/update` | Unchanged name. Update variants changed (see below) | -| `elicitation/create` | Unchanged shape. Exactly one of `sessionId` or `requestId` is required. Session-scoped requests follow the foreground-state contract (`requires_action`). An unknown action is handled as `cancel` | -| `elicitation/complete` | Unchanged | -| `fs/read_text_file`, `fs/write_text_file` | **Removed** | -| `terminal/create`, `terminal/output`, `terminal/release`, `terminal/wait_for_exit`, `terminal/kill` | **Removed** | -| `$/cancel_request` | Unchanged, except for an inserted `session/prompt` (see Cancellation) | +| v1 method | v2 | +| --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `initialize` | Unchanged name. Params and result restructured | +| `authenticate` | Renamed to `auth/login` for protocol-driven authentication methods | +| `logout` (gated by `agentCapabilities.auth.logout`) | Renamed to `auth/logout`. Required when `authMethods` is non-empty. No logout capability marker | +| `session/new` | `mcpServers` now optional. Response no longer includes `modes` | +| `session/load` | **Removed**. Use `session/resume` with `"replayFrom": { "type": "start" }` | +| `session/resume` | Gains optional `replayFrom`. Required (no capability marker) | +| `session/list` | Required. No capability | +| `session/close` | Required. No capability. Cancels ongoing work like `session/cancel`: the final updates and idle `cancelled` state come before the close response, and prompts not yet inserted get `-32800` | +| `session/delete` | Still optional via `session.delete`. Deleting a session active on any connection now cancels its work as if closed, and later requests for it, including `session/resume`, fail with `-32002` | +| `session/prompt` | Gains optional `idempotencyKey`. **Response semantics redesigned** (see [Prompt lifecycle](#the-new-prompt-lifecycle)) | +| `session/cancel` | Unchanged name. Completion now reported via `state_update` instead of the prompt response. Prompts not yet inserted get `-32800` | +| `session/set_mode` | **Removed**. Use `session/set_config_option` | +| `session/set_config_option` | Required when the Agent advertises config options. No capability. Params use `configId` and a required `type` discriminator (see [Config options](#session-modes-become-config-options)) | +| `session/request_permission` | Unchanged name. Params restructured (required `title`, optional `subject`) | +| `session/update` | Unchanged name. Update variants changed (see below) | +| `elicitation/create` | String properties lose `pattern` (see [Elicitation](#elicitation)). Otherwise unchanged. Exactly one of `sessionId` or `requestId` is required. Session-scoped requests follow the foreground-state contract (`requires_action`). An unknown action is handled as `cancel` | +| `elicitation/complete` | Unchanged | +| `fs/read_text_file`, `fs/write_text_file` | **Removed** | +| `terminal/create`, `terminal/output`, `terminal/release`, `terminal/wait_for_exit`, `terminal/kill` | **Removed** | +| `$/cancel_request` | Unchanged, except for an inserted `session/prompt` (see Cancellation) | ### `session/update` variant changes @@ -698,6 +698,15 @@ In v1, `cancelled` meant the prompt turn was cancelled. In v2 the Client also se While foreground work as a whole is blocked on a permission response, the Agent **SHOULD** report `state_update` with `requires_action`. Once reported, it **MUST** report `running` when foreground progress resumes, or `idle` if the work ends without resuming. A permission request for independent background activity does not by itself change the foreground state, and resolving a permission request does not itself imply `running`. Apply the [aggregate transition rules](/protocol/v2/prompt-lifecycle#waiting-for-user-action), including with concurrent requests and late answers. +## Elicitation + +`elicitation/create` and `elicitation/complete` keep their shape, with one removal. A string property in a form's `requestedSchema` no longer takes `pattern`. + +v1 added `pattern` on top of MCP's string schema. v2 has the same string keywords as MCP: `minLength`, `maxLength`, `format`, and `default`. + +- Agents stop sending `pattern` and check the submitted value themselves. +- Clients stop evaluating `pattern`. + ## Plans The v1 `plan` update was a flat entries list with no identity and no room to grow. v2 replaces it with `plan_update`, whose payload is a tagged union keyed by a required `planId`: @@ -953,6 +962,7 @@ See [Errors](/protocol/v2/error). 16. **Parsing.** Make enum handling open: preserve unknown variants where a safe fallback exists. 17. **Errors.** Return the now-required [error codes](#errors): `-32601`, `-32002` with `data.sessionId`, and `-32600` before initialization or for a late `initialize`. 18. **Subagents.** Exposing subagents is optional. If you do, announce each child with `subagent_update` on its parent before any update or request that carries the child's `sessionId`. Report the child's work on its own `sessionId`, mirror its `state_update` in the parent's `subagent_update.state`, and report messages from a parent to a child as `session_message`. Advertise `capabilities.cancel` only for a child whose work you can cancel on its own. Report `unknown` when you can no longer observe a session's foreground work. +19. **Elicitation.** Stop sending `pattern` on string properties, and validate the submitted value yourself. ## Migration checklist: Clients @@ -972,6 +982,7 @@ See [Errors](/protocol/v2/error). 14. **Cancellation.** After `session/cancel`, keep accepting updates and wait for the idle `state_update` with `stopReason: "cancelled"` as confirmation. 15. **Parsing.** Preserve unknown enum variants, tolerate unknown `sessionUpdate` types, and read commands and their `input` as tagged unions. Replace the `configOptions` and `availableCommands` lists you hold with the lists in each setup response, including lists from updates that arrived before the response. An omitted list means none. Replace the command list on each `available_commands_update`, including `[]` to clear it. 16. **Subagents.** Handle `subagent_update`, which needs no capability and cannot be ignored as an unknown update. Register each child session, attribute its updates and requests to it, and show `session_message` entries as messages between sessions. Send nothing for a child except responses to its requests, `session/cancel` while the child advertises `capabilities.cancel`, and `tool_call/cancel` or `terminal/cancel` for an item that advertises its own. Discard child state and capabilities when you resume the parent. +17. **Elicitation.** Stop evaluating `pattern` on string properties. v2 forms don't carry it. ## Migration checklist: SDKs diff --git a/docs/protocol/v2/schema.mdx b/docs/protocol/v2/schema.mdx index c0edd24a0..b88ca2ef1 100644 --- a/docs/protocol/v2/schema.mdx +++ b/docs/protocol/v2/schema.mdx @@ -3531,14 +3531,6 @@ Optional. Omitted and `null` are equivalent and mean there is no minimum length Must contain at least one option when present. Optional. Omitted and `null` are equivalent and mean no titled single-select choices are declared by `oneOf`. - - - Pattern the string must match, in ECMA-262 regular expression syntax. - -Optional. Omitted and `null` are equivalent and mean there is no pattern constraint. - - - Format: `regex` - Optional title for the property. @@ -8309,14 +8301,6 @@ Optional. Omitted and `null` are equivalent and mean there is no minimum length Must contain at least one option when present. Optional. Omitted and `null` are equivalent and mean no titled single-select choices are declared by `oneOf`. - - - Pattern the string must match, in ECMA-262 regular expression syntax. - -Optional. Omitted and `null` are equivalent and mean there is no pattern constraint. - - - Format: `regex` - Optional title for the property. diff --git a/docs/rfds/elicitation.mdx b/docs/rfds/elicitation.mdx index 7d264d690..6044a474d 100644 --- a/docs/rfds/elicitation.mdx +++ b/docs/rfds/elicitation.mdx @@ -273,6 +273,8 @@ MUST use a regex engine or execution limits that bound evaluation time and resource use. A malicious or pathological pattern MUST NOT be allowed to block Client UI or unboundedly consume resources. +ACP v2 removes `pattern`. MCP's string schema does not have it. See the [v2 migration guide](/protocol/v2/migration#elicitation). + Known formats include `email`, `uri`, `date`, and `date-time`. Other string format values are annotations. Implementations MUST preserve unknown formats when storing, replaying, proxying, or forwarding schemas and MUST NOT reject a @@ -931,6 +933,7 @@ For v1, we recommend starting with JSON Schema validation only. If more complex ## Revision history +- 2026-11-17: Noted that ACP v2 removes `pattern` from string properties, to match MCP's string schema. - 2026-10-29: Agents translate, rather than pass through, elicitation capabilities for MCP servers, since `{}` means no modes in ACP but form support in MCP. - 2026-07-22: Moved to Completed and stabilized elicitation in the protocol artifacts. Audited the data model and safety guidance against the locked MCP 2026-07-28 release candidate and documented ACP's direct-request, capability, scope, and URL-completion differences. - 2026-07-09: Moved to Preview. diff --git a/docs/rfds/v2/overview.mdx b/docs/rfds/v2/overview.mdx index 7d3401b3f..62b42cc97 100644 --- a/docs/rfds/v2/overview.mdx +++ b/docs/rfds/v2/overview.mdx @@ -59,6 +59,7 @@ This list tracks every breaking change in v2. Smaller changes without their own - Remove the dedicated session modes API from v2. This includes the `modes` session response fields, `session/set_mode`, `current_mode_update`, and the `SessionMode*` types. - Agents should expose mode-like and model-related state through [Session Config Options](../session-config-options.mdx) instead of dedicated mode or model selector APIs. - Remove the v1 Client filesystem and terminal execution surface from v2. This includes `clientCapabilities.fs`, the top-level `clientCapabilities.terminal` field, `fs/*` methods, `terminal/*` methods, and the Client-owned semantics of v1 terminal tool-call content. Terminal authentication remains separate under `capabilities.auth.terminal`. +- Remove `pattern` from elicitation string properties. MCP's string schema, which the form schema is based on, does not have it. - Add [Agent-owned, display-only terminal output](./terminal-output.mdx). Tool calls reference terminals by `terminalId`; terminal upserts carry `command`, absolute `cwd`, replay snapshots, and exit status; terminal output chunks append independently base64-encoded bytes. The display surface is baseline v2 and does not add Client execution or control methods. - Make [plan variants](./plan-variants.mdx) the default v2 plan shape by replacing the old `plan` session update with item-based `plan_update`. - Replace the v1 split between `tool_call` and `tool_call_update` with a single [tool-call update](./tool-call-updates.mdx) upsert shape keyed by `toolCallId`. @@ -137,6 +138,7 @@ With the needed breaking changes, as much as possible I am targeting having a co ## Revision history +- 2026-11-17: Removed `pattern` from elicitation string properties in v2, to match MCP's string schema. - 2026-11-17: Added Subagent Sessions to the v2 Preview scope and to the change list, together with the `unknown` state. The v2 rules are on the v2 [Subagents](/protocol/v2/subagents) page. - 2026-11-17: Added `idempotencyKey` on `session/prompt` to the change list now that it is in the v2 schema. - 2026-11-13: Added the v2 Idempotency Keys RFD for retry classes on every method and an optional `idempotencyKey` on `session/prompt`. diff --git a/schema/v2/schema.json b/schema/v2/schema.json index ce2734179..8be85eec4 100644 --- a/schema/v2/schema.json +++ b/schema/v2/schema.json @@ -2276,11 +2276,6 @@ "format": "uint32", "minimum": 0 }, - "pattern": { - "description": "Pattern the string must match, in ECMA-262 regular expression syntax.\n\nOptional. Omitted and `null` are equivalent and mean there is no pattern constraint.", - "type": ["string", "null"], - "format": "regex" - }, "format": { "description": "String format.\n\nOptional. Omitted and `null` are equivalent and mean there is no format constraint.", "anyOf": [ diff --git a/schema/v2/schema.unstable.json b/schema/v2/schema.unstable.json index f43552423..283530005 100644 --- a/schema/v2/schema.unstable.json +++ b/schema/v2/schema.unstable.json @@ -2366,11 +2366,6 @@ "format": "uint32", "minimum": 0 }, - "pattern": { - "description": "Pattern the string must match, in ECMA-262 regular expression syntax.\n\nOptional. Omitted and `null` are equivalent and mean there is no pattern constraint.", - "type": ["string", "null"], - "format": "regex" - }, "format": { "description": "String format.\n\nOptional. Omitted and `null` are equivalent and mean there is no format constraint.", "anyOf": [