C² Method8 min read

Claude Code hooks I actually run, and the one I turned off

Three hooks from a real monorepo's .claude/settings.json, what each one is for, how one went blind and one talked to nobody, and why the blocking hook got switched off.

Stuart Leo

Most lists of Claude Code hooks examples are ideas. This is the opposite: the hooks registered in my main monorepo's .claude/settings.json today, the script behind each one, and what each has cost or saved me. Three are running. One sits in .claude/hooks/ switched off, and I'll show why, because the reason is the most useful lesson here.

The short version. A SessionStart hook lists recent session briefs so every session starts knowing where the last one stopped. A SessionEnd hook prunes git worktrees whose pull request has merged. A PostToolUse hook prints a checklist reminder when a prompt brief is edited, and while writing this article I found Claude never sees it. The PreToolUse hook that blocked edits to config files was turned off on 12 April 2026, and the session brief from that day says exactly why.

How are Claude Code hooks configured?

Hooks live under the hooks key of a settings file. Per the hooks reference, there are three levels: the event, then matcher groups, then handlers. This is my hooks block, unedited (the file's permissions block is left out):

{
  "hooks": {
    "SessionStart": [
      { "hooks": [
        { "type": "command", "command": ".claude/hooks/session-context.sh", "timeout": 10 }
      ] }
    ],
    "SessionEnd": [
      { "hooks": [
        { "type": "command", "command": ".claude/hooks/session-end-prune.sh", "timeout": 10 }
      ] }
    ],
    "PostToolUse": [
      { "matcher": "Write|Edit", "hooks": [
        { "type": "command", "command": ".claude/hooks/pb-gate.sh", "timeout": 5 }
      ] }
    ]
  }
}

Each script receives a JSON payload on stdin, including session_id, transcript_path and cwd, and reads what it needs with jq. A group with no matcher runs for every source of that event. The docs list over thirty events now. I use three.

HookEventJobTalks to
session-context.shSessionStartList recent session briefsClaude, via stdout
session-end-prune.shSessionEndRemove worktrees whose PR mergedA log file
pb-gate.shPostToolUse, Write|EditChecklist reminder on prompt briefsNobody, it turns out
protect-config.shPreToolUse, Edit|WriteBlock edits to config filesOff since 12 April 2026

The SessionStart hook: a menu of briefs, not the latest brief

Every session in my repo opens with a list like this in Claude's context. These are the first lines it printed today:

=== Recent Session Briefs (last 30 days) ===

  26/11/15  shared inbox followups shipped and reboot handoff
  26/11/15  one prd brand standard
  26/11/15  one pb reconciliation escaping and brand logo
  ...

Briefs get parked — ask Stuart which to pick up, don't assume the latest.
===

SessionStart is one of the few events where plain stdout is added to Claude's context, so the script just echoes. The core of it:

# trimmed from .claude/hooks/session-context.sh
PROJECT_DIR=$(echo "$(cat)" | jq -r '.cwd // empty')
for dir in "$BRIEFS_2025" "$BRIEFS_2026"; do
  [ -d "$dir" ] && find "$dir" -maxdepth 1 -type f -name "*.md" -mtime -30 -exec basename {} \;
done | grep -v -i -E '^(readme|index|_)' | while read -r brief; do
  brief_line "$brief"
done | sort -r | head -15 | cut -f2-

Two choices are deliberate. It lists names and never dumps whole briefs, so the hook costs almost nothing in context. And its last line tells the agent not to assume the newest brief is the priority, because work gets parked.

This hook also failed silently for six weeks. It used to match only files ending -session-brief.md. From 19 August 2026 brief names dropped that suffix. The fix commit on 2 October (#1086) records the damage: 33 briefs had been written since, and "every session booted showing an 18 Aug brief as the newest and never saw the last session's brief." Nothing errored. Now the script parses four date formats and the header comment explains why. A SessionStart hook that reads files by name breaks the day the names change. When you change a naming convention, re-run the hook.

The comment at the top of the script is my favourite part of it, because it's a gotcha written where the next reader will trip on it.

The SessionEnd hook: cleaning up after agents

This one exists because of a disk. My gotcha file on it opens: "By 2026-10-05, waymaker/.claude/worktrees/ held 123 leftover agent worktrees using about 216 GB, and Stuart's Mac ran out of disk." Each worktree had run its own npm install, about 2.4 GB, and nothing removed a worktree when its agent finished.

The fix on 19 October (#1603) was two-part: a daily scheduled prune, and this hook at the end of every session. It removes a worktree only when its pull request is merged, the tree is clean, it isn't locked, and no process is working inside it. The interesting part is how it stays out of the way:

# trimmed from .claude/hooks/session-end-prune.sh
cd "${CLAUDE_PROJECT_DIR:-$PWD}" 2>/dev/null || exit 0
(
  take_lock "$me" || exit 0          # two sessions ending together don't both prune
  git fetch -q origin 2>/dev/null || true
  git show origin/main:scripts/prune-worktrees.sh > "$T" 2>/dev/null || exit 0
  grep -q -- '--merged-only' "$T" || exit 0   # never run an older, broader script
  /bin/bash "$T" --yes --merged-only --quiet
) >>"$LOG" 2>&1 </dev/null &
disown 2>/dev/null || true
exit 0

SessionEnd hooks can't block the session ending, and the docs give them a default budget of 1.5 seconds when you exit, /clear or switch sessions. A fetch and a prune don't fit in that. So the hook does the work in a detached background process and returns at once, and it always exits 0, so a failure never delays your exit. It also runs the prune script from origin/main, not from whatever branch the session left checked out, and refuses to run a version that doesn't know --merged-only.

Its output goes to a log file, not to Claude. Nobody needs to read it unless something looks wrong.

The PostToolUse hook that was talking to nobody

pb-gate.sh fires after every Write or Edit. If the file is a markdown prompt brief under docs/02-working/prompts/active/, it prints a box:

# trimmed from .claude/hooks/pb-gate.sh
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
if [[ "$FILE" != *"/prompts/active/"* ]]; then exit 0; fi
echo "  PB GATE — checklist required before autonomous hand-off"
echo "  Run /pb-check $(basename "$FILE") before handing this PB to an agent."
echo "  One NO = not ready. Fix first."

A prompt brief is a task written for an agent to run without me, and the checklist catches the gaps that would strand it. The reminder is aimed at the agent writing the brief.

While checking hook behaviour against the docs for this article, I noticed the reference lists only four events whose plain stdout reaches Claude: UserPromptSubmit, UserPromptExpansion, SessionStart and PostModelSwitch. PostToolUse isn't one. So I tested it on 20 November 2026 with Claude Code 2.1.329, in a scratch repo with a PostToolUse hook on Write|Edit shaped exactly like pb-gate.sh:

Hook outputDid the hook run?What Claude reported
echo "...the secret word is ZEBRA", exit 0Yes, it wrote a marker file"NO HOOK OUTPUT"
JSON with hookSpecificOutput.additionalContext, exit 0Yes"a PostToolUse hook for Write said the secret word is ZEBRA"

So my reminder has been printing into a void, at least as far as the agent is concerned. The docs don't say where that stdout goes. I haven't checked whether it shows anywhere in the interactive view, so I won't claim it does. The fix is small. Print JSON instead:

jq -n --arg f "$(basename "$FILE")" '{hookSpecificOutput: {
  hookEventName: "PostToolUse",
  additionalContext: ("PB GATE: run /pb-check " + $f + " before handing this PB to an agent.")
}}'

Or exit 2 with the message on stderr. The docs say that shows the stderr to Claude after the tool has already run. That's a heavier signal, which suits a warning more than a reminder.

A hook that prints is not a hook that's heard. Test that its output reaches whoever it's for.

The one I turned off: protect-config.sh

This hook arrived on 3 April 2026, in the same commit as the SessionStart hook. It was a PreToolUse hook on Edit|Write with a simple purpose: stop an agent "fixing" a type error by loosening tsconfig.json or switching off a lint rule. It checked the file name against a list and exited 2 to block:

# trimmed: the real list has 19 names, including the eslint, prettier, postcss and tailwind configs
PROTECTED_EXACT=( "tsconfig.json" "biome.json" "vercel.json" "vite.config.ts"
                  "package-lock.json" ".mcp.json" )
for pattern in "${PROTECTED_EXACT[@]}"; do
  if [[ "$FILENAME" == "$pattern" ]]; then
    echo "BLOCKED: Cannot edit '$FILENAME'. Fix the code instead of changing config." >&2
    echo "If Stuart explicitly asked you to edit this file, ask him to approve the edit manually." >&2
    exit 2
  fi
done

It also blocked any .env* file and Claude's own .claude/settings*.

Nine days later I turned it off. The session brief for 12 April 2026 records why. It was my first session on a new laptop, and the migration had lost the Supabase MCP server config, so the session needed to add it back to .mcp.json. The brief: "The PreToolUse hook in .claude/settings.json was blocking edits to .mcp.json (and other config files). Stuart approved removing it." The same commit removed the hook and fixed the MCP config.

Look at the second line of that error message. It tells the agent to ask me to approve the edit. But exit 2 doesn't ask anyone. Per the docs, it blocks the tool call. There was no approval path in the design, so when a legitimate edit came along, the only way through was to delete the hook.

If I rebuilt it, I'd use the JSON form instead. A PreToolUse hook can return a permissionDecision of allow, deny, ask or defer. deny for .env files. ask for tsconfig.json and .mcp.json, which hands the edit to the permission prompt so I can say yes when I mean it. That keeps the teeth and adds the door.

What replaced it, for now, is honesty. My root CLAUDE.md says: "protect-config.sh is not enabled: config edits are NOT blocked mechanically. The rule still stands: fix the code, don't weaken tsconfig/biome/vite/.env." I wrote about why that sentence matters in why Claude Code ignores your CLAUDE.md. A rule file that implies enforcement it doesn't have is worse than one that admits the rule is guidance.

One more confession. My repo's own hooks doc, docs/03-knowledge/patterns/claude-code/hooks.md, still lists protect-config.sh as an active hook. The settings file is the truth. The doc drifted. Check your hooks against .claude/settings.json, not against what you wrote about them.

What four hooks taught me

  • Tell, do, or block. SessionStart tells Claude something. SessionEnd does something and tells nobody. PreToolUse blocks. Know which one you're writing, because each needs a different output channel.
  • Plain stdout only reaches Claude on a few events. For the rest, use additionalContext or exit 2.
  • A block needs a door. Exit 2 with no approval path will eventually block the owner, and then the whole hook goes. Use ask where a human might legitimately say yes.
  • Hooks fail silently. Two of my four have been wrong without an error: one blind for six weeks, one unheard. Re-test after any change to names, paths or the hook itself.
  • Keep SessionEnd fast. Background the work, exit 0.

Start here: why Claude Code ignores your CLAUDE.md, how to stop Claude Code losing context between sessions, or the C² method.

Questions people ask

What are Claude Code hooks?
Hooks are commands Claude Code runs at fixed points in a session, such as SessionStart, PreToolUse, PostToolUse and SessionEnd. They are configured in settings.json and run whatever Claude decides, so they suit rules that must always happen, unlike CLAUDE.md, which Claude reads as guidance.
Where do Claude Code hooks go?
In the hooks key of a settings file: .claude/settings.json to share them with the project, .claude/settings.local.json for yourself in one project, or ~/.claude/settings.json for every project. Each event holds matcher groups, and each group holds handlers such as a command with a timeout.
Does Claude see the output of a PostToolUse hook?
Not plain stdout on exit 0. The docs list only SessionStart, UserPromptSubmit, UserPromptExpansion and PostModelSwitch as events whose plain stdout reaches Claude, and my own test confirmed a PostToolUse echo was invisible to it. Return JSON with hookSpecificOutput.additionalContext, or exit 2 with a message on stderr.
How do I block a tool call with a Claude Code hook?
Use a PreToolUse hook. Exit code 2 blocks the call and Claude sees your stderr as the reason. For finer control, print JSON with a permissionDecision of allow, deny, ask or defer. Ask sends the call to the user's permission prompt instead of refusing it outright.
Why would you turn off a Claude Code hook?
Because it blocks legitimate work. My config-protection hook exited 2 on any edit to a list of config files, including .mcp.json. When I needed to restore an MCP server on a new laptop, the hook blocked the edit and there was no way to approve it short of removing the hook.

Part of the C² Method. Start with the method

Put this in your repo

The C² Method is free and open. Point your agent at the kit and get started in minutes.