- Author(s): @josevalim
- Champion: @benbrandt
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?To add a “session/fork” method.
Shiny future
How will things 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?We propose to add a new “session/fork” method. Agents must declare this option is 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 given session:
session/load, such as cwd and mcpServers.
Similarly, the agent would respond with the sessionId of the new session, plus optional data such as config options, the same as session/new.
As with session/new, the forked session is active once the agent responds, set up with the request’s options, such as cwd and mcpServers. The client can prompt it right away, without calling session/load or session/resume first.
Agents may reply with an error if forking of that specific session or with the given options is not supported,
for example if the agent does not support forking with a different working directory than the initial session.
Forking at a cursor
By default,session/fork copies the whole session. To fork at an earlier position, the client passes a session cursor in an optional cursorId parameter:
fork capability on the cursor:
cursorIdis optional. Omitted andnullare equivalent and fork the whole session.forkis an optional, nullable capability object. Omitted ornullmeans unsupported, and{}advertises support. It may carry_meta.- The client MUST NOT send a
cursorIdunless that cursor currently advertisescapabilities.fork. The agent rejects any othercursorIdwith-32602, as the session cursors RFD requires. It does not fall back to forking the whole session. - The new session’s history is the source session’s history before the cursor’s position. The agent copies nothing after it.
- The source session does not change, and its cursors stay valid.
- The response is the same as for a fork without a cursor, and the new session is active once the agent responds.
- The new session does not inherit the source session’s cursors. The client learns the new session’s cursors from
cursor_updatenotifications on the new session.
- Edit a message. Fork at a cursor anchored
beforethe user message, then send the replacement withsession/promptin the new session. - Regenerate a response. Fork at the same cursor and send the original prompt again.
- Branch from a reply. Fork at a cursor anchored
afteran agent message.
after the entity that precedes the prompt. See differences in v1.
Forking at a cursor adds nothing to the session.fork capability object. An agent that supports it announces cursors with the fork capability, and an agent that doesn’t never announces one.
In the schema, ForkSessionRequest gains an optional cursorId and CursorCapabilities gains fork. A malformed cursorId fails with -32602 and is not treated as omitted.
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. Q: Should fork only accept the
sessionId or also other options, similar to session/load?
Initially, we proposed to only accept the sessionId, but this would make it more difficult to
allow forking of inactive sessions in agents like claude-agent-acp, as Claude does not retain the
configured MCP servers of a session. Limiting fork to only already active sessions would limit its usefulness.
Moreover, allowing to pass different options also allows features like dynamically adding MCP servers
to existing sessions to work by forking them with the new options, if the agent supports it. If it
does not, the client can still show an appropriate error message.
Q: Why does forking at a position take a cursor and not a message ID?
A message ID does not say whether the agent can fork at that message, and some positions are not at a message. A session cursor is announced only for positions the agent supports.
PR #629 proposed a message ID first.
Q: Does a fork inherit the source session’s cursors?
No. A fork is a new session with its own sessionId, and the protocol does not require a fork to keep the source session’s message IDs.
The client gets the new session’s cursors from cursor_update notifications on that session, for example through session/resume with replay.
A cheaper way to get the IDs and cursors of a new fork is an open question.
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.
- 2025-11-20: Added request format and updated capabilities format.
- 2025-12-10: Adjust fork options to align with
session/load. - 2026-10-12: Clarify that a forked session is active once the agent responds, so the client does not need to resume it before prompting.
- 2026-11-14: Added forking at a session cursor, with an optional
cursorIdonsession/forkand aforkcursor capability. - 2026-11-16:
cursorIdonsession/forkand theforkcursor capability are in the v1 and v2 schemas, behindunstable_session_forkandunstable_session_cursors.