From 2f6a6691c400fc1c3af8126f17d62dd69d9264d7 Mon Sep 17 00:00:00 2001 From: Ben Brandt Date: Wed, 18 Nov 2026 11:10:06 +0100 Subject: [PATCH] docs(rfd): record the implementation status of four v2 RFDs The plans of the Background Work, Replay Complete, Prompt, and Idempotency Keys RFDs did not say which steps are done. Background Work recorded only phase 1, Replay Complete recorded two of four steps, and the Prompt plan still ended on a choice between a v1 opt-in and a preview flow for v2. - Add a dated status note to each plan, with what is done in this repository, in the SDKs, in claude-agent-acp and codex-acp, and in Zed. - Replace the Prompt RFD's open choice with what happened: v2 is developed as its own version, so no v1 opt-in was needed. - Add a revision-history entry to each RFD. --- docs/rfds/v2/background-work.mdx | 7 +++++++ docs/rfds/v2/idempotency-keys.mdx | 6 ++++++ docs/rfds/v2/prompt.mdx | 13 +++++++------ docs/rfds/v2/session-replay-complete.mdx | 7 +++++++ 4 files changed, 27 insertions(+), 6 deletions(-) diff --git a/docs/rfds/v2/background-work.mdx b/docs/rfds/v2/background-work.mdx index ff6999c5b..80343f39e 100644 --- a/docs/rfds/v2/background-work.mdx +++ b/docs/rfds/v2/background-work.mdx @@ -288,6 +288,12 @@ claude-agent-acp also has to declare the SDK's `perTaskStopAffordance` whenever 2. Implement in `claude-agent-acp` and `codex-acp`, and in at least one Client. 3. Adjust from that experience before v2 is stabilized. +Status on 2026-11-18: + +- **Phase 1 is done.** The schema changes landed on 2026-10-30. The rules are on the v2 [Tool Calls](/protocol/v2/tool-calls#cancelling-tool-calls) and [Prompt Lifecycle](/protocol/v2/prompt-lifecycle#background-work) pages. +- **Phase 2 is partly done.** `claude-agent-acp` reports the `background` list and the `paused` status, and handles `tool_call/cancel` and `terminal/cancel`, on v2 connections. Zed reads the list and sends both requests for items that advertise `cancel`. `codex-acp` does not report the list or handle the two requests yet. +- **Phase 3 is ongoing.** The changes of 2026-11-02 and 2026-11-09 in the revision history came from the `claude-agent-acp` implementation. + ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? @@ -380,6 +386,7 @@ Not in this RFD. The `background` list belongs on the session-level `state_updat ## Revision history +- 2026-11-18: Recorded the status of the implementation plan. - 2026-11-17: Worded the status rules as rules for the Agent. An Agent does not move a tool call back to `pending`, including with `status: null`, and does not change a final status. A Client applies each `tool_call_update` as an upsert, so it shows the latest status it received. - 2026-11-17: On `session/cancel`, the Agent **MUST** send `$/cancel_request` for each pending permission request it stops waiting for. This was a SHOULD. The Agent still decides which requests belong to the cancelled work, and requests for listed work stay open. A Client that receives `$/cancel_request` for a pending permission request or elicitation **SHOULD** dismiss the prompt and answer with the cancellation result. Clients **SHOULD** dismiss permission prompts for a closed session. - 2026-11-09: An Agent that knows a tool call's work continues in the background keeps that tool call open and lists it. Background work without a tool call to report it on, or whose tool call already has a final status, is reported on a tool call the Agent starts itself. Final statuses stay final. This replaces vendor-specific list items such as the earlier `_claude/task` in `claude-agent-acp`. The tool call and prompt lifecycle pages say that an Agent may report tool calls the model did not request, and that work continuing after a final status gets a new tool call. diff --git a/docs/rfds/v2/idempotency-keys.mdx b/docs/rfds/v2/idempotency-keys.mdx index 140cf6a03..aa9cfb0da 100644 --- a/docs/rfds/v2/idempotency-keys.mdx +++ b/docs/rfds/v2/idempotency-keys.mdx @@ -266,6 +266,11 @@ Both runtimes store an ID that the adapter chooses with each user message, and b 5. Have Client SDKs generate keys by default, and give Agent SDKs a helper that records keys for a session. 6. Implement the derived ID and the lookup in claude-agent-acp and codex-acp. +Status on 2026-11-18: + +- **Steps 1 to 3 are done.** The field and its tests are in the v2 schema crate. The rules are on the v2 pages, with the retry classes in one table on the [overview page](/protocol/v2/overview#retrying-requests). +- **Steps 4 to 6 are open.** The SDKs do not send or record keys yet, and neither adapter implements the lookup. + ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? @@ -335,6 +340,7 @@ This RFD doesn't change v1. A v1 `session/prompt` response arrives at the end of ## Revision history +- 2026-11-18: Recorded the status of the implementation plan. - 2026-11-17: The retry classes and the class of each method are documented in one table on the overview page, not on each method's page. - 2026-11-17: An Agent may insert or discard held prompts when the connection that sent them ends. Withdrawing a held prompt with `$/cancel_request` is best effort. `session/cancel` and `session/close` are the guaranteed ways to drop one. - 2026-11-17: Steps 1 and 3 landed. `idempotencyKey` and the `IdempotencyKey` type are in the v2 schema, and a malformed key fails deserialization. From step 2, the keyed-prompt rules are on the prompt lifecycle, session setup, and transports pages. The retry classes are not on the method pages yet. diff --git a/docs/rfds/v2/prompt.mdx b/docs/rfds/v2/prompt.mdx index 17660e2fc..321f23819 100644 --- a/docs/rfds/v2/prompt.mdx +++ b/docs/rfds/v2/prompt.mdx @@ -365,14 +365,13 @@ The v2 schema and guides define the insertion-receipt response. The implementati 6. Add serialization and schema coverage for the idle update with an `error`, without one, and with `error: null`, and verify that an `error` beside another stop reason is treated as an unknown field. Exercise a failure after insertion but before the response is sent: the response still succeeds and the idle update reports the failure. 7. Update examples and generated artifacts, then run `npm run generate` and `npm run check`. -The schema and serialization tests establish the wire shape. Adapters still need to implement and validate insertion timing, live reporting for local commands, replay identity for retained messages, and reporting failures after insertion. The [foreground state contract](#foreground-state-contract) defines current-state synchronization on resume and gives guidance for cancellation races. Adapters and conformance suites should exercise the guide's traces, including concurrent requests and late answers. Those rules are separate from the insertion receipt's identity and do not require another prompt ID. Explicit queueing and steering capabilities, sender identity, safe retries, and submission idempotency guarantees remain outside this change. +The schema and serialization tests establish the wire shape. Adapters implement and validate insertion timing, live reporting for local commands, replay identity for retained messages, and reporting failures after insertion. The [foreground state contract](#foreground-state-contract) defines current-state synchronization on resume and gives guidance for cancellation races. Adapters and conformance suites should exercise the guide's traces, including concurrent requests and late answers. Those rules are separate from the insertion receipt's identity and do not require another prompt ID. Explicit queueing and steering capabilities, sender identity, safe retries, and submission idempotency guarantees remain outside this change. -Depending on how the rest of v2 testing goes, we can either: +Status on 2026-11-18: -1. Make this an opt-in "future-flag" capability on v1 so people can experiment, but it would be an unstable feature regardless. -2. We establish a preview/beta flow for v2 - -We definitely need 2 regardless, and can likely handle this in a similar "unstable" manner as we do for current unstabilized features. It's likely timing will work out that we can just do it that way. If for some reason the timing doesn't work out, we can start experimenting with an unstable capability or some `_meta` flag. +- **The schema, tests, and docs are done.** That is steps 1 to 3 and 5 to 7. +- **Step 4 belongs to the adapters and conformance suites.** `claude-agent-acp` and `codex-acp` both implement this lifecycle on v2 connections. +- **No v1 opt-in was needed.** An earlier version of this plan considered an opt-in capability on v1 for experiments. v2 is developed as its own protocol version behind the `unstable_protocol_v2` feature, so that option was dropped. ## Frequently asked questions @@ -454,6 +453,8 @@ Codex's app-server makes the same split. A failed turn ends with `turn/completed ## Revision history +2026-11-18: Recorded the status of the implementation plan. + 2026-10-29: Message IDs are unique per message type, not across the session. Prompts sent during active work are inserted or held in order rather than rejected, and held prompts get `-32800` on cancel. 2026-04-13: Initial draft diff --git a/docs/rfds/v2/session-replay-complete.mdx b/docs/rfds/v2/session-replay-complete.mdx index e2da4454e..3171d712d 100644 --- a/docs/rfds/v2/session-replay-complete.mdx +++ b/docs/rfds/v2/session-replay-complete.mdx @@ -142,6 +142,12 @@ When the Agent crashes during a resume, the Client knows that the replay was cut 3. **SDKs.** Expose the variant in the SDKs. An Agent SDK helper can buffer live updates while a replay runs. A Client SDK must deliver the updates of a resuming session before the response. The Client knows the session ID before the request, so the SDK can register the session handler first. [kotlin-sdk#146](https://github.com/agentclientprotocol/kotlin-sdk/pull/146) does this for the Kotlin SDK. 4. **Adapters.** claude-agent-acp already sends one end event after the replay, as a vendor extension in `_meta` that the Client opts in to. See [#1361](https://github.com/agentclientprotocol/claude-agent-acp/pull/1361). Move it to `replay_complete` on v2 connections, and add the marker to the other v2 adapters. +Status on 2026-11-18: + +- **Steps 1 and 2 are done.** They landed on 2026-11-13. +- **Step 3 is done for the TypeScript and Rust SDKs.** Both expose the variant, and their example Agents send it. The Kotlin SDK delivers a resuming session's updates before the response since [kotlin-sdk#146](https://github.com/agentclientprotocol/kotlin-sdk/pull/146). It has no v2 types yet. +- **Step 4 is done.** `claude-agent-acp` and `codex-acp` send `replay_complete` on v2 connections. + ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? @@ -225,6 +231,7 @@ These were open while the RFD was a draft. They are closed for the v2 Preview. ## Revision history +- 2026-11-18: Recorded the status of the implementation plan. - 2026-11-17: Closed the open questions for the v2 Preview. The update keeps the name `replay_complete` and stays required with no capability. The marker carries no request identifier, cursor, or known-gaps flag. Each can be added later as an optional field. The rule against two pending replaying resumes for one session is on the [Session Setup](/protocol/v2/session-setup#replay-complete) page. - 2026-11-17: In v2, the parent's marker is the freshness boundary for a child's work state and capabilities. Before, it was the response. `subagent_update` is in the stable v2 schema, so the child session rules are on the stable [Session Setup](/protocol/v2/session-setup#child-sessions) and [Subagents](/protocol/v2/subagents#resuming) pages. - 2026-11-13: Steps 1 and 2 landed. `replay_complete` is in the v2 schema as `SessionUpdate::ReplayComplete`, without a separate feature flag, like the other v2 RFDs. The rules are in the v2 [Session Setup](/protocol/v2/session-setup#replay-complete) page. The child session rules are in its draft copy, because `subagent_update` is still unstable.