Hooks Overview

Claude Code hooks let you run shell commands automatically at key points in the agent lifecycle. They are the extensibility mechanism for the Code Factory system — safety validation, observability, context injection, and automated quality checks all run as hooks.

Configuration

Hooks are configured in settings files:

• ~/.claude/settings.json — User settings (global, all projects)
• .claude/settings.json — Project settings (committed to repo)
• .claude/settings.local.json — Local project settings (not committed)

Structure

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here"
          }
        ]
      }
    ]
  }
}

matcher rules:

• Write — matches exactly the Write tool
• Edit|Write — matches either Edit or Write
• Notebook.* — regex: any Notebook tool
• * or "" — matches all tools (only for PreToolUse/PostToolUse)

hook properties:

• type — currently only "command" is supported
• command — the bash command to execute
• timeout — optional, seconds before the command is cancelled

Code Factory Hook Profile

The Code Factory includes three hook tiers that can be activated:

Minimal — safety only

• Block .env access attempts
• Block rm -rf with path validation

Standard — safety + observability

• All minimal hooks
• Log every tool call to logs/
• Heartbeat on agent stop

Strict — full validation

• All standard hooks
• Code style validation on Write/Edit
• Security scan on Bash commands
• Test verification on completion

Available Hook Events

Event	When it fires	Common uses
PreToolUse	Before any tool call	Block dangerous operations, validate inputs
PostToolUse	After tool call completes	Log activity, run style checks
Notification	Permission requests, idle notifications	Desktop notifications
UserPromptSubmit	When user submits a message	Inject context, validate prompts
Stop	When main agent finishes responding	Run cleanup, trigger follow-up
SubagentStop	When a subagent finishes	Aggregate results
PreCompact	Before context compaction	Save state before compacting
SessionStart	On session start or resume	Load project context

Quick Start: Safety Hook

The most common hook to add — blocks accidental .env reads and destructive deletions:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/security-validator.js"
          }
        ]
      }
    ]
  }
}

Quick Start: Observability Hook

Log every tool call to a session log:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/log-tool-use.sh"
          }
        ]
      }
    ]
  }
}

Configuration Safety

Direct edits to hooks in settings files don't take effect immediately:

1. Claude Code captures a snapshot of hooks at startup
2. Uses this snapshot throughout the session
3. Warns if hooks are modified externally
4. Requires review in /hooks menu for changes to apply

This prevents malicious hook modifications from affecting your current session.