Hooks
The big picture: Blueprint wires its Claude Code hooks (in .claude/settings.json; the table below lists each)
and two git hooks (in hooks/). A hook runs on its own at a fixed moment, so a rule that
must not depend on anyone remembering is enforced here rather than in prose.
Why it matters: When a command or an edit is refused, the refusal comes from a hook, not from Claude. This page says which hook it was, what it was protecting, and how to proceed.
This page is kept in step with the repository by scripts/check-harness-reference.py
(make check-harness-reference): a script in .claude/hooks/, a file in hooks/, or a
script named by a hook command in .claude/settings.json that has no entry here fails the
check.
Claude Code hooks
Section titled “Claude Code hooks”The files live in .claude/hooks/ and are registered in .claude/settings.json. The
Edit and Write deny rules there keep the agent from editing the hook files, and
pre-bash-deny.sh covers Bash writes to the same paths.
| Event | Matcher | Hook | Can it block? |
|---|---|---|---|
PreToolUse |
Bash |
pre-bash-deny.sh |
Yes |
PreToolUse |
Bash |
pre-mr-security-gate.sh |
Yes, until gates are recorded |
PreToolUse |
* |
pre-tool-agent-budget.sh |
Yes, for a /wave implementer past 120 tool calls (ships in 0.8) |
PreToolUse |
Edit|Write |
pre-tool-safety.sh |
Yes for lock files and existing migrations; warns for the rest |
PostToolUse |
Edit|Write |
post-edit-checks.sh |
No, it only adds reminders |
PostToolUse |
Bash |
post-mr-cost.sh |
No, it posts the MR’s cost record |
Stop |
none | on-stop.sh |
Yes, once per turn |
Stop |
none | context-nudge.sh |
No, it only shows a line |
SessionStart |
startup|resume|clear|compact |
session-start-status.sh |
No, it only shows a line |
A hook that blocks exits 2 and its stderr message is fed back to Claude, so the agent sees why and can change course.
pre-bash-deny.sh
Section titled “pre-bash-deny.sh”Denies the operations AGENTS.md forbids. It splits the command with shlex and looks at
each simple command, so git push origin main --force, git -C . push -f and git push -uf are all caught, which a prefix rule such as Bash(git push --force:*) would miss.
What it refuses:
git pushwith--force,-f(also inside a cluster such as-uf), a+ref, a:ref,--delete,--mirror, or the GitLab auto-merge push option.--no-verifyon any git command,git commit -n, and-c core.hooksPath=....- Every
git stashexceptlistandshow. git reset --hard, andgit cleanwith force.glab mr merge, andglab apicalls to a merge endpoint or the merge mutation.rm -raimed at/,~,.,..,*,.git, a top-level path, or a path outside the project and the temp directories.curlorwgetpiped into a shell.- Writes by Bash (
>,tee,sed -i,cp,mv,rm,chmodand similar) to.claude/settings*.json,.claude/hooks/**,hooks/**, the installed.git/hooks, and.git/config.
A refusal reads pre-bash-deny: blocked. followed by the reason. Use the safe equivalent
it names:
| Refused | Do this instead |
|---|---|
git stash |
scripts/wt stash (see scripts/wt) |
git push --force after a rebase |
git push --force-with-lease on your own feature branch |
--no-verify |
Fix what the hook reported |
glab mr merge |
Open the MR and stop; a person merges it |
If the command is one only you should run, type it at the Claude Code prompt with a leading
!, for example ! git status (use your own command). A ! command runs directly,
without going through Claude, so the hook does not see it. See also
Troubleshooting.
The /wave worker tier (ADR 0010). In an event whose agent_type is wave-worker,
or whose cwd lies under .claude/worktrees/, this hook switches to an allowlist. That
includes Claude Code’s own claude --worktree sessions, which also live under
.claude/worktrees/. The allowlist covers:
- Commands: git, glab and make subcommands and options from exact lists; listed
wrappers, text tools and toolchains; and
scripts/check-*,scripts/tests/*andscripts/wt adopt,stash,listandharness-diff. - Writes: only inside the worker’s own worktree, outside the harness
(
scripts/lib/harness-paths.txt), or in a scratch temp directory. - cd: only within the worktree.
- Network: none.
A refused command comes back at once as a tool error naming the rule. In every
session, the hook also refuses a write to scripts/lib/harness-paths.txt, and checks a
trap action string like eval.
pre-mr-security-gate.sh
Section titled “pre-mr-security-gate.sh”Fires when Claude runs a command that creates a merge request (glab mr create, also
under env, sudo, bash -c, eval, or git push -o merge_request.create). If the
branch changed source files, it blocks the command until the access-control gates have
run: rbac-check always, plus security-review when the diff touches views, serializers,
permissions, routes or handlers, auth, middleware, or uploads. A branch that changed only
docs, CI, or the changelog is not blocked.
To proceed, run the named gates, then record that they ran, for the current commit:
.claude/hooks/pre-mr-security-gate.sh record ranIf the user declined them, record skipped instead; the MR’s ## Gates section then
says skipped, never 0 findings. The marker is .claude/state/pre-mr-gate. A
new commit, or an edit after recording, invalidates it, so record after the last change.
If jq or python3 is missing, the event cannot be parsed, so anything that looks like an
MR command is blocked rather than let through.
What it refuses since ADR 0010. It always diffs the branch the MR opens, never its own directory, and it denies:
- an MR from
mainor a detached HEAD with no--source-branch; - a
--source-branchthat no worktree has checked out; - a
cdbeforeglab mr createthat may not apply (cd X; glab mr create), or a glab behind a prefix it cannot read (env -C,env -u); - for a pinned worker’s branch (its worktree under
.claude/worktrees/): harness paths that are dirty in the main checkout, or a failingscripts/wt harness-diff.
pre-tool-safety.sh
Section titled “pre-tool-safety.sh”Guards edits to files with downstream consequences:
- Blocks a hand edit to a lock file (
package-lock.json,yarn.lock,pnpm-lock.yaml,Pipfile.lock,poetry.lock,uv.lock,go.sum,Cargo.lock). Regenerate it with the package manager instead. - Blocks an edit to a migration file that already exists. Create a new migration.
- Warns (does not block) when CI config changes, or when an
.envfile is edited.
When a hand edit is truly required, start the session with
BLUEPRINT_ALLOW_PROTECTED_EDIT=1; the block then downgrades to a warning.
The /wave worker tier (ADR 0010). For a worker-tier event (as above), Edit, Write
and NotebookEdit are hard-blocked in two cases, and BLUEPRINT_ALLOW_PROTECTED_EDIT does
not lift either:
- a harness path (
scripts/lib/harness-paths.txt, including a nestedCLAUDE.mdor lint config); - any file outside the worker’s own worktree, other than a scratch temp directory.
pre-agent-worker.sh
Section titled “pre-agent-worker.sh”PreToolUse, matcher Agent|Task. It applies only in the /wave worker tier: an event
whose agent_type is wave-worker, or whose cwd lies under .claude/worktrees/. There,
it refuses every subagent spawn. A pinned worker has no Agent tool, and the
orchestrator runs its gates; the hook is defense in depth. It does nothing in any other
session, and it fails closed on an unreadable event (ADR 0010).
pre-tool-agent-budget.sh
Section titled “pre-tool-agent-budget.sh”Ships in 0.8.
PreToolUse, matcher *. It counts every tool call made by a /wave implementer (an event whose
agent_type is wave-worker or wave-harness-worker), keyed by its agent ID, in
wave-agent-budget/ under the git common directory. The ID survives a resume, so the count is
the agent’s whole life. Past 120 calls (WAVE_AGENT_TOOL_CAP overrides it) it blocks the call,
stops the agent and writes a <agent_id>.stopped marker, which /wave reads with
scripts/wave-agent-budget.py --stopped <agent_id>. It does nothing for your own session or any
other agent, and fails closed for an implementer event it cannot read or count. Files older than
30 days are removed as it writes (macrodream/blueprint#352).
post-edit-checks.sh
Section titled “post-edit-checks.sh”Never blocks. After an edit it adds reminders to Claude’s context: verify migration safety
when a model or schema file changed; run rbac-check and security-review for an endpoint
or auth change; run /voc and then ux-review and accessibility for a UI change; update
the matching test in the same commit when production source changed; run make typecheck
after TypeScript changes.
post-mr-cost.sh
Section titled “post-mr-cost.sh”Never blocks. After a glab mr create that printed an MR URL it runs scripts/post-mr-cost.py,
which posts record 1 of the MR’s ## Cost of this MR comment (timeout 300). It does nothing when
the cost ledger is off (scripts/cost-ledger status), when the MR description carries
cost-ledger: off, or when the MR was opened on another project than the repo the hook runs in (it
then prints the post-mr-cost.py --retry --mr <n> --session <sid> command to run in the right
checkout). When the MR already has a cost comment it posts nothing but reconciles: if the comment is this
session’s own record whose state write never happened, it advances the session state to that record’s
end so the tokens are not counted twice. The record claims only tokens no
earlier record of the same session claimed, tracked in one per-session state file under
${CLAUDE_CONFIG_DIR:-~/.claude}/mr-cost-state/ (shared by every repo the session works in), so the records of one session add up to its orchestrator spend and no token is counted in two records (except a record posted with no session state (macrodream/blueprint#391)). When the MR’s
implementer ran in another session, the record also counts that session’s subagents that worked in the MR’s
worktree (by where they edit or cd, never by their brief), over that session’s own watermarks, and leaves that session’s
orchestrator out with a one-line note of how much of it is unclaimed. Every glab mr create it sees is
one line in mr-cost-hook.log in the git common directory (time, session id, MR number, a fixed outcome; no command or
transcript text). Details: docs/harness/cost-ledger.md § Non-overlap.
on-stop.sh
Section titled “on-stop.sh”A nudge at the end of a turn. If production source is dirty (against HEAD) and newer than
the marker .claude/state/tests-ran, it blocks the stop once and tells Claude to run
make test-scoped, which writes the marker. It does not fire for subagents, does not
re-check committed work, and stays silent while make test is the unconfigured stub.
It is a reminder, not a security control: the marker can be touched by hand.
context-nudge.sh
Section titled “context-nudge.sh”Ships in 0.8.
Never blocks. At the end of a turn, when the main session’s context has reached 150,000 tokens
(a provisional threshold), it shows you one line: the size, and a suggestion to /clear between
issues or /compact at a logical break. Every turn re-reads the whole context, so a session
carried into the next issue pays for the old one on every later turn. The line goes to you
alone (systemMessage), because you are the one who types those commands, and adding it to
Claude’s context would add to the cost. It prints the size and the suggestion, never anything
from the transcript.
It speaks once per crossing, not on every turn: a marker in .claude/state/context-nudge/ holds
it until the context falls back under the threshold, as it does after /compact. /clear
starts a new session, which starts clean.
Set BLUEPRINT_CONTEXT_NUDGE (for example in the env block of .claude/settings.local.json)
to off to turn it off, or to a positive number of tokens to change the threshold.
It may stop working after a Claude Code update, without telling you. The per-turn hook
events carry no context size: only SessionStart on a resume or fork, and the model-switch
events, get context_tokens. So this hook reads the usage figures from the last assistant record
near the end of transcript_path. Upstream says that format “is internal to Claude Code and
changes between versions”, so a format change usually means no line and never a failed turn, but
a change the hook cannot detect, such as a new token field, can misstate the size. Upstream also
says the transcript is written asynchronously and may lag the conversation, so the line can come
a turn late.
For a size you can always see, use a personal status line:
it receives context_window.total_input_tokens as a documented field. Blueprint does not ship
one, because a project statusLine overrides the one in your user settings.
session-start-status.sh
Section titled “session-start-status.sh”Ships in 0.8.
Never blocks. At the start of a session it runs scripts/blueprint-status --offline --line and
shows the result, for example
Blueprint 0.1: ✓Configure ✓Specify ▶Plan ·Build ·Release — next: /dotplanning 0.1, to you
and to Claude (with a pointer to /next). After a compaction only Claude gets it again. It
reads repo facts and a tracker answer cached in the last 15 minutes, never the network. It
prints nothing outside a Blueprint project, when the script fails, or when
BLUEPRINT_SESSION_STATUS=off is set (for example in the env block of
.claude/settings.local.json). See Where am I?.
Git hooks
Section titled “Git hooks”Installed once per clone by make setup, and shared by every worktree. Coding agents do
not bypass them (AGENTS.md forbids --no-verify).
pre-commit
Section titled “pre-commit”Runs before every commit, fastest first: the secret scan (make gitleaks-check), then
make format-check, make lint and make typecheck. A stage whose target is still the
unconfigured stub prints skipped (not configured). If the format check fails, run
make format; a failed hook means the commit did not happen.
pre-push
Section titled “pre-push”Runs make pre-push-checks, the full-codebase gate suite (see
Make targets). Fix what it reports and push again.
Opting out
Section titled “Opting out”Removing an entry from .claude/settings.json, or setting disableAllHooks in your user or
local settings, turns Claude Code hooks off for you.
That is a person’s call, not an agent’s: both files are on the rigor floor, so a change to them runs the strict gate chain (see Harness gates).