writing-hooks

Writing Hooks

Scope: covers Claude Code hooks.json authoring and hook script design. Hook event vocabularies are per-tool and NOT 1:1 mappable (nlpm design decision #4): Claude uses PreToolUse/PostToolUse/Stop/etc.; Codex overlaps with Claude plus PostCompact/SubagentStart; Antigravity/Gemini uses a different Before*/After* Agent/Model/Tool decomposition. The hook-script design principles here (idempotency, fail-open, exit codes, portable paths) transfer across tools; the event names and config locations do not. For the authoritative per-tool event tables see [[nlpm:conventions-claude]] §7, [[nlpm:conventions-codex]] §6, [[nlpm:conventions-antigravity]] §5. For plugin architecture, see [[writing-plugins]]. For rules (which are simpler but static), see [[writing-rules]].

1. Three Hook Types

Type Selection Flowchart

Is the check deterministic (regex, file exists, JSON schema)?
  YES --> command hook (shell script)
  NO  --> Does it need AI judgment?
    YES --> agent hook
    NO  --> prompt hook (context injection)

Command Hook Example

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/check-loc.sh",
            "timeout": 10000
          }
        ]
      }
    ]
  }
}

Hook script receives JSON on stdin with tool name and parameters. It outputs JSON to stdout.

Prompt Hook Example

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Remember: this project uses Result<T, E> for error handling. Never use try/catch directly."
          }
        ]
      }
    ]
  }
}

Agent Hook Example

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "agent",
            "agent": "Verify the written file follows project conventions. Check: import order, export style, naming conventions. Report any violations."
          }
        ]
      }
    ]
  }
}

2. Blocking vs Advisory

Blocking (PreToolUse with deny)

The hook prevents the tool from executing. Use for hard quality gates.

Script output for blocking:

{
  "hookSpecificOutput": {
    "permissionDecision": "deny",
    "permissionDecisionReason": "File exceeds 300 LOC limit (current: 342). Extract logic before writing."
  }
}

When to block:

• Tests must pass before committing
• File exceeds size limit
• Required field missing from config
• Dangerous operation detected (force push, drop table)

Advisory (PostToolUse with message)

The hook adds a message to Claude's context after the action completes. Use for suggestions and reminders.

Script output for advisory:

{
  "hookSpecificOutput": {
    "message": "The file you just edited has no tests. Consider adding tests in __tests__/."
  }
}

When to advise:

• Suggest related actions (run tests, update docs)
• Remind about conventions
• Surface contextual information
• Warn about potential issues without blocking

Decision Matrix

Rule of thumb: block only what you would reject in a code review. Advise on everything else.

3. Event Selection Guide

Event Selection by Goal

4. Matcher Patterns

The matcher field uses regex to match tool names. It applies only to PreToolUse, PostToolUse, and PostToolUseFailure events.

Matcher Testing

Before deploying, verify your matcher with test cases:

5. Portable Paths

Always use ${CLAUDE_PLUGIN_ROOT} for script paths in hooks.json. This variable resolves to the plugin's installation directory at runtime.

Correct

{
  "command": "${CLAUDE_PLUGIN_ROOT}/scripts/check-loc.sh"
}

Wrong (breaks on other machines)

{
  "command": "/Users/joker/.claude/plugins/cache/xiaolai/my-plugin/0.1.0/scripts/check-loc.sh"
}

Script Location Convention

my-plugin/
  hooks/
    hooks.json          # hook definitions
  scripts/
    check-loc.sh        # hook scripts
    validate-config.sh
    lint-output.sh

Script Requirements

Every hook script must have:

1. Shebang line: #!/bin/bash or #!/usr/bin/env node
2. Executable permission: chmod +x scripts/*.sh
3. JSON output: scripts must output valid JSON to stdout
4. Stderr for logging: debug output goes to stderr, not stdout (stdout is parsed as JSON)

#!/bin/bash
# Read input from stdin
input=$(cat)

# Debug logging goes to stderr
echo "Hook triggered: $(date)" >&2

# Business logic
file_path=$(echo "$input" | jq -r '.toolInput.file_path // empty')

if [ -z "$file_path" ]; then
  # Allow if we can't determine the file
  echo '{"hookSpecificOutput":{"decision":"allow"}}'
  exit 0
fi

loc=$(wc -l < "$file_path" 2>/dev/null || echo "0")

if [ "$loc" -gt 300 ]; then
  echo "{\"hookSpecificOutput\":{\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"File has $loc lines, exceeds 300 LOC limit\"}}"
else
  echo '{"hookSpecificOutput":{"decision":"allow"}}'
fi

6. Fail-Open vs Fail-Closed

What happens when your hook script crashes?

Fail-Open (recommended default)

If the script crashes, allow the action. Safer for advisory hooks and non-critical checks.

#!/bin/bash
# Fail-open wrapper
set +e  # Don't exit on error

result=$(your_check_logic 2>/dev/null)
exit_code=$?

if [ $exit_code -ne 0 ]; then
  # Script failed -- allow the action (fail-open)
  echo '{"hookSpecificOutput":{"decision":"allow"}}'
  exit 0
fi

# Normal processing...
echo "$result"

Fail-Closed (security-critical only)

If the script crashes, deny the action. Use only for critical security gates.

#!/bin/bash
# Fail-closed wrapper
set +e

result=$(your_check_logic 2>/dev/null)
exit_code=$?

if [ $exit_code -ne 0 ]; then
  # Script failed -- deny the action (fail-closed)
  echo '{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"Safety check script failed -- blocking action as precaution"}}'
  exit 0
fi

# Normal processing...
echo "$result"

When to Use Each

7. Common Mistakes

8. Quality Checklist

Before deploying hooks, verify:

• Each hook has the correct event type for its purpose
• Blocking hooks use PreToolUse, not PostToolUse
• Matchers are tested against expected and unexpected tool names
• All script paths use ${CLAUDE_PLUGIN_ROOT}
• All scripts have shebangs and executable permissions
• All scripts output valid JSON to stdout
• Debug logging goes to stderr, not stdout
• Fail-open or fail-closed is explicitly chosen for each hook
• Timeouts are set (default: 10 seconds)
• Hooks are tested with: normal input, edge case input, missing input