Agent Skills: Claude Hook Authoring

Claude Hook Authoring

Create event hooks that automate workflows, validate operations, and respond to Claude Code events.

Hook Types

Three hook execution types:

| Type | Best For | Example | |------|----------|---------| | command | Deterministic checks, external tools, performance | Bash script validates paths | | prompt | Complex reasoning, context-aware validation | LLM evaluates if action is safe | | agent | Multi-step verification requiring tool access | Agent with Read/Grep tools verifies consistency |

Command hooks (for deterministic/fast checks):

{
  "type": "command",
  "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh",
  "timeout": 10
}

Prompt hooks (recommended for complex logic):

{
  "type": "prompt",
  "prompt": "Evaluate if this file write is safe: $TOOL_INPUT. Check for sensitive paths, credentials, path traversal. Return 'allow' or 'deny' with reason.",
  "timeout": 30
}

Agent hooks (for complex multi-step verification):

{
  "type": "agent",
  "prompt": "Verify this code change maintains consistency with the existing codebase. Check imports, type signatures, and naming conventions. Use Read and Grep tools as needed.",
  "allowedTools": ["Read", "Grep", "Glob"],
  "timeout": 120
}

Agent hooks spawn a subagent with tool access for verification tasks that require reading files, searching code, or multi-step reasoning. Use when prompt hooks are insufficient.

Hook Events

| Event | When | Can Block | Common Uses | |-------|------|-----------|-------------| | PreToolUse | Before tool executes | Yes | Validate commands, check paths, enforce policies | | PostToolUse | After tool succeeds | No | Auto-format, run linters, update docs | | PostToolUseFailure | After tool fails | No | Error logging, retry logic, notifications | | PermissionRequest | Permission dialog shown | Yes | Auto-allow/deny based on rules | | UserPromptSubmit | User submits prompt | No | Add context, log activity, augment prompts | | Notification | Claude sends notification | No | External alerts, logging | | Stop | Main agent finishes | No | Cleanup, completion notifications | | SubagentStart | Subagent spawns | No | Track subagent usage | | SubagentStop | Subagent finishes | No | Log results, trigger follow-ups | | Setup | --init, --init-only, or --maintenance flags | No | Initialize environment, install dependencies | | PreCompact | Before context compacts | No | Backup conversation, preserve context | | SessionStart | Session starts/resumes | No | Load context, show status, init resources | | SessionEnd | Session ends | No | Cleanup, save state, log metrics |

See references/hook-types.md for detailed documentation of each event.

Quick Start

Auto-Format TypeScript

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit(*.ts|*.tsx)",
        "hooks": [{
          "type": "command",
          "command": "biome check --write \"$file\"",
          "timeout": 10
        }]
      }
    ]
  }
}

Block Dangerous Commands

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/validate-bash.sh",
          "timeout": 5
        }]
      }
    ]
  }
}

validate-bash.sh:

#!/usr/bin/env bash
set -euo pipefail

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if echo "$COMMAND" | grep -qE '\brm\s+-rf\s+/'; then
  echo "Dangerous command blocked: rm -rf /" >&2
  exit 2  # Exit 2 = block and show error to Claude
fi

exit 0

Smart Validation with Prompt Hook

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{
          "type": "prompt",
          "prompt": "Analyze this file operation for safety. Check: 1) No sensitive paths (/etc, ~/.ssh), 2) No credentials in content, 3) No path traversal (..). Tool input: $TOOL_INPUT. Respond with JSON: {\"decision\": \"allow|deny\", \"reason\": \"...\"}",
          "timeout": 30
        }]
      }
    ]
  }
}

Configuration Locations

| Location | Scope | Committed | |----------|-------|-----------| | .claude/settings.json | Project (team-shared) | Yes | | .claude/settings.local.json | Project (local only) | No | | ~/.claude/settings.json | Personal (all projects) | No | | plugin/hooks/hooks.json | Plugin | Yes |

Plugin Format (hooks.json)

Uses wrapper structure:

{
  "description": "Plugin hooks for auto-formatting",
  "hooks": {
    "PostToolUse": [...]
  }
}

Settings Format (settings.json)

Direct structure (no wrapper):

{
  "hooks": {
    "PostToolUse": [...]
  }
}

Matchers

Matchers determine which tool invocations trigger the hook. Case-sensitive.

{"matcher": "Write"}                    // Exact match
{"matcher": "Edit|Write"}               // Multiple tools (OR)
{"matcher": "*"}                        // All tools
{"matcher": "Write(*.py)"}              // File pattern
{"matcher": "Write|Edit(*.ts|*.tsx)"}   // Multiple + pattern
{"matcher": "mcp__memory__.*"}          // MCP server tools
{"matcher": "mcp__github__create_issue"} // Specific MCP tool

Lifecycle hooks (SessionStart, SessionEnd, Stop, Notification) use special matchers:

// SessionStart matchers
{"matcher": "startup"}   // Initial start
{"matcher": "resume"}    // --resume or --continue
{"matcher": "clear"}     // After /clear
{"matcher": "compact"}   // After compaction

// PreCompact matchers
{"matcher": "manual"}    // User triggered /compact
{"matcher": "auto"}      // Automatic compaction

See references/matchers.md for advanced patterns.

Input Format

All hooks receive JSON on stdin:

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/current/working/directory",
  "hook_event_name": "PreToolUse",
  "permission_mode": "ask",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/project/src/file.ts",
    "content": "export const foo = 'bar';"
  }
}

Event-specific fields:

• Tool hooks: tool_name, tool_input, tool_result (PostToolUse)
• UserPromptSubmit: user_prompt
• Stop/SubagentStop: reason

