Review backends

Every review gate runs through a configurable review backend, and the point of configuring one is that it is a different model than the one that wrote the artifact. The verdict grammar, receipts, fix loop, and optional --deep / --validate passes are identical across all of them, so pick the one your team already runs.

Backend	Driver	Reviewer models	Shape
OpenAI Codex (codex)	codex CLI	GPT family	headless, cross-platform
GitHub Copilot (copilot)	copilot CLI	several model families via a Copilot subscription (org-policy managed)	headless, cross-platform
Cursor CLI (cursor)	cursor-agent CLI	several vendor families in one place - ask cursor-agent --list-models for the current ids	headless subprocess; reviews billed against your existing Cursor subscription
Claude Code CLI (claude)	claude CLI (claude -p)	Claude family	headless subprocess, read-only by construction (three read tools, no shell); same family as a Claude Code host
Host (host)	Host-native fresh-context subagent	Cross-family pin from the model-routing block in CLAUDE.md or AGENTS.md (never the session model)	Bare only - no subprocess; preferred from inside Cursor

Host (host) is a model-less selection sentinel, not a CLI. Review runs as a host-native fresh-context subagent pinned to a model family that did not write the diff (pins live in the model-routing block of whichever instruction file holds it, CLAUDE.md or AGENTS.md - never on the backend string; host:<model> is rejected). Every re-review is a new subagent. Fail-closed: without a cross-family pin, interactive runs ask; autonomous runs stop with NEEDS_HUMAN rather than silent same-family self-review. Setup on Cursor leads the backend menu with Host (Recommended). On Grok, Host is also offered, but Grok’s only native model family is grok-4.5 - native host review fails closed for a Grok writer unless the writer is non-Grok; cross-family review on Grok comes through bridge backends (codex / cursor / copilot). Muse Code is single-family too, so host fails closed there; use a CLI backend (codex, copilot, cursor or claude) in a Muse session started with --disable-sandbox, because the CLIs cannot write to their own home directories inside Muse’s sandbox. See Orchestration → Cursor host, Install → Grok and Install → Muse Code.

Claude Code CLI (claude) runs the Claude Code CLI headless with the prompt on standard input and exactly three tools (Read, Grep, Glob) with MCP servers excluded - there is no shell, because a pre-approved git diff would still accept flags that write files. The reviewed diff arrives as a file path under .flow/tmp/claude-review/, one file per reviewed range, so a re-review after a fix commit reads the new range while earlier evidence stays byte-identical. Sessions are resume-only: deep passes and validator passes continue the primary review by session id. The ladder steps on the CLI’s real model-unavailable signature (exit 0 with an error payload). On a Claude Code host this is a same-family second opinion, receipted rather than refused; independence is judged on the model family that wrote the diff, not on the host name.

Cursor CLI (cursor-agent) runs the same headless contract and verdict grammar as codex/copilot, with reviews billed against your Cursor subscription instead of a separate API key. It is resume-only (the first review persists Cursor’s session_id; re-reviews resume it) and folds reasoning effort into the model name (Cursor convention), so a spec is cursor:<model> with no :effort rung. From inside Cursor this path is circular - prefer host.

Set it once with /flow-next:setup, or override per run:

# persist the default (.flow/config.json)
flowctl config set review.backend codex
flowctl config set review.backend host          # preferred from inside Cursor

# override for a single run
/flow-next:impl-review fn-1 --review=codex|copilot|cursor|claude|host|none

# full spec form - backend:model:effort (host is bare only)
FLOW_REVIEW_BACKEND=codex:<model>:high

none is an explicit opt-out (skip review). The :model:effort suffix is optional and backend-specific. Codex and Copilot accept a :model:effort suffix (e.g. copilot:<model>:high); Claude Code CLI accepts claude:<model>:<effort> with the CLI’s own effort levels (low, medium, high, xhigh, max); Cursor CLI takes a model only (e.g. cursor:<model>) since effort is baked into the model name; host accepts no suffix at all. The chosen backend is recorded as the mode field on every review receipt.

