v2 Idempotency Keys

Elevator pitch

What are you proposing to change?

• Give every method a documented retry class. A Client then knows whether a request is safe to send again as is, safe to send again with a key, or not resent at all.
• Add an optional idempotencyKey parameter to session/prompt. The Client generates the key and sends the same key on every attempt. The Agent inserts the user message at most once for that key and answers retries with the messageId of the original.

Status quo

How do things work today and what problems does this cause? Why would we change things?

A lost response has an unknown outcome

• The Client retries, and the first message was inserted. The Agent now has two user messages and does the work twice. Model usage is spent twice, and tool calls with side effects, such as commits, deployments, or sent messages, run again.
• The Client doesn’t retry, and the message was never inserted. The user’s input is dropped without an error.

When responses get lost

Retry safety isn’t written down per method

What we propose to do about it

What are you proposing to improve the situation?

Give every method a retry class

The idempotencyKey parameter

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "session/prompt",
  "params": {
    "sessionId": "sess_abc123def456",
    "idempotencyKey": "0b6f3c1e-8d2a-4c57-9a41-5e2f7d90c3ab",
    "prompt": [
      {
        "type": "text",
        "text": "Run the database migration"
      }
    ]
  }
}

• Agents that advertise capabilities.session MUST support the key.
• The field is optional. Omitted and null are equivalent and mean no key. The Agent handles the prompt without duplicate detection, as it does today.
• When present, it is an opaque, case-sensitive string of 1 to 255 characters. The Agent MUST reject any other value with -32602 (Invalid params) and MUST NOT treat it as omitted.
• The Client generates the key. Clients SHOULD use a UUID (RFC 9562) or another random value with at least as much entropy. Clients SHOULD NOT derive the key from user content or put sensitive data in it.
• One key identifies one submission. The Client creates the key when the user submits the input, not when it writes the request, and stores it with the pending input. It sends the same key on every attempt, including after reconnecting or restarting. It uses a new key for a new submission, including when the user sends the same text again on purpose.
• Clients MUST NOT send the same key with a different prompt.
• Each attempt is its own JSON-RPC request with its own id. The key is what links the attempts.

How the Agent handles a keyed prompt

• The response. A retry gets the original messageId and nothing else. The Agent doesn’t start a second round of work for the message. Whether it continues work that stopped before it finished is up to the Agent, as it is after any restart. The Client learns the session’s current activity from live updates or from the session/resume snapshot.
• Errors leave the key unused. An error response to session/prompt already means the message was not inserted. The Agent records nothing, and the Client can send the same prompt with the same key again.
• A reused key. The Agent MUST NOT insert a second message for a key it has recorded. If a request carries a recorded key with a different prompt, the Agent either answers as for a retry or, if it notices the difference, rejects the request with -32602. Agents are not required to compare prompts. After such a -32602, the key stays recorded for the first prompt.
• Cancelling. $/cancel_request for any pending request with the key withdraws a prompt that is not inserted yet. The Agent then answers every pending request for that key with -32800. session/cancel and session/close answer held prompts the same way they do today.
• Keys stay private. The Agent doesn’t echo keys in session updates, session/list results, or replayed history, so one Client doesn’t see another Client’s keys. A key is not a credential. It only has meaning in a session the caller can already prompt.

How long a key lasts

• Retained messages. For a prompt whose inserted message the Agent retains, the Agent MUST recognize the key for as long as it retains the message. This holds across connections and Agent restarts. It follows the existing rule that a retained message keeps its messageId: if the Agent would still replay the message, it still recognizes the key.
• Live-only messages. For a prompt whose message the Agent doesn’t retain, such as a locally handled command, the Agent MUST recognize the key while the session stays active on a connection. After that it MAY forget it.
• Once the Agent no longer has the message or the session, it MAY forget the key. A prompt with a forgotten key is a new submission.
• Clients SHOULD resend a pending prompt as soon as they have resumed the session. A Client that has held a prompt for a long time, such as since a previous day, SHOULD show it to the user instead of resending it. By then the Agent may have discarded the message under its own history retention.

• stdio. While the process runs, a record in memory is enough. The cases that need the key are a crashed or restarted Agent process and a restarted Client, so the record only helps if it is in the stored session.
• Remote transports. A retry may reach a different process or node than the original request. The record belongs in the storage the session is loaded from, not in per-connection or per-node memory. A Client may also resend an HTTP POST that failed before 202 Accepted without reconnecting.

Shiny future

How will things play out once this feature exists?

• A Client stores a key with each pending prompt. After a dropped connection or a crash, it resumes the session and sends the pending prompts again. Each one is inserted once, and the Client gets the messageId it needs to reconcile its optimistic message.
• Client SDKs generate a key for every prompt by default and resend on transport failures without asking the application. Applications that persist pending input pass their own key.
• SDK and Client authors read one table to learn which requests they may retry.

Implementation details and plan

Tell me more about your implementation. What is your detailed implementation plan?

Method audit

Client to Agent requests

Agent to Client requests

Notifications

Prior art

