Skip to main content

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:
The request expects the same options as 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:
The agent says which cursors it can fork at with a fork capability on the cursor:
  • cursorId is optional. Omitted and null are equivalent and fork the whole session.
  • fork is an optional, nullable capability object. Omitted or null means unsupported, and {} advertises support. It may carry _meta.
  • The client MUST NOT send a cursorId unless that cursor currently advertises capabilities.fork. The agent rejects any other cursorId with -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_update notifications on the new session.
With a cursor, a client can build:
  • Edit a message. Fork at a cursor anchored before the user message, then send the replacement with session/prompt in 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 after an agent message.
In v1, the cursor before a prompt the client sent on this connection is anchored 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 cursorId on session/fork and a fork cursor capability.
  • 2026-11-16: cursorId on session/fork and the fork cursor capability are in the v1 and v2 schemas, behind unstable_session_fork and unstable_session_cursors.