agentvibes 5.2.1 → 5.4.0

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

@@ -2,11 +2,8 @@
 #
 # File: .claude/hooks/play-tts-ssh-remote.sh
 #
-# AgentVibes - SSH-Remote TTS Provider (v2 — JSON payload)
-# Sends text + effects config to remote device via SSH for local playback
-#
-# The sender reads local audio-effects.cfg and bundles everything into a
-# single base64-encoded JSON payload. The receiver is a thin executor.
+# AgentVibes - SSH-Remote TTS Provider
+# Sends text to remote device via SSH for local AgentVibes playback
 #
 # Copyright (c) 2025 Paul Preibisch
 # Licensed under the Apache License, Version 2.0
@@ -20,149 +17,74 @@ 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 and project root
+# Get script directory
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 
-# Derive project name from directory
-PROJECT_NAME=$(basename "$PROJECT_ROOT")
-
-# ---------------------------------------------------------------------------
 # Get SSH host from config
-# ---------------------------------------------------------------------------
-
 SSH_HOST=$(cat "$PROJECT_ROOT/.claude/ssh-remote-host.txt" 2>/dev/null || \
            cat "$HOME/.claude/ssh-remote-host.txt" 2>/dev/null || echo "")
 
 if [[ -z "$SSH_HOST" ]]; then
-  echo "SSH-Remote host not configured" >&2
-  echo "Set host: echo 'my-host' > .claude/ssh-remote-host.txt" >&2
+  echo "❌ SSH-Remote host not configured" >&2
+  echo "💡 Set host: echo 'android' > ~/.claude/ssh-remote-host.txt" >&2
   exit 1
 fi
 
-# SECURITY: Validate SSH_HOST format
+# 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 "❌ Invalid SSH host format: $SSH_HOST" >&2
+  echo "💡 Host must be alphanumeric (may contain dots, hyphens, underscores)" >&2
   exit 1
 fi
 
-# SECURITY: Validate VOICE (allow :: for multi-speaker, . for locale, space for names)
-_voice_re='^[a-zA-Z0-9_.:  -]+$'
-if [[ ! "$VOICE" =~ $_voice_re ]]; then
-  echo "Invalid voice format: $VOICE" >&2
+# 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 AGENT_NAME
-if [[ ! "$AGENT_NAME" =~ ^[a-zA-Z0-9_\ -]+$ ]]; then
-  echo "Invalid agent name format: $AGENT_NAME" >&2
+# 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
 
