specweave 0.30.19 → 0.32.2

package/plugins/specweave/hooks/pre-task-completion.sh

@@ -167,11 +167,7 @@ fi
 if [ "$COMPLETING_TASK" = "false" ]; then
   echo "[$(date)] ⏭️  No tasks being completed, skipping validation" >> "$DEBUG_LOG" 2>/dev/null || true
   rm -f "$STDIN_DATA"
-  cat <<EOF
-{
-  "continue": true
-}
-EOF
+  echo '{"continue":true}'
   exit 0
 fi
 
@@ -184,11 +180,7 @@ CURRENT_INCREMENT=$(ls -td .specweave/increments/*/ 2>/dev/null | xargs -n1 base
 if [ -z "$CURRENT_INCREMENT" ]; then
   echo "[$(date)] ℹ️  No active increment found, skipping validation" >> "$DEBUG_LOG" 2>/dev/null || true
   rm -f "$STDIN_DATA"
-  cat <<EOF
-{
-  "continue": true
-}
-EOF
+  echo '{"continue":true}'
   exit 0
 fi
 
@@ -197,11 +189,7 @@ TASKS_MD=".specweave/increments/$CURRENT_INCREMENT/tasks.md"
 if [ ! -f "$TASKS_MD" ]; then
   echo "[$(date)] ℹ️  tasks.md not found for $CURRENT_INCREMENT (increment may be in planning stage)" >> "$DEBUG_LOG" 2>/dev/null || true
   rm -f "$STDIN_DATA"
-  cat <<EOF
-{
-  "continue": true
-}
-EOF
+  echo '{"continue":true}'
   exit 0
 fi
 
@@ -231,12 +219,7 @@ fi
 if [ -z "$VALIDATOR_SCRIPT" ] || ! command -v node &> /dev/null; then
   echo "[$(date)] ⚠️  AC test validator not found or Node.js missing" >> "$DEBUG_LOG" 2>/dev/null || true
   rm -f "$STDIN_DATA"
-  cat <<EOF
-{
-  "continue": true,
-  "systemMessage": "⚠️  Warning: AC test validator not available. Task completion validation skipped. Install Node.js and rebuild SpecWeave to enable validation."
-}
-EOF
+  echo '{"continue":true,"systemMessage":"⚠️  Warning: AC test validator not available. Task completion validation skipped. Install Node.js and rebuild SpecWeave to enable validation."}'
   exit 0
 fi
 
@@ -262,16 +245,11 @@ if [ "$VALIDATION_EXIT_CODE" = "0" ]; then
   # Reset circuit breaker on success
   echo "0" > "$CIRCUIT_BREAKER_FILE" 2>/dev/null || true
 
-  VALIDATION_SUMMARY=$(cat "$VALIDATION_OUTPUT" | tail -5 | tr '\n' ' ')
+  VALIDATION_SUMMARY=$(cat "$VALIDATION_OUTPUT" | tail -5 | tr '\n' ' ' | sed 's/"/\\"/g')
 
   rm -f "$VALIDATION_OUTPUT"
 
-  cat <<EOF
-{
-  "continue": true,
-  "systemMessage": "✅ AC Test Validation Passed: All acceptance criteria have passing tests. Task completion allowed. ${VALIDATION_SUMMARY}"
-}
-EOF
+  printf '{"continue":true,"systemMessage":"✅ AC Test Validation Passed: All acceptance criteria have passing tests. Task completion allowed. %s"}\n' "$VALIDATION_SUMMARY"
 else
   # Validation failed - block completion
   echo "[$(date)] ❌ AC test validation failed" >> "$DEBUG_LOG" 2>/dev/null || true
@@ -280,18 +258,11 @@ else
   CURRENT_FAILURES=$(cat "$CIRCUIT_BREAKER_FILE" 2>/dev/null || echo 0)
   echo "$((CURRENT_FAILURES + 1))" > "$CIRCUIT_BREAKER_FILE" 2>/dev/null || true
 
-  VALIDATION_ERROR=$(cat "$VALIDATION_OUTPUT" | grep -A 10 "VALIDATION FAILED" | tr '\n' ' ' | cut -c 1-300)
+  VALIDATION_ERROR=$(cat "$VALIDATION_OUTPUT" | grep -A 10 "VALIDATION FAILED" | tr '\n' ' ' | cut -c 1-300 | sed 's/"/\\"/g')
 
   rm -f "$VALIDATION_OUTPUT"
 
-  cat <<EOF
-{
-  "continue": false,
-  "systemMessage": "❌ AC TEST VALIDATION FAILED: Cannot mark task as complete until all acceptance criteria have passing tests. ${VALIDATION_ERROR}
-
-Fix the failing tests and try again. Run tests manually: npm test"
-}
-EOF
+  printf '{"continue":false,"systemMessage":"❌ AC TEST VALIDATION FAILED: Cannot mark task as complete until all acceptance criteria have passing tests. %s\\n\\nFix the failing tests and try again. Run tests manually: npm test"}\n' "$VALIDATION_ERROR"
 fi
 
 # ALWAYS exit 0 - NEVER let hook errors crash Claude Code

package/plugins/specweave/hooks/pre-task-completion.sh.backup

@@ -0,0 +1,194 @@
+#!/bin/bash
+
+# SpecWeave Pre-Task-Completion Hook
+# CRITICAL QUALITY GATE: Validates AC tests before allowing task completion
+#
+# Runs automatically BEFORE any task is marked complete via TodoWrite
+#
+# WORKFLOW:
+# =========
+# 1. TodoWrite called with status="completed"
+# 2. This hook fires (pre-completion validation)
+# 3. Extract task ID from TodoWrite input
+# 4. Find task in tasks.md
+# 5. Run AC test validator
+# 6. If tests PASS → Allow completion (continue: true)
+# 7. If tests FAIL → Block completion (continue: false, show error)
+#
+# ENFORCEMENT:
+# ============
+# This is the ONLY way to mark tasks complete in SpecWeave.
+# Manual edits to tasks.md are detected and flagged by pre-commit hooks.
+
+set -e
+
+# Find project root
+find_project_root() {
+  local dir="$1"
+  while [ "$dir" != "/" ]; do
+    if [ -d "$dir/.specweave" ]; then
+      echo "$dir"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  pwd
+}
+
+PROJECT_ROOT="$(find_project_root "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")"
+cd "$PROJECT_ROOT" 2>/dev/null || true
+
+# ============================================================================
+# CONFIGURATION
+# ============================================================================
+
+LOGS_DIR=".specweave/logs"
+DEBUG_LOG="$LOGS_DIR/hooks-debug.log"
+
+mkdir -p "$LOGS_DIR" 2>/dev/null || true
+
+echo "[$(date)] 🔒 Pre-task-completion hook fired" >> "$DEBUG_LOG" 2>/dev/null || true
+
+# ============================================================================
+# CAPTURE INPUT
+# ============================================================================
+
+STDIN_DATA=$(mktemp)
+cat > "$STDIN_DATA"
+
+echo "[$(date)] Input JSON:" >> "$DEBUG_LOG" 2>/dev/null || true
+cat "$STDIN_DATA" >> "$DEBUG_LOG" 2>/dev/null || true
+
+# ============================================================================
+# CHECK FOR TASK COMPLETION
+# ============================================================================
+
+# Only validate if a task is being marked complete
+COMPLETING_TASK=false
+
+if command -v jq >/dev/null 2>&1; then
+  # Check if any task is transitioning to "completed" status
+  COMPLETED_COUNT=$(jq -r '.tool_input.todos // [] | map(select(.status == "completed")) | length' "$STDIN_DATA" 2>/dev/null || echo "0")
+
+  if [ "$COMPLETED_COUNT" != "0" ]; then
+    COMPLETING_TASK=true
+    echo "[$(date)] ✓ Detected task completion (${COMPLETED_COUNT} tasks)" >> "$DEBUG_LOG" 2>/dev/null || true
+  fi
+fi
+
+# If no tasks being completed, allow without validation
+if [ "$COMPLETING_TASK" = "false" ]; then
+  echo "[$(date)] ⏭️  No tasks being completed, skipping validation" >> "$DEBUG_LOG" 2>/dev/null || true
+  rm -f "$STDIN_DATA"
+  cat <<EOF
+{
+  "continue": true
+}
+EOF
+  exit 0
+fi
+
+# ============================================================================
+# DETECT CURRENT INCREMENT
+# ============================================================================
+
+CURRENT_INCREMENT=$(ls -td .specweave/increments/*/ 2>/dev/null | xargs -n1 basename | grep -v "_backlog" | grep -v "_archive" | grep -v "_working" | head -1)
+
+if [ -z "$CURRENT_INCREMENT" ]; then
+  echo "[$(date)] ℹ️  No active increment found, skipping validation" >> "$DEBUG_LOG" 2>/dev/null || true
+  rm -f "$STDIN_DATA"
+  cat <<EOF
+{
+  "continue": true
+}
+EOF
+  exit 0
+fi
+
+TASKS_MD=".specweave/increments/$CURRENT_INCREMENT/tasks.md"
+
+if [ ! -f "$TASKS_MD" ]; then
+  echo "[$(date)] ℹ️  tasks.md not found for $CURRENT_INCREMENT (increment may be in planning stage)" >> "$DEBUG_LOG" 2>/dev/null || true
+  rm -f "$STDIN_DATA"
+  cat <<EOF
+{
+  "continue": true
+}
+EOF
+  exit 0
+fi
+
+# ============================================================================
+# RUN AC TEST VALIDATION
+# ============================================================================
+
+echo "[$(date)] 🧪 Running AC test validation for $CURRENT_INCREMENT" >> "$DEBUG_LOG" 2>/dev/null || true
+
+# Determine which validation script to use
+VALIDATOR_SCRIPT=""
+if [ -f "$PROJECT_ROOT/dist/src/core/ac-test-validator-cli.js" ]; then
+  VALIDATOR_SCRIPT="$PROJECT_ROOT/dist/src/core/ac-test-validator-cli.js"
+elif [ -f "$PROJECT_ROOT/node_modules/specweave/dist/src/core/ac-test-validator-cli.js" ]; then
+  VALIDATOR_SCRIPT="$PROJECT_ROOT/node_modules/specweave/dist/src/core/ac-test-validator-cli.js"
+elif [ -n "${CLAUDE_PLUGIN_ROOT}" ] && [ -f "${CLAUDE_PLUGIN_ROOT}/dist/src/core/ac-test-validator-cli.js" ]; then
+  VALIDATOR_SCRIPT="${CLAUDE_PLUGIN_ROOT}/dist/src/core/ac-test-validator-cli.js"
+fi
+
+if [ -z "$VALIDATOR_SCRIPT" ] || ! command -v node &> /dev/null; then
+  echo "[$(date)] ⚠️  AC test validator not found or Node.js missing" >> "$DEBUG_LOG" 2>/dev/null || true
+  rm -f "$STDIN_DATA"
+  cat <<EOF
+{
+  "continue": true,
+  "systemMessage": "⚠️  Warning: AC test validator not available. Task completion validation skipped. Install Node.js and rebuild SpecWeave to enable validation."
+}
+EOF
+  exit 0
+fi
+
+# Run validator (captures exit code)
+VALIDATION_OUTPUT=$(mktemp)
+VALIDATION_EXIT_CODE=0
+
+(cd "$PROJECT_ROOT" && node "$VALIDATOR_SCRIPT" "$CURRENT_INCREMENT") > "$VALIDATION_OUTPUT" 2>&1 || VALIDATION_EXIT_CODE=$?
+
+echo "[$(date)] Validator exit code: $VALIDATION_EXIT_CODE" >> "$DEBUG_LOG" 2>/dev/null || true
+cat "$VALIDATION_OUTPUT" >> "$DEBUG_LOG" 2>/dev/null || true
+
+rm -f "$STDIN_DATA"
+
+# ============================================================================
+# DECISION LOGIC
+# ============================================================================
+
+if [ "$VALIDATION_EXIT_CODE" = "0" ]; then
+  # Validation passed - allow completion
+  echo "[$(date)] ✅ AC test validation passed" >> "$DEBUG_LOG" 2>/dev/null || true
+
+  VALIDATION_SUMMARY=$(cat "$VALIDATION_OUTPUT" | tail -5 | tr '\n' ' ')
+
+  rm -f "$VALIDATION_OUTPUT"
+
+  cat <<EOF
+{
+  "continue": true,
+  "systemMessage": "✅ AC Test Validation Passed: All acceptance criteria have passing tests. Task completion allowed. ${VALIDATION_SUMMARY}"
+}
+EOF
+else
+  # Validation failed - block completion
+  echo "[$(date)] ❌ AC test validation failed" >> "$DEBUG_LOG" 2>/dev/null || true
+
+  VALIDATION_ERROR=$(cat "$VALIDATION_OUTPUT" | grep -A 10 "VALIDATION FAILED" | tr '\n' ' ' | cut -c 1-300)
+
+  rm -f "$VALIDATION_OUTPUT"
+
+  cat <<EOF
+{
+  "continue": false,
+  "systemMessage": "❌ AC TEST VALIDATION FAILED: Cannot mark task as complete until all acceptance criteria have passing tests. ${VALIDATION_ERROR}
+
+Fix the failing tests and try again. Run tests manually: npm test"
+}
+EOF
+fi