Every backend gives a change the same review. The first round runs one reviewer for a small diff in one area that touches no persisted or shared state, concurrency, security or data layout, and three reviewers (correctness, contracts, integration) for anything larger, merged into one fix pass. The re-review after fixes is one reviewer. The merged round counts as one round against the cap. It works the same from any harness, so flow-next in Codex with the claude backend takes the same steps as flow-next in Claude Code with codex. Switching backend changes which model reviews, and the panel stays the same. See Three reviewers for risky diffs, one otherwise. How far the fix and re-review loop goes, attended or unattended, is in Implementation review.

A per-task review: (or per-spec default_review) override routes end-to-end - it wins over the project default and env/config, so a task set to review: cursor:... under a codex project default actually reviews with cursor. Implementation reviews also carry an always-on code-smell baseline (Fowler Refactoring - Feature Envy, Data Clumps, Primitive Obsession, …) across every backend.

Removed in 8.0.0: RepoPrompt

RepoPrompt support is gone: the rp backend, the Export Context skill and plan review’s --review=export mode. Reviews run on codex, host, claude, copilot or cursor.

A project that still names rp or export (in review.backend, FLOW_REVIEW_BACKEND, a spec’s or task’s review setting, or --review=) gets a one-line notice and continues with no reviewer configured, and flowctl config set refuses the value. Pick another reviewer:

flowctl config set review.backend codex        # or host, claude, copilot, cursor
flowctl spec set-backend fn-1 --review codex   # a spec that pinned rp

Re-run the Codex, OpenCode or Cursor installer to drop the Export Context skill from an existing install. Receipts already on disk with mode: "rp" still read.

review.backend stays. 7.1.0 said the setting would leave in 8.0.0 in favour of the model-routing block. It stays: the reviewer is chosen with review.backend, a spec’s or task’s review setting, or --review=, and nothing needs migrating.

Managed review execution

A compatible host can run a configured review through a registered provider account. Flow-Next still prepares the review, records its findings and writes the ordinary receipt. This changes where the reviewer runs, not the selected backend or the workflow’s review rules.

The host supplies a session-scoped execution endpoint, token and launcher choice inside the agent session. Users do not need to set these environment variables themselves. A required managed review needs a Flow-Next installation that advertises managed-execution support; an older installation must be upgraded before that review can run. The host checks compatibility before its structured work, unattended (flow --auto) and review entrypoints. Ordinary direct chats remain available. Installing Flow-Next alone keeps the existing standalone CLI execution path.

When managed execution is configured, invalid scope, an unavailable provider or a malformed response stops the review. Flow-Next does not retry through an unscoped local CLI. The host decides which registered accounts and transports it supports; the hook does not make every backend available in every host. The CLI installation requirements below describe standalone execution; a managed caller does not need a separate reviewer CLI on its PATH.

For host implementers, the execution-provider contract documents the local protocol and capability probe. Local profile files are not part of that contract. Cloud execution and cloud credential handling remain host-specific work.

Per-backend notes

Backend	Notes
codex	Codex CLI, cross-platform. Defaults to the strongest GPT tier the installed CLI accepts (the fallback ladder steps down automatically); tunable with FLOW_CODEX_MODEL and FLOW_CODEX_EFFORT.
copilot	GitHub Copilot CLI, cross-platform. Read-only: it runs with write and shell tools denied, the same read-only tools the claude reviewer gets. Native Windows works from 1.1.9 via stdin delivery (below). Offers several model families via a Copilot subscription (org-policy managed).
cursor	Cursor CLI (cursor-agent), cross-platform. Model names carry their reasoning tier. Circular from inside Cursor, where host is preferred.
claude	Claude Code CLI (claude), cross-platform; needs the CLI installed and authenticated. Read-only by construction, diff delivered by path, resume-only sessions. The cross-family pick from Codex, Cursor, Grok Build, Droid, OpenCode, or Muse Code; same-family (and receipted as such) on a Claude Code host, where codex or host keeps family independence.
host	Host-native fresh-context subagent. Bare only; cross-family pin from the routing block; fail-closed NEEDS_HUMAN without a pin.
none	Skip review entirely, cleanly and visibly.

