Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Recover a stopped run

A run can stop for several reasons. Read status, lastDecision, and stopContext together. The runtime decides which recovery is eligible; a model explanation cannot grant permission.
StopRecoveryEffect
Explicit refusalClarifyAdd context and request a fresh evaluation; no automatic retry or override
Missing informationClarifyAnswer the executor's question within the original task
Missing exact approvalApproveApprove the current immutable prepared transaction
Transient provider failure or invalid outputRetryResume without dispatching; the next step evaluates again
Missing configurationConfigure, then retryFix API settings and explicitly resume
Uncertain external effectReview external resultNo redispatch; inspect the receipt and evidence
Exhausted limit or unsupported capabilityNew runStart a compatible task with new authority
Hard-policy terminationNoneAuthority is revoked

A refusal response

Advance one step can return HTTP 200 with a paused run:
{
  "status": "paused",
  "pendingPermit": null,
  "stopContext": {
    "version": 1,
    "category": "refusal",
    "source": "executor",
    "reasonCode": "EXECUTOR_REFUSAL",
    "message": "I cannot assist with an unauthorized transfer.",
    "recovery": "clarify",
    "attemptId": "55555555-5555-4555-8555-555555555555",
    "observationId": "44444444-4444-4444-8444-444444444444",
    "dispatch": "not_dispatched"
  }
}
This excerpt omits other RunView fields. The endpoint reference shows a complete example. Native provider refusals and structured executor refusals retain different provenance. A guardian refusal also pauses without issuing a permit; it is not converted into a fabricated TERMINATE judgment.

Clarify without overriding

Send clarification only when recovery is clarify. The original instruction and grants remain unchanged. The next step performs a fresh evaluation. If the transaction scope changes, create a new task.
Exact approval cannot clear a refusal. After clarification, approval is unavailable until a fresh evaluation produces an approval stop. Concurrent approval and clarification requests cannot create an execution grant through that gap.

Interpret dispatch certainty

not_dispatched means no action was dispatched in the referenced attempt. It does not erase earlier effects. confirmed refers to recorded dispatch/effect evidence. unconfirmed means execution may have occurred and must be reviewed. unknown preserves uncertainty for records without enough evidence.
The core checks unresolved claimed permits and hosted receipts before recovery, including permits that were later revoked. A 403 with UNRESOLVED_DISPATCH requires external review, not another retry.
The signed timeline retains the stop and recovery history. Legacy pauses remain inspectable without being relabeled as model refusals.