/agent-response

name: agent-response
description: Use when the orchestrator must read, reconcile, route, and present an agent_contract_handoff

Agent Response — Consumer Branch

The durable contract row is the turn's whole delivery. The final message is the signal that the turn ended and carries no envelope of its own, so there is nothing to reconcile against: what the agent declared and what was persisted are one artifact.

**The read is not free, and that is the economics that decides whether it happens at all.** `contract view --field <dotted.path>` prints only that subtree of the envelope (`agent_status.agent_state`, `evidence_report.open_gaps`, ...), exiting 0 with the value verbatim when the path exists and 1 when it does not — so "searched and found nothing" and "did not search" are distinguishable without opening anything else. Without that distinction the only choice is between the WHOLE row (expensive) and nothing (free), and free wins every time; the narrow `--field` read is what makes reading the row cheaper than skipping it. `contract list --state DISPATCHED` lists turns still open; `contract list --cut` lists every turn that did not close cleanly, naming the specialist and the lane; `contract view --harness-id <agentId>`, with the id the dispatch returned, gives that turn's own partial evidence.

Reading order

**Phase 0 — triage, always, cheap.** Read `agent_status.agent_state`, then `cut_reason`, then `continues_contract_id`, in that order. `agent_state` routes everything downstream. `cut_reason` says whether that state is honest: it is stamped at birth and cleared only by a clean finalize, so clean-versus-cut is recorded by design, not inferred. `never_finalized` means the turn never closed itself; `backstop_capture` and `reaped` are the stop hook's forensic cleanup; `salvaged_truncation` is rebuilt purely from the agent's incremental on-disk draft — which is why incremental writes are what survive a cut. `continues_contract_id` says whether "empty" means anything: a continuation row is born empty by design (Trap 3), and reading this before judging any field as empty is what keeps that design from reading as a failure. What the row does not hold was never delivered — an `open_gaps` entry the agent only narrated in its message did not survive the turn; treat the row's silence as the finding it is rather than reading the prose as if it had been persisted.

**Phase 1 — load what that state demands, one block.**

| `agent_state` | Load | |---|---| | `APPROVAL_REQUEST` | `approval_request`, and nothing else matters until the user signs. Load `orchestrator-present-approval`; do not execute. | | `NEEDS_INPUT` | `pending_steps` and `next_action`: the turn is stuck in the ORCHESTRATOR, not the user, and resuming the SAME agent keeps its state. | | `BLOCKED` | `failure_report` and `open_gaps`, read with the rule proven true today: the block is usually a stale premise in the dispatch itself — information about the dispatch, not about the agent. Route only when another owner can resolve it. | | `NEEDS_VERIFICATION` | Not "done": a plan-task-bound turn cannot seal itself. Dispatch `gaia-verifier`, binding `parent_handoff_id` to this producer row. A verifier pass may promote the work to `COMPLETE`; a fail returns it to `IN_PROGRESS` with evidence. Never accept a plan-task-bound producer's self-asserted `COMPLETE` as independent verification. | | `COMPLETE` | `evidence_report.verification` first, then `open_gaps`. Terminal: relay/synthesize the verified result. |

Only `COMPLETE` is terminal. A finalized `IN_PROGRESS`, `APPROVAL_REQUEST`, `BLOCKED`, `NEEDS_INPUT`, or `NEEDS_VERIFICATION` row is persisted, not complete.

For COMMAND_SET, reconcile `approval_request` with DB progress: exact ordered commands, `next_index`, consumed indexes, failed index/reason, and grant status. Do not infer that the set ran merely because it was approved. After a partial failure, report completed and untouched indexes distinctly, treat `FAILED` as a terminal/frozen grant, and route fresh investigation plus a new request/approval for any retry or remainder.

**Phase 2 — the findings.** `key_outputs`, and `report_prose` when the why is needed or when this row's coordinate is about to be handed to another agent.

**Phase 3 — evidence on demand, only for the claim about to be made.** `commands_run` and `verbatim_outputs` for a positive; `patterns_checked` for a NEGATIVE; `cross_layer_impacts` before touching anything adjacent. A row's claim about an ARTIFACT'S CONTENTS is a claim, never the contents: a `key_outputs` line saying the file now reads X is the agent's reading of it, and relaying that as the file's text skips the one step that could have caught a misreading. Relay it only after the `verbatim_outputs` excerpt that shows it, or after opening the artifact yourself; if neither happened, say it as the row's claim rather than as the artifact's content.

**Phase 4 — handoff.** Pass the COORDINATE, not the narrative.

Three traps, all measured today on real rows

1. **`evidence_report.verification.result == "pass"` means the check RAN, not that the artifact is good.** A real row closed `pass` over a document rejected for three blocking defects. A reader who SWEEPS rows looking for `pass` reports the opposite of what happened. The row is read, not swept. 2. **`patterns_checked` is the only field a zero-result search survives in.** If the claim about to be made is that something does NOT exist, this is the only possible evidence for it. 3. **A continuation row is born empty by design.** That is exactly why `cut_reason` and `continues_contract_id` are read in Phase 0, before any field is judged empty — and why completeness is judged over the CHAIN, never the last link alone.

Relaying to the user

On a valid single-agent `COMPLETE`, SubagentStop parses `user_facing_summary` off the same envelope the gate treated as authoritative (`parse_user_facing_summary`) and emits it as the turn's `syst