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");

Replace history in place

Pass replace: true to truncate the current Session and return the same instance. Its ID, configuration, and retained Message identities stay intact. This creates no branch, archives nothing, and writes no Action record.

await session.fork({
  message_id: "user:question:abc",
  include_message: false,
  replace: true,
});
await session.prompt({ query: "The edited question" });

include_message defaults to true; setting it to false also removes the boundary Message. Later history is permanently deleted, together with related context summaries. Without message_id, history stays unchanged. Replacement is rejected while the Session is executing or has queued commands.

Subscribers receive a variant: "session", type: "truncate" event. Remove messages after its through_sequence; do not display this synchronization event as a timeline Action. Both local and remote Sessions support this option.

History 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.

A successful fork records one history-fork Action at the end of the new Session's timeline, describing where the history came from. The source Session gets no record of the fork.

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.