Prompt hooks access fields via placeholders:

• $ARGUMENTS - Full context passed to the hook (general-purpose)
• $TOOL_INPUT - Tool input for tool-related events
• $TOOL_RESULT - Tool result (PostToolUse only)
• $USER_PROMPT - User prompt (UserPromptSubmit only)

Reading Input

Bash:

#!/usr/bin/env bash
set -euo pipefail

INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

Bun/TypeScript:

#!/usr/bin/env bun
const input = await Bun.stdin.json();
const toolName = input.tool_name;
const filePath = input.tool_input?.file_path;

Output Format

Exit Codes (Simple)

exit 0   # Success, continue execution
exit 2   # Block operation (PreToolUse only), stderr shown to Claude
exit 1   # Warning, stderr shown to user, continues

JSON Output (Advanced)

{
  "continue": true,
  "suppressOutput": false,
  "systemMessage": "Context for Claude",
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow|deny|ask",
    "permissionDecisionReason": "Explanation",
    "updatedInput": {"modified": "field"}
  }
}

PreToolUse can modify tool input via updatedInput and control permissions via permissionDecision.

Environment Variables

| Variable | Availability | Description | |----------|--------------|-------------| | $CLAUDE_PROJECT_DIR | All hooks | Project root directory | | $CLAUDE_PLUGIN_ROOT | Plugin hooks | Plugin root (use for portable paths) | | $file | PostToolUse (Write/Edit) | Path to affected file | | $CLAUDE_ENV_FILE | SessionStart | Write env vars here to persist | | $CLAUDE_CODE_REMOTE | All hooks | Set if running in remote context |

Plugin hooks should always use ${CLAUDE_PLUGIN_ROOT} for portability:

{
  "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
}

SessionStart can persist environment variables:

#!/usr/bin/env bash
# Persist variables for the session
echo "export PROJECT_TYPE=nodejs" >> "$CLAUDE_ENV_FILE"
echo "export API_URL=https://api.example.com" >> "$CLAUDE_ENV_FILE"

Component-Scoped Hooks

Skills, agents, and commands can define hooks in frontmatter. These hooks only run when the component is active.

Supported events: PreToolUse, PostToolUse, Stop

Skill with Hooks

---
name: my-skill
description: Skill with validation hooks
hooks:
  PreToolUse:
    - matcher: "Write|Edit"
      hooks:
        - type: prompt
          prompt: "Validate this write operation for the skill context..."
---

Agent with Hooks

---
name: security-reviewer
model: sonnet
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "${CLAUDE_PLUGIN_ROOT}/scripts/validate-bash.sh"
  Stop:
    - matcher: "*"
      hooks:
        - type: prompt
          prompt: "Verify the security review is complete..."
---

Execution Model

Parallel execution: All matching hooks run in parallel, not sequentially.

{
  "PreToolUse": [{
    "matcher": "Write",
    "hooks": [
      {"type": "command", "command": "check1.sh"},  // Runs in parallel
      {"type": "command", "command": "check2.sh"},  // Runs in parallel
      {"type": "prompt", "prompt": "Validate..."}   // Runs in parallel
    ]
  }]
}

Implications:

• Hooks cannot see each other's output
• Non-deterministic ordering
• Design for independence

Hot-swap limitations: Hook changes require restarting Claude Code. Editing hooks.json or hook scripts does not affect the current session.

Security Best Practices

1. Validate all input - Check for path traversal, sensitive paths, injection
2. Quote shell variables - Always use "$VAR" not $VAR
3. Set timeouts - Prevent hanging hooks (default: 60s command, 30s prompt)
4. Use absolute paths - Via $CLAUDE_PROJECT_DIR or ${CLAUDE_PLUGIN_ROOT}
5. Handle errors gracefully - Use set -euo pipefail in bash
6. Don't log sensitive data - Filter credentials, tokens, API keys

See references/security.md for detailed security patterns.

Debugging

# Run Claude with debug output
claude --debug

# Test hook manually
echo '{"tool_name": "Write", "tool_input": {"file_path": "test.ts"}}' | ./.claude/hooks/my-hook.sh

# Check transcript for hook execution
# Press Ctrl+R in Claude Code to view transcript

Common issues:

• Hook not firing: Check matcher syntax, restart Claude Code
• Permission errors: chmod +x script.sh
• Timeout: Increase timeout value or optimize script

Workflow Patterns

Pre-Commit Quality Gate

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {"type": "command", "command": "./.claude/hooks/validate-paths.sh"},
          {"type": "command", "command": "./.claude/hooks/check-sensitive.sh"}
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit(*.ts)",
        "hooks": [
          {"type": "command", "command": "biome check --write \"$file\""},
          {"type": "command", "command": "tsc --noEmit \"$file\""}
        ]
      }
    ]
  }
}

Context Injection

{
  "hooks": {
    "SessionStart": [{
      "matcher": "startup",
      "hooks": [{
        "type": "command",
        "command": "echo \"Branch: $(git branch --show-current)\" && git status --short"
      }]
    }],
    "UserPromptSubmit": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "echo \"Time: $(date '+%Y-%m-%d %H:%M %Z')\""
      }]
    }]
  }
}

References

• references/hook-types.md - Detailed documentation for each hook event
• references/matchers.md - Advanced matcher patterns and MCP tools
• references/security.md - Security best practices and validation patterns
• references/schema.md - Complete configuration schema reference
• references/examples.md - Real-world hook implementations

External Resources

• Official Hooks Reference
• Hooks Guide
• Community Examples (disler)
• Claude Code Showcase