flowchart TD
    Start([Need a hook script?]) --> Q1{Language choice}
    Q1 -->|JavaScript .cjs| Correct[Correct — use Node.js CommonJS]
    Q1 -->|Python| Wrong1[Prohibited — use .cjs instead]
    Q1 -->|Bash / shell| Wrong2[Prohibited — use .cjs instead]
    Q1 -->|TypeScript| Wrong3[Compile step required — write .cjs directly]
    Correct --> Pattern[Follow Node.js hook pattern below]

#!/usr/bin/env node
/**
 * Brief description of what this hook does.
 * Fires on: EventName — ToolMatcher
 * Action: blocking | non-blocking — what it does
 */

const { execFileSync } = require('node:child_process');
const fs = require('node:fs');

let input = '';
process.stdin.setEncoding('utf8');
process.stdin.on('data', (chunk) => { input += chunk; });
process.stdin.on('end', () => {
  let data = {};
  try {
    data = JSON.parse(input);
  } catch {
    process.stdout.write(JSON.stringify({}));
    process.exit(0);
  }

  // Extract fields
  const toolName = data.tool_name || '';
  const toolInput = data.tool_input || {};

  // Guard: exit early if this hook does not apply
  if (toolName !== 'Write') {
    process.stdout.write(JSON.stringify({}));
    process.exit(0);
  }

  // Hook logic here
  const output = {
    hookSpecificOutput: {
      hookEventName: 'PreToolUse',
      additionalContext: 'Context injected into Claude.',
    },
  };

  process.stdout.write(JSON.stringify(output));
  process.exit(0);
});

{"hooks": {}}

{
  "description": "Brief explanation of what these hooks enforce",
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/my-hook.cjs\"",
            "timeout": 3
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Verify the task is complete. Return {\"ok\": true} or {\"ok\": false, \"reason\": \"...\"}.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

flowchart TD
    Start([What should the hook do?]) --> Q1{When does it act?}
    Q1 -->|Before a tool runs — can block| PreToolUse[PreToolUse + tool name matcher]
    Q1 -->|After a tool succeeds| PostToolUse[PostToolUse + tool name matcher]
    Q1 -->|After a tool fails| PostToolUseFailure[PostToolUseFailure + tool name matcher]
    Q1 -->|Before Claude stops responding| Stop[Stop — no matcher]
    Q1 -->|When subagent spawned| SubagentStart[SubagentStart — matcher: agent type name]
    Q1 -->|When subagent finishes| SubagentStop[SubagentStop — matcher: agent type name]
    Q1 -->|Agent team teammate going idle| TeammateIdle[TeammateIdle — no matcher]
    Q1 -->|Task being marked complete| TaskCompleted[TaskCompleted — no matcher]
    Q1 -->|CLAUDE.md or rules file loaded| InstructionsLoaded[InstructionsLoaded — no matcher]
    Q1 -->|Config file changes| ConfigChange[ConfigChange — matcher: config source]
    Q1 -->|Worktree being created| WorktreeCreate[WorktreeCreate — no matcher]
    Q1 -->|Worktree being removed| WorktreeRemove[WorktreeRemove — no matcher]
    Q1 -->|MCP server requests user input| Elicitation[Elicitation — matcher: MCP server name]
    Q1 -->|User responds to MCP elicitation| ElicitationResult[ElicitationResult — matcher: MCP server name]
    Q1 -->|When user submits a prompt| UserPromptSubmit[UserPromptSubmit — no matcher]
    Q1 -->|When session starts| SessionStart[SessionStart — matcher: startup|resume|clear|compact]
    Q1 -->|When session ends| SessionEnd[SessionEnd — matcher: exit reason]
    Q1 -->|Before context compaction| PreCompact[PreCompact — matcher: manual|auto]
    Q1 -->|After context compaction| PostCompact[PostCompact — matcher: manual|auto]
    Q1 -->|On repo setup or maintenance| Setup[Setup — matcher: init|maintenance]
    Q1 -->|When Claude sends notifications| Notification[Notification — notification matcher]
    PreToolUse --> HookType[Choose hook type]
    PostToolUse --> HookType
    PostToolUseFailure --> HookType
    Stop --> HookType
    SubagentStart --> HookType
    SubagentStop --> HookType
    TeammateIdle --> HookType
    TaskCompleted --> HookType
    InstructionsLoaded --> HookType
    ConfigChange --> HookType
    WorktreeCreate --> HookType
    WorktreeRemove --> HookType
    Elicitation --> HookType
    ElicitationResult --> HookType
    UserPromptSubmit --> HookType
    SessionStart --> HookType
    SessionEnd --> HookType
    PreCompact --> HookType
    PostCompact --> HookType
    Setup --> HookType
    Notification --> HookType
    HookType --> Q2{Decision logic complexity?}
    Q2 -->|Deterministic rule — fast| Command[type: command — Node.js .cjs]
    Q2 -->|Context-aware — needs reasoning| Prompt[type: prompt — LLM-evaluated]
    Q2 -->|Complex verification with tools| Agent[type: agent — agentic verifier]
    Q2 -->|Send to external service| HTTP[type: http — POST to URL]

flowchart TD
    Start([Choose hook type]) --> Q{What kind of logic?}
    Q -->|Regex/pattern match, path check, fast rule| Command["type: command\nNode.js .cjs script\nFast, deterministic, no API call"]
    Q -->|Understand intent, evaluate context, reasoning| Prompt["type: prompt\nLLM evaluated (fast model)\nSlower, flexible, context-aware"]
    Q -->|Complex verification needing tool access| Agent["type: agent\nAgentic verifier with tools\nMost flexible, highest latency"]
    Q -->|Send to external service or webhook| HTTP["type: http\nPOST to URL\nFor remote validation services"]
    Command --> Timeout1[Timeout: 3s for local binary checks\nMax 10s for slow operations\nDefault: 600s built-in]
    Prompt --> Timeout2[Timeout: 30s default\nAdjust if reasoning takes longer]
    Agent --> Timeout3[Timeout: 60s default\nAdjust for complex tasks]
    HTTP --> Timeout4[Timeout: configurable\nNon-2xx errors are non-blocking]

{"ok": true}

{"ok": false, "reason": "Explanation shown to Claude"}

"matcher": "Write"
"matcher": "Write|Edit"
"matcher": "Bash"
"matcher": "mcp__.*__write.*"
"matcher": "*"

const { execFileSync } = require('node:child_process');

// Correct — stderr suppressed
try {
  const result = execFileSync('/usr/bin/node', ['--version'], {
    stdio: ['ignore', 'pipe', 'ignore'],
    timeout: 3000,
  });
} catch (err) {
  // Handle failure without leaking stderr
}

{
  "continue": true,
  "suppressOutput": false,
  "systemMessage": "Optional message shown to user"
}

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Auto-approved read-only file",
    "additionalContext": "Context for Claude"
  }
}

