create-hooks（创建钩子）

Hooks provide programmatic control over Claude's behavior without modifying core code, enabling project-specific automation, safety checks, and workflow customization.

<quick_start>

1. Create hooks config file:

- Project: .claude/hooks.json - User: ~/.claude/hooks.json

1. Choose hook event (when it fires)
2. Choose hook type (command or prompt)
3. Configure matcher (which tools trigger it)
4. Test with claude --debug

.claude/hooks.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '\"\\(.tool_input.command) - \\(.tool_input.description // \\\"No description\\\")\"' >> ~/.claude/bash-log.txt"
          }
        ]
      }
    ]
  }
}

This hook:

• Fires before (PreToolUse) every Bash tool use
• Executes a command (not an LLM prompt)
• Logs command + description to a file

</quick_start>

<hook_types>

Blocking hooks can return "decision": "block" to prevent the action. See references/hook-types.md for detailed use cases. </hook_types>

<hook_anatomy> <hook_type name="command"> Type: Executes a shell command

Use when:

• Simple validation (check file exists)
• Logging (append to file)
• External tools (formatters, linters)
• Desktop notifications

Input: JSON via stdin Output: JSON via stdout (optional)

{
  "type": "command",
  "command": "/path/to/script.sh",
  "timeout": 30000
}

</hook_type>

<hook_type name="prompt"> Type: LLM evaluates a prompt

Use when:

• Complex decision logic
• Natural language validation
• Context-aware checks
• Reasoning required

Input: Prompt with $ARGUMENTS placeholder Output: JSON with decision and reason

{
  "type": "prompt",
  "prompt": "Evaluate if this command is safe: $ARGUMENTS\n\nReturn JSON: {\"decision\": \"approve\" or \"block\", \"reason\": \"explanation\"}"
}

</hook_type> </hook_anatomy>

{
  "matcher": "Bash",           // Exact match
  "matcher": "Write|Edit",     // Multiple tools (regex OR)
  "matcher": "mcp__.*",        // All MCP tools
  "matcher": "mcp__memory__.*" // Specific MCP server
}

No matcher: Hook fires for all tools

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [...]  // No matcher - fires on every user prompt
      }
    ]
  }
}

<input_output> Hooks receive JSON via stdin with session info, current directory, and event-specific data. Blocking hooks can return JSON to approve/block actions or modify inputs.

Example output (blocking hooks):

{
  "decision": "approve" | "block",
  "reason": "Why this decision was made"
}

See references/input-output-schemas.md for complete schemas for each hook type. </input_output>

<environment_variables> Available in hook commands:

Example:

{
  "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/validate.sh"
}

</environment_variables>

<common_patterns> Desktop notification when input needed:

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude needs input\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Block destructive git commands:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if this command is destructive: $ARGUMENTS\n\nBlock if it contains: 'git push --force', 'rm -rf', 'git reset --hard'\n\nReturn: {\"decision\": \"approve\" or \"block\", \"reason\": \"explanation\"}"
          }
        ]
      }
    ]
  }
}

Auto-format code after edits:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write $CLAUDE_PROJECT_DIR",
            "timeout": 10000
          }
        ]
      }
    ]
  }
}

Add context at session start:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"SessionStart\", \"additionalContext\": \"Current sprint: Sprint 23. Focus: User authentication\"}}'"
          }
        ]
      }
    ]
  }
}

</common_patterns>

This shows which hooks matched, command execution, and output. See references/troubleshooting.md for common issues and solutions.

<reference_guides> Hook types and events: references/hook-types.md

• Complete list of hook events
• When each event fires
• Input/output schemas for each
• Blocking vs non-blocking hooks

Command vs Prompt hooks: references/command-vs-prompt.md

• Decision tree: which type to use
• Command hook patterns and examples
• Prompt hook patterns and examples
• Performance considerations

Matchers and patterns: references/matchers.md

• Regex patterns for tool matching
• MCP tool matching patterns
• Multiple tool matching
• Debugging matcher issues

Input/Output schemas: references/input-output-schemas.md

