agentvibes 3.5.10-alpha.0 → 4.0.0

package/.agentvibes/bmad/bmad-voices.md

@@ -0,0 +1,69 @@
+---
+plugin: bmad-voices
+version: 2.0.0
+enabled: true
+description: Provider-aware voice mappings for BMAD agents
+---
+
+# BMAD Voice Plugin
+
+This plugin automatically assigns voices to BMAD agents based on their role and active TTS provider.
+
+## Agent Voice Mappings (Provider-Aware)
+
+| Agent ID | Agent Name | Intro | Piper TTS Voice | Piper Voice | Personality |
+|----------|------------|-------|------------------|-------------|-------------|
+| pm | John (Product Manager) | John, Product Manager here | Matthew Schmitz | en_US-john-medium | professional |
+| dev | Amelia (Developer) | Amelia, Developer here | Aria | en_US-amy-medium | normal |
+| analyst | Mary (Business Analyst) | Mary, Business Analyst here | Jessica Anne Bogart | en_US-kristin-medium | normal |
+| architect | Winston (Architect) | Winston, Architect here | Michael | en_GB-alan-medium | normal |
+| sm | Bob (Scrum Master) | Bob, Scrum Master here | Matthew Schmitz | en_US-joe-medium | professional |
+| tea | Murat (Test Architect) | Murat, Test Architect here | Michael | en_US-kusal-medium | normal |
+| tech-writer | Paige (Technical Writer) | Paige, Technical Writer here | Aria | en_US-lessac-medium | normal |
+| ux-designer | Sally (UX Designer) | Sally, UX Designer here | Jessica Anne Bogart | en_US-lessac-high | normal |
+| frame-expert | Saif (Visual Designer) | Saif, Visual Designer here | Matthew Schmitz | en_GB-alan-medium | normal |
+| bmad-master | BMad Master | BMad Master here | Michael | en_US-libritts-high | zen |
+| quick-flow-solo-dev | Barry (Quick Flow Solo Dev) | Barry, Quick Flow Solo Dev here | Matthew Schmitz | en_US-john-medium | professional |
+
+## How It Works
+
+The voice manager automatically selects the appropriate voice based on your active TTS provider:
+- **Piper TTS active**: Uses voices from the "Piper TTS Voice" column
+- **Piper active**: Uses voices from the "Piper Voice" column
+
+This ensures BMAD agents work seamlessly regardless of which provider you're using.
+
+### Supports Both Display Names and Agent IDs
+
+The `bmad-speak.sh` script accepts both formats:
+
+**Party Mode** (multiple agents, uses display names):
+```bash
+.claude/hooks/bmad-speak.sh "Winston" "I recommend microservices for scalability"
+```
+
+**Individual Agents** (single agent sessions, uses agent IDs):
+```bash
+.claude/hooks/bmad-speak.sh "architect" "I recommend microservices for scalability"
+```
+
+Both formats map to the same voice configuration based on the agent ID in the table above. This allows BMAD to use customizable display names while maintaining stable voice mappings.
+
+## How to Edit
+
+Simply edit the table above to change voice mappings. The format is:
+- **Agent ID**: Must match BMAD's `agent.id` field (pm, dev, qa, etc.)
+- **Agent Name**: Display name (for reference only)
+- **Intro**: Text spoken before agent's message (e.g., "John, Product Manager here"). Leave empty to disable.
+- **Piper TTS Voice**: Voice name for Piper TTS provider
+- **Piper Voice**: Voice model name for Piper provider
+- **Personality**: Optional personality to apply (or "normal" for none)
+
+## Commands
+
+- `/agent-vibes:bmad enable` - Enable BMAD voice plugin
+- `/agent-vibes:bmad disable` - Disable BMAD voice plugin
+- `/agent-vibes:bmad status` - Show plugin status
+- `/agent-vibes:bmad edit` - Open this file for editing
+- `/agent-vibes:bmad list` - List all agent voice mappings
+- `/agent-vibes:bmad set <agent-id> <piper-voice> <piper-voice> [personality]` - Set voices for specific agent

package/.claude/config/audio-effects.cfg

