agentvibes 5.6.7 → 5.6.8

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

@@ -1 +1,6 @@
 default||agentvibes_soft_flamenco_loop.mp3|0.30
+llm:default|light||0.15|en_US-lessac-high||piper
+llm:claude-code|light|agent_vibes_chillwave_v2_loop.mp3|0.15|en_US-lessac-high|Claude Code here|piper
+llm:copilot|light|agent_vibes_bossa_nova_v2_loop.mp3|0.15|en_US-libritts-high::Anna-11|Copilot here|piper
+llm:codex|light|agent_vibes_chillwave_v2_loop.mp3|0.15|en_US-lessac-high|Codex here|piper
+llm:hermes|light|agent_vibes_bachata_v1_loop.mp3|0.15|en_US-libritts-high::Leo-8|Hermes here|piper

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

@@ -25,3 +25,4 @@ agent_vibes_chillwave_v2_loop.mp3:.00000000000000000003308191
 Midnight Charleston Stomp.mp3:.00000000000000000010960000
 agent_vibes_japanese_city_pop_v1_loop.mp3:11.702675
 agentvibes_soft_flamenco_loop.mp3:9.589660
+Late Night Hip Hop Groove.mp3:5.601723

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

@@ -1 +1 @@
-20260508
+20260509

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

@@ -91,6 +91,7 @@ DEFAULT_VOICE="en_US-lessac-medium"
 # @returns Sets $VOICE_MODEL global variable
 # @sideeffects None
 VOICE_MODEL=""
+FILE_VOICE=""
 
 # Get current language setting
 CURRENT_LANGUAGE=$(get_language_code)
@@ -206,6 +207,15 @@ else
   fi
 fi
 
+# Preserve full display name (with ::SpeakerName) before any stripping for logging
+if [[ -n "$VOICE_OVERRIDE" ]]; then
+  DISPLAY_VOICE_NAME="$VOICE_OVERRIDE"
+elif [[ -n "$FILE_VOICE" ]]; then
+  DISPLAY_VOICE_NAME="$FILE_VOICE"
+else
+  DISPLAY_VOICE_NAME="$VOICE_MODEL"
+fi
+
 # @function validate_inputs
 # @intent Check required parameters
 # @why Fail fast with clear errors if inputs missing
@@ -215,6 +225,10 @@ if [[ -z "$TEXT" ]]; then
   exit 1
 fi
 
+# Augment PATH for non-interactive shells (pipx installs to ~/.local/bin which
+# interactive shells get via .bashrc/.zshrc, but Bash tool calls skip profile)
+export PATH="$HOME/.local/bin:$HOME/.local/share/pipx/venvs/piper-tts/bin:$PATH"
+
 # Check if Piper is installed
 if ! command -v piper &> /dev/null; then
   echo "❌ Error: Piper TTS not installed"
@@ -614,7 +628,31 @@ if [[ -n "$BACKGROUND_MUSIC" ]]; then
   MUSIC_FILENAME=$(basename "$BACKGROUND_MUSIC")
   echo -e "${WHITE}🎵 Background music:${NC} ${PURPLE}$MUSIC_FILENAME${NC}"
 fi
-echo -e "${WHITE}🎤 Voice used:${NC} ${BLUE}$VOICE_MODEL${NC} ${WHITE}(Piper TTS)${NC}"
+# Build friendly label: "model::Mike-13 [Mike Nash]"
+_SURNAME_POOL=("Bell" "Carter" "Davis" "Ellis" "Foster" "Gray" "Hayes" "Irving" "Jones" "Knox" "Lane" "Mason" "Nash" "Owens" "Pierce" "Quinn")
+_VOICE_DISPLAY_LABEL="$DISPLAY_VOICE_NAME"
+if [[ "$DISPLAY_VOICE_NAME" == *"::"* ]]; then
+  _SP="${DISPLAY_VOICE_NAME#*::}"
+  # Skip 16Speakers names (underscore = already first_last format)
+  if [[ "$_SP" != *"_"* ]]; then
+    _FRIENDLY=""
+    if [[ "$_SP" =~ ^(.+)-([0-9]+)$ ]]; then
+      if [[ ${BASH_REMATCH[2]} -ge 2 ]]; then
+        _IDX=$(( (${BASH_REMATCH[2]} - 1) % 16 ))
+        _FRIENDLY="${BASH_REMATCH[1]} ${_SURNAME_POOL[$_IDX]}"
+      else
+        # n=1: strip suffix, use Bell — matches uniquifyVoiceName JS behaviour
+        _FRIENDLY="${BASH_REMATCH[1]} ${_SURNAME_POOL[0]}"
+      fi
+    elif [[ "$_SP" =~ [[:space:]] ]]; then
+      _FRIENDLY="$_SP"
+    else
+      _FRIENDLY="$_SP ${_SURNAME_POOL[0]}"
+    fi
+    [[ "$_FRIENDLY" != "$_SP" ]] && _VOICE_DISPLAY_LABEL="$DISPLAY_VOICE_NAME [$_FRIENDLY]"
+  fi
+fi
+echo -e "${WHITE}🎤 Voice used:${NC} ${BLUE}$_VOICE_DISPLAY_LABEL${NC} ${WHITE}(Piper TTS)${NC}"
 
 # Show personality if configured
 PERSONALITY=$(cat "$PROJECT_ROOT/.claude/tts-personality.txt" 2>/dev/null || cat "$HOME/.claude/tts-personality.txt" 2>/dev/null || echo "")

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

