agentvibes 5.12.0 → 5.13.0

package/.claude/hooks/provider-catalog.sh

@@ -0,0 +1,161 @@
+#!/usr/bin/env bash
+#
+# provider-catalog.sh — GENERATED FILE. DO NOT EDIT.
+# DO NOT EDIT — generated from src/services/provider-catalog.js
+# Regenerate with: node scripts/generate-provider-catalog.mjs
+# content-hash: sha256:5e717024f1250a8f54d07291256e532606dba7b4a15ab9589305d1af6bba7f35
+#
+# Bash-3.2-safe catalog accessors (macOS ships bash 3.2 — no associative
+# arrays, no case-modifying parameter expansions). Source this file; do not execute it.
+
+AGENTVIBES_CATALOG_VERSION="5e717024f1250a8f"
+
+# Guard against double-sourcing.
+[ -n "${_AGENTVIBES_PROVIDER_CATALOG_LOADED:-}" ] && return 0
+_AGENTVIBES_PROVIDER_CATALOG_LOADED=1
+
+# Lowercase a string without case-modifying expansions (unavailable in bash 3.2).
+_catalog_lc() { printf '%s' "${1:-}" | tr '[:upper:]' '[:lower:]'; }
+
+# Resolve an id-or-alias to its canonical provider id (echoes it; 1 if unknown).
+catalog_canonical_provider() {
+  case "$(_catalog_lc "${1:-}")" in
+    soprano) printf '%s' 'soprano' ;;
+    piper) printf '%s' 'piper' ;;
+    kokoro) printf '%s' 'kokoro' ;;
+    elevenlabs) printf '%s' 'elevenlabs' ;;
+    macos|macos-say|say) printf '%s' 'macos' ;;
+    windows-sapi|sapi) printf '%s' 'windows-sapi' ;;
+    windows-piper) printf '%s' 'windows-piper' ;;
+    *) return 1 ;;
+  esac
+}
+
+# Echo the default voice for a provider (empty string is valid — system default).
+catalog_default_voice() {
+  local _p; _p="$(catalog_canonical_provider "${1:-}")" || return 1
+  case "$_p" in
+    soprano) printf '%s' 'soprano-default' ;;
+    piper) printf '%s' 'en_US-lessac-medium' ;;
+    kokoro) printf '%s' 'af_heart' ;;
+    elevenlabs) printf '%s' 'Sarah' ;;
+    macos) printf '%s' 'Samantha' ;;
+    windows-sapi) printf '%s' '' ;;
+    windows-piper) printf '%s' 'en_US-lessac-medium' ;;
+  esac
+}
+
+# Echo a human display name for a provider.
+catalog_display_name() {
+  local _p; _p="$(catalog_canonical_provider "${1:-}")" || { printf '%s' "${1:-}"; return 0; }
+  case "$_p" in
+    soprano) printf '%s' 'Soprano TTS' ;;
+    piper) printf '%s' 'Piper TTS' ;;
+    kokoro) printf '%s' 'Kokoro TTS' ;;
+    elevenlabs) printf '%s' 'ElevenLabs' ;;
+    macos) printf '%s' 'macOS Say' ;;
+    windows-sapi) printf '%s' 'Windows SAPI' ;;
+    windows-piper) printf '%s' 'Piper TTS' ;;
+  esac
+}
+
+# Print the provider ids playable on a platform (unix|darwin|windows), one per line.
+catalog_providers_for_platform() {
+  case "$(_catalog_lc "${1:-}")" in
+    unix)
+      printf '%s\n' 'soprano' 'piper' 'kokoro' 'elevenlabs'
+      ;;
+    darwin)
+      printf '%s\n' 'soprano' 'piper' 'kokoro' 'elevenlabs' 'macos'
+      ;;
+    windows)
+      printf '%s\n' 'soprano' 'kokoro' 'windows-sapi' 'windows-piper'
+      ;;
+    *) return 1 ;;
+  esac
+}
+
+# Print a provider's listable voices (ids for kokoro, names for elevenlabs), one per line.
+# Discovered providers (piper/macos/sapi) enumerate at runtime and print nothing here.
+catalog_list_voices() {
+  local _p; _p="$(catalog_canonical_provider "${1:-}")" || return 1
+  case "$_p" in
+    soprano)
+      printf '%s\n' 'soprano-default'
+      ;;
+    piper)
+      : # (none — enumerated at runtime)
+      ;;
+    kokoro)
+      printf '%s\n' 'af_heart' 'af_alloy' 'af_aoede' 'af_bella' 'af_jessica' 'af_kore' 'af_nicole' 'af_nova' 'af_river' 'af_sarah' 'af_sky' 'am_adam' 'am_echo' 'am_eric' 'am_fenrir' 'am_liam' 'am_michael' 'am_onyx' 'am_puck' 'bf_alice' 'bf_emma' 'bf_isabella' 'bf_lily' 'bm_daniel' 'bm_fable' 'bm_george' 'bm_lewis' 'jf_alpha' 'jf_gongitsune' 'jf_nezumi' 'jf_tebukuro' 'jm_kumo' 'zf_xiaobei' 'zf_xiaoni' 'zf_xiaoxiao' 'zf_xiaoyi' 'zm_yunxi' 'zm_yunxia' 'zm_yunyang' 'ef_dora' 'em_alex' 'em_santa' 'ff_siwis' 'hf_alpha' 'hm_omega' 'if_sara' 'im_nicola' 'pf_dora' 'pm_alex' 'pm_santa' 'kf_alpha' 'km_hyunsu'
+      ;;
+    elevenlabs)
+      printf '%s\n' 'Sarah' 'Roger' 'Laura' 'Charlie' 'George' 'Callum' 'River' 'Harry' 'Liam' 'Alice' 'Matilda' 'Will' 'Jessica' 'Eric' 'Bella' 'Chris' 'Brian' 'Daniel' 'Lily' 'Adam' 'Bill'
+      ;;
+    macos)
+      : # (none — enumerated at runtime)
+      ;;
+    windows-sapi)
+      : # (none — enumerated at runtime)
+      ;;
+    windows-piper)
+      : # (none — enumerated at runtime)
+      ;;
+  esac
+}
+
+# Validate a voice for a provider. Echoes the canonical voice and returns 0 on
+# success; returns 1 (no output) on rejection. Mirrors validateVoice() in the JS SSOT.
+catalog_validate_voice() {
+  local _p _v _lc; _p="$(catalog_canonical_provider "${1:-}")" || return 1
+  _v="${2:-}"; _lc="$(_catalog_lc "$_v")"
+  case "$_p" in
+    kokoro)
+      case "$_lc" in
+        'af_heart'|'af_alloy'|'af_aoede'|'af_bella'|'af_jessica'|'af_kore'|'af_nicole'|'af_nova'|'af_river'|'af_sarah'|'af_sky'|'am_adam'|'am_echo'|'am_eric'|'am_fenrir'|'am_liam'|'am_michael'|'am_onyx'|'am_puck'|'bf_alice'|'bf_emma'|'bf_isabella'|'bf_lily'|'bm_daniel'|'bm_fable'|'bm_george'|'bm_lewis'|'jf_alpha'|'jf_gongitsune'|'jf_nezumi'|'jf_tebukuro'|'jm_kumo'|'zf_xiaobei'|'zf_xiaoni'|'zf_xiaoxiao'|'zf_xiaoyi'|'zm_yunxi'|'zm_yunxia'|'zm_yunyang'|'ef_dora'|'em_alex'|'em_santa'|'ff_siwis'|'hf_alpha'|'hm_omega'|'if_sara'|'im_nicola'|'pf_dora'|'pm_alex'|'pm_santa'|'kf_alpha'|'km_hyunsu')
+          printf '%s' "$_lc"; return 0 ;;
+      esac
+      return 1 ;;
+    elevenlabs)
+      case "$_lc" in
+        'sarah') printf '%s' 'EXAVITQu4vr4xnSDxMaL'; return 0 ;;
+        'roger') printf '%s' 'CwhRBWXzGAHq8TQ4Fs17'; return 0 ;;
+        'laura') printf '%s' 'FGY2WhTYpPnrIDTdsKH5'; return 0 ;;
+        'charlie') printf '%s' 'IKne3meq5aSn9XLyUdCD'; return 0 ;;
+        'george') printf '%s' 'JBFqnCBsd6RMkjVDRZzb'; return 0 ;;
+        'callum') printf '%s' 'N2lVS1w4EtoT3dr4eOWO'; return 0 ;;
+        'river') printf '%s' 'SAz9YHcvj6GT2YYXdXww'; return 0 ;;
+        'harry') printf '%s' 'SOYHLrjzK2X1ezoPC6cr'; return 0 ;;
+        'liam') printf '%s' 'TX3LPaxmHKxFdv7VOQHJ'; return 0 ;;
+        'alice') printf '%s' 'Xb7hH8MSUJpSbSDYk0k2'; return 0 ;;
+        'matilda') printf '%s' 'XrExE9yKIg1WjnnlVkGX'; return 0 ;;
+        'will') printf '%s' 'bIHbv24MWmeRgasZH58o'; return 0 ;;
+        'jessica') printf '%s' 'cgSgspJ2msm6clMCkdW9'; return 0 ;;
+        'eric') printf '%s' 'cjVigY5qzO86Huf0OWal'; return 0 ;;
+        'bella') printf '%s' 'hpp4J3VqNfWAUOO0d1Us'; return 0 ;;
+        'chris') printf '%s' 'iP95p4xoKVk53GoZ742B'; return 0 ;;
+        'brian') printf '%s' 'nPczCjzI2devNBz1zQrb'; return 0 ;;
+        'daniel') printf '%s' 'onwK4e9ZLuTAKqWW03F9'; return 0 ;;
+        'lily') printf '%s' 'pFZP5JQG7iQjIQuC4Bku'; return 0 ;;
+        'adam') printf '%s' 'pNInz6obpgDQGcFmaJgB'; return 0 ;;
+        'bill') printf '%s' 'pqHfZKP75CvOlQylNhV4'; return 0 ;;
+      esac
+      [[ "$_v" =~ ^[A-Za-z0-9]{20}$ ]] && { printf '%s' "$_v"; return 0; }
+      return 1 ;;
+    soprano)
+      case "$_lc" in
+        ''|soprano|soprano-default) printf '%s' 'soprano-default'; return 0 ;;
+      esac
+      return 1 ;;
+    piper|windows-piper)
+      if [[ "$_v" =~ ^[a-z]{2,3}_[A-Z]{2}- ]] || [[ "$_v" == *"::"* ]]; then
+        printf '%s' "$_v"; return 0
+      fi
+      return 1 ;;
+    macos|windows-sapi)
+      if [ -n "$_v" ]; then printf '%s' "$_v"; return 0; fi
+      [ "$_p" = windows-sapi ] && { printf '%s' ''; return 0; }
+      return 1 ;;
+  esac
+  return 1
+}

