Hooks Management

Hooks Management

Manage hooks and automation through natural language commands.

IMPORTANT: After adding, modifying, or removing hooks, always inform the user that they need to restart the agent for changes to take effect. Hooks are loaded at startup.

Quick Reference

Hook Events: PreToolUse, PostToolUse, PermissionRequest, UserPromptSubmit, Notification, Stop, SubagentStop, PreCompact, SessionStart, SessionEnd

Settings Files:

• User-wide: ~/.claude/settings.json
• Project: .claude/settings.json
• Local (not committed): .claude/settings.local.json

Workflow

1. Understand the Request

Parse what the user wants:

• Add/Create: New hook for specific event and tool
• List/Show: Display current hooks configuration
• Remove/Delete: Remove specific hook(s)
• Update/Modify: Change existing hook
• Validate: Check hooks for errors

2. Validate Before Writing

Always run validation before saving:

python3 "$SKILL_PATH/scripts/validate_hooks.py" ~/.claude/settings.json

3. Read Current Configuration

cat ~/.claude/settings.json 2>/dev/null || echo '{}'

4. Apply Changes

Use Edit tool for modifications, Write tool for new files.

Adding Hooks

Translate Natural Language to Hook Config

Hook Configuration Template

{
  "hooks": {
    "EVENT_NAME": [
      {
        "matcher": "TOOL_PATTERN",
        "hooks": [
          {
            "type": "command",
            "command": "SHELL_COMMAND",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Simple vs Complex Hooks

PREFER SCRIPT FILES for complex hooks. Inline commands with nested quotes, osascript, or multi-step logic often break due to JSON escaping issues.

Script location: ~/.claude/hooks/ (create if needed)

Script template (~/.claude/hooks/my-hook.sh):

#!/bin/bash
set -euo pipefail

# Read JSON input from stdin
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command')

# Your logic here
if echo "$cmd" | grep -q 'pattern'; then
    # Option 1: Block with exit code
    exit 2

    # Option 2 (preferred for PreToolUse): JSON decision control
    # jq -n '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"ask",permissionDecisionReason:"Reason"}}'
fi

exit 0  # Allow

Hook config using script:

{
  "type": "command",
  "command": "~/.claude/hooks/my-hook.sh"
}

Always:

1. Create script in ~/.claude/hooks/
2. Make executable: chmod +x ~/.claude/hooks/my-hook.sh
3. Test with sample input: echo '{"tool_input":{"command":"test"}}' | ~/.claude/hooks/my-hook.sh

Common Patterns

Logging (PreToolUse):

{
  "matcher": "Bash",
  "hooks": [{
    "type": "command",
    "command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
  }]
}

File Protection (PreToolUse, exit 2 to block):

{
  "matcher": "Edit|Write",
  "hooks": [{
    "type": "command",
    "command": "jq -r '.tool_input.file_path' | grep -qE '(\\.env|secrets)' && exit 2 || exit 0"
  }]
}

Auto-format (PostToolUse):

{
  "matcher": "Edit|Write",
  "hooks": [{
    "type": "command",
    "command": "file=$(jq -r '.tool_input.file_path'); [[ $file == *.ts ]] && npx prettier --write \"$file\" || true"
  }]
}

Desktop Notification (Notification):

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

Codex CLI Hooks

Codex CLI has a limited hook system. For blocking/allowing commands, use Starlark rules instead of hooks:

# In .codex/rules/safety.rules
prefix_rule(
    pattern = ["rm", ["-rf", "-r"]],
    decision = "forbidden",
    justification = "Use git clean -fd instead.",
)

For notifications: notify = ["notify-send", "Codex"] in config.toml.

See references/codex-hooks.md for full Codex hooks reference and migration patterns.

Event Input Schemas

See references/claude-event-schemas.md for complete JSON input schemas for each event type (Claude Code).

Validation

Run validation script to check hooks:

python3 "$SKILL_PATH/scripts/validate_hooks.py" <settings-file>

Validates:

• JSON syntax
• Required fields (type, command/prompt)
• Valid event names
• Matcher patterns (regex validity)
• Command syntax basics

Removing Hooks

1. Read current config
2. Identify hook by event + matcher + command pattern
3. Remove from hooks array
4. If array empty, remove the matcher entry
5. If event empty, remove event key
6. Validate and save

Decision Control (PreToolUse)

PreToolUse hooks can return JSON on stdout to control tool execution. This is preferred over bare exit codes for PreToolUse because it supports three outcomes and richer control.

Additional JSON fields:

• permissionDecisionReason — shown to user for "allow"/"ask", shown to Claude for "deny"
• updatedInput — modify tool input before execution
• additionalContext — inject context for Claude before the tool executes

Ask user before dangerous command (PreToolUse):

#!/bin/bash
set -euo pipefail
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // empty')

if echo "$cmd" | grep -qE 'supabase\s+db\s+reset'; then
    jq -n '{
      hookSpecificOutput: {
        hookEventName: "PreToolUse",
        permissionDecision: "ask",
        permissionDecisionReason: "This will destroy and recreate the local database."
      }
    }'
else
    exit 0
fi

Deny with reason (PreToolUse):

jq -n '{
  hookSpecificOutput: {
    hookEventName: "PreToolUse",
    permissionDecision: "deny",
    permissionDecisionReason: "Destructive command blocked by hook"
  }
}'

See references/claude-event-schemas.md for the full output schema.

Exit Codes

Security Checklist

Before adding hooks, verify:

• No credential logging
• No sensitive data exposure
• Specific matchers (avoid * when possible)
• Validated input parsing
• Appropriate timeout for long operations

Troubleshooting

Hook not triggering: Check matcher case-sensitivity, ensure event name is exact.

Command failing: Test command standalone with sample JSON input.

Permission denied: Ensure script is executable (chmod +x).

Timeout: Increase timeout field or optimize command.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.