Hooks

Philosophy: Use prompts for guidance. Use hooks for behavior that should run every time. When a rule contains "always", "never", "block", "record", "run", or "verify", it belongs in a hook.

Included Hooks

SessionStart (runs at session start — and again after each compaction)

SessionStart fires with a source: startup / resume / clear for a fresh session, and compact mid-session right after a context compaction.

UserPromptSubmit (runs before the model sees each user prompt)

PreToolUse (runs BEFORE a tool executes)

PostToolUse (runs AFTER a tool executes)

PostToolUseFailure (runs AFTER a tool call fails)

StopFailure (runs when a turn ends on an API error)

Stop (runs when Claude tries to finish a turn)

SessionEnd (runs when the session ends)

Optional (installed but not enabled by default)

These hooks are included in the kit but not enabled in the standard profile. They can be slow or conflict with project-specific configs.

State Files

Several hooks share state through transient files at the project root. Quality-gate results for files in another git worktree of the same repository go to that worktree's own .hook-state/ instead, so parallel worktrees never block or clear each other (see agent_docs/worktrees.md). These are self-gitignored (the hook writes a local .gitignore inside the directory the first time it creates state). You don't need to add them to your project's root .gitignore.

The transient .hook-state/* counters are reset on every new session (session-start.sh) so they reflect only the current session; quality-gate results are not — they are per session already, and pruned after 7 days. The audit log is append-only across sessions — /scorecard aggregates over the requested window.

Both directories are created on demand. Delete them anytime — the next hook run re-creates them.

Persistence note: results are per file. A failed .py stays failed until a check of that file — or of its whole scope, for project-wide checks such as tsc — passes; a pass on another file or an edit to a Markdown file doesn't clear it. A file that changes after its check (through Bash, a formatter, codegen) is stale, and stop-gate.sh re-verifies it instead of trusting the old pass. A file no check covers is recorded as skipped with a reason: reported as NOT verified, never counted as passed, and not blocking. Results carry their session and are kept across sessions and compactions; a stop answers only for its own session's files.

Escape Hatches

Some hooks block actions or completion. When they get in the way (broken test infra, intentional hot-fix, etc.) use these environment variables:

Set per-session (export CLAUDE_APPROVED=1) or per-command (CLAUDE_APPROVED=1 claude ...). Never put these in committed config — they defeat the purpose.

How It Works

Hooks are configured in .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write|NotebookEdit",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/protect-files.sh" },
          { "type": "command", "command": ".claude/hooks/protect-changes.sh" }
        ]
      }
    ]
  }
}

• matcher: which tools trigger the hook (regex pattern). Not used for SessionStart/UserPromptSubmit/SessionEnd/Stop.
• exit 0: allow the action
• exit 2: block the action (PreToolUse only) or block completion (Stop only)
• stdout: for SessionStart and UserPromptSubmit, valid JSON of the form {"additionalContext": "..."} injects context into the model.
• stderr: shown to Claude as feedback regardless of exit code.

The hook receives tool input as JSON via stdin.

Hook Profiles

The installer supports three profiles (--profile minimal|standard|strict). Each profile enables a different set of hooks:

The repository's .claude/settings.json represents the standard profile. The strict profile is generated by install.sh at install time.

Enabling / Disabling Hooks

Disable a specific hook

Remove or comment out its entry in .claude/settings.json.

Enable optional hooks

To enable auto-lint and auto-format, add to the PostToolUse section in .claude/settings.json:

{
  "matcher": "Edit|Write",
  "hooks": [
    { "type": "command", "command": ".claude/hooks/auto-lint.sh" },
    { "type": "command", "command": ".claude/hooks/auto-format.sh" }
  ]
}

Enable notify-waiting (out-of-terminal "agent is waiting" ping)

Enabled by default in the strict profile. To turn it on elsewhere, add a Notification section to .claude/settings.json:

"Notification": [
  { "hooks": [ { "type": "command", "command": ".claude/hooks/notify-waiting.sh" } ] }
]

With no further config it only fires a local desktop notification (via terminal-notifier/osascript on macOS, notify-send on Linux) and is silent where none is installed (CI, headless servers). To also get an out-of-band push on another device, opt in with env vars — nothing leaves the machine unless one of these is set:

The hook is strictly advisory: it always exits 0 and never blocks or mutates tool flow, so a missing binary or an unreachable push endpoint can't stall a run.

Make secret-scan block instead of warn

Edit secret-scan.sh and change the final exit 0 to exit 2.

Loosen protect-changes for a specific project

Add a project-specific override under .claude/hooks/project/. Project hooks are configured separately in settings and are never modified by kit upgrades. Example: a hook that exits 0 for package.json if the project owner has pre-approved auto-updates.

Writing Your Own Hooks

Template

#!/usr/bin/env bash
set -euo pipefail

INPUT=$(cat)
HOOK_LIB="$(cd "$(dirname "$0")/lib" 2>/dev/null && pwd)"
source "$HOOK_LIB/json-parse.sh"

TOOL_NAME=$(parse_json_field "tool_name")
FILE_PATH=$(parse_json_field "file_path")

# Your logic here

exit 0  # allow (or exit 2 to block in PreToolUse / Stop)

Output JSON (SessionStart, UserPromptSubmit)

For context-injecting hooks, write JSON to stdout:

printf '%s' "$context" | python3 -c \
  'import json,sys; print(json.dumps({"additionalContext": sys.stdin.read()}))'

The kit uses python3 for safe JSON construction, falling back to jq, then to manual bash escaping. Match this pattern.

Tips

• Keep hooks fast — they run on every tool call. Quality-gate runs each check under a 30s limit through lib/run-with-timeout.sh, which kills the whole process group on timeout (and when the hook is signalled) — use it in any hook that spawns a tool. Probe python3 with lib/python3.sh (python3_usable), not command -v: a stub that exists but can't run must count as absent. It caches a working python3 in $TMPDIR (never a broken one), so call it once at the top of a hook.
• Use exit 0 for pass, exit 2 for block
• Output to stderr is shown to Claude as feedback regardless of exit code
• Output to stdout in JSON form (for SessionStart/UserPromptSubmit) is parsed by Claude Code and injected as context
• For Stop hooks: avoid infinite loops. If you block, make sure the condition can become false (e.g., read a state file, don't re-evaluate the same condition forever).
• Test hooks manually: echo '{"tool_name":"Edit","tool_input":{"file_path":".env"}}' | .claude/hooks/your-hook.sh
• For hooks that read state, fall back gracefully when the state file doesn't exist (e.g., a fresh checkout).