• The Client generates the key, and the server uses it “to recognize subsequent retries of the same request” (Stripe and the IETF draft).
• The key is optional, and a request is only protected when it carries one (AIP-155).
• The key travels in the request body, not in a header, so it works on every transport (AWS, Google). ACP has no headers on stdio or WebSocket.
• The server records a key when the operation takes effect, not when the request arrives, so a request that fails early can be sent again with the same key (Stripe v1).

• Only one method takes a key. Stripe accepts one on every POST.
• There is no time window. Stripe keeps a key for 24 hours or 30 days. Here a key lasts as long as the message it belongs to.
• The Agent doesn’t have to detect a key reused with a different request. Stripe, AWS, and the IETF draft make that an error. AIP-155 doesn’t address it.
• HTTP APIs answer a retry of an in-progress request with 409 and expect the client to poll. ACP requests can stay pending, so the Agent answers the retry when it answers the original.

Adapter validation

• Prompt keys need no extra storage. The adapter derives the ID from the key, for example a UUIDv5 of the sessionId and the key, in place of a random UUID. The runtime then writes the key and the message in one step.
• The adapter does the lookup itself. Neither runtime can be relied on to refuse a repeated ID. Before it submits a keyed prompt, the adapter looks for the derived ID among its pending prompts and in the stored session.
• Finding the ID after a restart means reading history. The adapter keeps an in-memory set of the session’s user message IDs. It fills the set from the session’s history once, on the first keyed prompt after a restart, and adds each ID when it inserts a message. The set is a cache. The stored session stays the record. Filling it is about the work of a replay, and a replay the Client asked for can fill it. claude-agent-acp’s replay already reads the messages before each compaction, which getSessionMessages alone leaves out, and the lookup can use the same read. codex-acp pages thread/turns/list with full items.
• There is no stored prompt to compare a retry with. The runtimes store the prompt in their own form, and Claude Code itself ignores the text when it skips a repeated ID. This is why comparing prompts is not required.
• Keys for locally handled commands stay in memory. These commands report status or set a value, so running one again after a restart does no harm.

Plan

1. Add an optional, nullable idempotencyKey to PromptRequest in the v2 schema, as an IdempotencyKey string type with a length of 1 to 255. Keep it strict: a malformed value fails with -32602.
2. Document the retry classes in the v2 overview and on each method’s page, and add the keyed-prompt rules to the prompt lifecycle, session setup, and transport pages. Replace the “outcome remains uncertain” paragraph in the prompt lifecycle with the keyed behavior.
3. Add serialization and schema coverage for a valid key, null, an empty string, a string over 255 characters, and a non-string value.
4. Exercise these traces in SDK tests and conformance suites: a retry on the same connection, a retry after session/resume on a new connection, a retry after an Agent restart with a stored session, a retry while the prompt is held, a retry after an error, the same key in another session, and a retry of a prompt that was inserted during active work.
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.

Frequently asked questions

What questions have arisen over the course of authoring this document or during subsequent discussions?

Why is there no capability?

Why not key session/new and session/fork?

• A duplicate is cheap. It is an unused session, not repeated work. If the session/new response was lost, the Client never learned the session ID, so the session is never prompted, and Agents commonly don’t store a session before its first prompt.
• Adapters could not keep the promise. The Claude Agent SDK and Codex choose the ID of a forked session themselves, so an adapter could only remember the key until it restarts. On stdio, a restart is the only time the key would be needed.
• It can be added later without a breaking change. Whatever an Agent could promise here is best effort, and a best-effort key needs no capability. An Agent that ignores it behaves as it does today.

Why is there no error for a reused key?

Why is there no time window?

Why a field in params and not _meta, an HTTP header, or the JSON-RPC id?

• _meta carries custom information that receivers may ignore and intermediaries may drop. The Agent acts on this value, so it belongs in the schema, where a malformed value fails with -32602.
• An Idempotency-Key HTTP header doesn’t exist on stdio or WebSocket, and the rules here apply to a JSON-RPC request, not to an HTTP exchange.
• The JSON-RPC id is scoped to a connection, and proxies may rewrite it. A retry after reconnecting can’t reuse it.

Why not accept a key on every request?

Does a key make the work run exactly once?

Why does a retry wait for a held prompt and not get an error?

Doesn’t stream resumption on the remote transport solve this?

Should user_message updates echo the key?

What about v1?

What alternative approaches did you consider, and why did you settle on this one?

• Document retry classes only. This is the smallest change and still worth doing, but it leaves session/prompt unsafe to retry, which is the case that costs users the most.
• Stricter rules. Agents would compare a retry’s prompt with the original, return a dedicated error for a reused key, keep keys for a fixed window, and write the key and the message in one transaction. Adapters have no stored prompt to compare with and no storage of their own for keys (see Adapter validation). See also Why is there no error for a reused key? and Why is there no time window?.
• Let the Client choose the messageId. A Client-chosen ID would deduplicate prompts. The Message ID RFD rejected Client-generated message IDs. An Agent may still derive its messageId from the key, which keeps the ID Agent-owned.
• Resolve by lookup instead of retry. The Client could call session/resume with replay and look for its message. Replay may omit live-only or discarded messages, matching by content is unreliable, and the Client still couldn’t tell “not inserted yet” from “never arrived”.

Revision history

• 2026-11-13: Initial draft.