Forking a Session

session.fork() creates an independent new Session from the current Session's history. Later input, model execution, tool state, and approvals are isolated between the branches.

const full_branch = await session.fork();

const branch_at_message = await session.fork({
  message_id: "assistant:repo-analysis:abc",
});

You can also pass a message_id string directly:

const branch = await session.fork("assistant:repo-analysis:abc");

Two boundaries

The boundary is a top-level Message, not an Assistant part_id. To experiment before or after a tool call, first locate the containing Assistant Message's message_id through messages().

Origin and ordering

Messages copied into the new Session receive the new Session identity and linear ordering while they can carry origin with the source session_id, message_id, and turn_id. This makes a fork traceable without sharing mutable state.

Do not treat a fork as two windows jointly editing one history. Later source Messages do not appear in the branch, and later branch Messages never write back to the source.

Good use cases

• Compare implementation choices while preserving the main conclusion.
• Ask again from one user input without later context influencing the answer.
• Create an experimental path for a long task without polluting the main conversation.

Use the fork as any normal Session: load messages(), establish subscribe(), then call prompt(). Do not copy Mutations or pending approvals from the source Session.