How Hooks Work#

At their core, hooks are shell commands that Claude Code executes at predefined points during its operation. You configure them in your project’s .claude/settings.json file, specifying which events trigger which commands. When the event fires, Claude Code pipes a JSON payload containing the event context to your hook script’s stdin, and your script can inspect the payload, perform validation, and optionally return a JSON response that influences Claude’s behavior.

Think of hooks as middleware in a web framework. Just as Express.js middleware intercepts HTTP requests before they reach your route handler, hooks intercept Claude Code’s tool calls, session events, and permission requests before they execute. The difference is that hooks operate at the AI agent level, intercepting decisions rather than network requests.

Figure 2 - Hooks as Agent Middleware: Hooks intercept the agent’s tool calls at 2 critical points. PreToolUse hooks act as safety gates before execution, allowing, denying, or escalating to human confirmation. PostToolUse hooks act as quality gates after execution, running validators and injecting feedback back into the agent’s context. Together, they create a deterministic control layer around every agent action.

This PreToolUse hook blocks any Bash command containing destructive patterns:

1
#!/usr/bin/env python3
2
"""PreToolUse hook: Block dangerous shell commands."""
3
import json
4
import sys
5

6
BLOCKED_PATTERNS = ["rm -rf", "DROP TABLE", "format c:", "shutdown", "> /dev/sda"]
7

8
def main():
9
    input_data = json.loads(sys.stdin.read())
10
    tool_name = input_data.get("tool_name", "")
11

12
    if tool_name != "Bash":
13
        sys.exit(0)  # Not a bash command, allow it
14

15
    command = input_data.get("tool_input", {}).get("command", "")
16

17
    for pattern in BLOCKED_PATTERNS:
18
        if pattern.lower() in command.lower():
19
            output = {
20
                "decision": "deny",
21
                "reason": f"Blocked: command contains '{pattern}'"
22
            }
23
            print(json.dumps(output))
24
            sys.exit(0)
25

26
    sys.exit(0)  # No blocked pattern found, allow execution
27

28
if __name__ == "__main__":
29
    main()

Without this hook, you would need to write “never run dangerous commands” in your CLAUDE.md and trust that the model always follows the instruction. With this hook, dangerous commands are physically blocked at the execution layer. The agent cannot bypass it, forget it, or reason its way around it.

Prompts vs Hooks: The Reliability Comparison#

This distinction is worth emphasizing because it is the core architectural insight behind hooks.

Figure 3 - Four Approaches to Agent Control: From unreliable prompt reminders to deterministic hooks with intelligent evaluation. The key insight is that hooks and prompts serve different purposes: prompts guide the agent’s approach, hooks enforce non-negotiable constraints. The strongest systems use both.

Hooks do not replace good prompting; they complement it. You still want clear instructions in CLAUDE.md for guidance on how to approach tasks, but for anything that must happen, hooks are the enforcement mechanism.

The Hook Event System#

Claude Code’s hook system supports 12+ event types that span the complete agent lifecycle. Each event fires at a specific point, receives a specific payload, and can influence execution in specific ways.

1
# PostToolUse: Run TypeScript compiler after file writes
2
import subprocess
3

4
result = subprocess.run(
5
    ["npx", "tsc", "--noEmit", "--pretty"],
6
    capture_output=True, text=True, timeout=30
7
)
8

9
if result.returncode != 0:
10
    errors = result.stdout.strip().split("\n")
11
    error_count = len([l for l in errors if ": error TS" in l])
12

13
    output = {
14
        "additionalContext": (
15
            f"TypeScript errors detected: {error_count} error(s). "
16
            f"Fix these before continuing to the next task."
17
        )
18
    }
19
    print(json.dumps(output))

The Three Hook Types#

Hooks are not limited to running shell scripts. Claude Code supports 3 distinct hook types, each suited to different validation needs.

1
{
2
  "type": "command",
3
  "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/validators/lint_on_save.sh"
4
}

1
{
2
  "type": "prompt",
3
  "prompt": "Review this computation output. Does it contain valid risk metrics? Are the numbers in reasonable ranges? Flag anything implausible."
4
}

1
{
2
  "type": "agent",
3
  "prompt": "Review this agent's complete output. Verify all portfolio positions are covered and hedging recommendations include cost estimates. Block completion if anything is missing.",
4
  "tools": "Read, Bash"
5
}

Embedding Hooks in Agent and Skill Definitions#

One of the most important developments is the ability to embed hooks directly in agent definitions and skill definitions, rather than only in the global settings.json . This enables per-agent validation, meaning each agent gets hooks tailored to its specific role and responsibilities.

