Skip to content

About

Local Claude/Codex PR review loop using existing CLI subscriptions instead of model API keys

Topics

Resources

Stars

12 stars

Watchers

0 watching

Forks

Repository files navigation

coding-review-agent-loop

coding-review-agent-loop is a local command-line orchestrator for GitHub code review. One coding agent creates or updates a pull request, one or more other agents review it, and the loop sends blocking feedback back to the coder until the reviewers approve or the run reaches a clear stopping condition.

GitHub issue, task, or PR
          |
          v
      coding agent  <-------+
          |                 |
          v                 |
     pull request           |
          |                 |
          v                 |
      reviewers ---- feedback
          |
          v
       approved  ->  optional CI wait and merge

The loop runs on your machine and uses the local claude, codex, agy, gemini, and gh programs you have already authenticated. It does not require you to put model API keys into this project. You only need the agent CLIs used for the roles you select; you do not need to install every supported backend.

The project is alpha software. It can let coding agents edit repositories, run commands, push branches, and write to GitHub. Start with a repository where you can inspect and revert the results.

Why Use It?

  • Replace the manual cycle of copying reviewer feedback between agent sessions.
  • Assign coding and review to different models or providers.
  • Start from a GitHub issue, an existing pull request, or a free-form task.
  • Review an implementation plan before allowing code changes.
  • Require multiple independent reviewers to approve the same PR head.
  • Resume interrupted work from durable metadata recorded on GitHub.
  • Optionally run local tests, wait for CI, and merge after approval.

The default workflow is deliberately conservative: Claude is the coder, Codex is the reviewer, the review limit is 10 rounds, and automatic merge is off.

Risk-based mode and transition matrices

Fresh stateful or multi-mode plans may carry a bounded generation-1 risk matrix. Each applicable row has a matrix-local ID, entry path or mode, initial state, event, expected outcome, forbidden side effects, proposed test location, and one execution owner. Simple local work can instead use a non-empty, proportionate not-applicable rationale; important exclusions remain explicit. Rows are planning proposals until implementation evidence maps them to actual tests.

The structured matrix payload is the authority, not a copied markdown table. Round metadata and the existing bounded sidecar persist its canonical identity, so a renderer change does not invalidate an otherwise authentic plan. A corrupt or unfittable matrix closes only the matrix channel and reports a diagnostic; it does not withdraw a separately valid plan hash and subject. Historical plans without a matrix remain resumable without invented rows.

Sidecar comments that precede a large plan or review carry machine-readable overflow data and are not independent agent responses. Each shows a short visible label such as Agent-loop plan attachment 2/5 (machine-readable overflow: ...); keep them with the comment that follows. Older unlabeled sidecars remain valid.

Agent-loop also posts tool-owned protocol records whose data lives in a hidden marker. Each one opens with a short visible label naming the record and its role, so it is recognizable instead of rendering as "No description provided.". The record types are:

  • the managed-CI issue authorization record, and its fresh re-authorization and head-continuity forms;
  • the managed-CI exact-head intent record;
  • the managed-CI unprotected-override audit and resume-provenance audit;
  • the managed-CI qualified-head record;
  • the issue-to-PR handoff and the PR expected-closing contract;
  • the plan-validation diagnostic record.

These comments are machine-readable and must be kept: resume, recovery, and audit read them back. Older marker-only copies, which GitHub renders as "No description provided.", remain valid and still parse.

Requirements

  • Python 3.12 or newer.
  • Git and GitHub CLI with gh auth status succeeding.
  • Repository access sufficient for the requested issue, branch, PR, and comment operations.
  • A local CLI for the coder and each reviewer you select: Claude Code, OpenAI Codex CLI, Antigravity CLI (agy), or the legacy Gemini CLI backend.

Each agent CLI has its own authentication, quota, terms, and model availability. Confirm those with the provider; this tool does not combine or replace provider subscriptions.

Managed CI in this repository

This repository's .github/workflows/ci.yml installs the managed-CI v2 contract with the literal AGENT_LOOP_MANAGED_CI_V2, AGENT_LOOP_MANAGED_CI_UNLABELED_RECOVERY_V1, and AGENT_LOOP_MANAGED_CI_VISIBLE_INTENT_V1 declarations. Pull requests use exactly four activities: opened, synchronize, reopened, and unlabeled. Only a trusted, same-repository draft on the reserved agent-loop/managed-* branch can suppress intermediate CI: opening is recognized before the label write, while later synchronization and reopening require agent-loop-managed. Unlabeled events always run the ordinary Python 3.12 suite, and forks, malformed payloads, trust mismatches, and all ordinary PRs fail open to that suite. Pushes to main and all-empty manual dispatches also run the complete suite.

A successful explicit --managed-ci manual qualification keeps agent-loop-managed on the PR it has just made ready. Removing the label would fire unlabeled and re-run the full suite on the head that exact-head CI has just qualified. A ready PR is never suppressed, so the retained label has no effect there. Removing it by hand still returns the PR to ordinary CI. If publication fails at any step, agent-loop releases the label, unless a readable label event from someone else owns it; that label is left and reported. Any later agent-loop invocation on the PR removes a retained label from an open ready PR before any other managed-CI work, then continues exactly as for a ready/unlabeled PR. If a qualified PR is converted back to draft and pushed by hand, the label suppresses ordinary CI for that push. Remove the label to restore it.

While a managed draft waits for review, coder and format-repair turns cannot dispatch ordinary CI themselves. Their prompts say that a skipped pull_request check is expected. A per-turn gh guard refuses gh workflow run, gh run rerun, and gh api dispatch or rerun POSTs. A post-turn audit reports any bypass as a non-authoritative diagnostic. To get early CI as an operator, run gh workflow run ci.yml --ref <branch> from your own shell. agent-loop reports that run as an excluded ad hoc diagnostic and never as final qualification. See Coder turns cannot dispatch CI before approval.

After the workflow change is merged, the sole-maintainer rollout is ordered:

  1. Set the repository Actions variable to the trusted actor: gh variable set AGENT_LOOP_MANAGED_ACTOR --repo wwind123/coding-review-agent-loop --body wwind123.

  2. Authenticate gh as wwind123, then run the read-only preflight: agent-loop managed-ci preflight --repo wwind123/coding-review-agent-loop --base main --trusted-actor wwind123.

  3. While main remains unprotected, pass --managed-ci-trusted-actor wwind123 --allow-unprotected-managed-ci on every applicable issue-created invocation. The waiver is explicit per run; it does not change defaults for other repositories, enable arbitrary existing-PR adoption, or replace a head-guarded merge. For example:

    agent-loop issue <issue-number> --repo wwind123/coding-review-agent-loop \
      --plan-first --implement-after-approval --auto-merge --managed-ci \
      --managed-ci-trusted-actor wwind123 --allow-unprotected-managed-ci

For an approved head, the base-branch workflow validates the live actor, repository, PR tuple, workflow revision, and one fresh generation-scoped handoff record before exposing expected_head_sha. Freshness is measured on the base runner: created_at must be at most 15 minutes old and no more than 5 minutes ahead of the runner clock. A no-status retry may advance only from the recorded terminal attempt to the immediate next attempt of that same run. A separate set of six repository-selected shard jobs checks out that exact SHA, installs the editable development dependencies, and runs the full python -m pytest suite once between them; an aggregate job named Test validated exact head succeeds only if every shard passed and the shard manifests prove exactly-once coverage. The ordinary Python 3.12 full suite check is sharded the same way. Both are provided by reusable workflow_call workflows in this repository (.github/workflows/managed-ci.yml and managed-ci-ordinary.yml, called by a thin ci.yml), so other projects can reuse the same validator and exact-head gate; the shard plugin and verifier live in ci/managed/ and are checked out from the reusable workflow's own revision. Managed CI can also target allow-listed integration branches via the AGENT_LOOP_TRUSTED_BASES repository variable (exact names or prefix/*); see trusted integration bases for the adoption snippet, trust model and limitation. Shard balance comes from tests/.test_durations. A test without an entry is weighted at the mean of the known durations, so new tests are always scheduled. Feature PRs do not refresh tests/.test_durations: a full refresh, with PYTHONPATH=ci/managed${PYTHONPATH:+:$PYTHONPATH} CI_SHARD_STORE_DURATIONS=tests/.test_durations CI_SHARD_STORE_DURATIONS_MODE=replace python -m pytest -p ci_shard_plugin -n auto (the plugin is not loaded automatically), belongs in a dedicated maintenance PR (see #1551). Timing drift alone must not block CI or review: missing timings affect balance only, while exactly-once coverage and real test failures remain blocking. Optional maintenance can add only missing entries with PYTHONPATH=ci/managed${PYTHONPATH:+:$PYTHONPATH} CI_SHARD_STORE_DURATIONS=tests/.test_durations CI_SHARD_STORE_DURATIONS_MODE=add-missing python -m pytest -p ci_shard_plugin -n auto, which leaves every existing entry unchanged. The always-evaluated publisher writes final-ci/exact-head only for that validated target, with the nonce, run ID, attempt, and Actions URL correlated in the status. Authorization failures before target validation write no status; checkout or test failures publish a terminal non-success result. Keep queued work on ordinary CI until this post-merge live qualification is complete.

Adopters whose tests need services, extra setup or a routed matrix can use the split layout instead (a read-only validate entry point, caller-owned test jobs that end with the managed-ci-attest action, and an attested publish entry point); see split layout for the SHA-pinned template, the security contract and the routed-matrix migration notes. The single-job workflows stay supported.

Process-tree containment

Agent subprocesses and repository test gates use a shared per-user containment policy by default. On Linux with systemd 253+ and delegated cgroup v2, agent-loop creates a foreground child scope inside agent-loop.slice and applies aggregate plus role-specific MemoryHigh, MemoryMax, MemorySwapMax, and TasksMax limits. The aggregate protects host headroom across independent agent-loop processes; a child scope cannot exceed it. The portable fallback uses process-group TERM/KILL for deterministic termination but provides no memory ceiling. --containment-mode required fails closed when cgroup preflight is unavailable, while auto reports the fallback.

