agentvibes 4.0.0 → 4.2.0

package/.claude/hooks/play-tts.sh

@@ -78,7 +78,8 @@ elif [[ -f "$GLOBAL_MUTE_FILE" ]]; then
 fi
 
 TEXT="${1:-}"
-VOICE_OVERRIDE="${2:-}"  # Optional: voice name or ID
+VOICE_OVERRIDE="${2:-}"      # Optional: voice name or ID
+AGENT_PROFILE_FILE="${3:-}"  # Optional: path to per-agent profile JSON (from bmad-speak.sh)
 
 # Security: Validate inputs
 if [[ -z "$TEXT" ]]; then
@@ -92,14 +93,13 @@ if [[ -n "$VOICE_OVERRIDE" ]] && [[ "$VOICE_OVERRIDE" =~ [';|&$`<>(){}'] ]]; the
   exit 1
 fi
 
-# Remove backslash escaping that Claude might add for special chars
-# In single quotes these don't need escaping, but Claude sometimes adds backslashes
+# Remove backslash escaping that Claude might add for SAFE special chars only
+# SECURITY: Only unescape punctuation chars that cannot form shell commands (#127)
+# Never unescape $, `, \, or other shell metacharacters
 TEXT="${TEXT//\\!/!}"        # Remove \!
-TEXT="${TEXT//\\\$/\$}"      # Remove \$
 TEXT="${TEXT//\\?/?}"        # Remove \?
 TEXT="${TEXT//\\,/,}"        # Remove \,
 TEXT="${TEXT//\\./.}"        # Remove \. (keep the period)
-TEXT="${TEXT//\\\\/\\}"      # Remove \\ (escaped backslash)
 
 # Prepend intro text (pretext) if configured
 # Check project-local first, then global
@@ -154,10 +154,11 @@ speak_text() {
   local text="$1"
   local voice="${2:-}"
   local provider="${3:-$ACTIVE_PROVIDER}"
+  local profile_file="${4:-$AGENT_PROFILE_FILE}"
 
   case "$provider" in
     piper)
-      "$SCRIPT_DIR/play-tts-piper.sh" "$text" "$voice"
+      "$SCRIPT_DIR/play-tts-piper.sh" "$text" "$voice" "$profile_file"
       ;;
     soprano)
       "$SCRIPT_DIR/play-tts-soprano.sh" "$text" "$voice"
@@ -206,7 +207,8 @@ handle_learning_mode() {
 
   # 2. Auto-translate to target language
   local translated
-  translated=$(python3 "$SCRIPT_DIR/translator.py" "$TEXT" "$target_lang" 2>/dev/null) || translated="$TEXT"
+  # SECURITY: Add timeout to prevent hanging (#134)
+  translated=$(timeout 5 python3 "$SCRIPT_DIR/translator.py" "$TEXT" "$target_lang" 2>/dev/null) || translated="$TEXT"
 
   # Small pause between languages
   sleep 0.5
@@ -241,7 +243,8 @@ handle_translation_mode() {
 
   # Translate text
   local translated
-  translated=$(python3 "$SCRIPT_DIR/translator.py" "$TEXT" "$translate_to" 2>/dev/null) || translated="$TEXT"
+  # SECURITY: Add timeout to prevent hanging (#134)
+  translated=$(timeout 5 python3 "$SCRIPT_DIR/translator.py" "$TEXT" "$translate_to" 2>/dev/null) || translated="$TEXT"
 
   # Get voice for target language if no override specified
   local voice_to_use="$VOICE_OVERRIDE"
@@ -279,7 +282,7 @@ fi
 # Normal single-language mode - route to appropriate provider implementation
 case "$ACTIVE_PROVIDER" in
   piper)
-    exec "$SCRIPT_DIR/play-tts-piper.sh" "$TEXT" "$VOICE_OVERRIDE"
+    exec "$SCRIPT_DIR/play-tts-piper.sh" "$TEXT" "$VOICE_OVERRIDE" "$AGENT_PROFILE_FILE"
     ;;
   soprano)
     exec "$SCRIPT_DIR/play-tts-soprano.sh" "$TEXT" "$VOICE_OVERRIDE"

