hook-development

# Hook Development for Claude Code Plugins ## Overview Hooks are event-driven automation scripts that execute in response to Claude Code events. Use hooks to validate operations, enforce policies, add context, and integrate external tools into workflows. **Key capabilities:** - Validate tool calls before execution (PreToolUse) - React to tool results (PostToolUse) - Enforce completion standards (Stop, SubagentStop) - Load project context (SessionStart) - Automate workflows across the development lifecycle ## Hook Types ### Prompt-Based Hooks (Recommended) Use LLM-driven decision making for context-aware validation: ```json { "type": "prompt", "prompt": "Evaluate if this tool use is appropriate: $TOOL_INPUT", "timeout": 30 } ``` **Supported events:** Stop, SubagentStop, UserPromptSubmit, PreToolUse **Benefits:** - Context-aware decisions based on natural language reasoning - Flexible evaluation logic without bash scripting - Better edge case handling - Easier to maintain and extend ### Command Hooks Execute bash commands for deterministic checks: ```json { "type": "command", "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh", "timeout": 60 } ``` **Use for:** - Fast deterministic validations - File system operations - External tool integrations - Performance-critical checks ## Hook Configuration Formats ### Plugin hooks.json Format **For plugin hooks** in `hooks/hooks.json`, use wrapper format: ```json { "description": "Brief explanation of hooks (optional)", "hooks": { "PreToolUse": [...], "Stop": [...], "SessionStart": [...] } } ``` **Key points:** - `description` field is optional - `hooks` field is required wrapper containing actual hook events - This is the **plugin-specific format** **Example:** ```json { "description": "Validation hooks for code quality", "hooks": { "PreToolUse": [ { "matcher": "Write", "hooks": [ { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/validate.sh" } ] } ] } } ``` ### Settings Format (Direct) **For user settings** in `.claude/settings.json`, use direct format: ```json { "PreToolUse": [...], "Stop": [...], "SessionStart": [...] } ``` **Key points:** - No wrapper - events directly at top level - No description field - This is the **settings format** **Important:** The examples below show the hook event structure that goes inside either format. For plugin hooks.json, wrap these in `{"hooks": {...}}`. ## Hook Events ### PreToolUse Execute before any tool runs. Use to approve, deny, or modify tool calls. **Example (prompt-based):** ```json { "PreToolUse": [ { "matcher": "Write|Edit", "hooks": [ { "type": "prompt", "prompt": "Validate file write safety. Check: system paths, credentials, path traversal, sensitive content. Return 'approve' or 'deny'." } ] } ] } ``` **Output for PreToolUse:** ```json { "hookSpecificOutput": { "permissionDecision": "allow|deny|ask", "updatedInput": {"field": "modified_value"} }, "systemMessage": "Explanation for Claude" } ``` ### PostToolUse Execute after tool completes. Use to react to results, provide feedback, or log. **Example:** ```json { "PostToolUse": [ { "matcher": "Edit", "hooks": [ { "type": "prompt", "prompt": "Analyze edit result for potential issues: syntax errors, security vulnerabilities, breaking changes. Provide feedback." } ] } ] } ``` **Output behavior:** - Exit 0: stdout shown in transcript - Exit 2: stderr fed back to Claude - systemMessage included in context ### Stop Execute when main agent considers stopping. Use to validate completeness. **Example:** ```json { "Stop": [ { "matcher": "*", "hooks": [ { "type": "prompt", "prompt": "Verify task completion: tests run, build succeeded, questions answered. Return 'approve' to stop or 'block' with reason to continue." } ] } ] } ``` **Decision output:** ```json { "decision": "approve|block", "reason": "Explanation", "systemMessage": "Additional context" } ``` ### SubagentStop Execute when subagent considers stopping. Use to ensure subagent completed its task. Similar to Stop hook, but for subagents. ### UserPromptSubmit Execute when user submits a prompt. Use to add context, validate, or block prompts. **Example:** ```json { "UserPromptSubmit": [ { "matcher": "*", "hooks": [ { "type": "prompt", "prompt": "Check if prompt requires security guidance. If discussing auth, permissions, or API security, return relevant warnings." } ] } ] } ``` ### SessionStart Execute when Claude Code session begins. Use to load context and set environment. **Example:** ```json { "SessionStart": [ { "matcher": "*", "hooks": [ { "type": "command", "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh" } ] } ] } ``` **Special capability:** Persist environment variables using `$CLAUDE_ENV_FILE`: ```bash echo "export PROJECT_TYPE=nodejs" >> "$CLAUDE_ENV_FILE" ``` See `examples/load-context.sh` for complete example. ### SessionEnd Execute when session ends. Use for cleanup, logging, and state preservation. ### PreCompact Execute before context compaction. Use to add critical information to preserve. ### Notification Execute when Claude sends notifications. Use to react to user notifications. ## Hook Output Format ### Standard Output (All Hooks) ```json { "continue": true, "suppressOutput": false, "systemMessage": "Message for Claude" } ``` - `continue`: If false, halt processing (default true) - `suppressOutput`: Hide output from transcript (default false) - `systemMessage`: Message shown to Claude ### Exit Codes - `0` - Success (stdout shown in transcript) - `2` - Blocking error (stderr fed back to Claude) - Other - Non-blocking error ## Hook Input Format All hooks receive JSON via stdin with common fields: ```json { "session_id": "abc123", "transcript_path": "/path/to/transcript.txt", "cwd": "/current/working/dir", "permission_mode": "ask|allow", "hook_event_name": "PreToolUse" } ``` **Event-specific fields:** - **PreToolUse/PostToolUse:** `tool_name`, `tool_input`, `tool_result` - **UserPromptSubmit:** `user_prompt` - **Stop/SubagentStop:** `reason` Access fields in prompts using `$TOOL_INPUT`, `$TOOL_RESULT`, `$USER_PROMPT`, etc. ## Environment Variables Available in all command hooks: - `$CLAUDE_PROJECT_DIR` - Project root path - `$CLAUDE_PLUGIN_ROOT` - Plugin directory (use for portable paths) - `$CLAUDE_ENV_FILE` - SessionStart only: persist env vars here - `$CLAUDE_CODE_REMOTE` - Set if running in remote context **Always use ${CLAUDE_PLUGIN_ROOT} in hook commands for portability:** ```json { "type": "command", "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh" } ``` ## Plugin Hook Configuration In plugins, define hooks in `hooks/hooks.json`: ```json { "PreToolUse": [ { "matcher": "Write|Edit", "hooks": [ { "type": "prompt", "prompt": "Validate file write safety" } ] } ], "Stop": [ { "matcher": "*", "hooks": [ { "type": "prompt", "prompt": "Verify task completion" } ] } ], "SessionStart": [ { "matcher": "*", "hooks": [ { "type": "command", "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh", "timeout": 10 } ] } ] } ``` Plugin hooks merge with user's hooks and run in parallel. ## Matchers ### Tool Name Matching **Exact match:** ```json "matcher": "Write" ``` **Multiple tools:** ```json "matcher": "Read|Write|Edit" ``` **Wildcard (all tools):** ```json "matcher": "*" ``` **Regex patterns:** ```json "matcher": "mcp__.*__delete.*" // All MCP delete tools ``` **Note:** Matchers are case-sensitive. ### Common Patterns ```json // All MCP tools "matcher": "mcp__.*" // Specific plugin's MCP tools "matcher": "mcp__plugin_asana_.*" // All file operations "matcher": "Read|Write|Edit" // Bash commands only "matcher": "Bash" ``` ## Security Best Practices ### Input Validation Always validate inputs in command hooks: ```bash #!/bin/bash set -euo pipefail input=$(cat) tool_name=$(echo "$input" | jq -r '.tool_name') # Validate tool name format if [[ ! "$tool_name" =~ ^[a-zA-Z0-9_]+$ ]]; then echo '{"decision": "deny", "reason": "Invalid tool name"}' >&2 exit 2 fi ``` ### Path Safety Check for path traversal and sensitive files: ```bash file_path=$(echo "$input" | jq -r '.tool_input.file_path') # Deny path traversal if [[ "$file_path" == *".."* ]]; then echo '{"decision": "deny", "reason": "Path traversal detected"}' >&2 exit 2 fi # Deny sensitive files if [[ "$file_path" == *".env"* ]]; then echo '{"decision": "deny", "reason": "Sensitive file"}' >&2 exit 2 fi ``` See `examples/validate-write.sh` and `examples/validate-bash.sh` for complete examples. ### Quote All Variables ```bash # GOOD: Quoted echo "$file_path" cd "$CLAUDE_PROJECT_DIR" # BAD: Unquoted (injection risk) echo $file_path cd $CLAUDE_PROJECT_DIR ``` ### Set Appropriate Timeouts