Fix/claude code hook python3 fallback

[jessburnett]

Title

fix: fall back python3 -> python -> graceful skip in SessionStart hook

Summary

Add a small POSIX wrapper and point the SessionStart hook at it so the hook first tries python3, falls back to python, and otherwise exits 0 with a benign skip message. This prevents a SyntaxError crash on systems where bare python resolves to Python 2.

Problem

• The Hook: claude-code/hooks/hooks.json invoked capture.py directly with a bare "python":
  "command": "python \"${CLAUDE_PLUGIN_ROOT}/engine/capture.py\" hook"
• On machines where the unqualified python resolves to Python 2, capture.py (which uses PEP 3107 annotations) raises a SyntaxError (capture.py:54) and crashes the SessionStart hook.
• This crash was reproduced locally: running the original command under a python→python2 alias produced the SyntaxError at line 54, matching the user report.

Root cause

• The hook used an unqualified "python" executable name. PEP 394 does not guarantee that "python" maps to Python 3; many systems still use "python" for Python 2 or have differing PATH/aliases.
• Prior hardening (fix(claude-code): make install work + hook never crashes the session agentrust-io/integrations#39) fixed many crash vectors for SessionStart but did not address interpreter resolution.

Fix / Changes

• Added new executable wrapper script: claude-code/hooks/session-start.sh
  • Behavior:
    1. If python3 is available, exec python3 "${CLAUDE_PLUGIN_ROOT}/engine/capture.py" hook
    2. Else if python is available, exec python "${CLAUDE_PLUGIN_ROOT}/engine/capture.py" hook
    3. Else print JSON: {"continue":true,"systemMessage":"AgenTrust: skipped the integrity check because Python is unavailable."} and exit 0
• Updated claude-code/hooks/hooks.json to invoke the wrapper:

  -            "command": "python \"${CLAUDE_PLUGIN_ROOT}/engine/capture.py\" hook",
  +            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh\"",

• Files changed (local branch fix/claude-code-hook-python3-fallback):
  • M claude-code/hooks/hooks.json
  • A claude-code/hooks/session-start.sh (executable)

Testing

• Local manual checks run in the repository:
  • With CLAUDE_PLUGIN_ROOT set, wrapper executed via python3 and returned valid SessionStart JSON and exit 0:

    CLAUDE_PLUGIN_ROOT="$(pwd)/claude-code" sh claude-code/hooks/session-start.sh
    → {"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"AgenTrust: agent composition unchanged ..."}}
    

  • Hiding both python3 and python on PATH (test harness) produced the graceful skip JSON and exit 0.
  • Attempt to run wrapper without CLAUDE_PLUGIN_ROOT set produced the expected file-not-found exit but demonstrates path usage; with CLAUDE_PLUGIN_ROOT set it exercises the real execution path.
• CI: no engine logic changed; existing CI runs on Python 3 (matrix 3.9/3.11/3.13 etc). This change is a compatibility/infra fix and should not affect tests; nonetheless run the claude-code tests in CI as usual.

How to reproduce locally

• Reproduce the crash (before change):
  • Ensure your python resolves to Python 2 (or use a PATH that points python to a py2 binary)
  • Run: CLAUDE_PLUGIN_ROOT="$(pwd)/claude-code" sh -c 'python "${CLAUDE_PLUGIN_ROOT}/engine/capture.py" hook'
  • Expect: SyntaxError at capture.py:54
• After applying this patch locally:
  • CLAUDE_PLUGIN_ROOT="$(pwd)/claude-code" sh claude-code/hooks/session-start.sh
  • Expect: valid JSON output and exit 0 (with python3) or graceful skip JSON if no python available

Rollout / Migration

• To update local installs (maintainers / users who use the cached plugin):
  • Copy the updated hooks into the local plugin cache (example path on your machine):

    cp claude-code/hooks/hooks.json ~/.claude/plugins/cache/agentrust-io/agentrust-claude-code/0.2.0/hooks/hooks.json
    cp claude-code/hooks/session-start.sh ~/.claude/plugins/cache/agentrust-io/agentrust-claude-code/0.2.0/hooks/session-start.sh
    chmod +x ~/.claude/plugins/cache/agentrust-io/agentrust-claude-code/0.2.0/hooks/session-start.sh
    

  • Or, reinstall the plugin from the updated marketplace clone so the cache is rebuilt.
• No user-facing configuration changes needed beyond the cache update or reinstall.

Backwards compatibility & Risks

• Backwards-compatible: systems with python3 continue to run python3.
• Systems with only python (no python3) will continue to run python (fallback).
• Systems with neither will receive a benign skip message and the session will continue; this is intentional to avoid crashing the host CLAUDE session.
• Risk: If someone expects the integrity check to always run, systems without any Python interpreter will skip the check — documented in rollout/migration.

Security & Privacy

• No network calls introduced. The wrapper only chooses which local Python to exec.
• No sensitive data is logged or transmitted by this change.

Related issues / PRs

• Root cause originates from initial hook commit (9d93102) and was not addressed by fix(claude-code): make install work + hook never crashes the session agentrust-io/integrations#39 (which hardened other crash vectors).

Reviewer checklist

• Title follows repo convention — matches type(scope): summary used across recent history (fix(claude-code): make install work + hook never crashes the session agentrust-io/integrations#39, ci(claude-code): run the plugin test suite in CI agentrust-io/integrations#42, release(claude-code): v0.2.0 (launch-ready) agentrust-io/integrations#43, docs(claude-code): add PRIVACY.md agentrust-io/integrations#44)
• Problem and root cause explained clearly — §Problem/§Root cause above, git-blamed to initial commit 9d93102, confirmed untouched by fix(claude-code): make install work + hook never crashes the session agentrust-io/integrations#39
• Tests / reproduction instructions provided — §Testing + §How to reproduce locally, both run and their actual output pasted in
• CI passes on merge — not checked: branch not pushed, no CI run has happened yet. This ticks only once GitHub Actions runs green on the PR itself
• Rollout steps documented — §Rollout / Migration above

Co-authors / Acknowledgements

• Discovered and triaged by Jessica Burnett (local repo and tests) with Claude.
• Mirror pattern implemented to match plugins/agentrust-codex/scripts/session-start.sh.