In a team of agents where one handles CSV data processing and another handles API development, a global hook that validates CSV structure on every file write would be wasteful for the API agent. Conversely, the API agent needs OpenAPI spec validation that would be irrelevant for the CSV agent. Per-agent hooks solve this by co-locating the validation logic with the agent definition.

Figure 8 - Global Hooks vs Per-Agent Hooks: Global hooks apply the same validation to every agent, creating waste and noise when agents have different roles. Per-agent hooks embedded in agent definitions apply only relevant validation to each specialist.

Here is an agent definition with embedded hooks:

1
---
2
name: risk-monitor
3
description: Assesses portfolio risk exposure and recommends hedging strategies.
4
tools: Read, Write, Bash, Glob, Grep
5
model: opus
6
hooks:
7
  PostToolUse:
8
    - matcher: "Write"
9
      hooks:
10
        - type: command
11
          command: "uv run $CLAUDE_PROJECT_DIR/.claude/hooks/validators/validate_risk_metrics.py"
12
    - matcher: "Bash"
13
      hooks:
14
        - type: prompt
15
          prompt: |
16
            Review this computation output. Does it contain valid risk
17
            metrics? Are the numbers in reasonable ranges? Flag anything
18
            implausible.
19
  Stop:
20
    - matcher: "*"
21
      hooks:
22
        - type: agent
23
          prompt: |
24
            Review this agent's complete output. Verify all portfolio
25
            positions are covered and hedging recs include cost estimates.
26
            Block completion if anything is missing.
27
          tools: Read, Bash
28
color: red
29
---
30

31
# Risk Monitor Agent
32
You are a portfolio risk specialist...

Four Architectural Patterns#

Based on research and community implementations, 4 distinct hook architecture patterns have emerged for production use.

1
Agent Decision → PreToolUse Hook → Safety Check → Allow/Deny → Tool Execution

1
#!/usr/bin/env python3
2
"""Safety hook: Enforce file ownership boundaries for team agents."""
3
import json
4
import sys
5
import os
6

7
OWNERSHIP = {
8
    "frontend-dev": ["src/components/", "src/pages/", "src/styles/"],
9
    "backend-dev": ["src/server/", "src/api/", "src/database/"],
10
    "sync-engine": ["src/sync/", "src/crdt/", "src/websocket/"],
11
}
12

13
def main():
14
    input_data = json.loads(sys.stdin.read())
15
    tool_name = input_data.get("tool_name", "")
16

17
    if tool_name not in ("Write", "Edit"):
18
        sys.exit(0)
19

20
    file_path = input_data.get("tool_input", {}).get("file_path", "")
21
    agent_name = os.environ.get("CLAUDE_AGENT_NAME", "")
22

23
    if agent_name not in OWNERSHIP:
24
        sys.exit(0)
25

26
    allowed_dirs = OWNERSHIP[agent_name]
27
    if not any(file_path.startswith(d) for d in allowed_dirs):
28
        output = {
29
            "decision": "deny",
30
            "reason": (
31
                f"Agent '{agent_name}' cannot write to '{file_path}'. "
32
                f"Allowed directories: {', '.join(allowed_dirs)}."
33
            )
34
        }
35
        print(json.dumps(output))
36

37
    sys.exit(0)
38

39
if __name__ == "__main__":
40
    main()

1
Tool Execution → PostToolUse Hook → Quality Check → additionalContext → Agent Adapts

1
{
2
  "hooks": {
3
    "PreToolUse": [{
4
      "matcher": "*",
5
      "hooks": [{
6
        "type": "command",
7
        "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/observability/send_event.py --event pre_tool_use"
8
      }]
9
    }],
10
    "PostToolUse": [{
11
      "matcher": "*",
12
      "hooks": [{
13
        "type": "command",
14
        "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/observability/send_event.py --event post_tool_use"
15
      }]
16
    }],
17
    "PreCompact": [{
18
      "matcher": "*",
19
      "hooks": [{
20
        "type": "command",
21
        "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/observability/log_compaction_loss.py"
22
      }]
23
    }]
24
  }
25
}

1
#!/bin/bash
2
# Stop hook: Validate all features pass before allowing agent to finish
3
INPUT=$(cat)
4

5
INCOMPLETE=$(jq '[.[] | select(.passes == false)] | length' feature_list.json)
6

7
if [ "$INCOMPLETE" -gt 0 ]; then
8
    echo "{\"decision\": \"block\", \"reason\": \"$INCOMPLETE features still incomplete. Cannot finish yet.\"}"
9
    exit 2  # Exit code 2 blocks the stop
10
fi
11

12
exit 0  # All features complete, allow stop

Best Practices#

Start with hooks before scaling to teams. Get your validation, safety, and observability infrastructure working with a single agent before parallelizing. The chaos of multi-agent systems is only manageable with deterministic control already in place.

