athola/hook-scope-guide

Hook Scope Decision Guide

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

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

| Scope | Location | Audience | Committed? | Persistence | |-------|----------|----------|------------|-------------| | Plugin | hooks/hooks.json in plugin | Plugin users | With plugin | When plugin enabled | | Project | .claude/settings.json | Team members | Yes (repo) | Per project | | Global | ~/.claude/settings.json | Only you | Never | All sessions |

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: $CLAUDE_TOOL_INPUT' >> ${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": "if [[ \"$CLAUDE_TOOL_INPUT\" == *\"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): $CLAUDE_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

Loading Order & Precedence

Claude Code loads settings in this priority (highest first):

1. Enterprise policies (organization-managed)
2. Command-line arguments (claude --flag)
3. Local project settings (.claude/settings.local.json)
4. Shared project settings (.claude/settings.json)
5. User settings (~/.claude/settings.json)

Important: Multiple hooks from different scopes can respond to the same event. When they do, all matching hooks execute in parallel.

Quick Reference: Scope Selection

Is this hook part of a plugin's core functionality?
├─ YES → Plugin hooks (hooks/hooks.json in plugin)
└─ NO ↓

Should all team members on this project have this hook?
├─ YES → Project hooks (.claude/settings.json)
└─ NO ↓

Should this hook apply to all my Claude sessions?
├─ YES → Global hooks (~/.claude/settings.json)
└─ NO → Reconsider if you need a hook at all

Security Considerations

Plugin hooks:

• Audited as part of plugin installation
• Users consent when enabling plugin
• Scope limited to plugin's purpose

Project hooks:

• Visible to all team members
• Changes reviewed in PRs
• Should reflect team consensus

Global hooks:

• Execute with your credentials everywhere
• Can affect all projects unexpectedly
• Review security implications carefully
• Test thoroughly before adding

Common Patterns by Scope

Plugin Hook Patterns

• Validation: Check files match plugin's format
• Auto-completion: Suggest plugin-specific completions
• Logging: Track plugin-specific operations

Project Hook Patterns

• Protection: Block dangerous operations on sensitive paths
• Enforcement: Require tests, linting, or builds
• Conventions: Warn about style or naming violations

Global Hook Patterns

• Auditing: Log all operations for personal review
• Safety: Universal dangerous command detection
• Integration: Personal tool notifications

SessionStart Hook Enhancements (Claude Code 2.1.2+)

SessionStart hooks now receive additional input fields via stdin:

| Field | Type | Description | |-------|------|-------------| | session_id | string | Unique session identifier | | source | enum | "startup" | "resume" | "clear" | "compact" | | agent_type | string | Agent name if --agent flag used, empty otherwise |

Agent-Aware Hooks

The agent_type field enables scope-appropriate context injection:

# Skip heavy context for review agents
input_data = json.loads(sys.stdin.read())
if input_data.get("agent_type") in ["code-reviewer", "quick-query"]:
    print(json.dumps({"hookSpecificOutput": {"additionalContext": "Minimal"}}))

This is particularly useful for:

• Plugin hooks: Reduce overhead for lightweight agents
• Project hooks: Skip governance for review-only agents
• Global hooks: Customize logging verbosity per agent

Related Skills

• abstract:hook-authoring - For hook rule syntax and patterns
• abstract:validate-plugin - For validating plugin structure including hooks

References

• Claude Code Hooks Documentation
• Settings Configuration