-# ---------------------------------------------------------------------------
-# Read audio effects config for this agent
-# ---------------------------------------------------------------------------
-
-SOX_EFFECTS=""
-BG_FILE=""
-BG_VOLUME="0.10"
-
-EFFECTS_CFG="$PROJECT_ROOT/.claude/config/audio-effects.cfg"
-if [[ -f "$EFFECTS_CFG" ]]; then
-  CONFIG_LINE=$(grep "^${AGENT_NAME}|" "$EFFECTS_CFG" 2>/dev/null || \
-                grep "^default|" "$EFFECTS_CFG" 2>/dev/null || true)
-  if [[ -n "$CONFIG_LINE" ]]; then
-    IFS='|' read -r _ SOX_EFFECTS BG_FILE BG_VOLUME <<< "$CONFIG_LINE"
-  fi
-fi
-
-# Read pretext if configured
-PRETEXT=""
-PRETEXT_FILE="$PROJECT_ROOT/.agentvibes/config/pretext.txt"
-if [[ -f "$PRETEXT_FILE" ]]; then
-  PRETEXT=$(cat "$PRETEXT_FILE" 2>/dev/null || true)
-fi
-
-# Read speed if configured
-SPEED=""
-SPEED_FILE="$PROJECT_ROOT/.agentvibes/config/speed.txt"
-if [[ -f "$SPEED_FILE" ]]; then
-  SPEED=$(cat "$SPEED_FILE" 2>/dev/null || true)
-fi
-
-# Read the TTS provider the RECEIVER should use to generate audio.
-# This is separate from the sender's own provider (which is "ssh-remote").
-# Check receiver-provider.txt first, then fall back to "piper".
-PROVIDER=""
-RECEIVER_PROVIDER_FILE="$PROJECT_ROOT/.agentvibes/config/receiver-provider.txt"
-if [[ -f "$RECEIVER_PROVIDER_FILE" ]]; then
-  PROVIDER=$(cat "$RECEIVER_PROVIDER_FILE" 2>/dev/null || true)
-fi
-# Also check home-level config
-if [[ -z "$PROVIDER" ]]; then
-  RECEIVER_PROVIDER_FILE="$HOME/.agentvibes/config/receiver-provider.txt"
-  if [[ -f "$RECEIVER_PROVIDER_FILE" ]]; then
-    PROVIDER=$(cat "$RECEIVER_PROVIDER_FILE" 2>/dev/null || true)
-  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
-# Validate — only known TTS providers (not transport providers like ssh-remote)
-case "${PROVIDER:-}" in
-  piper|soprano|macos|windows-sapi) ;;
-  *) PROVIDER="piper" ;;
-esac
-
-# ---------------------------------------------------------------------------
-# Build JSON payload
-# ---------------------------------------------------------------------------
-
-# SECURITY: Use jq if available for safe JSON construction, else manual escaping
-build_json_payload() {
-  if command -v jq &>/dev/null; then
-    jq -n \
-      --arg text "$TEXT" \
-      --arg voice "$VOICE" \
-      --arg effects "$SOX_EFFECTS" \
-      --arg music "$BG_FILE" \
-      --arg volume "$BG_VOLUME" \
-      --arg project "$PROJECT_NAME" \
-      --arg pretext "$PRETEXT" \
-      --arg speed "$SPEED" \
-      --arg provider "$PROVIDER" \
-      '{text: $text, voice: $voice, effects: $effects, music: $music, volume: $volume, project: $project, pretext: $pretext, speed: $speed, provider: $provider}'
-  else
-    # Manual JSON — escape double quotes and backslashes in text
-    local escaped_text
-    escaped_text=$(printf '%s' "$TEXT" | sed 's/\\/\\\\/g; s/"/\\"/g; s/\t/\\t/g')
-    local escaped_pretext
-    escaped_pretext=$(printf '%s' "$PRETEXT" | sed 's/\\/\\\\/g; s/"/\\"/g')
-    printf '{"text":"%s","voice":"%s","effects":"%s","music":"%s","volume":"%s","project":"%s","pretext":"%s","speed":"%s","provider":"%s"}' \
-      "$escaped_text" "$VOICE" "$SOX_EFFECTS" "$BG_FILE" "$BG_VOLUME" "$PROJECT_NAME" "$escaped_pretext" "$SPEED" "$PROVIDER"
-  fi
-}
 
-JSON_PAYLOAD=$(build_json_payload)
-
-# SECURITY: Base64-encode entire payload — safe for SSH transport
-# base64 -w 0 is Linux (GNU coreutils), -b 0 is macOS (BSD)
-if base64 --help 2>&1 | grep -q '\-w'; then
-  ENCODED_PAYLOAD=$(printf '%s' "$JSON_PAYLOAD" | base64 -w 0)
+# 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
+
+# Determine which receiver script exists and send encoded text, voice, and agent name
+# SECURITY: Base64-encoded values are safe to pass as arguments (no shell metacharacters)
+# The receiver auto-detects and decodes base64 input
+if ssh "$SSH_HOST" "test -f ~/.termux/agentvibes-play.sh" 2>/dev/null; then
+  ssh "$SSH_HOST" "bash ~/.termux/agentvibes-play.sh '$ENCODED_TEXT' '$VOICE' '$ENCODED_AGENT'" &
+  SSH_PID=$!
+elif ssh "$SSH_HOST" "test -f ~/.agentvibes/play-remote.sh" 2>/dev/null; then
+  ssh "$SSH_HOST" "bash ~/.agentvibes/play-remote.sh '$ENCODED_TEXT' '$VOICE' '$ENCODED_AGENT'" &
+  SSH_PID=$!
 else
-  ENCODED_PAYLOAD=$(printf '%s' "$JSON_PAYLOAD" | base64 -b 0 2>/dev/null || printf '%s' "$JSON_PAYLOAD" | base64 | tr -d '\n')
+  echo "⚠️  Receiver script not found on $SSH_HOST" >&2
+  echo "💡 Install: agentvibes install --ssh-receiver" >&2
+  exit 1
 fi
 
