hook-developer

intent

master claude code hooks to intercept, validate, and modify tool execution, user prompts, and session lifecycle events. use this when building hook handlers that block tool calls, inject context, automate permissions, or enforce custom logic before claude acts. hooks run synchronously as bash or llm-based evaluators, making them critical for security gates, auto-formatting, context injection, and workflow enforcement.

inputs

hook event system (all hooks receive):

• session_id: string, unique session identifier
• transcript_path: string, absolute path to session transcript
• cwd: string, current working directory
• permission_mode: string, one of "default", "plan", "acceptEdits", "bypassPermissions"
• hook_event_name: string, the event type firing (PreToolUse, PostToolUse, etc.)

external connections & setup:

• bash scripts: place in .claude/hooks/, mark executable (+x), invoke via settings.json
• typescript handlers: bundle with esbuild to dist/my-hook.mjs after edits
• env vars available to all hooks: CLAUDE_PROJECT_DIR (project root), CLAUDE_CODE_REMOTE ("true" if web, empty if local cli)
• sessionstart only: CLAUDE_ENV_FILE, write export VAR=value lines to persist env vars across sessions
• plugin hooks only: CLAUDE_PLUGIN_ROOT, absolute path to plugin directory

event-specific inputs:

PreToolUse: tool_name, tool_input (contains file_path, command, etc.), tool_use_id

PostToolUse: tool_name, tool_input, tool_response (contains filePath, success boolean, output string, exitCode integer) - note: field is tool_response, NOT tool_result

UserPromptSubmit: prompt (string, the user's input)

PermissionRequest: tool_name, tool_input

SessionStart: source (one of "startup", "resume", "clear", "compact")

SessionEnd: reason (one of "clear", "logout", "prompt_input_exit", "other")

Stop / SubagentStop: stop_hook_active (boolean, true if hook already ran once this session - critical to check to prevent infinite loops)

SubagentStart: agent_id (string)

PreCompact: trigger (one of "manual", "auto"), custom_instructions (string)

Notification: message (string), notification_type (one of "permission_prompt", "idle_prompt", "auth_success", "elicitation_dialog")

procedure

1. choose your hook type

command hooks (bash/python/typescript): execute synchronously, receive json stdin, output json or plain text stdout. default type. use for simple filtering, file checks, env var setup.

prompt hooks (llm-based): send context + prompt template to haiku, get structured decision. use for complex reasoning (e.g., "should claude stop based on task completion?").

2. register in settings.json

structure depends on whether hook requires a matcher (tool pattern):

for hooks with matchers (PreToolUse, PostToolUse, PermissionRequest, Notification, SessionStart, PreCompact):

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/my-hook.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

matcher patterns are case-sensitive:

• "Bash" matches exactly Bash tool
• "Edit|Write" matches Edit OR Write
• "Read." matches regex Read
• "mcp__.__write." matches all mcp write tools
• "*" matches all tools

for hooks without matchers (UserPromptSubmit, SessionEnd, Stop, SubagentStart, SubagentStop):

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [{ "type": "command", "command": "/path/to/hook.sh" }]
      }
    ]
  }
}

3. write your hook handler

shell wrapper (for typescript):

#!/bin/bash
set -e
cd "$CLAUDE_PROJECT_DIR/.claude/hooks"
cat | npx tsx src/my-hook.ts

or bundled:

#!/bin/bash
set -e
cd "$HOME/.claude/hooks"
cat | node dist/my-hook.mjs

typescript pattern:

import { readFileSync } from 'fs';

interface HookInput {
  session_id: string;
  hook_event_name: string;
  tool_name?: string;
  tool_input?: Record<string, unknown>;
  tool_response?: Record<string, unknown>;
  prompt?: string;
  [key: string]: unknown;
}

function readStdin(): string {
  return readFileSync(0, 'utf-8');
}

async function main() {
  const input: HookInput = JSON.parse(readStdin());
  
  // your logic here
  
  const output = {
    decision: 'block',
    reason: 'your reason'
  };

  console.log(JSON.stringify(output));
}

main().catch(console.error);

4. define input/output contract for your event

PreToolUse (blocks or modifies tool calls before execution):

input: session_id, transcript_path, cwd, permission_mode, hook_event_name, tool_name, tool_input, tool_use_id

output json:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow|deny|ask",
    "permissionDecisionReason": "string",
    "updatedInput": {}
  },
  "continue": true,
  "stopReason": "string",
  "systemMessage": "string",
  "suppressOutput": true
}