@@ -49,4 +49,4 @@ BMad Master|reverb 50 60 100 pitch -100|agentvibes_soft_flamenco_loop.mp3|0.30
 _party_mode|compand 0.3,1 6:-70,-60,-20|agent_vibes_dark_chill_step_loop.mp3|0.40
 |||
 # Default (no agent specified) - clean with Bachata background|||
-default|reverb 20 50 50|agentvibes_soft_flamenco_loop.mp3|0.30
+default|reverb 40 50 70|agent_vibes_celtic_harp_v1_loop.mp3|0.30

package/.claude/config/background-music-position.txt

@@ -1,27 +1 @@
-agent-vibes-dark-chill-step.mp3:49.006169
-Agent Vibes Japanese City Pop v1.mp3:29.392744
-Agent Vibes ChillWave v2.mp3:22.154467
-Agent Vibes Bossa Nova v2.mp3:23.733424
-Agent Vibes Tabla Dream Pop v1.mp3:19.101043
-Agent Vibes Hawaiian slack key guitar v2.mp3:36.381950
-AgentVibes Soft Flamenco.mp3:23.160000
-Agent Vibes Arabic v2.mp3:21.922268
-Agent Vibes Goa Trance v2.mp3:55.953741
-Agent Vibes Ganawa Ambient v2.mp3:39.680205
-Agent Vibes Celtic Harp v1.mp3:42.190476
-Agent Vibes Harpsichord v2.mp3:21.739410
-Agent Vibes Japanese City Pop v1-loop.mp3:13.917551
-Agent Vibes Hawaiian slack key guitar v2-loop.mp3:12.977143
-Agent Vibes Ganawa Ambient v2-loop.mp3:.00000000000000000002815996
-Agent Vibes Tabla Dream Pop v1-loop.mp3:.00000000000000000009067943
-Agent Vibes ChillWave v2-loop.mp3:.00000000000000000007080511
-Agent Vibes Harpsichord v2-loop.mp3:.00000000000000000013140818
-agent_vibes_japanese_city_pop_v1_loop.mp3:6.054512
-agent_vibes_bossa_nova_v2_loop.mp3:5.369524
-agent_vibes_salsa_v2_loop.mp3:9.972790
-agent_vibes_cumbia_v1_loop.mp3:5.717823
-agent_vibes_arabic_v2_loop.mp3:.00000000000000000006132724
-agent_vibes_chillwave_v2_loop.mp3:14.628390
-agent_vibes_bachata_v1_loop.mp3:.00000000000000000005344000
-agentvibes_soft_flamenco_loop.mp3:.00000000000000000006934441
-agent_vibes_goa_trance_v2_loop.mp3:.00000000000000000002499918
+agent_vibes_celtic_harp_v1_loop.mp3:12.341678

package/.claude/github-star-reminder.txt

@@ -1 +1 @@
-20260214
+20260309

package/.claude/hooks/audio-processor.sh

@@ -39,18 +39,19 @@ OUTPUT_FILE="${3:-}"
 CONFIG_FILE="$(cd "$SCRIPT_DIR/.." && pwd)/config/audio-effects.cfg"
 BACKGROUNDS_DIR="$(cd "$SCRIPT_DIR/../audio" && pwd)/tracks"
 ENABLED_FILE="$(cd "$SCRIPT_DIR/.." && pwd)/config/background-music-enabled.txt"
+GLOBAL_ENABLED_FILE="$HOME/.claude/config/background-music-enabled.txt"
 
-# Check if background music is globally enabled
+# Check if background music is enabled (project-local, then global fallback)
 is_background_music_enabled() {
-    # Default to false if file doesn't exist
-    if [[ ! -f "$ENABLED_FILE" ]]; then
+    local enabled=""
+    if [[ -f "$ENABLED_FILE" ]]; then
+        enabled=$(cat "$ENABLED_FILE" 2>/dev/null | tr -d '[:space:]')
+    elif [[ -f "$GLOBAL_ENABLED_FILE" ]]; then
+        enabled=$(cat "$GLOBAL_ENABLED_FILE" 2>/dev/null | tr -d '[:space:]')
+    else
         return 1  # Disabled by default
     fi
 
-    # Read the enabled flag
-    local enabled
-    enabled=$(cat "$ENABLED_FILE" 2>/dev/null | tr -d '[:space:]')
-
     # Return 0 (true) if enabled, 1 (false) otherwise
     [[ "$enabled" == "true" ]]
 }
