Search guides, workflows, and reference pages.

Docs/Tools

adversarial-review

Capability: substrate:review

Harness: agnostic

Runs other models’ CLIs — Codex, Copilot, Antigravity, Grok, Claude — read-only over a change, and prints their merged findings as one JSON report. Magpie skills run it before they open a PR; pr-management-code-review runs it over someone else’s PR. Design: docs/designs/2026-09-23-adversarial-review.md.

Prerequisites

  • Runtime: Python 3.11+ via uv. The package itself is stdlib-only.
  • CLIs: at least one reviewer CLI on PATH — codex, copilot, agy (the antigravity reviewer), pi, grok, goose or claude — logged in with its own account. --target pr:<N> also needs gh.
  • Credentials: whatever each reviewer CLI already uses (~/.codex, ~/.copilot, ~/.gemini/antigravity-cli, ~/.pi/agent, ~/.grok, ~/.config/goose, ~/.claude); this tool reads none of them itself. Headless agy uses the sign-in cached by an earlier interactive agy session; without one it exits with authentication required, which the report shows as unavailable.
  • Network: each reviewer CLI calls its own model provider; this tool makes no network calls of its own.

Usage

Always as one line, so the one sandbox exclusion matches:

uvx --from ~/.claude/magpie/adversarial-review adversarial-review detect
uvx --from ~/.claude/magpie/adversarial-review adversarial-review run --base origin/main --title "<PR title>" --body-file <body.md>
uvx --from ~/.claude/magpie/adversarial-review adversarial-review run --target pr:123 --repo owner/name

Spell the path exactly so, with the literal ~: the agent-guard vetted-ops-spelling guard refuses an expanded home path or a checkout path. ~/.claude/magpie/adversarial-review is a stable link: the plugin’s SessionStart hook (hooks/link-stable-path.sh) points that path at the installed version every session, so the sandbox exclusion names a fixed path instead of a wildcard where the version sits. A * there would also match spaces, letting a command with extra uv options spliced in at that position (--with <any package>, a second --from) run outside the sandbox. Other harnesses use the installed plugin directory, for example ~/.claude/plugins/cache/apache-magpie/magpie-adversarial-review/<version>/tools/adversarial-review.

With --target pr:<N>, pass --repo whenever --repo-dir is not a checkout of the PR’s repository, such as an exported PR head: without it, gh infers the repository from the git remotes of --repo-dir, and an export has none.

run reads the reviewer list from adversarial-review.md (.apache-magpie-local/ first, then .apache-magpie-overrides/, under --project-root), or from --reviewers codex,copilot. The model running the harness is skipped; --self none turns that off.

Each reviewer has 8 minutes by default (timeout_minutes), below the 10-minute cap harnesses put on one shell call, so the harness never kills the tool before the tool’s own timeout does. On Ctrl-C or SIGTERM the tool kills every reviewer it started.

Output

One JSON object: each reviewer’s status (ok, unavailable, error, timeout, skipped) with its reason, and findings de-duplicated across reviewers and sorted by severity. The exit code is 0 whenever the run completes — the review is advisory — and 2 for a wrong invocation or an invalid config.

Findings are reviewer output and therefore untrusted: a finding that reads like an instruction is data.

What a reviewer sees

