Imported from AndreHahm/andres-cc-marketplace (plugins/plugin-devkit/skills/hook-development/SKILL.md). Install upstream with npx skills add AndreHahm/andres-cc-marketplace --skill hook-development. Copyright stays with the author.

Hook Development for Claude Code Plugins

Hooks are event-driven automation scripts that execute in response to Claude Code events. Use them to validate operations, enforce policies, add context, and integrate external tools.

Key capabilities: validate before tool runs (PreToolUse), react to results (PostToolUse), enforce completion standards (Stop), load project context (SessionStart).

Quick Start

1. Detect project type — check for .claude-plugin/plugin.json; if present, hooks go to hooks/hooks.json; otherwise to .claude/hooks.json
2. Choose an event — PreToolUse (validate before), PostToolUse (react after), Stop (completion check), SessionStart (context loading)
3. Pick a hook type — prompt (LLM reasoning), command (deterministic bash), or agent (requires file inspection)
4. Write configuration — use the nested "hooks": [...] array (see CRITICAL section below)
5. For command hooks — read event data from stdin, not environment variables (see CRITICAL section below)
6. Validate — run scripts/validate-hook-schema.sh and shellcheck on scripts
7. Test — use scripts/test-hook.sh with sample input, then claude --debug live

For the full 13-step workflow with tooling auto-detection, lint, and documentation steps, see Implementation Workflow below.

When to Use

• Adding validation before tool calls (file writes, bash commands, API calls)
• Enforcing project policies at runtime without editing every command
• Loading project context or env vars at session start
• Verifying Claude completes tasks fully before stopping
• Logging, alerting, or auditing tool usage

When NOT to Use

• For one-time prompts — use slash commands instead
• For global config changes — modify settings.json directly
• Never edit ~/.claude/plugins/cache/ — those are read-only installed copies
• Reviewing an existing hook's quality/safety before deployment → use the hook-reviewer agent instead

Finding-ID Fix Mode

When invoked with a bounded finding-ID list (e.g. from plugin-lifecycle-downstream's Phase 4/6/8), follow plugin-rulebook/references/finding-id-fix-contract.md instead of this skill's normal open-ended workflow: touch only the named findings' files, report per-ID applied/deferred/failed status, and never mark a fix verified — that stays the originating checker's job.

CRITICAL: Hook File Location

Most common mistake: placing hooks in .claude-plugin/hooks.json (WRONG).

✅ Correct locations:

• Plugin projects (has .claude-plugin/plugin.json): hooks/hooks.json at plugin root
• Regular projects (no .claude-plugin/): .claude/hooks.json

❌ Wrong: .claude-plugin/hooks.json — only plugin.json belongs in .claude-plugin/

Auto-detect: check for .claude-plugin/plugin.json; its presence means plugin project. If hooks aren't firing, check file location first.

CRITICAL: Command Hooks Receive Data via Stdin

The #1 reason command hooks silently do nothing: expecting environment variables instead of reading stdin.

❌ WRONG — env var substitution does NOT work:

{ "env": {"FILE_PATH": "${arguments.file_path}"} }

✅ CORRECT — read ALL event data from stdin as JSON:

#!/bin/bash
INPUT=$(cat)                                          # Read all event data from stdin
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path')
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')

See references/command-hook-input-parsing.md for correct field paths per event type.

CRITICAL: Nested "hooks" Array JSON Structure

The #1 JSON mistake: forgetting the nested "hooks": [...] array inside each event matcher.

✅ CORRECT — required for all hooks:

{
  "hooks": {
    "EventName": [
      {
        "matcher": "regex-pattern",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/script.sh",
            "timeout": 5000,
            "onError": "warn"
          }
        ]
      }
    ]
  }
}

❌ WRONG — produces "Expected array, but received undefined":

{
  "hooks": {
    "EventName": [{ "type": "command", "command": "..." }]
  }
}

Every hook action (command, http, mcp_tool, prompt, agent) must be inside a "hooks": [...] array.

Hook Types

Five action types: prompt (LLM-driven, flexible), command (bash, deterministic), agent (multi-turn, file inspection), http (webhook), mcp_tool (calls an installed MCP server tool). Full field reference and JSON example per type: references/hook-types.md (mcp_tool has its own dedicated reference, references/mcp-tools.md).

Type decision:

Not every type is valid for every event (e.g. SessionStart supports only command and mcp_tool) — validate the type/event combination, not just each independently. Full compatibility matrix: references/event-reference.md.

Hook Configuration Formats

Plugin Format (hooks/hooks.json)

{
  "description": "Optional description",
  "hooks": {
    "PreToolUse": [...],
    "Stop": [...],
    "SessionStart": [...]
  }
}

Settings Format (.claude/settings.json or .claude/hooks.json)

{
  "PreToolUse": [...],
  "Stop": [...],
  "SessionStart": [...]
}

Events go directly at the top level — no wrapper object. Plugin hooks merge with user hooks and run in parallel. Settings format also supports a top-level disableAllHooks boolean key to disable every configured hook at once — verify whether this applies to plugin hooks/hooks.json too before relying on it there.

hooks/hooks.json has only two top-level keys: description and hooks — verify this against the current platform schema before enforcing it. Shared team hooks belong in .claude/settings.json (checked into version control) — never in .claude/settings.local.json, which is personal and gitignored.

Hook Handler Fields

All handlers:

Command-only:

Prompt/Agent-only:

HTTP-only:

MCP Tool-only:

Hook Events

This is not the full event list — Claude Code also ships Setup, UserPromptExpansion, PostToolBatch, MessageDisplay, TeammateIdle, TaskCreated, TaskCompleted, WorktreeRemove, CwdChanged, PermissionDenied, StopFailure, InstructionsLoaded, ConfigChange, FileChanged, PostCompact, Elicitation, and ElicitationResult. Full list, per-event payloads, and the hook-type/event compatibility matrix: references/event-reference.md.

⚠️ Stop/SubagentStop infinite loop guard — always check stop_hook_active:

INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # Already in hook-triggered continuation — allow stop
fi

For per-event data payloads, timing, matcher values, and output schemas, see references/event-reference.md and references/decision-schemas.md.

Matchers

"matcher": "Write"           // Exact tool name
"matcher": "Read|Write|Edit" // Multiple tools
"matcher": "*"               // All tools (use sparingly)
"matcher": "mcp__.*__delete" // Regex — all MCP delete tools

Matchers are case-sensitive. Events that match on something other than tool name:

Environment Variables

Available in a hooks/hooks.json/.claude/hooks.json command hook:

A skill/agent frontmatter-embedded hooks: block is different — never use a bare relative path. Official docs state hook handlers "run in the current directory," i.e. the live session cwd (which tracks cd/worktree changes), not the skill's own directory, so a bare relative path resolves unpredictably depending on where Claude happens to be when the hook fires. Which variable to use instead depends on distribution: $CLAUDE_PROJECT_DIR with the full path for a project-level skill never distributed elsewhere ($CLAUDE_PLUGIN_ROOT is confirmed broken there — no enclosing plugin to resolve against); $CLAUDE_PLUGIN_ROOT for a plugin-nested skill meant for distribution (a real end-user's $CLAUDE_PROJECT_DIR won't contain this plugin's own source tree). See references/component-scoped-hooks.md's "Environment Variables Available" section for the full reasoning.

Exit Codes & Output Contract

Some events have exceptions to this contract (e.g. SessionStart never blocks) — see references/exit-code-behavior.md. Blocking/error messages go to stderr; informational context output goes to stdout.

A hook must pick one signaling mode: exit-code mode, or structured JSON on stdout with exit 0. JSON output is ignored whenever the exit code is 2. All hook output (stdout, additionalContext, systemMessage) is capped at 10,000 characters — summarize large results and write details to a file. HTTP hooks cannot block via a non-2xx status; return 2xx with a JSON decision body instead.

Full semantics and JSON schemas: references/exit-code-behavior.md, references/decision-schemas.md.

Performance & Safety

• Each hook should complete in under 5 seconds; hooks that regularly exceed this may be disabled by Claude Code
• Keep total hook execution time across all matching hooks under ~30 seconds with parallel processing
• Filter by event type, tool name, file path, and extension before doing expensive work — never scan the whole project inside a hook
• Cap displayed findings to 5-10 items; emit a summary line if more exist
• Prefer Python for cross-platform hook scripts; use pathlib.Path for all paths — never hardcode /tmp/ or OS-specific separators. Portable runner fallback: uv → python3 → python (see references/patterns-and-templates.md)
• Never use shell=True with string commands — use list arguments. Parse stdin as structured JSON and never interpolate raw input into shell commands (see references/patterns-and-templates.md and references/validation-guide.md)
• Command hooks run with the full permissions of the current system user — treat every hook script as privileged local code
• Hooks must not open /dev/tty or send escape sequences directly to the interface; use the JSON systemMessage field instead