@@ -115,6 +115,15 @@ while [[ $# -gt 0 ]]; do
       LLM_PROVIDER="${2:-}"
       shift 2
       ;;
+    --project-dir)
+      # Always prefer the explicitly-injected project dir over any stale
+      # CLAUDE_PROJECT_DIR in the environment (fixes silent override by env).
+      # Validate the path exists before trusting it.
+      if [[ -n "${2:-}" && -d "${2}" ]]; then
+        export CLAUDE_PROJECT_DIR="${2}"
+      fi
+      shift 2
+      ;;
     *)
       _POSITIONAL_ARGS+=("$1")
       shift

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

@@ -10,18 +10,49 @@ set -euo pipefail
 # Fix locale warnings
 export LC_ALL=C
 
-# Get script directory
+# Get script directory (resolve symlinks so $SCRIPT_DIR is the real hooks dir)
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
+# Resolve absolute path to play-tts.sh from this script's own location.
+# Using an absolute path in the injected protocol ensures the correct
+# play-tts.sh is called regardless of the working directory when Claude
+# runs the command — fixes "wrong voice in fresh folder" regression.
+PLAY_TTS_PATH="$SCRIPT_DIR/play-tts.sh"
+
 # Check if AgentVibes is installed
-if [[ ! -f "$SCRIPT_DIR/play-tts.sh" ]]; then
+if [[ ! -f "$PLAY_TTS_PATH" ]]; then
   # AgentVibes not installed, don't inject anything
   exit 0
 fi
 
+# Capture project dir NOW while Claude Code has set CLAUDE_PROJECT_DIR.
+# Bash tool calls (how Claude actually runs play-tts.sh) do not automatically
+# receive CLAUDE_PROJECT_DIR, so we bake it into the injected protocol command
+# via --project-dir so the correct per-project config is always found.
+CAPTURED_PROJECT_DIR=""
+if [[ -n "${CLAUDE_PROJECT_DIR:-}" && -d "$CLAUDE_PROJECT_DIR/.claude" ]]; then
+  CAPTURED_PROJECT_DIR="$CLAUDE_PROJECT_DIR"
+  _PROJECT_CLAUDE_DIR="$CLAUDE_PROJECT_DIR/.claude"
+else
+  # Fallback: script lives inside .claude/hooks/, so parent IS .claude/
+  _PROJECT_CLAUDE_DIR="$(dirname "$SCRIPT_DIR")"
+fi
+
+# Build --project-dir flag to embed in TTS commands.
+# Sanitize: strip any embedded quotes that would break shell quoting.
+PROJECT_DIR_FLAG=""
+if [[ -n "$CAPTURED_PROJECT_DIR" ]]; then
+  _SAFE_PROJECT_DIR="${CAPTURED_PROJECT_DIR//\"/}"
+  PROJECT_DIR_FLAG=" --project-dir \"$_SAFE_PROJECT_DIR\""
+fi
+
 # Check for sentiment (priority) or personality (fallback)
-SENTIMENT=$(cat .claude/tts-sentiment.txt 2>/dev/null || cat ~/.claude/tts-sentiment.txt 2>/dev/null || echo "")
-PERSONALITY=$(cat .claude/tts-personality.txt 2>/dev/null || cat ~/.claude/tts-personality.txt 2>/dev/null || echo "normal")
+SENTIMENT=$(cat "$_PROJECT_CLAUDE_DIR/tts-sentiment.txt" 2>/dev/null \
+  || cat "$HOME/.claude/tts-sentiment.txt" 2>/dev/null \
+  || echo "")
+PERSONALITY=$(cat "$_PROJECT_CLAUDE_DIR/tts-personality.txt" 2>/dev/null \
+  || cat "$HOME/.claude/tts-personality.txt" 2>/dev/null \
+  || echo "normal")
 
 # Determine style
 if [[ -n "$SENTIMENT" ]]; then
@@ -31,26 +62,30 @@ else
 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")
+VERBOSITY=$(cat "$_PROJECT_CLAUDE_DIR/tts-verbosity.txt" 2>/dev/null \
+  || cat "$HOME/.claude/tts-verbosity.txt" 2>/dev/null \
+  || echo "low")
 
-# Output optimized TTS protocol
-cat <<'EOF'
+# Output optimized TTS protocol.
+# Note: heredoc uses double-quotes (<<EOF not <<'EOF') so $PLAY_TTS_PATH expands.
+# Backticks must be escaped (\`) to avoid command substitution.
+cat << EOF
 
 # 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]"`
