# Completion and verification

## Worker tools

### `goal_set`

Creates or replaces the persistent branch goal only when the user's current message explicitly requests goal creation. Its contract fields are the objective, optional criteria and constraints. Goals have no iteration or token budgets. It never accepts verifier definitions, preventing model-generated commands from becoming approved verification steps. Because a tool executes inside an agent run, setting the goal does not abort that run; settlement accounts it as the first goal iteration and may queue the next continuation.

### `goal_get`

Returns a cloned active state (or no-goal message), including contract, status, token usage, verification results, verdict, and blocker data. Use it whenever the active contract or audit gaps are unclear.

### `goal_complete`

A candidate must be:

```json
{
  "summary": "Concise description of completed work",
  "evidence": [{
    "criterion": "A contract criterion",
    "source": "Command, test, or inspected artifact",
    "result": "Concrete result"
  }]
}
```

`summary` is 1–8,000 characters; evidence has 1–100 objects; each criterion/source/result has explicit non-empty size bounds. The candidate does **not** complete the goal. It is sequential and follows this authority chain:

1. Capture goal id, revision, and runtime generation; mark evaluator-running and create an abort controller.
2. Run exactly the approved verification steps, sequentially.
3. Re-check identity. If state changed, ignore the superseded candidate.
4. Persist verification output. If any check failed, synthesize a `continue` verdict with exact failed commands and do not contact the judge.
5. Call the configured judge in a fresh context.
6. Re-check identity. On `complete`, persist the approved verdict and transition to `complete`; on `continue`, persist the rejection and keep work active; on `blocked`, persist it and block.
7. On evaluator failures, transition to `evaluator_error`, never `complete`. Clear evaluator runtime state in all cases.

### `goal_blocked`

Use only for a concrete external dependency. It requires a 1–4,000 character reason and 1–50 attempted workarounds. `requiredUserAction`, when supplied, immediately pauses as `blocked`; otherwise the same claim must recur in three worker runs. It is not appropriate for uncertainty, a test failure that can still be investigated, or ordinary implementation difficulty.

## Approved verifier execution

No verifier runs when the contract has no steps. When steps exist, project trust is mandatory. Each runs through `pi.exec(executable, args, { cwd, timeout, signal })`; pi-let never invokes a shell and never runs model-invented commands. A step passes only when it was not killed and its exit code appears in `expectedExitCodes`.

Verifier stdout and stderr are independently tail-truncated to at most 2,000 lines and 50 KiB. The result retains original byte/line counts, truncation flags, exit code (or `null`), killed/timed-out flags, elapsed duration, resolved cwd, command definition, and pass result. Timeouts use both the exec timeout and an abort signal. The supplied evaluation signal can also cancel verification between or during steps.

## Judge protocol

The default `same` judge resolves the active model; `model` resolves the exact configured `provider/model` from Pi’s registry. Authentication is requested through the model registry and must yield an API key. The judge call has a 120-second default timeout, a 2,000-token response cap, and one user message only.

The message contains only objective, criteria, constraints, worker summary/evidence, verifier results, and recent relevant tool results. It does not inherit the worker transcript. Its system prompt requires exactly one JSON object:

```json
{
  "decision": "complete|continue|blocked",
  "reason": "non-empty explanation",
  "unmetCriteria": ["criterion or concrete gap"],
  "nextInstruction": "specific action or null"
}
```

Unknown fields, invalid JSON, empty reason, invalid decisions, non-string fields, `complete` with unmet criteria, or `continue` without a concrete gap are rejected. The model must finish with stop reason `stop`. A successful verdict records its evaluation time and `provider/model`.

The judge should approve only evidence that proves every criterion and mandatory constraint. Missing, ambiguous, decisive truncation, or contradictory evidence is `continue`; a genuinely unresolvable external dependency is `blocked`.