Summary
Every audio-hooks invocation crashes at import time with NameError: name 'Tuple' is not defined. The bug is present in both v5.0.3 and v5.1.0 (latest release). Any user on a Python version that does not lazily evaluate annotations (i.e. without from __future__ import annotations) is fully blocked — no subcommand runs.
Repro
Fresh plugin install on Windows 11 / Python 3.12 (likely every platform with CPython ≥ 3.9 that evaluates annotations eagerly, which is the default):
$ audio-hooks diagnose
Traceback (most recent call last):
File ".../bin/audio-hooks.py", line 86, in <module>
HR = _import_hook_runner()
File ".../bin/audio-hooks.py", line 80, in _import_hook_runner
import hook_runner
File ".../hooks/hook_runner.py", line 765, in <module>
SYNTHETIC_EVENT_MAP: Dict[str, Tuple[str, Optional[str]]] = {
^^^^^
NameError: name 'Tuple' is not defined. Did you mean: 'tuple'?Same failure for audio-hooks test all, status, version, etc. — the runner can't even import.
Root cause
hooks/hook_runner.py line 30:
from typing import Optional, Dict, Any, List
But Tuple is used on:
- Line 765 — module-level annotation
Dict[str, Tuple[str, Optional[str]]]
- Line 802 — function signature
-> Tuple[str, Optional[str], Optional[str]]
Because these are module-level (not inside a function), Python evaluates them at import time and crashes before any subcommand dispatch.
Fix
One-line patch to line 30:
-from typing import Optional, Dict, Any, List
+from typing import Optional, Dict, Any, List, Tuple
Verified locally — audio-hooks diagnose and audio-hooks test all work after this change.
Notes
- Confirmed present at HEAD of
main (checked via gh api repos/ChanMeng666/claude-code-audio-hooks/contents/hooks/hook_runner.py?ref=v5.1.0).
- Alternative fix: add
from __future__ import annotations at the top of the file, which makes all annotations strings and sidesteps the issue — but the explicit import is simpler.
- Happy to send a PR if useful.
Summary
Every
audio-hooksinvocation crashes at import time withNameError: name 'Tuple' is not defined. The bug is present in both v5.0.3 and v5.1.0 (latest release). Any user on a Python version that does not lazily evaluate annotations (i.e. withoutfrom __future__ import annotations) is fully blocked — no subcommand runs.Repro
Fresh plugin install on Windows 11 / Python 3.12 (likely every platform with CPython ≥ 3.9 that evaluates annotations eagerly, which is the default):
Same failure for
audio-hooks test all,status,version, etc. — the runner can't even import.Root cause
hooks/hook_runner.pyline 30:But
Tupleis used on:Dict[str, Tuple[str, Optional[str]]]-> Tuple[str, Optional[str], Optional[str]]Because these are module-level (not inside a function), Python evaluates them at import time and crashes before any subcommand dispatch.
Fix
One-line patch to line 30:
Verified locally —
audio-hooks diagnoseandaudio-hooks test allwork after this change.Notes
main(checked viagh api repos/ChanMeng666/claude-code-audio-hooks/contents/hooks/hook_runner.py?ref=v5.1.0).from __future__ import annotationsat the top of the file, which makes all annotations strings and sidesteps the issue — but the explicit import is simpler.