Checkpoints

Some workflows need someone to inspect intermediate results before an external action happens. For example, an invoice batch might need review after its totals are calculated and before files are exported. A checkpoint lets the program return a review message and its current context at that point.

A checkpoint ends the current VM execution with a checkpoint result. The caller must decide how to present the review and how to start any later work. The current CLI does not provide a general resume command that continues at the next instruction; running the source again starts it again.

Return a review point

Use Checkpoint after the steps whose results need review. Statements after it do not run in that invocation. This example reads and validates an application, then returns its intermediate values:

Read JSON from "application.json" as application
applicant equals name of application
amount equals requested_amount of application

amount must be at least 10000
Checkpoint "Review extracted fields before export"

Name the saved context

saving context as chooses the key under which a snapshot of the current context is included. It names the snapshot; it does not select just a subset of variables.

Checkpoint "Approval needed for extracted values" saving context as approval_state

The caller can inspect the values calculated so far and use them as inputs to a separate, explicitly authorized next stage.

Understand the result

The VM marks the result with is_checkpoint and includes the message as prompt, along with context and results. A host can wrap this result in its own transport envelope. The following abbreviated example shows the VM fields rather than an MCP envelope:

{
  "success": true,
  "is_checkpoint": true,
  "prompt": "Review extracted fields before export",
  "context": {"applicant": "Acme Corp", "amount": 50000}
}

The success value means this stage reached its checkpoint without an execution error. It does not mean the whole workflow finished or that a reviewer approved it.

Plan the next stage

For a review workflow, separate data preparation from the action that needs approval. Have the caller retain the checkpoint result, obtain the review decision, and invoke the later stage with explicit inputs and appropriate permissions. A checkpoint alone does not authenticate a reviewer, record approval, or grant permission to an external action.

See Permissions for declared capabilities and Local Tools and Policy for per-request decisions. Audit and Replay explains execution records when the workflow also needs a traceable history.