Skip to content

docs(unstable-v2): state the error codes for tool_call/cancel and terminal/cancel - #2869

Merged
benbrandt merged 1 commit into
mainfrom
docs/v2-cancel-error-codes
Nov 18, 2026
Merged

benbrandt merged 1 commit into
mainfrom
docs/v2-cancel-error-codes

Conversation

@benbrandt

Copy link
Copy Markdown
Member

Summary

The v2 error page and the tool calls page gave different error codes for a tool_call/cancel or terminal/cancel request on an item that does not advertise capabilities.cancel. This states one answer on the error page. Both edits are made in the stable page and its draft/ copy.

Changes

  • Item does not advertise cancel: -32602. The rule for capability-gated methods requires -32601, and it read as covering these two methods. The tool calls page, the Background Work RFD and the schema descriptions all give -32602. The error page now says the two methods are gated per tool call or terminal, not by a capability in initialize, and that an Agent that implements them answers -32602.
  • Unknown sessionId: -32002. The unknown-session rule already requires -32002 for any session-scoped request. Its list of methods now names tool_call/cancel and terminal/cancel.

Why -32602 for the item

  • The request can race with the update that clears cancel, for example when the tool call finishes. -32601 would tell the Client that the Agent has no such method.
  • An Agent does not always know why an item cannot be cancelled. Unknown, already finished and never cancellable get the same code.

An Agent that implements neither method still answers -32601.

Follow-up

claude-agent-acp answers -32602 when the sessionId of a cancel request is unknown, because it looks the item up before it checks the session. That needs a fix in the adapter.

Checks

  • Prettier and typos pass on the changed files.
  • All links and anchors in the changed files resolve.

…minal/cancel

The error page gave two answers for a cancel request on an item that
does not advertise `capabilities.cancel`. Its rule for capability-gated
methods requires `-32601`, while the tool calls page gives `-32602`.

- Say that the two methods are gated per tool call or terminal, not by a
  capability in `initialize`, and that an Agent that implements them
  answers `-32602` for an item that does not advertise `cancel`.
- Name both methods in the unknown-session rule, which requires `-32002`
  for any session-scoped request.
@benbrandt
benbrandt requested a review from a team as a code owner November 18, 2026 12:29
@benbrandt
benbrandt enabled auto-merge (squash) November 18, 2026 12:30
@benbrandt
benbrandt merged commit 6239402 into main Nov 18, 2026
10 checks passed
@benbrandt
benbrandt deleted the docs/v2-cancel-error-codes branch November 18, 2026 12:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant