Start a plugin's runtime through the shipped launcher, not a bare python3

[jothimani-rajendran]

What

The repo route got a portable launcher in #172, but the plugin tier did not. Every plugin package (claude, cursor, codex, copilot, devin) still ran its runtime with a bare python3 "<plugin root>/scripts/<agent>.py" …. On Windows python3 is often missing, or is the Microsoft Store stub, which exists and exits 9009. The hook then failed to start, Claude Code treated that as a non-blocking error, and the command ran. The plugin descriptions admitted this and told users to disable the Store alias.

Now each package ships scripts/launch.sh (the same launcher as the repo route) beside its runtime, and its hook runs:

git -c "alias.chock-sh=!sh" chock-sh "<root>/scripts/launch.sh" "<root>/scripts/<agent>.py" --guard|--gate "<root>/scripts/…"

• The alias carries only sh, with no path, $ or quotes. git supplies a POSIX sh under bash, PowerShell and cmd.exe alike, and it works outside a git repository too.
• The client expands its plugin-root token (${CLAUDE_PLUGIN_ROOT}, ${CURSOR_PLUGIN_ROOT}, ${PLUGIN_ROOT}, $DEVIN_PLUGIN_ROOT, Copilot's "$r") in the arguments exactly as it did for python3 "<path>".
• The launcher starts the first of python3, python and py that actually runs Python 3.11+, skipping the Store stub, or refuses with exit 2 and a fix-it message.

Plugin postures and the catalog page now say the hook needs git and a Python 3.11+, and what happens without each. Claims stay per client:

• Claude Code: refuses (exit 2) with no working Python.
• Cursor, Codex and Devin: only the exit code is stated.
• Without git: fail-open clients still allow silently.

Definition of done

• chock check → 0 failures
• chock check --only matrix passes (part of chock check)
• chock sync --repo . --check clean
• chock check --only verify clean
• Registry rescanned; no stale entries
• pytest -q green (1599 passed, 3 skipped); new checks have attack and ordinary-data tests. tests/test_plugin_launcher.py builds the real block-destructive-commands Claude plugin and runs its hook as Claude Code would, from a non-repo directory:
  • With a python3 stub that exits 9009 ahead of a working python, the guard still denies rm -rf /.
  • With no working Python, the hook exits 2 with the fix-it message.
  • All three new tests fail on the old builders.
• Acceptance suite green (21 passed)
• Existing artifacts migrated — chock ships no built plugins; chock-catalog's plugin trees regenerate on its next adoption
• Changelog entry under Unreleased
• ruff check . and ruff format --check . clean

Claims

• No surface is described as enforcing more than it installs. The postures were narrowed where they were claiming too much, and docs/cli-reference.md now names git, not python3, as what the codex and cursor packages fail open without.

Not verified here: how each client expands its plugin-root token on Windows. That behaviour is unchanged, since only python3 was replaced. Next, re-adopt chock-catalog after this is released, then run kit.py auto --route plugin on Windows.

🤖 Generated with Claude Code

https://claude.ai/code/session_016DapRw9Ce9z6jRd11uiuyu

---

Generated by Claude Code