sharkitect-solutions/hook-development

Hook Development for Claude Code Plugins

File Index

| File | Purpose | When to Load | |------|---------|--------------| | examples/load-context.sh | SessionStart context-loading script | Building SessionStart hooks or detecting project type | | examples/validate-bash.sh | Bash command validation patterns | Building PreToolUse hooks for Bash tool | | examples/validate-write.sh | File write validation patterns | Building PreToolUse hooks for Write/Edit tools | | references/advanced.md | Multi-stage validation, cross-event workflows, caching, external integrations | Complex hook architectures, performance optimization, state sharing | | references/migration.md | Converting command hooks to prompt hooks | Refactoring existing hooks or choosing between hook types | | references/patterns.md | 10 proven hook patterns (security, test enforcement, context loading, MCP monitoring, etc.) | Starting a new hook -- find the closest pattern first | | scripts/hook-linter.sh | Lint hook scripts for common issues | Before deploying any command hook script | | scripts/README.md | Usage guide for all utility scripts | First time using the development tools | | scripts/test-hook.sh | Test hooks with sample input | Before deploying hooks to Claude Code | | scripts/validate-hook-schema.sh | Validate hooks.json structure | After editing any hooks.json configuration |

Scope Boundary

This skill covers hooks within the Claude Code plugin system ONLY. Hooks are bash scripts or LLM prompts triggered by Claude Code events.

| In Scope | Out of Scope | |----------|-------------| | Plugin hooks.json configuration | General webhook/API development | | Prompt-based and command hooks | GitHub Actions / CI pipelines | | Hook event lifecycle | Server-side event systems | | Matcher patterns for Claude tools | MCP server development (use mcp skill) | | ${CLAUDE_PLUGIN_ROOT} usage | Claude Desktop configuration |

Hook Type Decision

| Signal | Choose Prompt Hook | Choose Command Hook | |--------|-------------------|-------------------| | Needs context-aware reasoning | Yes | No | | Catches intent, not just patterns | Yes | No | | Needs to run in < 50ms | No | Yes | | Purely deterministic check (file size, regex) | No | Yes | | Integrates external CLI tool | No | Yes | | Needs to set environment vars | No | Yes (SessionStart only) | | Complex multi-criteria validation | Yes | No |

Prompt hooks support: PreToolUse, PostToolUse, Stop, SubagentStop, UserPromptSubmit. Command hooks support: ALL events (including SessionStart, SessionEnd, PreCompact, Notification).

Configuration Format (CRITICAL -- Two Different JSON Structures)

Plugin hooks and settings hooks use DIFFERENT JSON structures. Confusing them is the most common hook bug.

Plugin format -- hooks/hooks.json in a plugin directory:

{
  "description": "Optional description",
  "hooks": {
    "PreToolUse": [{ "matcher": "Write", "hooks": [{ "type": "prompt", "prompt": "..." }] }]
  }
}

The "hooks" wrapper key is REQUIRED. Events nest inside it.

Settings format -- .claude/settings.json or .claude.json:

{
  "hooks": {
    "PreToolUse": [{ "matcher": "Write", "hooks": [{ "type": "prompt", "prompt": "..." }] }]
  }
}

Events go directly under "hooks" alongside other settings keys.

Both formats merge at runtime. Plugin hooks and settings hooks run in parallel.

Event Selection Guide

| Event | Fires When | Best For | Output Controls | |-------|-----------|----------|----------------| | PreToolUse | Before tool executes | Approve/deny/modify tool calls | permissionDecision: allow, deny, ask; updatedInput | | PostToolUse | After tool completes | Feedback, logging, quality checks | systemMessage to Claude | | Stop | Main agent wants to stop | Completeness verification | decision: approve or block | | SubagentStop | Subagent wants to stop | Subagent task validation | decision: approve or block | | UserPromptSubmit | User submits prompt | Context injection, prompt validation | systemMessage, can block | | SessionStart | Session begins | Load context, set env vars | $CLAUDE_ENV_FILE for persisting env | | SessionEnd | Session ends | Cleanup, logging | Fire-and-forget | | PreCompact | Before context compaction | Preserve critical information | systemMessage survives compaction | | Notification | Claude sends notification | External integrations, logging | Fire-and-forget |

Hook Lifecycle (Non-Obvious Behavior)

1. Loaded at session start ONLY. Editing hooks.json or hook scripts mid-session has zero effect. Must restart Claude Code.
2. All matching hooks run in parallel. Multiple hooks in the same matcher array execute simultaneously. They cannot see each other's output. Design for independence.
3. Plugin + settings hooks merge. A plugin's PreToolUse hooks and the user's settings PreToolUse hooks ALL run in parallel together.
4. Invalid JSON = silent failure. Bad hooks.json prevents ALL hooks from loading. Always validate with scripts/validate-hook-schema.sh.
5. Use /hooks command to inspect which hooks are loaded in the current session.
6. Use claude --debug to see hook registration, execution logs, input/output JSON, and timing.

