disk-hygiene: guard hook launches via bare `python` — fails to run (fail-open risk) on python3-only hosts

[kyle-sexton]

Summary (highest priority — potential fail-open of the security guard)

The disk-hygiene clean skill launches its PreToolUse safety guard via the unqualified
interpreter python:

• skills/clean/SKILL.md:12 — command: "python", args ["${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/destructive_guard.py"]

Stock macOS and many Linux distros ship only python3 (no python shim). If python is
unresolvable, the PreToolUse hook process cannot launch.

Two failure modes, both severe

1. Fail-open (worst case): if Claude Code treats a hook-launch failure as non-blocking, the
   destructive guard never runs — rm -rf, engine apply, etc. are no longer intercepted on the
   very POSIX hosts the safety model relies on. The guard's whole purpose is defeated silently.
2. Fail-closed: if hook-launch failure blocks, the plugin is entirely unusable (scan/preview/
   apply all denied) on those hosts.

Additionally, if a legacy python (2.x) resolves first, the guard crashes immediately on
from __future__, f-strings, and dict[str, object] annotations.

Note the irony: the guard discloses its own absolute sys.executable for the engine calls to use,
but the guard itself is bootstrapped by the unqualified python it warns against.

Suggested fix

• Launch the hook via a resolvable 3.11+ interpreter: prefer python3, or a tiny launcher that
  resolves a suitable interpreter and execs the guard.
• Confirm Claude Code's actual behavior on hook-launch failure (fail-open vs fail-closed) and, if
  fail-open, treat this as critical.
• Add a regression test / setup:check probe that the hook's interpreter actually resolves (see the
  companion setup:check issue).

Severity

HIGH (security) — a security guard that may not run at all on POSIX hosts.
Found via a deep source audit prompted by a real Windows session.

[kyle-sexton]

Claimed by work-2 lane (T5) at 2026-07-22T02:58:38Z. Even-A2 (operator-promoted into the 7/26 set per #627 re-baseline, 2026-07-21). Implementing the fail-open remediation: launch the disk-hygiene clean PreToolUse guard via a resolvable Python 3.11+ interpreter instead of bare python, plus a resolution probe. Branch: fix/380-disk-hygiene-guard-python3.

[kyle-sexton]

Decision needed: python3-only vs. multi-name hook interpreter

WIP fix is up as draft #936 (python → python3). Research surfaced a genuine, balanced cross-platform tradeoff that is a security-coverage-vs-UX-noise priority call, not a technical unknown — so parking rather than banking it.

Context established (evidence)

• Hook runs in exec form (args present) → command is resolved on PATH with no shell (hooks ref). So a .sh/launcher script cannot be the command on Windows ("requires command to resolve to a real executable such as a .exe"), and shell-form resolution would newly depend on Git Bash/PowerShell — launcher and shell-form are dead ends.
• Launch failure is fail-open: "Any other exit code is a non-blocking error for most hook events. … Execution continues." So the guard only enforces where its interpreter resolves.
• POSIX (macOS/most Linux): python3 resolves, bare python often absent → the current bug. Linux is the only host that runs the real engine deletion.
• Windows: uv- and Microsoft-Store installs provide python3.exe (verified on the dev machine: python3 → CPython 3.14.6). python.org-only installs expose python.exe/py but no python3.exe — there python3 fails to launch (or hits the App Execution Alias Store stub). Windows never runs engine deletion; its guard only raises the bar on the manual PowerShell deletion lane, which already requires explicit per-path human approval.

The question

python3-only fixes the critical POSIX/Linux fail-open but leaves python.org-only Windows fail-open (defense-in-depth on a human-gated lane). Multi-name closes that too. Which coverage/noise posture do we want?

Options

A — python3-only + honest caveat (RECOMMENDED). Single command: "python3". Fixes the high-stakes POSIX/Linux lane cleanly; works on uv/Store Windows. Caveats (in SKILL.md Gotchas + CHANGELOG, rule 6e) that on a host without a resolvable python3 the launch fails open, with the manual-handoff human approval + consumer permission policy as backstop, and setup:check reporting resolution.

• Downside: python.org-only Windows keeps a fail-open on the manual lane.
• Why recommended: minimal, no behavior change per call, cleanest everywhere the plugin is actually used; the residual is the lowest-stakes host/lane combination.

B — multi-name (python3 + python, two PreToolUse entries). At least one resolves on every host; closes the python.org-Windows gap and neutralizes the legacy-python-2.x crash (the py3 entry still runs the real guard; deny-precedence means any entry's deny/exit-2 blocks).

• Downside: on hosts where both resolve (e.g. this dev machine) the guard double-runs every Bash/PowerShell call during a clean session (the Bash lane is deny-by-default and emits allow for scan/preview — functionally harmless but wasteful and can double the ask/allow UI); on python.org-Windows the failing python3 entry emits a <hook> hook error notice per command during clean sessions (per-call, confirmed by the exit-code semantics above).
• Why not default: real per-command UX noise + double execution to cover one low-stakes, human-gated Windows config — but a maintainer prioritizing "a security guard must never fail open" may accept the noise. Your posture call.

C — do nothing / keep python. Rejected: leaves the critical POSIX/Linux fail-open, which is the whole issue.

Notes for whoever implements the chosen option

• If B: the added regression test (test_skill_hook_interpreter_is_python3_and_resolves) must be widened to accept either entry, and its skip clause reworked — on Windows-with-App-Execution-Alias shutil.which("python3") returns a non-None stub path, so the current runtime half would fail (not skip) there; the docstring's "skips where no python3 exists at all" is inaccurate for that host and should be corrected regardless of A/B.
• Watch portability-lint CI (not run locally) for any opinion on hook command values.

RECOMMENDED: A. Labeling status: needs-decision.

[kyle-sexton]

DECISION: Option A (python3-only) — resolved 2026-07-22T03:39:31Z

Made under the operator's Human-Out-Of-Loop directive (2026-07-22) via independent Opus consensus, not a human park:

• Implementer (opus) recommended A after establishing launcher/shell-form are infeasible for an exec-form hook (primary-source verified).
• Independent reviewer (fresh-context opus, producer≠critic) ruled A: A fully closes the fail-open on every automated-deletion lane (Linux/macOS/uv+Store Windows); B's only gain is a defense-in-depth layer behind an existing per-path human gate on the lowest-stakes host (python.org-only Windows manual lane), bought at a recurring per-command double-run + error-notice cost borne by all users — worst on the high-stakes Linux lane. Fail-open status: SATISFIED-BY-A (A converts a silent bypass into a visible, setup:check-audited residual; not a deferral).

Residual (accepted, documented): python.org-only Windows leaves the manual PowerShell lane's defense-in-depth guard off — acceptable because that lane still requires explicit per-path human approval and setup:check surfaces the non-resolution. This will be caveated in SKILL.md Gotchas + CHANGELOG per rule 6e.

Proceeding on PR #936 (draft). Clearing status: needs-decision.