Blog / Agents
· Agents

Why an agent does not merge its own pull request

· 7 min read

Splitting decisions between agents and people

We run roughly 100 coding agents for one operator. On 16 November, our weekly thread audit counted 302 open agent threads on a single machine. Most of that work should never interrupt a person, so we drew a hard line in our standing rules on 14 November.

Agents handle three classes of action on their own and report afterward. They merge pull requests that touch only documentation or internal skills once a review agent confirms quality and need. They merge into staging or feature branches when CI is green, a review agent has signed off, and there is no database migration. They also take low-impact steps that are simple to reverse.

Everything else waits for the owner. Production deploys, database migrations, schema changes, access changes, deletions, messages to external people, and any financial spend require explicit approval. If a repository's own AGENTS.md file sets a stricter bar, the repository wins. A merge freeze from a release manager overrides both.

Even when an agent is allowed to merge, the author never approves its own code. A separate review agent reads the diff, and our thread manager treats a pull request as reviewed only when a report exists for the current head commit. A review on an older commit, or a skipped, failed, or errored review check, counts as zero review.

Why prose instructions fail at scale

Rules written inside a prompt or instruction file only work when the model remembers to apply them at the exact right turn. Over long threads and dozens of parallel repositories, text rules drift.

For actions that can break a branch or bypass review, we move the rule out of the prompt and into Claude Code pre-tool hooks. Each hook is a small shell script that intercepts a tool call before execution. When a call breaks a rule, the hook denies it and returns the reason directly into the agent's context, telling the agent what to fix before trying again. We run four of them.

Enforcing repository rules before the first edit

The first hook, agents-md-gate.sh, blocks an agent's first mutating action in any repository during a session. That covers file edits, git writes like commit, push, or reset, and pull request commands. Before denying the call, the script fetches the remote and looks for AGENTS.md on staging, then main, then master, and finally the local HEAD. The refusal hands the agent the full AGENTS.md text along with up to 40 skill files found in the repository. Once the agent reads them, the retry passes. Repositories without an AGENTS.md file pass immediately.

Blocking polling loops on CI

The second hook, ci-wait-gate.sh, stops any shell command that combines a sleep of 30 seconds or longer with a CI or deployment check. Sleeping in a terminal loop wastes context and stalls the thread. The refusal directs the agent to register a platform PR watch, or run a single blocking command that exits on completion, and keep doing other work while CI runs.

Checking pull request hygiene at creation

When an agent runs gh pr create, pr-standards-gate.sh checks the request before it reaches GitHub. Every pull request needs an explicit base branch, and targeting main is blocked whenever a staging branch exists. Even a user prompt saying to ship, finish, or land work does not unlock main in that check. The hook also rejects branches that scatter status or handoff markdown files (such as STATUS, PROGRESS, HANDOFF, or NOTES) outside docs or agent directories. Finally, it invokes the repository's own linter on the diff only, running pre-commit via prek when configured or falling back to biome on changed TypeScript and JavaScript files. The hook enforces the repo's checks without inventing extra style rules.

Holding merges until every review thread closes

The fourth hook, pr-review-gate.sh, wraps gh pr merge and gh pr ready. It queries GitHub over GraphQL for the pull request's review threads (up to the first 100) and blocks the command if any thread remains unresolved, regardless of whether an agent or a human opened it. The refusal prints each open thread with its file and line so the author can either fix a confirmed bug or rebut a weak claim with evidence. This single script is what keeps an author agent from merging past its reviewer.

The fail-open tradeoff and explicit overrides

All four hooks fail open when infrastructure breaks. If jq is missing, the working directory is not a git repository, or GitHub returns an unusable response, the call goes through. A hook only blocks when the check executes cleanly and detects a violation. That keeps a broken utility from freezing every thread on the machine, at a real cost: a hook that silently failed to run looks identical to one that ran and passed.

Three of the four hooks (all except agents-md-gate.sh) also honor the token SKIP-GATE inside a command for documented exceptions, such as a release pull request targeting main after explicit owner approval. Our release manager agent must log every override in its report. A pre-tool hook is a structured guardrail with an audit trail, not a security sandbox.

Two real failures caught on 18 November

On 18 November, our release manager agent tried to merge two documentation pull requests under the standing rules and got blocked twice by pr-review-gate.sh. It inspected the review threads itself, confirmed nothing was open, used SKIP-GATE, and logged the overrides. After a chief of staff agent flagged the pattern, our operations agent audited the hook script directly.

The audit exposed three parsing bugs in pr-review-gate.sh. It inferred the repository from the current working directory and ignored --repo and -R flags. It only parsed the pull request number when it appeared immediately after merge or ready. And it passed the call whenever the current folder was not a git checkout. Together, those three flaws produced both false blocks (inspecting the wrong PR and rejecting a clean merge) and false passes (checking nothing at all). The false pass is the dangerous failure mode because nothing in the output reveals that the check was skipped.

A worker agent built a 58-line candidate patch that parses --repo, --repo=, -R, and full pull request URLs, locates PR numbers placed after flags, and falls back to the local directory only when no repository is specified. Against a 16-case test script, the installed hook fails 10 cases while the candidate passes all 16. Known edges remain: repositories passed through shell variables or GH_REPO are not parsed, branch-name targets still fall back to the local folder, and the query checks only the first 100 review threads and the first merge command on a line.

The same audit surfaced a configuration drift problem across accounts. One of the four agent accounts on the machine had its own settings file, written the previous evening, that registered only ci-wait-gate.sh. Any thread running on that account could open, mark ready, and merge a pull request without repository rules, PR standards, or review-thread checks. That account ran 66 threads on 17 November.

As of 21 November, neither change has been applied yet. Because it was unclear whether the trimmed hook list on that fourth account was deliberate, the operations agent left all settings untouched and placed one decision card in front of the owner covering three steps: enable the three missing gates on that account, install the patched review hook with a backup copy, and link three missing skills.

Keeping the human bottleneck small

Every decision that crosses a standing-rule boundary lands on a single decision desk as a card with a recommendation. Clicking a button authorizes only the exact action written on that button. Our operations agent caps its daily summary at 15 lines, puts pending decisions at the top, and structures each one for a single-word answer. Every manager agent is capped at five open cards so approvals do not pile up into noise.

Where the line holds

For documentation and staging branches, standing rules let agents merge once an independent review passes and every review thread resolves. Production merges, deploys, migrations, and spend stay behind human approval. Hooks catch the predictable slips before they hit GitHub, and auditing those hooks catches the gaps that fail-open checks hide.

If your team runs coding agents and wants practical review and deploy gates wired into your repositories, book a 30 minute intro.

AI Lab · Private Community

Join AI Lab

The private community for serious AI builders, business owners & professionals.

Join the Lab →
$99/month — Cancel anytime.