specweave 0.23.10 → 0.23.14

package/plugins/specweave/hooks/pre-edit-spec.sh

@@ -0,0 +1,151 @@
+#!/bin/bash
+#
+# Pre-Edit Hook: Capture File Path BEFORE Edit Executes (Tier 2)
+#
+# Purpose: Detect which file will be edited BEFORE the Edit tool runs
+# Strategy: PreToolUse has better access to tool arguments than PostToolUse
+#
+# TIER 2 COORDINATION:
+# 1. Extract file_path from TOOL_USE_ARGS (more reliable in PreToolUse)
+# 2. If it's spec.md/tasks.md in increments folder, signal PostToolUse hook
+# 3. Write file path to .pending-status-update for PostToolUse to consume
+#
+# This eliminates the need for mtime-based fallback detection (Tier 1)
+# and reduces false positives to near zero.
+#
+# Architecture:
+#   PreToolUse:Edit → pre-edit-spec.sh (this file)
+#     ↓ writes to
+#   .specweave/state/.pending-status-update
+#     ↓ read by
+#   PostToolUse:Edit → post-edit-spec.sh
+#
+# Version: v0.24.3 (EMERGENCY FIXES)
+# Date: 2025-11-22
+
+# EMERGENCY FIX: Remove set -e - it causes Claude Code crashes!
+set +e
+
+# EMERGENCY KILL SWITCH: Disable all hooks if env variable set
+if [[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]]; then
+  exit 0
+fi
+
+# Find project root
+find_project_root() {
+  local dir="$PWD"
+  while [[ "$dir" != "/" ]]; do
+    if [[ -d "$dir/.specweave" ]]; then
+      echo "$dir"
+      return 0
+    fi
+    dir=$(dirname "$dir")
+  done
+  echo "$PWD"
+}
+
+PROJECT_ROOT=$(find_project_root)
+STATE_DIR="$PROJECT_ROOT/.specweave/state"
+LOGS_DIR="$PROJECT_ROOT/.specweave/logs"
+DEBUG_LOG="$LOGS_DIR/hooks-debug.log"
+PENDING_FILE="$STATE_DIR/.pending-status-update"
+METRICS_FILE="$STATE_DIR/hook-metrics.jsonl"
+
+# Ensure directories exist
+mkdir -p "$STATE_DIR" "$LOGS_DIR" 2>/dev/null || true
+
+# ============================================================================
+# TIER 2: Extract File Path from Tool Arguments
+# ============================================================================
+# PreToolUse should have access to tool arguments BEFORE execution
+# Try multiple methods to extract file_path
+
+FILE_PATH=""
+
+# Method 1: TOOL_USE_ARGS environment variable (primary for PreToolUse)
+if [[ -n "${TOOL_USE_ARGS:-}" ]]; then
+  # Try to parse JSON with jq if available
+  if command -v jq &> /dev/null; then
+    FILE_PATH=$(echo "$TOOL_USE_ARGS" | jq -r '.file_path // empty' 2>/dev/null || echo "")
+  fi
+
+  # Fallback: Regex extraction if jq not available or failed
+  if [[ -z "$FILE_PATH" ]]; then
+    FILE_PATH=$(echo "$TOOL_USE_ARGS" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)".*/\1/' || echo "")
+  fi
+fi
+
+# Method 2: TOOL_USE_CONTENT (fallback)
+if [[ -z "$FILE_PATH" ]] && [[ -n "${TOOL_USE_CONTENT:-}" ]]; then
+  FILE_PATH="$TOOL_USE_CONTENT"
+fi
+
+# Method 3: Parse from stdin (last resort - experimental)
+if [[ -z "$FILE_PATH" ]] && [[ ! -t 0 ]]; then
+  # Read stdin and try to extract file_path
+  STDIN_DATA=$(cat 2>/dev/null || echo "")
+  if [[ -n "$STDIN_DATA" ]] && command -v jq &> /dev/null; then
+    FILE_PATH=$(echo "$STDIN_DATA" | jq -r '.file_path // empty' 2>/dev/null || echo "")
+  fi
+fi
+
+# ============================================================================
+# TIER 2: Signal Detection and Validation
+# ============================================================================
+
+# Log what we detected (for debugging PreToolUse effectiveness)
+if [[ -n "$FILE_PATH" ]]; then
+  echo "[$(date)] pre-edit-spec: Detected file_path: $FILE_PATH" >> "$DEBUG_LOG" 2>/dev/null || true
+else
+  echo "[$(date)] pre-edit-spec: No file_path detected (will fall back to Tier 1)" >> "$DEBUG_LOG" 2>/dev/null || true
+  exit 0  # Let PostToolUse handle it with mtime fallback
+fi
+
+# Check if this is a spec.md or tasks.md file in increments folder
+IS_SPEC_FILE=false
+if [[ "$FILE_PATH" == *"/spec.md" ]] || [[ "$FILE_PATH" == *"/tasks.md" ]]; then
+  if [[ "$FILE_PATH" == *"/.specweave/increments/"* ]]; then
+    # Exclude archived increments
+    if [[ "$FILE_PATH" != *"/_archive/"* ]]; then
+      IS_SPEC_FILE=true
+    fi
+  fi
+fi
+
+# If not a spec/tasks file, exit silently (no signal to PostToolUse)
+if [[ "$IS_SPEC_FILE" != "true" ]]; then
+  echo "[$(date)] pre-edit-spec: Not a spec/tasks file - no signal" >> "$DEBUG_LOG" 2>/dev/null || true
+  exit 0
+fi
+
+# ============================================================================
+# TIER 2: Write Signal for PostToolUse Hook
+# ============================================================================
+
+# Write file path to pending file for PostToolUse to consume
+echo "$FILE_PATH" > "$PENDING_FILE" 2>/dev/null || true
+
+echo "[$(date)] pre-edit-spec: Signaled PostToolUse for: $FILE_PATH" >> "$DEBUG_LOG" 2>/dev/null || true
+
+# ============================================================================
+# TIER 2: Metrics Collection
+# ============================================================================
+
+# Record metrics (JSONL format - one JSON object per line)
+TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+METRIC_ENTRY="{\"timestamp\":\"$TIMESTAMP\",\"hook\":\"pre-edit-spec\",\"event\":\"file_detected\",\"file_path\":\"$FILE_PATH\",\"method\":\"TOOL_USE_ARGS\"}"
+
+# Append to metrics file (JSONL)
+echo "$METRIC_ENTRY" >> "$METRICS_FILE" 2>/dev/null || true
+
+# Log rotation for metrics (keep last 1000 entries)
+if [[ -f "$METRICS_FILE" ]]; then
+  LINE_COUNT=$(wc -l < "$METRICS_FILE" 2>/dev/null || echo 0)
+  if (( LINE_COUNT > 1000 )); then
+    tail -1000 "$METRICS_FILE" > "$METRICS_FILE.tmp" 2>/dev/null || true
+    mv "$METRICS_FILE.tmp" "$METRICS_FILE" 2>/dev/null || true
+  fi
+fi
+
+# ALWAYS exit 0 - NEVER let hook errors crash Claude Code
+exit 0

