ruvnet--ruflo/v3/implementation/init/HOOKS.md

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

{
  "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

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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

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:

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