Windows + Copilot (1.1.9+)

Native Windows works. run_copilot_exec delivers the prompt via stdin on Windows (subprocess.run(input=prompt, ...)), sidestepping the CreateProcessW 32,767-char argv cap that broke the -p path for spec-sized prompts in 1.1.8 and earlier. Session continuity is tracked with a touch marker, because stdin-mode --resume is resume-only unlike -p mode’s create-or-resume. Verified by a real-subprocess Windows CI smoke. Upstream tracking: github/copilot-cli#3398.

Precedence

Highest first: an explicit --review= argument → a per-task review: field or per-spec default_review → FLOW_REVIEW_BACKEND → .flow/config.json → backend env → the shipped default. A review skill with nothing configured anywhere hard-errors rather than silently skipping. Work and plan are the exception: they ask no setup question, run with review off, and say once in the handoff “no review backend set; run setup or set review.backend”. Per-spec overrides are written with flowctl spec set-backend, per-task with flowctl task set-backend. A single task can pin its own reviewer and the override routes end-to-end, so a task set to review: cursor:… under a codex project default really does review with cursor.

flowctl config set review.maxIterations 6      # review-round cap (env MAX_REVIEW_ITERATIONS wins)
flowctl config set review.fanoutExecution sequential   # first-round reviewers one at a time (local models, rate limits)

Sequential fan-out is described in Implementation review.

The model-routing tiers never touch this configuration. The reviewer tier is advice about which family to pick; review.backend is the machinery that runs it.

What the reviewer actually receives (3.16.0)

The reviewer runs in your checkout with a shell, so it is handed identities, not content: the reviewed base..head range, the exact list of changed paths (git diff --numstat --no-renames -z, so nothing is elided, renames appear as real paths, and non-ASCII filenames survive), the repo-relative spec and task paths, and a few context hints. It reads the diff and the specs itself, at whatever depth each part warrants.

Earlier releases embedded the diff body in the prompt under a 50 KB cap, which meant a large change was reviewed against a truncated sample. Nothing is trimmed to fit now, and if a git read behind the evidence fails, the review stops with the underlying error before a review round is spent, rather than returning a verdict formed from nothing.

Re-reviews continue the reviewer’s own session, so when it checks whether your fixes landed it compares against findings it remembers making rather than a re-rendered list. When a session cannot be resumed, the prior findings travel in the prompt as before. On codex, a resumed re-review, validator pass, or deep pass is re-pinned to the model the prior receipt records, so it runs the model the review started with rather than the one in your Codex config.

Expect better-informed reviews rather than cheaper ones. A fetching reviewer spends turns on tool calls, so it is slower on a large diff and its measured token use went up, not down. The dispatch bound is 1800 seconds, overridable with FLOW_REVIEW_EXEC_TIMEOUT.

Turning it off

review.backend none is an explicit opt-out, not a degraded mode. Every backend-driven review exits cleanly and the skip is recorded.

Under flow --auto the same rules hold. The unattended run resolves its backend from --review=<backend> (passed through unchanged to the plan, plan-review, and work dispatches; qa and make-pr take no review flag) or flowctl review-backend, records a none skip as skipped(config: review=none) on the stage line, and never lowers the gate or fabricates a verdict. A host backend with no cross-family pin stops the run with NEEDS_HUMAN, and a review that returns NOT_RETRYABLE: artifact unchanged since last verdict ends the run with NEEDS_HUMAN as well; both are human recoveries, never retries.