package/plugins/specweave/hooks/pre-implementation.sh

@@ -4,7 +4,12 @@
 # Runs before starting implementation of a task
 # Checks regression risk for brownfield projects
 
-set -e
+set +e  # EMERGENCY FIX: Prevents Claude Code crashes
+
+# EMERGENCY KILL SWITCH
+if [[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]]; then
+  exit 0
+fi
 
 # Find project root by searching upward for .specweave/ directory
 # Works regardless of where hook is installed (source or .claude/hooks/)
@@ -65,3 +70,6 @@ echo "[$(date)] Pre-implementation check complete" >> "$LOGS_DIR/hooks.log"
 
 echo ""
 echo -e "${GREEN}✅ Pre-implementation check complete${NC}"
+
+# ALWAYS exit 0 - NEVER let hook errors crash Claude Code
+exit 0

package/plugins/specweave/hooks/pre-implementation.sh.backup

@@ -0,0 +1,67 @@
+#!/bin/bash
+
+# SpecWeave Pre-Implementation Hook
+# Runs before starting implementation of a task
+# Checks regression risk for brownfield projects
+
+set -e
+
+# Find project root by searching upward for .specweave/ directory
+# Works regardless of where hook is installed (source or .claude/hooks/)
+find_project_root() {
+  local dir="$1"
+  while [ "$dir" != "/" ]; do
+    if [ -d "$dir/.specweave" ]; then
+      echo "$dir"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  # Fallback: try current directory
+  if [ -d "$(pwd)/.specweave" ]; then
+    pwd
+  else
+    echo "$(pwd)"
+  fi
+}
+
+PROJECT_ROOT="$(find_project_root "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")"
+cd "$PROJECT_ROOT"
+
+# Colors
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+GREEN='\033[0;32m'
+NC='\033[0m'
+
+echo -e "${BLUE}🔍 Pre-Implementation Check${NC}"
+
+# Check if this is a brownfield project (has existing code)
+if [ -d "src" ] || [ -d "app" ] || [ -d "lib" ]; then
+  echo -e "${YELLOW}⚠️  Brownfield project detected${NC}"
+  echo ""
+  echo "Recommendations:"
+  echo "  1. Create baseline tests before changes"
+  echo "  2. Check for existing tests that may break"
+  echo "  3. Review impact on existing features"
+  echo ""
+
+  # Check if baseline tests exist
+  if [ -d ".specweave/tests/baseline" ]; then
+    echo -e "${GREEN}✅ Baseline tests exist${NC}"
+  else
+    echo -e "${YELLOW}⚠️  No baseline tests found${NC}"
+    echo "   Consider creating baseline tests first"
+    echo "   This captures current state before changes"
+  fi
+else
+  echo -e "${GREEN}✅ Greenfield project - no regression risk${NC}"
+fi
+
+# Log to hooks log
+LOGS_DIR=".specweave/logs"
+mkdir -p "$LOGS_DIR"
+echo "[$(date)] Pre-implementation check complete" >> "$LOGS_DIR/hooks.log"
+
+echo ""
+echo -e "${GREEN}✅ Pre-implementation check complete${NC}"

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