@@ -87,9 +88,9 @@ get_agent_config() {
         return
     fi
 
-    # Try exact match first
+    # Try exact match first (use awk for safe literal matching)
     local config
-    config=$(grep -i "^${agent}|" "$CONFIG_FILE" 2>/dev/null | head -1)
+    config=$(awk -F'|' -v agent="$agent" 'tolower($1) == tolower(agent)' "$CONFIG_FILE" 2>/dev/null | head -1)
 
     # Fall back to default
     if [[ -z "$config" ]]; then
@@ -119,6 +120,16 @@ apply_sox_effects() {
         return 0
     fi
 
+    # Validate effects contain only allowed sox effect names and numeric params
+    local allowed_effects="gain|reverb|echo|chorus|flanger|phaser|tremolo|overdrive|bass|treble|equalizer|highpass|lowpass|bandpass|vol|speed|tempo|pitch|rate|pad|silence|trim|fade|norm|loudness|compand|contrast|delay|repeat|stat|remix"
+    for word in $effects; do
+      if ! [[ "$word" =~ ^-?[0-9]*\.?[0-9]+$ ]] && ! echo "$word" | grep -qiE "^($allowed_effects)$"; then
+        echo "Warning: Invalid sox effect '$word', skipping effects" >&2
+        cp "$input" "$output"
+        return 0
+      fi
+    done
+
     # Apply effects - note: effects string is intentionally unquoted to allow word splitting
     # shellcheck disable=SC2086
     sox "$input" "$output" $effects 2>/dev/null || {
@@ -140,7 +151,7 @@ get_background_position() {
     bg_name=$(basename "$bg_file")
 
     if [[ -f "$POSITION_FILE" ]]; then
-        grep "^${bg_name}:" "$POSITION_FILE" 2>/dev/null | cut -d: -f2 | tr -d '[:space:]' || echo "0"
+        awk -F: -v name="$bg_name" '$1 == name {print $2}' "$POSITION_FILE" 2>/dev/null | tr -d '[:space:]' | tail -1
     else
         echo "0"
     fi
@@ -158,12 +169,14 @@ save_background_position() {
 
     mkdir -p "$(dirname "$POSITION_FILE")"
 
-    # Remove old entry and add new one
+    # Remove old entry and add new one (atomic update via temp file + mv)
+    local tmp_pos
+    tmp_pos=$(mktemp "${POSITION_FILE}.XXXXXX")
     if [[ -f "$POSITION_FILE" ]]; then
-        grep -v "^${bg_name}:" "$POSITION_FILE" > "${POSITION_FILE}.tmp" 2>/dev/null || true
-        mv "${POSITION_FILE}.tmp" "$POSITION_FILE"
+        grep -v "^${bg_name}:" "$POSITION_FILE" > "$tmp_pos" 2>/dev/null || true
     fi
-    echo "${bg_name}:${position}" >> "$POSITION_FILE"
+    echo "${bg_name}:${position}" >> "$tmp_pos"
+    mv "$tmp_pos" "$POSITION_FILE"
 }
 
 # @function mix_background
@@ -336,9 +349,11 @@ main() {
     temp_effects=$(mktemp "$TEMP_DIR/effects-XXXXXX.wav")
     temp_final=$(mktemp "$TEMP_DIR/final-XXXXXX.wav")
 
-    # Clean up on exit - use double quotes to capture paths at definition time
-    # (local variables won't exist at trap execution time outside function scope)
-    trap "rm -f '$temp_effects' '$temp_final'" EXIT
+    # Clean up on exit - use a cleanup function to avoid trap injection
+    _cleanup_effects="$temp_effects"
+    _cleanup_final="$temp_final"
+    cleanup() { rm -f "$_cleanup_effects" "$_cleanup_final"; }
+    trap cleanup EXIT
 
     # Step 1: Apply sox effects
     if [[ -n "$sox_effects" ]]; then

package/.claude/hooks/bmad-speak-enhanced.sh

@@ -39,7 +39,7 @@ if [[ -f "$PROJECT_ROOT/.agentvibes/bmad/bmad-party-mode-disabled.flag" ]]; then
 fi
 
 # Check if BMAD is installed
-if [[ ! -f "$PROJECT_ROOT/.bmad/_cfg/agent-manifest.csv" ]]; then
+if [[ ! -f "$PROJECT_ROOT/_bmad/_config/agent-manifest.csv" ]]; then
     exit 0
 fi
 
@@ -48,13 +48,13 @@ map_to_agent_id() {
     local name_or_id="$1"
 
     # If it looks like a file path, extract the agent ID
-    if [[ "$name_or_id" =~ \.bmad/.*/agents/([^/]+)\.md$ ]]; then
+    if [[ "$name_or_id" =~ _?\.?bmad/.*/agents/([^/]+)\.md$ ]]; then
         echo "${BASH_REMATCH[1]}"
         return
     fi
 
     # Check if it's already an agent ID
-    local direct_match=$(grep -i "^\"*${name_or_id}\"*," "$PROJECT_ROOT/.bmad/_cfg/agent-manifest.csv" | head -1)
+    local direct_match=$(grep -i "^\"*${name_or_id}\"*," "$PROJECT_ROOT/_bmad/_config/agent-manifest.csv" | head -1)
     if [[ -n "$direct_match" ]]; then
         echo "$name_or_id"
         return
@@ -73,7 +73,7 @@ map_to_agent_id() {
                 exit
             }
         }
-    ' "$PROJECT_ROOT/.bmad/_cfg/agent-manifest.csv")
+    ' "$PROJECT_ROOT/_bmad/_config/agent-manifest.csv")
 
     echo "$agent_id"
 }
@@ -94,7 +94,7 @@ get_display_name() {
                 exit
             }
         }
-    ' "$PROJECT_ROOT/.bmad/_cfg/agent-manifest.csv")
+    ' "$PROJECT_ROOT/_bmad/_config/agent-manifest.csv")
 
     echo "$display_name"
 }

package/.claude/hooks/bmad-speak.sh

@@ -34,7 +34,7 @@ if [[ -f "$PROJECT_ROOT/.agentvibes/bmad/bmad-party-mode-disabled.flag" ]]; then
 fi
 
 # Check if BMAD is installed
-if [[ ! -f "$PROJECT_ROOT/.bmad/_cfg/agent-manifest.csv" ]]; then
+if [[ ! -f "$PROJECT_ROOT/_bmad/_config/agent-manifest.csv" ]]; then
   exit 0
 fi
 
@@ -44,14 +44,14 @@ map_to_agent_id() {
 
   # If it looks like a file path (.bmad/*/agents/*.md), extract the agent ID
   # Example: .bmad/bmm/agents/pm.md -> pm
-  if [[ "$name_or_id" =~ \.bmad/.*/agents/([^/]+)\.md$ ]]; then
+  if [[ "$name_or_id" =~ _?\.?bmad/.*/agents/([^/]+)\.md$ ]]; then
     echo "${BASH_REMATCH[1]}"
     return
   fi
 
   # First check if it's already an agent ID (column 1 of manifest)
   # CSV format: name,displayName,title,icon,role,...
-  local direct_match=$(grep -i "^\"*${name_or_id}\"*," "$PROJECT_ROOT/.bmad/_cfg/agent-manifest.csv" | head -1)
+  local direct_match=$(grep -i "^\"*${name_or_id}\"*," "$PROJECT_ROOT/_bmad/_config/agent-manifest.csv" | head -1)
   if [[ -n "$direct_match" ]]; then
     # Already an agent ID, pass through
     echo "$name_or_id"
@@ -78,7 +78,7 @@ map_to_agent_id() {
         exit
       }
     }
-  ' "$PROJECT_ROOT/.bmad/_cfg/agent-manifest.csv")
+  ' "$PROJECT_ROOT/_bmad/_config/agent-manifest.csv")
 
   echo "$agent_id"
 }

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

@@ -281,10 +281,10 @@ sync_intros_from_manifest() {
         bmad_voice_map="bmad/_cfg/agent-voice-map.csv"
     fi
 
-    if [[ -f ".bmad/_cfg/agent-manifest.csv" ]]; then
-        manifest_file=".bmad/_cfg/agent-manifest.csv"
-    elif [[ -f "bmad/_cfg/agent-manifest.csv" ]]; then
-        manifest_file="bmad/_cfg/agent-manifest.csv"
+    if [[ -f "_bmad/_config/agent-manifest.csv" ]]; then
+        manifest_file="_bmad/_config/agent-manifest.csv"
+    elif [[ -f "_bmad/_config/agent-manifest.csv" ]]; then
+        manifest_file="_bmad/_config/agent-manifest.csv"
     fi
 
     # Both files must exist for sync to work
@@ -404,10 +404,10 @@ get_agent_intro() {
         if [[ -z "$intro" ]] || [[ "$intro" == "Hello! Ready to help with the discussion." ]]; then
             # Try to get display name from agent-manifest.csv
             local manifest_file=""
-            if [[ -f ".bmad/_cfg/agent-manifest.csv" ]]; then
-                manifest_file=".bmad/_cfg/agent-manifest.csv"
-            elif [[ -f "bmad/_cfg/agent-manifest.csv" ]]; then
-                manifest_file="bmad/_cfg/agent-manifest.csv"
+            if [[ -f "_bmad/_config/agent-manifest.csv" ]]; then
+                manifest_file="_bmad/_config/agent-manifest.csv"
+            elif [[ -f "_bmad/_config/agent-manifest.csv" ]]; then
+                manifest_file="_bmad/_config/agent-manifest.csv"
             fi
 
             if [[ -n "$manifest_file" ]]; then

package/.claude/hooks/clawdbot-receiver-SECURE.sh

@@ -26,20 +26,19 @@ VOICE="${2:-en_US-lessac-medium}"
 ENCODED_AGENT="${3:-}"
 ENCODED_INTRO="${4:-}"
 
-# SECURITY: Whitelist of allowed voice names
-ALLOWED_VOICES="en_US-amy-medium|en_US-lessac-medium|es_ES-mls_9972-low|es_ES-davefx-medium|en_US-joe-medium"
-
 # Validate inputs
 if [[ -z "$ENCODED_TEXT" ]]; then
-  echo "❌ No encoded text provided" >&2
+  echo "Error: No encoded text provided" >&2
   echo "Usage: $0 <base64_text> <voice> <base64_agent_name> [base64_intro]" >&2
   exit 1
 fi
 
-# SECURITY: Validate VOICE parameter against whitelist
-if ! [[ "$VOICE" =~ ^($ALLOWED_VOICES)$ ]]; then
-  echo "❌ Invalid voice name: $VOICE" >&2
-  echo "Allowed voices: $(echo "$ALLOWED_VOICES" | tr '|' ', ')" >&2
+# SECURITY: Validate base64 format (reject shell metacharacters)
+[[ "$ENCODED_TEXT" =~ ^[A-Za-z0-9+/=]+$ ]] || { echo "Error: invalid base64 text" >&2; exit 1; }
+
+# SECURITY: Validate VOICE parameter format (alphanumeric, hyphens, underscores only)
+if [[ ! "$VOICE" =~ ^[a-zA-Z0-9_-]+$ ]]; then
+  echo "Error: Invalid voice name format: $VOICE" >&2
   exit 1
 fi
 
@@ -58,31 +57,30 @@ fi
 
 DECODED_AGENT="default"
 if [[ -n "$ENCODED_AGENT" ]]; then
-  DECODED_AGENT=$(echo -n "$ENCODED_AGENT" | base64 -d 2>/dev/null) || DECODED_AGENT="default"
-  
-  # SECURITY: Validate agent name format (alphanumeric, dash, underscore only)
-  if ! [[ "$DECODED_AGENT" =~ ^[a-zA-Z0-9_-]+$ ]]; then
-    echo "⚠️  Invalid agent name format, using 'default'" >&2
-    DECODED_AGENT="default"
+  # SECURITY: Validate base64 format before decoding
+  [[ "$ENCODED_AGENT" =~ ^[A-Za-z0-9+/=]+$ ]] || ENCODED_AGENT=""
+  if [[ -n "$ENCODED_AGENT" ]]; then
+    DECODED_AGENT=$(echo -n "$ENCODED_AGENT" | base64 -d 2>/dev/null) || DECODED_AGENT="default"
   fi
-  
+
+  # SECURITY: Validate agent name format (alphanumeric, dash, underscore only)
+  [[ "$DECODED_AGENT" =~ ^[a-zA-Z0-9_-]+$ ]] || DECODED_AGENT="default"
+
   # SECURITY: Enforce length limit on agent name
-  if [[ ${#DECODED_AGENT} -gt 50 ]]; then
-    echo "⚠️  Agent name too long, using 'default'" >&2
-    DECODED_AGENT="default"
-  fi
+  [[ ${#DECODED_AGENT} -le 50 ]] || DECODED_AGENT="default"
 fi
 
 # Decode and prepend intro if provided
 DECODED_INTRO=""
 if [[ -n "$ENCODED_INTRO" ]]; then
-  DECODED_INTRO=$(echo -n "$ENCODED_INTRO" | base64 -d 2>/dev/null) || DECODED_INTRO=""
-  
-  # SECURITY: Enforce length limit on intro message
-  if [[ ${#DECODED_INTRO} -gt 200 ]]; then
-    echo "⚠️  Intro message too long, truncating" >&2
-    DECODED_INTRO="${DECODED_INTRO:0:200}"
+  # SECURITY: Validate base64 format before decoding
+  [[ "$ENCODED_INTRO" =~ ^[A-Za-z0-9+/=]+$ ]] || ENCODED_INTRO=""
+  if [[ -n "$ENCODED_INTRO" ]]; then
+    DECODED_INTRO=$(echo -n "$ENCODED_INTRO" | base64 -d 2>/dev/null) || DECODED_INTRO=""
   fi
+
+  # SECURITY: Enforce length limit on intro message
+  [[ ${#DECODED_INTRO} -le 200 ]] || DECODED_INTRO="${DECODED_INTRO:0:200}"
 fi
 
 # Prepend intro to text if configured

package/.claude/hooks/clawdbot-receiver.sh

@@ -30,26 +30,50 @@ ENCODED_INTRO="${4:-}"
 
 # Validate inputs
 if [[ -z "$ENCODED_TEXT" ]]; then
-  echo "❌ No encoded text provided" >&2
+  echo "Error: No encoded text provided" >&2
   echo "Usage: $0 <base64_text> <voice> <base64_agent_name> [base64_intro]" >&2
   exit 1
 fi
 
+# SECURITY: Validate base64 format (reject shell metacharacters)
+[[ "$ENCODED_TEXT" =~ ^[A-Za-z0-9+/=]+$ ]] || { echo "Error: invalid base64 text" >&2; exit 1; }
+
+# SECURITY: Validate voice name format (alphanumeric, hyphens, underscores only)
+[[ "$VOICE" =~ ^[a-zA-Z0-9_-]+$ ]] || { echo "Error: invalid voice format" >&2; exit 1; }
+
 # SECURITY: Decode base64 safely
 DECODED_TEXT=$(echo -n "$ENCODED_TEXT" | base64 -d 2>/dev/null) || {
-  echo "❌ Failed to decode text (invalid base64)" >&2
+  echo "Error: Failed to decode text (invalid base64)" >&2
   exit 1
 }
 
+# SECURITY: Enforce length limit on decoded text (10KB max)
+if [[ ${#DECODED_TEXT} -gt 10000 ]]; then
+  echo "Error: Decoded text too long (${#DECODED_TEXT} chars, max 10000)" >&2
+  exit 1
+fi
+
 DECODED_AGENT="default"
 if [[ -n "$ENCODED_AGENT" ]]; then
-  DECODED_AGENT=$(echo -n "$ENCODED_AGENT" | base64 -d 2>/dev/null) || DECODED_AGENT="default"
+  [[ "$ENCODED_AGENT" =~ ^[A-Za-z0-9+/=]+$ ]] || ENCODED_AGENT=""
+  if [[ -n "$ENCODED_AGENT" ]]; then
+    DECODED_AGENT=$(echo -n "$ENCODED_AGENT" | base64 -d 2>/dev/null) || DECODED_AGENT="default"
+  fi
+  # Validate agent name format (alphanumeric, dash, underscore only)
+  [[ "$DECODED_AGENT" =~ ^[a-zA-Z0-9_-]+$ ]] || DECODED_AGENT="default"
+  # Enforce length limit
+  [[ ${#DECODED_AGENT} -le 50 ]] || DECODED_AGENT="default"
 fi
 
 # Decode and prepend intro if provided
 DECODED_INTRO=""
 if [[ -n "$ENCODED_INTRO" ]]; then
-  DECODED_INTRO=$(echo -n "$ENCODED_INTRO" | base64 -d 2>/dev/null) || DECODED_INTRO=""
+  [[ "$ENCODED_INTRO" =~ ^[A-Za-z0-9+/=]+$ ]] || ENCODED_INTRO=""
+  if [[ -n "$ENCODED_INTRO" ]]; then
+    DECODED_INTRO=$(echo -n "$ENCODED_INTRO" | base64 -d 2>/dev/null) || DECODED_INTRO=""
+  fi
+  # Enforce length limit on intro (200 chars max)
+  [[ ${#DECODED_INTRO} -le 200 ]] || DECODED_INTRO="${DECODED_INTRO:0:200}"
 fi
 
 # Prepend intro to text if configured

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

@@ -42,7 +42,7 @@
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
-if [[ -n "$CLAUDE_PROJECT_DIR" ]] && [[ -d "$CLAUDE_PROJECT_DIR/.claude" ]]; then
+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/hooks/path-resolver.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+#
+# File: .claude/hooks/path-resolver.sh
+#
+# AgentVibes Path Resolver Utility - Robust path resolution for all hooks
+# Handles: symlinks, working directory changes, non-standard installations
+#
+# Usage in other scripts:
+#   source "$(dirname "${BASH_SOURCE[0]}")/path-resolver.sh"
+#   # Now use: $PROJECT_ROOT, $HOOKS_DIR, $SCRIPT_DIR
+#
+
+set -euo pipefail
+
+# Resolve the actual script location (handles symlinks)
+# This function must be called from the sourcing script
+_resolve_agentvibes_paths() {
+  local calling_script="$1"
+
+  # Get real path (resolve symlinks)
+  local script_path
+  if command -v readlink &>/dev/null; then
+    script_path="$(readlink -f "$calling_script")"
+  else
+    # Fallback for systems without readlink -f
+    script_path="$(cd "$(dirname "$calling_script")" && pwd)/$(basename "$calling_script")"
+  fi
+
+  local script_dir="$(dirname "$script_path")"
+
+  # Find PROJECT_ROOT by searching up for .claude/hooks directory
+  # This is resilient to non-standard installations
+  local current_dir="$script_dir"
+  local project_root=""
+
+  while [[ "$current_dir" != "/" ]]; do
+    if [[ -d "$current_dir/.claude/hooks" ]]; then
+      # Found .claude/hooks - PROJECT_ROOT is 2 levels up
+      project_root="$(dirname "$(dirname "$current_dir")")"
+      break
+    fi
+    current_dir="$(dirname "$current_dir")"
+  done
+
+  # Validate we found a valid project root
+  if [[ -z "$project_root" ]] || [[ ! -d "$project_root/.claude/hooks" ]]; then
+    echo "❌ ERROR: Could not locate AgentVibes installation" >&2
+    echo "   Script: $script_path" >&2
+    return 1
+  fi
+
+  # Export paths for use in sourcing script
+  export SCRIPT_PATH="$script_path"
+  export SCRIPT_DIR="$script_dir"
+  export HOOKS_DIR="$project_root/.claude/hooks"
+  export PROJECT_ROOT="$project_root"
+}
+
+# Call the resolver with the calling script
+_resolve_agentvibes_paths "${BASH_SOURCE[1]}"

package/.claude/hooks/play-tts-agentvibes-receiver-for-voiceless-connections.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+#
+# File: .claude/hooks/play-tts-agentvibes-receiver-for-voiceless-connections.sh
+#
+# AgentVibes - AgentVibes Receiver Provider (for voiceless connections)
+# Sends text to a remote device via SSH for local AgentVibes playback.
+# Use this when the AI agent runs on a server/headless machine that has no
+# audio output — the remote device (laptop, phone, etc.) plays the audio.
+#
+# Copyright (c) 2025 Paul Preibisch
+# Licensed under the Apache License, Version 2.0
+#
+
+set -euo pipefail
+
+TEXT="${1:-}"
+VOICE="${2:-en_US-lessac-medium}"
+AGENT_NAME="${3:-default}"
+
+# Validate required input
+if [[ -z "$TEXT" ]]; then
+  echo "❌ No text provided" >&2
+  echo "Usage: $0 <text> [voice] [agent_name]" >&2
+  exit 1
+fi
+
+# Get script directory
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+# Get SSH host from config
+SSH_HOST=$(cat "$PROJECT_ROOT/.claude/agentvibes-receiver-host.txt" 2>/dev/null || \
+           cat "$HOME/.claude/agentvibes-receiver-host.txt" 2>/dev/null || echo "")
+
+if [[ -z "$SSH_HOST" ]]; then
+  echo "❌ AgentVibes Receiver host not configured" >&2
+  echo "💡 Set host: echo 'your-device' > ~/.claude/agentvibes-receiver-host.txt" >&2
+  exit 1
+fi
+
+# SECURITY: Validate SSH_HOST to prevent option injection
+# Must be a valid hostname, IP address, or SSH config alias (alphanumeric, dots, hyphens, underscores)
+if [[ ! "$SSH_HOST" =~ ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ ]]; then
+  echo "❌ Invalid SSH host format: $SSH_HOST" >&2
+  echo "💡 Host must be alphanumeric (may contain dots, hyphens, underscores)" >&2
+  exit 1
+fi
+
+# SECURITY: Reject hosts starting with hyphen (SSH option injection)
+if [[ "$SSH_HOST" == -* ]]; then
+  echo "❌ Invalid SSH host: cannot start with hyphen" >&2
+  exit 1
+fi
+
+# SECURITY: Validate VOICE to prevent injection (alphanumeric, hyphens, underscores only)
+if [[ ! "$VOICE" =~ ^[a-zA-Z0-9_-]+$ ]]; then
+  echo "❌ Invalid voice format: $VOICE" >&2
+  exit 1
+fi
+
+# SECURITY: Validate AGENT_NAME to prevent injection (alphanumeric, hyphens, underscores, spaces only)
+if [[ ! "$AGENT_NAME" =~ ^[a-zA-Z0-9_\ -]+$ ]]; then
+  echo "❌ Invalid agent name format: $AGENT_NAME" >&2
+  exit 1
+fi
+
+# SECURITY: Encode text and agent name as base64 to prevent command injection
+# The receiver will decode these safely
+ENCODED_TEXT=$(printf '%s' "$TEXT" | base64 -w 0)
+ENCODED_AGENT=$(printf '%s' "$AGENT_NAME" | base64 -w 0)
+
+# Send text to remote for local AgentVibes playback
+echo "📱 Sending to $SSH_HOST for local playback..." >&2
+
+# Try receiver scripts in order — single SSH call, no separate probe
+# SECURITY: Base64-encoded values are safe to pass as arguments (no shell metacharacters)
+ssh "$SSH_HOST" "
+  if [ -f ~/.agentvibes/play-remote.sh ]; then
+    bash ~/.agentvibes/play-remote.sh '$ENCODED_TEXT' '$VOICE' '$ENCODED_AGENT'
+  elif [ -f ~/.termux/agentvibes-play.sh ]; then
+    bash ~/.termux/agentvibes-play.sh '$ENCODED_TEXT' '$VOICE' '$ENCODED_AGENT'
+  else
+    echo 'Error: Receiver script not found' >&2
+    exit 1
+  fi
+" &
+SSH_PID=$!
+
+echo "Sent to $SSH_HOST (PID: $SSH_PID)" >&2
+exit 0