package/plugins/specweave/hooks/pre-tool-use.sh

@@ -128,18 +128,9 @@ rm -f "$STDIN_DATA"
 # ============================================================================
 
 if [ "$TOOL_NAME" = "AskUserQuestion" ]; then
-  cat <<EOF
-{
-  "continue": true,
-  "systemMessage": "🔔 Sound played - user notified of question request"
-}
-EOF
+  echo '{"continue":true,"systemMessage":"🔔 Sound played - user notified of question request"}'
 else
-  cat <<EOF
-{
-  "continue": true
-}
-EOF
+  echo '{"continue":true}'
 fi
 
 # ALWAYS exit 0 - NEVER let hook errors crash Claude Code

package/plugins/specweave/hooks/pre-tool-use.sh.backup

@@ -0,0 +1,133 @@
+#!/bin/bash
+
+# SpecWeave Pre-Tool-Use Hook
+# Runs BEFORE Claude calls any tool (PreToolUse event)
+#
+# PURPOSE: Detect when Claude asks questions via AskUserQuestion
+# - Plays sound IMMEDIATELY when question is about to be asked
+# - Complements post-task-completion hook (which only fires after TodoWrite)
+# - Ensures user is always notified when Claude needs input
+#
+# SCOPE:
+# - This hook fires for ALL tool calls (Read, Edit, Write, AskUserQuestion, etc.)
+# - We filter for AskUserQuestion specifically to play sound
+# - Non-blocking and fast (<10ms overhead)
+
+set -e
+
+# ============================================================================
+# CONFIGURATION
+# ============================================================================
+
+# Find project root
+find_project_root() {
+  local dir="$1"
+  while [ "$dir" != "/" ]; do
+    if [ -d "$dir/.specweave" ]; then
+      echo "$dir"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  # Fallback
+  if [ -d "$(pwd)/.specweave" ]; then
+    pwd
+  else
+    echo "$(pwd)"
+  fi
+}
+
+PROJECT_ROOT="$(find_project_root "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")"
+cd "$PROJECT_ROOT" 2>/dev/null || true
+
+LOGS_DIR=".specweave/logs"
+DEBUG_LOG="$LOGS_DIR/hooks-debug.log"
+
+mkdir -p "$LOGS_DIR" 2>/dev/null || true
+
+# ============================================================================
+# CAPTURE INPUT (Tool Call Details)
+# ============================================================================
+
+STDIN_DATA=$(mktemp)
+cat > "$STDIN_DATA"
+
+# Log the tool call for debugging
+echo "[$(date)] 🔧 PreToolUse hook fired" >> "$DEBUG_LOG" 2>/dev/null || true
+echo "[$(date)] Tool call JSON:" >> "$DEBUG_LOG" 2>/dev/null || true
+cat "$STDIN_DATA" >> "$DEBUG_LOG" 2>/dev/null || true
+echo "" >> "$DEBUG_LOG" 2>/dev/null || true
+
+# ============================================================================
+# DETECT AskUserQuestion TOOL
+# ============================================================================
+
+TOOL_NAME=""
+
+if command -v jq >/dev/null 2>&1; then
+  # Use jq if available (most reliable)
+  TOOL_NAME=$(jq -r '.tool_name // empty' "$STDIN_DATA" 2>/dev/null)
+else
+  # Fallback: grep-based detection
+  if grep -q '"tool_name"' "$STDIN_DATA" 2>/dev/null; then
+    TOOL_NAME=$(grep -o '"tool_name":"[^"]*"' "$STDIN_DATA" | cut -d'"' -f4)
+  fi
+fi
+
+echo "[$(date)] Tool name: $TOOL_NAME" >> "$DEBUG_LOG" 2>/dev/null || true
+
+# ============================================================================
+# PLAY SOUND IF AskUserQuestion
+# ============================================================================
+
+play_sound() {
+  case "$(uname -s)" in
+    Darwin)
+      # macOS: Use afplay with a distinctive sound for questions
+      afplay /System/Library/Sounds/Tink.aiff 2>/dev/null || true
+      ;;
+    Linux)
+      # Linux: Use paplay or aplay
+      paplay /usr/share/sounds/freedesktop/stereo/dialog-question.oga 2>/dev/null || \
+      paplay /usr/share/sounds/freedesktop/stereo/message-new-instant.oga 2>/dev/null || \
+      aplay /usr/share/sounds/alsa/Front_Center.wav 2>/dev/null || true
+      ;;
+    MINGW*|MSYS*|CYGWIN*)
+      # Windows: Use PowerShell
+      powershell -c "(New-Object Media.SoundPlayer 'C:\Windows\Media\Windows Notify.wav').PlaySync();" 2>/dev/null || true
+      ;;
+  esac
+}
+
+if [ "$TOOL_NAME" = "AskUserQuestion" ]; then
+  echo "[$(date)] 🔔 QUESTION DETECTED! Playing notification sound" >> "$DEBUG_LOG" 2>/dev/null || true
+  play_sound
+
+  # Log this event
+  echo "[$(date)] Claude is asking for user input via AskUserQuestion" >> "$DEBUG_LOG" 2>/dev/null || true
+fi
+
+# ============================================================================
+# CLEANUP
+# ============================================================================
+
+rm -f "$STDIN_DATA"
+
+# ============================================================================
+# OUTPUT TO CLAUDE (Always continue)
+# ============================================================================
+
+if [ "$TOOL_NAME" = "AskUserQuestion" ]; then
+  cat <<EOF
+{
+  "continue": true,
+  "systemMessage": "🔔 Sound played - user notified of question request"
+}
+EOF
+else
+  cat <<EOF
+{
+  "continue": true
+}
+EOF
+fi