+1. **Acknowledgment** - Start of task: \`Bash: $PLAY_TTS_PATH "[action]" --llm claude-code$PROJECT_DIR_FLAG\`
+2. **Completion** - End of task: \`Bash: $PLAY_TTS_PATH "[result + key details]" --llm claude-code$PROJECT_DIR_FLAG\`
 
 **IMPORTANT: Run TTS commands inline (NOT in background). Wait for each TTS call to complete before continuing.**
 
 **Example:**
-```
-[Bash: .claude/hooks/play-tts.sh "Checking git status"]
+\`\`\`
+[Bash: $PLAY_TTS_PATH "Checking git status" --llm claude-code$PROJECT_DIR_FLAG]
 [work...]
-[Bash: .claude/hooks/play-tts.sh "Repository is clean, no changes"]
-```
+[Bash: $PLAY_TTS_PATH "Repository is clean, no changes" --llm claude-code$PROJECT_DIR_FLAG]
+\`\`\`
 
 EOF
 

package/.claude/hooks-windows/play-tts-piper.ps1

@@ -75,6 +75,7 @@ elseif (Test-Path $VoiceFile) {
 # IMPORTANT: The trailing number in a speaker name (e.g. "Holly-7") is a disambiguation
 # suffix, NOT the speaker index. Real index must be looked up from voice-assignments.json.
 $SpeakerId = $null
+$DisplayVoiceName = $VoiceName  # preserve full name (e.g. "model::SpeakerName") for logging
 
 if ($VoiceName -match '::') {
     $parts = $VoiceName -split '::'
@@ -227,7 +228,31 @@ try {
 
     # Display results
     Write-Host "[OK] Saved to: $AudioFile" -ForegroundColor Green
-    Write-Host "[VOICE] Voice used: $VoiceName (Piper)" -ForegroundColor Green
+
+    # Build friendly label: "model::Mike-13 [Mike Nash]"
+    $SURNAME_POOL = @('Bell','Carter','Davis','Ellis','Foster','Gray','Hayes','Irving','Jones','Knox','Lane','Mason','Nash','Owens','Pierce','Quinn')
+    $VoiceDisplayLabel = $DisplayVoiceName
+    if ($DisplayVoiceName -match '::(.+)$') {
+        $sp = $Matches[1]
+        # Skip 16Speakers names (contain underscore — already first_last format)
+        if ($sp -notmatch '_') {
+            $friendly = $null
+            if ($sp -match '^(.+)-(\d+)$') {
+                if ([int]$Matches[2] -ge 2) {
+                    $friendly = "$($Matches[1]) $($SURNAME_POOL[([int]$Matches[2] - 1) % $SURNAME_POOL.Length])"
+                } else {
+                    # n=1: strip suffix, use Bell — matches uniquifyVoiceName JS behaviour
+                    $friendly = "$($Matches[1]) $($SURNAME_POOL[0])"
+                }
+            } elseif ($sp -match '\s') {
+                $friendly = $sp
+            } else {
+                $friendly = "$sp $($SURNAME_POOL[0])"
+            }
+            if ($null -ne $friendly -and $friendly -ne $sp) { $VoiceDisplayLabel = "$DisplayVoiceName [$friendly]" }
+        }
+    }
+    Write-Host "[VOICE] Voice used: $VoiceDisplayLabel (Piper)" -ForegroundColor Green
 
     # Apply audio effects (reverb, background music) if processor script exists.
     # SKIP when AGENTVIBES_NO_PLAY is set — that means the parent play-tts.ps1

package/.claude/hooks-windows/play-tts.ps1

@@ -16,7 +16,13 @@ param(
     # When provided, the router looks up an `llm:<name>` row in audio-effects.cfg
     # to apply LLM-specific voice, pretext, reverb, and engine settings.
     [Parameter(Mandatory = $false)]
-    [string]$llm = ""
+    [string]$llm = "",
+
+    # Project directory override. session-start-tts.ps1 bakes the session's
+    # CLAUDE_PROJECT_DIR value here so per-project config is found even when
+    # Bash tool calls do not propagate CLAUDE_PROJECT_DIR to child processes.
+    [Parameter(Mandatory = $false)]
+    [string]$ProjectDir = ""
 )
 
 # Text-file handoff: the SSH receiver watcher writes long/special-char text to
@@ -31,6 +37,16 @@ if ($Text -eq "__from_file__" -and $env:AGENTVIBES_TEXT_FILE) {
     }
 }
 
+# If -ProjectDir was passed (by session-start-tts.ps1), promote it to the
+# CLAUDE_PROJECT_DIR env var so the per-LLM config lookup below finds it.
+# This ensures per-project audio settings work even when Bash tool calls
+# don't automatically inherit CLAUDE_PROJECT_DIR from Claude Code.
+if ($ProjectDir -and (Test-Path $ProjectDir)) {
+    # Always prefer the explicitly-injected project dir; validates path exists
+    # before trusting it (fixes both the stale-env-var override bug and path injection).
+    $env:CLAUDE_PROJECT_DIR = $ProjectDir
+}
+
 # Configuration paths
 # First check if we're running from a project directory with .claude
 $ScriptPath = Split-Path -Parent $MyInvocation.MyCommand.Path
@@ -187,6 +203,14 @@ if ($llm -and $llm -notmatch '^[a-zA-Z0-9][a-zA-Z0-9_-]*$') {
 }
 
 # --- Default fallback --------------------------------------------------------
+# When no -llm flag is passed (e.g. hooks invoked by Claude Code without the
+# flag), check AGENTVIBES_LLM_KEY first — it is set by the hook infrastructure
+# as "llm:<name>" and carries the active LLM identity.  Strip the "llm:" prefix
+# to get the bare key used for config lookup.
+if (-not $llm -and $env:AGENTVIBES_LLM_KEY -match '^llm:([a-zA-Z0-9][a-zA-Z0-9_-]*)$') {
+    $llm = $Matches[1]
+}
+
 # An empty $llm routes through the "default" pseudo-LLM.  Users who configure
 # an `llm:default` row in audio-effects.cfg get consistent audio settings for
 # every LLM that doesn't pass its own -llm flag — a convenient global override

package/.claude/hooks-windows/session-start-tts.ps1

@@ -9,18 +9,37 @@
 
 $ErrorActionPreference = "Stop"
 
-# Get script directory
+# Get script directory and resolve absolute path to play-tts.ps1.
+# Using an absolute path in the injected protocol ensures the correct play-tts.ps1
+# is called regardless of the working directory when Claude runs the command.
 $ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$PlayTtsPath = Join-Path $ScriptDir "play-tts.ps1"
 
 # Check if AgentVibes is installed
-if (-not (Test-Path (Join-Path $ScriptDir "play-tts.ps1"))) {
+if (-not (Test-Path $PlayTtsPath)) {
     # AgentVibes not installed, don't inject anything
     exit 0
 }
 
-# Resolve project .claude dir from script location (avoids CWD-relative path issues)
-$ProjectClaudeDir = Split-Path -Parent (Split-Path -Parent $ScriptDir)
-$ProjectClaudeDir = Join-Path $ProjectClaudeDir ".claude"
+# Capture project dir NOW while Claude Code has set it correctly.
+# Bash tool calls (how Claude actually runs play-tts.ps1) do not
+# automatically receive CLAUDE_PROJECT_DIR, so we bake the value
+# into the injected protocol command via the -ProjectDir parameter.
+$CapturedProjectDir = ""
+if ($env:CLAUDE_PROJECT_DIR -and (Test-Path "$env:CLAUDE_PROJECT_DIR\.claude")) {
+    $CapturedProjectDir  = $env:CLAUDE_PROJECT_DIR
+    $ProjectClaudeDir    = "$env:CLAUDE_PROJECT_DIR\.claude"
+} else {
+    $ProjectClaudeDir = Join-Path (Split-Path -Parent (Split-Path -Parent $ScriptDir)) ".claude"
+}
+
+# Build the -ProjectDir flag to inject into TTS commands (empty string = omit flag).
+# Sanitize: strip any embedded quotes that would break PowerShell argument quoting.
+$ProjectDirFlag = ""
+if ($CapturedProjectDir) {
+    $SafeProjectDir = $CapturedProjectDir -replace '"', ''
+    $ProjectDirFlag = " -ProjectDir `"$SafeProjectDir`""
+}
 
 # Check for sentiment (priority) or personality (fallback)
 $Sentiment = ""
