CC7: Hooks

Learning Objectives

• Recognize the 9 hook events across 6 categories and pick the right one for a goal.
• Configure each of the 5 handler types: command / http / mcp_tool / prompt / agent.
• Use exit codes (0 / 2 / other) and JSON output to allow / block / inject context.
• Wire async + HTTP hooks for centralized policy enforcement.
• Use permissionDecision: "defer" for slow human-in-the-loop approvals.
• Avoid the four hook hygiene mistakes that quietly break workflows.

What Hooks Are For — Three Real Use Cases

Three concrete cases

• Auto-format on write. Every PostToolUse(Edit|Write) runs prettier/eslint on the changed file. Claude writes ugly code; you only ever see formatted.
• Block dangerous commands. PreToolUse(Bash) intercepts rm -rf, exits 2 with a stderr message. Claude sees the rejection and tries something else.
• Route policy to HQ. PreToolUse(*) POSTs every tool call to https://policy.acme.internal. Central server logs, decides allow/deny/ask, and Claude obeys. One audit trail across every developer.

Your First Hook — Auto-Format on Write

Drop this into .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "FILE=$(jq -r '.tool_input.file_path' < /dev/stdin); npx prettier --write \"$FILE\" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

That's it. After every Edit or Write, prettier formats the file. The hook receives JSON via stdin (containing tool_input.file_path), extracts the path with jq, and runs prettier. The || true stops a prettier failure from blocking Claude.

All 9 Hook Events — Grouped by Category

Most workflows use 3-4 events. Here's the full surface so you know what's available:

The can-block column matters: only some events let exit code 2 stop the action. Use PreToolUse to block a Bash call; PostToolUse's exit 2 surfaces feedback to Claude after the tool ran (it can't undo the call).

Handler Types — Pick by Style

The Claude Code hook spec uses type: "command" — an executable invoked with the hook JSON on stdin. Within that single primitive you can build five distinct enforcement styles, summarized below. (HTTP / MCP / prompt / agent variants are wrappers around a command-type hook that shells out to curl, an MCP client, the claude -p CLI, or a subagent runner.)

Example: prompt-based check

Not every check should be a regex. Use a prompt-type hook for semantic decisions:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "User submitted: '$ARGUMENTS'. Is this prompt asking Claude to do something off-topic for a backend engineering project (e.g. write poetry, debate philosophy)? Answer YES or NO only.",
            "model": "haiku"
          }
        ]
      }
    ]
  }
}

If Haiku replies YES, the hook blocks the prompt with a polite redirect. Cheap (Haiku), fast (~30s timeout), and handles fuzziness regex can't.

HTTP Hooks & Defer Permission — The Modern Production Pattern

For organizations: stop scattering hook scripts across every developer's repo. Centralize policy in one HTTP endpoint. Add async + defer for slow human-in-the-loop approvals.

{
  "allowedHttpHookUrls": ["https://policy.acme.internal/*"],
  "httpHookAllowedEnvVars": ["POLICY_TOKEN"],
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Write|Edit",
        "hooks": [
          {
            "type": "http",
            "url": "https://policy.acme.internal/check",
            "headers": { "Authorization": "Bearer $POLICY_TOKEN" },
            "allowedEnvVars": ["POLICY_TOKEN"],
            "async": true,
            "asyncRewake": true,
            "timeout": 5,
            "statusMessage": "Checking corporate policy..."
          }
        ]
      }
    ]
  }
}

The endpoint receives the tool-use JSON, runs whatever policy logic, returns a JSON response with hookSpecificOutput.permissionDecision set to one of:

• allow — tool call proceeds.
• deny — blocked, message returned to Claude.
• ask — user prompted (escapes auto-approval).
• defer — park the tool call, returns stop_reason: "tool_deferred"; resume later with claude --resume <session-id> after policy decision lands.

Defer requires Claude Code v2.1.89+ in non-interactive (-p) mode. Pattern: pre-commit checks send Bash calls to a Slack approval bot; while the SRE thumbs-ups in Slack, the session sits in deferred state; resume re-runs with the decision.

Hook Output Anatomy — Exit Codes & JSON

Hooks communicate with Claude Code two ways: exit codes (simple) and JSON output (rich). Most events accept both.

Common JSON output fields

{
  "continue": true,
  "stopReason": "Optional message when continue=false",
  "suppressOutput": false,
  "systemMessage": "Warning shown to user",
  "decision": "block",
  "reason": "Explanation for decision",
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Pre-approved by policy",
    "updatedInput": { "command": "git diff --name-only" },
    "additionalContext": "Note: this run is part of release pipeline"
  }
}

Useful hook input fields (always present in stdin)

• session_id — current session ID, for log correlation.
• transcript_path — path to the JSON-lines conversation history.
• cwd — current working directory when the hook fires.
• hook_event_name — the event firing this hook (e.g. PreToolUse).
• tool_name + tool_input — on PreToolUse.
• tool_name + tool_input + tool_response — on PostToolUse.
• prompt — on UserPromptSubmit.
• stop_hook_active — on Stop / SubagentStop (true if Claude is already continuing because of a stop hook; check this to avoid infinite loops).

