docs(rfd): Move session/close to Preview (#970)

Author: benbrandt

docs/docs.json

@@ -127,15 +127,14 @@
               "rfds/diff-delete",
               "rfds/boolean-config-option",
               "rfds/elicitation",
-              "rfds/session-close",
               "rfds/next-edit-suggestions",
               "rfds/additional-directories",
               "rfds/custom-llm-endpoint"
             ]
           },
           {
             "group": "Preview",
-            "pages": ["rfds/session-resume"]
+            "pages": ["rfds/session-close", "rfds/session-resume"]
           },
           {
             "group": "Completed",

docs/protocol/draft/schema.mdx

@@ -845,7 +845,7 @@ This capability is not part of the spec yet, and may be removed or changed at an
 
 Closes an active session and frees up any resources associated with it.
 
-This method is only available if the agent advertises the `session.close` capability.
+This method is only available if the agent advertises the `sessionCapabilities.close` capability.
 
 The agent must cancel any ongoing work (as if `session/cancel` was called)
 and then free up any resources associated with the session.
@@ -862,7 +862,7 @@ If supported, 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.
 
-Only available if the Agent supports the `session.close` capability.
+Only available if the Agent supports the `sessionCapabilities.close` capability.
 
 **Type:** Object
 

docs/protocol/draft/session-setup.mdx

@@ -268,6 +268,79 @@ session is ready to continue.
 The response **MAY** also include initial mode, model, or session configuration
 state when those features are supported by the Agent.
 
+## Closing Active Sessions
+
+<Note>
+  This section describes the preview `sessionCapabilities.close` capability.
+  Clients MUST gate usage on that capability being present during
+  initialization.
+</Note>
+
+When advertised, Clients MAY call `session/close` to tell the Agent to cancel
+any ongoing work for a session and free any resources associated with that
+active session.
+
+### Checking Support
+
+Before attempting to close a session, Clients **MUST** verify that the Agent
+supports this capability by checking the `sessionCapabilities.close` field in
+the `initialize` response:
+
+```json highlight={8-10}
+{
+  "jsonrpc": "2.0",
+  "id": 0,
+  "result": {
+    "protocolVersion": 1,
+    "agentCapabilities": {
+      "sessionCapabilities": {
+        "close": {}
+      }
+    }
+  }
+}
+```
+
+If `sessionCapabilities.close` is not present, the Agent does not support
+closing sessions and Clients **MUST NOT** attempt to call `session/close`.
+
+### Closing a Session
+
+To close an active session, Clients **MUST** call the `session/close` method
+with the session ID:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "session/close",
+  "params": {
+    "sessionId": "sess_789xyz"
+  }
+}
+```
+
+<ParamField path="sessionId" type="SessionId" required>
+  The ID of the active session to close.
+</ParamField>
+
+The Agent **MUST** cancel any ongoing work for that session as if
+[`session/cancel`](../prompt-turn#cancellation) had been called, then free the
+resources associated with the session.
+
+On success, the Agent responds with an empty result object:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "result": {}
+}
+```
+
+Agents MAY return an error if the session does not exist or is not currently
+active.
+
 ## Additional Workspace Roots
 
 <Note>

docs/rfds/session-close.mdx

@@ -44,8 +44,8 @@ Clients can track what sessions are actively used by a user and automatically cl
 > Tell me more about your implementation. What is your detailed implementation plan?
 
 We propose to add a new `"session/close"` method. Agents must declare this option is
-available by returning `session: { close : {} }` in their capabilities. The object is reserved
-to declare future capabilities.
+available by returning `sessionCapabilities: { close: {} }` in their capabilities. The object is
+reserved to declare future capabilities.
 
 Then the client would be able to close a specific session with:
 
@@ -76,5 +76,6 @@ seems like a good idea.
 
 ## Revision history
 
+2026-04-14: Move to preview and update capability docs to `sessionCapabilities.close`
 2026-03-09: Rename from session/stop to session/close
 2026-02-24: Initial draft

docs/rfds/updates.mdx

@@ -13,6 +13,13 @@ The RFD for adding a `session/resume` method to the protocol has been moved to P
 
 </Update>
 
+<Update label="April 14, 2026" tags={["Preview"]}>
+## session/close RFD moves to Preview stage
+
+The RFD for allowing agents to close a given session has been moved to Preview stage. Please review the [RFD](/rfds/session-close) for more information on the current proposal and provide feedback before the feature is stabilized.
+
+</Update>
+
 <Update label="March 27, 2026" tags={["Draft"]}>
 ## Custom LLM Endpoint RFD moves to Draft stage
 

schema/schema.unstable.json

@@ -1247,7 +1247,7 @@
                       "$ref": "#/$defs/CloseSessionRequest"
                     }
                   ],
-                  "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCloses an active session and frees up any resources associated with it.\n\nThis method is only available if the agent advertises the `session.close` capability.\n\nThe agent must cancel any ongoing work (as if `session/cancel` was called)\nand then free up any resources associated with the session.",
+                  "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCloses an active session and frees up any resources associated with it.\n\nThis method is only available if the agent advertises the `sessionCapabilities.close` capability.\n\nThe agent must cancel any ongoing work (as if `session/cancel` was called)\nand then free up any resources associated with the session.",
                   "title": "CloseSessionRequest"
                 },
                 {
@@ -1484,7 +1484,7 @@
       "x-side": "agent"
     },
     "CloseSessionRequest": {
-      "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest parameters for closing an active session.\n\nIf supported, the agent **must** cancel any ongoing work related to the session\n(treat it as if `session/cancel` was called) and then free up any resources\nassociated with the session.\n\nOnly available if the Agent supports the `session.close` capability.",
+      "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest parameters for closing an active session.\n\nIf supported, the agent **must** cancel any ongoing work related to the session\n(treat it as if `session/cancel` was called) and then free up any resources\nassociated with the session.\n\nOnly available if the Agent supports the `sessionCapabilities.close` capability.",
       "properties": {
         "_meta": {
           "additionalProperties": true,

src/agent.rs

@@ -1608,7 +1608,7 @@ impl ResumeSessionResponse {
 /// (treat it as if `session/cancel` was called) and then free up any resources
 /// associated with the session.
 ///
-/// Only available if the Agent supports the `session.close` capability.
+/// Only available if the Agent supports the `sessionCapabilities.close` capability.
 #[cfg(feature = "unstable_session_close")]
 #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)]
 #[schemars(extend("x-side" = "agent", "x-method" = SESSION_CLOSE_METHOD_NAME))]
@@ -4714,7 +4714,7 @@ pub enum ClientRequest {
     ///
     /// Closes an active session and frees up any resources associated with it.
     ///
-    /// This method is only available if the agent advertises the `session.close` capability.
+    /// This method is only available if the agent advertises the `sessionCapabilities.close` capability.
     ///
     /// The agent must cancel any ongoing work (as if `session/cancel` was called)
     /// and then free up any resources associated with the session.