@@ -65,14 +84,14 @@ Write-Output @"
 
 **CRITICAL: You MUST execute TTS at TWO points for EVERY user interaction:**
 
-1. **Acknowledgment** - Start of task: ``Bash: powershell -NoProfile -ExecutionPolicy Bypass -File ".claude\hooks-windows\play-tts.ps1" "[action]"``
-2. **Completion** - End of task: ``Bash: powershell -NoProfile -ExecutionPolicy Bypass -File ".claude\hooks-windows\play-tts.ps1" "[result + key details]"``
+1. **Acknowledgment** - Start of task: ``Bash: powershell -NoProfile -ExecutionPolicy Bypass -File "$PlayTtsPath" "[action]" -llm claude-code$ProjectDirFlag``
+2. **Completion** - End of task: ``Bash: powershell -NoProfile -ExecutionPolicy Bypass -File "$PlayTtsPath" "[result + key details]" -llm claude-code$ProjectDirFlag``
 
 **Example:**
 ``````
-[Bash: powershell -NoProfile -ExecutionPolicy Bypass -File ".claude\hooks-windows\play-tts.ps1" "Checking git status"]
+[Bash: powershell -NoProfile -ExecutionPolicy Bypass -File "$PlayTtsPath" "Checking git status" -llm claude-code$ProjectDirFlag]
 [work...]
