Fork and replay
Replay a finished run step by step, and start a new task that continues a run from any step, with another instruction, model or version.
On this page
Steps. Step n of a run is its n-th model call; step 0 is everything before the first.
Replay a run
hexel harness replay run_789
hexel harness replay run_789 --from-step 5 --to-step 9GET /harness/runs/{id}/replay?from_step=&to_step=&after=&limit= returns a finished run's stored events from from_step (default 0) to to_step (default the last), in order, each with its step:
{"run_id": "run_789", "task_id": "tsk_123", "steps": 12, "from_step": 5, "to_step": 9,
"events": [{"seq": 41, "step": 5, "type": "tool.call", "data": {}}], "next_after": 57}- A run that has not ended is refused with
409 run_not_ended. - Only the run's own events are returned; a sub-agent is a run of its own.
- At most
limit(1 to 1,000) events per answer; passnext_afterasafterfor the next page. - The events are what the control plane stores, so they are metadata only (Content and history). The content is in the run's record in your runtime.
Fork a run
A fork is a new task that continues a run from the end of one of its steps, optionally changed.
hexel harness fork run_789 --step 7 --instruction "Use the staging database instead"
hexel harness fork run_789 --step 7 --model anthropic/claude-sonnet-5-5 --followPOST /harness/runs/{id}/fork takes {step, instruction?, model?, version?}:
| Field | Description |
|---|---|
step | 0 to the run's steps. Past them: 400 step_out_of_range. |
instruction | Optional. The fork's goal: an extra instruction after the copied conversation. |
model | Optional. provider/model; it must be the model or one of the fallback_models the version's bundle names (400 model_not_allowed with details.allowed). |
version | Optional. Another version of the agent in your environment. |
The answer is the new task (201). Its first event after task.state is run.forked {parent_run_id, step, overrides}, and GET /harness/tasks/{id} shows its fork.
What a fork is
- A copy of the conversation up to the step: messages, the model's turns and the tool results. Nothing is run again.
- Nothing is inherited: no policy decision, approval, budget or sandbox. The fork has its own Titan session and every action after the fork point is decided by Titan again. Its sandbox is new: the parent's files are not copied, and the model is told so.
- Its own task: yours, in the same workspace and environment, with the parent task's budget and sandbox template, admitted and billed like a new task. The copied turns are not billed again. Its own steps count from 1.
- Its own retention: a fork is not deleted with its parent; delete it on its own.
- As careful as its parent: the fork carries the parent's sensitivity, so Titan still asks before external side effects where the parent would have.
Who can fork
You need harness:task:read and harness:task:create, and you must be able to see the run's task. Only a task's root run can be forked: a sub-agent's run is refused (400), and a swarm member's (409 swarm_member).
A fork is also refused (409) when the parent task is under a legal hold (parent_held), its content is erased (parent_erased), it is in a zero-retention environment or has a zero-retention run (parent_zero_retention), or its budget does not validate (parent_budget_invalid). A fork whose parent is held, erased or deleted before the fork starts fails with that reason as its end_reason.
The fork's start fails, naming why, when a tool call at or before the step has no result yet: it would have to run again.