---
name: adversarial-review
description: >-
  Run the cross-model adversarial review gate on a pull request: a *different* model from the one
  that wrote the code reviews the open PR adversarially and posts its findings as PR comments, before
  the change is declared done. Covers reviewer selection (the fallback chain), the auditable
  PR-comment protocol, the bundled headless-Gemini harness (`tools/agy-review`, typed exits), and the
  one-time machine setup headless reviewers need. Also covers reviewing a numeric or engineering
  contract (a physical model, sizing or pricing calculation, tolerance table — anything whose units
  mean something), where findings carry counterexamples, fixes carry recomputations, and each
  counterexample becomes a permanent test vector. Use for any complex change — more than one layer
  touched, a new pattern introduced, or unattended/production consequences — in any repo, driven by
  any coding agent (Claude Code, Codex, or another CLI agent).
---

# adversarial-review

A change is not done when its author believes it works — it is done when a **different model** has
tried to break it and failed, on the record. Self-review shares the author's blind spots; the gate
exists to put a second, adversarial intelligence between "looks right" and "merged". The reference
deployment's history shows why this is worth the round-trips: reviewers have caught data-loss paths,
dedup bypasses that would have spammed a human every run, silent-failure windows, and — reviewing
this very skill's harness — eleven real defects the author had just written.

**When the gate applies:** any *complex* build — it touches more than one layer, introduces a new
pattern, or has unattended/production runtime consequences. Trivial mechanical edits don't need it.
When in doubt, it applies.

## The rules

1. **Reviewer ≠ author, by model.** Select by model *diversity* first, availability second. If
   Claude wrote the code, Gemini, Codex or MiniMax reviews it; if Codex wrote it, Gemini, Claude or
   MiniMax reviews it. Same-model review is a genuine last resort — and must be disclosed on the PR so
   the weaker gate is visible.
2. **PR-anchored.** Review the *open PR*, not a local diff: the merge-base diff (`main...HEAD`) is
   exactly the author's change, and the PR description is the stated intent the reviewer can check
   it against. (A quick local-diff pass is fine while iterating pre-push; the auditable gate before
   merge is the PR review.)
3. **Findings live on the PR.** The review lands as PR comments naming which reviewer ran and its
   verdict (APPROVE / CHANGES-REQUESTED) with findings as `file:line` + severity + why it is a real
   defect. The author replies on the PR addressing every finding — fixed, rebutted with evidence, or
   accepted-with-rationale — so the whole gate is auditable later.
4. **Iterate to convergence, judged by whether a fix removes a *cause* — not by the finding count, and
   not by diff size.** Fix, push, re-review. Rounds often shrink (11 findings → 3 → 0), but not always:
   one gate ran 5 → 2 → 2 → 4 → 0 and the count carried no signal. The useful question is what a fix
   *did*. Consolidating a decision that lived in two places, or deleting a special case, ends a whole
   class of finding; bolting another guard beside the existing ones ends one instance and leaves the
   next reviewer more surface to reason about. In that gate the converging round's fix happened to
   delete 83 lines — but plenty of correct fixes legitimately **add** code (a missing liveness signal
   per `silent-failure-design`, input validation, a counterexample folded in as a permanent test
   vector), and **nothing here licenses stripping a safeguard to make a diff look convergent.** The tell
   for symptom-patching is not size but **repetition**: successive rounds adding guards to the same
   area, each needing its own reasoning about how it interacts with the last.
5. **Verify a finding's *premise* before acting on it — a CHANGES-REQUESTED is not automatically right.**
   Rebutting a premise takes **empirical proof** — a caller search, an execution trace, test output —
   never an opinion that the finding seems wrong, and the proof goes in the PR reply under rule 3. This
   rule raises the evidence bar on the author; it is not licence to dismiss an inconvenient finding.
   With no proof to hand, treat the finding as correct. The mirror of "an APPROVE is not a pass". A reviewer reasons from the diff and can be wrong about
   the code around it, and its remedy is then wrong in a way that *looks* rigorous. In the run above, a
   finding argued a function must avoid `resolve()` because it "runs on the 60-second health poll". It
   did not — its only caller was the weekly backup job, which one `grep` for callers would have shown.
   The optimisation added to satisfy it caused **three** real defects in the next round; deleting it
   converged immediately. Check the premise whenever the remedy **adds** complexity: that is precisely
   when being wrong is expensive.