Hook Hygiene — Limits That Bite You

Async vs sync — when to use which

async: true — hook runs in background, agent doesn't wait. Useful for telemetry, slow logging. Cannot block.

asyncRewake: true — like async, but if the hook exits 2 the agent gets woken with a system reminder. Lets you do slow validation that can still inject context (just not synchronously).

Default (sync) — agent blocks until hook completes. Use for permission decisions and anything where the next tool call depends on the hook's verdict.

Hands-On Lab — Block Java Edits That Fail Spotless

Working in the PublicRecords API. You'll wire a PostToolUse hook that runs mvn -q spotless:check after every Edit/Write touching a .java file, and exit 2 if formatting drifts — injecting a system reminder that forces Claude to fix the code before the next step. About 12 minutes.

Step 1 — Add the Spotless plugin to pom.xml

Add this plugin block inside <build><plugins> in your existing pom.xml:

<plugin>
  <groupId>com.diffplug.spotless</groupId>
  <artifactId>spotless-maven-plugin</artifactId>
  <version>2.43.0</version>
  <configuration>
    <java>
      <googleJavaFormat/>
      <trimTrailingWhitespace/>
      <endWithNewline/>
    </java>
  </configuration>
</plugin>

Baseline the existing source (formats everything to Google style), then verify clean:

Step 2 — Write the hook

This file is the same .claude/settings.json you started in CC4 — merge the new hooks key in alongside permissions, don't replace the file:

{
  "permissions": { "...": "from CC4" },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "FILE=$(jq -r '.tool_input.file_path'); case \"$FILE\" in *.java) mvn -q spotless:check 1>&2 || exit 2 ;; esac"
          }
        ]
      }
    ]
  }
}

Step 3 — Verify the hook is loaded

> /hooks

Your PostToolUse hook should appear with source "Project." If it's missing, the JSON didn't parse — most often a trailing comma where you merged with permissions, or unescaped quotes inside the command string.

Step 4 — Make a deliberately bad edit

> In FilingController.java, add a new endpoint
   GET /filings/count that returns the total count.
   Use 2-space indentation throughout (don't worry about Google style).

Watch what happens: Claude makes the edit, the hook fires, mvn -q spotless:check reports formatting drift, the hook exits 2. Claude receives a system reminder like "PostToolUse hook exited with code 2: Spotless check failed" and either runs mvn spotless:apply or rewrites the method with 4-space indent. Either way, the edit doesn't proceed until the formatter is happy.

Step 5 — Confirm clean edits aren't blocked

> Now add a JavaDoc to the new endpoint method, properly formatted.

Hook fires, Spotless passes, exit 0, no system reminder. Claude continues to the next step (probably running tests). The hook is invisible when things are good — that's the goal.

Step 6 — Inspect the hook's tool ribbon

Look at the tool ribbon on a recent turn. After each Edit tool call, there's a hook entry showing the command that ran and its exit code. That's your audit trail — if a teammate ever asks "did Claude really run the formatter on that PR?", point them at the transcript.

Stretch — Make it async + non-blocking

Change the hook entry to add "async": true, "asyncRewake": true. Now Spotless runs in the background; Claude continues immediately. If the format check fails, Claude gets woken with the system reminder a few seconds later (instead of being blocked synchronously). Useful when mvn warm-up is slow and you don't want to pay the latency on every edit.

Stretch — Wire in the CC6 PII auditor

Add a second hook on PreToolUse matching Bash(git commit:*) that invokes the pii-auditor subagent. If it returns anything other than "PII audit clean", exit 2 to block the commit. You've now got formatter + PII gate, both automatic.

Windows note

Replace the bash-style command with PowerShell:

"command": "pwsh -NoProfile -Command \"$j = [Console]::In.ReadToEnd() | ConvertFrom-Json; if ($j.tool_input.file_path -like '*.java') { mvn -q spotless:check; if ($LASTEXITCODE -ne 0) { exit 2 } }\""

Knowledge Check

Module Summary

• 9 events across 6 categories: Session (SessionStart, SessionEnd) / Prompt (UserPromptSubmit) / Tool (PreToolUse, PostToolUse) / Stop (Stop, SubagentStop) / Compact (PreCompact) / User (Notification).
• 5 handler types: command (default, shell), http (centralized), mcp_tool, prompt (LLM), agent (subagent verification).
• Communication: exit codes (0 success, 2 block, other = non-blocking error) + optional JSON for rich responses.
• Permission decisions: allow / deny / ask / defer (latter requires v2.1.89+ in -p mode).
• Async: async for fire-and-forget, asyncRewake for slow validation that can still inject context.
• Limits: 10K char output cap, hook deduplication per event, stale-on-resume context.
• Browse with /hooks; debug before blame.