@@ -20,7 +20,12 @@
 # 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
+set +e  # EMERGENCY FIX: Prevents Claude Code crashes
+
+# EMERGENCY KILL SWITCH
+if [[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]]; then
+  exit 0
+fi
 
 # Find project root
 find_project_root() {
@@ -92,15 +97,14 @@ fi
 # DETECT CURRENT INCREMENT
 # ============================================================================
 
-CURRENT_INCREMENT=$(ls -t .specweave/increments/ 2>/dev/null | grep -v "_backlog" | grep -v "_archive" | grep -v "_working" | head -1)
+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
+  echo "[$(date)] ℹ️  No active increment found, skipping validation" >> "$DEBUG_LOG" 2>/dev/null || true
   rm -f "$STDIN_DATA"
   cat <<EOF
 {
-  "continue": true,
-  "systemMessage": "⚠️  Warning: No active increment found. Task completion validation skipped."
+  "continue": true
 }
 EOF
   exit 0
@@ -109,12 +113,11 @@ fi
 TASKS_MD=".specweave/increments/$CURRENT_INCREMENT/tasks.md"
 
 if [ ! -f "$TASKS_MD" ]; then
-  echo "[$(date)] ⚠️  tasks.md not found for $CURRENT_INCREMENT" >> "$DEBUG_LOG" 2>/dev/null || true
+  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,
-  "systemMessage": "⚠️  Warning: tasks.md not found. Task completion validation skipped."
+  "continue": true
 }
 EOF
   exit 0
@@ -194,3 +197,6 @@ Fix the failing tests and try again. Run tests manually: npm test"
 }
 EOF
 fi
+
+# ALWAYS exit 0 - NEVER let hook errors crash Claude Code
+exit 0

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

@@ -13,7 +13,12 @@
 # - We filter for AskUserQuestion specifically to play sound
 # - Non-blocking and fast (<10ms overhead)
 
-set -e
+set +e  # EMERGENCY FIX: Prevents Claude Code crashes
+
+# EMERGENCY KILL SWITCH
+if [[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]]; then
+  exit 0
+fi
 
 # ============================================================================
 # CONFIGURATION
@@ -131,3 +136,6 @@ else
 }
 EOF
 fi
+
+# ALWAYS exit 0 - NEVER let hook errors crash Claude Code
+exit 0

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