package/.claude/hooks/session-start-tts.sh

@@ -64,6 +64,16 @@ CONTEXT+="4. Keep under 150 chars\n"
 CONTEXT+="5. Always include errors\n\n"
 CONTEXT+="Quick Ref: low=action+result | medium=+key decisions | high=+full reasoning"
 
+# Add BMAD agent voice routing instructions
+CONTEXT+="\n\n## BMAD Agent Voice Routing\n"
+CONTEXT+="If \`.bmad-agent-context\` exists, check its content:\n\n"
+CONTEXT+="**Single agent mode** (content is an agent ID like \"analyst\"):\n"
+CONTEXT+="Use \`bmad-speak.sh\` instead of \`play-tts.sh\`:\n\n\n"
+CONTEXT+="**Party mode** (content is \"party-mode\"):\n"
+CONTEXT+="Each agent speaks via \`bmad-speak.sh\` with their display name. The queue system ensures sequential playback — agents speak one at a time, not overlapping:\n\n"
+CONTEXT+="IMPORTANT: In party mode, do NOT use \`play-tts.sh\`. Always use \`bmad-speak.sh\` with the agent's display name. Do NOT call multiple bmad-speak.sh in parallel — call them sequentially so the queue processes them in order.\n\n"
+CONTEXT+="If \`.bmad-agent-context\` does NOT exist, use \`play-tts.sh\` as normal."
+
 # Escape for JSON (handle newlines, quotes, backslashes)
 ESCAPED=$(printf '%s' "$CONTEXT" | sed 's/\\/\\\\/g; s/"/\\"/g; s/\t/\\t/g')
 

