Hooks Reference

Claude Code hooks generated by the V3 init system.

Overview

The init system generates a complete hooks configuration in .claude/settings.json that integrates with Claude Code's hook system.

Generated Hook Types

PreToolUse Hooks

Executed before tool operations. Used for:

File edit validation
Command risk assessment
Task routing suggestions
Search pattern caching

json

{
  "PreToolUse": [
    {
      "matcher": "^(Write|Edit|MultiEdit)$",
      "hooks": [{
        "type": "command",
        "command": "npx @claude-flow/cli hooks pre-edit --file \"$TOOL_INPUT_file_path\"",
        "timeout": 5000,
        "continueOnError": true
      }]
    },
    {
      "matcher": "^Bash$",
      "hooks": [{
        "type": "command",
        "command": "npx @claude-flow/cli hooks pre-command --command \"$TOOL_INPUT_command\"",
        "timeout": 5000,
        "continueOnError": true
      }]
    },
    {
      "matcher": "^Task$",
      "hooks": [{
        "type": "command",
        "command": "npx @claude-flow/cli hooks pre-task --description \"$TOOL_INPUT_prompt\"",
        "timeout": 5000,
        "continueOnError": true
      }]
    },
    {
      "matcher": "^(Grep|Glob|Read)$",
      "hooks": [{
        "type": "command",
        "command": "npx @claude-flow/cli hooks pre-search --pattern \"$TOOL_INPUT_pattern\"",
        "timeout": 2000,
        "continueOnError": true
      }]
    }
  ]
}

PostToolUse Hooks

Executed after tool operations. Used for:

Pattern learning from edits
Command outcome recording
Task completion analysis
Search result caching

json

{
  "PostToolUse": [
    {
      "matcher": "^(Write|Edit|MultiEdit)$",
      "hooks": [{
        "type": "command",
        "command": "npx @claude-flow/cli hooks post-edit --file \"$TOOL_INPUT_file_path\" --success \"$TOOL_SUCCESS\" --train-patterns",
        "timeout": 5000,
        "continueOnError": true
      }]
    },
    {
      "matcher": "^Bash$",
      "hooks": [{
        "type": "command",
        "command": "npx @claude-flow/cli hooks post-command --command \"$TOOL_INPUT_command\" --success \"$TOOL_SUCCESS\" --exit-code \"$TOOL_EXIT_CODE\"",
        "timeout": 5000,
        "continueOnError": true
      }]
    },
    {
      "matcher": "^Task$",
      "hooks": [{
        "type": "command",
        "command": "npx @claude-flow/cli hooks post-task --agent-id \"$TOOL_RESULT_agent_id\" --success \"$TOOL_SUCCESS\" --analyze",
        "timeout": 5000,
        "continueOnError": true
      }]
    }
  ]
}

UserPromptSubmit Hook

Executes when user submits a prompt. Used for intelligent task routing.

json

{
  "UserPromptSubmit": [{
    "hooks": [{
      "type": "command",
      "command": "npx @claude-flow/cli hooks route --task \"$PROMPT\" --include-explanation",
      "timeout": 5000,
      "continueOnError": true
    }]
  }]
}

SessionStart Hook

Executes when a Claude Code session starts. Used for context restoration.

json

{
  "SessionStart": [{
    "hooks": [{
      "type": "command",
      "command": "npx @claude-flow/cli hooks session-start --session-id \"$SESSION_ID\" --load-context",
      "timeout": 10000,
      "continueOnError": true
    }]
  }]
}

Stop Hook

Executes when Claude Code considers stopping. Used for task completion evaluation.

json

{
  "Stop": [{
    "hooks": [{
      "type": "prompt",
      "prompt": "Evaluate task completion. Consider:\n1. Were all requested changes made?\n2. Did builds/tests pass?\n3. Is follow-up work needed?\n\nRespond with {\"decision\": \"stop\"} if complete, or {\"decision\": \"continue\", \"reason\": \"...\"} if more work is needed."
    }]
  }]
}

Notification Hook

Executes on notifications. Used for swarm status updates.

json

{
  "Notification": [{
    "hooks": [{
      "type": "command",
      "command": "npx @claude-flow/cli hooks notify --message \"$NOTIFICATION_MESSAGE\" --swarm-status",
      "timeout": 3000,
      "continueOnError": true
    }]
  }]
}

PermissionRequest Hook

Executes on permission requests. Used for auto-allowing claude-flow tools.

json

{
  "PermissionRequest": [
    {
      "matcher": "^mcp__claude-flow__.*$",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"decision\": \"allow\", \"reason\": \"claude-flow MCP tool auto-approved\"}'",
        "timeout": 1000
      }]
    },
    {
      "matcher": "^Bash\\(npx @?claude-flow.*\\)$",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"decision\": \"allow\", \"reason\": \"claude-flow CLI auto-approved\"}'",
        "timeout": 1000
      }]
    }
  ]
}

Hook Variables

Variable	Description
`$TOOL_INPUT_*`	Tool input parameters
`$TOOL_SUCCESS`	Whether tool succeeded
`$TOOL_EXIT_CODE`	Bash exit code
`$TOOL_RESULT_*`	Tool result values
`$PROMPT`	User's prompt text
`$SESSION_ID`	Current session ID
`$NOTIFICATION_MESSAGE`	Notification content

Configuration Options

typescript

interface HooksConfig {
  preToolUse: boolean;       // Enable PreToolUse hooks
  postToolUse: boolean;      // Enable PostToolUse hooks
  userPromptSubmit: boolean; // Enable task routing
  sessionStart: boolean;     // Enable session hooks
  stop: boolean;             // Enable stop evaluation
  notification: boolean;     // Enable notifications
  permissionRequest: boolean; // Enable auto-allow
  timeout: number;           // Default timeout (ms)
  continueOnError: boolean;  // Continue on hook failure
}

Customization

To customize hooks after initialization:

Edit .claude/settings.json
Modify hook commands or add new matchers
Adjust timeouts as needed
Add custom hooks for project-specific needs