adversarial-review-loop

adversarial-review-loop

A Claude Code plugin that implements an agreed plan phase by phase, with an external adversarial review as an enforcement gate. Claude cannot commit a phase until a separate reviewer — a second claude process by default, or OpenCode — has reviewed the exact tree it is about to commit and passed it.

The reviewer is external in the sense that matters: a fresh process, isolated from your ambient plugins, skills and MCP servers, given the diff as evidence and a fixed prompt, with no way to write anything and no memory of the session that wrote the code.

The review is not advice Claude may weigh up. It is a PreToolUse gate on the commit itself: findings come back as a denial, and the commit only proceeds once they are resolved.

/adversarial-review-loop:implement plan.md
   -> arms (freezes the baseline and the plan) before Claude has a turn
   -> Claude proposes phases and freezes them
   -> phase N implemented -> git commit -> INTERCEPTED
        snapshot the whole working state into a tree
        the reviewer reads the delta since the last approved tree
        approved -> commit proceeds -> phase advances
        findings -> commit denied, findings returned inline
   -> all phases committed -> turn ends -> COMPLETE
        (plus a final cumulative review first, if final_review is on)

📋 Requirements

• Claude Code 2.1.287 or newer (the plugin registers PreToolUse, PostToolUse, PostToolUseFailure, Stop, SessionStart and UserPromptSubmit hooks in hooks/hooks.json)
• the reviewer CLI on PATH and authenticated: claude by default (you already have it), or opencode with harness set to opencode. Arming refuses if the configured one is missing.
• python3 3.12 or newer — the gate itself. No install step: the standard library plus a vendored, lint-excluded copy of bashlex is everything it needs. On macOS the bundled /usr/bin/python3 is 3.9 and will not do; install one from Homebrew or python.org.
• git, bash 3.2 or newer, and an outer watchdog for the hooks: timeout/gtimeout (GNU or uutils coreutils) or perl. macOS ships perl and no timeout, so it is covered out of the box. Arming refuses if none of them is present.

📦 Install

Add this repository as a plugin marketplace, then install the plugin:

$ claude
> /plugin marketplace add leinardi/adversarial-review-loop
> /plugin install adversarial-review-loop

Then raise the Stop-hook block cap so a long loop is not cut short. Claude Code caps consecutive Stop blocks (default 8) and overrides by ending the turn, which reads as success — so give the loop headroom in settings.json and restart Claude Code, since the variable is read at process start:

{
  "env": {
    "CLAUDE_CODE_STOP_HOOK_BLOCK_CAP": "40"
  }
}

If you use Claude Code's sandbox

Sandboxing is off unless you turned it on, so most people can skip this. If you did enable it, the loop needs two write permissions that a default-deny setup will refuse, and the symptoms do not look like permissions:

A blanket "denyWrite": ["~/"] covers both, and allowWrite does not re-open it — measured: paths listed in allowWrite are still refused when the home directory is denied. Narrow the deny instead of adding exceptions:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "denyWrite": ["~/.ssh", "~/.aws", "~/.gnupg"],
      "allowWrite": ["~/.local/state/adversarial-review-loop/**"]
    }
  }
}

excludedCommands does not help here: the loop's git runs inside the gate process, not as a git … command the sandbox can pattern-match. If you would rather not loosen anything, run the loop in a session with the sandbox off — it is a per-session setting under /sandbox.

If a command says "run this first" instead of running

On Claude Code 2.1.272 and later, a slash command's shell step runs only if Claude Code's permission check allows it. Otherwise Claude Code hands the command to Claude as [run this first, exactly as written, and use its output: …]. For /adversarial-review-loop:implement that ends in "arming never ran", because the gate will not let Claude arm the loop itself. Each skill ships its own allowed-tools rule for exactly the arl.sh subcommand it runs, so this only happens with an install older than that fix, or when your own permissions.deny or permissions.ask rule matches arl.sh. Update the plugin, or remove the rule. If a session is already stuck in NEEDS_HUMAN from a failed arm, leave the mode from a terminal outside Claude Code, in the repository: <plugin-root>/scripts/arl.sh deactivate --session <session-id>. The handed-off command shows both values.

