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

User Says	Event	Matcher	Notes
"log all bash commands"	PreToolUse	Bash	Logging to file
"format files after edit"	PostToolUse	Edit\|Write	Run formatter
"block .env file changes"	PreToolUse	Edit\|Write	Exit code 2 blocks
"notify me when done"	Notification	""	Desktop notification
"run tests after code changes"	PostToolUse	Edit\|Write	Filter by extension
"ask before dangerous commands"	PreToolUse	Bash	Return `permissionDecision: "ask"`

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.

Complexity	Approach	Example
Simple	Inline	`jq -r '.tool_input.command' >> log.txt`
Medium	Inline	Single grep/jq pipe with basic conditionals
Complex	Script file	Dialogs, multiple conditions, osascript, error handling

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:

Create script in ~/.claude/hooks/
Make executable: chmod +x ~/.claude/hooks/my-hook.sh
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

Read current config
Identify hook by event + matcher + command pattern
Remove from hooks array
If array empty, remove the matcher entry
If event empty, remove event key
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.

`permissionDecision`	Behavior
`"allow"`	Bypass permissions, proceed silently
`"deny"`	Block the tool call, reason shown to Claude
`"ask"`	Prompt the user to confirm in the terminal

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

Code	Meaning	Use Case
0	Success/Allow	Continue execution
2	Block	Simple blocking (prefer JSON decision control for PreToolUse)
Other	Error	Log to stderr, shown in verbose mode

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.

hooks-management