Five small bash scripts that make Claude Code run your tests before it says “done”, refuse a force push, and tell you when it’s waiting. Tested, with the code.
On a ship, a job isn’t done because the person who did it says so. The engineer finishes the overhaul, but the job card closes only after someone runs the machinery and checks it. Twenty years at sea teaches you to trust the check, not the claim.
AI coding tools work the other way round. Claude Code decides for itself when a task is finished.
So I tested it. I asked Claude Code to do one small thing: add a comment to the top of a script. Nothing else, and don’t run the tests.
It added the comment and was about to say “done”. Then a hook ran the test suite. The test was failing, and had been failing before Claude touched anything. The hook sent Claude back with the error. Claude fixed the real bug, left the test alone, and told me the fix went beyond what I’d asked.
Nothing in my prompt asked for that. A 46-line bash script did.
What you’ll build: five Claude Code hooks: a dangerous-command blocker, a “tests must pass before done” check, a desktop alert, a session briefing, and a command log. Code: github.com/tarunagarwal1981/ops-ai/tree/main/claude-code-hooks Tested with: Claude Code 2.1.319, bash 5.2, jq 1.7, git 2.43, on Linux. 43 checks in test_hooks.sh pass, and I ran four of the hooks end to end in a real headless session.
A hook is a script with a veto
In my previous post on Claude Code setup, I added two hooks: a formatter and a .env blocker. That's where most people stop. But hooks can fire at many more moments than "before an edit".
A hook is a command Claude Code runs at a fixed moment. It gets a JSON blob on stdin and answers with an exit code. Exit 0 means carry on. Exit 2 means "no", and whatever you wrote to stderr goes back to Claude.
What “no” means depends on the moment:
- PreToolUse: the tool call is blocked
- Stop: Claude doesn’t get to stop. It keeps working with your message
- PostToolUse: the tool already ran, so Claude only sees your message
- SessionStart: no veto, but anything you print goes into Claude’s context
- Notification: no veto at all. It’s just a signal
All five are wired up in one .claude/settings.json, using the same shape as before. The full file is in the repo.
Don’t want to wire these up by hand? The Claude Code Starter Kit installs all five plus five more with one command, finds your test command, and checks every hook works before you start.
1. Block the commands you can’t undo (PreToolUse)
A deny rule matches a command pattern. A hook reads the whole string, so it can also catch SQL hiding inside psql -c "...".
cmd=$(jq -r '.tool_input.command // empty')
if grep -Eiq 'git[[:space:]]+push([[:space:]].*)?[[:space:]](--force|-f)([[:space:]]|$)' <<<"$cmd"; then
echo "Blocked: git push --force. Use --force-with-lease, or ask the user." >&2
exit 2
fi
The real script has six rules: rm -rf on /, ~ or *, force push, git reset --hard, git clean -f, DROP/TRUNCATE, and curl | sh. Match it on "Bash".
The test script caught two of my own regex bugs. The first version blocked rm -rf ./dist, and it missed a bare git push -f. Test your blocker against commands you want to allow, not just the scary ones.
In the live run, I told Claude to force push. The hook blocked it, Claude didn’t try to get around it, and it offered --force-with-lease instead.
2. “Done” means the tests pass (Stop)
This is the one from the opening. When Claude is about to finish, the hook runs your tests. If they fail, it exits 2 and Claude keeps going with the failure output.
if output=$(bash -c "$test_cmd" 2>&1); then rm -f "$counter"; exit 0; fi
attempts=$(( $(cat "$counter" 2>/dev/null || echo 0) + 1 )); echo "$attempts" > "$counter"
if (( attempts > max )); then echo "Still failing after $max tries. Over to you." >&2; exit 1; fi
{ echo "Tests are failing, so the task is not done."; tail -n 40 <<<"$output"
echo "Fix the cause. Do not skip, delete or weaken tests."; } >&2
exit 2
The danger is a loop: Claude can’t fix it, tries to stop, gets sent back, forever. Claude Code passes a stop_hook_active flag so you can spot a repeat stop, and it has its own cap: after 8 blocks in a row it ends the turn anyway. My script stops at 3 attempts, counted per session, then exits 1, which tells you and lets Claude stop.
Preview: readers without a Medium subscription see this banner in your story.
Want to remove it? Friend of Medium hides it from all your free stories.
It also skips the tests if the git working tree is clean. No changes, nothing to test.
An instruction tells Claude what “done” means. A Stop hook decides it.
3. Get a ping when it’s waiting on you (Notification)
You start a long task, switch windows, and come back twenty minutes later to find Claude has been waiting for a permission click for nineteen of them.
The Notification event fires when that happens. Match it on permission_prompt|idle_prompt, read .message from stdin, and call osascript on macOS or notify-send on Linux. The script adds the project folder to the title, so you know which terminal to go back to.
4. Start every session with a briefing (SessionStart)
On SessionStart, anything your script prints on stdout lands in Claude's context. Mine prints the branch, the last five commits, uncommitted files, and the first ten TODO/FIXME lines.
echo "Branch: $(git branch --show-current)"
git log --oneline -5 | sed 's/^/- /'
git status --porcelain | head -n 15 | sed 's/^/- /'
Match it on startup|clear|compact. The compact one matters: after Claude compresses a long conversation, it gets the briefing again. In the live test, I asked for the branch and the last commit message without letting it run a command. It answered both correctly.
5. Keep a log of every command (PostToolUse)
Hooks on PostToolUse and PostToolUseFailure, both matched on Bash, append one JSON line per command:
{"ts":"2026-11-07T12:56:07Z","session":"b3c20e0c-…","status":"ok","cwd":"…/e2e-stop","command":"ls -la && cat greet.sh"}
That’s a real line from the test run. When something odd happens, jq the log and see exactly what ran. Blocked commands never appear, because they never ran. Add the log file to .gitignore.
When these hooks are the wrong choice
- The blocker is a seatbelt, not a sandbox. It matches text. A script that does the deleting, or a command built from variables, gets past it. Keep your deny rules too.
-
A slow test suite makes every stop slow. Point
HOOK_TEST_CMDat a fast subset. - Hooks run with your permissions. Read any hook before you install it, these included.
Rules don’t drift. Instructions do.
We tell AI agents what “done” means in prompts, in CLAUDE.md, in skills. On a long task, with a full context, that can slip.
At sea we learned this long ago. Nobody relies on a reminder to close a valve before opening a tank. There’s a lock on it, and a permit that has to be signed. The rule lives in the system, not in someone’s memory.
A Stop hook is that lock for your coding agent. It’s the difference between telling a new engineer “always run the tests” and having a pipeline that won’t merge without them.
So look at your own setup. Which rule do you keep repeating to Claude that should be an exit code instead?
All five scripts, the *settings.json, and the 43-check test script are in the ops-ai repo. Found a hook worth adding? Open an issue.*
Want a head start? Get the free Claude Code cheat sheet and 3 safety hooks: one page of what to type, plus three of these hooks ready to copy, with tests. The full Starter Kit has all ten, five subagents and a one-command installer.
References
- Claude Code hooks reference: https://code.claude.com/docs/en/hooks
- Official example, Bash command validator hook (anthropics/claude-code): https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py
- Companion code: https://github.com/tarunagarwal1981/ops-ai/tree/main/claude-code-hooks
Top comments (0)