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.