Blocking the commit the agent shouldn't make

The commit you didn't ask for

The problem this aims to address is that even when the turn goes well, the commit after it can be sth you didn't ask for. It lands on main. Or it carries .env along with the four files you wanted. Or the message is wip and the diff is 200 lines across three unrelated concerns. Or — the one that stings — it goes in with --no-verify, because the pre-commit hook complained and the agent read that as an obstacle rather than an instruction.

The obvious objection first: this repo already has a pre-commit hook, and CI runs on every push. Both true, and neither one is upstream of the decision. CI kicks off after there's a commit, which means after it's already on the branch; and the pre-commit hook is skippable by design — that's what its own flag is for.

So what we want is a pre-tool hook that reads the git command as text before it runs, and decides. Not a general shell-command policer: one narrow gate on the four properties of a commit or push you actually mind, with a refusal written so the model does the right thing next instead of trying a different spelling.

What --no-verify does to the hook you already have

Worth watching once, because it changes where you put the gate. A disposable repo with a real .git/hooks/pre-commit that fails, on git 2.39.5:

$ git commit -m first
pre-commit hook ran
                          # refused — no commit object created

$ git commit --no-verify -m first
 2 files changed, 175 insertions(+)
$ git log --oneline
e1bbe38 first             # the hook never ran; the commit exists

$ git -c core.hooksPath=/dev/null commit -m second
[main d24c9f5] second     # the hook never ran either

Two bypasses, and only one of them is a flag. core.hooksPath points git at a different hooks directory for a single invocation, so there's nothing left for pre-commit to defend. A repo's own hooks can't protect themselves; sth further up has to.

That sth is the harness's pre-tool event, which sees the command as a string before a process starts — while --no-verify is still an argument you can read, rather than a decision git has already acted on.

Four properties, not a list of bad commands

So the setup we want is a thing that runs before every command, reads the command itself as text, and then decides whether it's okay to run it. What we don't want is a list of forbidden commands — git commit has enough spellings to lose that game, and Kimi Code's own hooks documentation says the quiet part out loud about its rm -rf example: it "is not a production-grade security parser. Real scenarios are better served by whitelists, or a dedicated shell parser to handle quoting, variable expansion, and multi-command sequences."

So we gate properties of one specific action instead. It's not okay when it's a commit or a push and it's any of these:

• the branch is main or master — the cheapest of the four to enforce and the most common to trip,

• sth in it turns the repo's own checks off: --no-verify, the clustered -n, or -c core.hooksPath=…,

• there's a file that never gets committed here (.env, *.pem, a keyfile) — and we mean what's actually staged, plus what this command is about to stage,

• it's a force push without a lease, because --force-with-lease fails instead of overwriting a commit somebody else pushed and plain --force doesn't.

Everything else goes through, on purpose. A guard that fires on things you didn't mean gets deleted within a week and then you have nothing — while we were working on this one we watched an overly broad version refuse git commit --help, because it pattern-matched a word anywhere in the command string instead of looking at what the command does.

The guard

So… the guard itself is one file, scripts/commit-guard.py, and we keep it in the repo under scripts/ rather than in any harness's config directory — that way six harnesses can point at one script, and it gets reviewed like everything else in there. No dependencies; the two lists at the top are the whole config:

PROTECTED_BRANCHES = ("main", "master")
NEVER_COMMIT = (".env", ".env.*", "*.pem", "id_rsa", "*.p12")

And there are four things in it worth explaining. Each of them is a consequence of a bug we hit first:

• It finds the command in four different places. The pre-tool payload arrives as JSON on stdin — in the five harnesses whose docs name a transport at all; GitHub's reference only says the payload reaches the handler. And every one of them nests the shell command somewhere else: tool_input.command on Claude Code, Codex, Gemini CLI and Kimi Code, toolArgs.command on Copilot's camelCase events, a top-level command on Cursor's beforeShellExecution, and toolCall.args.CommandLine on Antigravity. Four lookups, one script. Copilot's is the one to check rather than trust: its reference types toolArgs as unknown and never names the sub-key.

• It leaves early and often. The first thing it does is return if there's no git in the command, or no commit/push among the segments — exit 0 before doing anything expensive, because this code sits on the path of every shell call the agent makes.

• It knows -n is two different flags. -n is short for --no-verify on commit (git help commit) and for --dry-run on push (git help push), so if we treated it as a bypass on push we'd be blocking dry runs for no reason. Short flags also cluster, so git commit -nm "wip" has to trip it too.

• It splits compound commands. git add -A && git commit -m wip is two invocations in one string, and at that point the hook can't see anything the add did yet — so the guard also asks what that add is about to stage. -A and . include untracked files while -u and commit -a affect only tracked ones, which is why an untracked .env doesn't trip git commit -am.

If the guard decides it's not a good command, it refuses by writing the reason to stderr and returning 2 as the exit code. All six harnesses treat that pair as a refusal, so the script speaks it and nothing else. What each one then does with the text varies — mostly it becomes the model's next input, on Copilot it doesn't — so the wording is an instruction with a way forward rather than a log line, and each harness section below says what happens to it.