-[Bash: powershell -NoProfile -ExecutionPolicy Bypass -File ".claude\hooks-windows\play-tts.ps1" "Repository is clean, no changes"]
+[Bash: powershell -NoProfile -ExecutionPolicy Bypass -File "$PlayTtsPath" "Repository is clean, no changes" -llm claude-code$ProjectDirFlag]
 ``````
 
 "@

package/.claude/settings.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "powershell -NoProfile -ExecutionPolicy Bypass -File \"$CLAUDE_PROJECT_DIR\\.claude\\hooks-windows\\session-start-tts.ps1\""
+            "command": "powershell -NoProfile -ExecutionPolicy Bypass -File \"$HOME\\.claude\\hooks-windows\\session-start-tts.ps1\""
           }
         ]
       }
@@ -16,7 +16,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/session-start-tts.sh\""
+            "command": "bash \"$HOME/.claude/hooks/session-start-tts.sh\""
           }
         ]
       }

package/CLAUDE.md

@@ -28,6 +28,15 @@ This project follows **BMAD (BMM - Business Model Methodology)** for all story d
 4. **Update sprint-status.yaml** automatically via `/dev-story`
 5. **Code review included** - Built into `/dev-story` workflow
 
+### ✅ Non-Destructive Configuration Rule (MANDATORY)
+All code that reads, writes, or modifies user configuration MUST be non-destructive:
+1. **Never delete or overwrite** existing user `.claude/` or `~/.claude/` config files (settings, voices, personalities, audio-effects.cfg) unless the user explicitly requested it
+2. **Copy new files; never remove existing ones** — installer adds missing files only
+3. **Write hooks only when absent** — `configureSessionStartHook` and similar functions check for existing hooks before writing
+4. **Preserve custom entries** — e.g. `audio-effects.cfg` user rows must survive an `agentvibes update`
+5. **Creating directories is fine** — `mkdir -p` / `{ recursive: true }` is always safe
+6. Any function that could overwrite user data must have a test asserting idempotency
+
 ### ✅ Git Workflow (ONLY Outside BMAD)
 For changes outside story development:
 1. Describe changes before acting

package/README.md