-# ---------------------------------------------------------------------------
-# Send to receiver via SSH (fire and forget — backgrounded)
-# ---------------------------------------------------------------------------
-
-echo "Sending to $SSH_HOST..." >&2
-
-# ForceCommand receiver: SSH_ORIGINAL_COMMAND passes the payload directly
-ssh "$SSH_HOST" "$ENCODED_PAYLOAD" &
-SSH_PID=$!
-
-echo "Sent to $SSH_HOST (PID: $SSH_PID)" >&2
+# Log the background PID for debugging (non-blocking)
+echo "✓ Sent to $SSH_HOST (PID: $SSH_PID, playing remotely)" >&2
 exit 0

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

@@ -39,15 +39,41 @@
 # @patterns Provider pattern - delegates to provider-specific implementations, auto-detects provider from voice name
 # @related provider-manager.sh, play-tts-piper.sh, learn-manager.sh, translate-manager.sh
 #
+# **CRITICAL: This script MUST ALWAYS be called with `run_in_background: true` in Bash tool**
+# Do NOT wait for TTS playback to complete. Run in background so other tasks continue immediately.
+# Example: Bash (background): .claude/hooks/play-tts.sh "Acknowledging task start"
+#
+
+set -euo pipefail
 
 set -euo pipefail
 
 # Fix locale warnings
 export LC_ALL=C
 
-# Get script directory (needed for mute file check)
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+# Get script directory - handle symlinks correctly with readlink -f
+# This resolves: symlinks, relative paths, and working directory changes
+SCRIPT_PATH="$(readlink -f "${BASH_SOURCE[0]}")"
+SCRIPT_DIR="$(dirname "$SCRIPT_PATH")"
+
+# Find PROJECT_ROOT by searching up the directory tree for .claude/hooks
+# This handles non-standard installations and directory structures
+PROJECT_ROOT="$SCRIPT_DIR"
+while [[ "$PROJECT_ROOT" != "/" ]]; do
+  if [[ -d "$PROJECT_ROOT/.claude/hooks" ]]; then
+    break  # PROJECT_ROOT is already the project root when its .claude/hooks child exists
+  fi
+  PROJECT_ROOT="$(dirname "$PROJECT_ROOT")"
+done
+
+# Verify PROJECT_ROOT is valid
+if [[ ! -d "$PROJECT_ROOT/.claude/hooks" ]]; then
+  echo "❌ ERROR: Could not find AgentVibes .claude/hooks directory" >&2
+  echo "   Script path: $SCRIPT_PATH" >&2
+  echo "   Searched up from: $SCRIPT_DIR" >&2
+  exit 1
+fi
+
 export PROJECT_ROOT  # Export for child scripts
 
 # Check if muted (persists across sessions)
@@ -77,34 +103,8 @@ elif [[ -f "$GLOBAL_MUTE_FILE" ]]; then
   exit 0
 fi
 
-# Parse arguments: positional + optional --llm <provider>
-TEXT=""
-VOICE_OVERRIDE=""
-AGENT_PROFILE_FILE=""
-LLM_PROVIDER=""
-
-_positional=()
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --llm)
-      LLM_PROVIDER="${2:-}"
-      # Security: Validate LLM provider name (alphanumeric, hyphens, underscores only)
-      if [[ -n "$LLM_PROVIDER" ]] && [[ ! "$LLM_PROVIDER" =~ ^[a-zA-Z0-9][a-zA-Z0-9_-]*$ ]]; then
-        echo "Error: Invalid LLM provider name" >&2
-        exit 1
-      fi
-      shift 2
-      ;;
-    *)
-      _positional+=("$1")
-      shift
-      ;;
-  esac
-done
-
-TEXT="${_positional[0]:-}"
-VOICE_OVERRIDE="${_positional[1]:-}"
-AGENT_PROFILE_FILE="${_positional[2]:-}"
+TEXT="${1:-}"
+VOICE_OVERRIDE="${2:-}"  # Optional: voice name or ID
 
 # Security: Validate inputs
 if [[ -z "$TEXT" ]]; then