package/.claude/hooks/stop-tts.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+set -eo pipefail
+#
+# File: .claude/hooks/stop-tts.sh
+#
+# AgentVibes Stop Hook — Auto-speak Claude's response via TTS
+# Reads last_assistant_message from stdin JSON and speaks it.
+#
+
+# Fix locale warnings
+export LC_ALL=C
+
+# Get script directory
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Check if AgentVibes play-tts.sh exists
+if [[ ! -f "$SCRIPT_DIR/play-tts.sh" ]]; then
+  exit 0
+fi
+
+# Check if muted
+if [[ -f "${CLAUDE_PROJECT_DIR:-.}/.claude/tts-muted.txt" ]] || [[ -f "$HOME/.claude/tts-muted.txt" ]]; then
+  MUTED=$(cat "${CLAUDE_PROJECT_DIR:-.}/.claude/tts-muted.txt" 2>/dev/null || cat "$HOME/.claude/tts-muted.txt" 2>/dev/null || echo "")
+  if [[ "$MUTED" == "true" ]]; then
+    exit 0
+  fi
+fi
+
+# Read JSON from stdin
+INPUT=$(cat)
+
+# Extract last_assistant_message using node (available in Claude Code env)
+MESSAGE=$(echo "$INPUT" | node -e "
+  let d = '';
+  process.stdin.on('data', c => d += c);
+  process.stdin.on('end', () => {
+    try {
+      const j = JSON.parse(d);
+      const msg = j.last_assistant_message || '';
+      // Strip markdown before TTS — prevent "asterisk asterisk" being spoken literally
+      const stripped = msg
+        .replace(/\*\*/g, '').replace(/\*/g, '')
+        .replace(/`[^`]*`/g, '').replace(/`/g, '')
+        .replace(/#+\s*/g, '')
+        .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1');  // [text](url) → text
+      // Truncate to 150 chars for TTS
+      const trimmed = stripped.replace(/\n/g, ' ').replace(/\s+/g, ' ').trim();
+      process.stdout.write(trimmed.length > 150 ? trimmed.slice(0, 147) + '...' : trimmed);
+    } catch(e) {
+      process.exit(0);
+    }
+  });
+" 2>/dev/null) || exit 0
+
+# Skip if empty or too short
+if [[ -z "$MESSAGE" ]] || [[ ${#MESSAGE} -lt 2 ]]; then
+  exit 0
+fi
+
+# Check if a BMAD agent is active — route through bmad-speak.sh for per-agent voice
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+BMAD_CONTEXT="$PROJECT_DIR/.bmad-agent-context"
+BMAD_SPEAK="$PROJECT_DIR/.claude/hooks/bmad-speak.sh"
+
+if [[ -f "$BMAD_CONTEXT" ]] && [[ -f "$BMAD_SPEAK" ]]; then
+  AGENT_ID=$(head -1 "$BMAD_CONTEXT" 2>/dev/null | tr -d '[:space:]')
+
+  # Party mode: context file contains "party-mode" — skip stop hook TTS entirely.
+  # Party mode handles its own TTS inline via bmad-speak.sh per agent.
+  if [[ "$AGENT_ID" == "party-mode" ]]; then
+    exit 0
+  fi
+
+  if [[ -n "$AGENT_ID" ]] && [[ "$AGENT_ID" =~ ^[a-zA-Z0-9_-]+$ ]]; then
+    # Single agent mode: use bmad-speak for per-agent voice/pretext
+    bash "$BMAD_SPEAK" "$AGENT_ID" "$MESSAGE" &
+    exit 0
+  fi
+fi
+
+# Default: speak with global voice (run in background so we don't block Claude)
+"$SCRIPT_DIR/play-tts.sh" "$MESSAGE" &
+
+exit 0

package/.claude/hooks/tts-queue-worker.sh

@@ -13,7 +13,7 @@ if [[ -n "${XDG_RUNTIME_DIR:-}" ]] && [[ -d "$XDG_RUNTIME_DIR" ]]; then
   QUEUE_DIR="$XDG_RUNTIME_DIR/agentvibes-tts-queue"
 else
   # Fallback to user-specific temp directory
-  QUEUE_DIR="/tmp/agentvibes-tts-queue-$USER"
+  QUEUE_DIR="/tmp/agentvibes-tts-queue-$(id -u)"
 fi
 
 # Security: Validate queue directory exists and has correct ownership
@@ -71,42 +71,73 @@ process_queue() {
         exit 0
       fi
 
-      # Wait 1 second and check again
-      sleep 1
+      # Wait for a new queue item — use inotifywait if available to avoid polling
+      # Use a 1-second timeout (-t 1) so the idle counter still advances correctly
+      if command -v inotifywait &>/dev/null; then
+        inotifywait -q -e create -t 1 "$QUEUE_DIR" 2>/dev/null || true
+      else
+        sleep 1
+      fi
       continue
     fi
 
     # Reset idle counter - we have work
     idle_count=0
 
-    # Load TTS request
-    source "$queue_item"
+    # Load queue item — explicit key=value parsing (SECURITY: never source untrusted files)
+    TEXT_FILE=""
+    VOICE=""
+    AGENT=""
+    PROFILE_PATH=""
+    PLAY_WAV=""
+    while IFS='=' read -r _key _val; do
+      case "$_key" in
+        TEXT_FILE)     TEXT_FILE="$_val" ;;
+        VOICE)         VOICE="$_val" ;;
+        AGENT)         AGENT="$_val" ;;
+        PROFILE_PATH)  PROFILE_PATH="$_val" ;;
+        PLAY_WAV)      PLAY_WAV="$_val" ;;
+      esac
+    done < "$queue_item"
+
+    # Check if this is a pre-generated WAV playback item
+    if [[ -n "${PLAY_WAV:-}" ]] && [[ -f "$PLAY_WAV" ]]; then
+      # Play the pre-generated WAV directly (synthesis already done by bmad-speak)
+      if command -v paplay &>/dev/null; then
+        paplay "$PLAY_WAV" 2>/dev/null || true
+      elif command -v aplay &>/dev/null; then
+        aplay -q "$PLAY_WAV" 2>/dev/null || true
+      elif command -v ffplay &>/dev/null; then
+        ffplay -nodisp -autoexit -loglevel quiet "$PLAY_WAV" 2>/dev/null || true
+      fi
+    else
+      # Full TTS request — read text from companion file, use voice/agent directly
+      TEXT=""
+      if [[ -n "${TEXT_FILE:-}" ]] && [[ -f "$TEXT_FILE" ]]; then
+        TEXT=$(cat "$TEXT_FILE")
+        rm -f "$TEXT_FILE"
+      fi
+      AGENT_PROFILE="${PROFILE_PATH:-}"
 