Exit Code Semantics

| Exit Code | Meaning | Behavior | |-----------|---------|----------| | 0 | Success | stdout shown in transcript | | 2 | Blocking error | stderr fed back to Claude as context | | Other | Non-blocking error | Logged but does not block |

For PreToolUse: exit 2 with permissionDecision: "deny" blocks the tool call. For Stop: exit 2 with decision: "block" prevents the agent from stopping.

Hook Input (stdin JSON)

All hooks receive JSON via stdin. Common fields:

• session_id, transcript_path, cwd, permission_mode, hook_event_name

Event-specific fields:

• PreToolUse/PostToolUse: tool_name, tool_input, tool_result (PostToolUse only)
• UserPromptSubmit: user_prompt
• Stop/SubagentStop: reason

In prompt hooks, access via: $TOOL_INPUT, $TOOL_RESULT, $USER_PROMPT. In command hooks, parse with: input=$(cat) then jq -r '.tool_name'.

Matcher Patterns

"Write"              -- exact tool name
"Write|Edit"         -- multiple tools (pipe-separated)
"*"                  -- all tools (wildcard)
"mcp__.*"            -- regex: all MCP tools
"mcp__asana__.*"     -- regex: specific MCP server's tools
"mcp__.*__delete.*"  -- regex: all MCP delete operations

Matchers are case-sensitive. Regex uses standard patterns (no delimiters).

Environment Variables (Command Hooks)

| Variable | Available In | Purpose | |----------|-------------|---------| | $CLAUDE_PROJECT_DIR | All events | Project root path | | $CLAUDE_PLUGIN_ROOT | All events | Plugin directory (use for portable paths) | | $CLAUDE_ENV_FILE | SessionStart ONLY | Append export KEY=val to persist env vars | | $CLAUDE_CODE_REMOTE | All events | Set if running in remote context |

ALWAYS use ${CLAUDE_PLUGIN_ROOT} in hooks.json commands. Never hardcode paths.

Bash Hook Script Template

#!/bin/bash
set -euo pipefail
input=$(cat)
tool_name=$(echo "$input" | jq -r '.tool_name // empty')
# ... validation logic ...
# Approve: exit 0
# Block: echo '{"hookSpecificOutput":{"permissionDecision":"deny"},"systemMessage":"reason"}' >&2 && exit 2
exit 0

See examples/ for complete working scripts. Run scripts/hook-linter.sh before deploying.

Implementation Workflow

1. Identify which event to hook (use Event Selection Guide above)
2. Choose prompt vs command hook (use Hook Type Decision table above)
3. Check references/patterns.md for a matching pattern
4. Write hook config in hooks/hooks.json (use correct format -- plugin wrapper)
5. For command hooks: write script, lint with scripts/hook-linter.sh, test with scripts/test-hook.sh
6. Validate config: scripts/validate-hook-schema.sh hooks/hooks.json
7. Test in Claude Code: claude --debug
8. Iterate -- remember to restart session after each hooks.json change

Rationalization Table

| Concept | Why It Earns Space | |---------|--------------------| | Two JSON configuration formats | Most common hook bug -- plugin wrapper vs settings direct structure | | Hook lifecycle (load-once, parallel execution) | Non-obvious runtime behavior that causes debugging confusion | | Exit code semantics (0 vs 2 vs other) | Determines whether hooks block operations or just log | | Event selection guide with output controls | Each event has unique output capabilities that affect what hooks can do | | Matcher regex patterns for MCP tools | MCP tool naming convention is not documented elsewhere | | File Index with load conditions | 10 companion files need clear routing to avoid information overload |

Red Flags

1. Editing hooks mid-session and expecting changes -- hooks only load at session start
2. Using settings JSON format in plugin hooks.json -- missing the "hooks" wrapper key
3. Assuming hook execution order -- all matching hooks run in parallel, non-deterministic
4. Hardcoding absolute paths -- use ${CLAUDE_PLUGIN_ROOT} for portability
5. Using prompt hooks for SessionStart/SessionEnd/PreCompact/Notification -- these events only support command hooks
6. Forgetting set -euo pipefail in bash hook scripts -- silent failures on errors
7. Writing to stdout when intending to block -- blocking output must go to stderr with exit 2
8. Not quoting bash variables -- injection vulnerability ("$var" not $var)

NEVER

1. NEVER assume hooks execute in a specific order -- they run in parallel
2. NEVER modify hooks.json and expect current session to pick up changes
3. NEVER hardcode file paths in hooks.json commands -- always use ${CLAUDE_PLUGIN_ROOT}
4. NEVER use prompt hooks for SessionStart, SessionEnd, PreCompact, or Notification events
5. NEVER output blocking errors to stdout -- use stderr (>&2) with exit code 2