package/plugins/specweave/hooks/universal/dispatcher.mjs

@@ -12,6 +12,7 @@
  *   - session-start
  *   - post-tool-use
  *   - completion-guard
+ *   - bash-file-guard
  *
  * @module hooks/universal/dispatcher
  */
@@ -27,18 +28,82 @@ const __dirname = dirname(__filename);
 // Hook type from arguments
 const hookType = process.argv[2] || 'unknown';
 
+// Global timeout for hook execution (30 seconds max)
+const HOOK_TIMEOUT_MS = 30000;
+
+/**
+ * Detect if we're in a development environment with duplicate hooks
+ *
+ * Problem: When working IN the specweave project AND having the marketplace
+ * plugin installed, Claude Code loads hooks from BOTH sources, causing:
+ * - Duplicate hook execution
+ * - Potential race conditions
+ * - Confusing output
+ *
+ * Solution: If we detect we're running from the marketplace copy while
+ * the CWD is the specweave project itself, skip execution (let local hooks handle it).
+ *
+ * @returns {boolean} true if we should skip this hook execution
+ */
+function shouldSkipDueToDevEnvironment() {
+  const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT || '';
+  const cwd = process.cwd();
+
+  // Check if running from marketplace (installed plugin)
+  const isFromMarketplace = pluginRoot.includes('.claude/plugins/marketplaces/');
+
+  // Check if CWD is the specweave project itself
+  const isInSpecweaveProject = existsSync(join(cwd, 'plugins', 'specweave', 'hooks', 'hooks.json'));
+
+  // Skip marketplace hooks when developing specweave locally
+  if (isFromMarketplace && isInSpecweaveProject) {
+    // Output diagnostic only for session-start (once per session)
+    if (hookType === 'session-start') {
+      console.log(JSON.stringify({
+        continue: true,
+        systemMessage: 'SpecWeave dev environment: Using local hooks (marketplace hooks skipped)'
+      }));
+    } else {
+      console.log(JSON.stringify({ continue: true }));
+    }
+    return true;
+  }
+
+  return false;
+}
+
 /**
- * Find the dist/hooks directory
+ * Wrap a promise with a timeout
+ * @param promise - Promise to wrap
+ * @param timeoutMs - Timeout in milliseconds
+ * @param cleanup - Optional cleanup function (e.g., to kill child process)
+ */
+function withTimeout(promise, timeoutMs, cleanup) {
+  let timeoutId;
+  const timeoutPromise = new Promise((_, reject) => {
+    timeoutId = setTimeout(() => {
+      if (cleanup) cleanup();
+      reject(new Error(`Hook timeout after ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+
+  return Promise.race([promise, timeoutPromise]).finally(() => {
+    clearTimeout(timeoutId);
+  });
+}
+
+/**
+ * Find the dist/src/hooks directory (TypeScript compiled hooks)
  */
 function findHooksDir() {
   // Try multiple locations
   const candidates = [
-    // Production: node_modules/specweave/dist/hooks
-    join(__dirname, '..', '..', '..', '..', 'node_modules', 'specweave', 'dist', 'hooks'),
-    // Development: project root dist/hooks
+    // Production: node_modules/specweave/dist/src/hooks
+    join(__dirname, '..', '..', '..', '..', 'node_modules', 'specweave', 'dist', 'src', 'hooks'),
+    // Development: project root dist/src/hooks
+    join(__dirname, '..', '..', '..', '..', 'dist', 'src', 'hooks'),
+    // Fallback: older path without src/ (backward compatibility)
     join(__dirname, '..', '..', '..', '..', 'dist', 'hooks'),
-    // Relative to this file
-    join(__dirname, '..', '..', '..', '..', 'src', 'hooks'),
   ];
 
   for (const candidate of candidates) {
@@ -52,7 +117,7 @@ function findHooksDir() {
 }
 
 /**
- * Run a hook script
+ * Run a hook script with timeout protection
  */
 async function runHook(scriptName) {
   const hooksDir = findHooksDir();
@@ -74,13 +139,26 @@ async function runHook(scriptName) {
     windowsHide: true,
   });
 
-  return new Promise((resolve) => {
+  const execPromise = new Promise((resolve) => {
     child.on('exit', (code) => resolve(code || 0));
     child.on('error', () => {
       console.log(JSON.stringify({ continue: true }));
       resolve(1);
     });
   });
+
+  try {
+    return await withTimeout(execPromise, HOOK_TIMEOUT_MS, () => {
+      // Kill the child process on timeout
+      try {
+        child.kill('SIGTERM');
+        setTimeout(() => child.kill('SIGKILL'), 1000);
+      } catch { /* ignore */ }
+    });
+  } catch (err) {
+    console.log(JSON.stringify({ continue: true, error: err.message }));
+    return 1;
+  }
 }
 
 /**
@@ -124,7 +202,39 @@ function findGitBash() {
 }
 
 /**
- * Fallback to bash script if TypeScript not built
+ * Helper to spawn a bash script with timeout protection
+ */
+async function spawnBashWithTimeout(bashExe, args, options = {}) {
+  const child = spawn(bashExe, args, {
+    stdio: ['inherit', 'inherit', 'inherit'],
+    windowsHide: true,
+    ...options,
+  });
+
+  const execPromise = new Promise((resolve) => {
+    child.on('exit', (code) => resolve(code || 0));
+    child.on('error', () => {
+      console.log(JSON.stringify({ continue: true }));
+      resolve(1);
+    });
+  });
+
+  try {
+    return await withTimeout(execPromise, HOOK_TIMEOUT_MS, () => {
+      // Kill the child process on timeout
+      try {
+        child.kill('SIGTERM');
+        setTimeout(() => child.kill('SIGKILL'), 1000);
+      } catch { /* ignore */ }
+    });
+  } catch (err) {
+    console.log(JSON.stringify({ continue: true, error: err.message }));
+    return 1;
+  }
+}
+
+/**
+ * Fallback to bash script if TypeScript not built (with timeout protection)
  *
  * @param bashScript - Name of the bash script (e.g., 'post-tool-use.sh')
  * @param subdir - Subdirectory under v2 (e.g., 'dispatchers', 'guards')
@@ -143,17 +253,7 @@ async function fallbackToBash(bashScript, subdir = 'dispatchers') {
     // Strategy 1: Git Bash (preferred - most common)
     const bashExe = findGitBash();
     if (bashExe) {
-      const child = spawn(bashExe, [scriptPath], {
-        stdio: ['inherit', 'inherit', 'inherit'],
-        windowsHide: true,
-      });
-      return new Promise((resolve) => {
-        child.on('exit', (code) => resolve(code || 0));
-        child.on('error', () => {
-          console.log(JSON.stringify({ continue: true }));
-          resolve(1);
-        });
-      });
+      return spawnBashWithTimeout(bashExe, [scriptPath]);
     }
 
     // Strategy 2: WSL (if Git Bash not available) - FALLBACK only
@@ -166,17 +266,7 @@ async function fallbackToBash(bashScript, subdir = 'dispatchers') {
       const wslScriptPath = scriptPath
         .replace(/\\/g, '/')
         .replace(/^([A-Za-z]):/, (_, d) => `/mnt/${d.toLowerCase()}`);
-      const child = spawn('wsl', ['bash', wslScriptPath], {
-        stdio: ['inherit', 'inherit', 'inherit'],
-        windowsHide: true,
-      });
-      return new Promise((resolve) => {
-        child.on('exit', (code) => resolve(code || 0));
-        child.on('error', () => {
-          console.log(JSON.stringify({ continue: true }));
-          resolve(1);
-        });
-      });
+      return spawnBashWithTimeout('wsl', ['bash', wslScriptPath]);
     }
 
     // Strategy 3: No bash available - output warning and continue
@@ -188,21 +278,18 @@ async function fallbackToBash(bashScript, subdir = 'dispatchers') {
     return;
   }
 
-  // POSIX (macOS, Linux) - run directly
-  const child = spawn('bash', [scriptPath], {
-    stdio: ['inherit', 'inherit', 'inherit'],
-  });
-  return new Promise((resolve) => {
-    child.on('exit', (code) => resolve(code || 0));
-    child.on('error', () => {
-      console.log(JSON.stringify({ continue: true }));
-      resolve(1);
-    });
-  });
+  // POSIX (macOS, Linux) - run directly with timeout
+  return spawnBashWithTimeout('bash', [scriptPath]);
 }
 
 // Main routing
 async function main() {
+  // CRITICAL: Skip if we're in dev environment with duplicate hooks
+  // This prevents marketplace hooks from running when local hooks are available
+  if (shouldSkipDueToDevEnvironment()) {
+    return;
+  }
+
   const isWindows = process.platform === 'win32';
 
   try {
@@ -235,6 +322,12 @@ async function main() {
         await fallbackToBash('completion-guard.sh', 'guards');
         break;
 
+      case 'bash-file-guard':
+        // CRITICAL: Prevents infinite hangs from heredoc/echo file creation
+        // See CLAUDE.md Rule 9 for why this is essential
+        await fallbackToBash('bash-file-guard.sh', 'guards');
+        break;
+
       default:
         console.log(JSON.stringify({ continue: true, error: `Unknown hook type: ${hookType}` }));
     }