Inspect the resolved policy and capabilities with agent-loop containment-preflight --containment-mode auto. The systemd launcher is the synchronous foreground form systemd-run --user --scope --quiet; it deliberately does not use --wait, --service, or --pipe. A target-start shim report is authoritative when distinguishing launcher failures from target exit statuses. The shim also holds a supervisor pipe whose only write end lives in the orchestrator: if the orchestrator dies (for example systemctl --user stop of the loop's own scope), the shim SIGKILLs every process in the target scope, so an orphaned coder cannot go on to push or open a PR. A shim that cannot confirm a live supervisor refuses to start the target. The process-group fallback has no shim and no such guarantee. Optional cgroup telemetry (peak memory, PSI, and swap counters) is capability-aware: missing files are reported as not collected rather than treated as lost evidence. OOM, hard memory/swap failures, and task-limit failures are resource-exhausted; MemoryHigh/PSI pressure is diagnostic only.

The same-command test wrapper has a per-invocation lane lock. A duplicate is rejected before spawn until the earlier managed attempt exits or is explicitly terminated. Standalone commands not run through the wrapper cannot be deduplicated from free-form agent logs, but their complete agent tree remains resource-bounded when launched by agent-loop. The aggregate is per user manager, not cross-user host isolation.

Install

Clone the repository and install it into a virtual environment:

If python3 --version reports an interpreter older than 3.12, name a newer one explicitly in the venv step, for example python3.12 -m venv .venv.

gh repo clone wwind123/coding-review-agent-loop
cd coding-review-agent-loop
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e .
agent-loop --help

Check the CLIs for your chosen roles before the first run:

gh auth status
claude --version
codex --version

Substitute agy --version or gemini --version when using those backends.

Running where GitHub GraphQL is refused

Some hosts, notably Claude Code cloud sessions, block every GitHub GraphQL request at an egress proxy while allowing repository-scoped REST (repos/{owner}/{repo}/...). Much of gh's porcelain (gh issue view --json, gh pr view --json, gh pr create, gh repo clone, …) is GraphQL-backed, so without the steps below agent-loop and its coder agents fail on their first GitHub read.

1. Check whether you need this.

gh api graphql -f query='{viewer{login}}'

If this prints your login, GraphQL works and you can skip this section. If it fails with GitHub GraphQL is not available, continue. A supplied personal token does not help: such proxies replace the Authorization header.

2. Install agent-loop with Python 3.12 or newer. The Install steps start with gh repo clone, which is itself GraphQL-backed and fails before the shim exists, so clone over plain HTTPS instead:

git clone https://github.com/wwind123/coding-review-agent-loop.git
cd coding-review-agent-loop
python3.12 -m venv .venv
. .venv/bin/activate
python -m pip install -e .

The package includes a second command, agent-loop-gh, in the same bin/ directory as agent-loop. Keep the virtual environment activated (or invoke .venv/bin/agent-loop explicitly) in every later step and shell to find agent-loop, and separately keep the step-3 export PATH in every shell regardless: it is what puts the gh shim ahead of the real gh on PATH, and agent-loop itself never adds it.

3. Put the shim ahead of the real gh. agent-loop-gh is a gh-compatible shim that answers exactly the porcelain forms agent-loop and its coder prompts use over REST, printing the same --json shape gh would. Every other command, including every gh api call, passes through to the real gh unchanged. It must be found as gh on PATH, not only passed with --gh-cmd, because the coder and reviewer agents run gh themselves:

.venv/bin/agent-loop-gh shim-install ~/.local/agent-loop-gh/bin
export PATH="$HOME/.local/agent-loop-gh/bin:$PATH"

shim-install creates a gh symlink to the installed agent-loop-gh.

4. Verify.

command -v gh                                   # ~/.local/agent-loop-gh/bin/gh
gh issue view 1 --repo OWNER/REPO --json title  # answered over REST

5. Authenticate the agent CLIs as usual. On a headless host, codex login --device-auth signs Codex in to a ChatGPT plan with a link and code opened on another device; CODEX_API_KEY instead bills the API account, and takes precedence over the sign-in while it is set.

6. Give each agent only the access its role needs. Where --dangerous-agent-permissions is unwanted or refused (a Claude Code cloud session's permission classifier, for example, blocks spawning agents with sandboxes disabled), use --agent-permissions sandboxed. agent-loop then builds CLI-enforced grants for every invocation from the provider and the role, so no --claude-arg/--codex-arg is needed (and none is accepted):

agent-loop issue 123 --repo OWNER/REPO --plan-first \
  --plan-execution-mode implement-one-shot \
  --agent-permissions sandboxed \
  --coder claude --reviewer codex --reviewer claude \
  --repair-backend claude --repair-model MODEL \
  --semantic-followup-backend claude \
  --test-command "python -m pytest tests/ -q"

Instead of --semantic-followup-backend claude you may pass --no-semantic-followup-dedupe. Both helper backends must be overridden because their defaults are rejected in this mode: the default repair backend (antigravity) and the default semantic-followup backend (antigravity) have no role grant. Codex or Claude repair needs an explicit --repair-model.

What each role gets:

Role Claude Codex
Coder (implementation, PR fixes, completion recovery) acceptEdits plus path-scoped Write/Edit rules for its assigned checkout (as given and as resolved); user-only setting sources; Bash(git *); the gh subcommands coder prompts use (gh pr create/view/edit/comment/checks/diff, gh issue view/comment, gh run view, gh label create/list, gh repo view); the read-only inspector; and exactly one test rule, the resolved agent-loop run-tests … -- <test command> invocation shown in the prompt rejected (see below)
Every other role (reviewer, planner, analyzer, summary, repair, semantic dedupe, and any unknown or missing role) --restricted with an explicit --tools set, dontAsk, no permission prompts, an empty strict MCP config, writes only to its response file, and one shell grant: agent-loop inspect --sandbox read-only with approvals set to never; the Codex CLI writes its final message to the validated response file

Requirements and limitations of sandboxed mode:

  • Install agent-loop outside the agent checkouts (for example with uv tool install, or a separate clone's virtual environment). The inspector grant is pinned to the orchestrator's interpreter in Python isolated mode (-I), and its installed package files are fingerprinted at startup and re-verified before every read-only Claude turn; startup fails fast when the interpreter or package lies inside a checkout.
  • git and gh found first on PATH must also live outside every checkout; they are pinned by absolute path for the run, and checkout directories must not precede them on PATH. The inspector runs only those pinned binaries, so a git or gh planted in a checkout later is never executed. Upgrading git or gh during a run blocks read-only turns until the run is restarted. Without gh on PATH, gh inspection is unavailable. When the pinned gh is the step-3 shim, the inspector's gh subcommands work only if the real gh sits in the same directory as the pinned git, because the shim finds the real gh on the inspector's constructed PATH.
  • TMPDIR must resolve outside every checkout, including the repository checkout you run agent-loop from. Responses go to a private per-turn directory under ${TMPDIR:-/tmp}/coding-review-agent-loop/responses/ (the shared ancestors are mode 0300, so agents cannot list peer responses), whose agent-loop-created components must be real directories owned by you that are not group- or world-writable (no symlinks). agent-loop creates its scratch directories with mode 700 whatever your umask; a component left group-writable by an older release is refused, and the refusal lists every such component with a single chmod go-w command that fixes them all. The directory and every checkout, including one not yet created, are re-verified before each spawn, so checkouts and their parent directories must not be moved, replaced, or redirected during a run.
  • Pass-through agent arguments are rejected (--claude-arg, --codex-arg, --gemini-arg, --antigravity-arg); use the dedicated model and effort options instead.
  • A committing Codex coder is rejected. Codex's sandbox keeps the repository's .git read-only even with --add-dir, so git commit fails. Use --coder claude (or --implementation-coder claude); a Codex planner in a plan-only run is allowed.
  • Codex non-coders have no network, because the read-only sandbox disables it; they rely on the issue and PR context in the prompt.
  • Gemini and Antigravity cannot be selected on any path (coder, reviewer, analyzer, repair, or semantic dedupe), so a sandboxed review board has at most the Claude and Codex reviewers. That is a trade of review depth for containment: to keep an Antigravity reviewer, run with default or dangerous permissions. Antigravity has no CLI-enforced read-only grant. agy --sandbox restricts only its terminal, so its file-writing tool can still write the checkout and a bare git there runs the checkout's .git/config. Its allow rules live only in the shared user settings file.
  • The inspector refuses checkouts with unusual git config. agent-loop inspect runs only the pinned git and gh with a closed environment allowlist and a PATH built from their directories (inherited GIT_* variables, including every trace variable, and GH_DEBUG never apply), ignores system and global git config, and refuses to run when the checkout's local, worktree, or included config has a key outside its allowlist, for example a filter (including LFS), signing, include, trace-target, or alias setting. The refusal names the key and the file it came from; the reviewer can still read files directly. See the inspector reference.
  • Coders run tests as the same OS user. The mode stops accidental and prompt-driven checkout mutation by non-coders and detects or refuses between-turn tampering with the inspector code, the pinned git and gh binaries, git configuration, and the response directory. It is not OS-level isolation from a deliberately hostile coder.

--dangerous-agent-permissions is unchanged and still turns the agents' sandboxes off entirely; --agent-permissions dangerous is its alias.

These settings do not persist. The venv activation and export PATH lines last only for the current shell. Add both to your shell profile or the host's setup script, or repeat both in each new shell; invoking .venv/bin/agent-loop explicitly only substitutes for venv activation, not for the step-3 export PATH, which is what keeps the gh shim ahead of the real gh and must be re-run (or re-sourced) in every new shell regardless. The symlink points into the virtual environment, so rerun shim-install after recreating .venv. On ephemeral hosts such as cloud containers, repeat every step, including the Codex sign-in, in each new session.

Transport selection. AGENT_LOOP_GH_TRANSPORT chooses how the shim talks to GitHub: auto (default) probes GraphQL once and uses REST only when the refusal is identified (the result is cached for 15 minutes), rest always emulates, and graphql always passes through. On a host where GraphQL works, auto passes through, so the shim can stay installed. Set AGENT_LOOP_REAL_GH if the real gh is not on PATH.

Behavior in REST mode. An unsupported flag or --json field fails with a pointer to gh api repos/... rather than being ignored; issue search is evaluated locally because search/issues is not repository-scoped; and PR commit provenance fails closed above GitHub REST's 250-commit listing limit.

Managed CI in such sessions. The same hosts also refuse two reads that --managed-ci uses before it creates a PR. Both answers are 403s:

  • The AGENT_LOOP_MANAGED_ACTOR Actions variable is refused by the proxy. When gh reports a strict HTTP 403 for that read, --managed-ci-trusted-actor stands in for the variable. The run logs that the actor is asserted and unverified locally, and managed-ci preflight prints it as asserted. This fails safe because the workflow still enforces the real vars.AGENT_LOOP_MANAGED_ACTOR server-side. A mismatch leaves ordinary PR CI unsuppressed, and managed dispatches fail validation. A variable that can be read and differs still refuses, as does a 404 or any other error.
  • Classic branch protection is refused by the session's GitHub App (it lacks administration read). The effective rules and rulesets are still readable. When they show no strict final-ci/exact-head enforcement, protection is classified as unreadable, which is distinct from voluntary. It can be waived only with --allow-unreadable-protection, which requires --allow-unprotected-managed-ci. The waiver has the same merge-safety meaning as voluntary protection: GitHub is not shown to enforce the exact-head gate. After such a 403, a ruleset counts as strict only when its bypass actors are visible and empty. Malformed rule data, or a rules read that is not gh's strict 404/422, stays indeterminate, and no waiver applies.

agent-loop managed-ci preflight exits 10 (known not ready) for unreadable protection and names both flags. A cloud-session invocation therefore looks like:

agent-loop issue <issue-number> --repo OWNER/REPO --plan-first \
  --implement-after-approval --managed-ci --managed-ci-trusted-actor <login> \
  --allow-unprotected-managed-ci --allow-unreadable-protection

Quick Start

Review an existing PR

This is the smallest useful first run. The reviewers inspect the current PR; if they find blockers, the coder updates that same PR and review continues.

agent-loop pr 456 \
  --repo OWNER/REPO \
  --coder claude \
  --reviewer codex

Implement a GitHub issue

Issue mode gives the issue title, body, and comments to the coder, validates the resulting PR, and then enters the same review loop.

agent-loop issue 123 \
  --repo OWNER/REPO \
  --coder claude \
  --reviewer codex

Without --plan-first, issue mode asks the coder to implement immediately, unless planning already decided the issue. If the issue carries a planning round that approved the plan as a whole, a plan-approval announcement, a recorded execution decision, or an approved-plan implementation handoff, plain issue mode refuses before invoking any agent and names the resume command, agent-loop issue <n> --plan-first. A single reviewer's approval in a split or abandoned planning round does not count. Planning records whose approval state cannot be determined, including unreadable records, still refuse, and the error says so instead of claiming the plan was approved. Only records authored by the authenticated agent-loop GitHub actor count, read from the issue's complete comment history.

Plan-first implementation carries the approved plan through a dedicated, lossless PR-bound context. The PR handoff binds reviewers and coder follow-ups to the recorded plan hash and subject, independently of truncated issue comments or compact PR history. Issue/PR resume validates that handoff (and any staged parent/child topology) before invoking an agent; an ordinary PR with no planning provenance continues through the normal no-plan path.

Signed human instructions are rendered as Requirement hr-<digest> and use the same content-derived ID in acknowledgements, repair, round metadata, and resume. Insertion or chronological reordering cannot change an existing instruction's ID, while an edited body receives a new ID. Historical positional acknowledgements require a fresh acknowledgement against the currently surfaced stable IDs rather than being reinterpreted by current ordering. Original issue requirements, later valid human instructions, and safety constraints outrank an approved plan; a defective plan must be raised as a scope/plan decision, not silently replaced by review prose.

Review a plan, then implement it

Use plan-first mode for work whose design should be challenged before files are changed. --plan-first alone stops after plan approval. Add --implement-after-approval to continue into implementation and PR review. A re-approved plan may supersede a completed execution decision after the loop verifies all historical children and PRs are terminal and the managed branch is absent. If a merged PR left its managed branch behind, verify the work is finished and delete that branch manually before retrying. Open or unreadable work still blocks; historical records remain intact. See execution strategy guidance.

agent-loop issue 123 \
  --repo OWNER/REPO \
  --coder codex \
  --reviewer claude \
  --plan-first \
  --implement-after-approval

If you edit the issue title or body while its plan is still under review, the next plan-first run starts a fresh plan instead of patching the old one. It logs both issue digests and posts a planning-scope boundary record. The fresh plan starts at the next round number, and the --max-rounds budget restarts there. The old plan stays in the issue history but no longer binds the new plan. A comment alone, including a signed requirement, is not an issue edit. For a typo-level edit, pass --plan-resume-keep-on-issue-edit to keep the existing plan for that invocation. See edited issues during planning.

An approved plan is never reopened by an edit. To replace an approved plan that has not been handed off into a PR or child stages, rerun with --reopen-approved-plan (for example after narrowing the issue). The run posts a boundary record naming the superseded plan hash and starts a fresh plan at the next round; the old approval does not carry over. A handed-off plan is refused and nothing is posted. The flag applies to that invocation only and is never carried into child planning or recovery commands. See reopening an approved plan.

Implement a task without an issue

agent-loop task "Add a health-check endpoint" \
  --repo OWNER/REPO \
  --coder codex \
  --reviewer claude

Choose a Workflow

Command Use it when
agent-loop issue A GitHub issue defines the work to implement or plan.
agent-loop pr The implementation PR already exists.
agent-loop task You have a direct task and do not need an issue first.
agent-loop discuss You want agents to evaluate an open question without writing code.
agent-loop managed-pr Code is pushed but no PR exists, and the repository uses managed exact-head CI.
agent-loop managed-ci preflight You want a read-only readiness report for managed CI.
agent-loop issue --triage You want an advisory route recommendation (discuss-first, plan-first or direct) posted before the run's first agent turn; the run still takes the route you selected. See advisory issue triage.
agent-loop history export You want a read-only per-issue outcome table (route taken, plan/PR rounds, step-backs, human-decision stops, plan finding provenance, baseline forms and sweep reviews, merge state, infrastructure failures, run-start snapshot). See outcome history export.
agent-loop triage backtest You want an offline, report-only measurement of a triage provider command against outcome labels from history export files (per-route precision/recall, majority baseline, hybrid-routing threshold finding). See offline triage backtest.

Run agent-loop <command> --help for the complete options for one workflow. The full CLI guide covers lifecycle and resume behavior in detail.

If agent-loop pr <number> refuses to resume because a coder follow-up pushed a commit and was then rejected (or the PR head otherwise advanced without a recorded handoff), rerun with --review-unrecorded-head. It runs an ordinary review round of the current head with the recorded active items carried, never force-pushes, and never posts a record in the coder's name. See rejected coder follow-ups.

For an issue-created managed-CI PR whose original authorization comment is missing, recovery is deliberately explicit. On a voluntary or plan-limited base, use --managed-ci-fresh with --managed-ci and the unprotected waiver; PR mode must also provide --managed-ci-issue <issue-number>. This creates a new operator grant after validating the live PR tuple, fetching the issue and canonical plan scope, and confirming a server-observed issue-to-PR association. It reuses any valid exact-head authorization and does not adopt arbitrary existing PRs. Earlier actor-owned authorization records that differ only in their recorded protection, or that GitHub cannot chain to the live head, are retired by one superseding record rather than refused; any other conflicting record still fails closed. Ordinary resumes prevent that accumulation: each continuity record they publish also retires the same actor's otherwise compatible, same-protection records that GitHub cannot chain to the new head (a protection disagreement still needs the fresh grant), so an interrupted run does not leave a stranded grant behind for a later --managed-ci-fresh to clear. If structured response validation rejected the implementation before accepting its PR number, strict protection instead uses ordinary same-PR issue/PR discovery and resume; the fresh unprotected grant is not available or required for a strict base. If a strict draft was left unlabeled, that resume requires the authenticated strict PR tuple and an actor-owned historical agent-loop-managed label event, then reapplies the label without creating a waiver record.

How the Review Loop Behaves

  1. The coder implements the issue or updates the existing PR.
  2. Every configured reviewer reviews the same PR head.
  3. Blocking findings return to the coder as an explicit work ledger.
  4. The updated head is reviewed again.
  5. The run stops on unanimous approval, a terminal blocker, a clarification request, unavailable required input, or the round limit.

Repeat --reviewer to require multiple approvals. Use --review-parallel when the reviewers have distinct workdirs and may run concurrently. Same-round review comments are posted only after every reviewer in the round has returned, so no reviewer can read a peer's findings mid-turn. A reviewer that must be retried, or a round interrupted mid-publication, is resumed from a private local spool rather than re-run against peers' posted reviews:

PR and issue-plan review accept named reviewer seats: --reviewer-seat ID=BACKEND, --seat-model ID=MODEL, --seat-effort ID=EFFORT, and --seat-dir ID=PATH. A named-only board has no implicit Codex reviewer; an explicit --reviewer adds one legacy default seat. Use --primary-reviewer-seat ID with PR primary-then-panel scheduling, or --primary-plan-reviewer-seat ID with plan primary-then-panel scheduling, to select a named primary. Named seats work with pr, task, managed-pr, plain issue PR review, and issue --plan-first. discuss rejects them. Each seat has its own checkout, response file, logs, signature, approval, and saved plan and PR bindings. The PR board is chosen per invocation: a plan approved by one board can be reviewed as a PR by another. The plan stays verified against its own board, and a differing PR board gets one board-change audit record on the PR. --min-reviewers N and --min-distinct-providers N set an optional floor for the effective board (providers count by backend). A board below the floor is refused before any agent runs unless a signed reviewer-board amendment authorized it. Mid-PR board changes (an added, removed or swapped reviewer, or a seat's model, effort or backend) are recorded as one board-change record on the PR and need no signature; added and rebound reviewers must approve the current head, and removed reviewers' open findings stay open on the remaining board. See Changing the PR reviewer board mid-run. Plan review boards change the same way: a differing plan board is one plan board-change record on the issue, and a completely approved plan is never reopened by a different board. See Changing the plan reviewer board mid-run. Antigravity fallback stays inside one seat; seats share account quota and serialize turns through a host settings lock whose wait follows the holder's turn bound; an expired wait is a transient, seat-local failure. Existing --reviewer agy with --antigravity-models remains one reviewer with an ordered fallback chain. When a legacy Codex, Claude, or Gemini reviewer shares a backend with a named seat, select its model explicitly so preflight can check for overlap. Backend model and effort flags apply only to an active coder or legacy reviewer.

agent-loop pr 456 \
  --repo OWNER/REPO \
  --coder codex \
  --reviewer claude \
  --reviewer agy \
  --review-parallel

Agent-loop creates a separate per-run git worktree for each active agent unless you provide workdirs (see "Default checkouts" in docs/local_agent_loop.md). GitHub comments carry durable round and handoff metadata, so a later run can reconstruct the active review state. When the PR number is known, resume with agent-loop pr <number> instead of starting issue implementation again.

Agent-loop's own Git commands in agent checkouts use a closed environment, a pinned executable, settings that disable hooks, fsmonitor, external diff, submodule traversal, pagers, credentials, and trace targets, and command-time child-execution denial. Linux verifies a preload/seccomp guard; macOS verifies a preload/Seatbelt guard; Windows assigns a suspended Git process to a one-process Job Object before resume. A host without a verified boundary fails before its first checkout Git probe. Checkout settings that require external filters or helpers may make the operation fail; the planted program does not run. Host prerequisites: on Linux, agent-loop needs a root-owned Git at /usr/bin/git, /bin/git, or /usr/local/bin/git; a root-owned C compiler at /usr/bin/cc or /usr/bin/clang; the Linux UAPI headers (linux-libc-dev on Debian/Ubuntu, kernel-headers on Fedora/RHEL); and an x86_64 or aarch64 CPU. On macOS, agent-loop tries /opt/homebrew/bin/git, /usr/local/bin/git, then /usr/bin/git, and pins the first one in a root-owned, preloadable install. Apple Silicon Homebrew is owned by the installing user, so it is skipped. Without these, checkout Git operations fail with Unsupported Git confinement: ... before any checkout Git runs. On POSIX hosts the pinned Git binary and every component of its installation path must be root-owned. Private HTTPS authentication uses the same rule for the GitHub CLI and SSH client. Guard source and the Windows launcher are checked against identities held in the loaded controller before use; the C compiler reads verified source bytes from stdin, and Windows runs the verified launcher bytes directly.

Base and PR commits are fetched into a private transport repository from the exact GitHub HTTPS or SSH origin selected by --repo, using trusted GitHub CLI authentication when private HTTPS needs it. Agent-loop streams the reachable pack into the checkout, verifies the commit, and updates its tracking ref by compare-and-swap under a checkout or store lock before changing HEAD. A checkout origin with a different host, URL rewrite, or untrusted local path is refused before transport. For an explicitly trusted offline repository, pass --trusted-local-origin /absolute/path/to/origin; the checkout origin must match that resolved path exactly. New checkouts use HTTPS by default. Pass --trusted-origin-protocol ssh when the operator has configured SSH authentication; agent-loop creates the exact git@host:owner/repo.git origin before its private fetch (or an ssh:// URL when the trusted host includes a port). This option cannot be combined with --trusted-local-origin.

The pinned SSH client runs with -F /dev/null, so ~/.ssh/config is never evaluated by ssh itself, and ssh -G is never used. On Linux and macOS, agent-loop instead reads a small subset of ~/.ssh/config for the literal origin host, without running anything, and passes it as explicit options:

  • IdentityFile (each entry, as -i), HostName, IdentitiesOnly, a single UserKnownHostsFile, and Port only when the origin URL has no port.
  • User is ignored, because the origin pins the git user. Match blocks, Include, ProxyCommand, ProxyJump, LocalCommand, KnownHostsCommand and every other directive are ignored.
  • Only plain values are used: after ~/ expansion (to $HOME) and symlink resolution, a value must contain only A-Z a-z 0-9 . _ / + , : @ - and must not start with -. Values with % tokens, ${VAR}, spaces, quotes or several known-hosts files are skipped with a warning, never escaped.
  • ~/.ssh/config, every identity file and the known-hosts file must pass one trust check. agent-loop resolves the path one component at a time. Every component it passes through, including each intermediate symlink and the directories its target passes through, must be owned by you or root and must not be group- or world-writable (a symlink's own mode is ignored). Neither the path you gave nor any component on the way may lie inside an agent checkout, store or run directory, and the final file must be a regular file. An untrusted config is ignored entirely; an untrusted entry is skipped with a warning.

To select a key explicitly, pass --git-ssh-identity /absolute/path/to/key or set AGENT_LOOP_GIT_SSH_IDENTITY. The option wins over the variable, both win over ~/.ssh/config identities, and agent-loop then offers only that key (IdentitiesOnly=yes). An explicit key that fails the trust check stops the run with an error. The option cannot be combined with --trusted-local-origin, and managed recovery commands keep it.

The SSH command pins StrictHostKeyChecking=yes: the server's host key must already be in ~/.ssh/known_hosts (or the trusted UserKnownHostsFile), and unknown or changed keys fail without a prompt. BatchMode is not set, so an encrypted key can still ask for its passphrase on a terminal. Default identity files and SSH_AUTH_SOCK remain available unless IdentitiesOnly says otherwise.

A failed fetch never shows Git's stderr, because it may contain credentials. Instead the error names a fixed class: remote not found, host-key failure, network or timeout, authentication failure or unclassified. An SSH authentication failure suggests --git-ssh-identity. No HTTPS fallback is attempted after an SSH failure.

Before merging a change to git_transport.py, secure_git.py or the checkout sync path, run the pre-merge transport smoke check with your real protocol and credentials: scripts/transport_smoke.sh --repo OWNER/REPO [--trusted-origin-protocol ssh]. It builds the PR head into a temporary venv and runs agent-loop transport-check, which fetches the default branch once into a private scratch repository and prints only transport-check: pass or transport-check: fail (<class>). See Pre-merge transport smoke check.

On Windows, ~/.ssh/config is not read and --git-ssh-identity is refused until a Windows ACL trust policy exists (#1371). SSH transport on Windows is untested: no Windows CI runner exists, so only its command construction is covered (tracked in #1371). This boundary covers settings, hooks, environment, and transport options planted in a checkout; a live, unrestricted agent running as the same OS user that races agent-loop while it runs needs OS-level isolation and is out of scope (#1371).

Optional --worktree-link PATH (repeatable, off by default) symlinks (never copies) an untracked repository-relative path from the shared store, for example .venv, into each per-run worktree. The path must exist in the store (otherwise the run fails, naming the shared clone and suggesting --worktree-setup or creating the path there) and its parent directories must be tracked. Explicit --<agent>-dir checkouts ignore it. The link is exempted from checkout verification, sync cleaning and test-evidence attribution by agent-loop's in-process registry only (no git ignore state is written); a removed, retargeted, staged or committed link is refused. Linked state is shared and mutable across concurrent runs. Keep every link ignored with a root-anchored pattern without a trailing slash, for example /.venv or /node_modules in .gitignore or the store's .git/info/exclude (shared by every worktree); a dir-only .venv/ or node_modules/ rule does not match a symlink. agent-loop warns, and never writes ignore state, when a created link is not ignored. .venv/bin/python works through the link; bare python reaches the linked venv only if the agent environment activates it.

Test dependencies in per-run worktrees

Per-run worktrees start with no untracked environment, so a Python or Node project has no in-checkout interpreter or node_modules unless the operator provides one. --worktree-setup CMD (operator CLI only, never read from repository configuration) builds it once in each active agent's shared clone (/tmp/coding-review-agent-loop/OWNER-REPO/<agent>/repo), and --worktree-link then symlinks it into every per-run worktree. Repeatable --worktree-setup-key PATH names the repository-relative files whose Git entries at the pinned base commit key the setup.

Python:

agent-loop issue 123 --repo OWNER/REPO \
  --worktree-setup "python3 -m venv .venv && .venv/bin/pip install -r requirements.txt" \
  --worktree-setup-key requirements.txt \
  --worktree-link .venv

Node:

agent-loop issue 123 --repo OWNER/REPO \
  --worktree-setup "npm ci" \
  --worktree-setup-key package-lock.json \
  --worktree-link node_modules
  • The command runs via /bin/sh -c in the shared clone, as the operator with full privileges and the operator environment, outside any agent sandbox, under the store lock and bounded by --worktree-setup-timeout SECONDS (operator CLI only, requires --worktree-setup, default 3600). The limit is independent of --coder-test-command-timeout-seconds, so a slow npm ci or pip install is not cut short by the test-gate ceiling; a timeout stops the run with a message naming the flag. Managed-CI recovery commands keep it.
  • It runs again only when the command string or a key entry at the newly pinned base commit changes, when a --worktree-link source is missing or is a dangling symlink, or when agent-loop (re-)creates the clone. Without keys it runs once per clone lifetime. Setup is rechecked at every base pin, including the base sync just before implementation; PR-head checkouts keep the base environment.
  • The store lives under /tmp and is wiped on reboot; the next run simply sets it up again.
  • A nonzero exit or timeout stops the run with the output tail and leaves no setup record, so the next run retries. A success record is kept per clone under the private host lock root, outside the repository.
  • Before a required setup, tracked files in the shared clone (including initialized submodules) must match the base commit: any locally modified, staged or deleted tracked file, and any index entry flagged assume-unchanged or skip-worktree, stops the run without overwriting it. Untracked and ignored content there is operator-trusted.
  • An untracked file at a --worktree-setup-key path that is absent at the base commit also stops a required setup, because the digest does not cover it. A setup command may create such a file itself: npm install writes package-lock.json when the repository tracks none. After a successful setup agent-loop records the SHA-256 of each such generated key file in a private ledger next to the success record, and later setups in the same clone accept it while its bytes are unchanged and it is still a regular file. The ledger survives a failed or timed-out setup and is deleted when agent-loop re-creates the clone. An edited, replaced or symlinked generated file, a file a failed setup created, and any file the operator placed there still stop the run; the message names the path and says the file may have been created by the setup command itself. Remove it after confirming, or track it in the repository. A generated file that a later setup reads (npm reusing its own lockfile) is an input the digest does not cover.
  • When a new base commit starts tracking a generated key file, agent-loop removes it before the checkout only if its bytes still match the ledger, re-verified just before the removal. Any other untracked file at that key path, ignored or not, stops the run before the record is touched or the setup runs, and is left unchanged.
  • The shared-clone checkout never overwrites ignored files (--no-overwrite-ignore): an ignored file or directory, for example node_modules, at a path a new base commit starts tracking stops the run with Git's checkout error instead of being silently replaced. Remove it in the shared clone and rerun.
  • Linked environments are shared and mutable across concurrent runs; a rerun of setup changes them under other runs' turns.
  • Keep each link ignored as a symlink: /.venv or /node_modules, without a trailing slash.
  • When neither --worktree-setup nor --worktree-link is given and the base tree has requirements*.txt, pyproject.toml, setup.py, Pipfile.lock, poetry.lock, uv.lock, package-lock.json, yarn.lock or pnpm-lock.yaml, agent-loop logs one hint per run. It never installs anything on its own.
  • Without --worktree-setup-pr-local, a PR that changes a key file still runs against the base environment; see Dependency changes inside a PR.
  • Without --worktree-link, a run-tests launch failure in a per-run worktree (a missing .venv/bin/python, or an interpreter without pytest), a coder test-gate launch failure and a refused out-of-checkout test executable add one line naming --worktree-link and --worktree-setup, chosen from the orchestrator's own configuration. The line is advice only; classification, outcome, evidence identity and exit codes are unchanged.
  • A replaced or removed link is still refused; the message names the link source in the shared clone and says that dependency changes inside a PR need --worktree-setup-pr-local or an explicit --<agent>-dir checkout. When an issue run stops after the coder pushed its branch and its checkout became untrusted (a checkout refusal or a terminal result with no PR), the stop also prints agent-loop managed-pr --head <branch> --expected-closing-issue N as the resume and the manual git -C <store> worktree remove --force <run-worktree> cleanup; agent-loop never removes that worktree itself.

Dependency changes inside a PR

--worktree-setup-pr-local (operator CLI only, never read from repository configuration; requires --worktree-setup, at least one --worktree-setup-key and at least one --worktree-link) gives per-run worktrees private dependency environments, so a PR may change package-lock.json or requirements.txt:

agent-loop issue 123 --repo OWNER/REPO \
  --worktree-setup "npm ci" \
  --worktree-setup-key package-lock.json \
  --worktree-link node_modules \
  --worktree-setup-pr-local
  • Every writable per-run worktree (the coder's, and every worktree of a run that is not --agent-permissions sandboxed) gets a private environment before its first agent turn: agent-loop removes its links without following them (a symlink is unlinked, never its target) and runs the setup command inside the worktree. An install during a turn therefore changes only that worktree, never the shared clone. This costs one full install per writable worktree per run, plus one per committed key change; the private environment is removed with the worktree.
  • After each turn and each sync, agent-loop compares the digest of the --worktree-setup-key entries at the worktree's committed HEAD with the digest its environment was built for. A difference removes the private paths (or links) and rebuilds them with the setup command, then logs PR-local dependency environment: rebuilt ...; the next coder prompt names the rebuilt paths and HEAD. Returning the keys to the base digest rebuilds privately again; it never re-links.
  • During a key-changing turn, tests use the previous private build until the rebuild at the end of the turn, and test evidence from before a rebuild does not count for the rebuilt environment: the evidence snapshot binds each result to one concrete environment (registration nonce, generation and digest).
  • Setup reads only committed bytes. Any uncommitted, staged or index-hidden (assume-unchanged, skip-worktree) tracked change, a dirty or drifted initialized submodule, or an untracked or ignored file at a key path absent from HEAD defers the rebuild; nothing is removed and the remedy names the paths. An untracked key file is never exempted here, even one an earlier setup created; the deferral message says it may have been created by the setup command itself.
  • Each PR-local rebuild is bounded by --worktree-setup-timeout too.
  • Deleting or replacing a private environment, or a link, without a committed key change is still refused, as is staging or committing it.
  • Read-only worktrees of a sandboxed run (agents that hold only CLI-enforced read-only roles) keep the shared links and move to a private environment only on a sync whose HEAD changes a key; the read-only grant is what keeps their turns from writing through the links.
  • Trust boundary: with the flag on, the setup command runs on PR-controlled key files and their install scripts as the operator, unsandboxed, with the same privilege as the test gate running PR code. That is why it is opt-in. A setup failure or timeout poisons the checkout with the output tail and stops the next turn; the shared clone is never touched.

Reviewer blocking scope and declared non-goals

Plan and PR reviewers block only on the issue's stated requirements or signed human requirements, regressions in behaviour the change touches, or security and data-loss risk the change introduces. Other hardening goes in future follow-ups, which blocking reviews may now carry too; they are published at approval under --approved-followups and never become coder or planner work. Add an ## Out of scope or ## Non-goals section to the issue body (or a signed human comment) to declare areas the planner and every reviewer must treat as binding scope. See docs/local_agent_loop.md.

Sub-items for conjunctive findings

A reviewer can split a finding that bundles several separately checkable obligations into an ordered sub_items list, and the loop reports partial progress as counts (item-1: 3/4 sub-items resolved) instead of a bare addressed/remaining split. Single-obligation findings are unchanged. Reviewers disposition individual sub-items, coder claims are advisory, and an item is resolved when all of its sub-items are. --sub-item-stall-rounds N (default 3, 0 disables) warns when no sub-item of a finding closes for N rounds; it is advisory and never changes --max-rounds. See docs/local_agent_loop.md.

Advisory architecture context

By default, workflows read the conventional repository-local ARCHITECTURE.md from committed Git objects and include a bounded, revision- and hash-labeled overview in planning, implementation, and review prompts. Use --architecture-path docs/ARCHITECTURE.md for a validated repository-relative POSIX override, or --no-architecture-context to opt out. Missing, unsafe, binary, or unavailable documents preserve the legacy prompt path.

The path names the root of an architecture set: the root document plus every repository-relative Markdown file under a configured detail directory (by default docs/architecture/) that the root links to (inline links and reference links whose definition is actually used), minus excluded history. Links are followed one level only; unlinked files under a detail directory are not members. Agents may still open deeper linked docs, and excluded history, on demand from the checkout. Links are read with a CommonMark parser (the markdown-it-py runtime dependency), so code, raw HTML, images (including links inside an image description) and unresolved references never count, and the detail-doc and oversized heading indexes list only real Markdown headings; without the parser, membership is reported as unknown. The recommended layout is a short root overview of at most about 10k characters (what the system is, a component map with each component's role, main source paths and detail doc, system-wide invariants, the main flows, and an index of the detail docs, with no issue history) plus detail docs of about 10–30k characters each under docs/architecture/. Each detail doc opens with a short summary and the source paths it covers and ends with a "Decisions" section that holds only a link to its decision log at docs/architecture/decisions/<same-name>.md. Log entries take the shape - **Title.** What was chosen; why; rejected alternatives. (#N, YYYY-MM-DD) and restate no current values. They are append-only: a replaced entry gets Superseded by #M: <clause>. appended and is never rewritten or deleted. Record decisions in the log, keep the body current, and read the log before changing a component's behaviour. The root never links into docs/architecture/decisions/, and decision logs are excluded from the set by default anyway. When the set has detail docs, prompts carry the root overview followed by a short detail-doc index: path, first heading and the first sentence of the doc's opening summary, bounded to about 200 characters. Summaries are the first thing dropped under a tight budget, before index entries and before the root overview is truncated. --architecture-read-size applies to the root and to each member. A root larger than the read size is not dropped: the prompt carries its identity, size and a bounded heading index, with a diagnostic that the document is too large and should be split into a short root overview plus docs/architecture/* detail docs (roots above a 2 MiB scan ceiling, or that are not valid UTF-8, are injected without an index and with set membership marked unknown). A coder's canonical_document_path must be null or name a member of the set (normalized as a repository-relative path); an out-of-set path gets one bounded re-ask. The PR base/candidate comparison covers every member, so a PR that edits only a detail doc is reported as an architecture change; member paths are named (with their bounded summaries) but only the root documents' text is injected.

The layout above is the recommended default, not a requirement. It has four layers: a short root index, detail docs that are set members, deeper docs linked on demand, and a decision log or ADRs kept out of the set. It follows matklad's ARCHITECTURE.md (a short map of the codebase), keeps ADR-style history separate from the current design, and gives each index entry a one-line description in the spirit of AGENTS.md and llms.txt indexes. To point the tool at an existing convention:

  • --architecture-path design/OVERVIEW.md names a different root.
  • --architecture-detail-dir DIR (repeatable) names the directories whose root-linked .md files are members. Giving it replaces the default docs/architecture/, so repeat that value to keep it, for example --architecture-detail-dir docs/design --architecture-detail-dir packages/core/docs. An explicit list is used rather than "any linked .md" so the default set, and therefore its approval identity, stays unchanged, and a stray root link to a README or changelog never becomes a member.
  • --architecture-exclude DIR (repeatable) adds a history directory that is never a member, even when linked; a leading */ matches it at any depth. The defaults are */decisions/, doc/adr/ (adr-tools) and docs/adr/. --no-default-architecture-excludes drops the defaults. An adr-tools or MADR repository that links its ADRs from the root needs no flag for doc/adr/ or docs/adr/; for MADR's docs/decisions/ the */decisions/ default applies.

Exclusions always win over detail directories, and a detail directory that an exclusion covers entirely is rejected before any agent runs. The membership policy is not part of the architecture identity; only the resulting member paths and blobs are, so default-layout repositories keep the same identity. A repository whose root currently links into an excluded directory loses those members once, which changes its identity once. The read and rendering budgets are configurable with --architecture-read-size, --architecture-snapshot-max-chars, and --architecture-aggregate-max-chars; --managed-context-max-chars bounds active managed prompt context and fails closed when an explicitly restrictive cap cannot retain protected requirements or plan context. The overview is untrusted orientation only: source inspection and full-diff review remain required, and it is not a whole-codebase audit or correctness guarantee. Architecture-impact assessments distinguish contract changes from meaningfully unchanged work and guide updates to the canonical document.

Machine obligations and CI repair

Selective review keeps reviewer-owned findings separate from machine-owned obligations. Managed exact-head CI, ordinary PR checks, migration validation, mergeability, and human-requirement acknowledgement have stable authority kinds and are upserted by kind rather than accumulated as duplicate reviewer items. After a machine failure, the failed head is permanently ineligible for requalification: the coder must produce a strictly different head, and the selective scheduler takes the broad full-board path for that repair transition.

Reviewer dispositions keep machine records complete in the review ledger, but approval is evidence about the correction only; it is never CI success. Each authority clears only from its own fresh, correctly correlated result for the current head and base. Skipped, absent, intermediate-filtered, stale, or uncorrelated checks cannot satisfy the final gate. Qualification checkpoints record the obligation, heads, review/plan/requirement identities, scheduler inputs, attached attempt, and the two independent one-shot allowances (one failure repair and one head-change re-review, for at most max_rounds + 2). Restarts resume a correlated attempt when possible and otherwise fail closed. Terminal diagnostics distinguish reviewer objections, repair-required CI, qualification pending, migration/mergeability validation, unknown persisted state, and external infrastructure stops.

Signed comments ending in -- Human Reviewer are treated as explicit human requirements and remain approval-critical. See Human requirements for the exact contract.

By default the signature is an honour system: agent-loop does not check who wrote a signed comment, so anyone with write access to the repository, including the agent accounts themselves, can create an authoritative requirement. Prompts then label every requirement's author as unverified. To admit only specific identities, pass one repeatable --human-reviewer-trusted-actor LOGIN:ID per trusted account (find the numeric ID with gh api users/LOGIN --jq .id). With a trust set configured, a signed issue body, issue comment, PR comment, or PR review counts only when its live REST author matches both the login and the numeric ID of one entry. Other signed comments are logged as excluded and stay ordinary discussion. An agent account that relays operator decisions must be listed explicitly if its relayed comments should count.

Reviewer-board amendments use a stricter author policy than ordinary signed requirements: only the authenticated invocation account and configured human LOGIN:ID pairs are eligible. With no trusted humans configured, only the invocation account can amend a board. To replay amendments posted by a separate human account, configure that account with --human-reviewer-trusted-actor; unconfigured historical amendments are ignored and logged. Human admission never authorizes round metadata or sidecars sharing that comment.

What "review" and "approval" mean

Agent-loop publishes model reviews as structured comments in the pull request's conversation. An Approved verdict means that the named model approved the recorded PR head under agent-loop's protocol. It is not a native GitHub pull-request review, does not populate GitHub's Reviewers or Reviews panels, and does not satisfy a branch-protection rule that requires approving GitHub reviews.

The agent CLIs normally share the GitHub identity authenticated through gh, so their model signatures identify protocol participants rather than distinct GitHub accounts. If a repository requires native GitHub approvals, obtain them separately from an eligible human, bot, or GitHub App identity. GitHub's own merge protections remain in force in addition to agent-loop's reviewer and CI gates.

When a coder and reviewer maintain an evidence-backed disagreement after the reviewer's reconsideration turn, agent-loop posts a Human decision required comment and exits with status 4. This is an intentional operator boundary, not an orchestration failure. Respond on the PR with the decision and required action in a comment ending with -- Human Reviewer, then resume the PR. An issue-created managed PR keeps its suppression label while waiting, so ordinary CI is not released before approval.

The same signed comment is also how an operator adds instructions to a PR that is already approved at its head. Without one, rerunning agent-loop pr <number> on an approved head prints the approval and exits without invoking any agent: a plain PR comment is not read as a requirement, and --pr-review-force-full changes who reviews, not what must be fixed. Post the new instructions in a PR comment ending with a line containing exactly -- Human Reviewer, then rerun agent-loop pr <number>. A new or edited signed requirement invalidates every carried approval, so reviewers re-check the same head against it and any unmet part becomes a coder obligation in that PR. The approval message and agent-loop pr --help name this path.

A signed comment is also how an operator answers an exact-head evidence freeze. Some approved plans require evidence that no agent can produce, such as an authenticated live-CLI run at the exact head. Reviewers request it separately from code findings. The loop requests it only once the board and every machine gate are clean at a head: it posts one freeze comment naming that head and stops with exit code 4, and it pushes nothing while frozen. Supply the evidence for that head, or withdraw the request, in a signed comment and rerun. The requesting reviewer then re-reviews the same head without spending a round. See the evidence freeze. When an external push breaks a converted-row freeze, the coder gets one bounded capture opportunity from admitted freeze and coder history. Live-head tool evidence supersedes conversions; missing or failed capture preserves the final human evidence barrier. Native human-only evidence does not dispatch the coder.

The signature certifies that a human wrote the requirement, and nothing verifies authorship. An agent must not apply it on its own initiative; when an operator tells an agent to relay a decision, the relay must be disclosed in the comment.

Current Limitations

  • Each run claims every agent checkout it uses for its duration (a flock lock file under a private per-user lock root, outside the checkout). A second run that resolves to a claimed checkout is refused by name (pid, run id, repo, command and target) before any reset or clean; a claim left by a crashed run is taken over. Concurrent default-dir invocations on one repository now proceed: each gets its own detached worktree off a shared per-repo store, removed when the run ends, and stale worktrees of killed runs are pruned at the next startup. Runs with explicit --{agent}-dir checkouts behave as before. Other repo-scoped local state (the memory cache, subprocess-log root) is still shared. --allow-shared-dir only lets agents within one run share a checkout; it never lets a second run use a claimed one. --review-parallel is supported within one orchestrator run.
  • Agent-loop is a local process, not a hosted service. The machine must remain available for the run, and an interrupted in-flight agent turn may need to be repeated. Once a PR exists, resume with agent-loop pr <number>.
  • GitHub is the only supported forge, and every selected agent backend must be installed and authenticated locally.
  • Agent CLIs can exhaust quota, time out, update themselves, or return malformed structured output. Retries, repair passes, and salvage reduce lost work but cannot guarantee unattended completion. A usage limit with a parsed reset stops the run (exit code 3) unless you opt in to waiting for it with --wait-for-quota-reset DURATION (for example 6h; see Waiting for a quota reset).
  • Default agent checkouts live under the system temporary directory (/tmp on Linux) and may disappear after a reboot or system cleanup. Configure explicit workdirs for long-lived installations.

Planning and Decomposition

Plan-first mode supports five post-approval choices:

Mode Result after plan approval
plan-only Post the approved plan and stop. This is the default.
implement-one-shot Implement the approved plan in one PR.
decompose-only Create detailed child issues for the approved phases and stop.
implement-by-phase Create the phase issues and implement or resume the current (first incomplete) agent phase, returning that child's exit status; rerun the parent after delivery to advance to the next phase, and to get a terminal delivery report once every phase is complete. That report is also posted once to the parent as a completion record (by the child run that auto-merges the last phase, or by the next parent rerun); the parent is left open for the operator to close.
auto After approval, select one-shot or by-phase, then route each staged child from its reviewed disposition.

Example:

agent-loop issue 123 --repo OWNER/REPO \
  --plan-first \
  --plan-execution-mode decompose-only

--plan-execution-mode decompose-only and --materialize-split-issues are different mechanisms. Do not combine them for the same decomposition: doing so can create duplicate children. Use the former for detailed approved phases and the latter for discuss-mode split proposals or eligible plan-only deferred work. auto cannot be combined with either --materialize-split-issues or --split-stage, because its topology is unknown until approval. Read Phased decomposition versus split materialization before filing child issues.

For fresh staged plans, the planner declares each child as direct-implementation, requires-child-planning, or human-owned, and plan reviewers approve or block that semantic choice. The orchestrator checks typed readiness fields and approved-parent provenance; it does not infer readiness from issue size or file count. A direct child uses the parent stage contract without duplicate planning. A planning-required child records its route first, then must run with --plan-first and complete its own reviewed plan before implementation. That child plan may refine or strengthen the risk-matrix rows it inherits from the parent but may not weaken them; weakening is caught and replanned during child planning rather than after implementation. Recorded routes survive reruns and cannot be switched with CLI flags. See the detailed child execution disposition contract.

Re-planning an approved child plan

An approved child plan can stop satisfying the inherited-matrix contract, most often because the contract tightened after the plan was approved. The failure always names a supported route, and which route depends on how far the child got:

  1. No implementation handoff yet. Rerun the same --plan-first command. The loop posts one audit comment, sends the approved plan back to the planner with the field-level diagnostic, mechanically rechecks the revision before it is posted, and has the complete reviewer board review it. No signed record is needed, because nothing is bound to the plan yet.
  2. A handoff and an open PR already exist. The plan can only be re-planned under a signed human authorization. Without it the run stops before any agent turn and prints this record pre-filled for the child. Post it as a comment on the child issue, then rerun agent-loop issue <child> --plan-first --plan-execution-mode auto:
Child plan supersession:

```json
{
  "child_issue": 925,
  "kind": "child-plan-supersession",
  "parent_issue": 924,
  "rationale": "Approved before the inherited-matrix contract tightened.",
  "schema_version": 1,
  "stage_id": "stage-1",
  "superseded_plan_hash": "<16-hex plan hash printed by the diagnostic>"
}
```
-- Human Reviewer

The child is re-planned, and once the revision is approved the same PR is rebound to the new plan hash by one issue comment. No second PR is opened, no implementation turn runs, nothing is written on the PR, and reviewer approvals recorded before the rebind do not count under the new plan. agent-loop pr <n> never re-plans or rebinds; on an inadmissible binding it fails closed and prints the same route. If the replacement plan adds or replaces steps, adds matrix rows or changes an existing row, or adds or changes any execution-recommendation value (including its strategy), the rebind comment also carries an informational notice naming what grew; it never stops the run.

Deliberate re-plan of an admissible plan. The same signed record also authorizes replacing a bound child plan that is still admissible, for example a human-approved scope reduction. The record is consulted for every bound plan, not only an inadmissible one: post it naming the bound plan hash (printed in the plan_hash= log line) with the reason as rationale, then rerun agent-loop issue <child> --plan-first --plan-execution-mode auto. The planner receives the rationale, reviewer approval of the superseded plan never approves it again, and the revision is rebound to the same PR as above. While such a record is pending, agent-loop pr <n> stops before any reviewer runs and prints the issue-mode rerun command instead of reviewing the PR against a scope no plan approved. The check is repeated on the freshly fetched child issue before every approval or merge, so a record posted during review also stops the run. A PR follow-up coder turn that leaves the head unchanged twice in a row stops the run with a human-review error instead of re-reviewing an identical diff.

Rules: keep exactly one signed record per superseded plan hash (two distinct records for one hash always stop for a human decision; records are never chosen by comment order), and leave the record in place afterwards because the rebound PR re-verifies it on every run. Re-planning continues the child's existing round numbering, so raise --max-rounds if the budget is exhausted. Abandoning or replacing the existing PR, re-planning direct-implementation or non-child issues, revising the parent plan, and any unsigned or flag-only bypass are not supported.

Migration note. When the inherited-matrix contract tightens, children approved under the looser contract are reported as inadmissible the next time the loop touches them. That is expected: follow the route above rather than hand-editing issue records. See the detailed contract.

Removing an unavailable reviewer from an in-flight run

If one reviewer's backend becomes unavailable, for example because its quota is exhausted, rerunning without that reviewer is a recorded board change, on a PR (#1376) and in planning (#1377), unless it takes the board below --min-reviewers or --min-distinct-providers. The planning policy stays immutable for the run. A below-floor refusal prints a filled-in signed reviewer-board amendment record. A human operator posts it to record a deliberate, audited reduction of the board:

Reviewer board amendment:

```json
{
  "effective_from_round": 3,
  "flow": "plan",
  "issue": 942,
  "kind": "reviewer-board-amendment",
  "original_required_reviewers": [
    "Codex",
    "Claude",
    "Antigravity"
  ],
  "policy": "primary-then-panel",
  "pr_number": null,
  "primary_reviewer": "Codex",
  "rationale": "Antigravity weekly quota exhausted.",
  "reason": "backend-unavailable",
  "removed_reviewers": [
    "Antigravity"
  ],
  "schema_version": 1
}
```
-- Human Reviewer
  • Where to post it. Post a plan record (issue set, pr_number null) on the issue being planned. Post a pr record (pr_number set, issue null) on the PR itself, including standalone agent-loop pr runs. A record on the wrong surface, a record naming another issue or PR, and a pr record on the owning issue all stop for a human decision.
  • Named PR seats. Use reason seat-unavailable when one or more named seats independently exhaust their model chains; list all affected seats in one amendment. Other seats on their backends remain required. Use backend-unavailable for a shared backend outage and remove every active seat on that backend in the same amendment. The signed record still binds the original board and takes effect only after the normal resume checks. When shared backend outages and independent seat failures happen together, use mixed-unavailable. Its rationale must start with shared_outage_backends=backend1,backend2 on its own line. Every active seat of each listed backend must be removed; other removed seats remain local failures.
  • Named plan seats. The default all-reviewers plan policy persists its required seat board. A shared backend outage can remove all affected seats through a signed plan amendment; restoration requires a later signed record.
  • Choosing effective_from_round. Use the round number the drift error prints. That is the round the resume re-enters, whether the round is only partly recorded or already reconciled, and it is not always the latest visible round number. Any other value stops before any agent turn or comment and prints the corrected template.
  • Which board to rerun with. Posting the record is what removes the reviewer. For a PR run, keep the original reviewer board configured (recommended); the run derives the amended board from the signed record and never selects, invokes, or requires the removed reviewer, including under an automatic force-full latch. The reduced board is also accepted, except on an issue-created strict managed-CI PR, where the approved plan is re-verified against the flags you supply and the original board is required. Planning reruns use the reduced board. A different board stops while the signed record is still pending, and becomes a recorded board change once the record has taken effect. If you posted a record and still see a refusal, the record was not recognized, so look for an ignored-record diagnostic in the log.
  • Record format. Line endings may be LF or CRLF (a lone CR is not supported). A comment that consists only of one fenced block naming the record kind but not written as a ```json fence is reported as an ignored record and is never applied.
  • Records posted under an unread amendment. If a run posted scheduler records after an amendment comment it could not read, those records are never reinterpreted. The drift error then tells you to delete the unread amendment comment and post a fresh signed record with the printed effective_from_round.
  • Retroactive use. The record rescues runs whose contract was persisted before this feature existed. Earlier rounds are never rewritten. Inside the re-entered round, reviews already posted by the remaining reviewers are reused, and the removed reviewer is never invoked again.
  • What stays immutable. policy and primary_reviewer must match the persisted contract. The primary cannot be removed, and a primary-then-panel board must keep at least one secondary. Re-adding a removed reviewer by changing the reviewer flags alone is a recorded board change, on a PR and in planning; a signed restoration (see below) also works. Every scheduler record posted after the amendment carries the amended board and the record's digest; any other contract fails closed, and at PR qualification it refuses the merge. Amendments can chain, with each record's original_required_reviewers equal to the previous amended board. Two different records that amend the same board always stop for a human decision.
  • Findings and approvals. An active finding whose only pending owner was removed is reassigned to the primary, or to every remaining reviewer when there is no primary. It stays blocking until a new owner clears it; nothing is auto-cleared. Approvals the removed reviewer already gave remain in the history but are no longer required. The run posts one audit comment naming the record, the activation round, and every reassignment. Scheduler audits, completion messages, and (for PR runs, on every completion path including managed CI) one plain completion comment on the PR note that the run finished on a reduced board. The activation round always posts a fresh scheduler checkpoint carrying the amended board and digest, even when every remaining reviewer's review is reused. When the activation round was already reconciled and a reviewer now needs a fresh turn, that checkpoint selects nobody and the fresh turns open the next round.
  • Unsigned or malformed records are ignored with a logged diagnostic. A comment that contains only the record is not treated as a signed human requirement. All-reviewers PR runs and the non-staged plan path persist no contract, so there you change the reviewer flags directly and must not post a record.

Restoring a recovered reviewer. Backend outages are usually temporary. When a removed reviewer's backend recovers, rerun with the full reviewer flags; the drift error then prints a filled-in restoration record. It is the same signed record with an optional restored_reviewers list, an empty removed_reviewers list, and reason backend-recovered:

{
  "original_required_reviewers": ["Codex", "Claude"],
  "removed_reviewers": [],
  "restored_reviewers": ["Antigravity"],
  "reason": "backend-recovered",
  "effective_from_round": 6
}

(The other keys are the same as in the removal record.) A restoration may only re-add a reviewer that an earlier record in the run's amendment chain removed and that is not already required, so the board can never grow beyond the original one. It keeps the original board order. The effective round, activation rule, digest binding, and fail-closed handling are the same as for removals, and removals and restorations chain freely (remove → restore → remove). From its effective round the restored reviewer is required again. Approvals it gave before that round do not count, so it must re-approve the current artifact before the run can complete. Findings that were reassigned while it was off the board stay with their new owners and are not re-opened. Once the board is back to the original set, no reduced-board completion note is posted.

See the detailed contract.

Approved follow-up dedupe

When approved future follow-ups are summarized or filed, semantic reuse is enabled by default after deterministic narrowing. Use --no-semantic-followup-dedupe for deterministic-only operation. The provider and its bounds are configurable with --semantic-followup-backend, --semantic-followup-model, --semantic-followup-timeout-seconds, --semantic-followup-max-calls, --semantic-followup-max-candidates, and --semantic-followup-prompt-char-limit. Only high-confidence matches suppress or merge work; uncertain matches are filed with a possible-duplicate note.

The default backend is antigravity, using the first --antigravity-models entry (a cheap Flash model) unless --semantic-followup-model is set. Its per-call timeout defaults to 120 seconds (30 seconds for the other backends); an explicit --semantic-followup-timeout-seconds always wins. The Antigravity classification turn runs in an isolated empty temporary directory with no tools and returns its JSON on stdout only. When the selected backend's CLI is not on PATH, semantic matching is skipped with one log line (Approved follow-up semantic dedupe skipped: <backend> CLI '<cmd>' is not configured ...) and deterministic matching continues; the run does not fail.

Discuss Mode

Discuss mode asks agents to evaluate an issue without modifying the repository. Use it for architecture choices, product decisions, feasibility questions, or whether work should be implemented or split.

agent-loop discuss 123 \
  --repo OWNER/REPO \
  --reviewer claude \
  --reviewer codex

The default result contract is implementation triage: implement, do-not-implement, needs-human, or split. For an open-ended recommendation instead of an implementation vote, use --discuss-result-mode answer.

Useful optional controls include:

  • --discuss-analyzer AGENT for a structured consensus/disagreement agenda.
  • --discuss-research auto|required|none for current external facts.
  • --discuss-parallel for concurrent independent positions.
  • --materialize-split-issues to file agreed split proposals.

See Discuss mode for result semantics, research evidence, deadlocks, and resume behavior.

Answer-mode summaries now put a bounded executive state before the audit transcript. With a configured --discuss-analyzer, completed non-final rounds reuse the analyzer's enriched agenda when available and show cumulative current consensus, active disagreements, changes, missing facts, and next-round focus. The final comment similarly leads with outcome, agreed conclusions, residual decisions, and the next action. Exact, semantic-equivalent, and debater-confirmed results reuse their mechanically validated artifacts without a redundant final synthesis call; only the configured discuss analyzer may perform the explicitly bounded fallback or final synthesis call. Analyzer-less or invalid synthesis falls back to the existing fail-closed result. Per-agent comments remain the authoritative raw audit, and resume metadata carries only the latest validated snapshot with bounded, spillable excerpts.

Agent Backends

Backend CLI Notes
Claude claude Default coder. --claude-model selects the model to run and stamp in the signature.
Codex codex Default reviewer. Select a model with --codex-model.
Antigravity agy Accepted as agy or antigravity; supports coder and reviewer roles.
Gemini gemini Legacy, best-effort path for accounts that still have CLI access.

The default Antigravity model chain is Gemini 3.8 Flash (High), then Claude Opus 5.5 (Medium) (served on a separate quota) for eligible capacity failures. A quota-exhausted provider is skipped as a whole quota group, so a Gemini exhaustion goes straight to Opus; see Quota groups and fallback. Override it with --antigravity-model or --antigravity-models. Antigravity turns are single-shot and its usage totals are estimated because agy does not expose token counts. A model that repeatedly answers in chat prose with no recoverable structured payload also falls back to the next chain model. When agy supports --output-format, structured turns read the single JSON answer from agy's JSON envelope. Disable it with --antigravity-structured-output off; see Structured output.

Malformed structured responses get a format-repair pass. By default it uses Antigravity with the repair chain Gemini 3.8 Flash (Medium), then Claude Opus 5.5 (Medium), followed by the Antigravity chain above. Use --repair-backend and repeatable --repair-model to change it. The default requires the agy CLI even when no role uses Antigravity; on a host without it, pass --repair-backend codex --repair-model MODEL (or claude). Models that agy models does not list are skipped. When agy reports a transient model-access validation errors failure on its own output (stdout with no response artifact and no structured JSON response), that repair model is retried once, and then the next model in the chain is tried. If the chain ends on that transient failure, the run stops with a resumable repair-provider-failure and a suggestion to re-run the same command. It is not reported as a deterministic plan-validation failure. A valid repaired response is always accepted, and model-authored text that only quotes the phrase is still treated as invalid output.

Backend-specific authentication, model selection, fallback, timeout, and executable-replacement behavior are documented under Agent backends.

Reasoning-effort defaults

Agent-loop owns the effort setting for Codex and Claude. When no effort option is supplied, every invocation explicitly receives medium; a local CLI config file or inherited environment value cannot silently change that selection. The precedence is the matching role override (reviewer or implementation), agent-wide option, then the tool default. Use --codex-reasoning-effort xhigh (or the matching implementation option) for an explicit higher-effort Codex/Luna run. Claude accepts low, medium, high, xhigh, and max through --claude-effort. Antigravity's selected model already carries its tier, such as Gemini 3.8 Flash (High), and is not rewritten by this setting. Startup logs, signatures, usage records, and new round metadata distinguish configured effort from verified runtime observations; older records retain unknown values.

Separate Coder and Reviewer Models

When Codex or Claude occupies both seats, select its reviewer independently:

agent-loop pr 123 --repo OWNER/REPO \
  --coder codex --reviewer claude --reviewer codex \
  --codex-model gpt-5.6-luna --codex-reasoning-effort xhigh \
  --reviewer-codex-model gpt-5.6-sol --reviewer-codex-reasoning-effort medium

Claude has matching --reviewer-claude-model and --reviewer-claude-effort options. These overrides apply to plan reviews, PR reviews, and discussion participants, not the coder or discussion analyzer. Model and effort are independent: omitting either retains that setting's existing fallback. Reviewer overrides survive the issue-to-PR implementation handoff; repeat them when starting a separate resume command. See the issue-mode example and precedence.

Selective intermediate PR review

PR review keeps the historical all-reviewers policy by default. To pause reviewers who have already approved while a narrow fix is checked, opt in with:

agent-loop pr 123 --repo OWNER/REPO \
  --pr-review-policy selective-intermediate

The initial candidate always runs the full configured board. A later transition is considered narrow only when repository-observed Git history is available and the complete diff contains ordinary text additions or modifications within the exact reviewer-provided fix_scope paths. Workflow, dependency/lock, build/packaging, schema/migration, and repository-policy/configuration paths use deterministic broad rules; customize the rule list with repeated --pr-review-broad-rule options. Missing, disputed, invalid, out-of-scope, or uncertain scope is conservative and reactivates the full board. The --pr-review-force-full latch remains active for the rest of the run.

For example, with Claude, Codex, and Antigravity required, a Codex-owned fix scoped to src/worker.py can invoke Codex for the intermediate head while the other two approvals are retained as historical evidence. Once the obligation is cleared, the final exact-head sweep invokes only Claude and Antigravity if they lack qualifying approvals for that head. A same-head approval is reusable only when its approved-plan/handoff identity, surfaced requirements, and acquisition contract still match. Every required reviewer must still approve the exact final head; selective scheduling never changes CI or merge gates.

Resolution ownership is durable: a non-owner blocking disposition adds that reviewer as an owner, while a non-owner resolved disposition is evidence only. Every owner must independently clear the obligation. An unavailable owner is not an approval; when all remaining owners are unavailable, the run stops as an incomplete review without another coder turn. Scheduler decisions are recorded in round audit metadata and recover conservatively after interruption or a configuration change. Issue-mode implementation handoffs carry the same PR policy, while planning and discussion remain outside this policy.

Primary-then-panel PR review

The opt-in staged policy lets one configured primary work to exact-head approval before an independent secondary audit:

agent-loop pr 123 --repo OWNER/REPO \
  --pr-review-policy primary-then-panel \
  --primary-reviewer codex \
  --reviewer codex --reviewer claude --reviewer gemini

The primary is the first and only reviewer in the normal opening phase, and it alone rechecks its own findings on each narrow fix until it approves the exact head. Once it approves, every secondary reviews the complete current base-to-head diff from a common snapshot in the secondary-audit phase; secondary prompts are independent and are not finding-check prompts. A scoped secondary fix enters remediation, which rechecks every active finding owner and the primary, then performs a complete exact-head final-secondary-sweep for every secondary missing approval.

Before the primary's first exact-head approval the phase is strictly primary-only. A broad or out-of-scope change, missing or ambiguous fix scope, recovery ambiguity (a stale qualification checkpoint, an architecture identity change, obligation-digest drift), or legacy/malformed/contradictory scheduler metadata re-invokes only the primary with full context. The audit reason starts with strict pre-panel fallback: and nothing is latched. Secondaries are never treated as finding owners before their first legitimate panel invocation. The panel is opened only by a qualified panel opening: a secondary-audit record preceded by the primary's approval of the same exact head, or an operator-attributed force-full record. Secondary reviews, full-board checkpoints, and unattributed force-full latches written before such an opening (for example by the pre-#840 automatic escalation) are premature-panel artifacts. They are ignored, and a secondary approval counts only when it was recorded after the qualified opening.

After the panel has opened, the existing conservative rules apply, with audit reasons prefixed post-panel fallback:. An active finding with a broad, ambiguous, out-of-scope, or unreconstructible change, and any unsafe head change, selects the complete board. That full-board decision, like any automatic recovery reason, raises a durable latch recorded with source automatic, so later heads stay on the complete board instead of returning to owner-scoped remediation. Missing input is never treated as approval.

If safety cannot be established without the panel, the run stops with a PR review scheduling diagnostic instead of silently spending it. That happens when a finding is pending on a configured secondary, or a premature secondary review in an interrupted round is blocking, and there is no qualified opening. No reviewer runs. Rerun with --pr-review-force-full to authorize the complete board. Undecodable scheduler history (for example a missing round-metadata sidecar) also stops with the diagnostic, at startup or at a round boundary. It stops even with the flag, because resume, approval, and qualification accounting all depend on that history; restore the missing records and rerun. The operator latch is durable, is recorded with source operator, and is itself a qualified opening. Under the override, a premature blocking secondary review is superseded rather than consumed: it is listed in the operator audit comment, excluded from the ledger and approvals, and replayed to that reviewer only as non-authoritative context for its fresh review.

The tradeoff is deliberate. Pre-panel uncertainty costs one extra primary turn instead of N secondary turns. Safety is kept because the panel's first invocation is always a complete, independent review of the whole diff, and every configured reviewer must still approve the exact final head. Public audit comments and logs name the phase, exact head, primary, active owners, force-full state and source (operator, automatic, or none), and policy-neutral cumulative calls avoided. The policy is opt-in and does not change the default or the CI/merge gates. Use review-evaluation with frozen local artifacts to compare latency/cost against independent severity-weighted coverage before any proposal to change the default; measurements without verified provenance are reported as unavailable.

PR and plan reviewers are prompted to review exhaustively: every independently substantiated defect on the reviewed head or plan is reported in one response, defects in the same function or path are enumerated together, and a defect that genuinely masks what lies behind it is disclosed in the finding text and summary. review-evaluation measures that contract with an optional per-run review_contract label (first-finding-permitted or exhaustive) plus review_contract_provenance, and reports rounds, reviewer calls, and escaped defects per run side by side within each flow and scheduling policy, never pooled across policies. Real runs are frozen only into docs/evaluation/review_contract_runs.json; see review contract comparison.

Staged issue plan review

The same staged idea is available for issue plan review, selected independently of the PR policy and off by default:

agent-loop issue 123 --repo OWNER/REPO --plan-first \
  --plan-review-policy primary-then-panel \
  --primary-plan-reviewer codex \
  --reviewer codex --reviewer claude --reviewer gemini \
  --max-rounds 10

One primary plan reviewer works the plan to an approval of the exact candidate plan, then the secondary panel audits that byte-identical plan independently in a reviewer-only round with no planner turn. Every required reviewer must still approve the exact final plan. Because each phase advance costs a planning round, raise --max-rounds when enabling it. --plan-review-force-full authorizes the complete plan board and recovers the two ownership-ambiguity diagnostics; it cannot recover an unreadable planning history. --plan-primary-stall-rounds N (default 8, 0 disables) stops the run with a diagnostic once the primary has blocked N consecutive completed primary-phase rounds with no exact-plan approval, instead of spending the rest of --max-rounds; the panel is never convened automatically. Editing the issue title or body starts a fresh plan in a new planning scope by default, which leaves the stalled rounds behind. Under --plan-resume-keep-on-issue-edit the edit instead retires rounds reviewed against earlier text (a comment alone does not, and rounds recorded before issue-text tracking carry no digest, so an edit cannot retire them), and the one-shot --plan-reset-stall-streak durably retires the counted rounds; otherwise rerun with --plan-review-force-full or a higher threshold. A staged plan under plan-only or implement-one-shot can never satisfy the phased-delivery guard, so the run stops on the first such round for a human decision: use --plan-execution-mode decompose-only (the review-before-implementation mode for work that may be staged) or pass --plan-narrow-staged to have the planner narrow it to one deliverable once (independent remainder goes in the recorded-only typed deferred_work). Changing --plan-execution-mode on resume retires stall streaks recorded under the old mode; pre-change history needs --plan-reset-stall-streak. --plan-step-back-rounds K (default 2, 0 disables) acts earlier on the "new edge case every round" pattern: once the one-shot plan has crossed a plan-growth signal and the primary has blocked K consecutive rounds on new mandatory findings, the next planner turn must propose a materially simpler design (or a split, or under implement-one-shot a re-file-as-staged caveat) instead of patching the newest finding, and --plan-step-back-escalation-rounds M (default 2) stops for a human decision once the primary has blocked M rounds after it. A reached --plan-primary-stall-rounds stop is deferred while a step-back is pending or an episode is active, so a stalled history still gets its step-back, and the stall message says why the step-back did not apply otherwise. --plan-sweep-rounds K (default 2, 0 disables) is independent of the plan-growth gate: once the primary has blocked K consecutive primary-phase rounds with new mandatory findings, its next review is asked for one exhaustive sweep of the whole plan, siblings of the classes it already raised included. Repeats of unresolved items (re-emitted text included), future follow-ups and, on reviews after the primary's first, findings it tagged revision_introduced do not count; it never stops a run. --plan-sweep-reasoning-effort LEVEL (off by default) runs only that sweep turn at a higher Codex or Claude effort. Plan reviewers tag new mandatory findings with an optional provenance (revision_introduced or pre_existing) against a previous-plan baseline: the unified diff, a compact sentence-level diff, or the full previous reviewed plan as baseline data, in that order. The diff forms must fit max(12000, half the current plan), and every form must fit --plan-provenance-baseline-max-chars N (default 120000, 0 disables; otherwise the baseline is unavailable). history export reports the tag counts and the baseline forms; see plan sweep trigger and finding provenance. An in-flight run already past eight such rounds stops at its next round after upgrading. Omitting the flags keeps today's full-board planning behavior unchanged, and discussion-mode cycles always stay full-board. In the PR fix loop, --pr-step-back-rounds K (default 3, 0 disables) and --pr-step-back-line-window N (default 40) apply the same idea: once a reviewer has blocked K consecutive rounds with new findings clustered on one file span, the next coder turn must fix the whole class with one rule and a parametrized test, that reviewer sweeps the resulting head for every remaining instance, and a further clustered sibling stops for a human decision. --pr-evidence-stall-rounds K (default 2, 0 disables) stops for a human decision (exit 4) when K consecutive PR reviews have only evidence-only blockers (findings tagged with approved risk-matrix rows that stay unverified at the head), no failing check, and an unchanged set of unsatisfied rows. --pr-evidence-capture-attempts N (default 2, 0 disables) first converts a row whose evidence was only capture-limited (incomplete capture, unverified launch, unknown selectors; never an authoritative failure) for N consecutive coder attempts into an exact-head human evidence obligation answered at the final evidence freeze, and agent-loop pr N --pr-convert-evidence-rows ROW[,ROW...] converts named unsatisfied rows on demand before any agent runs. --pr-non-convergence-rounds K (default 3, 0 disables, independent of --pr-step-back-rounds) stops for a human decision (exit 4) before the next coder turn when the same tracked-reviewer items stayed blocking across K consecutive coder turns that each changed the head, wherever the findings are; the message lists each item with its attempts, the diff growth and the PR size, and the override options (0 or a larger K, a signed decision, a pushed change, or re-filing unattainable evidence as an exact-head evidence request). A clustered-sibling escalation stops first, and this stop wins over a fresh step-back turn. Evidence no agent session or runner can produce belongs only in exact_head_evidence_requests. A child-planning cycle inherits --plan-review-policy, --primary-plan-reviewer, --plan-primary-stall-rounds, --plan-step-back-rounds, --plan-step-back-escalation-rounds, --plan-sweep-rounds, --plan-sweep-reasoning-effort, and --plan-provenance-baseline-max-chars but never the parent's --plan-review-force-full override, --plan-reset-stall-streak, or scheduler state. review-evaluation reports planning runs in their own plan flow, separately from the PR rows, so staged and full-board planning can be compared on calls, tokens, latency, overlap, severity-weighted marginal findings, and escaped plan defects before any proposal to change the default. See staged issue plan review.

After a converted recovery capture at a code-approved head, PR review can request only semantic evidence acceptance from the configured primary or the captured rows' active requesting reviewers. These evidence-only verdicts preserve the independent code-approval gate and cannot open a panel, satisfy a code sweep or clear machine obligations. Operator force-full and unsafe states keep ordinary policy review. See the evidence-only review guide.

Planning also applies a plan-growth gate (#886). When a one-shot plan reaches a growth threshold, it cannot be approved until a revision restructures it as staged or carries a reviewed one_shot_growth_justification that names exactly the crossed signals:

Flag Default Signal
--plan-growth-gate {enforce,off} enforce Turns the gate on or off; scope-ledger preservation still applies when it is off
--plan-growth-max-chars N 120000 rendered-size: canonical plan characters (about twice the visible plan, since encoded records are included)
--plan-growth-max-scope-items N 12 scope-items: distinct scope items
--plan-growth-max-matrix-rows N 18 matrix-rows: risk-matrix rows
--plan-growth-max-revisions N 6 revision-count: planner candidates, counted only while the plan is at least half the size threshold

Reviewers may block with "this detail belongs in a child plan; restructure as staged". The approved-plan handoff record carries the gate's approval-time verdict, and handoff-backed resume re-validates against that verdict rather than today's thresholds; a handoff recorded before the verdict existed is accepted as legacy (#1074). See plan-growth gate.

Safety and Permissions

Agents can run commands and change code. Keep their normal permission prompts unless you understand and accept the repository and machine-level risk.

For a trusted local environment, this flag supplies each backend's permission bypass option:

agent-loop pr 456 --repo OWNER/REPO \
  --coder codex --reviewer claude \
  --dangerous-agent-permissions

The flag is intentionally explicit. It does not make agent output, fetched issue text, dependencies, shell commands, or generated code trustworthy.

Sandboxed role permissions

--agent-permissions {default,sandboxed,dangerous} selects the permission mode (default: default). default passes no permission arguments, and dangerous is the same as --dangerous-agent-permissions; combining that flag with another mode is an error. sandboxed builds role-scoped, CLI-enforced grants for Claude and Codex per invocation; see Running where GitHub GraphQL is refused, step 6, for a complete invocation, the per-role grants, and the requirements.

In sandboxed mode the only shell command a Claude non-coder may run is the read-only inspector:

agent-loop inspect --git=<absolute git> [--gh=<absolute gh>] git|gh ARGS

The grant runs it as <python> -I -m coding_review_agent_loop.cli inspect --git=<pinned git> --gh=<pinned gh> …, with the paths pinned at startup, and --git=/--gh= are accepted only once each in those leading positions. Everything else is checked against closed allowlists before git or gh runs:

  • Subcommands and options. git diff|log|show|status|rev-parse|ls-files with --stat, --name-only, --name-status, --numstat, --patch/-p, -U<n>/--unified=<n>, --format=/--pretty=, -n <k>/--max-count=<k>, --oneline, --porcelain, --short, --branch, and --abbrev-ref (each where it applies); and, only with --gh=, gh issue view|pr view|pr diff|pr checks with --repo, --comments, --json <fields>, and --name-only. Positional arguments may not start with - except after --. Abbreviations, unknown options, git grep, -O/--open-files-in-pager, --output, --ext-diff, --textconv, --no-index, --show-signature, git -c, gh api, --web, --jq, and --template are rejected.
  • Format placeholders. --format/--pretty accept oneline, short, medium, full, fuller, reference, or a format:/tformat: string whose placeholders are all among %H %h %T %t %P %p %an %ae %ad %ar %at %aI %cn %ce %cd %cr %ct %cI %s %b %B %d %D %n %%; every %G form, %(...), and %C... are rejected.
  • Environment. git and gh get an environment built from an empty mapping: HOME, USER, LOGNAME, LANG, LANGUAGE, LC_*, TZ, TERM, TMPDIR, XDG_{CONFIG,CACHE,DATA,STATE}_HOME, SSL_CERT_FILE, SSL_CERT_DIR, the proxy variables (either case), GH_TOKEN, GITHUB_TOKEN, GH_ENTERPRISE_TOKEN, GITHUB_ENTERPRISE_TOKEN, GH_HOST, GH_CONFIG_DIR, and AGENT_LOOP_GH_TRANSPORT, plus a PATH made of the pinned executables' directories and forced GIT_CONFIG_NOSYSTEM=1, GIT_CONFIG_GLOBAL=/dev/null, GIT_NO_LAZY_FETCH=1, GIT_OPTIONAL_LOCKS=0, GIT_TERMINAL_PROMPT=0, and cat pagers. No inherited GIT_* variable is ever passed.
  • Forced git config. git runs with --no-pager, --no-ext-diff, and --no-textconv, and with -c overrides that disable the pager, fsmonitor, external diff, signature display and every gpg program, all transports, hooks, submodule recursion, and Trace2 targets. status, diff, log, and show also get --ignore-submodules=all, so git never runs inside a submodule whose own config the gate does not scan. agent-loop's own pre- and post-turn workdir snapshot in sandboxed mode goes through the same gate and hardened git.
  • Repository-config gate. Before any git or gh subprocess, the inspector lists the checkout's config with git config --list --show-origin --show-scope --includes and refuses to run if any non-command key is outside core.{repositoryformatversion,filemode,bare=false,logallrefupdates, ignorecase,precomposeunicode,symlinks,autocrlf,eol,safecrlf,quotepath,abbrev}, extensions.{objectformat,worktreeconfig,refstorage}, remote.<name>.{url,pushurl,fetch,gh-resolved}, branch.<name>.{remote,merge,rebase}, and user.{name,email}. The error names the key and its origin, for example agent-loop inspect: rejected: repository git config key 'filter.lfs.clean' from file:.git/config is outside the inspect allowlist.

Other important boundaries:

  • Automatic merge is off unless --auto-merge is present.
  • Reviewer approval is not a substitute for project tests or human judgment.
  • --test-command adds a local gate before review and again before auto-merge. The finite watchdog defaults to 1,800 seconds and is configurable with --coder-test-command-timeout-seconds SECONDS.
  • --test-python PATH names an absolute interpreter with the repository's dev extras (pytest, pytest-xdist). Coders receive it as AGENT_LOOP_TEST_PYTHON and are pointed at it for broad and full-suite runs once a parent-side import check succeeds; nothing is ever installed into it.
  • The tool validates assigned workdirs and reported test locations, but agent CLIs may still consume substantial CPU, memory, network, and provider quota.
  • Raw subprocess logs and salvage artifacts can contain sensitive repository context. Protect access to the configured log directories and review their retention settings. Old subprocess capture directories in the subprocess-logs/<slug>/ layout (including an explicit --subprocess-log-dir in that layout) are pruned after 14 days by default; --subprocess-log-retention-days N (or AGENT_LOOP_SUBPROCESS_LOG_RETENTION_DAYS) changes that, and 0 or never disables pruning. Archive captures elsewhere for long-term storage; see Logs.

Read Workdirs, Agent permission flags, and Logs before unattended use.

Runtime-aware local test timeouts

Coder test commands may be run through the backend-neutral wrapper:

agent-loop run-tests --memory-dir /path/to/memory -- pytest tests/test_app.py -q

The --timeout-seconds value is the watchdog for that one whole command. When omitted, the wrapper uses the inherited run ceiling, or 1,800 seconds when run outside agent-loop. A positive finite override may be smaller than the ceiling; values above it are rejected before the child starts. Agent backends inherit the ceiling through AGENT_LOOP_CODER_TEST_TIMEOUT_CEILING_SECONDS.

Every invocation first prints a non-evidence notice naming its whole foreground budget (watchdog, host-capacity wait, overhead), so a coder whose shell limit is shorter knows to report a killed suite as not run. A <python> -m pytest launch in a repository that declares pytest-xdist gets an advisory when that interpreter cannot import xdist, and a command that reaches its watchdog gets a timeout advisory. Claude coder turns get Bash limits sized to the whole budget. See Running a long or full suite.

Suites that need long-lived helper processes (servers, workers, proxies) can declare them in a committed executable fixture script instead of wrapping the test command:

agent-loop run-tests --timeout-seconds 600 --fixture scripts/test-fixture.sh -- pytest tests/test_app.py -q

The test broker checks that the script is a tracked 100755 blob identical to HEAD in a clean tree, then runs <script> setup, the unchanged test command, and <script> teardown in one supervised scope with a shared AGENT_LOOP_FIXTURE_STATE_DIR. Only a run whose setup and teardown exit 0 and whose cleanup is confirmed (Linux, initial PID namespace, no hidepid) is citable. Cleanup flags any in-window process the run could own; on a shared host, an operator can declare other sessions' cgroup scopes with the orchestrator's repeatable --fixture-foreign-scope GLOB so their processes are reported as foreign diagnostics instead. --fixture needs at least 30 seconds and the broker; it never runs locally. See Multi-process fixtures.

Only an identical, passing, current-head rerun in an equivalent environment clears a recorded test failure; broader or different selections never do. A coder replays an unsuperseded failure exactly with agent-loop run-tests --rerun <receipt-id>: the test broker reuses the recorded command, working directory, fixture and environment from a private, invocation-scoped catalog, and nothing raw is shown or posted. Coder prompts list each open failure with its exact rerun handle and why the latest later pass did not supersede it. See Exact reruns of unsuperseded failures.

Every agent subprocess resolves this install's agent-loop: the orchestrator puts a private, import-pinned launcher first on each agent's PATH and exports its absolute path as AGENT_LOOP_EXECUTABLE, whatever other agent-loop the inherited PATH holds. Each brokered receipt records the client's tool commit; a receipt from a different or unidentified agent-loop is flagged with a run-tests-tool-mismatch or run-tests-tool-unidentified diagnostic, never rejected. See Agent-loop executable pin and receipt tool identity.

When agent memory is enabled, the wrapper records measured outcomes, elapsed time, the attempted cap, a privacy-preserving environment fingerprint, and cheap lockfile/configuration hashes in test-runtime.json. Recent successful runs produce advisory median/p95 recommendations with headroom; timeouts remain lower-bound evidence and are never treated as successful durations. Data is best-effort, retained to 20 samples per command/fingerprint cohort and 200 cohorts, and becomes stale after 30 days or when relevant inputs change. Cohorts also key on the worker count, so serial and parallel durations never blend. Each row also records launch_integrity: a run whose launch was not fully verified (for example an ad hoc shell script wrapping pytest, whose suite start is unknown) is the same run the evidence gate refuses, so it is stored as non-evidence. Only verified rows feed a timeout recommendation or are surfaced to coders as remembered commands; older rows without the field are treated as non-evidence too. New rows also carry wrapper_bootstrap, inner_exec and suite_start as diagnostics explaining that verdict; they are not evidence inputs, and older rows lack them. When an execution_refs selector is refused, the rejection names the failing launch condition(s) (or the failing outcome/provenance), the redacted command and the observation timestamp.

run-tests, containment-preflight and the loop flows accept --test-workers N, --test-worker-memory SIZE and --test-worker-enforcement {clamp,refuse,off}. Coder and repair agents receive a containment-derived budget in AGENT_LOOP_TEST_WORKERS; in the default clamp mode an injected pytest plugin lowers over-budget pytest-xdist requests (-n auto, -n 16, config or PYTEST_ADDOPTS) to that budget, refuse rejects them before any test runs, and off only advertises the budget. In clamp and refuse, a plain direct pytest in a repository that declares pytest-xdist support also runs with the budget as its default -n when xdist is installed; a command naming -n, --dist, --tx or -p no:xdist keeps its own choice, and a target without xdist still runs serially. Concurrent loops on one host share a host-wide worker pool, admitted exclusively: a test command asks for its full budget and, while another loop holds the pool, waits (bounded by AGENT_LOOP_TEST_WORKER_HOST_WAIT_SECONDS, default 1200 s, 0 disables waiting) instead of dividing it. After the bound it runs with the free workers, or one worker when none are free; host capacity never fails a command or reaches the coder as worker-budget-busy (only a second concurrent command in the same invocation does). Set AGENT_LOOP_TEST_WORKER_HOST_SHARING=off to opt out. See Parallel test-worker budget.

Remembered commands are suggestions only: agents must inspect the checkout and select focused tests. Framework per-test limits, the wrapper whole-command watchdog, and the backend whole-turn timeout are separate. The backend turn must leave headroom for analysis, edits, and reporting; split or shard healthy browser/integration matrices when that improves diagnosis and retry cost.

Before a managed wrapper is recommended, agent-loop runs a non-mutating run-tests --preflight probe. It checks only the running install's pinned agent-loop launcher, once per invocation, with a five-second watchdog (and no more than six distinct recognized inner launcher candidates per invocation). The inner probe uses the effective target environment, including ambient values merged with a partial overlay. The probe never runs remembered test arguments, installs dependencies, contacts a database, or executes an arbitrary shell. Recognized inner launchers receive the same bounded --version probe: direct pytest/py.test, exactly <python> -m pytest, and Node's built-in runner (node --test ..., with --test before the first positional argument and every other option on a fixed allow-list so print-and-exit options such as --version or --help and startup-code options such as --import/--require stay unrecognized, as does a non-empty NODE_OPTIONS; probed as node --version), and the Playwright CLI (playwright test ..., with test as the first argument and every other option on a fixed allow-list in --name=value form, so --list, --help, --version, zero-test-success flags (including --shard), --config/--tsconfig/global-setup options, custom reporters, and a non-empty NODE_OPTIONS or PW_TEST_REPORTER stay unrecognized; probed as playwright --version; npx [--no-install|--no] playwright test ... is recognized only when <cwd>/node_modules/.bin/playwright exists and is then probed and launched as that local binary, never letting npx resolve or download a package; npm run <script> [-- args], pnpm run <script> and yarn run <script>/yarn <script> are recognized when <cwd>/package.json statically resolves the script to one recognized command with no pre/post script, and then the resolved command is probed and launched, never the package manager). A standalone Node test script is citable only as node --test <file> and counts as one runner test that passes only on exit 0; other commands remain unknown rather than being judged from text or exit codes. The runtime result keeps independent wrapper_bootstrap, inner_exec, and suite_start states, so a missing executable or import is launcher health rather than a suite failure. Collection/configuration errors, failing tests, timeouts, and interruptions after startup remain ordinary suite evidence. Probe cleanup is process-tree aware: POSIX probes use a dedicated process group, and Windows probes use a kill-on-close Job Object. If Windows cannot provide that owning boundary, the probe is not launched and its result remains unknown rather than running an uncontained child. Python identity is checked without execution: the running interpreter and symlinks to it are trusted, as are byte-for-byte copies in a conventional pyvenv.cfg environment; name-only scripts or native binaries are unknown.

Schema-v1 test-runtime.json persistence adds a separate launcher_health collection. It records only bounded diagnostics, repository/checkout and environment identities, candidate identity, timestamp, and provenance; it does not store environment dumps or external paths (the exact canonical managed-wrapper path is retained for that wrapper). Health failures expire after 24 hours, are capped independently at eight records per identity and 100 identities, deduplicate, and are cleared immediately by a matching successful probe. Reinstalling a wrapper, changing its interpreter/dependencies, recreating a virtualenv, or changing the checkout/environment changes the identity and permits a fresh probe. Health is advisory: the configured test command is always shown, verified alternatives are scoped to the current checkout/environment, and direct agent-shell failures cannot be claimed as comprehensively captured.

CI and Merge

When a review round requires coder changes, agent-loop also checks for CI failures already reported on the reviewed commit and includes them with the reviewer findings. It does not wait for queued or running checks at this handoff. Missing checks and recognized runner-infrastructure stalls are not added as code defects. Managed CI still defers its final qualification until approval.

A blocking review is treated as CI-wait-only only when its findings and summary are unambiguously simple CI-status statements (or the summary is boilerplate). Mentioning a check name such as test is not sufficient. Mixed or ambiguous findings remain blocking; the tool must not erase code concerns to avoid a CI wait.

Use --auto-merge only when the repository's CI and branch protections are appropriate for unattended merging:

agent-loop pr 456 --repo OWNER/REPO --auto-merge

For ordinary CI, auto-merge waits for a reliable, non-empty check board on the current head. Without auto-merge, --watch-pending-ci can wait and report that an approved PR is merge-ready without merging. It is off by default; a run that stops on pending checks prints a hint naming it. Set the total watcher budget with --ci-timeout-seconds (default 2400) and its polling interval with --ci-poll-interval-seconds (default 30). This 40-minute ordinary and managed watch covers the default 30-minute shard budget with ten minutes overhead; queue delays can still exhaust it. Explicit shorter overrides such as --ci-timeout-seconds 1200 stay unchanged; longer consumer shard budgets need longer watches, for example --ci-timeout-seconds 4200 for 60-minute shards. Hosted job budgets and local watching are independent; watch expiry does not cancel hosted work. Managed v2 watching reports completed test jobs with failure or timed_out before sibling jobs finish, using complete jobs from the authenticated current attempt. Cancelled and infrastructure conclusions retain existing recovery. Before coder handoff, the original attachment and live job evidence are checked again, including on restart. Active audit records stay attached until the exact baseline finishes; historical clearance still needs a completed record and a later completed successful attempt. After approval, a test failure resumes the coder. A failure in plumbing jobs only (status publishing, routing, attestation), with every test check passed on a complete board, is re-run once and watched again. If plumbing fails again, the loop stops with an infrastructure message and the run URL instead of resuming the coder. A required status left pending after its run completed counts as such a plumbing failure. Add caller-defined plumbing job names with the repeatable --ci-plumbing-check NAME; see Plumbing failures and the rerun-once rule. GitHub runner stalls are bounded by --ci-queued-grace-seconds; see External CI infrastructure stalls.

When the token cannot read classic branch protection (an HTTP 403, as in sessions whose GitHub App lacks administration read), the required checks are unknown. A green board then counts as reliable only when GitHub reports a CLEAN merge state for the same head, which GitHub computes from the real protection. The merge still pins that head with --match-head-commit. If every observed check passed but the merge state stays BLOCKED, UNSTABLE, UNKNOWN, or unavailable for the bounded startup window (--ci-startup-timeout-seconds), the watch stops without merging and says why, instead of polling until --ci-timeout-seconds. Managed ordinary recovery keeps its PR draft while CI runs, and GitHub reports DRAFT rather than CLEAN for a draft. So recovery qualifies the green draft board for the same head and marks the PR ready. It merges only if GitHub then reports CLEAN within the same bounded window. Otherwise the PR stays ready and unmerged. If the recovery board is green but its merge state is neither a same-head DRAFT nor CLEAN (for example UNKNOWN) for that window, recovery stops early with the PR still a draft.

Managed exact-head CI

Managed CI is an advanced, repository-integrated workflow that suppresses expensive intermediate CI and qualifies one reviewed SHA at the end. Do not enable it from a README example alone. First read Managed exact-head CI and run the read-only preflight:

agent-loop managed-ci preflight \
  --repo OWNER/REPO \
  --base main \
  --trusted-actor LOGIN

For code already pushed without an open PR, the pre-creation form begins with agent-loop managed-pr --head BRANCH. On a waived base, creation verifies a durable creation audit before entering review. Resume with agent-loop pr N --managed-ci --managed-ci-trusted-actor LOGIN --allow-unprotected-managed-ci; current waivers and authenticated source/coder continuity are required. Historical audit-less drafts need the ordinary recovery described in the CLI guide. Managed issue recovery relies on a canonical issue handoff, explicit --managed-ci intent, documented draft/labeled and ready/unlabeled lifecycle states, immutable actor evidence, and preserved base provenance. Historical records are audit evidence only and never grant fresh authority.

Qualification and merge remain bound to the live head. The final merge uses --match-head-commit and merges only that qualified SHA. --watch-pending-ci and --no-watch-pending-ci do not alter managed exact-head qualification: a managed run always waits for final-ci/exact-head after approval, with or without --auto-merge, and applies the same plumbing rerun-once rule with a full, contract-verified rerun.

Documentation

The detailed guide is intentionally the source for protocol schemas, durable markers, repair passes, fallback ladders, CI provenance, and compatibility behavior. Those internals are not required for a first successful run.

Development

Install the development dependency and run the tests:

python -m pip install -e '.[dev]'
python -m pytest

Repository tests have a 600-second per-test signal timeout, including fixture setup and teardown. Both reusable CI workflows default to a 30-minute shard job ceiling and accept the optional numeric shard_timeout_minutes input. See the CI budget and consumer guidance for longer consumer budgets and the independent local CI watch.

Pytest's built-in faulthandler_timeout = 300 adds a SIGALRM-independent, non-terminating stack diagnostic after 300 seconds, before the existing 600-second signal failure limit and default 30-minute shard ceiling. Override it with -o faulthandler_timeout=<seconds>; coordinate shorter consumer shard budgets explicitly so the diagnostic has time to reach the log. It covers a hang in setup, call or teardown when no earlier phase of that test raised. Pytest's exception-interaction hook unconditionally cancels the diagnostic timer on ordinary phase exceptions: an early setup or call failure followed by a teardown hang may produce no dump. Nested in-process pytest sessions share the process-global faulthandler timer; an inner test failure can cancel the outer timer even with inner faulthandler_timeout = 0. Timer rearming and refactoring nested sessions are outside this diagnostic's scope. Stacks identify active Python test/fixture frames, without guaranteeing full parametrized node IDs. There is no attribution guarantee for startup/collection hangs, external subprocess internals, disabled faulthandler, runner loss or cancellation before the threshold. The diagnostic does not terminate the test or replace existing timeout and shard failure gates.

Use focused tests while changing one subsystem, for example:

python -m pytest tests/test_docs_guidance.py
python -m pytest tests/test_protocol.py
python -m pytest tests/test_pr_loop_ci_gate.py

Tests use fake subprocess runners and do not invoke real agent CLIs or GitHub. Browse the focused test modules in tests/ and see the component map and diagrams in ARCHITECTURE.md.

Related Tools

This project is a standalone local GitHub lifecycle orchestrator. Projects such as claude-review-loop, codex-review, and codex-plugin-cc integrate review or delegation into a particular agent host. Here, the orchestrator stays outside the agent hosts and can reverse coder/reviewer roles.

License

MIT

Explicit agent directories

--claude-dir, --codex-dir, --gemini-dir and --antigravity-dir must point at existing, clean git checkouts of the target repository; an empty or non-git directory is refused at startup with <option> is not a git checkout. Before every agent turn agent-loop verifies the checkout still matches what it last left there and fails closed, naming the observed branch and unexpected paths, if something else modified it.

For private directories left by completed or interrupted runs, see Removing stopped private directory trees. Release only a trusted tree after all its writers have stopped; deletion is a separate operator step.

Shared --worktree-link directory sources must be nonempty. Bounded structural health checks detect selected deletion at startup and around checked turns; damaged or stale sources require a trusted --worktree-setup CMD repair (for node_modules, --worktree-setup 'npm ci' in the named clone). Shared links still allow write-through; use --worktree-setup-pr-local for writable run isolation. See source integrity and recovery for migration, persistence and detection limits.

Pinned image transport conformance is an internal, opt-in developer check for #1794. Ordinary CI replays its fixtures without installed agent CLIs. See internal image reviewer transport for the explicit pytest option, pinned executable prerequisites, loopback-only harness and transport API. The experimental visual options below connect it to issue and PR runs; rollout remains deferred.

Opt-in visual defect review (experimental)

Issue and PR runs accept --review-images-cmd COMMAND with repeatable --review-images-paths GLOB and --review-images-runtime-grant /absolute/path. No path globs means no image activity. --review-images-seat SEAT selects one configured image-capable reviewer; omission requires an explicit primary. Unsupported executable/model/fallback combinations are refused without fallback. See the CLI guide for grants, limits and failure semantics. Operator measurement and rollout remain gated by #1796.

Visual assessment dispatch is durable per PR head: a verified intent precedes launch, and restart never retries a spent head. New matching heads are captured freshly; unchanged content may reuse the latest compatible authenticated result while preserving findings and granting no code approval or new coder turn. See visual review recovery.

Screenshot requests can opt into requester-owned machine coverage. An available current-head report supplies manifest image IDs; only the requesting reviewer’s explicit bound acceptance clears a typed request. Legacy human-only requests and unrelated obligations remain pending. Text-only coverage has a separate one-attempt-per-seat/head budget; it cannot approve code or trigger another image assessment. See requester coverage. Visual image assessment and requester coverage appear separately in usage summaries.

Required work that can only happen after merge can be recorded as a post-merge obligation with an owner and an existing same-repository tracking issue. Scheduling survives head changes without weakening current-head review or CI. After a manual merge or interrupted tracking publication, use agent-loop pr <number> --repo OWNER/REPO --reconcile-post-merge-obligations (add --dry-run to inspect without writing). See required post-merge obligations for reviewer declarations, verified operator directives and recovery.

Within coder sessions, use "${AGENT_LOOP_EXECUTABLE:-agent-loop}" run-tests -- <test command> to keep receipts bound to the running orchestrator release across shell PATH or release-symlink changes. If launcher installation fails, the command falls back to the unpinned inherited PATH and the existing warning remains visible. See the CLI guide for signed requirement routing and exact-head human evidence.

About

Local Claude/Codex PR review loop using existing CLI subscriptions instead of model API keys

Topics

Resources

Stars

12 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages