Hook Scope Guide

Hook Scope Decision Guide

Overview

This skill helps you choose the right location for Claude Code hooks based on their purpose, audience, and persistence needs.

When NOT To Use

• Writing the hook itself (use abstract:hook-authoring)
• Scoring an existing hook (use abstract:hooks-eval)

Important: Auto-Loading Behavior

hooks/hooks.json is automatically loaded by Claude Code when the plugin is enabled. Do NOT add "hooks": "./hooks/hooks.json" to your plugin.json - this causes duplicate load errors. The hooks field in plugin.json is only needed for additional hook files beyond the standard hooks/hooks.json.

The Three Scopes

Decision Framework

Question 1: Who needs this hook?

Only plugin users → Plugin hooks

• Hook is part of plugin's core functionality
• Users expect it when they enable your plugin
• Example: A YAML plugin validates YAML syntax on edit

All team members on this project → Project hooks

• Codebase-specific rules or protections
• Team conventions that should be enforced
• Example: Block modifications to /src/production/ configs

Only me, everywhere → Global hooks

• Personal preferences or workflow optimizations
• Cross-project utilities like logging
• Example: Log all bash commands to personal audit trail

Question 2: Should this be version controlled?

Yes, as part of a distributable plugin → Plugin hooks Yes, shared with team in repo → Project hooks No, keep private → Global hooks

Question 3: What's the persistence requirement?

Only when my plugin is active → Plugin hooks Always in this specific project → Project hooks Always, in every project I work on → Global hooks

Scope Details

Plugin Hooks

Location: <plugin-root>/hooks/hooks.json

When to use:

• The hook is intrinsic to your plugin's functionality
• It should automatically activate when users enable your plugin
• It only makes sense in the context of your plugin's features

Configuration:

{
  "PreToolUse": [
    {
      "matcher": "Read",
      "hooks": [{
        "type": "command",
        "command": "echo \"Plugin reading: $(jq -r '.tool_input.file_path')\" >> ${CLAUDE_PLUGIN_ROOT}/log.txt"
      }]
    }
  ]
}

Note: Use string matchers ("Read") not object matchers ({"toolName": "Read"}).

Key features:

• Use ${CLAUDE_PLUGIN_ROOT} for plugin-relative paths
• Auto-merges when plugin is enabled
• Deactivates when plugin is disabled

Examples:

• Validation hook for a linting plugin
• Auto-formatting hook for a code style plugin
• Logging hook for a debugging plugin

Project Hooks

Location: .claude/settings.json (in project root)

When to use:

• Enforcing team-wide policies
• Protecting project-specific resources
• Codebase conventions that should survive across team members
• Rules that should be reviewed in PRs

Configuration:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "cmd=$(jq -r '.tool_input.command // empty'); if [[ \"$cmd\" == *\"production\"* ]]; then echo 'BLOCKED: Production access requires approval'; exit 1; fi"
        }]
      }
    ]
  }
}

Note: Use string matchers ("Bash") not object matchers.

Key features:

• Committed to version control
• Shared across all team members
• Changes are visible in PRs (governance trail)
• Project-specific, not personal

Examples:

• Block modifications to production configs
• Require test commands before completion
• Warn about editing sensitive directories
• Enforce project naming conventions

Global Hooks

Location: ~/.claude/settings.json

When to use:

• Personal workflow preferences
• Cross-project utilities
• Organization-wide compliance you want everywhere
• Private rules that shouldn't be shared

Configuration:

{
  "hooks": {
    "PreToolUse": [
      {
        "hooks": [{
          "type": "command",
          "command": "echo \"$(date): $(jq -r '.tool_name')\" >> ~/.claude/audit.log"
        }]
      }
    ]
  }
}

Key features:

• Never committed to any repo
• Applies to ALL Claude Code sessions
• Personal to your user account
• Survives across projects

Examples:

• Personal audit logging
• Cross-project safety rules
• Custom notification integrations
• Development environment preferences