/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. Before re-dispatching or judging where a plan's spend went, `usage show --plan <id>` gives its tokens per session and per agent, split into bound, unbound and main (main is an upper bound); `brief history <slug>` shows how the brief's ACs, decisions and plan versions changed.

Reading order

**Phase 0 — triage, always, cheap.** Read the row with `gaia contract view --contract-id <id> --row --json` -- `agent_state`, `cut_reason` and `harness_agent_id` together; `--field` reads the envelope only and exits 1 on a row column -- then `gaia contract chain --contract-id <id>` for continuation. `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; a cut row keeps whatever state it last mirrored, so `agent_state` alone never says the turn is alive. `never_finalized` means the turn never closed itself; `backstop_capture` is the stop hook's capture; `reaped` has two authors -- the stop hook, for a turn that stopped without its own close, and SessionStart's host-death reaper (`hooks/modules/agents/dispatch_lifecycle.py::reap_stale_turn`), for a DISPATCHED row with no tool call inside two hours (`gaia contract reap --older-than-seconds N` runs it by hand); `salvaged_truncation` is rebuilt purely from the agent's incremental on-disk draft — which is why incremental writes are what survive a cut. The chain 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 on an answer the orchestrator must obtain -- from the user or from context it holds -- and resuming the SAME agent keeps its draft. | | `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. First read `open_gaps` and `pending_steps` against the task goal: a gap that contradicts the goal, or a declared check left unrun, resumes the producer -- a verifier would only rediscover it, and a gap declared costs one round where a hidden one costs two. Otherwise dispatch `gaia-verifier`, binding `parent_handoff_id` to this producer row. What a verifier promotes is the task's gate (`gaia task gate set-status`), never the row, which stays as it closed; a fail returns the task to the producer with evidence. An unbound `NEEDS_VERIFICATION` (no `plan_task_id`, no `parent_handoff_id`; finalize now refuses it, so only older rows carry it) is a producer that took the free door: resume it to close `COMPLETE` or `BLOCKED`, and dispatch no verifier for a row no task owns. 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. Read `memory_delta` too: its proposals are the specialist's, not yet memory, and what is kept, merged or dropped is yours to curate per Skill('memory'). The dispatch result flags a non-empty one with a line, `N project facts proposed for <project> — contract <i