From 18033262f12415b2d438f1ba460924dfec97700d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Valim?= Date: Mon, 10 Nov 2025 16:59:12 +0100 Subject: [PATCH 1/5] Add proposal for forking existing sessions --- docs/rfds/session-fork.mdx | 66 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 docs/rfds/session-fork.mdx diff --git a/docs/rfds/session-fork.mdx b/docs/rfds/session-fork.mdx new file mode 100644 index 0000000..b9954e4 --- /dev/null +++ b/docs/rfds/session-fork.mdx @@ -0,0 +1,66 @@ +--- +title: "Forking of existing sessions" +--- + +Author(s): [@josevalim](https://github.com/josevalim) + +## Elevator pitch + +> What are you proposing to change? + +We propose adding the ability to "fork" a new session based on an existing one. +This will allow us to use the current conversation as context to generate pull +request descriptions, summaries, etc. without polluting the user history. + +## Status quo + +> How do things work today and what problems does this cause? Why would we change things? + +Imagine we want to summarize the current conversation to use it in a future chat. If we send a message +asking for the summary, it will become part of its context, affecting future user interactions. +Therefore we want to be able to fork a session, issue additional messages, and then close the fork. + +## What we propose to do about it + +> What are you proposing to improve the situation? + +One possible solution is to add a session/fork command. + +## Shiny future + +> How will things will play out once this feature exists? + +We will be able to implement functionality that requires using the current chat +without polluting its history, ranging from summaries to potentially subagents. + +I can also see this feature being extended in the future to support an optional +message ID, so the fork happens at a specific message, allowing clients to implement +functionality like editing previous messages and similar. + +## 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? + + + +### What alternative approaches did you consider, and why did you settle on this one? + +None. This proposal is inspired by the abilities exposed in Claude Agent SDK. It must be validated against other agents too. + + + +## Revision history + + From e0d2f13ad1d63f13927b00ca0790919d861b1216 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Valim?= Date: Mon, 17 Nov 2025 12:22:10 -0800 Subject: [PATCH 2/5] Add capabilities, update FAQ --- docs/rfds/session-fork.mdx | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/docs/rfds/session-fork.mdx b/docs/rfds/session-fork.mdx index b9954e4..0908e1c 100644 --- a/docs/rfds/session-fork.mdx +++ b/docs/rfds/session-fork.mdx @@ -24,7 +24,7 @@ Therefore we want to be able to fork a session, issue additional messages, and t > What are you proposing to improve the situation? -One possible solution is to add a session/fork command. +To add a "session/fork" method. ## Shiny future @@ -41,26 +41,27 @@ functionality like editing previous messages and similar. > Tell me more about your implementation. What is your detailed implementation plan? - +A proof of concept is available here: https://github.com/zed-industries/claude-code-acp/pull/145 ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? - +**Q: Should a new method be introduced or should "session/new" be expanded?** + +They must be different because they will effectively require different options. +For example, "session/new" has options such as capabilities and MCP which are not +recommended to be set when forking, as the context being forked was built with other +tools, and forking may accept a messageId for checkpoints. ### What alternative approaches did you consider, and why did you settle on this one? None. This proposal is inspired by the abilities exposed in Claude Agent SDK. It must be validated against other agents too. - - ## Revision history - +2025-11-17: Mentioned capabilities format, updated FAQ. From aea9cca293e319ca14e419253e0b5604df5cac9f Mon Sep 17 00:00:00 2001 From: Ben Brandt Date: Thu, 20 Nov 2025 11:50:17 +0100 Subject: [PATCH 3/5] Add ben as champion and add an example request --- docs/rfds/session-fork.mdx | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/docs/rfds/session-fork.mdx b/docs/rfds/session-fork.mdx index 0908e1c..8d62321 100644 --- a/docs/rfds/session-fork.mdx +++ b/docs/rfds/session-fork.mdx @@ -3,6 +3,7 @@ title: "Forking of existing sessions" --- Author(s): [@josevalim](https://github.com/josevalim) +Champion: [@benbrandt](https://github.com/benbrandt) ## Elevator pitch @@ -42,8 +43,23 @@ functionality like editing previous messages and similar. > Tell me more about your implementation. What is your detailed implementation plan? We propose to add a new "session/fork" method. Agents must declare this option is -available by returning `forkSession: {}` in its capabilities. The object is reserved -to declare future capabilities, such as forking from a message, a tool call, or similar. +available by returning `session: { fork : {} }` in its capabilities. The object is reserved +to declare future capabilities, such as forking from a specific message, a tool call, or similar. + +Then the client would be able to request a fork of the current session: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "session/fork", + "params": { + "sessionId": "sess_789xyz" + } +} +``` + +And the agent would respond with optional data such as config options, the same as `session/load`. A proof of concept is available here: https://github.com/zed-industries/claude-code-acp/pull/145 From 61ed8b3bfc09252a189ae47e955aa144f7be6a34 Mon Sep 17 00:00:00 2001 From: Ben Brandt Date: Thu, 20 Nov 2025 11:51:06 +0100 Subject: [PATCH 4/5] Add revision info --- docs/rfds/session-fork.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/rfds/session-fork.mdx b/docs/rfds/session-fork.mdx index 8d62321..c675100 100644 --- a/docs/rfds/session-fork.mdx +++ b/docs/rfds/session-fork.mdx @@ -81,3 +81,4 @@ None. This proposal is inspired by the abilities exposed in Claude Agent SDK. It ## Revision history 2025-11-17: Mentioned capabilities format, updated FAQ. +2025-11-20: Added request format and updated capabilities format. From 7b6dea9f47545c41aea27372cdb911e8df14c9a4 Mon Sep 17 00:00:00 2001 From: Ben Brandt Date: Thu, 20 Nov 2025 11:53:04 +0100 Subject: [PATCH 5/5] add to website --- docs/docs.json | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/docs.json b/docs/docs.json index 3513b2f..d7abb9d 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -91,7 +91,11 @@ "rfds/about", { "group": "Draft", - "pages": ["rfds/session-list", "rfds/session-config-options"] + "pages": [ + "rfds/session-list", + "rfds/session-config-options", + "rfds/session-fork" + ] }, { "group": "Preview", "pages": [] }, { "group": "Completed", "pages": ["rfds/introduce-rfd-process"] }