feat(guard): a policy implementation may be Python, not only shell

[jothimani-rajendran]

What

A policy could only ship a guard as <policy_id>.sh. Three coupled limits made a Python implementation invisible end to end, each in a different file, each hiding the next:

Layer	Before	Effect on a .py guard
in_agent._guard_script	matched <id>.sh only	never discovered — so never wired, never packaged
guard_runner.run_guard	[bash, guard, *argv] hardcoded	handed to bash, would fail
eval.suites.Policy.guards	implementations/*.sh	eval suite silently demoted to tier 3, "no executable form"

Discovery now walks GUARD_SUFFIXES — shell first, so a policy shipping both is deterministic rather than filesystem-ordered. run_guard picks the interpreter from the suffix: this Python for .py, the existing bash probe otherwise. The "no usable bash" message becomes "no usable interpreter", because the condition it reports is no longer bash-specific.

Plugin packaging needed no change. All four packagers (claude, codex, copilot, cursor) already call _guard_script, so a Python guard now reaches plugin.json, the hooks file and the packaged scripts by exactly the path a shell one does. That was the point of fixing discovery rather than special-casing four emitters.

What this deliberately does not change

A guard still receives shlex.split(command) — it judges a shell command. Guards that need file content stay unavailable, and that is a separate change to the input contract, not a follow-up to this one:

• vendors.shell_matcher is the only matcher helper in the compiler, so every emitted PreToolUse hook matches shell tools.
• The adapters already extract content (tool_input.new_string, tool_input.edits[].new_string, …) and path for Write/Edit/MultiEdit/NotebookEdit, with evidence basis live-run — but nothing can emit a hook that would ever deliver those payloads. verify-mcp-allowlist states the consequence in its own manifest: "a file-write tool bypasses this guard."

So this PR makes Python guards first-class; it does not add a write-tool surface. No coverage claim moves: a Python guard installs the same surface at the same tier as a shell one, INSTALLED_SURFACES is language-agnostic, and --only matrix / --only mechanisms both pass.

Definition of done

• chock check → 0 errors, 0 warnings, 0 infos
• chock check --only matrix passes; no matrix change needed — behaviour tier is unchanged
• chock sync --repo . --check clean
• chock check --only verify clean
• Registry rescanned; no stale entries
• pytest -q green — 1136 passed, 6 skipped; new capability has both block and allow tests
• pytest acceptance/ … green — 21 passed (packaging and hook installation are touched)
• Existing artifacts migrated — none needed; every existing .sh policy is unaffected, and discovery still prefers .sh
• Touched manifests: none. No policy manifest changes, so no version bump or changelog entry applies
• ruff check . and ruff format --check . clean (262 files)

Also run, enumerated from ci.yml rather than from this checklist: --only mechanisms, --only index, --only conflicts, --only evals, --only validate --mode frontier-claude, --only validate --mode frontier-devin, and tools/check_literal_duplication.py (no repeated literals — ".py" appears in two modules because guard_runner is vendored standalone into adopters and cannot import from chock.compile).

Claims

• No surface is described as enforcing more than it installs. Nothing in docs/ or INSTALLED_SURFACES ties a guard's tier to its script language, so no published claim moves.

Break-and-restore

Each change was reverted on its own to prove a named test pins it, rather than reverting all three and watching the import fail:

revert discovery    -> caught by: test_discovery_finds_a_python_guard,
                                  test_the_plugin_packages_the_python_guard
revert interpreter  -> caught by: test_a_python_guard_blocks_and_allows
revert eval-glob    -> caught by: test_a_python_guard_makes_the_suite_deterministic

The generated-artifact ripple, stated because it reaches every adopter

guard_runner is embedded in all ten vendored adapters, so .chock/bin/*.py and the frozen runtime goldens move with it. test_runtime_goldens failed exactly as designed — "every adopter's next sync rewrites .chock/bin" — and was regenerated deliberately with CHOCK_REGEN_GOLDENS=1, then .chock/ re-synced with chock sync --repo .. Nothing hand-edited.

That is the one thing worth a reviewer's attention: this PR changes bytes in every adopter's vendored runtime. The functional delta is small and additive (a new find_interpreter, one substituted variable, one message), but it will show up as a rewrite on the next sync in every repo that has chock installed.

🤖 Generated with Claude Code

---

Generated by Claude Code