6. **Watch for fix-induced findings, and treat a run of them as a signal.** Three of thirteen findings
   in that gate existed *only* because of earlier fixes. Once you see the second one, stop patching and
   look for the shared root — twice it was the same shape, one decision living in two places and
   drifting. The remedy is a single home, which is a deletion, not a guard.
7. **Point the harness at the PR you think you are reviewing.** Deriving a review invocation by copying
   a previous one and substituting the number is how a reviewer ends up auditing a different, already-
   merged PR while its instructions describe yours — a review that *appears* to have run, on the wrong
   thing. Read back the resolved PR number before launching, and treat the verdict as void if the
   posted comment is not on your PR.
8. **A dead reviewer is a *done* reviewer.** A hang, timeout, rate-wall, or silent exit means that
   leg of the chain is finished for this round: advance to the next reviewer. Never retry in place,
   and never skip the gate because a tool misbehaved.
9. **Re-assert your working branch** after any review tool runs — review CLIs can check out or
   strand the branch under you. The bundled `agy-review` harness removes this hazard at source by
   running the reviewer in an isolated worktree (see *The headless-reviewer contract*), but the rule
   still holds for the Codex leg and any CLI you drive raw in the live tree.
10. **Scope and shape are findings.** The PR description is the stated intent (rule 2), and the diff
   is checked against it in both directions: a hunk that does not trace to the intent — a drive-by
   improvement, a reformat of passing lines — is a finding, and so is structure the change does not
   need — speculative abstraction, configurability without a second caller, handling for scenarios
   that cannot occur. The authoring-side rules live in implementation-discipline; this is the gate
   holding a diff to them, where they are defects to name, not taste differences. And since no leg
   of the chain reads this page, name the lens when you delegate — a label/prompt line such as:
   "also flag, by reading the diff, any hunk that does not trace to the PR's stated intent, and any
   abstraction or error handling the change does not need".

## The fallback chain

Pick the first *available* reviewer whose model differs from the author's. Four concrete legs — Gemini,
Claude, Codex, MiniMax — each eligible whenever the author is **not** that model; order the eligible ones
by diversity first, then window economics (lead with the idle separate-subscription pools — Antigravity,
then MiniMax; conserve the walled Codex bucket and the Max window Claude shares with interactive work).
The recurring case is a **Claude-authored** change, whose order is therefore Gemini → MiniMax → Codex
(Claude itself is ineligible): the two idle separate budgets spend first, Codex — which walls for days —
last. A **Codex-** or **Gemini-authored** change has Claude as a first-class leg, not the last resort — do
not reach past it to a same-model reviewer. MiniMax adds a genuinely different model family (a fourth
vendor, separately trained): it differs from *any* author, so it is eligible on every review and is never
the *only* thing between an author and a same-model gate. Diversity here is the eligibility gate — a
reviewer must differ from the author — while the *order* among the eligible legs is window economics,
which is why the idle Antigravity pool still leads and MiniMax follows it rather than jumping the queue.

1. **Gemini** — the idle-pool lead; ineligible only when Gemini authored the change. Via the bundled
   harness: `tools/agy-review <pr>
   [--repo owner/name] [--label focus]` (path relative to this skill's directory — from a clone of
   this repo that is `plugins/coding/skills/adversarial-review/tools/agy-review`), run from inside a checkout of
   the repo under review. It pre-flights the known silent
   killers, bounds the run, and verifies success by the *posted PR comment*, never the CLI's exit
   code. `--model "<label>"` runs the review on another Antigravity-pool model (see *Quota-aware
   reviewer selection*), and every result line carries the run's `conversation: <id>` for follow-ups
   (see *Follow-ups*). Gemini leads on **window economics, not review quality**: the Antigravity
   subscription is a budget separate from both the author's Claude plan and Codex's single shared
   ChatGPT-Plus bucket — which rate-walls for *days* and is better saved for the coding work it is
   the capability fit for. (Flipped from Codex-first 2026-07-22, the day Codex hard-walled to the
   28th mid-review while the Antigravity pools sat at 2–6% weekly.) Typed exits tell you what
   happened and what to do:

   | exit | status | next action |
   |---|---|---|
   | 0 | ok | comment is on the PR — read it, address it |
   | 2 | auth-needed | run `agy` once interactively to sign in, retry |
   | 3 | permission-denied | grants missing a rule → restore (*Machine setup*), retry; grants intact → read the narration tail: a posting-step denial → relay salvage (*Follow-ups*), else autopsy for the invented command (below) |
   | 4 | timeout | treat this leg as done; advance the chain |
   | 5 | no-comment | narration tail is printed for diagnosis; advance the chain |
   | 6 | bad-args / missing prerequisites | fix the invocation |

   Exits 4 and 5 are also where a *window-burn* lands — a run that spent itself waiting on a
   long-running command. The harness flags that shape (repeated "waiting…" narration, nothing
   posted) instead of reporting a generic silence, so you can tell "the reviewer wasted its round"
   apart from "the reviewer died" — and reword an offending `--label` before the next *round*. It
   is a heuristic, so treat it as the first hypothesis, not a ruling: the debug log and a
   conversation autopsy (see *Follow-ups*) are what confirm any death.

   And exit 3 is not always a missing grant. An **intact** grants block — every documented rule
   present — with a permission-denied exit is not a `config.json` regression; editing config is the
   wrong lead. Which recovery to reach for is settled by the **narration tail**, and its two shapes
   want opposite responses. A tail that dies *mid-read*, reaching for a command, is the reviewer
   inventing an un-granted command: go straight to the conversation autopsy (see *Follow-ups*) to
   recover the exact command it proposed — when the diff under review is shell, that command is often
   `bash -c` reaching to test a shell semantic empirically (see *The headless-reviewer contract*). A
   tail that instead shows a **finished verdict whose only denial was the posting step** — the review
   is composed, and a command the config does not allow was soft-denied as it tried to post (the
   print-mode shape) — is not an invented-command death at all: the first response is the **relay
   salvage** (see *Follow-ups*), recovering the composed review from the kept conversation and
   relaying it, before you treat the leg as spent.

2. **Claude** — ineligible only when Claude authored the change; for a Codex- or Gemini-authored change
   this is a first-class leg. There is **no bundled harness** — none is needed, because Claude does not
   share the hostile silent-failure modes that forced the Gemini harness into being: print mode returns
   findings on stdout and a **non-zero exit on hard failure**, so success is directly observable. Drive
   it like the Codex leg below. Two forms: when your driver is **Claude Code**, spawn a fresh subagent
   (the Task tool) with *no shared context*; otherwise run **`claude -p`** headless. Either way hand it
   ONLY the PR diff, the PR description, and a mandate to break the change — plus the scope-and-shape lens
   (rule 10), which no reviewer reads off this page. Claude posts nothing itself: relay its findings with
   `gh pr comment`, naming the reviewer. Bound a `claude -p` run like any review CLI (see *Bounding a
   review CLI*). (If you ever drive this leg headlessly often enough to feel the hand-rolling, that pain —
   not symmetry with `agy-review` — is the trigger to build a `tools/claude-review` harness; until then a
   speculative one is exactly the structure rule 10 says not to add.)

3. **Codex** — ineligible only when Codex authored the change. `codex review --base <main>` reviews the
   branch diff. Note it takes **no** custom prompt (`--base` and `[PROMPT]` are mutually exclusive), so
   when you need to forward instructions to the reviewer — a focus, or the evidence contract in *Reviewing
   a numeric or engineering contract* — use the `codex exec` form in *Bounding a review CLI* instead.
   Codex doesn't post to the PR itself: relay its findings with `gh pr comment`. Run it bounded and in
   the background (see *Bounding a review CLI* below); expect a subscription rate wall after
   roughly a dozen rounds in a session — the wall locks the shared bucket for days, which is why
   it sits last among the different-model legs. Its review quality has earned its place in the
   chain (it has caught data-loss-class bugs the author's own tests missed); reach for it when the
   Gemini or Claude leg dies typed or when a second independent model is worth the window.

4. **MiniMax** — ineligible only when MiniMax authored the change (i.e. never, for a repo whose agents are
   Claude/Codex/Gemini), so it is an eligible different-model leg on *every* review, and the most diverse
   one — a fourth vendor's model, separately trained. It draws its own **MiniMax subscription** (a
   Token/Coding plan), a budget independent of the Claude, ChatGPT and Antigravity plans, so it spends
   nothing the author or the other legs need. There is **no bundled harness** — build one only when the
   hand-rolling is felt (rule 10); drive it like the Codex leg. The catch that shapes the prompt: `mmx text
   chat` is a **pure chat completion — no repo, `gh`, or tool access** — so, unlike agy/codex, it can fetch
   nothing itself. Hand it the whole change *inline*: run `gh pr diff <n> --repo owner/name` and `gh pr
   view <n> --repo owner/name` yourself and paste both (the diff + the stated intent) INTO the prompt,
   alongside the break-it mandate and the scope-and-shape lens (rule 10) — name `--repo` on both so a
   multi-checkout session diffs the right repo. Send the prompt on stdin as a JSON messages array
   (`echo '[{"role":"user","content":"…"}]' | mmx text chat --messages-file - --output json`), and bound
   the run (`--timeout <secs>`, wrapped in the watchdog of *Bounding a review CLI*). It posts nothing
   itself: relay its findings with `gh pr comment`, naming the reviewer (`MiniMax (mmx)`) and its verdict.
   It walls *typed* like the others — an exhausted/rate-limited window returns a documented MiniMax error
   code (1002/2045 rate · 1008/2056 quota), so treat a walled run as a done leg and advance. Note that mmx
   **silently substitutes its default model for an unknown `--model`** rather than erroring, and there is no
   `mmx models` catalogue to check against — so pin a model your plan documents (e.g. `MiniMax-M3`) and
   confirm it by the **served model in the response** (the envelope's `model` field must equal your pin),
   never by trusting the call to have run what you asked for.

**Last resort — same-model, disclosed.** When *no* different-model reviewer is available (every other
model's CLI missing or walled), run a same-model reviewer: a fresh agent of the author's own model with
*no shared context*, handed only the PR diff, the PR description, and a mandate to break the change.
Disclose on the PR that the gate ran same-model, so the weaker diversity is visible. This is the floor,
never a substitute for an available different-model leg.

## Prerequisites — what each leg needs before you pick it

The **Gemini** leg self-enforces: `tools/agy-review` pre-flights its prerequisites at runtime and fails
with a typed exit — `6` if `agy`/`gh`/`git`/`python3` is off PATH or you are not inside the repo's
checkout, `2` if `agy` is not signed in, `3` if a grant is missing (*Machine setup*). You need not check
by hand before that leg.

The **Claude**, **Codex**, and **MiniMax** legs have **no wrapper** — nothing pre-flights them, so a
missing CLI or a dead login surfaces only as a failed run mid-review. Confirm them yourself first. Every
leg also needs `gh` authenticated and a git checkout of the repo under review; findings post as PR comments.

| leg | CLIs | auth / setup | one-line check |
|---|---|---|---|
| Gemini | `agy` `gh` `git` `python3` | signed into Antigravity + one-time grants (*Machine setup*) | `agy models` lists models (the harness checks the rest) |
| Claude | `claude` `gh` | signed into Claude | `claude -p "reply with ok"` returns `ok` |
| Codex | `codex` `gh` | signed into ChatGPT (Codex) | `codex --version`, and `codex exec "say ok"` answers |
| MiniMax | `mmx` `gh` | subscription key in `~/.mmx/config.json` (a Token/Coding plan) | `mmx quota show` returns windows, and `mmx text chat --message "say ok"` answers |
| all | `gh` | `gh auth login` | `gh auth status` is green, run from inside the repo checkout |

A cold machine typically fails on auth (a CLI installed but not signed in) or, for Gemini, the one-time
grants — both are `agy models` / `claude -p` / `codex exec` away from a clear answer.

## Reviewing a numeric or engineering contract

Some changes carry numbers the world will hold you to: a structural or physical model, a sizing or
capacity calculation, a pricing or rate formula, a tolerance table — any spec whose units mean
something. This class reviews *differently*, and unusually well. Truth conditions are crisp, so
neither side can hand-wave: one gate run over an engineering document returned thirteen findings and
**every one was real** — a units trap, load cases that failed to superpose, an unstated support
geometry, an absent material limit, and under-specified vectors.

That hit rate is not luck, and it does not survive prose. It comes from holding *both* sides to
executable evidence:

- **A finding must carry a counterexample.** Concrete inputs, the value the change produces, and the
  value that is correct — "with `F = 4 kN` and `L = 800 mm` this returns `M = 3200 kN·m`; the moment
  is `4 × 0.8 = 3.2 kN·m`, so the length was never converted from millimetres — a factor of 1000"
  beats "the units look wrong". Note that the *unit alone proves nothing*: `3.2 kN·m` and
  `3200 kN·mm` are the same quantity, so a finding has to put two **numbers of the same quantity**
  side by side, not two spellings of one.
- **Where the contract is under-specified, demonstrate the divergence instead.** For an omitted
  support condition, an unstated sign convention or a missing limit there is often no single correct
  value *yet* — the defect is precisely that several defensible readings give different answers. The
  evidence is then two readings and their two numbers ("modelled as pinned the reaction is 12.4 kN,
  as fixed it is 18.1 kN; the spec never says which"), which is as executable as a wrong/right pair
  and must not be dismissed for lacking one. What makes a finding an opinion is the absence of
  *concrete numbers*, not the absence of a single right answer.
- **A fix must carry a recomputation.** The fix commit includes the script or derivation that
  produces the new numbers, and the reply shows before → after. "Fixed" is not evidence: a reviewer
  who cannot see the recomputation has to re-derive it, which is exactly how rounds stop shrinking.
  The headless grants already allow `uv run`, so the reviewer can *execute* the check rather than
  trust it.
- **The counterexample becomes a test vector.** Fold the reviewer's own numbers into the artefact's
  permanent checks — a test, an assertion, a worked-example row. This is the step that pays forward:
  it turns a one-off adversarial exchange into a regression guard, so the same defect cannot return
  silently once the thread is closed.

**Forward this contract — no leg of the chain reads this page.** Every reviewer sees only what you
hand it, so a protocol documented here alone is never applied: you get ordinary prose findings and
none of the hit rate above. Forward the block below on whichever leg you use, keeping it inside the
label-hygiene rules (static reading, name only permitted extras, never cite an external reference):

- **Gemini** — pass it as `tools/agy-review <pr> --label "…"`.
- **Claude** — include it in the subagent brief or the `claude -p` prompt, alongside the diff and PR
  description.
- **Codex** — pass it in the prompt to `codex exec` (see *Bounding a review CLI*). Note that
  `codex review --base <branch>` takes **no** custom prompt: the two are mutually exclusive
  (`the argument '--base <BRANCH>' cannot be used with '[PROMPT]'`), so `exec` is the form that can
  carry this contract. When the Gemini leg runs, a numeric review rides the harness's `--label`, but
  forwarding matters most on THIS leg: `codex review` is the form that CANNOT carry the contract, so
  reaching for it out of habit silently drops the whole protocol.
- **Same-model last resort** — include it in the brief, alongside the diff and PR description.

```
Numeric contract. For EVERY finding give concrete inputs, the value the change produces, and the
value that is correct — two numbers of the same quantity, since a unit alone proves nothing. Where
the spec is under-specified, instead give two defensible readings and the different numbers they
produce. You may check arithmetic with 'uv run'. On a follow-up round, also check the fix side: each
correction must ship a recomputation showing before and after, and the counterexample must have been
added to the artefact's permanent checks — flag any correction missing either. Look for: units and
scale factors; sign and direction conventions left unstated; cases that must combine or superpose
but do not; boundary, support or initial conditions assumed rather than declared; a missing limit
(strength, capacity, rate, budget); and the domain of validity — the range outside which the formula
quietly stops being true.
```

The fix-side clause matters because follow-up rounds are exactly when the recomputation and the test
vector are due, and a reviewer holding only the finding rules will approve a correction that ships
neither. Each defect class above is invisible to a prose read, and each has shipped at least once.

## Machine setup (one-time, per machine) — headless Gemini

These grants govern the **headless reviewer only** — the sandboxed `agy -p` process the harness
drives. Authoring agents (the ones picking up issues, editing labels, opening PRs) run under their
own harnesses' permission systems and are not constrained by this block; do not read it as the
capability envelope of the whole workflow.

`agy -p` (headless print mode) **auto-denies every confirmable tool** unless grants exist — and it
denies *silently*: exit 0, no output, no comment, indistinguishable from a hang. The grants live in
**`~/.gemini/config/config.json`** — the two look-alike files are decoys (`~/.gemini/settings.json`
belongs to gemini-cli; `~/.gemini/antigravity-cli/settings.json` loads but is not consulted):

```json
{
  "userSettings": {
    "globalPermissionGrants": {
      "allow": [
        "read_file(*)",
        "command(git)",
        "command(gh pr view)",
        "command(gh pr diff)",
        "command(gh pr comment)",
        "command(ls)", "command(cat)", "command(head)", "command(tail)",
        "command(grep)", "command(rg)", "command(find)", "command(sed -n)",
        "command(wc)", "command(uv run)", "command(bash -n)"
      ]
    }
  }
}
```

Two distinct layers, both required: `command(...)` rules are **prefix** matches on the Bash command
line (`git` matches `git add`, *not* `github`), and `read_file(*)` covers agy's *internal*
Search/read tools — without it the reviewer dies the moment it greps. Keep the set scoped: do **not**
grant `command(echo)` or `write_file(*)` (echo + shell redirection is arbitrary file write, and
keeping them denied forces review comments through the inline `--body` path the artifact contract
needs), and do not use `--dangerously-skip-permissions` (it removes the entire approval gate).
`command(uv run)` is deliberately whole: `uv run pytest` already executes arbitrary repo code via
test collection, so narrowing to it bought no safety — while the narrow form killed a reviewer
mid-insight when it reached for `uv run python -c` to check packaging metadata (a check that later
proved to be a real defect). Note that this grant is what makes the *prompt-side* ban on running the
test suite necessary (see *The headless-reviewer contract*): the permission layer decides what is
allowed, not what is wise, and the suite is now allowed. Sign in once by running `agy`
interactively.

## Quota-aware reviewer selection

Every reviewer burns a subscription window, and the windows are the real wall — plan spend the way
you plan the review:

- **The chain degrades reactively by design.** A walled or exhausted reviewer fails *typed*
  (rate-wall, `timeout`, `no-comment`) and you advance — no pre-flight quota probe is built in, and
  none is needed at review volumes. If your deployment already tracks provider windows, a glance
  there before a long review session is cheap; do not rebuild that tracking inside the gate.
- **The Antigravity pool is a separate budget.** `agy` exposes multiple model families (run
  `agy models` for the live labels — Gemini, Claude and GPT variants), all billed to the Antigravity
  subscription rather than the primary Claude/ChatGPT plans. When the primary plans are near their
  windows — or you simply want to preserve them for authoring — run the review on the pool:
  `tools/agy-review <pr> --model "<label>"`. An unknown label fails loud with the valid list.
- **The MiniMax plan is another separate budget.** MiniMax's Token/Coding subscription is billed apart
  from the Claude, ChatGPT and Antigravity plans and metered in its own 5-hour + weekly windows — so the
  MiniMax leg is the one to reach for when those three are near their walls: a fresh, cheap, maximally
  diverse reviewer that costs the primary plans nothing. It degrades reactively like the rest (a walled
  window returns a MiniMax quota error, so you advance).
- **Diversity still outranks quota.** The pool's Claude models let you review Claude-authored code
  without spending the primary Claude plan — but that is same-family review (weaker diversity, older
  generation). Prefer a genuinely different family first; reach for same-family-via-pool to preserve
  quota, and disclose it on the PR like any weaker gate.
- **Older pool models are fine for this job.** Adversarial review is careful *reading*; a
  previous-generation model with the diff in front of it catches real defects (the reference
  deployment's gate history is largely a mid-tier model finding genuine bugs).

## Follow-ups — interrogating a review

Continuity across rounds lives in the **PR comment thread** — the only session that survives
switching reviewer legs mid-chain — so rounds are deliberately stateless: each re-reads the PR,
including prior findings and author replies. Native conversation resume is NOT the round-to-round
mechanism (it cannot cross providers, exactly when the chain switches). It is, however, a superb
*diagnostic*: every `tools/agy-review` result line carries the run's `conversation: <id>`, and

    agy --conversation <id> -p "your follow-up"      # --conversation BEFORE -p; headless works

reopens that run with full context. Use it to ask a reviewer why it judged a finding as it did — or
to perform an autopsy on a dead run: a run killed by a denied tool can be *asked what it was trying
to do* ("what exact command did you propose at the final step, and why?"), which has turned an
opaque typed failure into the missing grant — and once revealed that the dying reviewer had been
mid-way to a genuine defect the next leg later confirmed.

**The relay salvage.** The posting step is the fragile one, and it fails in more than one way. The
permission validator shell-parses the composed `--body`, so backticks, escape sequences, or nested
quoting in an otherwise-legitimate comment can kill a run whose review is already complete; and more
broadly, *any* command the config does not allow at the posting step — soft-denied in print mode
rather than refused loudly — ends the run the same way, the exit-3-with-intact-grants shape whose
narration tail shows a finished verdict (see *The fallback chain*). When an autopsy shows a finished verdict
that simply failed to post, first ask the resumed run to re-post with a plainer body; if that is
denied too, **relay it yourself**: post the reviewer's verdict verbatim with `gh pr comment`,
naming the reviewer, noting the relay, and including the conversation id — the same pattern the
Claude and Codex legs (which post nothing themselves) use routinely. The gate's requirement is an
auditable verdict on the PR, not that the reviewer's own process wrote the bytes.

## The headless-reviewer contract

These rules are what make *any* headless review CLI reliable — they are baked into `tools/agy-review`
and are the spec for porting the gate to a new reviewer:

- **Verify by artifact, never by exit code.** The success signal is the posted PR comment (the
  harness counts marker comments before and after — immune to clock skew and old comments). Headless
  CLIs exit 0 on every failure mode above.
- **A reviewer's read of the code can't see a validator/reader disagreement.** Two components meant
  to agree — a schema and the field it silently rejects, a writer and the reader downstream — can
  diverge at run time with nothing visible in either one alone, and neither a review that reads the
  diff nor a test that mocks the load path will catch it: the defect only exists once the real path
  executes. A config or deploy change is verified by exercising the *real, unmocked* path — write the
  actual file, run the actual resolver — never by a green test suite or an approving read alone.
- **Bound the run and kill the tree.** Set the CLI's own timeout above the review's real duration
  (agy's default print-timeout is 5m — too short; pass 15m), wrap it in a watchdog that kills the
  full descendant tree depth-first (review CLIs spawn node/language-server grandchildren a PID-only
  kill orphans).
- **Pin the reviewer's commands to permission-matchable forms.** The prompt instructs: `git -C
  <root>` and `gh ... --repo <owner/name>` only, never `cd`, never `&&`/`;` chains — prefix matching
  sees only the first word of a chained command.
- **Name the exact allowed command set in the prompt.** Any un-granted command the model invents is
  fatal mid-run: one review died staging its comment body via a denied write path, another reaching
  for a command the grants did not cover. Granting a command does not make it safe to invoke,
  though — see the next rule.
- **Ban the long-running command; keep the fast checks.** The mirror-image death: a reviewer decided
  to run the project's test suite — a *granted* command — and then spent its entire remaining window
  polling it ("I am waiting for pytest … checking back in 60 seconds", over and over) before exiting
  cleanly with nothing posted. Nothing was denied, so no grant change fixes this; the leg is lost
  just as completely, and the typed no-comment looks identical to every other silence. Three rules
  for the prompt, each guarding a trap a draft of this one fell into. **Ban the suite by name**, and
  justify it as CI's job and the author's — never by asserting the author already ran it, which the
  prompt cannot know and which tells an adversarial reviewer to trust the very claim under test.
  **Make the operative rule *never poll*, not a wall-clock budget**: a reviewer cannot predict a
  command's duration before running it, but it can always decide not to wait on one — abandon it, go
  back to reading, post. (A flat budget also disarms the `uv run` arithmetic check *Reviewing a
  numeric or engineering contract* depends on, whose first run may sync dependencies.) **Name the
  short checks that stay welcome individually, from your own grants** — `bash -n` and a single
  `uv run python -c` here — never an open-ended category: "a quick single-file check" invites
  `shellcheck` or `node --check` and trades this death for the un-granted-command one above. The
  same care belongs in your `--label`: "check the tests pass" walks the reviewer straight into this.
- **Post with one inline call, and no backticks in the body.** The final `gh pr comment --body
  "..."` must carry the body inline — staging it in a file via echo/printf/redirection/file-write
  tools is denied and kills the run at the last step. And the permission validator parses
  **backticks inside the body as command substitutions**, permission-checking their contents as
  commands: a review comment that backticks any un-granted identifier (which is most of them) dies
  at the posting step, while one whose snippets happen to start with granted words slips through —
  the most confusing failure in the whole class. The prompt therefore bans backticks in the body
  (code identifiers go in single quotes); a run that died here anyway can be salvaged by resuming
  it and asking it to re-post without backticks (see *Follow-ups*).
- **Ensure the reviewer's scratch clone exists and is fresh.** agy reviews in its own clone
  (`~/.gemini/antigravity-cli/scratch/<repo>`). Stale, a just-merged SHA does not exist there;
  *absent*, agy bootstraps one itself via commands outside the allow-list and dies silently at
  step 1 — the first review of any repo agy has never seen fails this way. The harness clones or
  fetches it deterministically before the run; do the same when driving agy raw.
- **Run the reviewer in an isolated worktree, never your live tree.** A headless review CLI's
  workspace layer checks out a `pr-<n>` branch in its own working directory mid-review. When that
  directory is the coordinator's live checkout, two things break: the branch is *stranded* (the
  caller's `HEAD` moves under them — commits then land on the wrong branch, the push reports
  up-to-date, and the tell is only spotted later), and worse, a coordinator editing files while a
  background round runs hits a *contested tree* — an edit lands against the wrong branch's contents
  or a file the round's checkout has removed (an `Edit` hit a missing file exactly this way). The
  harness fetches the PR head and runs agy in a **detached worktree** at that SHA (`git worktree add
  --detach`), so the reviewer's branch-switching is confined to a throwaway tree and the caller's
  checkout is never touched — you can keep editing while a review runs. It falls back (loud) to the
  caller's tree plus a before/after branch-restore guard only when a worktree cannot be made. This
  is the structural fix for rule 9: prefer worktree isolation over re-asserting the branch after the
  fact.
- **Steer review labels to static reading — and steer the opening move.** Every label phrase that
  implies a tool is a landmine: "verify the shell fixes" sends the model to shellcheck; naming
  "git-fetch(1)" sends it to `man` — each un-granted, each fatal at step 1 with zero narration.
  Say "by reading the diff", name any permitted extras (`bash -n`), never cite external
  references, and when a repo is new to the reviewer, open the label with "START by running
  'gh pr diff <n> --repo <owner/name>' — no other command first". When the diff under review is
  *itself shell*, the subject matter is a landmine no label phrasing avoids: a reviewer auditing a
  bash hook's error handling reaches for shell *execution* to settle a semantic question
  empirically, so reviewing shell makes this death likely rather than incidental. One review of a
  deployment-critical hook died exit-3 with the grants block fully intact, proposing
  `bash -c 'set -e; ( false; echo "still ran" ) || true'` to check whether `set -e` survives inside
  a subshell. `command(bash -n)` is granted; `bash -c` is not — prefix matching does not cover it —
  and it stays un-granted, being arbitrary code execution refused for the same reason as
  `command(echo)` and `write_file(*)` (see *Machine setup*). A bare "do not run `bash -c`" only
  moves the wall, because the reviewer still needs the answer. So the shell-diff label must do both:
  forbid executing shell snippets (and `bash -c` by name), **and pre-answer the semantic question**
  the reviewer would otherwise test — e.g. that bash suppresses `set -e` inside a compound command
  used as the left operand of `||`, so the code under review must give every fallible command an
  explicit `|| { …; exit 1; }` rather than rely on `set -e` to abort. The pre-answer is the actual
  fix; the prohibition alone just relocates the death.

## Bounding a review CLI (Codex or any other)

Never run a review CLI bare in the foreground. Launch it in the background, wrap it in a
self-terminating watchdog that kills the child **tree**, and treat a hang or wall as that reviewer
being done:

```bash
codex exec "review ..." < /dev/null & p=$!
( sleep 600; pkill -KILL -P "$p" 2>/dev/null; kill -KILL "$p" 2>/dev/null ) & w=$!
wait "$p"; kill "$w" 2>/dev/null
```

Close stdin explicitly (`< /dev/null`): backgrounded with stdin left as an open non-TTY pipe,
`codex exec` prints "Reading additional input from stdin..." and waits on that pipe forever — the
watchdog kills it with nothing reviewed, indistinguishable from a rate wall.

Point `CODEX_HOME` at a lean home with no MCP servers configured — MCP loading is the commonest
Codex hang.