hooks-development

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

---

Never rewrite AskUserQuestion

A PreToolUse hook must never return updatedInput for AskUserQuestion — not directly, and not through allowWithInput. For that tool updatedInput is the channel the dialog uses to deliver the user's answers, so a hook that returns it is taken as having answered: the menu never renders and the tool returns "The user did not answer the questions." Measured 2026-09-24 across every session transcript: 86 of 86 rewritten calls went unseen and unanswered, against 465 of 466 plain-allow calls that rendered and were answered.

• A plain allow is safe; the dialog still shows.
• To change what the user sees, deny with a reason that names exactly what the agent should re-ask, and make sure the re-ask passes unchanged so the loop settles in one round (pretooluse-pr-premise-annotator.ts is the worked example).
• Enforced three ways: allowWithInput refuses the tool at runtime, TOOL_SCHEMAS has no entry for it, and scripts/validate-plugins.mjs fails the gate when a hook whose matcher covers AskUserQuestion emits updatedInput or calls allowWithInput.

---

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:

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

---

Language choice: shell vs Bun/TypeScript

Default to shell (bash) for hooks. A hook fires on every matching event and ~95% bail out immediately, so process-startup latency dominates — not the logic. Measured on an m3max: a full bash hook (keyword match + bail) ≈ 7 ms; a do-nothing Bun script ≈ 17 ms. bash also needs no runtime dependency and matches existing hook convention. Keep the hot-path bail-out a bash builtin case (no jq/process spawn) — see the pre-jq-fastpath in the devops-tools SCS hooks.

Reach for Bun/TypeScript only when a hook does real work that amortizes the ~10 ms startup tax: parsing/transforming structured data, calling an API, sharing typed modules across many hooks, or maintaining state. For simple match-and-emit reminders, shell wins on speed, durability, and convention. (This is the language doctrine's "existing convention + SOTA-native ecosystem override the Bun-first default" clause in action.)

---

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:

1. Did the command succeed? — If not, fix the instruction or error table that caused the failure.
2. Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. 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.