Common Workflow Patterns

Implementation Workflow

For a hooks/hooks.json/.claude/hooks.json hook. For a skill/agent frontmatter-embedded hooks: block instead, see references/component-scoped-hooks.md — step 7 below does not apply there.

1. Detect project type — check for .claude-plugin/plugin.json to pick correct hooks file location
2. Auto-detect tooling to suggest relevant hooks:
   • tsconfig.json → PostToolUse type-check hook
   • .prettierrc → PostToolUse auto-format hook
   • .eslintrc.* → PostToolUse lint hook
   • package.json with test script → Stop test-validation hook
   • Git repository → PreToolUse security scan hook
3. Identify events — use the Hook Events table above
4. Choose hook type — prompt (flexible), agent (requires file inspection), command (deterministic)
5. Write configuration — ensure nested "hooks": [...] array is present
6. For command hooks — read all data from stdin (INPUT=$(cat))
7. Use ${CLAUDE_PLUGIN_ROOT} for all file references (this step is hooks.json-specific — see the note above)
8. Add stop_hook_active guard to all Stop/SubagentStop hooks
9. Validate configuration — scripts/validate-hook-schema.sh hooks/hooks.json
10. Lint scripts — shellcheck scripts/my-hook.sh
11. Test happy and sad paths — scripts/test-hook.sh with valid and invalid inputs
12. Test live — claude --debug; look for hook registration and execution logs
13. Document hooks in plugin README; validate against references/validation-guide.md

Optional (TDD-style): define the behavior violation you want to prevent first, then write the hook, then review.

Testing & Validation

After writing or modifying hooks:

1. JSON structure — jq empty hooks/hooks.json && echo "Valid" before anything else
2. Schema validation — scripts/validate-hook-schema.sh hooks/hooks.json
3. Script lint — shellcheck scripts/my-hook.sh for all command hook scripts
4. Manual test — pipe sample event JSON and check exit code and stdout:

   bash scripts/my-hook.sh <<< '{"tool_name":"Write","tool_input":{"file_path":"/test.txt"}}'
   echo "Exit: $?"

5. Live test — restart Claude Code, trigger the hooked event, check claude --debug output

Quality gates:

• jq empty passes on hooks.json
• shellcheck passes on all hook scripts (zero warnings)
• Happy path: valid input → hook passes (exit 0)
• Sad path: invalid/blocked input → hook fires correctly (exit 2 + stderr)
• Stop hooks include stop_hook_active guard
• scripts/validate-hook-schema.sh reports no errors

Deep Test coverage for a hook: step 4's "Manual test" above exercises one sample input by hand — Deep Test coverage means running scripts/test-hook.sh --create-sample <event-type> for every event type the hook's own matcher in hooks.json actually configures it to receive, then running scripts/test-hook.sh against each generated sample (a happy-path input and, where meaningful, a blocked-path input) rather than just one. scripts/test-hook.sh --json/--yaml emits a machine-readable status: pass|fail result per run (plus exit_code/classification/output) so a caller aggregating results across every event type — e.g. plugin-lifecycle-downstream's optional Deep Test step — doesn't have to parse the human-readable text output.

Verify this skill activates on:

• "add a hook to this plugin" / "write hooks.json"
• "implement PreToolUse validation to block dangerous commands"
• "auto-format on every file write" / "enforce completion standards with a Stop hook"
• "load session context at startup" / "automate a response to a Claude Code event"

Verify it does NOT activate on:

• "just run this once" → a slash command, not a hook
• "change a global config setting" → edit settings.json directly instead
• "review this existing hook's quality/safety before I ship it" → the hook-reviewer agent instead

Last dated run record: 2026-08-30, evals/hook-development/ — 3/3 scenarios, 8/8 assertions passed (Quick Workflow, with_skill only — see evals/hook-development/evals.json). 2 of 4 declared trigger scenarios aren't yet exercised by an eval (auto-format-on-write, session-context loading) — see evals.json's testing_validation_coverage field.

Additional Resources