RFD: Resume existing sessions (#234)

* RFD: resume existing sessions

This document proposes the addition of a 'session/resume' command to allow users to resume existing sessions without returning previous messages, addressing the limitations of the current 'session/load' command.

* Revise proposal for session resumption functionality

Clarified the proposal for resuming sessions and its advantages and compatibility in relation to 'session/load'.

* Add session/load vs session/resume to FAQ

* update capabilities and formatting

* Add to website

* Add update

---------

Co-authored-by: Ben Brandt <benjamin.j.brandt@gmail.com>

Author: josevalim

docs/docs.json

@@ -95,7 +95,8 @@
               "rfds/session-list",
               "rfds/session-config-options",
               "rfds/session-fork",
-              "rfds/request-cancellation"
+              "rfds/request-cancellation",
+              "rfds/session-resume"
             ]
           },
           { "group": "Preview", "pages": [] },

docs/rfds/session-resume.mdx

@@ -0,0 +1,85 @@
+---
+title: "Resuming of existing sessions"
+---
+
+- Author(s): [@josevalim](https://github.com/josevalim)
+- Champion: [@benbrandt](https://github.com/benbrandt)
+
+## Elevator pitch
+
+> What are you proposing to change?
+
+We propose adding the ability to resume existing sessions. This is similar to "session/load",
+except it does not return previous messages.
+
+## Status quo
+
+> How do things work today and what problems does this cause? Why would we change things?
+
+While the spec provides a "session/load" command, not all coding agents implement it.
+This means that, once you close your editor, browser, etc, you can't resume the conversation.
+
+This is particularly a problem for agents that do not directly implement ACP and the
+functionality is implemented via a wrapper. In such cases, they may provide the ability
+to resume (without history), which we would like to hook into. Not only that, resuming
+could be used as a mechanism for proxies and adapter libraries to emulate "session/load".
+
+## What we propose to do about it
+
+> What are you proposing to improve the situation?
+
+Add a "session/resume" command and a capability `{ session: { resume: {} }`.
+
+## Shiny future
+
+> How will things will play out once this feature exists?
+
+We will be able to resume existing conversations, providing a better user experience.
+
+Not only that, if an agent does not implement "session/load" but it does implement
+"session/resume", it is now possible to implement a proxy/adapter that intercepts
+the agents messages and writes them to disk. Now when the client issues a
+"session/load", the proxy/adapter converts it to a "session/resume", and then returns
+the stored messages.
+
+## Implementation details and plan
+
+> Tell me more about your implementation. What is your detailed implementation plan?
+
+## Frequently asked questions
+
+> What questions have arisen over the course of authoring this document or during subsequent discussions?
+
+### Should we introduce a new operation (session/resume) or add an option to (session/load)?
+
+A separate method provides a few benefits:
+
+- for clients that for whatever reason don't want the history, they can just resume
+
+- for agents that can only supply resume, a proxy on top could provide load on top of it,
+  but the agent is still clear on what it supports
+
+- for agents who support both, it should be trivial to use the same resume functionality,
+  they just either replay events or do not
+
+### What alternative approaches did you consider, and why did you settle on this one?
+
+The biggest question is if it makes sense to support both "session/load" and
+"session/resume".
+
+When we start a new session over ACP, we introduce custom MCP tools and configuration.
+This means that, while we could use "session/load" to load our own chats, loading
+third-party chats would likely lead to a flawed user experience, as our tools would
+not be available. And depending on the ACP implementation, not even the capabilities
+would be respected (as loading a third-party session would not include our capabilities
+in its history, misleading the agent).
+
+Therefore, if we assume "session/load" is for loading conversations started by the client
+itself, "session/resume" is effectively a subset of "session/load", decoupled from storage
+mechanics. If an agent implements "session/load", then it can be used directly, but if it
+doesn't, a proxy or adapter can provide a reasonable fallback on top of "session/resume".
+This argues "session/resume" is the basic primitive which "session/load" builds on top of.
+
+## Revision history
+
+- 2025-11-24: Update FAQ to mention session/resume vs session/load

docs/updates.mdx

@@ -4,6 +4,13 @@ description: Updates and announcements about the Agent Client Protocol
 rss: true
 ---
 
+<Update label="November 26, 2025" tags={["RFD"]}>
+## session/resume RFD moves to Draft stage
+
+The RFD for adding a "session/resume" method to the protocol has been moved to Draft stage. Please review the [RFD](./rfds/session-resume) for more information on the current proposal and provide feedback as work on the implementation begins.
+
+</Update>
+
 <Update label="November 20, 2025" tags={["RFD"]}>
 ## $/cancelRequest RFD moves to Draft stage