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. 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/* files are reset on every session-start.sh invocation so counters reflect only the current session. 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: last_quality_gate.json is written when a verification runs; if quality-gate.sh skips (no suitable tool for the file extension, no tsconfig.json, etc.) the previous state is left intact. That means a failed .py followed by an unrelated .md edit keeps stop-gate.sh blocking until you re-edit the .py and the gate flips back to passed. This is intentional — failures should not be cleared by activity on unrelated 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" }
  ]
}

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 verification under a 30s timeout.
• 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).