exit code 2: blocks tool, stderr shown to claude.

PostToolUse (react to tool results, provide feedback):

input: session_id, transcript_path, cwd, permission_mode, hook_event_name, tool_name, tool_input, tool_response, tool_use_id

output json:

{
  "decision": "block",
  "reason": "string",
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "string"
  },
  "continue": true,
  "stopReason": "string",
  "suppressOutput": true
}

decision: "block" with reason prompts claude to address the issue. exit code 2 passes stderr to claude.

UserPromptSubmit (validate user prompts, inject context):

input: session_id, transcript_path, cwd, permission_mode, hook_event_name, prompt

output plain text or json:

• any stdout text is added as context for claude
• json with decision: "block" and reason erases prompt, shows reason to user only (not claude)
• exit code 2 blocks prompt, shows stderr to user only

PermissionRequest (automate permission dialog decisions):

input: session_id, transcript_path, cwd, permission_mode, hook_event_name, tool_name, tool_input

output json:

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow|deny",
      "updatedInput": {},
      "message": "string",
      "interrupt": false
    }
  }
}

SessionStart (initialize session, load context, set env vars):

input: session_id, transcript_path, cwd, permission_mode, hook_event_name, source

output plain text or json:

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "string"
  },
  "suppressOutput": true
}

plain text stdout is added as context. write env vars to $CLAUDE_ENV_FILE as export VAR=value lines to persist across sessions.

SessionEnd (cleanup, save state, log session):

input: session_id, transcript_path, cwd, permission_mode, hook_event_name, reason

output: cannot affect session (already ending). use for cleanup and logging only.

Stop (control when claude stops, force continuation):

input: session_id, transcript_path, cwd, permission_mode, hook_event_name, stop_hook_active

output json:

{
  "decision": "block",
  "reason": "string"
}

decision: "block" forces claude to continue with reason as prompt. critical: check stop_hook_active: true to prevent infinite loops.

SubagentStart (run when task tool spawns subagent):

input: session_id, transcript_path, cwd, permission_mode, hook_event_name, agent_id

output: context injection only (cannot block).

SubagentStop (control when subagents finish):

input: session_id, transcript_path, cwd, permission_mode, hook_event_name, stop_hook_active

output: same as Stop. check stop_hook_active to avoid loops.

PreCompact (save state before context compaction):

input: session_id, transcript_path, cwd, permission_mode, hook_event_name, trigger, custom_instructions

output json:

{
  "continue": true,
  "systemMessage": "string"
}

Notification (custom notification handling):

input: session_id, transcript_path, cwd, permission_mode, hook_event_name, message, notification_type

output json:

{
  "continue": true,
  "suppressOutput": true,
  "systemMessage": "string"
}

5. test your hook manually before relying on it

# PreToolUse (Bash)
echo '{"tool_name":"Bash","tool_input":{"command":"ls"},"session_id":"test"}' | \
  .claude/hooks/my-hook.sh

# PostToolUse (Write)
echo '{"tool_name":"Write","tool_input":{"file_path":"test.md"},"tool_response":{"success":true},"session_id":"test"}' | \
  .claude/hooks/my-hook.sh

# SessionStart
echo '{"hook_event_name":"SessionStart","source":"startup","session_id":"test"}' | \
  .claude/hooks/session-start.sh

# SessionEnd
echo '{"hook_event_name":"SessionEnd","reason":"clear","session_id":"test"}' | \
  .claude/hooks/session-end.sh

# UserPromptSubmit
echo '{"prompt":"test prompt","session_id":"test"}' | \
  .claude/hooks/prompt-submit.sh

# PermissionRequest
echo '{"hook_event_name":"PermissionRequest","tool_name":"Bash","tool_input":{"command":"rm -rf /"},"session_id":"test"}' | \
  .claude/hooks/permission-hook.sh

# Stop (check stop_hook_active to prevent loops)
echo '{"hook_event_name":"Stop","stop_hook_active":false,"session_id":"test"}' | \
  .claude/hooks/stop-hook.sh

6. rebuild bundles after typescript changes

cd .claude/hooks
npx esbuild src/my-hook.ts \
  --bundle --platform=node --format=esm \
  --outfile=dist/my-hook.mjs

typescript edits do not auto-apply. rebuild is required.

7. reference mcp tool naming patterns

mcp tools use pattern mcp____:

