Today I Learned

Two things went wrong here. First, the agent’s command. grep, a tool that finds lines containing some text, only answers “is the line there?”. The line was there. It just said preflight_exit=1, so the commit went ahead. The agent spotted that twelve seconds later. Second, my guard. It existed for exactly this moment, and it let the commit through without a word. That’s the part this post is about. The bad commit itself was harmless: one line a formatter wanted rearranged. A guard that fails silently is not.

Try it yourself, no guard needed. With four apostrophes, shlex splits the command into words. With three, it stops with an error.

python3 - <<'PY'
import shlex
even = "git commit -F - <<'EOF'\nCI's and the job's\nEOF"
odd = "git commit -F - <<'EOF'\nit's done\nEOF"
print(shlex.split(even)[:2])  # ['git', 'commit']
shlex.split(odd)  # ValueError: No closing quotation
PY

“When a guard can’t tell, it must block.”The moral of incident No. 004

Here’s the version I use now, in five steps: a script that fingerprints your files, two lines that save the fingerprint when preflight passes, the guard that compares the saved fingerprint with a fresh one, the setting that tells Claude Code to run the guard, and four tests. If you only want the rule, you can skip the code.

1. Take a fingerprint of your files

   Preflight and the guard must agree on which files were checked. This script turns your last commit, your changes and any new files into one short code, the fingerprint. Change any file and the fingerprint changes. The || echo gone line keeps it going if a temporary file disappears while it runs. Save it as scripts/tree-hash.sh and make it runnable with chmod +x.

   #!/usr/bin/env bash
   # One hash for HEAD, the diff and untracked files.
   set -euo pipefail
   ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
   cd "$ROOT"
   {
     git rev-parse HEAD 2>/dev/null || echo no-head
     git diff HEAD 2>/dev/null || git diff --cached
     git ls-files -o --exclude-standard | sort |
       while IFS= read -r f; do
         # A file can vanish mid-run: hash it as
         # "gone" instead of dying under set -e.
         printf '%s ' "$f"
         { shasum -a 256 "$f" 2>/dev/null |
             cut -d' ' -f1; } || echo gone
       done
   } | shasum -a 256 | cut -d' ' -f1

2. Save the fingerprint when preflight passes

   Add these lines at the very end of preflight. If any check failed, preflight stops before it gets here, so nothing is saved. The guard’s messages call the saved fingerprint the stamp.

   # The last lines of scripts/preflight.sh
   "$ROOT/scripts/tree-hash.sh" > "$ROOT/.git/preflight-pass"
   echo "preflight passed: safe to commit"

3. Write the guard: when unsure, it’s a commit

   First, if the command doesn’t contain the word commit, allow it. Then read it with shlex: if it’s clearly not a git commit, allow it, and if shlex can’t read it, treat it as a commit. Last, compare the saved fingerprint with a fresh one, and block with a reason if anything is missing, fails or doesn’t match. Save it as scripts/hooks/commit-guard.sh and make it runnable with chmod +x.

   It protects against mistakes, not against someone trying to sneak past. A commit hidden inside bash -c "…" is just text to it.

   #!/usr/bin/env bash
   # Claude Code PreToolUse hook, matcher "Bash".
   # Blocks `git commit` until preflight passed for
   # this exact tree. Exit 2 blocks; ANY other exit
   # allows, so every unproven path ends in block().
   set -uo pipefail
   ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
   
   block() {
     echo "BLOCKED: $1" >&2
     echo "Run ./scripts/preflight.sh, then commit." >&2
     exit 2
   }
   
   input="$(cat)"
   
   # 1. Cheap filter: only a sure "no" exits 0.
   case "$input" in *commit*) ;; *) exit 0 ;; esac
   
   # 2. Is it a commit? Only a clear "other" escapes.
   kind="$(printf '%s' "$input" | python3 -c '
   import json, shlex, sys
   
   def kind(cmd):
       try:
           w = shlex.split(cmd)
       except ValueError:  # unbalanced quotes
           return "commit"
       opt = {"-C", "-c", "--git-dir", "--work-tree"}
       for i, t in enumerate(w):
           if t.rsplit("/", 1)[-1] != "git":
               continue
           j = i + 1
           while j < len(w) and w[j].startswith("-"):
               j += 2 if w[j] in opt else 1
           if j < len(w) and w[j] == "commit":
               return "commit"
       return "other"
   
   print(kind(json.load(sys.stdin)["tool_input"]["command"]))
   ')"
   [ "$kind" = "other" ] && exit 0
   
   # 3. In scope now. Every failure below blocks.
   stamp="$ROOT/.git/preflight-pass"
   [ -s "$stamp" ] || block "no preflight stamp"
   now="$("$ROOT/scripts/tree-hash.sh")" \
     || block "could not hash the working tree"
   [ -n "$now" ] || block "empty tree hash"
   [ "$now" = "$(cat "$stamp")" ] \
     || block "preflight has not passed for this tree"
   exit 0