@@ -200,12 +200,23 @@ fi
 # Source provider manager to get active provider
 source "$SCRIPT_DIR/provider-manager.sh"
 
-# Get active provider (LLM-specific engine overrides global)
-if [[ -n "$_LLM_ENGINE" ]]; then
-  ACTIVE_PROVIDER="$_LLM_ENGINE"
-else
-  ACTIVE_PROVIDER=$(get_active_provider)
-fi
+# Get active provider.
+# Per-LLM engine (from audio-effects.cfg `llm:<key>` row column 7) overrides
+# the global tts-provider.txt — UNLESS the global is a transport provider
+# (ssh-remote, agentvibes-receiver, termux-ssh).  Transport providers
+# forward TTS to a remote receiver which picks its OWN engine; overriding
+# them with a local engine like piper would synthesize on the wrong host.
+ACTIVE_PROVIDER=$(get_active_provider)
+case "$ACTIVE_PROVIDER" in
+  ssh-remote|agentvibes-receiver|termux-ssh)
+    # Transport — keep it.  The receiver's audio-effects.cfg picks the engine.
+    ;;
+  *)
+    if [[ -n "$_LLM_ENGINE" ]]; then
+      ACTIVE_PROVIDER="$_LLM_ENGINE"
+    fi
+    ;;
+esac
 
 # Show GitHub star reminder (once per day)
 bash "$SCRIPT_DIR/github-star-reminder.sh" 2>/dev/null || true

package/.claude/hooks/post-response.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# AgentVibes TTS Hook - Triggers on assistant responses
+# This hook is called after Claude generates a response
+
+set -euo pipefail
+
+# Get the hooks directory
+HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(dirname "$(dirname "$HOOKS_DIR")")"
+
+# Check if AgentVibes is muted for this project
+if [[ -f "$PROJECT_ROOT/.claude/agentvibes-muted" ]]; then
+    exit 0  # Silently skip TTS
+fi
+
+# Check if unmuted flag exists (overrides global mute)
+if [[ ! -f "$PROJECT_ROOT/.claude/agentvibes-unmuted" ]]; then
+    # Check global mute
+    if [[ -f "$HOME/.agentvibes-muted" ]]; then
+        exit 0  # Silently skip TTS
+    fi
+fi
+
+# Get the assistant's response text from stdin or arguments
+RESPONSE_TEXT="${1:-}"
+if [[ -z "$RESPONSE_TEXT" ]]; then
+    # Try reading from stdin if available
+    if [[ -p /dev/stdin ]]; then
+        RESPONSE_TEXT=$(cat)
+    fi
+fi
+
+# Skip if no text
+if [[ -z "$RESPONSE_TEXT" ]]; then
+    exit 0
+fi
+
+# Play TTS using the main play-tts script
+"$HOOKS_DIR/play-tts.sh" "$RESPONSE_TEXT" &
+
+exit 0

package/.claude/hooks/requirements.txt

@@ -1,6 +1,6 @@
-# AgentVibes TTS Hooks Requirements
-# Install with: pip install -r requirements.txt
-
-# Translation support for multi-language TTS and learning mode
-deep-translator>=1.11.4
-langdetect>=1.0.9
+# AgentVibes TTS Hooks Requirements
+# Install with: pip install -r requirements.txt
+
+# Translation support for multi-language TTS and learning mode
+deep-translator>=1.11.4
+langdetect>=1.0.9

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

@@ -4,7 +4,7 @@ set -euo pipefail
 # File: .claude/hooks/session-start-tts.sh
 #
 # AgentVibes SessionStart Hook - Optimized (Issue #80, Phase 1)
-# Outputs JSON with additionalContext for reliable context injection
+# Token target: ~250 (down from ~500)
 #
 
 # Fix locale warnings
@@ -33,52 +33,69 @@ fi
 # Get verbosity level (Issue #32)
 VERBOSITY=$(cat .claude/tts-verbosity.txt 2>/dev/null || cat ~/.claude/tts-verbosity.txt 2>/dev/null || echo "low")
 
