Branch a session

Branch when you want to explore a different approach from a known completed turn. Steering changes active work; branching creates an independent session from a retained boundary.

The branch starts from the selected turn’s context and files. Later turns in the original session and in the branch stay independent. Nothing merges back.

Select a boundary

Use an existing session ID and a source_run_id belonging to a completed, delivered turn in that session. The service must have retained its snapshot.

Branch and continue

branch = client.execution_sessions.branch(
    project, session_id,
    source_run_id=completed_run_id,
    idempotency_key="case-42-alternative-1",
)["session"]
turn = client.execution_sessions.append_turn(
    project, branch["id"],
    idempotency_key="alternative-first-turn",
    input={"text": "Explore an alternative explanation using the same evidence."},
)

• The branch inherits the selected boundary’s context and files.
• It does not copy later changes to the original session.
• Its subsequent turns remain independent; there is no automatic merge back into the parent.
• Branching does not execute a new task until you append a turn.

Retain the branch receipt and idempotency key. Reusing that key with a different source run is a conflict.

Continue observing the returned run as described in Runs and tool requests.

Next steps