• mcp__memory__.* matches all memory server tools
• mcp__.__write. matches all mcp write tools
• mcp__github__.* matches all github tools

decision points

if blocking a tool call: use PreToolUse with permissionDecision: "deny" or exit code 2. stderr is shown to claude.

if blocking a user prompt: use UserPromptSubmit with decision: "block". reason is shown to user only, not claude. prompt is erased.

if blocking a stop: check stop_hook_active: true in Stop or SubagentStop hooks. if true, don't block (return empty {}) to prevent infinite loops. if false and conditions met, return decision: "block" with reason.

if you need to inject context: use UserPromptSubmit (context added before prompt processing) or SessionStart (context added at session init). plain text stdout is injected automatically.

if you need to react to tool results: use PostToolUse. tool already executed, but you can block continuation with decision: "block" to ask claude to address issues.

if you need environment variables to persist: use SessionStart and write to $CLAUDE_ENV_FILE. each line must be export VAR=value.

if deciding based on complex logic: use type: "prompt" hooks (Stop, SubagentStop, PreToolUse). haiku llm evaluates context + your prompt template, returns structured decision.

if tool_response parsing fails: check that field name is tool_response, not tool_result. this is a common gotcha.

if hook times out: increase timeout in settings.json (default 60 seconds for command hooks, 30 for prompt hooks). network calls, file i/o, or bundling might exceed default.

if stderr from exit code 2 doesn't appear: verify hook is registered correctly and shell script has +x permission. run manual test first.

output contract

success looks like:

• hook registered in settings.json with correct event name, matcher (if required), and command path
• shell script exists, is executable (+x), and outputs valid json or plain text
• json response includes required fields for that hook type (decision, reason, hookSpecificOutput, etc.)
• exit code 0 for allow/continue, exit code 2 for block (stderr shown)
• any plain text stdout in UserPromptSubmit or SessionStart is injected into context
• env vars written to $CLAUDE_ENV_FILE persist across sessions
• stop_hook_active check prevents infinite loops

data format expectations:

• stdin is always valid json (one line)
• stdout for command hooks is valid json (structured response) or plain text (context injection)
• exit code 0: hook output processed normally
• exit code 2: blocking error, stderr message shown to claude/user depending on hook type
• other exit codes: non-blocking error, logged in verbose mode

file locations:

• hooks: .claude/hooks/my-hook.sh (bash), .claude/hooks/src/my-hook.ts (typescript source), .claude/hooks/dist/my-hook.mjs (bundled)
• settings: settings.json at project root, under "hooks" key
• env vars: written to path in $CLAUDE_ENV_FILE (e.g., .claude/.env)
• transcripts: path in transcript_path input parameter

outcome signal

you know the hook worked when:

• tool call is blocked: claude receives permission denied message or updated tool input
• user prompt is blocked: user sees reason message, prompt is not sent to claude
• context is injected: claude sees new context in conversation (UserPromptSubmit) or session starts with loaded context (SessionStart)
• permissions auto-approved/denied: permission dialog does not appear, behavior is automatic
• env vars persist: next session reads $CLAUDE_ENV_FILE and has variables set
• stop is enforced: claude continues with your reason as new prompt, does not end session
• manual test passes: echo command outputs valid json, exit code matches expectation

debugging checklist:

• hook registered in settings.json?
• shell script has +x permission?
• bundle rebuilt after ts changes? (esbuild command)
• using tool_response not tool_result in PostToolUse?
• output is valid json (or plain text for context injection)?
• checking stop_hook_active in Stop/SubagentStop hooks?
• using $CLAUDE_PROJECT_DIR for all relative paths?
• tested manually with echo before relying on it?
• matcher pattern is case-sensitive (Bash not bash)?
• timeout set appropriately for slow operations?

common patterns to copy:

block dangerous files (PreToolUse): check file_path for .env, secrets.json, .git/, deny if match found.

auto-format files (PostToolUse): parse tool_input.file_path, run prettier/black if .ts/.py, no blocking.

inject git context (UserPromptSubmit): output git status and recent commits as plain text, automatically injected.

force test verification (Stop): run npm test, block if exit code nonzero, reason tells claude tests are failing.

auto-approve safe tools (PermissionRequest): check tool_name and tool_input, return behavior: "allow" for safe patterns.

credits: original reference by parcadei. enriched for implexa standards with explicit decision points, edge case handling, and structured testing guidance.