docs(rfd): Move session/resume to Preview (#969)

* docs(rfd): Move session/resume to Preview

* Update RFD

Author: benbrandt

docs/docs.json

@@ -114,7 +114,6 @@
             "pages": [
               "rfds/session-fork",
               "rfds/request-cancellation",
-              "rfds/session-resume",
               "rfds/meta-propagation",
               "rfds/agent-telemetry-export",
               "rfds/proxy-chains",
@@ -136,7 +135,7 @@
           },
           {
             "group": "Preview",
-            "pages": []
+            "pages": ["rfds/session-resume"]
           },
           {
             "group": "Completed",

docs/protocol/draft/schema.mdx

@@ -1379,7 +1379,7 @@ This capability is not part of the spec yet, and may be removed or changed at an
 
 Resumes an existing session without returning previous messages.
 
-This method is only available if the agent advertises the `session.resume` capability.
+This method is only available if the agent advertises the `sessionCapabilities.resume` capability.
 
 The agent should resume the session context, allowing the conversation to continue
 without replaying the message history (unlike `session/load`).
@@ -1395,7 +1395,7 @@ Request parameters for resuming an existing session.
 Resumes an existing session without returning previous messages (unlike `session/load`).
 This is useful for agents that can resume sessions but don't implement full session loading.
 
-Only available if the Agent supports the `session.resume` capability.
+Only available if the Agent supports the `sessionCapabilities.resume` capability.
 
 **Type:** Object
 

docs/protocol/draft/session-setup.mdx

@@ -30,6 +30,11 @@ sequenceDiagram
         Agent->>Client: session/update
         Note over Agent,Client: All content streamed
         Agent-->>Client: session/load response
+    else
+        Client->>Agent: session/resume (sessionId)
+        Note over Agent: Restore session context
+        Note over Agent: Connect to MCP servers
+        Agent-->>Client: session/resume response
     end
 
     Note over Client,Agent: Ready for prompts
@@ -77,7 +82,7 @@ The Agent **MUST** respond with a unique [Session ID](#session-id) that identifi
 
 ## Loading Sessions
 
-Agents that support the `loadSession` capability allow Clients to resume previous conversations. This feature enables persistence across restarts and sharing sessions between different Client instances.
+Agents that support the `loadSession` capability allow Clients to resume previous conversations with history replay. This feature enables persistence across restarts and sharing sessions between different Client instances.
 
 ### Checking Support
 
@@ -166,17 +171,102 @@ Followed by the agent's response:
 }
 ```
 
-When **all** the conversation entries have been streamed to the Client, the Agent **MUST** respond to the original `session/load` request.
+When **all** the conversation entries have been streamed to the Client, the
+Agent **MUST** respond to the original `session/load` request.
 
 ```json
 {
   "jsonrpc": "2.0",
   "id": 1,
-  "result": null
+  "result": {}
+}
+```
+
+The response **MAY** also include initial mode, model, or session configuration
+state when those features are supported by the Agent.
+
+The Client can then continue sending prompts as if the session was never
+interrupted.
+
+## Resuming Sessions
+
+<Note>
+  This section describes the preview `session/resume` method. Clients MUST gate
+  usage on the `sessionCapabilities.resume` capability being present during
+  initialization.
+</Note>
+
+Agents that advertise `sessionCapabilities.resume` allow Clients to reconnect to
+an existing session without replaying the conversation history.
+
+### Checking Support
+
+Before attempting to resume a session, Clients **MUST** verify that the Agent
+supports this capability by checking for the `sessionCapabilities.resume` field
+in the `initialize` response:
+
+```json highlight={8-10}
+{
+  "jsonrpc": "2.0",
+  "id": 0,
+  "result": {
+    "protocolVersion": 1,
+    "agentCapabilities": {
+      "sessionCapabilities": {
+        "resume": {}
+      }
+    }
+  }
+}
+```
+
+If `sessionCapabilities.resume` is not present, the Agent does not support
+resuming sessions and Clients **MUST NOT** attempt to call `session/resume`.
+
+### Resuming a Session
+
+To resume an existing session without replaying prior messages, Clients
+**MUST** call the `session/resume` method with:
+
+- The [Session ID](#session-id) to resume
+- [MCP servers](#mcp-servers) to connect to
+- The [working directory](#working-directory)
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "session/resume",
+  "params": {
+    "sessionId": "sess_789xyz",
+    "cwd": "/home/user/project",
+    "mcpServers": [
+      {
+        "name": "filesystem",
+        "command": "/path/to/mcp-server",
+        "args": ["--mode", "filesystem"],
+        "env": []
+      }
+    ]
+  }
+}
+```
+
+Unlike `session/load`, the Agent **MUST NOT** replay the conversation history
+via `session/update` notifications before responding. Instead, it restores the
+session context, reconnects to the requested MCP servers, and returns once the
+session is ready to continue.
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "result": {}
 }
 ```
 
-The Client can then continue sending prompts as if the session was never interrupted.
+The response **MAY** also include initial mode, model, or session configuration
+state when those features are supported by the Agent.
 
 ## Additional Workspace Roots
 
@@ -214,7 +304,7 @@ When present, `additionalDirectories` has the following behavior:
 - `cwd` remains the primary working directory and the base for relative paths
 - each `additionalDirectories` entry **MUST** be an absolute path
 - omitting the field or providing an empty array activates no additional roots for the resulting session
-- on `session/load`, Clients must send the full intended additional-root list again because omitting the field or providing an empty array does not restore stored roots implicitly
+- on `session/load` and `session/resume`, Clients must send the full intended additional-root list again because omitting the field or providing an empty array does not restore stored roots implicitly
 
 ## Session ID
 
@@ -225,6 +315,7 @@ Clients use this ID to:
 - Send prompt requests via `session/prompt`
 - Cancel ongoing operations via `session/cancel`
 - Load previous sessions via `session/load` (if the Agent supports the `loadSession` capability)
+- Resume previous sessions via `session/resume` (if the Agent supports the preview `sessionCapabilities.resume` capability)
 
 ## Working Directory
 

docs/rfds/session-resume.mdx

@@ -28,7 +28,8 @@ could be used as a mechanism for proxies and adapter libraries to emulate "sessi
 
 > What are you proposing to improve the situation?
 
-Add a "session/resume" command and a capability `{ session: { resume: {} }`.
+Add a "session/resume" command and a capability
+`{ sessionCapabilities: { resume: {} } }`.
 
 ## Shiny future
 
@@ -82,4 +83,5 @@ This argues "session/resume" is the basic primitive which "session/load" builds
 
 ## Revision history
 
+- 2026-04-14: Update capability shape to `sessionCapabilities.resume`
 - 2025-11-24: Update FAQ to mention session/resume vs session/load

docs/rfds/updates.mdx

@@ -6,6 +6,13 @@ rss: true
 
 This page tracks lifecycle changes for ACP Requests for Dialog. For broader ACP announcements, see [Updates](/updates).
 
+<Update label="April 14, 2026" tags={["Preview"]}>
+## session/resume RFD moves to Preview stage
+
+The RFD for adding a `session/resume` method to the protocol has been moved to Preview stage. Please review the [RFD](/rfds/session-resume) 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

@@ -1238,7 +1238,7 @@
                       "$ref": "#/$defs/ResumeSessionRequest"
                     }
                   ],
-                  "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResumes an existing session without returning previous messages.\n\nThis method is only available if the agent advertises the `session.resume` capability.\n\nThe agent should resume the session context, allowing the conversation to continue\nwithout replaying the message history (unlike `session/load`).",
+                  "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResumes an existing session without returning previous messages.\n\nThis method is only available if the agent advertises the `sessionCapabilities.resume` capability.\n\nThe agent should resume the session context, allowing the conversation to continue\nwithout replaying the message history (unlike `session/load`).",
                   "title": "ResumeSessionRequest"
                 },
                 {
@@ -5219,7 +5219,7 @@
       "type": "object"
     },
     "ResumeSessionRequest": {
-      "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 resuming an existing session.\n\nResumes an existing session without returning previous messages (unlike `session/load`).\nThis is useful for agents that can resume sessions but don't implement full session loading.\n\nOnly available if the Agent supports the `session.resume` 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 resuming an existing session.\n\nResumes an existing session without returning previous messages (unlike `session/load`).\nThis is useful for agents that can resume sessions but don't implement full session loading.\n\nOnly available if the Agent supports the `sessionCapabilities.resume` capability.",
       "properties": {
         "_meta": {
           "additionalProperties": true,

src/agent.rs

@@ -1430,7 +1430,7 @@ impl ForkSessionResponse {
 /// Resumes an existing session without returning previous messages (unlike `session/load`).
 /// This is useful for agents that can resume sessions but don't implement full session loading.
 ///
-/// Only available if the Agent supports the `session.resume` capability.
+/// Only available if the Agent supports the `sessionCapabilities.resume` capability.
 #[cfg(feature = "unstable_session_resume")]
 #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)]
 #[schemars(extend("x-side" = "agent", "x-method" = SESSION_RESUME_METHOD_NAME))]
@@ -4702,7 +4702,7 @@ pub enum ClientRequest {
     ///
     /// Resumes an existing session without returning previous messages.
     ///
-    /// This method is only available if the agent advertises the `session.resume` capability.
+    /// This method is only available if the agent advertises the `sessionCapabilities.resume` capability.
     ///
     /// The agent should resume the session context, allowing the conversation to continue
     /// without replaying the message history (unlike `session/load`).