🚀 Quick start

1. Write a plan as a Markdown file — whatever describes the work; there is no required format.
2. Run /adversarial-review-loop:implement plan.md. Arming happens before Claude gets a turn: the baseline and the plan are frozen, and the reviewer is probed for reachability.
3. Claude splits the plan into phases and freezes the list. Every mutation is denied until it does.
4. Claude implements phase 1 and runs git add -A && git commit -m "…". That commit is intercepted, reviewed, and either allowed through or denied with the findings inline. Repeat until the phase passes, then on to phase 2.
5. /adversarial-review-loop:status at any time; /adversarial-review-loop:report [n] for a review in full. While the loop is armed, a band above the prompt shows its status, phase, round and failures, and an alert (an unreviewed commit, NEEDS_HUMAN, a state that cannot be read) appears as a line in the transcript. The band is a display only: if it fails, the gate is unaffected.

Pause after phase 5 with --until 5, or mid-run with /adversarial-review-loop:pause. Pick a plan back up in a new session with /adversarial-review-loop:resume, which runs to the end of the plan unless you pass --until N again — never a second implement, which re-baselines and throws away every approval.

💻 Commands

Every command except status and report is disable-model-invocation: true: Claude can never arm, resume, finish, stop, accept, pause, or run config itself — only the exact slash command does, and no natural-language phrasing invokes any of them. A mode whose whole point is enforcement must not be self-enabling; the cost is that "use the review loop for this" does nothing. That stops the command, not ordinary file edits to what it writes — see the honest-agent bar under Known limitations.

🔧 Configuration

Resolution order: ARL_* environment → repo .adversarial-review-loop.json → $XDG_CONFIG_HOME/adversarial-review-loop/config.json → defaults. Environment variables are the upper-cased key with an ARL_ prefix (ARL_BLOCK_SEVERITY, ARL_MODEL, …).

The keys most people touch:

{
  "model": "openai/gpt-5.6-sol",
  "variant": "high",
  "verify_cmd": "make test",
  "ignore_globs": ["CHANGELOG.md", "docs/**"]
}

Every key, the full precedence rules, and what a review actually costs are in docs/configuration.md. State lives under $XDG_STATE_HOME/adversarial-review-loop/: no hook, and nothing Claude can invoke itself, ever writes inside the repository under review — the one exception is config <key> <value> --repo, an explicit user-only write.

❓ FAQ

Each question links to its full answer.

• How do I start? Install, write a plan .md, run /adversarial-review-loop:implement plan.md.
• How do I stop partway through? <kbd>Esc</kbd> stops the turn at once, mid-phase. To stop at a clean boundary instead — current phase finished, reviewed and committed — press <kbd>Esc</kbd>, run /adversarial-review-loop:pause, then continue.
• I quit / rebooted / /cleared mid-phase — how do I pick it back up? Same session id (claude --resume, or /resume back to it): just continue. New session: /adversarial-review-loop:resume --allow-dirty. /adversarial-review-loop:status tells you which you're in.
• Can I implement only part of a plan? --until N on implement or resume; carry on later with a bare resume, which clears the target.
• How do I customise what the reviewer looks for? review_guide — a Markdown file added to the reviewer's prompt. It cannot change the contract or what blocks.
• The reviewer keeps finding new things and the phase never converges. /adversarial-review-loop:accept [reason] approves the current tree without another review, and records that it did.

More — RECONCILE, NEEDS_HUMAN, rate limits, cost, running your tests as evidence, revising a plan mid-run — in docs/faq.md.

🚧 Known limitations

