Hooks Development

Guide for developing Claude Code hooks with proper output visibility patterns.

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

When to Use This Skill

Creating a new PostToolUse or PreToolUse hook
Hook output is not visible to Claude (most common issue)
User asks about decision: block pattern
Debugging why hook messages don't appear
User mentions "Claude Code hooks" or "hook visibility"

Quick Reference: Visibility Patterns

Critical insight: PostToolUse hook stdout is only visible to Claude when JSON contains "decision": "block".

Output Format	Claude Visibility
Plain text	Not visible
JSON without `decision: block`	Not visible
JSON with `decision: block`	Visible

Exit code behavior:

Exit Code	stdout Behavior	Claude Visibility
0	JSON parsed, shown in verbose mode only	Only if `"decision": "block"`
2	Ignored, uses stderr instead	stderr shown to Claude
Other	stderr shown in verbose mode	Not shown to Claude

Minimal Working Pattern

/usr/bin/env bash << 'SKILL_SCRIPT_EOF'
#!/usr/bin/env bash
set -euo pipefail

# Read hook payload from stdin
PAYLOAD=$(cat)
FILE_PATH=$(echo "$PAYLOAD" | jq -r '.tool_input.file_path // empty')

[[ -z "$FILE_PATH" ]] && exit 0

# Your condition here
if [[ condition_met ]]; then
    jq -n \
        --arg reason "[HOOK] Your message to Claude" \
        '{decision: "block", reason: $reason}'
fi

exit 0
SKILL_SCRIPT_EOF

Key points:

Use jq -n to generate valid JSON
Include "decision": "block" for visibility
Exit with code 0
The "blocking error" label is cosmetic - operation continues

TodoWrite Templates

Creating a PostToolUse Hook

1. [pending] Create hook script with shebang and set -euo pipefail
2. [pending] Parse PAYLOAD from stdin with jq
3. [pending] Add condition check for when to trigger
4. [pending] Output JSON with decision:block pattern
5. [pending] Register hook in hooks.json with matcher
6. [pending] Test by editing a matching file
7. [pending] Verify Claude sees the message in system-reminder

Debugging Invisible Hook Output

1. [pending] Verify hook executes (add debug log to /tmp)
2. [pending] Check JSON format is valid (pipe to jq .)
3. [pending] Confirm decision:block is present in output
4. [pending] Verify exit code is 0
5. [pending] Check hooks.json matcher pattern
6. [pending] Restart Claude Code session

Reference Documentation

Lifecycle Reference - All 10 hook events, diagrams, use cases, configuration pitfalls
Visibility Patterns - Full exit code and JSON schema details
Hook Templates - Copy-paste templates for common patterns
Debugging Guide - Troubleshooting invisible output

Post-Change Checklist (Self-Evolution)

When this skill is updated:

Update evolution-log.md with discovery
Verify code examples still work
Check if ADR needs updating: PostToolUse Hook Visibility ADR

Related Resources

ADR: PostToolUse Hook Visibility
GitHub Issue #3983 - Original bug report
Claude Code Hooks Reference - Official documentation

Troubleshooting

Issue	Cause	Solution
Hook output not visible	Missing decision:block in JSON	Add `"decision": "block"` to JSON output
JSON parse error in hook	Invalid JSON syntax	Use `jq -n` to generate valid JSON
Hook not executing	Wrong matcher pattern	Check hooks.json matcher regex matches tool name
Plain text output ignored	Only JSON parsed	Wrap output in JSON with decision:block
Exit code 2 behavior	stderr used instead of stdout	Use exit 0 with JSON, or exit 2 for stderr messages
Session not seeing changes	Hooks cached	Restart Claude Code session after hook changes
Verbose mode not showing	Disabled by default	Enable verbose mode in Claude Code settings
jq command not found	jq not installed	`brew install jq`

Post-Execution Reflection

After this skill completes, check before closing:

Did the command succeed? — If not, fix the instruction or error table that caused the failure.
Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.

hooks-development