shadow-verify

Sub-agent contract

/contract

When a sub-agent (or wave) returns investigation findings, code-review conclusions, audit claims, refactor plans, gap-analysis results, or counts that will drive user decisions or file changes, do NOT surface the report. Instead, run a shadow verification wave before merging.

Pre-flight: claim normalization and scale guard

Before dispatching verifiers, the coordinating agent normalizes each claim to a canonical form:

[CLAIM_ID] <subject> :: <predicate> :: <evidence_ref>

evidence_ref must be a concrete pointer — a file path, line number, git ref, config key, or API endpoint. Claims that cannot be anchored to a concrete evidence_ref are classified UNVERIFIABLE immediately and removed from the verification queue. They are preserved in the final output under a dedicated section with the reason they could not be anchored (no re-derivation sub-agent is dispatched for them).

Scale cap: if the normalized claim list exceeds 50 items, the coordinating agent halts and asks the operator to scope the investigation before proceeding. Verification at scale degrades into noise; a 50-item cap prevents a finding flood from becoming an echo-chamber rubber-stamp.

Select 2–3 of the highest-stakes normalized claims to send to the verifier wave. Prefer claims that are (a) decision-driving, (b) expressed with high-confidence language, or (c) hard to re-derive from a single artifact.

---

Wave 2 — Adversarial verifiers (parallel, independent):

1. Extract 2–3 concrete, re-checkable claims from the returned report (e.g., "X function is unused", "file Y exceeds 300 lines", "PR targets main", "no tests cover Z") and normalize them to [CLAIM_ID] subject :: predicate :: evidence_ref form as described above.
2. Dispatch one shadow sub-agent per claim, in parallel. Each receives the normalized claim text + the user's original goal + the search surface — the inventory of files, directories, or URLs the original investigation touched. It must NOT receive the original agent's reasoning, verdict, confidence language, or the specific line/region it concluded from. Withhold the conclusion, not the map. Withholding the map too does not buy extra independence — the verifier still has to reach the same evidence, it just spends its budget guessing paths to get there. Measured: one verifier denied the inventory spent 70 grep + 18 read_file calls re-locating files the parent already had paths for, guessed 5 nonexistent paths on the way, and hit its tool-loop ceiling before finishing. The independence that matters is epistemic (re-deriving the verdict), not navigational.
   • The inventory is a starting surface, not a boundary: it does not satisfy the composition-axis guard below, and a verifier that reads only inside it still returns evidence_base: artifact-internal. At least one primary source outside that surface is still required for independent-rederivation.
   • Default to subagent_type: "research-agent" (mechanically locked to Read/Grep/Glob/WebFetch/WebSearch — cannot Edit/commit/push). If the claim requires Bash to verify (running a failing test, gh pr view, git log origin/...), fall back to a Bash-capable subagent type with isolation: "worktree" and prepend this prefix to the prompt: "Verifier sub-agent — do not Edit, Write, commit, push, gh pr create, or curl. Return findings only."
   • Set id_prefix to a short label identifying the claim being verified, e.g. "verify: unused export" or "verify: missing null check", so the live TUI shows which claim each verifier is checking.
   • Every verifier dispatch carries an explicit budget — max_tool_use_iterations (a wave of 2–3 claim checks needs ~15–25 rounds each, not 50) plus the cheapest sufficient model. An unbudgeted verifier does not fail loudly: it exhausts the default tool-round ceiling, terminates stopReason: "tool_use_loop_capped", and emits its verdict from a tools-stripped wind-down round built on partial evidence. A CONFIRMED produced that way is indistinguishable from a real one and silently defeats the entire point of the wave. Check each returned verifier's stop reason before merging its verdict; treat a capped or wind-down verifier as UNVERIFIABLE, not as a verdict.
3. Each verifier re-derives the verdict independently using tool calls only — never re-reading the original report's reasoning. Returns {claim_id, verifier_verdict, evidence_pointer, evidence_base}, where verifier_verdict is one of CONFIRMED, REFUTED, STALE, or UNVERIFIABLE, and evidence_base is independent-rederivation (read primary sources outside the cited artifact's boundary) or artifact-internal (re-read only the cited file/region). On REFUTED or STALE, the verifier also emits a corrected or updated finding.