Match hooks to the agent’s purpose. Per-agent hooks embedded in agent definitions are dramatically more effective than global hooks. Do not apply the same hooks to every agent as it wastes computation and creates noise.

Keep hook scripts fast. Hooks execute synchronously. A slow hook blocks the agent. Linting a single file should take under 5 seconds. If you need heavyweight analysis, use it only on Stop hooks (which run once) rather than PostToolUse hooks (which run on every tool call).

Use additionalContext for feedback beyond simple blocking. The most powerful hook pattern is injecting context that helps the agent self-correct. A PostToolUse hook that tells the agent “3 TypeScript errors found in line 42, 78, and 103” is more useful than one that simply blocks the write.

Log everything in production. Forward all hook events to an observability endpoint. When an agent swarm misbehaves, the hook event log is your primary debugging tool.

Use PreCompact hooks. This is the most underutilized event type, but it reveals critical information about what the agent is forgetting during long sessions. If your agents seem confused after extended work, PreCompact logs will show you what context was lost.

Figure 12 - The Complete Hooks Architecture: All 4 patterns working together: safety (PreToolUse gates), quality (PostToolUse feedback loops), observability (all-event monitoring), and completion (Stop gates). Command hooks enforce safety deterministically. Prompt and agent hooks provide intelligent quality evaluation. Observability hooks capture everything. Together, they make autonomous agents safe, reliable, and debuggable.

Conclusion#

Hooks represent a fundamental architectural insight: autonomous AI agents need deterministic control layers that operate outside the LLM’s reasoning chain. The agent can be creative, adaptive, and autonomous in its problem-solving while hooks enforce the non-negotiable constraints like safety boundaries, quality standards, workflow requirements, and observability guarantees.

The combination of the 3 hook types (command, prompt-based, and agent-based) with per-agent embedding creates a control system that is both rigid where it needs to be (blocking destructive actions) and intelligent where it helps (evaluating code quality with LLM judgment). As agent teams grow larger and more autonomous, hooks become the trust infrastructure that makes scaling possible.

The strongest agent systems do not choose between autonomy and control. They use prompts for guidance and hooks for enforcement. They use creative reasoning for problem-solving and deterministic validation for quality. The agent is free to be intelligent. The hooks make sure it is also reliable.

The Series#

This is part 1 of a 5 part series on Claude Code:

1. Claude Autonomous Coding Overview --- The control layer architecture that makes coding reliable
2. Building Effective Claude Code Agents: From Definition to Production --- Agent definitions, tool restrictions, and least privilege
3. Claude Code Skills: Building Reusable Knowledge Packages for AI Agents --- Progressive disclosure and reusablel knowledge packets
4. Claude Code Hooks: The Deterministic Control Layer for AI Agents (this article) --- PreToolUse, PostToolUse, and deterministic enforcement
5. Claude Code Agent Teams: Building Coordinated Swarms of AI Developers --- Defense-in-depth with agents, skills, hooks, commands, and teams

References#

[1] Anthropic, “Automate workflows with hooks,” Claude Code Documentation, 2025. https://code.claude.com/docs/en/hooks-guide

[2] Disler, “Claude Code Hooks Multi-Agent Observability,” GitHub Repository, 2025. https://github.com/disler/claude-code-hooks-multi-agent-observability

[3] J. Young et al., “Effective harnesses for long-running agents,” Anthropic Engineering Blog, Nov 2025. https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents

[4] Disler, “Agentic Finance Review,” GitHub Repository, 2025. https://github.com/disler/agentic-finance-review

[5] Disler, “Claude Code Hooks Mastery,” GitHub Repository, 2025. https://github.com/disler/claude-code-hooks-mastery

[6] E. Schluntz and B. Zhang, “Building effective agents,” Anthropic Engineering Blog, Dec 2024. https://www.anthropic.com/engineering/building-effective-agents

[7] Anthropic, “Orchestrate teams of Claude Code sessions,” Claude Code Documentation, 2025. https://code.claude.com/docs/en/agent-teams

[8] Anthropic, “Extend Claude Code,” Claude Code Documentation, 2025. https://code.claude.com/docs/en/features-overview

[9] N. Carlini, “Building a C compiler with a team of parallel Claudes,” Anthropic Engineering Blog, Feb 2025. https://www.anthropic.com/engineering/building-c-compiler

[10] Anthropic, “Skill authoring best practices,” Claude Platform Documentation, 2025. https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices

[11] A. Osmani, “Claude Code Swarms,” AddyOsmani.com, Feb 2026. https://addyosmani.com/blog/claude-code-agent-teams/

[12] Anthropic, “Create plugins,” Claude Code Documentation, 2025. https://code.claude.com/docs/en/plugins