package/.claude/hooks/provider-commands.sh

@@ -44,6 +44,7 @@
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/provider-manager.sh"
 source "$SCRIPT_DIR/language-manager.sh"
+source "$SCRIPT_DIR/python-resolver.sh"
 
 COMMAND="${1:-help}"
 
@@ -101,7 +102,7 @@ provider_list() {
 
   # Check installation status of optional providers
   local kokoro_installed=false
-  python3 -c "import importlib.util,sys; sys.exit(0 if importlib.util.find_spec('kokoro') else 1)" 2>/dev/null && kokoro_installed=true
+  [[ -n "$PYTHON_BIN" ]] && "$PYTHON_BIN" -c "import importlib.util,sys; sys.exit(0 if importlib.util.find_spec('kokoro') else 1)" 2>/dev/null && kokoro_installed=true
 
   local elevenlabs_key_set=false
   if [[ -n "${ELEVENLABS_API_KEY:-}" ]]; then

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

@@ -73,6 +73,23 @@ get_provider_config_path() {
   echo "$provider_file"
 }
 
+# @function _load_provider_catalog
+# @intent Source the generated Provider Catalog (bash-3.2-safe SSOT accessors)
+# @why Single source of truth for per-provider defaults (AVI-S9.4) — mirrors the
+#      identical pattern in voice-manager.sh (AVI-S9.3). FAIL-SAFE: callers probe
+#      `type catalog_* >/dev/null 2>&1` and fall back to legacy hardcoded literals
+#      when the artifact is missing (installed-tree skew). Defaults never break.
+# @returns None (sources catalog_* functions into the current shell when present)
+# @sideeffects None (double-sourcing is guarded inside provider-catalog.sh)
+_load_provider_catalog() {
+  local _script_dir
+  _script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  if [[ -f "$_script_dir/provider-catalog.sh" ]]; then
+    # shellcheck source=/dev/null
+    source "$_script_dir/provider-catalog.sh" 2>/dev/null || true
+  fi
+}
+
 # @function get_active_provider
 # @intent Read currently active TTS provider from config file
 # @why Central function for determining which provider to use
@@ -187,12 +204,24 @@ migrate_voice_to_provider() {
     "en_US-danny-low:Alex"
   )
 
-  # Default voices by provider
-  local piper_default="en_US-lessac-medium"
-  local macos_default="Samantha"
-  local soprano_default="soprano-default"  # Single voice — no selection needed
-  local elevenlabs_default="Rachel"
-  local kokoro_default="af_heart"
+  # Default voices by provider — sourced from the generated Provider Catalog SSOT
+  # (AVI-S9.4, catalog_default_voice). FAIL-SAFE: legacy literals if the catalog
+  # artifact is missing (installed-tree skew) — mirrors AVI-S9.3's pattern.
+  _load_provider_catalog
+  local piper_default macos_default soprano_default elevenlabs_default kokoro_default
+  if type catalog_default_voice >/dev/null 2>&1; then
+    piper_default="$(catalog_default_voice piper)"
+    macos_default="$(catalog_default_voice macos)"
+    soprano_default="$(catalog_default_voice soprano)"  # Single voice — no selection needed
+    elevenlabs_default="$(catalog_default_voice elevenlabs)"
+    kokoro_default="$(catalog_default_voice kokoro)"
+  else
+    piper_default="en_US-lessac-medium"
+    macos_default="Samantha"
+    soprano_default="soprano-default"  # Single voice — no selection needed
+    elevenlabs_default="Sarah"
+    kokoro_default="af_heart"
+  fi
 
   # Single-voice providers: migration is straightforward
   case "$target_provider" in
@@ -214,7 +243,15 @@ migrate_voice_to_provider() {
     return 0
   fi
 
-  # If migrating FROM a single-voice provider, return default for target provider
+  # If migrating FROM a single-voice/fixed-shape provider, return default for target.
+  # NOTE ("Rachel" sentinel, AVI-S9.4): "Rachel" was ElevenLabs' hardcoded default
+  # before the 21-voice catalog trim (AVI-S8.1) — it is NOT a name-to-id match in
+  # today's catalog. This is READ-SIDE TOLERANCE ONLY (CLAUDE.md non-destructive
+  # rule): a user config that still says "Rachel" degrades gracefully to the
+  # target provider's default instead of erroring; we never rewrite the user's file.
+  if [[ "$current_voice" == "Rachel" ]]; then
+    echo "⚠️  '$current_voice' is a legacy ElevenLabs default no longer in the voice catalog; migrating to the $target_provider default." >&2
+  fi
   if [[ "$current_voice" == "soprano-default" || "$current_voice" == "Rachel" || "$current_voice" =~ ^[a-z]{2}_[a-z0-9_]+$ ]]; then
     case "$target_provider" in
       piper) echo "$piper_default" ;;
@@ -372,6 +409,7 @@ get_provider_script_path() {
 # @returns Echoes LLM name (e.g. "claude-code") or empty string if no remote routing configured
 # @exitcode 0=always
 detect_routing_llm() {
+  source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/python-resolver.sh"
   # Priority 1: AGENTVIBES_LLM_KEY env var (set during active TTS sessions)
   if [[ -n "${AGENTVIBES_LLM_KEY:-}" ]] && [[ "$AGENTVIBES_LLM_KEY" =~ ^llm:([a-zA-Z0-9][a-zA-Z0-9_-]*)$ ]]; then
     echo "${BASH_REMATCH[1]}"
@@ -380,9 +418,9 @@ detect_routing_llm() {
 
   # Priority 2: First mode=remote entry in transport-config.json
   local _transport_cfg="$HOME/.agentvibes/transport-config.json"
-  if [[ -f "$_transport_cfg" ]] && command -v python3 &>/dev/null; then
+  if [[ -f "$_transport_cfg" ]] && [[ -n "$PYTHON_BIN" ]]; then
     local _remote_llm
-    _remote_llm=$(AGENTVIBES_CFG="$_transport_cfg" python3 - <<'PYEOF'
+    _remote_llm=$(AGENTVIBES_CFG="$_transport_cfg" "$PYTHON_BIN" - <<'PYEOF'
 import json, os, sys
 try:
     d = json.load(open(os.environ['AGENTVIBES_CFG'], encoding='utf-8'))

package/.claude/hooks/python-resolver.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+#
+# File: .claude/hooks/python-resolver.sh
+#
+# AgentVibes - Text-to-Speech WITH personality for AI Assistants
+# Website: https://agentvibes.org
+# Repository: https://github.com/paulpreibisch/AgentVibes
+#
+# Licensed under the Apache License, Version 2.0
+#
+# @fileoverview Locate a WORKING Python 3 interpreter across platforms.
+# @context Windows git-bash frequently has NO `python3`/`python` on PATH even when
+#          Python is installed (the on-PATH WindowsApps entries are Microsoft Store
+#          execution-alias stubs that do not actually run). The old `command -v
+#          python3` guard therefore made hooks falsely report "not installed".
+# @architecture Sourced (not executed) by hooks; sets and exports $PYTHON_BIN.
+#          $PYTHON_BIN is empty when no usable interpreter exists. Callers should
+#          test `[[ -n "$PYTHON_BIN" ]]` instead of `command -v python3`.
+# @related play-tts.sh, play-tts-kokoro.sh, kokoro-installer.sh, provider-commands.sh
+#
+# Usage:
+#   source "$SCRIPT_DIR/python-resolver.sh"
+#   [[ -n "$PYTHON_BIN" ]] || { echo "No Python 3 found" >&2; exit 1; }
+#   "$PYTHON_BIN" my-script.py ...
+#
+# Override: set AGENTVIBES_PYTHON=/path/to/python to force a specific interpreter.
+
+# Fast path: resolve once per process. Several hooks source this file
+# transitively (e.g. play-tts.sh -> provider-manager.sh), so if PYTHON_BIN is
+# already exported and the file still exists, TRUST it without re-launching
+# Python — a fresh interpreter startup per source adds ~100ms of latency per
+# utterance for nothing. We only pay the exec-validation cost during genuine
+# discovery below, where the Windows Store stub actually needs rejecting.
+if [[ -n "${PYTHON_BIN:-}" && -f "$PYTHON_BIN" ]]; then
+  export PYTHON_BIN
+else
+  _AV_PY_CACHE="${HOME}/.claude/config/python-bin.txt"
+
+  # A candidate is valid only if it runs AND is Python 3. Running it filters out
+  # the Windows Store alias stub (which exits non-zero when given args); the
+  # version check rejects a lone python2 whose py3 syntax would crash at runtime.
+  _av_python_valid() {
+    [[ -n "${1:-}" ]] || return 1
+    "$1" -c 'import sys; sys.exit(0 if sys.version_info[0] >= 3 else 1)' >/dev/null 2>&1
+  }
+
+  _av_resolve_python() {
+    local cand resolved
+
+    # 1. Explicit override wins.
+    if [[ -n "${AGENTVIBES_PYTHON:-}" ]] && _av_python_valid "$AGENTVIBES_PYTHON"; then
+      printf '%s' "$AGENTVIBES_PYTHON"; return 0
+    fi
+
+    # 2. Previously-cached hit (strip a stray CR from a CRLF-edited cache file).
+    if [[ -f "$_AV_PY_CACHE" ]]; then
+      cand="$(head -1 "$_AV_PY_CACHE" 2>/dev/null | tr -d '\r' || true)"
+      if _av_python_valid "$cand"; then printf '%s' "$cand"; return 0; fi
+    fi
+
+    # 3. On PATH — but VALIDATE each (rejects the WindowsApps store stub).
+    for cand in python3 python python3.13 python3.12 python3.11 python3.10; do
+      resolved="$(command -v "$cand" 2>/dev/null || true)"
+      if [[ -n "$resolved" ]] && _av_python_valid "$resolved"; then
+        printf '%s' "$resolved"; return 0
+      fi
+    done
+
+    # 4. Windows `py` launcher — ask it for the real interpreter path. Python on
+    #    Windows emits CRLF even to a pipe, so strip the trailing CR or the exec
+    #    of "…python.exe\r" fails.
+    if command -v py >/dev/null 2>&1; then
+      cand="$(py -3 -c 'import sys; print(sys.executable)' 2>/dev/null | tr -d '\r' || true)"
+      if _av_python_valid "$cand"; then printf '%s' "$cand"; return 0; fi
+    fi
+
+    # 5. Known Windows install locations, newest version first. Built with
+    #    nullglob into an array so paths containing spaces ("C:\Program Files",
+    #    "C:\Users\John Smith\…") survive — an unquoted *variable* glob would
+    #    word-split them, which is exactly the case this resolver exists to fix.
+    #    This file is SOURCED, so nullglob is saved and restored to avoid leaking
+    #    the option into the calling hook.
+    local _av_restore_glob; _av_restore_glob="$(shopt -p nullglob 2>/dev/null || true)"
+    shopt -s nullglob 2>/dev/null || true
+    local -a _av_pys=(
+      "${LOCALAPPDATA:-$HOME/AppData/Local}/Programs/Python"/Python3*/python.exe
+      "$HOME/AppData/Local/Programs/Python"/Python3*/python.exe
+      /c/Python3*/python.exe
+      "/c/Program Files/Python3"*/python.exe
+      "/c/Program Files (x86)/Python3"*/python.exe
+    )
+    eval "${_av_restore_glob:-shopt -u nullglob}" 2>/dev/null || true
+    # Version-sort descending (Python312 before Python39 — a plain sort -r is
+    # lexical and would rank "39" above "312"); NUL-delimited so spacey paths
+    # stay intact. `sort -zrV` is GNU coreutils, which git-bash ships (this glob
+    # only ever matches under git-bash anyway).
+    if [[ ${#_av_pys[@]} -gt 0 ]]; then
+      while IFS= read -r -d '' cand; do
+        _av_python_valid "$cand" && { printf '%s' "$cand"; return 0; }
+      done < <(printf '%s\0' "${_av_pys[@]}" | sort -zrV 2>/dev/null)
+    fi
+
+    return 1
+  }
+
+  PYTHON_BIN="$(_av_resolve_python || true)"
+  export PYTHON_BIN
+
+  # Cache a fresh discovery (best-effort; never fatal). Only rewrite when it
+  # actually changed, to avoid needless disk writes on every hook invocation.
+  if [[ -n "$PYTHON_BIN" ]]; then
+    if [[ ! -f "$_AV_PY_CACHE" ]] || [[ "$(head -1 "$_AV_PY_CACHE" 2>/dev/null | tr -d '\r' || true)" != "$PYTHON_BIN" ]]; then
+      mkdir -p "$(dirname "$_AV_PY_CACHE")" 2>/dev/null || true
+      printf '%s\n' "$PYTHON_BIN" > "$_AV_PY_CACHE" 2>/dev/null || true
+    fi
+  fi
+fi

package/.claude/hooks/session-id.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+#
+# File: .claude/hooks/session-id.sh
+#
+# AgentVibes - Canonical routing session-id helper.
+#
+# The receiver MULTIPLEXES forwarded TTS from many sources (multiple local
+# projects + remote machines) keyed by a per-message identity. That identity
+# MUST be stable and correctly derived, or the receiver merges unrelated
+# sessions into one.
+#
+# This helper is the SINGLE source of truth for that routing id so every
+# forward path (e.g. play-tts-ssh-remote.sh SSH) derives it identically:
+#
+#   session id = basename(CLAUDE_PROJECT_DIR)   when CLAUDE_PROJECT_DIR is set
+#              = basename(<fallback dir>)        otherwise (passed dir, else PWD)
+#
+# It is intentionally NOT basename(install root): for a global install
+# (~/.claude/hooks) that basename collapses to the HOME dir name (e.g.
+# "administrator"), so every project on the machine would report the same id.
+#
+# NOTE: This is a PLAIN SLUG for routing — do NOT confuse it with
+# agentvibes-session-id.sh, which produces a human SPOKEN identity string.
+#
+# Usage:
+#   source "$(dirname "${BASH_SOURCE[0]}")/session-id.sh"
+#   SESSION_ID="$(av_session_id "$FALLBACK_PROJECT_DIR")"
+#
+# bash-3.2 safe (macOS default bash). Sourced by scripts already in strict mode;
+# defines a function only and does not alter shell options.
+#
+
+# av_session_id [fallback_dir]
+#   Prints the canonical routing session id (plain slug) to stdout.
+#   Prefers CLAUDE_PROJECT_DIR (the real user project injected via
+#   --project-dir); else the passed fallback dir; else PWD. Callers MUST pass a
+#   real project dir as the fallback — never the package/install root.
+av_session_id() {
+  local _dir="${CLAUDE_PROJECT_DIR:-}"
+  if [[ -z "$_dir" ]]; then
+    _dir="${1:-$PWD}"
+  fi
+  # Strip trailing slashes so basename of "/a/b/" is "b", not "".
+  while [[ "$_dir" == */ && "${#_dir}" -gt 1 ]]; do
+    _dir="${_dir%/}"
+  done
+  local _base
+  _base="$(basename "$_dir" 2>/dev/null || printf '%s' "$_dir")"
+  # Slugify: collapse anything outside [A-Za-z0-9._-] to '-' so the id is safe
+  # as a JSON string and a stable map key on the receiver.
+  _base="$(printf '%s' "$_base" | tr -c 'A-Za-z0-9._-' '-')"
+  # Trim leading/trailing dashes introduced by slugification.
+  _base="${_base#-}"; _base="${_base%-}"
+  [[ -z "$_base" ]] && _base="unknown"
+  printf '%s' "$_base"
+}

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

@@ -38,6 +38,45 @@ else
   _PROJECT_CLAUDE_DIR="$(dirname "$SCRIPT_DIR")"
 fi
 
+# ---------------------------------------------------------------------------
+# OPT-IN INJECTION GATE (Issue: global-install cacophony).
+#
+# Previously this hook injected the ~250-token TTS protocol into EVERY session
+# where AgentVibes was found on disk. A GLOBAL install therefore made every open
+# Claude session start speaking at once ("a cacophony of agents"). It also spent
+# tokens on idle sessions that never wanted audio. Injection is now OPT-IN.
+#
+# Two distinct markers, kept SEPARATE on purpose:
+#   * agentvibes-unmuted / agentvibes-muted — the user's runtime mute choice,
+#     also read by play-tts.sh, where a project `unmuted` OVERRIDES a global mute.
+#   * agentvibes-enabled — "this project opted into injection" (written by a
+#     project install). It does NOT override a global mute; it only turns the
+#     protocol injection on. This separation is why a project install can no
+#     longer silently defeat a user's `~/.agentvibes-muted` global kill-switch.
+#
+# Precedence (mirrors play-tts.sh so injection and audio agree):
+#   1. project agentvibes-unmuted  → inject   (explicit per-project ON)
+#   2. project agentvibes-muted    → silent
+#   3. global ~/.agentvibes-muted  → silent   (the global kill-switch)
+#   4. project agentvibes-enabled, OR global opt-in
+#      (~/.claude/agentvibes-enabled or ~/.claude/agentvibes-unmuted) → inject
+#   5. otherwise                   → silent   (opt-in default; zero tokens)
+if [[ -f "$_PROJECT_CLAUDE_DIR/agentvibes-unmuted" ]]; then
+  :   # explicit per-project enable — wins over a global mute, as in play-tts.sh
+elif [[ -f "$_PROJECT_CLAUDE_DIR/agentvibes-muted" ]]; then
+  exit 0
+elif [[ -f "$HOME/.agentvibes-muted" ]]; then
+  exit 0   # global kill-switch, no per-project override
+elif [[ -f "$_PROJECT_CLAUDE_DIR/agentvibes-enabled" \
+     || -f "$HOME/.claude/agentvibes-enabled" \
+     || -f "$HOME/.claude/agentvibes-unmuted" ]]; then
+  :   # opted in (project install marker, or a deliberate global opt-in)
+else
+  # Not enabled for this project → inject nothing (zero tokens).
+  # Enable for this project with:  /agent-vibes:unmute
+  exit 0
+fi
+
 # Build --project-dir flag to embed in TTS commands.
 # Sanitize: strip any embedded quotes that would break shell quoting.
 PROJECT_DIR_FLAG=""

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

@@ -37,7 +37,7 @@
 # @dependencies .claude/config/tts-speech-rate.txt, .claude/config/tts-target-speech-rate.txt
 # @entrypoints Called by /agent-vibes:set-speed slash command
 # @patterns Provider-agnostic speed config, legacy file migration, random tongue twisters for testing
-# @related play-tts.sh, play-tts-piper.sh, play-tts-macos.sh, learn-manager.sh
+# @related play-tts.sh, play-tts-piper.sh, play-tts-macos.sh
 #
 
 # Get script directory

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

@@ -32,7 +32,7 @@
 # @dependencies translator.py, language-manager.sh, .bmad/core/config.yaml (optional)
 # @entrypoints Called by /agent-vibes:translate commands and play-tts.sh
 # @patterns Config cascade - manual override > BMAD config > default (no translation)
-# @related translator.py, play-tts.sh, language-manager.sh, learn-manager.sh
+# @related translator.py, play-tts.sh, language-manager.sh
 
 # Only set strict mode when executed directly, not when sourced
 if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
@@ -40,6 +40,7 @@ if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
 fi
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/python-resolver.sh"
 
 # Use PWD for project dir when called from project context, fall back to script-relative
 if [[ -d "$PWD/.claude" ]]; then
@@ -173,7 +174,7 @@ translate_text() {
 
     # Call translator.py
     local translated
-    translated=$(python3 "$SCRIPT_DIR/translator.py" "$text" "$target" 2>/dev/null) || translated="$text"
+    translated=$("$PYTHON_BIN" "$SCRIPT_DIR/translator.py" "$text" "$target" 2>/dev/null) || translated="$text"
 
     echo "$translated"
 }

package/.claude/hooks/translator.py

@@ -32,7 +32,7 @@
 # @dependencies deep-translator, langdetect (pip install deep-translator langdetect)
 # @entrypoints CLI: python3 translator.py <text> <target_lang>, Library: from translator import translate
 # @patterns Command pattern - supports translate, detect, and batch operations
-# @related play-tts.sh, learn-manager.sh, language-manager.sh
+# @related play-tts.sh, language-manager.sh
 #
 
 """