Run the cases before you wire it up

Let's do some exercise before we get to the integration. The guard is a script that reads JSON on stdin, so you can run it against every single rule without a harness, without calling the model and without spending a token. Here's a fixture and a check that pipes one in and prints the exit code together with the reason:

fixture() { printf '{"cwd":"%s","tool_input":{"command":"%s"}}' "$PWD" "$1"; }
check() { reason=$(fixture "$1" | python3 scripts/commit-guard.py 2>&1); printf '[exit %d] %-34s %s\n' $? "$1" "$reason"; }

check 'npm test'
check 'git commit -m wip'
check 'git commit --no-verify -m wip'
check 'git commit -nm wip'
check 'git push --force origin HEAD'
check 'git push --force-with-lease origin HEAD'
check 'git add -A && git commit -m wip'

On a topic branch with an untracked .env in the tree, that prints:

[exit 0] npm test
[exit 0] git commit -m wip
[exit 2] git commit --no-verify -m wip      Drop `--no-verify` and run the commit again. It turns off the checks this repo runs from its own git hooks — if one of them fails, fix what it reports.
[exit 2] git commit -nm wip                 Drop `-n` and run the commit again. It turns off the checks this repo runs from its own git hooks — if one of them fails, fix what it reports.
[exit 2] git push --force origin HEAD       Use `git push --force-with-lease` instead of `--force`, so the push fails instead of overwriting a commit somebody else pushed.
[exit 0] git push --force-with-lease origin HEAD
[exit 2] git add -A && git commit -m wip    `.env` is not committed to this repo. Run `git restore --staged .env`, add it to .gitignore, and commit the rest.

Run it on main and the second case — the plain commit — flips:

[exit 2] git commit -m wip                  main is protected here. Run `git switch -c <topic-branch>` first and commit there, then open a pull request when the work is ready to review.

Read those reasons the way the model will read them, because that's all it gets. And do this exercise before the integration rather than after it: if you wire it up first and see exit 0 on every turn, you have no way to tell a guard that agrees with everything from a guard that was never loaded.

Watch it refuse a real turn

Wiring done, spend one turn confirming it. Ask for the exact command rather than describing a goal, because what you want here is the refusal, not a negotiation:

Run exactly this command, nothing else, then tell me the outcome: git commit --no-verify -am wip

On Claude Code 2.1.220 the tool result came back as an error, verbatim:

PreToolUse:Bash hook error: [python3 $CLAUDE_PROJECT_DIR/scripts/commit-guard.py]: Drop
`--no-verify` and run the commit again. It turns off the checks this repo runs from its own
git hooks — if one of them fails, fix what it reports.

The command never ran, and the reply was "the command didn't run … re-running it as-is will just fail the same way. Want me to run git commit -am wip (hooks enabled) instead?" On Cursor 2026.07.23 the same guard on beforeShellExecution came back with the same refusal text, reported more briefly — "The command did not run … No commit was created." Neither of them went looking for a way around it, which is what the wording is for.

If you get silence instead, almost always it means the hook isn't loaded rather than that the logic is wrong. Swap the hook's command for this:

cat > /tmp/hook-payload.json

…then run one turn and take a look at the file. If it's not there, the hook isn't loaded; if it is, you can see exactly which key holds the command.

One more thing we've seen, once, and it's worth knowing it's possible. Asked to "stage everything and commit" on main, the agent read scripts/commit-guard.py on its way past, then gitignored the .env, branched off main and committed there — without a single refusal firing. So a guard the agent can read is a piece of documentation for it before it's a gate.

What it costs on every other call

The last thing worth showing is what the guard costs. Measured on the machine this was written on, 20 runs each: 34 ms per call on the early-exit path, and 77 ms when the command really is a commit and the guard shells out to git. The 34 ms is the figure to focus on, because it's what every shell call in the session pays — which is the argument for the early return despite it being the less readable shape, and the argument against matching this hook on every tool instead of the shell one.

What it doesn't stop

We want to finish by saying a few words about what isn't covered:

• it's not a security measure. Hooks fail open almost everywhere, so a crash, a timeout or a session started with hooks disabled and the gate simply isn't there. Permissions, sandboxing and branch protection on the server are the layers that work against an adversary; this one works against a mistake.

• it only sees the shell tool. If you have an MCP git server, a commit that goes through it never reaches the guard at all. Gate that tool too, or don't install it.

• it reads a string, not a shell. python3 deploy.py is a shell call the guard inspects and waves through, because the word git isn't in it — whatever the script does next is invisible. Same for aliases, variable expansion, and operators with no spaces around them (git add -A&&git commit): all of it is text, so all of it can be walked around by anyone who wants to. Agents mostly aren't trying to.

• local checks are not the repo's rules. Protected branches belong on the server as well; this just stops the commit from landing on main in the first place, which is the cheaper point of interception.

These are the four rules we came up with, but it's a starting point rather than a standard. The one worth adding next is whatever your team has already had to undo by hand.