Request Cancellation Mechanism

• Author(s): Artem Bukhonov
• Champion: @benbrandt

​

Elevator pitch

​

Status quo

• cancellation should be handled for each feature separately
• some languages that support handy cancellation mechanisms (C#, Kotlin, etc.) can’t implement general-purpose request cancellation using ACP low-level machinery, and rather developers should manually call per-feature cancellation methods

​

What we propose to do about it

• Optional: Declared through capabilities exchange during initialization
• Unavailable for initialize request (which happens before capabilities exchange)
• Flexible: Provides two response options when cancellation is received:
  1. An error response with the standard cancellation error code (-32800)
  2. A valid response with partial or cancelled data (when meaningful partial results exist)

​

Shiny future

• SDK integration layer: Default mechanism that ACP SDKs can automatically wire to native language cancellation (C# CancellationToken, Kotlin Job, Go context.Context, JavaScript AbortController, etc.)
• Individual JSON-RPC request cancellation without affecting other concurrent requests
• Universal fallback for any request when feature-specific cancellation methods don’t exist
• Consistent cancellation behavior from both external $/cancelRequest and internal cancellation triggers
• Standard error response (-32800) or partial results when requests are cancelled regardless of cancellation source

​

Implementation details and plan

​

Protocol Changes

​

Capability Declaration

interface CancellationCapabilities {
  request?: boolean; // Default: false
}

interface ClientCapabilities {
  // existing capabilities...
  cancellation?: CancellationCapabilities;
}

interface AgentCapabilities {
  // existing capabilities...
  cancellation?: CancellationCapabilities;
}

​

Cancellation Method

interface CancelNotification {
  method: "$/cancelRequest";
  params: {
    id: string | number; // ID of request to cancel
  };
}

​

Cancellation Behavior

​

Prerequisites

• A party MUST declare { cancellation: { request: true } } in their capabilities to handle $/cancelRequest notifications for their requests
• The other party can send $/cancelRequest to cancel requests if the recipient declared support
• Until capabilities are exchanged, NO requests can be cancelled
• The initialize request CANNOT be cancelled as it occurs before capability exchange
• Any requests after initialize (which performs capability negotiation) CAN be cancelled if the recipient declared support

​

Responsibility for Support Checking

• Check the recipient’s capabilities before sending $/cancelRequest
• Only send $/cancelRequest if the recipient declared supportsRequestCancellation: true
• Not send $/cancelRequest notifications to parties that don’t support them

• Perform special handling for unsupported cancellation requests
• Return custom errors for unsupported $/cancelRequest notifications

​

Cancellation Processing

1. MUST cancel the corresponding request activity and all nested activities
2. MUST send one of these responses for the original request:
   • Error response with code -32800 (Cancelled)
   • Valid response with appropriate data (partial results or cancellation marker)

​

Internal Cancellation

• Client-side examples: User closes IDE, switches to different project, file becomes unavailable
• Agent-side examples: LLM context limit reached, internal timeout, resource constraints

1. Stop the request processing immediately
2. Send the same -32800 (Cancelled) error response as if $/cancelRequest was received
3. Ensure consistent behavior regardless of cancellation source

​

Error Code

• Code: -32800
• Message: “Cancelled”
• Meaning: The request was cancelled

​

Frequently asked questions

​

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

• Serves as a default cancellation layer that SDK implementations can easily map to native language cancellation mechanisms
• Proven pattern familiar to developers from LSP ecosystem
• Works across all JSON-RPC transports (HTTP, WebSocket, stdio, pipes)
• Provides universal fallback when feature-specific cancellation doesn’t exist
• Complements existing feature-specific methods rather than replacing them

​

How does this relate to existing cancellation mechanisms like session/cancel?

• $/cancelRequest: Generic cancellation for any JSON-RPC request by ID
• session/cancel: Feature-specific cancellation with additional semantics (e.g., cancels entire prompt turn context, triggers specific cleanup logic)

• Domain-specific semantics and behavior
• Structured cleanup for complex operations
• Context-aware cancellation logic

• Default cancellation layer that bridges programming language cancellation mechanisms (C# CancellationToken, Kotlin Job, Go context.Context, etc.) with ACP
• Universal fallback for any request when no feature-specific method exists
• Simple ID-based targeting for SDK convenience
• Standardized error responses

​

Example: Cascading Cancellation Flow

​

What happens if a request completes before the cancellation is processed?

1. Send the normal response (not a cancellation error)
2. Ignore the subsequent cancellation notification for that request ID

​

How should implementations handle cascading cancellation?

1. Cancel the primary request activity
2. Propagate cancellation to any nested/child requests
3. Clean up resources associated with the entire request tree
4. Send cancellation responses for all affected requests

​

Is cancellation mandatory or optional?

• Implementations MAY support handling cancellation by declaring supportsRequestCancellation: true
• If an implementation declares support, it MUST handle $/cancelRequest notifications for its requests
• If an implementation does not declare support, $/cancelRequest notifications should be ignored
• The other party can send $/cancelRequest regardless of their own declared support
• The initialize request CANNOT be cancelled regardless of capability support
• Any requests after initialize CAN be cancelled if the recipient declared support

• Implementations MUST respond with either an error or valid response
• Implementations MAY choose how quickly to honor cancellation requests
• Implementations MAY return partial results instead of errors when appropriate

​

Example scenarios:

1. Client-to-Agent cancellation only: Client declares support=false, Agent declares support=true
   • Client can send $/cancelRequest to cancel agent’s requests
   • Agent cannot send $/cancelRequest to client (client will ignore)
2. Bidirectional cancellation: Both declare support=true
   • Both parties can cancel each other’s requests
3. No cancellation: Both declare support=false (or omit the capability)
   • No $/cancelRequest notifications are processed

​

Revision history

• 2025-11-13: Initial version converted from PR #183