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.
- 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.
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.
- Python 3.12 or newer.
- Git and GitHub CLI with
gh auth statussucceeding. - 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.
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:
-
Set the repository Actions variable to the trusted actor:
gh variable set AGENT_LOOP_MANAGED_ACTOR --repo wwind123/coding-review-agent-loop --body wwind123. -
Authenticate
ghaswwind123, then run the read-only preflight:agent-loop managed-ci preflight --repo wwind123/coding-review-agent-loop --base main --trusted-actor wwind123. -
While
mainremains unprotected, pass--managed-ci-trusted-actor wwind123 --allow-unprotected-managed-cion 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.
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.
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 --helpCheck the CLIs for your chosen roles before the first run:
gh auth status
claude --version
codex --versionSubstitute agy --version or gemini --version when using those backends.
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 REST5. 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. gitandghfound first onPATHmust also live outside every checkout; they are pinned by absolute path for the run, and checkout directories must not precede them onPATH. The inspector runs only those pinned binaries, so agitorghplanted in a checkout later is never executed. Upgrading git or gh during a run blocks read-only turns until the run is restarted. WithoutghonPATH, gh inspection is unavailable. When the pinnedghis the step-3 shim, the inspector's gh subcommands work only if the realghsits in the same directory as the pinnedgit, because the shim finds the realghon the inspector's constructedPATH.TMPDIRmust 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 mode0300, 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 mode700whatever your umask; a component left group-writable by an older release is refused, and the refusal lists every such component with a singlechmod go-wcommand 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
.gitread-only even with--add-dir, sogit commitfails. 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
defaultordangerouspermissions. Antigravity has no CLI-enforced read-only grant.agy --sandboxrestricts only its terminal, so its file-writing tool can still write the checkout and a baregitthere 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 inspectruns only the pinned git and gh with a closed environment allowlist and aPATHbuilt from their directories (inheritedGIT_*variables, including every trace variable, andGH_DEBUGnever 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_ACTORActions variable is refused by the proxy. When gh reports a strictHTTP 403for that read,--managed-ci-trusted-actorstands in for the variable. The run logs that the actor is asserted and unverified locally, andmanaged-ci preflightprints it asasserted. This fails safe because the workflow still enforces the realvars.AGENT_LOOP_MANAGED_ACTORserver-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 a404or 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-headenforcement, protection is classified asunreadable, which is distinct fromvoluntary. 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 a403, 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 strict404/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-protectionThis 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 codexIssue 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 codexWithout --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.
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-approvalIf 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.
agent-loop task "Add a health-check endpoint" \
--repo OWNER/REPO \
--coder codex \
--reviewer claude| 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.
- The coder implements the issue or updates the existing PR.
- Every configured reviewer reviews the same PR head.
- Blocking findings return to the coder as an explicit work ledger.
- The updated head is reviewed again.
- 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-parallelAgent-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 singleUserKnownHostsFile, andPortonly when the origin URL has no port.Useris ignored, because the origin pins thegituser.Matchblocks,Include,ProxyCommand,ProxyJump,LocalCommand,KnownHostsCommandand every other directive are ignored.- Only plain values are used: after
~/expansion (to$HOME) and symlink resolution, a value must contain onlyA-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.
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 .venvNode:
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 -cin 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 slownpm ciorpip installis 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-linksource 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
/tmpand 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-unchangedorskip-worktree, stops the run without overwriting it. Untracked and ignored content there is operator-trusted. - An untracked file at a
--worktree-setup-keypath 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 installwritespackage-lock.jsonwhen 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 examplenode_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:
/.venvor/node_modules, without a trailing slash. - When neither
--worktree-setupnor--worktree-linkis given and the base tree hasrequirements*.txt,pyproject.toml,setup.py,Pipfile.lock,poetry.lock,uv.lock,package-lock.json,yarn.lockorpnpm-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-linkand--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-localor an explicit--<agent>-dircheckout. 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 printsagent-loop managed-pr --head <branch> --expected-closing-issue Nas the resume and the manualgit -C <store> worktree remove --force <run-worktree>cleanup; agent-loop never removes that worktree itself.
--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-keyentries 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 logsPR-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-timeouttoo. - 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.
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.
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.
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.mdnames a different root.--architecture-detail-dir DIR(repeatable) names the directories whose root-linked.mdfiles are members. Giving it replaces the defaultdocs/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) anddocs/adr/.--no-default-architecture-excludesdrops the defaults. An adr-tools or MADR repository that links its ADRs from the root needs no flag fordoc/adr/ordocs/adr/; for MADR'sdocs/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.
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.
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.
- Each run claims every agent checkout it uses for its duration (a
flocklock 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}-dircheckouts behave as before. Other repo-scoped local state (the memory cache, subprocess-log root) is still shared.--allow-shared-dironly lets agents within one run share a checkout; it never lets a second run use a claimed one.--review-parallelis 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 example6h; see Waiting for a quota reset). - Default agent checkouts live under the system temporary directory (
/tmpon Linux) and may disappear after a reboot or system cleanup. Configure explicit workdirs for long-lived installations.
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.
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:
- No implementation handoff yet. Rerun the same
--plan-firstcommand. 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. - 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 ReviewerThe 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.
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
planrecord (issueset,pr_numbernull) on the issue being planned. Post aprrecord (pr_numberset,issuenull) on the PR itself, including standaloneagent-loop prruns. A record on the wrong surface, a record naming another issue or PR, and aprrecord on the owning issue all stop for a human decision. - Named PR seats. Use
reasonseat-unavailablewhen one or more named seats independently exhaust their model chains; list all affected seats in one amendment. Other seats on their backends remain required. Usebackend-unavailablefor 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, usemixed-unavailable. Its rationale must start withshared_outage_backends=backend1,backend2on 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-reviewersplan 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
```jsonfence 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.
policyandprimary_reviewermust match the persisted contract. The primary cannot be removed, and aprimary-then-panelboard 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'soriginal_required_reviewersequal 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.
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 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 codexThe 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 AGENTfor a structured consensus/disagreement agenda.--discuss-research auto|required|nonefor current external facts.--discuss-parallelfor concurrent independent positions.--materialize-split-issuesto 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.
| 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.
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.
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 mediumClaude 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.
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-intermediateThe 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.
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 geminiThe 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.
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 10One 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.
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-permissionsThe flag is intentionally explicit. It does not make agent output, fetched issue text, dependencies, shell commands, or generated code trustworthy.
--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-fileswith--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 checkswith--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--templateare rejected. - Format placeholders.
--format/--prettyacceptoneline,short,medium,full,fuller,reference, or aformat:/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%Gform,%(...), 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, andAGENT_LOOP_GH_TRANSPORT, plus aPATHmade of the pinned executables' directories and forcedGIT_CONFIG_NOSYSTEM=1,GIT_CONFIG_GLOBAL=/dev/null,GIT_NO_LAZY_FETCH=1,GIT_OPTIONAL_LOCKS=0,GIT_TERMINAL_PROMPT=0, andcatpagers. No inheritedGIT_*variable is ever passed. - Forced git config. git runs with
--no-pager,--no-ext-diff, and--no-textconv, and with-coverrides that disable the pager, fsmonitor, external diff, signature display and every gpg program, all transports, hooks, submodule recursion, and Trace2 targets.status,diff,log, andshowalso 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 --includesand refuses to run if any non-command key is outsidecore.{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}, anduser.{name,email}. The error names the key and its origin, for exampleagent-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-mergeis present. - Reviewer approval is not a substitute for project tests or human judgment.
--test-commandadds 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 PATHnames an absolute interpreter with the repository's dev extras (pytest, pytest-xdist). Coders receive it asAGENT_LOOP_TEST_PYTHONand 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-dirin that layout) are pruned after 14 days by default;--subprocess-log-retention-days N(orAGENT_LOOP_SUBPROCESS_LOG_RETENTION_DAYS) changes that, and0orneverdisables pruning. Archive captures elsewhere for long-term storage; see Logs.
Read Workdirs, Agent permission flags, and Logs before unattended use.
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 -qThe --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 -qThe 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.
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-mergeFor 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 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 LOGINFor 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.
ARCHITECTURE.md: canonical component map, execution flows, state, and trust boundaries.agent-loop --help: full command and option reference.docs/local_agent_loop.md: detailed lifecycle, protocol, recovery, CI, memory, and safety reference.
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.
Install the development dependency and run the tests:
python -m pip install -e '.[dev]'
python -m pytestRepository 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.pyTests 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.
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.
--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.
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.