• Honest-agent bar. Claude could commit through a wrapper script, abuse defer, or edit .adversarial-review-loop.json directly — disable-model-invocation blocks the config command, not ordinary edits to the file it writes. Policy written there can weaken the gate silently: ignore_globs: ["**"] skips the reviewer call on every commit, a raised block_severity stops findings from blocking, and final_review false removes the cumulative backstop. None of these run unreviewed code; all of them change what the gate does. Nothing here defends against a deliberately hostile agent, and this design does not pretend to — see security.md.
• A mod can route around the gate. On Claude Code 2.1.287 and later, a JavaScript hooks module runs inside Claude Code rather than as a tool call, so it can commit and stop the mode without any command for the gate to see. The end-of-turn report still catches that case. According to the docs, a mod can also overrule the gate's denial or keep its hooks from running at all, which would silence the report too. A mod is installed by you, or written by Claude and loaded only if you answer "Enable hot reloading for this session". Don't enable that while the loop is armed: the answer lasts for the whole session. See security.md.
• The Stop-block cap is residual. Continuation pressure from PostToolUse, progress-aware counting and CLAUDE_CODE_STOP_HOOK_BLOCK_CAP mitigate it, but a run that repeatedly ends its turn without progress can still exhaust the cap — and exhaustion ends the turn.
• A slash command's argument reaches the shell unescaped, and the plugin can only mostly contain that. $ARGUMENTS is substituted into the skill body textually, with no shell escaping, so a plan path like x"; id; echo " used to run id. Every skill that takes an argument now hands it over inside a here-document with a quoted delimiter — the one shell construct whose body is never parsed — so the argument arrives verbatim and nothing inside it runs. The substitution itself is still not fixable here: it happens before any shell sees the body, so the containment remains that these skills are disable-model-invocation: true and only the person typing the slash command can supply the argument. An install also serves skill bodies from a version-pinned cache, so one installed before this fix keeps the old, breakable body until it is updated.
• Binding is session-scoped. An activation belongs to one session at a time, so /clear, a crash, or a fresh claude leaves you in a session that is not bound to it. Nothing is disarmed and nothing is lost — the activation stays armed and enforcing, and the unbound session is simply denied every mutation in that worktree until /adversarial-review-loop:resume binds it, carrying the baseline and every approval across. Returning to the same session (claude --resume) needs no command at all. The cost is that a second session resuming the worktree retires the first for good — see edge-cases.md.
• Cost and latency. Every phase costs at least one full-model review, and a denied commit blocks the session for the length of the review. The PreToolUse hook itself adds ~111 ms to every tool call — the measurements are in architecture.md.

📚 Documentation

🔨 Development

make test                    # 3900+ tests against scratch repos, plus the shim selftest; no model is called
make test-unit               # the pytest half only
make test-filter FILTER=watchdog # one shim selftest section
make dry-run                 # print the exact reviewer argv and prompt, without invoking it
make check                   # pre-commit (shellcheck, yamllint, markdownlint, …)

tests/unit/ drives the hook entrypoints with synthetic payloads against scratch git repos — through the same bootstrap production uses — and replaces the reviewer with tests/fixtures/fake-reviewer.sh (ARL_REVIEWER_CMD), so loop logic costs nothing to iterate on. It covers the snapshot layer, the command-shape table, every arm-failure mode, the fail-closed guards, commit divergence and reconcile, the findings cap, the Stop accounting and the TTL.

tests/selftest.sh is a separate, much smaller suite in bash, for the one layer pytest structurally cannot reach because it runs inside the Python being launched: the interpreter probe, the shim contract, the watchdog layers, socket stdin, and the hot path's process budget.

Running the tests needs jq, and comparing the chunker against the real GNU split needs GNU coreutils (gsplit); both are development-only — the gate itself uses neither, and those comparisons skip cleanly where coreutils is absent, as on a stock Mac.

With the plugin enabled, its hooks run in every session, armed or not, and they deny any Claude Bash command that names a user-only subcommand (arl.sh arm, finish, deactivate, resume, config, accept, pause). When developing this repository, set "enabledPlugins": {"adversarial-review-loop@adversarial-review-loop": false} in its .claude/settings.local.json, and load the working tree with claude --plugin-dir . only when you mean to use the loop.

AGENTS.md is the contract any change to this project has to honour — the five non-negotiable rules, the invariants, and the hazards that silently reopen a closed hole if reverted. Before the first real run, work through tests/STEP0.md: the harness assumptions that only a live Claude Code session can settle.

📄 Licence

GPL-3.0-or-later. See LICENSE.

The gate parses commands with bashlex, which is GPLv3 and is vendored under scripts/arl/_vendor/ so the plugin works straight from a checkout with no install step. See that directory's README for the version, the upstream commit, and the one change made to it.