{"decision": "block", "reason": "Task not complete — tests not run"}

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Additional context prepended to prompt"
  }
}

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Project state loaded"
  }
}

flowchart TD
    A([Start: add a hook to a plugin]) --> B[Identify event and behavior]
    B --> C{Hook type?}
    C -->|Command — deterministic| D[Create hooks/myhook.cjs]
    C -->|Prompt — LLM-evaluated| E[Write prompt string directly in hooks.json]
    D --> F[Test script directly: echo input-json | node hooks/myhook.cjs]
    F --> G{Output valid JSON?}
    G -->|No| D
    G -->|Yes| H[Add entry to hooks/hooks.json using correct event + matcher]
    E --> H
    H --> I[Verify hooks.json is valid JSON: python3 -m json.tool hooks/hooks.json]
    I --> J[Restart Claude Code session — hooks snapshot at startup]
    J --> K[Test in session with claude --debug]
    K --> L{Hook fires correctly?}
    L -->|No| M[Check matcher case-sensitivity, event name, JSON syntax]
    M --> H
    L -->|Yes| N[Done]

# Test with minimal input
echo '{"tool_name":"Write","tool_input":{"file_path":"/tmp/test.txt"}}' | node ./hooks/my-hook.cjs

# Validate JSON output
echo '{"tool_name":"Write","tool_input":{"file_path":"/tmp/test.txt"}}' | node ./hooks/my-hook.cjs | python3 -m json.tool

{
  "description": "What these hooks enforce",
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/validate-write.cjs\"",
            "timeout": 3
          }
        ]
      }
    ]
  }
}

# Enable hook debug output
claude --debug
claude --debug "hooks"

# Check loaded hooks in session
/hooks