-    # Decode base64 values
-    TEXT=$(echo -n "$TEXT_B64" | base64 -d)
-    VOICE=$(echo -n "$VOICE_B64" | base64 -d)
-    AGENT=$(echo -n "${AGENT_B64:-}" | base64 -d 2>/dev/null || echo "default")
+      export AGENTVIBES_AGENT_PROFILE="$AGENT_PROFILE"
 
-    # Use enhanced TTS with agent-specific background music if agent is specified
-    # and background music is enabled
-    if [[ -f "$SCRIPT_DIR/play-tts-enhanced.sh" ]] && [[ "$AGENT" != "default" ]] && [[ -n "$AGENT" ]]; then
-      # Party mode: each agent gets their unique background music from audio-effects.cfg
-      bash "$SCRIPT_DIR/play-tts-enhanced.sh" "$TEXT" "$AGENT" "$VOICE" || true
-    else
-      # Standard TTS without background music
-      # Display output to show file location (GitHub Issue #39)
       if [[ -n "${VOICE:-}" ]]; then
-        bash "$SCRIPT_DIR/play-tts.sh" "$TEXT" "$VOICE" || true
+        bash "$SCRIPT_DIR/play-tts.sh" "$TEXT" "${VOICE}" || true
       else
         bash "$SCRIPT_DIR/play-tts.sh" "$TEXT" || true
       fi
+
+      if [[ -n "$AGENT_PROFILE" ]] && [[ -f "$AGENT_PROFILE" ]]; then
+        rm -f "$AGENT_PROFILE"
+      fi
+      unset AGENTVIBES_AGENT_PROFILE
     fi
 
     # Add configurable pause between speakers for natural conversation flow
     sleep $SPEAKER_DELAY
 
-    # Remove processed item
-    rm -f "$queue_item"
+    # Remove processed item and any companion text file
+    rm -f "$queue_item" "${queue_item%.queue}.txt"
   done
 }
 

package/.claude/hooks/tts-queue.sh

@@ -14,7 +14,7 @@ if [[ -n "${XDG_RUNTIME_DIR:-}" ]] && [[ -d "$XDG_RUNTIME_DIR" ]]; then
   QUEUE_DIR="$XDG_RUNTIME_DIR/agentvibes-tts-queue"
 else
   # Fallback to user-specific temp directory
-  QUEUE_DIR="/tmp/agentvibes-tts-queue-$USER"
+  QUEUE_DIR="/tmp/agentvibes-tts-queue-$(id -u)"
 fi
 
 QUEUE_LOCK="$QUEUE_DIR/queue.lock"
@@ -34,20 +34,26 @@ fi
 # @param $1 dialogue text
 # @param $2 voice name (optional)
 # @param $3 agent name (optional, for background music in party mode)
