A run represents one attempt by an agent to work on a task.
When an agent begins implementation, Istok associates the work with a run. This gives the attempt its own context, executed commands, artifacts, validation history, and final result.
Why runs exist
A task describes what needs to be done.
A run describes an attempt to do it.
Keeping these concepts separate matters because work does not always succeed on the first attempt.
A task may be:
- worked on across several sessions;
- interrupted before completion;
- blocked by another change;
- retried after validation fails;
- continued by another agent.
The task remains the durable unit of work while runs preserve the history of individual attempts.
A run starts with context
When an agent claims a task, Istok creates a run and associates an immutable snapshot of the context selected for that attempt.
The snapshot contains applicable project context — including enabled instructions — together with repository context retrieved for the work.
Task state remains associated with the task itself rather than being copied into the context snapshot.
This gives the run a stable view of the context that was available when the attempt began.
Later changes to project context do not rewrite the history of an earlier run.
Work inside a run
While working, an agent can associate useful execution state with the run.
This may include:
- progress recorded during implementation;
- commands executed as part of the work;
- command output;
- generated artifacts;
- validation results;
- a final summary of the attempt.
This makes the work inspectable beyond the agent’s final chat response.
Validation
Validation records how the result of the work was checked.
For example, an agent implementing a code change may run:
go test ./...or:
pnpm testthrough Istok as a validation step.
Istok can preserve the result together with information such as the command outcome and its captured output.
The important distinction is that validation is attached to the work itself rather than existing only as a sentence in the conversation.
Validation evidence
An agent saying that a change works and an agent recording a successful validation are different things.
Validation evidence makes it possible to inspect how the result was checked.
Conceptually:
Task
↓
Run
↓
Implementation
↓
Validation
↓
EvidenceThis is especially useful when work continues later or another agent needs to understand the state of the task.
Instead of seeing only:
Implemented successfully.
the next session can also see that the implementation was actually validated.
Failed validation is part of the work
Validation does not always pass.
A failed check can reveal that more implementation work is required. The agent can continue working within the task, record progress, and validate again after addressing the problem.
The failed attempt remains useful history rather than disappearing from the workflow.
Completing work
For normal agent workflows, completion should follow successful implementation and validation.
You generally do not need to manage runs or validation manually. An agent configured to use Istok can perform these steps through MCP as part of its work.
The CLI remains available when you need to inspect runs, validation results, or execution history directly.
Runs survive conversations
A run belongs to Istok project state, not to the conversation that created it.
If a session ends, the recorded state remains available for inspection later.
This makes runs one of the pieces that allow work to move safely between sessions and agents.
Next
Continue with Handoffs to see how durable Istok state helps another session or agent continue existing work.