Forking a Session

Create an independent Session from full history or a specific Message boundary

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

CallCopied range
fork()The complete canonical history, including Agent input Parts
fork({ message_id })History from the beginning through that Message, inclusive
fork({ message_id, include_message: false })History before that Message, exclusive

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. Input content is copied with its containing Agent Message; imported request metadata is historical context and does not resume the source actor's occupation or dispatch its callbacks.

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.

Attachment ownership and reads

A fork copies local attachments registered as owned by the source Session into the target Session's attachment directory. The copied canonical file Parts, including files within input content, record the target paths. Model-visible attachment references are derived from those canonical files, and framework path contexts are deduplicated against the associated files. The branch therefore owns its attachment copies even after the source Session is archived or deleted.

Branch attachments always retain their own path and metadata references. Static PNG, JPEG, and WebP confirmed from file headers may also be included automatically: up to 2 MiB per image, within the 4 MiB total for all request media and the model input budget. Recent candidates take priority while output order stays unchanged; current and historical attachments follow the same rules. PDFs and other files remain references until explicitly read, and images omitted for budget retain their references. The tool can read attachments registered as owned by the branch and files allowed by project policy; attachment copies grant no additional access to write, edit, grep, or find. Remote URLs remain references and are not implicitly downloaded during a fork. Missing attachments record their unavailable status without blocking the entire Session. See Messages and Parts for the disclosure contract.

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.