fix(hooks): bake absolute interpreter paths into generated hooks

[ikroal]

Summary

Generated git hooks (5 stages) and agent hooks (cursor, opencode)
previously called ac-guard run / python3 -m ac_guard.action_guard
directly, requiring those commands on $PATH. In typical Python
projects ac-guard lives only in .venv/bin/, so callers that don't
activate the venv (Claude Code's PreToolUse hook, generic CI runners,
IDEs that don't auto-source venv) hit command not found and the
hook silently broke the workflow.

Fix: at install time, bake the absolute path of ac-guard and
python3 into the generated hook scripts. Hooks then exec these
absolute paths with zero runtime lookup or PATH dependency.

This was self-discovered while running git commit from inside
Claude Code on this very repo — Claude Code's shell doesn't
auto-source the venv, so the existing .git/hooks/pre-commit
threw ac-guard: command not found.

Why this is safe

Hook files are not committed (.gitignore / .git/hooks/) — they're
regenerated by ac-guard install on every machine. venv changes
always coincide with reinstalling ac-guard (the package itself lives
in the venv), which the user already follows with ac-guard install
or update. Therefore baked paths cannot become stale relative to
the venv.

Coverage

• generator/core.py: new _resolve_ac_guard_executable() — probe
  Path(sys.executable).parent / "ac-guard" → shutil.which fallback
  → raise GeneratorError. Refusing to bake a bogus path beats
  silently producing a broken hook.
• 5 git hook templates use exec "{{ ac_guard_executable }}".
• cursor.j2 and opencode.j2 use the existing python_executable
  context already injected by adapters/_render.py:101 for
  claude_code.j2 — single source of truth.
• claude_code.j2 unchanged (its os.execv-to-baked-sys.executable
  fallback already solves this for Python hooks).
• cli/install.py: install_command and update_command both print
  Hooks linked to: <abs path> so users can see which install the
  hooks point at — important when both global and venv installs exist.
• update_command automatically picks up path changes because it
  re-runs the same _run_generator_pipeline as install (no
  update-specific code needed).

Test plan

• uv run pytest tests/ — 1214/1214 green (was 1205 before; +9
  from new tests)
• uv run lint-imports — both contracts kept
• uv run pre-commit run --all-files — all hooks pass
• New core regression tests/integration/test_hook_venv_fallback.py:
  • pre-commit hook executes with PATH=/usr/bin:/bin
  • cursor hook executes with the same stripped PATH
  • opencode TS plugin embeds an absolute python path constant
• New unit tests TestResolveAcGuardExecutable: fast path,
  PATH fallback, and the unresolvable→GeneratorError contract.
• Real-world dogfood: ran ac-guard install --agent claude-code then PATH=/usr/bin:/bin .git/hooks/pre-commit —
  Stage: pre-commit — PASSED, exit 0.

Plan

.claude/plans/action-guard-melodic-backus.md
in the local working tree (not committed; the file lives outside the
repo under ~/.claude/plans/).

🤖 Generated with Claude Code