docs(v2): clarify prompt cancellation when closing sessions (#2385)

Author: benbrandt

agent-client-protocol-schema/src/v2/agent.rs

@@ -1639,6 +1639,17 @@ impl ResumeSessionResponse {
 /// The agent **must** cancel any ongoing work related to the session (treat it
 /// as if `session/cancel` was called) and then free up any resources associated
 /// with the session.
+///
+/// When closing cancels active foreground work, the Agent MUST send the final
+/// updates for that work and the idle `state_update` with `stopReason: "cancelled"`
+/// before responding successfully to `session/close`. Closing an idle session
+/// does not itself require another idle update.
+///
+/// Closing may also cancel pending `session/prompt` requests, including queued
+/// prompts. If closing prevents a prompt's user message from being inserted, the
+/// Agent MUST answer that request with `-32800` (Request Cancelled). If the message
+/// has already been inserted, the Agent MUST respond successfully with its
+/// `messageId`. Prompt responses need not precede the close response.
 #[serde_as]
 #[skip_serializing_none]
 #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]

docs/protocol/v2/draft/prompt-lifecycle.mdx

@@ -261,6 +261,8 @@ Insertion is not a promise of durable storage or model consumption. Every insert
 
 A successful prompt response is not an `idle` signal. Session work and notifications continue independently of the completed prompt request. If the response is lost, the submission's outcome remains uncertain: replay may omit live-only or discarded messages, and a retry can create another submission.
 
+The same insertion boundary applies when [closing the session](/protocol/v2/draft/session-setup#closing-active-sessions) cancels a pending prompt: if closing prevents insertion, the request receives `-32800` (Request Cancelled); if the message has already been inserted, it receives a successful `messageId` response. Prompt responses need not precede the close response.
+
 ### 3. Agent Reports Output
 
 When foreground work starts or resumes, the Agent **MUST** send a `state_update` notification with `state: "running"`:

docs/protocol/v2/draft/schema.mdx

@@ -933,6 +933,17 @@ The agent **must** cancel any ongoing work related to the session (treat it
 as if `session/cancel` was called) and then free up any resources associated
 with the session.
 
+When closing cancels active foreground work, the Agent MUST send the final
+updates for that work and the idle `state_update` with `stopReason: "cancelled"`
+before responding successfully to `session/close`. Closing an idle session
+does not itself require another idle update.
+
+Closing may also cancel pending `session/prompt` requests, including queued
+prompts. If closing prevents a prompt's user message from being inserted, the
+Agent MUST answer that request with `-32800` (Request Cancelled). If the message
+has already been inserted, the Agent MUST respond successfully with its
+`messageId`. Prompt responses need not precede the close response.
+
 **Type:** Object
 
 **Properties:**

docs/protocol/v2/draft/session-setup.mdx

@@ -308,6 +308,10 @@ The Agent **MUST** cancel any ongoing work for that session as if
 [`session/cancel`](/protocol/v2/draft/prompt-lifecycle#cancellation) had been called, then free the
 resources associated with the session.
 
+When closing cancels active foreground work, the Agent **MUST** send the final updates for that work and the idle `state_update` with `stopReason: "cancelled"` before responding successfully to `session/close`. Closing an idle session does not itself require another idle update.
+
+Closing may also cancel pending `session/prompt` requests, including queued prompts. If closing prevents a prompt's user message from being inserted, the Agent **MUST** answer that request with `-32800` (Request Cancelled). If the message has already been inserted, the Agent **MUST** respond successfully with its `messageId`, as described in [Prompt Accepted](/protocol/v2/draft/prompt-lifecycle#2-prompt-accepted). Prompt responses need not precede the close response.
+
 On success, the Agent responds with an empty result object:
 
 ```json

docs/protocol/v2/prompt-lifecycle.mdx

@@ -211,6 +211,8 @@ Insertion is not a promise of durable storage or model consumption. Every insert
 
 A successful prompt response is not an `idle` signal. Session work and notifications continue independently of the completed prompt request. If the response is lost, the submission's outcome remains uncertain: replay may omit live-only or discarded messages, and a retry can create another submission.
 
+The same insertion boundary applies when [closing the session](/protocol/v2/session-setup#closing-active-sessions) cancels a pending prompt: if closing prevents insertion, the request receives `-32800` (Request Cancelled); if the message has already been inserted, it receives a successful `messageId` response. Prompt responses need not precede the close response.
+
 ### 3. Agent Reports Output
 
 When foreground work starts or resumes, the Agent **MUST** send a `state_update` notification with `state: "running"`:

docs/protocol/v2/schema.mdx

@@ -279,6 +279,17 @@ The agent **must** cancel any ongoing work related to the session (treat it
 as if `session/cancel` was called) and then free up any resources associated
 with the session.
 
+When closing cancels active foreground work, the Agent MUST send the final
+updates for that work and the idle `state_update` with `stopReason: "cancelled"`
+before responding successfully to `session/close`. Closing an idle session
+does not itself require another idle update.
+
+Closing may also cancel pending `session/prompt` requests, including queued
+prompts. If closing prevents a prompt's user message from being inserted, the
+Agent MUST answer that request with `-32800` (Request Cancelled). If the message
+has already been inserted, the Agent MUST respond successfully with its
+`messageId`. Prompt responses need not precede the close response.
+
 **Type:** Object
 
 **Properties:**

docs/protocol/v2/session-setup.mdx

@@ -301,6 +301,10 @@ To close an active session, Clients **MUST** call the `session/close` method wit
 
 The Agent **MUST** cancel any ongoing work for that session as if [`session/cancel`](/protocol/v2/prompt-lifecycle#cancellation) had been called, then free the resources associated with the session.
 
+When closing cancels active foreground work, the Agent **MUST** send the final updates for that work and the idle `state_update` with `stopReason: "cancelled"` before responding successfully to `session/close`. Closing an idle session does not itself require another idle update.
+
+Closing may also cancel pending `session/prompt` requests, including queued prompts. If closing prevents a prompt's user message from being inserted, the Agent **MUST** answer that request with `-32800` (Request Cancelled). If the message has already been inserted, the Agent **MUST** respond successfully with its `messageId`, as described in [Prompt Accepted](/protocol/v2/prompt-lifecycle#2-prompt-accepted). Prompt responses need not precede the close response.
+
 On success, the Agent responds with an empty result object:
 
 ```json

schema/v2/schema.json

@@ -6780,7 +6780,7 @@
       }
     },
     "CloseSessionRequest": {
-      "description": "Request parameters for closing an active session.\n\nThe agent **must** cancel any ongoing work related to the session (treat it\nas if `session/cancel` was called) and then free up any resources associated\nwith the session.",
+      "description": "Request parameters for closing an active session.\n\nThe agent **must** cancel any ongoing work related to the session (treat it\nas if `session/cancel` was called) and then free up any resources associated\nwith the session.\n\nWhen closing cancels active foreground work, the Agent MUST send the final\nupdates for that work and the idle `state_update` with `stopReason: \"cancelled\"`\nbefore responding successfully to `session/close`. Closing an idle session\ndoes not itself require another idle update.\n\nClosing may also cancel pending `session/prompt` requests, including queued\nprompts. If closing prevents a prompt's user message from being inserted, the\nAgent MUST answer that request with `-32800` (Request Cancelled). If the message\nhas already been inserted, the Agent MUST respond successfully with its\n`messageId`. Prompt responses need not precede the close response.",
       "type": "object",
       "properties": {
         "sessionId": {

schema/v2/schema.unstable.json

@@ -9119,7 +9119,7 @@
       }
     },
     "CloseSessionRequest": {
-      "description": "Request parameters for closing an active session.\n\nThe agent **must** cancel any ongoing work related to the session (treat it\nas if `session/cancel` was called) and then free up any resources associated\nwith the session.",
+      "description": "Request parameters for closing an active session.\n\nThe agent **must** cancel any ongoing work related to the session (treat it\nas if `session/cancel` was called) and then free up any resources associated\nwith the session.\n\nWhen closing cancels active foreground work, the Agent MUST send the final\nupdates for that work and the idle `state_update` with `stopReason: \"cancelled\"`\nbefore responding successfully to `session/close`. Closing an idle session\ndoes not itself require another idle update.\n\nClosing may also cancel pending `session/prompt` requests, including queued\nprompts. If closing prevents a prompt's user message from being inserted, the\nAgent MUST answer that request with `-32800` (Request Cancelled). If the message\nhas already been inserted, the Agent MUST respond successfully with its\n`messageId`. Prompt responses need not precede the close response.",
       "type": "object",
       "properties": {
         "sessionId": {