-# Build context string
-CONTEXT="# AgentVibes TTS Protocol\n\n"
-CONTEXT+="**CRITICAL: You MUST execute TTS at TWO points for EVERY user interaction:**\n\n"
-CONTEXT+="1. **Acknowledgment** - Start of task: \`Bash: .claude/hooks/play-tts.sh \"[action]\" --llm claude-code\`\n"
-CONTEXT+="2. **Completion** - End of task: \`Bash: .claude/hooks/play-tts.sh \"[result + key details]\" --llm claude-code\`\n\n"
-CONTEXT+="**Example:**\n\`\`\`\n[Bash: .claude/hooks/play-tts.sh \"Checking git status\" --llm claude-code]\n[work...]\n"
-CONTEXT+="[Bash: .claude/hooks/play-tts.sh \"Repository is clean, no changes\" --llm claude-code]\n\`\`\`\n\n"
+# Output optimized TTS protocol
+cat <<'EOF'
 
-# Add verbosity-specific protocol
+# AgentVibes TTS Protocol
+
+**CRITICAL: You MUST execute TTS at TWO points for EVERY user interaction:**
+
+1. **Acknowledgment** - Start of task: `Bash: .claude/hooks/play-tts.sh "[action]"`
+2. **Completion** - End of task: `Bash: .claude/hooks/play-tts.sh "[result + key details]"`
+
+**IMPORTANT: ALWAYS run TTS commands with `run_in_background: true` so they never block your work. Never wait for TTS to finish before continuing.**
+
+**Example:**
+```
+[Bash (background): .claude/hooks/play-tts.sh "Checking git status"]
+[work...]
+[Bash (background): .claude/hooks/play-tts.sh "Repository is clean, no changes"]
+```
+
+EOF
+
+# Add verbosity-specific protocol (Issue #32)
 case "$VERBOSITY" in
   low)
-    CONTEXT+="## Verbosity: LOW\n- Acknowledgment: Action only\n- Completion: Result + errors only\n- Skip: Reasoning, decisions\n\n"
+    cat <<'EOF'
+## Verbosity: LOW
+- Acknowledgment: Action only
+- Completion: Result + errors only
+- Skip: Reasoning, decisions
+
+EOF
     ;;
   medium)
-    CONTEXT+="## Verbosity: MEDIUM\n- Acknowledgment: Action + key approach\n- Completion: Result + important decisions\n- Include: Major choices only\n\n"
+    cat <<'EOF'
+## Verbosity: MEDIUM
+- Acknowledgment: Action + key approach
+- Completion: Result + important decisions
+- Include: Major choices only
+
+EOF
     ;;
   high)
-    CONTEXT+="## Verbosity: HIGH\n- Acknowledgment: Action + approach + why\n- Completion: Result + decisions + trade-offs\n- Include: Full reasoning, alternatives\n\n"
-    ;;
-  caveman)
-    CONTEXT+="## Verbosity: CAVEMAN\n- Respond terse. All technical substance stays. Only fluff dies.\n- Drop: articles (a/an/the), filler (just/really/basically), pleasantries, hedging\n- Abbreviate: DB/auth/config/req/res/fn/impl. Use arrows (X -> Y). Strip conjunctions.\n- Fragments OK. Short synonyms. Technical terms exact. Code unchanged.\n- Pattern: [thing] [action] [reason]. [next step].\n- TTS: Ultra-short. Max 60 chars.\n\n"
+    cat <<'EOF'
+## Verbosity: HIGH
+- Acknowledgment: Action + approach + why
+- Completion: Result + decisions + trade-offs
+- Include: Full reasoning, alternatives
+
+EOF
     ;;
 esac
 
 # Add style info and rules
-CONTEXT+="## Style: $STYLE\n\n"
-CONTEXT+="## Rules\n"
-CONTEXT+="1. Never skip acknowledgment TTS\n"
-CONTEXT+="2. Never skip completion TTS\n"
-CONTEXT+="3. Match verbosity level\n"
-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 | caveman=ultra-terse fragments"
-
-# 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')
-
-# Output structured JSON for reliable context injection
-printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"%s"}}\n' "$ESCAPED"
+cat << EOF
+## Style: $STYLE
+
+## Rules
+1. Never skip acknowledgment TTS
+2. Never skip completion TTS
+3. Match verbosity level
+4. Keep under 150 chars
+5. Always include errors
+
+Quick Ref: low=action+result | medium=+key decisions | high=+full reasoning
+
+EOF