Skip to content

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.

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.

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 push with --force, -f (also inside a cluster such as -uf), a +ref, a :ref, --delete, --mirror, or the GitLab auto-merge push option.
  • --no-verify on any git command, git commit -n, and -c core.hooksPath=....
  • Every git stash except list and show.
  • git reset --hard, and git clean with force.
  • glab mr merge, and glab api calls to a merge endpoint or the merge mutation.
  • rm -r aimed at /, ~, ., .., *, .git, a top-level path, or a path outside the project and the temp directories.
  • curl or wget piped into a shell.
  • Writes by Bash (>, tee, sed -i, cp, mv, rm, chmod and 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/* and scripts/wt adopt, stash, list and harness-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.

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:

Terminal window
.claude/hooks/pre-mr-security-gate.sh record ran

If 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 main or a detached HEAD with no --source-branch;
  • a --source-branch that no worktree has checked out;
  • a cd before glab mr create that 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 failing scripts/wt harness-diff.

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 .env file 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 nested CLAUDE.md or lint config);
  • any file outside the worker’s own worktree, other than a scratch temp directory.

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).

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).

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.

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.

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.

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.

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?.

Installed once per clone by make setup, and shared by every worktree. Coding agents do not bypass them (AGENTS.md forbids --no-verify).

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.

Runs make pre-push-checks, the full-codebase gate suite (see Make targets). Fix what it reports and push again.

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).