Hooks and Guardrails

Configuration and structure

Hooks are configured in settings files, not in markdown files like skills and agents:

Hooks can also be defined inside skill and agent frontmatter, scoped to that component's lifetime.

The configuration structure has three levels:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "eslint --stdin-filename \"$FILE\"",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

1. Event name — when to fire (PreToolUse, PostToolUse, SessionStart, etc.)
2. Matcher — which specific tool, file, or trigger to match
3. Hook handlers — what to execute (command, HTTP, prompt, or agent)

When hooks fire

Claude Code has dozens of hook events. Here are the ones that matter most for developer workflows.

Tool execution events — the workhorses:

Session events:

File events:

The matcher field on tool events filters by tool name. "matcher": "Edit" means the hook only fires on Edit tool calls. "matcher": "Bash" fires on Bash. You can also use regex patterns: "matcher": "Edit|Write" fires on either.

The critical behaviour of PreToolUse: A PreToolUse hook that returns exit code 2 (for command hooks) or a block decision prevents the tool from executing entirely. Claude receives feedback that the action was blocked and why, and it must adjust its approach. This is the mechanism for hard enforcement.

Four ways to handle an event

1. Command hooks — run a shell command:

{
  "type": "command",
  "command": "eslint --fix $FILE",
  "timeout": 30
}

The command receives event data as JSON on stdin. It returns decisions via exit code and stdout:

• Exit 0 — success (proceed normally)
• Exit 2 — block (prevent the action, send stderr to Claude as feedback)
• Any other exit — non-blocking error (logged but action proceeds)

2. HTTP hooks — POST to an endpoint:

{
  "type": "http",
  "url": "http://localhost:8080/hooks/pre-edit",
  "timeout": 30,
  "headers": {
    "Authorization": "Bearer $TOKEN"
  }
}

The endpoint receives the event payload and returns a JSON response with a decision. Useful for integrating with external systems — CI/CD, audit logging, notification services.

3. Prompt hooks — single-turn LLM evaluation:

{
  "type": "prompt",
  "prompt": "Is this bash command safe to execute in a development environment? The command is: $ARGUMENTS",
  "model": "claude-haiku-4-5"
}

A fast, lightweight LLM call that returns a yes/no decision with reasoning. Uses a small model by default for speed. Useful for nuanced evaluations that are hard to express as shell script logic.

4. Agent hooks — multi-turn subagent with tool access:

{
  "type": "agent",
  "prompt": "Verify that this code change follows our security standards. $ARGUMENTS",
  "model": "claude-sonnet-4-6"
}

The most powerful handler. A subagent can read files, run commands, and make a complex decision. Use sparingly — agent hooks are slower than command hooks.

Three hooks you should configure

Hook 1: Auto-lint after edits

The most common hook. Runs your linter after every file edit so you never commit unlinted code:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write \"$FILE\" 2>/dev/null; eslint --fix \"$FILE\" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

The || true ensures the hook does not block even if linting finds unfixable issues — it formats what it can and lets Claude continue.

Hook 2: Block dangerous bash commands

Prevent Claude from running destructive commands:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate if this bash command is safe for a development environment. Block if it: deletes files outside the project, force-pushes to main/master, drops databases, or modifies system configuration. The command: $ARGUMENTS",
            "model": "claude-haiku-4-5"
          }
        ]
      }
    ]
  }
}

This uses a prompt hook — a fast LLM call that evaluates the command semantically. It catches rm -rf /, git push --force origin main, DROP TABLE, and similar dangerous patterns even if they are disguised or combined with other commands.

Hook 3: Protected files

Prevent edits to specific files that should not be modified during normal development:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit",
        "if": "Edit(.env*)",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'BLOCKED: Cannot edit .env files through Claude Code. Manage environment variables through your secrets manager.' >&2; exit 2"
          }
        ]
      }
    ]
  }
}

Exit code 2 blocks the action. The stderr message is sent to Claude as feedback, so it knows why the edit was blocked and can adjust.

Component-scoped hooks

Hooks defined in skill and agent frontmatter are scoped to that component's lifetime. They activate when the skill loads or the agent starts, and deactivate when it completes.

---
name: safe-deploy
description: Deployment workflow with built-in safety hooks
user-invocable: true
disable-model-invocation: true
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "echo 'Deploy step:' && cat /dev/stdin | jq -r '.tool_input.command'"
  Stop:
    - hooks:
        - type: command
          command: "echo 'Deployment skill completed' >> deploy.log"
---

# Deployment Procedure
...

This deploy skill logs every bash command it runs and records completion in a log file. These hooks only fire while the deploy skill is active — they do not affect normal development work.

For agents, a Stop hook in the frontmatter automatically converts to SubagentStop, firing when the agent completes. Use this for cleanup operations — removing temp files, posting results to a channel, updating a status dashboard.