4. Tell Claude Code to run it

   Add this to .claude/settings.json in your repo. PreToolUse means “before the agent uses a tool”, and "matcher": "Bash" narrows that to shell commands, which is how the agent commits. "onFailure": "block" (Claude Code v2.1.295 or later) also blocks when the guard itself crashes, won’t start or runs too long. A broken guard then blocks every command until you fix it. That’s on purpose: you’ll notice.

   {
     "hooks": {
       "PreToolUse": [
         {
           "matcher": "Bash",
           "hooks": [
             {
               "type": "command",
               "command": "\"$CLAUDE_PROJECT_DIR\"/scripts/hooks/commit-guard.sh",
               "onFailure": "block"
             }
           ]
         }
       ]
     }
   }

5. Prove it blocks: try to break it

   Run this from your repo root. It works in a temporary folder, so your real files aren’t touched. Each test prints the guard’s exit code. You want 0 for the first test and 2 for the other three. The third test is the shape that got past my old guard. The fourth uses a fingerprint script that always fails. My old guard printed 0 for all four: the third went through hole 1, and the second and fourth through hole 2, because the temporary folder has no working fingerprint script.

   Four tests: want 0, 2, 2, 2Repo root, bash or zsh

   g=scripts/hooks/commit-guard.sh   # or your hook
   t=$(mktemp -d); mkdir -p "$t/.git" "$t/scripts"
   run() { CLAUDE_PROJECT_DIR="$t" "$g" >/dev/null 2>&1
           echo "$1: exit $?"; }
   
   echo '{"tool_input":{"command":"ls"}}' | run "ls (want 0)"
   echo '{"tool_input":{"command":"git commit -m x"}}' \
     | run "commit, no stamp (want 2)"
   run "odd apostrophes (want 2)" <<'JSON'
   {"tool_input":{"command":"git commit -F - <<'EOF'\nit's done\nEOF"}}
   JSON
   echo stamp > "$t/.git/preflight-pass"
   printf '#!/bin/sh\nexit 1\n' > "$t/scripts/tree-hash.sh"
   chmod +x "$t/scripts/tree-hash.sh"
   echo '{"tool_input":{"command":"git commit -m x"}}' \
     | run "hasher fails (want 2)"

   Copy

Eight minutes after the bad commit, the agent ran its next commit command. This one didn’t stop at finding the line. It read the number in it, and if the number wasn’t 0, it printed REFUSING TO COMMIT and stopped. That’s the rule for any check: read the answer, and when you can’t read it, refuse.

1. Find every place it allows

   In a Claude Code hook, any ending other than exit code 2 allows, crashes included. Each one should mean “certainly not a commit” or “preflight passed”. If one means “I couldn’t tell”, that’s your hole. Start with the explicit ones:

   grep -n 'exit 0' scripts/hooks/*.sh

2. Replay the exact command, then try to break it

   Copy the real command from the session log into a file, not a shorter version. Feed it to the guard as JSON, the way Claude Code does. Then run the four tests.

   python3 -c 'import json,sys
   print(json.dumps({"tool_input":
     {"command": open(sys.argv[1]).read()}}))' cmd.txt \
     | scripts/hooks/commit-guard.sh; echo "exit $?"

3. Make every exit explain itself

   Print a reason whenever the guard blocks. When it allows a command, the agent never sees what it printed, so while you debug, write each allow to a log file.

   log() { printf '%s %s\n' "$(date +%T)" "$*" \
     >> "$ROOT/.git/guard.log"; }
   log "allow: not a commit"

4. Read the number, not the line

   This goes in the agent’s own commit command, before git commit, not in the guard. Take the number out of the line, and refuse anything that isn’t exactly 0, including a missing line.

   ec=$(grep -o 'preflight_exit=[0-9]*' pf.log | cut -d= -f2)
   [ "$ec" = "0" ] || { echo "REFUSING TO COMMIT"; exit 1; }

5. Fix every copy

   If the guard lives in several repos, fix the template first, then compare each copy with it.

   diff ../template/scripts/hooks/commit-guard.sh \
        scripts/hooks/commit-guard.sh

Commitgit

Saving a snapshot of your changes into git’s history.

CIgeneral

Checks a server runs automatically on every change you push.

Preflightmy own script

Runs CI’s checks on my machine before a commit.

preflight_exitmy own label

The line printed when preflight finished. preflight_exit=0 means every check passed; preflight_exit=1 means at least one failed.

Guardmy own name

My script that allows or blocks each command before the agent runs it. Claude Code calls it a hook.

HookClaude Code

A script of yours that Claude Code runs at set moments, for example before each command (a PreToolUse hook). It blocks only by ending with exit code 2. Git has hooks too, and those stop a commit on any exit code other than 0.

Fingerprintgeneral (a hash)

A short code computed from files. Change one character and the code changes.

Stampmy own name

The saved fingerprint: what preflight writes when every check passes.

onFailureClaude Code

A hook setting. "block" means a hook that crashes or runs too long also blocks.

Exit codeshell

The number a program ends with. 0 means success; any other number means some kind of failure.

grepshell tool

Finds lines that contain some text.

Heredocshell

<<'EOF' … EOF: a way to pass several lines of text to a command.

shlexPython

Splits a command into words the way a shell would. A quote that never closes is an error.