• Complete schema for each hook type
• Field descriptions and types
• Hook-specific output fields
• Example JSON for each event

Working examples: references/examples.md

• Desktop notifications
• Command validation
• Auto-formatting workflows
• Logging and audit trails
• Stop logic patterns
• Session context injection

Troubleshooting: references/troubleshooting.md

• Hooks not triggering
• Command execution failures
• Prompt hook issues
• Permission problems
• Timeout handling
• Debug workflow </reference_guides>

<toolkit_hook_structure> Creating Installable Hooks for claude-code-toolkit

When creating hooks for distribution via the toolkit, use this structure:

hooks/
└── my-hook/
    ├── README.md                # Documentation
    ├── install.sh               # Standalone installer
    ├── settings-template.json   # Hook configuration to merge
    └── toggle.sh                # Optional: on/off toggle script

settings-template.json (hook configuration):

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "your-hook-command-here"
          }
        ]
      }
    ]
  }
}

install.sh (standalone installer):

#!/bin/bash
set -e

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
CLAUDE_DIR="$HOME/.claude"
TEMPLATE_FILE="$SCRIPT_DIR/settings-template.json"

# Check dependencies
command -v jq &>/dev/null || { echo "jq required"; exit 1; }

# Create settings if missing
mkdir -p "$CLAUDE_DIR"
[ -f "$CLAUDE_DIR/settings.json" ] || echo '{}' > "$CLAUDE_DIR/settings.json"

# Backup and merge
cp "$CLAUDE_DIR/settings.json" "$CLAUDE_DIR/settings.json.bak"
jq -s '.[0] * .[1]' "$CLAUDE_DIR/settings.json" "$TEMPLATE_FILE" > /tmp/merged.json
mv /tmp/merged.json "$CLAUDE_DIR/settings.json"

echo "Hook installed"

REQUIRED: Update root installers:

After creating a new hook, you MUST update both install-linux.sh and install-mac.sh:

1. Add install function:

install_my_hook() {
    local INSTALL_SCRIPT="$SCRIPT_DIR/hooks/my-hook/install.sh"
    [ -f "$INSTALL_SCRIPT" ] || { echo "Hook not found"; return; }
    bash "$INSTALL_SCRIPT"
}

1. Add to "install all" section:

echo -e "${BLUE}My Hook (description):${NC}"
install_my_hook

1. Add to "select by folder" section:

echo
echo -e "${BLUE}━━━ My Hook ━━━${NC}"
echo -e "${DIM}Brief description of what the hook does${NC}"
echo -n "Install my-hook? (y/n): "
read -r choice
[[ "$choice" =~ ^[Yy]$ ]] && install_my_hook

Examples in toolkit:

• hooks/concise-mode/ - UserPromptSubmit hook with toggle
• hooks/damage-control/ - PreToolUse hooks with Python scripts </toolkit_hook_structure>

<security_checklist> Critical safety requirements:

• Infinite loop prevention: Check stop_hook_active flag in Stop hooks to prevent recursive triggering
• Timeout configuration: Set reasonable timeouts (default: 60s) to prevent hanging
• Permission validation: Ensure hook scripts have executable permissions (chmod +x)
• Path safety: Use absolute paths with $CLAUDE_PROJECT_DIR to avoid path injection
• JSON validation: Validate hook config with jq before use to catch syntax errors
• Selective blocking: Be conservative with blocking hooks to avoid workflow disruption

Testing protocol:

# Always test with debug flag first
claude --debug

# Validate JSON config
jq . .claude/hooks.json

</security_checklist>

<success_criteria> A working hook configuration has:

• Valid JSON in .claude/hooks.json (validated with jq)
• Appropriate hook event selected for the use case
• Correct matcher pattern that matches target tools
• Command or prompt that executes without errors
• Proper output schema (decision/reason for blocking hooks)
• Tested with --debug flag showing expected behavior
• No infinite loops in Stop hooks (checks stop_hook_active flag)
• Reasonable timeout set (especially for external commands)
• Executable permissions on script files if using file paths </success_criteria>