Agent response

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.

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 systemMessage -- a channel that reaches the USER's display and does NOT continue your conversation (measured by suppression; see the comment over the relay in hooks/adapters/claude_code.py). Nothing arrived in front of you: the field lives on the row, and the one read that fetches it is contract view --field user_facing_summary --harness-id <agentId>. Read it when the user-facing report needs it and relay it near-verbatim. Synthesizing from key_outputs, verification, failures and open gaps is the fallback for when the field is absent, and at N>1 the per-agent summaries are inputs to one synthesis rather than N relays. Preserve ownership boundaries and do not hide evidence the row and the verdict disagree on.