+# @param $4 agent profile path (optional, PID-scoped temp JSON with reverb/personality/music overrides)
 add_to_queue() {
   local text="$1"
   local voice="${2:-}"
   local agent="${3:-default}"
+  local profile_path="${4:-}"
 
   # Create unique queue item with timestamp
   local timestamp=$(date +%s%N)
   local queue_file="$QUEUE_DIR/$timestamp.queue"
 
-  # Write request to queue file (base64 encoded to handle all special chars)
+  # Write request to queue file using direct storage
+  # Text is stored in a separate .txt file (handles newlines and special chars safely)
+  # Voice and agent are simple identifiers with no special chars
+  printf '%s' "$text" > "${queue_file%.queue}.txt"
   cat > "$queue_file" <<EOF
-TEXT_B64=$(echo -n "$text" | base64 -w0)
-VOICE_B64=$(echo -n "$voice" | base64 -w0)
-AGENT_B64=$(echo -n "$agent" | base64 -w0)
+TEXT_FILE=${queue_file%.queue}.txt
+VOICE=$voice
+AGENT=$agent
+PROFILE_PATH=$profile_path
 EOF
 
   # Start queue worker if not already running
@@ -113,10 +119,32 @@ show_queue() {
   fi
 }
 
+# @function play_wav
+# @intent Queue a pre-generated WAV file for sequential playback
+# @param $1 path to WAV file
+play_wav() {
+  local wav_file="$1"
+  [[ -z "$wav_file" ]] && return 1
+  [[ ! -f "$wav_file" ]] && return 1
+
+  local timestamp=$(date +%s%N)
+  local queue_file="$QUEUE_DIR/$timestamp.queue"
+
+  # Write a playback-only queue item (no synthesis needed)
+  cat > "$queue_file" <<EOF
+PLAY_WAV=$wav_file
+EOF
+
+  start_worker_if_needed
+}
+
 # Main command dispatcher
 case "${1:-help}" in
   add)
-    add_to_queue "${2:-}" "${3:-}" "${4:-default}"
+    add_to_queue "${2:-}" "${3:-}" "${4:-default}" "${5:-}"
+    ;;
+  play)
+    play_wav "${2:-}"
     ;;
   clear)
     clear_queue
@@ -125,10 +153,11 @@ case "${1:-help}" in
     show_queue
     ;;
   *)
-    echo "Usage: tts-queue.sh {add|clear|status}"
+    echo "Usage: tts-queue.sh {add|play|clear|status}"
     echo ""
     echo "Commands:"
-    echo "  add <text> [voice] [agent]  Add TTS request to queue with optional agent for background music"
+    echo "  add <text> [voice] [agent]  Add TTS request to queue"
+    echo "  play <wav_file>             Queue a pre-generated WAV for playback"
     echo "  clear                       Clear all pending requests"
     echo "  status                      Show queue status"
     exit 1

package/.claude/hooks/voice-manager.sh

@@ -49,7 +49,11 @@ to_lower() {
 # 2. Script location (for direct slash command usage)
 # 3. Global ~/.claude (fallback)
 
-if [[ -n "$CLAUDE_PROJECT_DIR" ]] && [[ -d "$CLAUDE_PROJECT_DIR/.claude" ]]; then
+# SECURITY: Canonicalize path to prevent traversal (#128)
+if [[ -n "${CLAUDE_PROJECT_DIR:-}" ]]; then
+  CLAUDE_PROJECT_DIR=$(cd "${CLAUDE_PROJECT_DIR}" 2>/dev/null && pwd -P) || CLAUDE_PROJECT_DIR=""
+fi
+if [[ -n "${CLAUDE_PROJECT_DIR:-}" ]] && [[ -d "$CLAUDE_PROJECT_DIR/.claude" ]]; then
   # MCP context: Use the project directory where MCP was invoked
   CLAUDE_DIR="$CLAUDE_PROJECT_DIR/.claude"
 else

package/CLAUDE.md

@@ -4,17 +4,6 @@
 **Updated:** 2026-02-15
 **Status:** Active (Using BMAD Methodology)
 
-## TTS Protocol (MANDATORY)
-
-**ALWAYS call TTS inline (never `run_in_background: true`):**
-```bash
-PULSE_SERVER=unix:/mnt/wslg/PulseServer bash ".claude/hooks/play-tts.sh" "text to speak"
-```
-- Provider: `piper` (WSL bash, NOT Windows PowerShell)
-- Mode: `full` (`.agentvibes/config/mode.txt`) — Claude calls TTS directly, no stop-hook Audio Summary
-- Pretext: configured in `.agentvibes/config/agentvibes.json` (prepended automatically by play-tts.sh)
-- Call at: task acknowledgment + task completion (high verbosity = also reasoning/findings)
-
 ## Overview
 
 AgentVibes is a Text-to-Speech system for AI assistants with personality support.