Skip to content
Hexel StudioDocs

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

Bash
hexel harness replay run_789
hexel harness replay run_789 --from-step 5 --to-step 9

GET /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:

JSON
{"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; pass next_after as after for 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.

Bash
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 --follow

POST /harness/runs/{id}/fork takes {step, instruction?, model?, version?}:

FieldDescription
step0 to the run's steps. Past them: 400 step_out_of_range.
instructionOptional. The fork's goal: an extra instruction after the copied conversation.
modelOptional. 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).
versionOptional. 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.