Create Your Own Hook

cd src/hooks
npm install
npm run build       # Compile TypeScript to ESM bundles
npm run typecheck   # Verify types without building
npm test            # Run the test suite

interface HookInput {
  // Core fields (always present)
  hook_event?: HookEvent;       // 'PreToolUse' | 'PostToolUse' | 'PermissionRequest' | ...
  tool_name: string;            // 'Bash' | 'Write' | 'Edit' | 'Read' | 'Task' | ...
  session_id: string;           // Guaranteed by CC 2.1.9+
  tool_input: ToolInput;        // Tool-specific parameters (see below)
  project_dir?: string;         // Absolute path to the project

  // PostToolUse only
  tool_output?: unknown;        // The tool's output
  tool_error?: string;          // Error message if the tool failed
  exit_code?: number;           // Bash exit code

  // UserPromptSubmit only
  prompt?: string;              // The user's prompt text

  // SubagentStart / SubagentStop
  subagent_type?: string;       // Agent type being spawned
  agent_output?: string;        // Agent output (SubagentStop)
  duration_ms?: number;         // Execution time

  // CC 2.1.25
  permissionMode?: 'default' | 'acceptEdits' | 'dontAsk';
}

interface ToolInput {
  command?: string;       // Bash tool
  timeout?: number;       // Bash tool
  file_path?: string;     // Write, Edit, Read tools
  content?: string;       // Write tool
  old_string?: string;    // Edit tool
  new_string?: string;    // Edit tool
  pattern?: string;       // Glob, Grep tools
  [key: string]: unknown; // Additional properties
}

import { isBashInput, isWriteInput, isEditInput, isReadInput } from '../types.js';

if (isBashInput(input.tool_input)) {
  // TypeScript knows input.tool_input.command exists
  const command: string = input.tool_input.command;
}

if (isWriteInput(input.tool_input)) {
  // TypeScript knows file_path and content exist
  const { file_path, content } = input.tool_input;
}

interface HookResult {
  continue: boolean;              // true = proceed, false = block
  suppressOutput?: boolean;       // Hide hook output from user
  systemMessage?: string;         // Message shown to user
  stopReason?: string;            // Why the operation was blocked (when continue=false)
  hookSpecificOutput?: {
    permissionDecision?: 'allow' | 'deny';
    permissionDecisionReason?: string;
    additionalContext?: string;     // Injected into Claude's context (CC 2.1.9)
    hookEventName?: HookEvent;     // Required when using additionalContext
    updatedInput?: Record<string, unknown>; // Modify tool input (CC 2.1.25)
  };
}

type HookFn = (input: HookInput) => HookResult | Promise<HookResult>;

import { guardBash, guardWriteEdit, runGuards } from '../../lib/guards.js';

export function myHook(input: HookInput): HookResult {
  // Single guard
  const guardResult = guardBash(input);
  if (guardResult) return guardResult;

  // Multiple guards (all must pass)
  const result = runGuards(input, guardBash, guardNontrivialBash);
  if (result) return result;

  // Hook logic...
}

const result = runGuards(input, guardBash, guardNontrivialBash, guardGitCommand);
// Only runs hook logic for non-trivial git commands

npm run build

dist/
  permission.mjs    (8 KB)
  pretool.mjs       (48 KB)
  posttool.mjs      (58 KB)
  prompt.mjs        (57 KB)
  lifecycle.mjs     (31 KB)
  stop.mjs          (33 KB)
  subagent.mjs      (56 KB)
  notification.mjs  (5 KB)
  setup.mjs         (24 KB)
  skill.mjs         (52 KB)
  agent.mjs         (8 KB)
  hooks.mjs         (324 KB, unified, for CLI tools only)
  bundle-stats.json (build metrics)

npm run build:watch

cd src/hooks
npm test                        # Run all tests
npm run test:watch              # Watch mode
npm test -- --filter my-hook    # Run specific test

// GOOD: Silent when nothing to report
if (noIssuesFound) return outputSilentSuccess();

// BAD: Noisy output for normal operations
return { continue: true, systemMessage: "Hook completed successfully!" };

// GOOD: Explain what happened and how to fix it
return outputBlock(
  `Direct commits to 'main' branch are not allowed.\n\n` +
  `Fix: Create a feature branch\n` +
  `  git checkout -b feature/my-feature\n` +
  `  git commit -m "Your changes"\n` +
  `  gh pr create`
);

// BAD: Vague error
return outputBlock('Operation not allowed');

// GOOD: Catch errors, return silent success
export function myHook(input: HookInput): HookResult {
  try {
    // Hook logic...
    return outputSilentSuccess();
  } catch (err) {
    logHook('my-hook', `Error: ${err.message}`);
    return outputSilentSuccess();  // Don't block on hook errors
  }
}

// BAD: Let errors crash the hook
export function myHook(input: HookInput): HookResult {
  const data = fs.readFileSync('/might-not-exist');  // Unhandled throw!
}

// GOOD: Log meaningful events
logHook('my-hook', `Blocked dangerous command: ${command}`);

// BAD: Log noise
logHook('my-hook', 'Hook started');
logHook('my-hook', 'Checking command...');
logHook('my-hook', 'Command is safe');
logHook('my-hook', 'Hook finished');