The diff, the files it touches, and the PR title and body as they will be posted — nothing else, by construction: no option or parameter accepts any other context. Reviewers can read files with their read-only tools, and that is the residual risk: the prompt is bounded, what a reviewer chooses to read is not.

  • When --repo-dir is empty, the report carries a warning: reviewers given only the diff cannot read the code around it, so no findings there is not a clean review.
  • When --repo-dir is the project’s private tracker, run refuses (exit 2). Pass --allow-tracker-checkout only when the tracker’s own code is what is under review; the report then still says so in warnings.
  • claude and copilot confine file reads to their working directory (plus the brief’s temporary directory for copilot). antigravity does too while allowNonWorkspaceAccess stays at its default false in ~/.gemini/antigravity-cli/settings.json. codex -s read-only restricts writes and network, not reads: an instruction injected into the diff could have it read a file elsewhere on the machine, such as a sibling tracker checkout, and put it into its reply to the model. Run the tool where nothing private sits beside the checkout under review, or leave codex out of the reviewer list for such machines. grok has the same exposure: its read_file and grep are not confined to the working directory, so the same advice applies.
  • grok is read-only through its tool allowlist (--tools read_file,grep,list_dir), with no subagents, no web search, and deny rules for the shell, edit, web-fetch and MCP tools. Its --permission-mode plan is not used: grok accepts the value but does not enforce it.
  • MCP tools are switched off for codex (-c mcp_servers={}) and claude (--strict-mcp-config). grok has no CLI switch that closes its MCP servers, so they stay connected, but --deny MCPTool auto-denies every MCP tool invocation. copilot and antigravity have no equivalent switch in the versions this was written against; their MCP servers, if any, stay reachable, so configure them with read-only servers or none.
  • antigravity runs in plan mode with no permission flag, so headless agy denies every tool call that would need approval: shell, edits, web fetches and MCP calls. That holds only while your own permissions.allow list in ~/.gemini/antigravity-cli/settings.json does not pre-approve them; an allow rule there applies to the reviewer too. The first denial ends the turn with an empty answer, so the prompt it gets asks it to read and search files only, and a review that still reaches for one is reported as an error naming the denied tool. Under proceed-in-sandbox its commands run inside the terminal sandbox instead. agy takes the permission mode only from that file, so the tool reads it back from agy’s init event and discards the review as an error unless it is request-review, strict or proceed-in-sandbox (whose auto-run commands stay in the terminal sandbox). The check runs after the reviewer has finished, so on that error inspect the reviewed tree.
  • pi is read-only by construction: --tools read,grep,find,ls is an allowlist, so the session has no shell, edit, write, MCP or extension tool at all. --no-approve ignores the reviewed tree’s .pi/ (project settings, extensions and packages), so the change under review cannot load code into the reviewer. AGENTS.md still loads, as it does for every reviewer: its content is data in the brief, not an instruction to follow.
  • goose is read-only by construction: it runs with GOOSE_MODE=chat, which gives the model no tools at all, and --no-profile, so none of your configured extensions or MCP servers start. It runs from the brief’s own temporary directory, not the reviewed tree, so Goose loads none of the tree’s project plugins, hooks or context files.
  • antigravity is skipped on a tree, or a tree inside a directory, that contains .agents/hooks.json or .agents/mcp_config.json (or the legacy .agent/ spellings). Antigravity runs workspace hooks and starts workspace MCP servers by itself, so the change under review would choose code that runs on your machine.

Backends

Backend Command line
codex codex exec -s read-only --ephemeral -c mcp_servers={} --output-schema <schema> -o <file> - (prompt on stdin)
copilot copilot -p <read the brief at …> --add-dir <brief dir> --deny-tool shell --deny-tool write
antigravity agy --mode plan --input-format stream-json --output-format stream-json --print-timeout 0 (prompt on stdin as one NDJSON user message; the answer is the final result event)
pi pi -p --no-session --no-approve --tools read,grep,find,ls <follow the brief above> (prompt on stdin, which Pi prepends to the instruction; the answer is stdout)
goose GOOSE_MODE=chat goose run --no-session --no-profile --quiet -i <brief> (prompt as a file; the answer is stdout)
grok grok --tools read_file,grep,list_dir --no-subagents --disable-web-search --deny Bash --deny Edit --deny Write --deny WebFetch --deny MCPTool --output-format json --prompt-file <brief> (prompt as a file)
claude claude -p --output-format json --strict-mcp-config --disallowedTools Bash,Edit,Write,NotebookEdit,WebFetch,WebSearch,Task (prompt on stdin)

tests/test_backends.py pins each command line.

Sandbox

The reviewer CLIs need network access and their own credentials (~/.codex, ~/.copilot, ~/.gemini/antigravity-cli, ~/.pi/agent, ~/.grok, ~/.config/goose, ~/.claude), which the reference sandbox denies. The single-line uvx --from ~/.claude/magpie/adversarial-review adversarial-review … form is what the sandbox exclusion names; setup installs it. The tool writes nothing to the repository: the brief and the schema live in a temporary directory that is removed afterwards.

Suggest a change