claude-flow 2.0.0-alpha.26 → 2.0.0-alpha.27

package/bin/claude-flow

@@ -1,7 +1,7 @@
 #!/bin/sh
 # Claude-Flow Smart Dispatcher - Detects and uses the best available runtime
 
-VERSION="2.0.0-alpha.26"
+VERSION="2.0.0-alpha.27"
 
 # Determine the correct path based on how the script is invoked
 if [ -L "$0" ]; then

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "2.0.0-alpha.26",
+  "version": "2.0.0-alpha.27",
   "description": "Enterprise-grade AI agent orchestration with ruv-swarm integration (Alpha Release)",
   "main": "cli.mjs",
   "bin": {

package/src/cli/command-registry.js

@@ -18,6 +18,7 @@ import { analysisAction } from './simple-commands/analysis.js';
 import { automationAction } from './simple-commands/automation.js';
 import { coordinationAction } from './simple-commands/coordination.js';
 import { hooksAction } from './simple-commands/hooks.js';
+import { hookSafetyCommand } from './simple-commands/hook-safety.js';
 import { hiveMindCommand } from './simple-commands/hive-mind.js';
 import { showUnifiedMetrics, fixTaskAttribution } from './simple-commands/swarm-metrics-integration.js';
 // Note: TypeScript imports commented out for Node.js compatibility
@@ -400,6 +401,38 @@ Hooks commands:
 Enables automated preparation & cleanup, performance tracking, and coordination synchronization.`
   });
 
+  commandRegistry.set('hook-safety', {
+    handler: hookSafetyCommand,
+    description: '🚨 Critical hook safety system - Prevent infinite loops & financial damage',
+    usage: 'hook-safety <command> [options]',
+    examples: [
+      'hook-safety validate                           # Check for dangerous hook configurations',
+      'hook-safety validate --config ~/.claude/settings.json',
+      'hook-safety status                             # View safety status and context',
+      'hook-safety reset                              # Reset circuit breakers',
+      'hook-safety safe-mode                          # Enable safe mode (skip all hooks)'
+    ],
+    details: `
+🚨 CRITICAL: Stop hooks calling 'claude' commands create INFINITE LOOPS that can:
+  • Bypass API rate limits
+  • Cost thousands of dollars per day  
+  • Make your system unresponsive
+
+Hook Safety commands:
+  • validate: Check Claude Code settings for dangerous patterns
+  • status: Show current safety status and execution context
+  • reset: Reset circuit breakers and execution counters  
+  • safe-mode: Enable/disable safe mode (skips all hooks)
+
+SAFE ALTERNATIVES:
+  • Use PostToolUse hooks instead of Stop hooks
+  • Implement flag-based update patterns
+  • Use 'claude --skip-hooks' for manual updates
+  • Create conditional execution scripts
+
+For more information: https://github.com/ruvnet/claude-flow/issues/166`
+  });
+
   commandRegistry.set('hive', {
     handler: async (args, flags) => {
       try {

package/src/cli/simple-commands/hook-safety.js

@@ -0,0 +1,668 @@
+/**
+ * Hook Safety System - Prevents recursive hook execution and financial damage
+ * 
+ * This system protects against infinite loops where Claude Code hooks call
+ * 'claude' commands, which could bypass rate limits and cost thousands of dollars.
+ * 
+ * Critical protections:
+ * - Environment variable context detection
+ * - Recursive call prevention
+ * - Circuit breaker for Stop hooks
+ * - Configuration validation
+ * - Emergency override flags
+ */
+
+import { printError, printWarning, printSuccess } from '../utils.js';
+import { existsSync, readFileSync } from 'fs';
+import path from 'path';
+
+/**
+ * Hook Safety Configuration
+ */
+const HOOK_SAFETY_CONFIG = {
+  // Maximum hook execution depth before blocking
+  MAX_HOOK_DEPTH: 3,
+  
+  // Maximum Stop hook executions per session
+  MAX_STOP_HOOK_EXECUTIONS: 2,
+  
+  // Circuit breaker timeout (milliseconds)
+  CIRCUIT_BREAKER_TIMEOUT: 60000, // 1 minute
+  
+  // Environment variables for context detection
+  ENV_VARS: {
+    CONTEXT: 'CLAUDE_HOOK_CONTEXT',
+    DEPTH: 'CLAUDE_HOOK_DEPTH', 
+    SESSION_ID: 'CLAUDE_HOOK_SESSION_ID',
+    SKIP_HOOKS: 'CLAUDE_SKIP_HOOKS',
+    SAFE_MODE: 'CLAUDE_SAFE_MODE'
+  }
+};
+
+/**
+ * Global hook execution tracking
+ */
+class HookExecutionTracker {
+  constructor() {
+    this.executions = new Map();
+    this.sessionId = this.generateSessionId();
+    this.resetTimeout = null;
+  }
+  
+  generateSessionId() {
+    return `session-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+  }
+  
+  track(hookType) {
+    const key = `${this.sessionId}:${hookType}`;
+    const count = this.executions.get(key) || 0;
+    this.executions.set(key, count + 1);
+    
+    // Auto-reset after timeout
+    if (this.resetTimeout) clearTimeout(this.resetTimeout);
+    this.resetTimeout = setTimeout(() => {
+      this.executions.clear();
+    }, HOOK_SAFETY_CONFIG.CIRCUIT_BREAKER_TIMEOUT);
+    
+    return count + 1;
+  }
+  
+  getExecutionCount(hookType) {
+    const key = `${this.sessionId}:${hookType}`;
+    return this.executions.get(key) || 0;
+  }
+  
+  reset() {
+    this.executions.clear();
+    this.sessionId = this.generateSessionId();
+  }
+}
+
+// Global instance
+const executionTracker = new HookExecutionTracker();
+
+/**
+ * Hook Context Manager - Tracks hook execution context
+ */
+export class HookContextManager {
+  static setContext(hookType, depth = 1) {
+    process.env[HOOK_SAFETY_CONFIG.ENV_VARS.CONTEXT] = hookType;
+    process.env[HOOK_SAFETY_CONFIG.ENV_VARS.DEPTH] = depth.toString();
+    process.env[HOOK_SAFETY_CONFIG.ENV_VARS.SESSION_ID] = executionTracker.sessionId;
+  }
+  
+  static getContext() {
+    return {
+      type: process.env[HOOK_SAFETY_CONFIG.ENV_VARS.CONTEXT],
+      depth: parseInt(process.env[HOOK_SAFETY_CONFIG.ENV_VARS.DEPTH] || '0'),
+      sessionId: process.env[HOOK_SAFETY_CONFIG.ENV_VARS.SESSION_ID],
+      skipHooks: process.env[HOOK_SAFETY_CONFIG.ENV_VARS.SKIP_HOOKS] === 'true',
+      safeMode: process.env[HOOK_SAFETY_CONFIG.ENV_VARS.SAFE_MODE] === 'true'
+    };
+  }
+  
+  static clearContext() {
+    delete process.env[HOOK_SAFETY_CONFIG.ENV_VARS.CONTEXT];
+    delete process.env[HOOK_SAFETY_CONFIG.ENV_VARS.DEPTH];
+    delete process.env[HOOK_SAFETY_CONFIG.ENV_VARS.SESSION_ID];
+  }
+  
+  static isInHookContext() {
+    return !!process.env[HOOK_SAFETY_CONFIG.ENV_VARS.CONTEXT];
+  }
+  
+  static setSafeMode(enabled = true) {
+    if (enabled) {
+      process.env[HOOK_SAFETY_CONFIG.ENV_VARS.SAFE_MODE] = 'true';
+    } else {
+      delete process.env[HOOK_SAFETY_CONFIG.ENV_VARS.SAFE_MODE];
+    }
+  }
+  
+  static setSkipHooks(enabled = true) {
+    if (enabled) {
+      process.env[HOOK_SAFETY_CONFIG.ENV_VARS.SKIP_HOOKS] = 'true';
+    } else {
+      delete process.env[HOOK_SAFETY_CONFIG.ENV_VARS.SKIP_HOOKS];
+    }
+  }
+}
+
+/**
+ * Command Validator - Validates commands for hook safety
+ */
+export class HookCommandValidator {
+  /**
+   * Validate if a command is safe to execute from a hook
+   */
+  static validateCommand(command, hookType) {
+    const context = HookContextManager.getContext();
+    const warnings = [];
+    const errors = [];
+    
+    // Critical check: Claude commands in Stop hooks
+    if (hookType === 'Stop' && this.isClaudeCommand(command)) {
+      errors.push({
+        type: 'CRITICAL_RECURSION_RISK',
+        message: '🚨 CRITICAL ERROR: Claude command detected in Stop hook!\n' +
+                'This creates an INFINITE LOOP that can cost THOUSANDS OF DOLLARS.\n' +
+                'Stop hooks that call "claude" commands bypass rate limits and\n' +
+                'can result in massive unexpected API charges.\n\n' +
+                'BLOCKED FOR SAFETY - Use alternative patterns instead.'
+      });
+    }
+    
+    // General recursion detection
+    if (context.type && this.isClaudeCommand(command)) {
+      const depth = context.depth;
+      
+      if (depth >= HOOK_SAFETY_CONFIG.MAX_HOOK_DEPTH) {
+        errors.push({
+          type: 'HOOK_RECURSION_LIMIT',
+          message: `🚨 Hook recursion limit exceeded! (Depth: ${depth})\n` +
+                  `Hook type: ${context.type}\n` +
+                  'Blocking execution to prevent infinite loop.'
+        });
+      } else {
+        warnings.push({
+          type: 'POTENTIAL_RECURSION',
+          message: `⚠️  WARNING: Claude command in ${context.type} hook (depth: ${depth})\n` +
+                  'This could create recursion. Consider using --skip-hooks flag.'
+        });
+      }
+    }
+    
+    // Check for other dangerous patterns
+    if (this.isDangerousPattern(command, hookType)) {
+      warnings.push({
+        type: 'DANGEROUS_PATTERN',
+        message: `⚠️  WARNING: Potentially dangerous hook pattern detected.\n` +
+                'Review the command and consider safer alternatives.'
+      });
+    }
+    
+    return { warnings, errors, safe: errors.length === 0 };
+  }
+  
+  static isClaudeCommand(command) {
+    // Match various forms of claude command invocation
+    const claudePatterns = [
+      /\bclaude\b/,           // Direct claude command
+      /claude-code\b/,        // claude-code command
+      /npx\s+claude\b/,      // NPX claude
+      /\.\/claude\b/,        // Local claude wrapper
+      /claude\.exe\b/        // Windows executable
+    ];
+    
+    return claudePatterns.some(pattern => pattern.test(command));
+  }
+  
+  static isDangerousPattern(command, hookType) {
+    const dangerousPatterns = [
+      // Commands that could trigger more hooks
+      /git\s+commit.*--all/,
+      /git\s+add\s+\./,
+      // File operations that might trigger watchers
+      /watch\s+.*claude/,
+      /nodemon.*claude/,
+      // Recursive script execution
+      /bash.*hook/,
+      /sh.*hook/
+    ];
+    
+    return dangerousPatterns.some(pattern => pattern.test(command));
+  }
+}
+
+/**
+ * Circuit Breaker - Prevents runaway hook execution
+ */
+export class HookCircuitBreaker {
+  /**
+   * Check if hook execution should be allowed
+   */
+  static checkExecution(hookType) {
+    const executionCount = executionTracker.track(hookType);
+    
+    // Stop hook protection - maximum 2 executions per session
+    if (hookType === 'Stop' && executionCount > HOOK_SAFETY_CONFIG.MAX_STOP_HOOK_EXECUTIONS) {
+      throw new Error(
+        `🚨 CIRCUIT BREAKER ACTIVATED!\n` +
+        `Stop hook has executed ${executionCount} times in this session.\n` +
+        `This indicates a potential infinite loop that could cost thousands of dollars.\n` +
+        `Execution blocked for financial protection.\n\n` +
+        `To reset: Use --reset-circuit-breaker flag or restart your session.`
+      );
+    }
+    
+    // General protection for any hook type
+    if (executionCount > 20) {
+      throw new Error(
+        `🚨 CIRCUIT BREAKER: ${hookType} hook executed ${executionCount} times!\n` +
+        `This is highly unusual and indicates a potential problem.\n` +
+        `Execution blocked to prevent system overload.`
+      );
+    }
+    
+    // Log warnings for concerning patterns
+    if (hookType === 'Stop' && executionCount > 1) {
+      printWarning(`⚠️  Stop hook execution #${executionCount} detected. Monitor for recursion.`);
+    }
+    
+    return true;
+  }
+  
+  static reset() {
+    executionTracker.reset();
+    printSuccess('Circuit breaker reset successfully.');
+  }
+  
+  static getStatus() {
+    return {
+      sessionId: executionTracker.sessionId,
+      executions: Array.from(executionTracker.executions.entries()).map(([key, count]) => {
+        const [sessionId, hookType] = key.split(':');
+        return { hookType, count };
+      })
+    };
+  }
+}
+
+/**
+ * Configuration Validator - Validates hook configurations for safety
+ */
+export class HookConfigValidator {
+  /**
+   * Validate Claude Code settings.json for dangerous hook configurations
+   */
+  static validateClaudeCodeConfig(configPath = null) {
+    if (!configPath) {
+      // Try to find Claude Code settings
+      const possiblePaths = [
+        path.join(process.env.HOME || '.', '.claude', 'settings.json'),
+        path.join(process.cwd(), '.claude', 'settings.json'),
+        path.join(process.cwd(), 'settings.json')
+      ];
+      
+      configPath = possiblePaths.find(p => existsSync(p));
+      
+      if (!configPath) {
+        return { safe: true, message: 'No Claude Code configuration found.' };
+      }
+    }
+    
+    try {
+      const config = JSON.parse(readFileSync(configPath, 'utf8'));
+      const validation = this.validateHooksConfig(config.hooks || {});
+      
+      return {
+        safe: validation.errors.length === 0,
+        configPath,
+        ...validation
+      };
+    } catch (err) {
+      return {
+        safe: false,
+        error: `Failed to validate configuration: ${err.message}`,
+        configPath
+      };
+    }
+  }
+  
+  /**
+   * Validate hooks configuration object
+   */
+  static validateHooksConfig(hooksConfig) {
+    const warnings = [];
+    const errors = [];
+    
+    // Check Stop hooks specifically
+    if (hooksConfig.Stop) {
+      for (const hookGroup of hooksConfig.Stop) {
+        for (const hook of hookGroup.hooks || []) {
+          if (hook.type === 'command' && hook.command) {
+            const result = HookCommandValidator.validateCommand(hook.command, 'Stop');
+            warnings.push(...result.warnings);
+            errors.push(...result.errors);
+          }
+        }
+      }
+    }
+    
+    // Check other dangerous hook types
+    const dangerousHookTypes = ['SubagentStop', 'PostToolUse'];
+    for (const hookType of dangerousHookTypes) {
+      if (hooksConfig[hookType]) {
+        for (const hookGroup of hooksConfig[hookType]) {
+          for (const hook of hookGroup.hooks || []) {
+            if (hook.type === 'command' && hook.command) {
+              const result = HookCommandValidator.validateCommand(hook.command, hookType);
+              warnings.push(...result.warnings);
+              errors.push(...result.errors);
+            }
+          }
+        }
+      }
+    }
+    
+    return { warnings, errors };
+  }
+  
+  /**
+   * Generate safe configuration recommendations
+   */
+  static generateSafeAlternatives(dangerousConfig) {
+    const alternatives = [];
+    
+    // Example: Stop hook calling claude
+    if (dangerousConfig.includes('claude')) {
+      alternatives.push({
+        pattern: 'Stop hook with claude command',
+        problem: 'Creates infinite recursion loop',
+        solution: 'Use flag-based approach instead',
+        example: `
+// Instead of this DANGEROUS pattern:
+{
+  "Stop": [{
+    "hooks": [{"type": "command", "command": "claude -c -p 'Update history'"}]
+  }]
+}
+
+// Use this SAFE pattern:
+{
+  "Stop": [{
+    "hooks": [{"type": "command", "command": "touch ~/.claude/needs_update"}]
+  }]
+}
+
+// Then manually run: claude -c -p "Update history" when needed
+        `
+      });
+      
+      alternatives.push({
+        pattern: 'PostToolUse hook alternative',
+        problem: 'Stop hooks execute too frequently',
+        solution: 'Use PostToolUse for specific tools',
+        example: `
+// SAFER: Use PostToolUse for specific operations
+{
+  "PostToolUse": [{
+    "matcher": "Write|Edit|MultiEdit",
+    "hooks": [{"type": "command", "command": "echo 'File modified' >> ~/.claude/changes.log"}]
+  }]
+}
+        `
+      });
+    }
+    
+    return alternatives;
+  }
+}
+
+/**
+ * Safe Hook Execution Wrapper
+ */
+export class SafeHookExecutor {
+  /**
+   * Safely execute a hook command with all safety checks
+   */
+  static async executeHookCommand(command, hookType, options = {}) {
+    try {
+      // Skip if hooks are disabled
+      if (HookContextManager.getContext().skipHooks) {
+        console.log(`⏭️  Skipping ${hookType} hook (hooks disabled)`);
+        return { success: true, skipped: true };
+      }
+      
+      // Circuit breaker check
+      HookCircuitBreaker.checkExecution(hookType);
+      
+      // Command validation
+      const validation = HookCommandValidator.validateCommand(command, hookType);
+      
+      // Show warnings
+      for (const warning of validation.warnings) {
+        printWarning(warning.message);
+      }
+      
+      // Block on errors
+      if (!validation.safe) {
+        for (const error of validation.errors) {
+          printError(error.message);
+        }
+        return { success: false, blocked: true, errors: validation.errors };
+      }
+      
+      // Set hook context for nested calls
+      const currentContext = HookContextManager.getContext();
+      const newDepth = currentContext.depth + 1;
+      HookContextManager.setContext(hookType, newDepth);
+      
+      // Execute the command with safety context
+      const result = await this.executeCommand(command, options);
+      
+      return { success: true, result };
+      
+    } catch (err) {
+      printError(`Hook execution failed: ${err.message}`);
+      return { success: false, error: err.message };
+    } finally {
+      // Clear context
+      HookContextManager.clearContext();
+    }
+  }
+  
+  static async executeCommand(command, options = {}) {
+    // This would integrate with the actual command execution system
+    // For now, just log what would be executed
+    console.log(`🔗 Executing hook command: ${command}`);
+    
+    // Here you would actually execute the command
+    // return await execCommand(command, options);
+    
+    return { stdout: '', stderr: '', exitCode: 0 };
+  }
+}
+
+/**
+ * Hook Safety CLI Commands
+ */
+export async function hookSafetyCommand(subArgs, flags) {
+  const subcommand = subArgs[0];
+  
+  switch (subcommand) {
+    case 'validate':
+      return await validateConfigCommand(subArgs, flags);
+    case 'status':
+      return await statusCommand(subArgs, flags);
+    case 'reset':
+      return await resetCommand(subArgs, flags);
+    case 'safe-mode':
+      return await safeModeCommand(subArgs, flags);
+    default:
+      showHookSafetyHelp();
+  }
+}
+
+async function validateConfigCommand(subArgs, flags) {
+  const configPath = flags.config || flags.c;
+  
+  console.log('🔍 Validating hook configuration for safety...\n');
+  
+  const result = HookConfigValidator.validateClaudeCodeConfig(configPath);
+  
+  if (result.safe) {
+    printSuccess('✅ Hook configuration is safe!');
+    if (result.configPath) {
+      console.log(`📄 Validated: ${result.configPath}`);
+    }
+  } else {
+    printError('❌ DANGEROUS hook configuration detected!');
+    
+    if (result.errors) {
+      console.log('\n🚨 CRITICAL ERRORS:');
+      for (const error of result.errors) {
+        console.log(`\n${error.message}`);
+      }
+    }
+    
+    if (result.warnings) {
+      console.log('\n⚠️  WARNINGS:');
+      for (const warning of result.warnings) {
+        console.log(`\n${warning.message}`);
+      }
+    }
+    
+    console.log('\n💡 RECOMMENDATIONS:');
+    console.log('1. Remove claude commands from Stop hooks');
+    console.log('2. Use PostToolUse hooks for specific tools');
+    console.log('3. Implement flag-based update patterns');
+    console.log('4. Use claude --skip-hooks for manual updates');
+  }
+}
+
+async function statusCommand(subArgs, flags) {
+  const context = HookContextManager.getContext();
+  const circuitStatus = HookCircuitBreaker.getStatus();
+  
+  console.log('🔗 Hook Safety Status\n');
+  
+  console.log('📊 Current Context:');
+  if (context.type) {
+    console.log(`  🔄 Hook Type: ${context.type}`);
+    console.log(`  📏 Depth: ${context.depth}`);
+    console.log(`  🆔 Session: ${context.sessionId}`);
+    console.log(`  ⏭️  Skip Hooks: ${context.skipHooks ? 'Yes' : 'No'}`);
+    console.log(`  🛡️  Safe Mode: ${context.safeMode ? 'Yes' : 'No'}`);
+  } else {
+    console.log('  ✅ Not currently in hook context');
+  }
+  
+  console.log('\n⚡ Circuit Breaker Status:');
+  console.log(`  🆔 Session: ${circuitStatus.sessionId}`);
+  
+  if (circuitStatus.executions.length > 0) {
+    console.log('  📊 Hook Executions:');
+    for (const exec of circuitStatus.executions) {
+      console.log(`    • ${exec.hookType}: ${exec.count} times`);
+    }
+  } else {
+    console.log('  ✅ No hook executions in current session');
+  }
+}
+
+async function resetCommand(subArgs, flags) {
+  console.log('🔄 Resetting hook safety systems...\n');
+  
+  HookCircuitBreaker.reset();
+  HookContextManager.clearContext();
+  
+  printSuccess('✅ Hook safety systems reset successfully!');
+  console.log('All execution counters and context cleared.');
+}
+
+async function safeModeCommand(subArgs, flags) {
+  const enable = !flags.disable && !flags.off;
+  
+  if (enable) {
+    HookContextManager.setSafeMode(true);
+    HookContextManager.setSkipHooks(true);
+    printSuccess('🛡️  Safe mode enabled!');
+    console.log('• All hooks will be skipped');
+    console.log('• Claude commands will show safety warnings');
+    console.log('• Additional validation will be performed');
+  } else {
+    HookContextManager.setSafeMode(false);
+    HookContextManager.setSkipHooks(false);
+    printSuccess('⚡ Safe mode disabled.');
+    console.log('Normal hook execution restored.');
+  }
+}
+
+function showHookSafetyHelp() {
+  console.log(`
+🛡️  Hook Safety System - Prevent Infinite Loops & Financial Damage
+
+USAGE:
+  claude-flow hook-safety <command> [options]
+
+COMMANDS:
+  validate      Validate hook configuration for dangerous patterns
+  status        Show current hook safety status and context
+  reset         Reset circuit breakers and execution counters
+  safe-mode     Enable/disable safe mode (skips all hooks)
+
+VALIDATE OPTIONS:
+  --config, -c <path>     Path to Claude Code settings.json
+
+SAFE-MODE OPTIONS:
+  --disable, --off        Disable safe mode
+
+EXAMPLES:
+  # Check your Claude Code hooks for dangerous patterns
+  claude-flow hook-safety validate
+
+  # Check specific configuration file
+  claude-flow hook-safety validate --config ~/.claude/settings.json
+
+  # View current safety status
+  claude-flow hook-safety status
+
+  # Reset if circuit breaker is triggered
+  claude-flow hook-safety reset
+
+  # Enable safe mode (skips all hooks)
+  claude-flow hook-safety safe-mode
+
+  # Disable safe mode
+  claude-flow hook-safety safe-mode --disable
+
+🚨 CRITICAL WARNING:
+Stop hooks that call 'claude' commands create INFINITE LOOPS that can:
+• Bypass API rate limits
+• Cost thousands of dollars per day
+• Make your system unresponsive
+
+SAFE ALTERNATIVES:
+• Use PostToolUse hooks instead of Stop hooks
+• Implement flag-based update patterns
+• Use 'claude --skip-hooks' for manual updates
+• Create conditional execution scripts
+
+For more information: https://github.com/ruvnet/claude-flow/issues/166
+`);
+}
+
+/**
+ * Emergency CLI flags for Claude commands
+ */
+export function addSafetyFlags(command) {
+  // Add safety flags to any claude command
+  const context = HookContextManager.getContext();
+  
+  if (context.type) {
+    // Automatically add --skip-hooks if in hook context
+    if (!command.includes('--skip-hooks')) {
+      command += ' --skip-hooks';
+    }
+  }
+  
+  if (context.safeMode) {
+    // Add additional safety flags in safe mode
+    if (!command.includes('--dry-run')) {
+      command += ' --dry-run';
+    }
+  }
+  
+  return command;
+}
+
+export default {
+  HookContextManager,
+  HookCommandValidator, 
+  HookCircuitBreaker,
+  HookConfigValidator,
+  SafeHookExecutor,
+  hookSafetyCommand,
+  addSafetyFlags
+};

package/src/cli/simple-commands/init/templates/claude-flow-universal

@@ -45,7 +45,7 @@
     
     // 3. NPX with latest alpha version (prioritized over global)
     async () => {
-      return spawn('npx', ['claude-flow@2.0.0-alpha.26', ...process.argv.slice(2)], { stdio: 'inherit' });
+      return spawn('npx', ['claude-flow@2.0.0-alpha.27', ...process.argv.slice(2)], { stdio: 'inherit' });
     }
   ];
 

package/src/cli/simple-commands/init/templates/safe-hook-patterns.js

@@ -0,0 +1,381 @@
+/**
+ * Safe Hook Patterns - Templates for safe Claude Code hook configurations
+ * 
+ * These patterns prevent infinite loops that could cost thousands of dollars
+ * by avoiding recursive hook execution when hooks call 'claude' commands.
+ */
+
+/**
+ * DANGEROUS PATTERN - DO NOT USE
+ * This creates an infinite loop that can cost thousands of dollars!
+ */
+export const DANGEROUS_PATTERN_EXAMPLE = {
+  name: "DANGEROUS: Stop hook calling claude command",
+  description: "❌ NEVER USE THIS - Creates infinite recursion loop",
+  pattern: {
+    "hooks": {
+      "Stop": [{
+        "matcher": "",
+        "hooks": [{
+          "type": "command",
+          "command": "claude -c -p \"Update all changes to history.md\""
+        }]
+      }]
+    }
+  },
+  problems: [
+    "🚨 Creates infinite loop: Stop → claude command → Stop → claude command...",
+    "💰 Can cost $3600+ per day by bypassing rate limits",
+    "🚫 Makes system unresponsive",
+    "⚡ No built-in protection in Claude Code"
+  ]
+};
+
+/**
+ * SAFE PATTERN 1: Flag-based updates
+ * Set a flag instead of calling claude directly
+ */
+export const SAFE_FLAG_PATTERN = {
+  name: "Safe Pattern: Flag-based updates",
+  description: "✅ Set flag when update needed, run manually",
+  pattern: {
+    "hooks": {
+      "Stop": [{
+        "matcher": "",
+        "hooks": [{
+          "type": "command",
+          "command": "bash -c 'echo \"History update needed at $(date)\" > ~/.claude/needs_update && echo \"📝 History update flagged. Run: claude -c -p \\\"Update history.md\\\"\"'"
+        }]
+      }]
+    }
+  },
+  benefits: [
+    "✅ No recursion - just sets a flag",
+    "💰 Zero risk of infinite API calls",
+    "🔄 User controls when update runs",
+    "📝 Clear instructions for manual execution"
+  ],
+  usage: [
+    "1. Hook sets flag when update is needed",
+    "2. User sees notification",
+    "3. User manually runs: claude -c -p \"Update history.md\"",
+    "4. Update runs once safely"
+  ]
+};
+
+/**
+ * SAFE PATTERN 2: PostToolUse hooks instead of Stop hooks
+ * React to specific tool usage rather than session end
+ */
+export const SAFE_POST_TOOL_PATTERN = {
+  name: "Safe Pattern: PostToolUse hooks",
+  description: "✅ React to specific file operations instead of Stop events",
+  pattern: {
+    "hooks": {
+      "PostToolUse": [{
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [{
+          "type": "command",
+          "command": "echo 'File modified: {file}' >> ~/.claude/modifications.log"
+        }]
+      }]
+    }
+  },
+  benefits: [
+    "✅ Only triggers on actual file changes",
+    "🎯 More precise than Stop hooks",
+    "📝 Logs specific modifications",
+    "🔄 No risk of Stop hook recursion"
+  ],
+  usage: [
+    "1. Triggers only when files are written/edited",
+    "2. Logs the specific file that was modified", 
+    "3. Can be used for change tracking",
+    "4. Safe to use with any logging command"
+  ]
+};
+
+/**
+ * SAFE PATTERN 3: Conditional execution with skip-hooks
+ * Check for hook context before executing claude commands
+ */
+export const SAFE_CONDITIONAL_PATTERN = {
+  name: "Safe Pattern: Conditional execution with context check",
+  description: "✅ Check if running in hook context before calling claude",
+  pattern: {
+    "hooks": {
+      "Stop": [{
+        "matcher": "",
+        "hooks": [{
+          "type": "command",
+          "command": "bash -c 'if [ -z \"$CLAUDE_HOOK_CONTEXT\" ]; then claude -c -p \"Update history.md\" --skip-hooks; else echo \"Skipping update - in hook context\"; fi'"
+        }]
+      }]
+    }
+  },
+  benefits: [
+    "✅ Checks hook context before execution",
+    "🛡️ Uses --skip-hooks flag for safety",
+    "🔄 Prevents recursive hook calls",
+    "📊 Provides clear feedback"
+  ],
+  usage: [
+    "1. Checks CLAUDE_HOOK_CONTEXT environment variable",
+    "2. Only runs claude if not in hook context",
+    "3. Uses --skip-hooks to prevent triggering more hooks",
+    "4. Shows clear message when skipping"
+  ]
+};
+
+/**
+ * SAFE PATTERN 4: Batch processing with scheduled execution
+ * Accumulate changes and process them on a schedule
+ */
+export const SAFE_BATCH_PATTERN = {
+  name: "Safe Pattern: Batch processing with scheduled execution",
+  description: "✅ Accumulate changes and process them separately",
+  pattern: {
+    "hooks": {
+      "Stop": [{
+        "matcher": "",
+        "hooks": [{
+          "type": "command",
+          "command": "echo \"$(date): Session ended\" >> ~/.claude/session_log.txt"
+        }]
+      }]
+    }
+  },
+  additionalSetup: {
+    cronJob: "# Add to crontab (run every hour):\n# 0 * * * * /path/to/update-history.sh",
+    updateScript: `#!/bin/bash
+# update-history.sh - Safe batch update script
+LOCK_FILE="~/.claude/update.lock"
+LOG_FILE="~/.claude/session_log.txt"
+
+# Check if update is already running
+if [ -f "$LOCK_FILE" ]; then
+    echo "Update already in progress"
+    exit 1
+fi
+
+# Create lock file
+touch "$LOCK_FILE"
+
+# Check if there are new sessions to process
+if [ -f "$LOG_FILE" ] && [ -s "$LOG_FILE" ]; then
+    echo "Processing accumulated changes..."
+    claude -c -p "Update history.md with recent session data" --skip-hooks
+    
+    # Archive the log
+    mv "$LOG_FILE" "~/.claude/session_log_$(date +%Y%m%d_%H%M%S).txt"
+fi
+
+# Remove lock file
+rm "$LOCK_FILE"`
+  },
+  benefits: [
+    "✅ No risk of recursion",
+    "⏰ Scheduled processing prevents overload",
+    "🔒 Lock file prevents concurrent updates",
+    "📦 Batches multiple sessions efficiently"
+  ]
+};
+
+/**
+ * SAFE PATTERN 5: Database/file-based queue system
+ * Use external queue for processing commands
+ */
+export const SAFE_QUEUE_PATTERN = {
+  name: "Safe Pattern: Queue-based command processing",
+  description: "✅ Queue commands for external processing",
+  pattern: {
+    "hooks": {
+      "Stop": [{
+        "matcher": "",
+        "hooks": [{
+          "type": "command",
+          "command": "echo '{\"command\": \"update-history\", \"timestamp\": \"'$(date -Iseconds)'\", \"session\": \"'$CLAUDE_SESSION_ID'\"}' >> ~/.claude/command_queue.jsonl"
+        }]
+      }]
+    }
+  },
+  processor: `#!/usr/bin/env python3
+# queue-processor.py - Safe command queue processor
+import json
+import subprocess
+import time
+import os
+from pathlib import Path
+
+QUEUE_FILE = Path.home() / '.claude' / 'command_queue.jsonl'
+PROCESSING_INTERVAL = 300  # 5 minutes
+
+def process_queue():
+    if not QUEUE_FILE.exists():
+        return
+    
+    # Read and clear queue atomically
+    with open(QUEUE_FILE, 'r') as f:
+        lines = f.readlines()
+    
+    # Clear the queue
+    QUEUE_FILE.unlink()
+    
+    # Process commands
+    for line in lines:
+        try:
+            cmd_data = json.loads(line.strip())
+            if cmd_data['command'] == 'update-history':
+                print(f"Processing history update for session {cmd_data['session']}")
+                subprocess.run([
+                    'claude', '-c', '-p', 'Update history.md', '--skip-hooks'
+                ], check=True)
+                time.sleep(2)  # Rate limiting
+        except Exception as e:
+            print(f"Error processing command: {e}")
+
+if __name__ == '__main__':
+    while True:
+        try:
+            process_queue()
+            time.sleep(PROCESSING_INTERVAL)
+        except KeyboardInterrupt:
+            break`,
+  benefits: [
+    "✅ Complete separation of hook and claude execution",
+    "⏰ Rate limited processing",
+    "🔄 Handles multiple queued commands",
+    "🛡️ No risk of infinite loops"
+  ]
+};
+
+/**
+ * Get all safe patterns for documentation generation
+ */
+export const ALL_SAFE_PATTERNS = [
+  SAFE_FLAG_PATTERN,
+  SAFE_POST_TOOL_PATTERN,
+  SAFE_CONDITIONAL_PATTERN,
+  SAFE_BATCH_PATTERN,
+  SAFE_QUEUE_PATTERN
+];
+
+/**
+ * Generate safe hooks documentation
+ */
+export function generateSafeHooksGuide() {
+  return `# 🛡️ Safe Hook Patterns for Claude Code
+
+⚠️ **CRITICAL WARNING**: Stop hooks that call 'claude' commands create infinite loops that can cost thousands of dollars per day!
+
+## 🚨 DANGEROUS PATTERN (NEVER USE)
+
+${DANGEROUS_PATTERN_EXAMPLE.description}
+
+\`\`\`json
+${JSON.stringify(DANGEROUS_PATTERN_EXAMPLE.pattern, null, 2)}
+\`\`\`
+
+**Problems:**
+${DANGEROUS_PATTERN_EXAMPLE.problems.map(p => `- ${p}`).join('\n')}
+
+---
+
+## ✅ SAFE PATTERNS
+
+${ALL_SAFE_PATTERNS.map(pattern => `
+### ${pattern.name}
+
+${pattern.description}
+
+**Configuration:**
+\`\`\`json
+${JSON.stringify(pattern.pattern, null, 2)}
+\`\`\`
+
+**Benefits:**
+${pattern.benefits.map(b => `- ${b}`).join('\n')}
+
+${pattern.usage ? `**Usage:**
+${pattern.usage.map((u, i) => `${i + 1}. ${u}`).join('\n')}` : ''}
+
+${pattern.additionalSetup ? `**Additional Setup:**
+${pattern.additionalSetup.cronJob ? `
+**Cron Job:**
+\`\`\`bash
+${pattern.additionalSetup.cronJob}
+\`\`\`
+` : ''}
+
+${pattern.additionalSetup.updateScript ? `
+**Update Script:**
+\`\`\`bash
+${pattern.additionalSetup.updateScript}
+\`\`\`
+` : ''}` : ''}
+
+${pattern.processor ? `
+**Queue Processor:**
+\`\`\`python
+${pattern.processor}
+\`\`\`
+` : ''}
+
+---
+`).join('')}
+
+## 🚀 Quick Migration Guide
+
+### If you currently have this DANGEROUS pattern:
+\`\`\`json
+{
+  "hooks": {
+    "Stop": [{"hooks": [{"type": "command", "command": "claude -c -p 'Update history'"}]}]
+  }
+}
+\`\`\`
+
+### Replace with this SAFE pattern:
+\`\`\`json
+{
+  "hooks": {
+    "Stop": [{"hooks": [{"type": "command", "command": "touch ~/.claude/needs_update && echo 'Run: claude -c -p \"Update history\"'"}]}]
+  }
+}
+\`\`\`
+
+## 🛡️ Hook Safety Tools
+
+Use claude-flow's built-in safety tools:
+
+\`\`\`bash
+# Check your configuration for dangerous patterns
+claude-flow hook-safety validate
+
+# Enable safe mode (skips all hooks)
+claude-flow hook-safety safe-mode
+
+# Check current safety status
+claude-flow hook-safety status
+
+# Reset circuit breakers if triggered
+claude-flow hook-safety reset
+\`\`\`
+
+## 📚 Additional Resources
+
+- Issue #166: https://github.com/ruvnet/claude-flow/issues/166
+- Claude Code Hooks Documentation: https://docs.anthropic.com/en/docs/claude-code/hooks
+- Reddit Discussion: https://www.reddit.com/r/ClaudeAI/comments/1ltvi6x/anyone_else_accidentally_create_an_infinite_loop/
+
+---
+
+**Remember**: When in doubt, use flag-based patterns or PostToolUse hooks instead of Stop hooks!
+`;
+}
+
+export default {
+  DANGEROUS_PATTERN_EXAMPLE,
+  ALL_SAFE_PATTERNS,
+  generateSafeHooksGuide
+};