@@ -11,7 +11,7 @@
 [![Publish](https://github.com/paulpreibisch/AgentVibes/actions/workflows/publish.yml/badge.svg)](https://github.com/paulpreibisch/AgentVibes/actions/workflows/publish.yml)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-**Author**: Paul Preibisch ([@997Fire](https://x.com/997Fire)) | **Version**: v5.6.7
+**Author**: Paul Preibisch ([@997Fire](https://x.com/997Fire)) | **Version**: v5.6.8
 
 ---
 
@@ -40,9 +40,17 @@ Whether you're coding in Claude Code, chatting in Claude Desktop, using Warp Ter
 
 ---
 
-## 🌟 NEW IN v5.6.7 — Windows Preview Fixed
+## 🌟 NEW IN v5.6.8 — WSL Voice Routing Fixed + Session Lifecycle Reliability
 
-The **Preview button in LLM audio configuration now works correctly on Windows**. It plays the voice, reverb, and background track you configured — no more defaulting to the wrong voice or playing silence.
+**WSL users:** AgentVibes was playing `en_US-lessac-medium` regardless of your configured voice. Fixed — Piper is now found in non-interactive shells by explicitly prepending `~/.local/bin` to `PATH` before the binary check.
+
+**Per-project routing:** The session-start hook now bakes `--project-dir` into every injected TTS command, so your configured voice and music play correctly in Bash tool calls even when `CLAUDE_PROJECT_DIR` isn't in the environment.
+
+`play-tts-piper.sh` and `play-tts-piper.ps1` are now included in `agentvibes install`'s critical hooks deployment — updated versions propagate automatically.
+
+## v5.6.7 — Windows Preview Fixed
+
+The Preview button in LLM audio configuration now works correctly on Windows.
 
 ## v5.6.6 — Preview Button Works in WSL + Comprehensive Windows Test Suite
 

package/RELEASE_NOTES.md

@@ -1,5 +1,37 @@
 # AgentVibes Release Notes
 
+## 🐧 v5.6.8 — WSL Voice Routing Fixed + Session Lifecycle Reliability
+
+**Released:** 2026-05-09
+
+### 🐛 WSL: Configured Voice Now Plays (Not Lessac Fallback)
+
+In WSL sessions, AgentVibes was playing `en_US-lessac-medium` regardless of what voice you configured. The root cause: `pipx` installs Piper to `~/.local/bin/`, which interactive shells get via `.bashrc`/`.zshrc`, but Claude Code's Bash tool calls run non-interactively and skip profile sourcing — `command -v piper` failed, falling back to the default voice.
+
+**Fix:** `play-tts-piper.sh` now prepends `~/.local/bin` and the pipx Piper venv bin to `PATH` before the binary check, so Piper is found regardless of shell mode.
+
+### 🐛 Per-Project Voice/Music Lost When `CLAUDE_PROJECT_DIR` Not in Bash Environment
+
+When Claude Code runs a Bash tool call, `CLAUDE_PROJECT_DIR` is not passed in the environment. The TTS hooks couldn't find per-project config and fell back to global defaults — wrong voice, wrong music, no pretext.
+
+**Fix:** `session-start-tts.sh` (and `.ps1`) now bakes the project directory into the injected hook command as `--project-dir`. `play-tts.sh` reads this flag before any config lookup, so per-project routing is reliable in every Bash tool call.
+
+### 🐛 `play-tts-piper.sh` and `play-tts-piper.ps1` Not Deployed by `agentvibes install`
+
+These hooks were missing from `CRITICAL_HOOKS` / `CRITICAL_HOOKS_WINDOWS`, so `agentvibes install` never propagated updated versions to `~/.claude/hooks/`.
+
+**Fix:** Both are now in the critical hooks list and always deployed on install/update.
+
+### 🐛 Voice Display Name Bugs
+
+- `uniquifyVoiceName("Mary-1")` returned `"Mary-1 Bell"` instead of `"Mary Bell"`.
+- 16Speakers names like `Rose_Ibex` were incorrectly getting a surname appended (`"Rose Ibex Bell"`).
+- `🎤 Voice used:` line was missing from WSL bash output.
+
+All three fixed. A new test file (`test/unit/voice-names.test.js`, 16 tests) covers these cases.
+
+---
+
 ## 🪟 v5.6.7 — Windows Preview Fixed
 
 **Released:** 2026-05-08

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "agentvibes",
-  "version": "5.6.7",
+  "version": "5.6.8",
   "description": "Now your AI Agents can finally talk back! Professional TTS voice for Claude Code, Claude Desktop (via MCP), and Clawdbot with multi-provider support.",
   "homepage": "https://agentvibes.org",
   "keywords": [

package/src/console/app.js

@@ -30,6 +30,7 @@ import { createReceiverTab } from './tabs/receiver-tab.js';
 import { createAgentsTab } from './tabs/agents-tab.js';
 import { ConfigService } from '../services/config-service.js';
 import { ProviderService } from '../services/provider-service.js';
+import { seedAllLlmDefaultsSync } from '../services/llm-provider-service.js';
 
 const _dir = path.dirname(fileURLToPath(import.meta.url));
 const _pkg = JSON.parse(readFileSync(path.join(_dir, '../../package.json'), 'utf8'));
@@ -893,6 +894,11 @@ export class AgentVibesConsole {
  * @returns {Promise<AgentVibesConsole>}
  */
 export async function launchConsole(opts = {}) {
+  // Seed per-LLM piper defaults into the project config on every TUI launch.
+  // This guarantees play-tts.ps1 always finds a piper engine row for each LLM
+  // and never silently falls back to the global windows-sapi provider.
+  seedAllLlmDefaultsSync(process.cwd());
+
   const app = new AgentVibesConsole(opts);
   await app.init();
   return app;

package/src/console/widgets/format-utils.js

@@ -5,6 +5,8 @@
  * circular imports between widgets and tabs.
  */
 
+import { uniquifyVoiceName } from '../../utils/voice-names.js';
+
 const TRACK_NAMES = Object.freeze({
   'agentvibes_soft_flamenco_loop.mp3':                 '🎻 Soft Flamenco',
   'agent_vibes_bachata_v1_loop.mp3':                   '🎺 Bachata',
@@ -60,8 +62,15 @@ export function formatVoiceName(voice) {
 
   let name;
   if (voice.includes('::')) {
-    // 16Speakers::Rose_Ibex → extract after '::'
-    name = voice.split('::')[1];
+    const speakerPart = voice.split('::')[1];
+    if (speakerPart.includes('_')) {
+      // 16Speakers format (Rose_Ibex) — already a complete name, just normalise display
+      name = speakerPart.replace(/_/g, ' ');
+    } else {
+      // LibriTTS / single-word names: append deterministic surname
+      // "Mary" → "Mary Bell", "Mary-7" → "Mary Hayes"
+      name = uniquifyVoiceName(speakerPart);
+    }
   } else {
     const parts = voice.split('-');
     const QUALITIES = new Set(['high', 'medium', 'low']);

package/src/installer.js

@@ -4054,17 +4054,18 @@ async function configureSessionStartHook(targetDir, spinner) {
       existingSettings.hooks = {};
     }
 
-    if (!existingSettings.hooks.SessionStart) {
-      if (isNativeWindows()) {
-        existingSettings.hooks.SessionStart = [{
-          hooks: [{
-            type: 'command',
-            command: 'powershell -NoProfile -ExecutionPolicy Bypass -File "$CLAUDE_PROJECT_DIR\\.claude\\hooks-windows\\session-start-tts.ps1"'
-          }]
-        }];
-      } else {
-        existingSettings.hooks.SessionStart = templateSettings.hooks.SessionStart;
-      }
+    // Windows uses SessionStart; Linux/macOS/WSL uses UserPromptSubmit.
+    // Both point to the global $HOME path so updates to the hook script
+    // take effect immediately without needing per-project reinstalls.
+    const hookKey = isNativeWindows() ? 'SessionStart' : 'UserPromptSubmit';
+    const hookCommand = isNativeWindows()
+      ? 'powershell -NoProfile -ExecutionPolicy Bypass -File "$HOME\\.claude\\hooks-windows\\session-start-tts.ps1"'
+      : 'bash "$HOME/.claude/hooks/session-start-tts.sh"';
+
+    if (!existingSettings.hooks[hookKey]) {
+      existingSettings.hooks[hookKey] = [{
+        hooks: [{ type: 'command', command: hookCommand }]
+      }];
 
       if (!existingSettings.$schema) {
         existingSettings.$schema = templateSettings.$schema;
@@ -5045,8 +5046,8 @@ async function updateCommandFiles(targetDir, spinner) {
  * These hooks contain bug fixes (e.g. markdown stripping) that must propagate
  * on every `npx agentvibes update` regardless of target directory.
  */
-const CRITICAL_HOOKS = ['stop-tts.sh', 'stop.sh', 'play-tts.sh', 'session-start-tts.sh', 'bmad-party-speak.sh'];
-const CRITICAL_HOOKS_WINDOWS = ['play-tts.ps1', 'session-start-tts.ps1', 'bmad-speak.ps1', 'bmad-party-speak.ps1'];
+const CRITICAL_HOOKS = ['stop-tts.sh', 'stop.sh', 'play-tts.sh', 'play-tts-piper.sh', 'audio-processor.sh', 'session-start-tts.sh', 'bmad-party-speak.sh'];
+const CRITICAL_HOOKS_WINDOWS = ['play-tts.ps1', 'play-tts-piper.ps1', 'audio-processor.ps1', 'session-start-tts.ps1', 'bmad-speak.ps1', 'bmad-party-speak.ps1'];
 
 /**
  * Update critical hooks in the global ~/.claude/hooks/ directory if it exists.
@@ -5056,45 +5057,38 @@ const CRITICAL_HOOKS_WINDOWS = ['play-tts.ps1', 'session-start-tts.ps1', 'bmad-s
  * @returns {Promise<number>} Number of hooks updated
  */
 async function updateGlobalHooks(srcHooksDir, homeDirOverride) {
-  const globalHooksDir = path.join(homeDirOverride || os.homedir(), '.claude', 'hooks');
+  const homeDir = homeDirOverride || os.homedir();
+  const globalHooksDir = path.join(homeDir, '.claude', 'hooks');
   let updated = 0;
-  try {
-    await fs.access(globalHooksDir);
-  } catch {
-    return 0; // global hooks dir not present — nothing to do
-  }
+
+  // Always ensure the global hooks dir exists so registered $HOME hooks resolve.
+  await fs.mkdir(globalHooksDir, { recursive: true });
 
   for (const hook of CRITICAL_HOOKS) {
     const destPath = path.join(globalHooksDir, hook);
     const srcPath = path.join(srcHooksDir, hook);
     try {
-      await fs.access(destPath); // only update if already installed
       await fs.copyFile(srcPath, destPath);
       await fs.chmod(destPath, 0o750);
       updated++;
     } catch {
-      // file not in global dir or src missing — skip silently
+      // src missing — skip silently
     }
   }
 
-  // Also update Windows global hooks-windows dir if present
-  const globalHooksWindowsDir = path.join(homeDirOverride || os.homedir(), '.claude', 'hooks-windows');
+  // Also ensure Windows global hooks-windows dir and scripts are up to date.
+  const globalHooksWindowsDir = path.join(homeDir, '.claude', 'hooks-windows');
   const srcHooksWindowsDir = path.join(path.dirname(srcHooksDir), 'hooks-windows');
-  try {
-    await fs.access(globalHooksWindowsDir);
-    for (const hook of CRITICAL_HOOKS_WINDOWS) {
-      const destPath = path.join(globalHooksWindowsDir, hook);
-      const srcPath = path.join(srcHooksWindowsDir, hook);
-      try {
-        await fs.access(destPath); // only update if already installed
-        await fs.copyFile(srcPath, destPath);
-        updated++;
-      } catch {
-        // file not in global dir or src missing — skip silently
-      }
+  await fs.mkdir(globalHooksWindowsDir, { recursive: true });
+  for (const hook of CRITICAL_HOOKS_WINDOWS) {
+    const destPath = path.join(globalHooksWindowsDir, hook);
+    const srcPath = path.join(srcHooksWindowsDir, hook);
+    try {
+      await fs.copyFile(srcPath, destPath);
+      updated++;
+    } catch {
+      // src missing — skip silently
     }
-  } catch {
-    // hooks-windows dir not present — nothing to do
   }
 
   return updated;
@@ -5337,6 +5331,13 @@ async function install(options = {}) {
     await copyBackgroundMusicFiles(targetDir, silentSpinner);
     await copyConfigFiles(targetDir, silentSpinner);
     await copyCodexFiles(targetDir, silentSpinner);
+
+    // Populate global ~/.claude/hooks[/-windows]/ so $HOME hook paths resolve
+    // on first install (not just on update).
+    const hooksSubdirInstall = isNativeWindows() ? 'hooks-windows' : 'hooks';
+    const srcHooksDirInstall = path.join(__dirname, '..', '.claude', hooksSubdirInstall);
+    await updateGlobalHooks(srcHooksDirInstall);
+
     await configureSessionStartHook(targetDir, silentSpinner);
     await configurePartyModeHook(targetDir, silentSpinner);
     await installPluginManifest(targetDir, silentSpinner);

package/src/services/llm-provider-service.js

@@ -92,8 +92,17 @@ const DEFAULT_LLM_CONFIGS = {
 };
 
 function ensureDefaultLlmConfigSync(llmKey, targetDir) {
-  const existing = loadLlmConfigSync(llmKey, targetDir);
-  if (existing.sourcePath) return;
+  // Check only the project dir — a global config row must not prevent seeding
+  // per-project defaults (otherwise new installs silently inherit a different
+  // project's voice/pretext and the per-LLM piper engine is never written,
+  // causing play-tts.ps1 to fall through to the global SAPI provider).
+  const resolvedDir = targetDir || process.env.INIT_CWD || process.cwd();
+  const projectCfgPath = path.join(resolvedDir, '.claude', 'config', 'audio-effects.cfg');
+  const cfgKey = `llm:${llmKey}`;
+  try {
+    const content = fsSync.readFileSync(projectCfgPath, 'utf8');
+    if (content.split('\n').some(line => line.startsWith(cfgKey + '|'))) return;
+  } catch { /* file not found — continue to seed */ }
 
   const defaults = DEFAULT_LLM_CONFIGS[llmKey];
   if (!defaults) return;
@@ -101,6 +110,17 @@ function ensureDefaultLlmConfigSync(llmKey, targetDir) {
   saveLlmConfigSync(llmKey, defaults, targetDir);
 }
 
+/**
+ * Seed piper defaults for every LLM in DEFAULT_LLM_CONFIGS into the project dir.
+ * Called at install time so play-tts.ps1 always finds a per-LLM piper row in the
+ * project config and never silently falls back to the global windows-sapi provider.
+ */
+export function seedAllLlmDefaultsSync(targetDir) {
+  for (const llmKey of Object.keys(DEFAULT_LLM_CONFIGS)) {
+    ensureDefaultLlmConfigSync(llmKey, targetDir);
+  }
+}
+
 // ── Provider install-checks ─────────────────────────────────────────────────
 
 export async function checkClaudeInstalled(targetDir) {
@@ -902,13 +922,12 @@ export function saveLlmConfigSync(llmKey, config, targetDir) {
   const sanitize = (v) => (v || '').replace(/[\|\n\r\x00]/g, '');
   const cfgLine = `${cfgKey}|${sanitize(config.effects)}|${sanitize(config.bgTrack)}|${sanitize(config.bgVolume)}|${sanitize(config.voice)}|${sanitize(config.pretext)}|${sanitize(config.ttsEngine)}`;
   const resolvedTargetDir = targetDir || process.env.INIT_CWD || process.cwd();
-  // When targetDir is explicitly passed, write there directly (do not fall back to global).
-  // resolveCfgPath falls back to ~/.claude when the local file doesn't yet exist,
-  // which would silently redirect writes away from the intended directory.
-  const cfgPath = config.sourcePath ||
-    (targetDir
-      ? path.join(resolvedTargetDir, '.claude', 'config', 'audio-effects.cfg')
-      : resolveCfgPath(resolvedTargetDir));
+  // When targetDir is explicitly passed, always write to the project dir — never follow
+  // config.sourcePath back to the global ~/.claude/config (it may have been loaded from there
+  // as a "default seed" for a new project, and writing back would pollute other projects).
+  const cfgPath = targetDir
+    ? path.join(resolvedTargetDir, '.claude', 'config', 'audio-effects.cfg')
+    : (config.sourcePath || resolveCfgPath(resolvedTargetDir));
 
   try {
     let content = '';

package/src/utils/voice-names.js

@@ -35,6 +35,8 @@ export function uniquifyVoiceName(rawName) {
       const idx = (n - 1) % SURNAME_POOL.length;
       return `${base} ${SURNAME_POOL[idx]}`;
     }
+    // n=1 (or 0): strip the suffix — "Mary-1" → "Mary Bell" is cleaner than "Mary-1 Bell"
+    return `${base} ${SURNAME_POOL[0]}`;
   }
   if (/\s/.test(rawName)) return rawName;
   return `${rawName} ${SURNAME_POOL[0]}`;