disk-hygiene: the destructive-operation guard has never launched — 73 recorded runs, all hook_non_blocking_error

[kyle-sexton]

The finding

disk-hygiene's destructive-operation guard has not run at all across the entire measured window.
Both comparators fail at launch, so every recorded invocation is a hook_non_blocking_error and no
permission decision is contributed:

• destructive_guard.py --mode engine-gate — all 16 recorded runs are
  hook_non_blocking_error, exitCode: 1, stderr:

  Failed to run: Plugin option "disk_hygiene_enabled" isn't set.
  

  This is config validation refusing to launch, before any process is spawned. It is also why the
  guard appeared to run in 2 ms — python3 -c 'pass' costs 396 ms on the measuring host, so 2 ms was
  never physically achievable for real work.

• destructive-guard.sh — all 57 recorded runs are hook_non_blocking_error, stderr:

  execvpe(/bin/bash) failed: No such file or directory
  

  The hook is being routed to WSL, which has no /bin/bash at that path.

Why it was invisible

A hook that fails to launch writes an error to the transcript and then gets out of the way. Nothing
surfaces "your destructive-operation guard has never made a decision", so the failure reads
identically to a guard that ran and approved. The 2 ms figure was even cited in a machine-health
decision (D-12) as evidence of a fast sibling guard — the opposite of what it meant.

Two things to fix, and they are separable

1. The launch failures themselves — the unset disk_hygiene_enabled plugin option, and the
   /bin/bash resolution on a WSL-routed host.
2. The silence. A PreToolUse guard that cannot launch should be loud, because the failure mode
   is that the guarded operation proceeds unguarded. Whatever shape that takes — a one-time session
   warning, a /doctor line, an observability counter — the property to restore is that "guard never
   ran" and "guard approved" do not look the same from outside.

Related

Refs #1403 — the guardrails PreToolUse fail-open, the same class of defect in a sibling plugin,
found in the same measurement pass. The two are independent fixes.

[kyle-sexton]

This was generated by AI during triage.

Classification: unclassified, fail-closed human-gated per the admission gate's own table.

Partially verified against origin/main: plugins/disk-hygiene/.claude-plugin/plugin.json does
declare disk_hygiene_enabled with a manifest "default": true, yet the issue reports the guard
failing at launch with Plugin option "disk_hygiene_enabled" isn't set. — a real mismatch between
declared default and observed runtime behavior worth investigating. The two scripts named in the
issue belong to two different plugins: destructive_guard.py --mode engine-gate is
disk-hygiene's own guard (confirmed wired via that plugin's hooks/hooks.json), but
destructive-guard.sh resolves to plugins/repo-hygiene/skills/clean/scripts/destructive-guard.sh
— a different plugin's legacy guard, not disk-hygiene's.

This item is priority: critical (a destructive-operation guard that has never once made a real
decision, across 73 combined runs, with no visible signal that it isn't running), spans two
plugins' worth of separable root causes (a disk-hygiene config-resolution bug, and a
repo-hygiene WSL/bash path-resolution bug), and its own "Two things to fix, and they are
separable" section explicitly leaves the second fix (making a launch failure loud) open-ended
across three named shapes — "a one-time session warning, a /doctor line, an observability
counter" — with no stated preference. Given the severity, the cross-plugin scope ambiguity (one
fix or two, and which plugin owns which half), and the open design choice on the visibility
mechanism, this needs an operator decision on scope before a brief can be written responsibly
rather than this lane guessing a split. Applying needs-human per the gate's fail-closed rule.

No further action needed from this lane; not re-triaging further.

[kyle-sexton]

This was generated by AI, delegated directly by the repository operator to resolve this blocker.

Scope decision: not split per plugin. Both named root causes are already fixed; this issue keeps
its second half — the silence. The one genuinely live defect is split out to #1423.

The record needs correcting first

I went back to the raw transcripts rather than trusting the issue's framing. Counting only genuine
harness records ("attachment":{"type":"hook_non_blocking_error", not prose that merely quotes the
error text) reproduces this issue's 16 / 57 split exactly — and both sets stop dead:

Guard	Records	Window	Fix	Merged
disk-hygiene destructive_guard.py --mode engine-gate	16	2026-07-23 → 2026-07-24T14:46:03Z	#1242 (0.9.0)	2026-07-24T08:12:09Z
repo-hygiene destructive-guard.sh	57	2026-07-22T13:54Z → 2026-07-22T15:26:09Z	#1006	2026-07-22T15:57:26Z

• All 16 disk-hygiene records carry the pre-0.9.0 command string
  … --disk-hygiene-enabled ${user_config.disk_hygiene_enabled}. Zero records of that form exist
  after the fix propagated. The ~6.5 h tail past the merge is install lag, not an unfixed bug — the
  local cache only moved to 0.9.x later; it now runs 0.9.1.
• All 57 repo-hygiene records are on 2026-07-22, ending 31 minutes before fix(repo-hygiene): destructive-guard fail-open on Windows — shell-form hook launch + jq fail-closed degraded mode #1006 merged.

So the title's "has never launched — 73 recorded runs" describes a window that closed. Recommend
retitling (see the note at the end).

repo-hygiene is verified working, not merely quiet

Its guard is skill-scoped (registered from SKILL.md frontmatter only while clean is invoked), so
"no errors since" would be equally consistent with nobody running the skill. Checked: the clean
skill loaded on 07-23, 07-24 and 07-25, and the CLEAN_GUARD_ACK=1 acknowledgement the guard
demands was exercised on 07-24 and 07-25. The guard is firing and blocking. No remaining work on
the repo-hygiene side — which is why a per-plugin split would have produced an empty ticket.

Root causes, confirmed

1. disk-hygiene — a bare ${user_config.disk_hygiene_enabled} in the hook's args. A declared
   manifest "default": true is not applied at hook-invocation time; the harness refuses to
   launch with Plugin option "disk_hygiene_enabled" isn't set. This is empirically established
   from the recorded stderr, not from documentation — the
   hooks reference (fetched 2026-07-25) documents
   ${user_config.*} substitution but is silent on whether a declared default fills an unset
   option, so treat the docs as not confirming it. Fixed by fix(disk-hygiene): resolve kill switch by reading user settings directly #1242 by dropping the token and
   reading the setting directly. A related variant also appears once in the record: the skill-scoped
   belt failing with Hook command references ${CLAUDE_PLUGIN_DATA} but only ${CLAUDE_PLUGIN_ROOT} is available for skill hooks — also already gone from the current frontmatter.
2. repo-hygiene — exec form resolved bash via PATH, hitting the Windows System32 WSL relay,
   which has no /bin/bash. Fixed by fix(repo-hygiene): destructive-guard fail-open on Windows — shell-form hook launch + jq fail-closed degraded mode #1006 with shell form plus shell: bash. Not a
   one-line interpreter path change; the interpreter had to stop being resolved via PATH at all.

What is actually still broken

One record, 2026-07-25T21:03:30Z, post-fix command form: the guard launched, ran 17 s, then
exited 1 with empty stderr — fail-open again, new shape. Split to #1423, because it is a
distinct defect with its own diagnosis and it is not described anywhere in this issue's body.

---

Agent Brief — make a guard that did not run visibly different from one that approved

Type

Observability / safety-property restoration. This is item 2 of this issue's own "Two things to fix",
now the whole of it.

Summary

Across the measured window a destructive-operation guard failed 73 times and nothing surfaced
it. It was found only because someone went looking. Two separate root causes in two plugins each
produced the same externally-silent outcome, and #1423 is a third instance already. The launch bugs
are fixed; the property that let them hide for days is not. Restore it: a guard that did not render
a verdict must be distinguishable, at the time it happens, from one that rendered allow.

Current behavior

A PreToolUse hook that fails to launch, or that dies after launching, is recorded by the harness
as a hook_non_blocking_error attachment in the transcript and is otherwise silent. Per the
hooks reference (fetched 2026-07-25), "Claude Code treats
exit code 1 as a non-blocking error and proceeds with the action" — so the guarded command runs.
The operator sees no warning. "Guard denied nothing because it approved" and "guard denied nothing
because it never ran" are the same observation from outside.

Desired behavior

When disk-hygiene's guard fails to launch or dies without a verdict, the operator gets a
user-visible warning in that session, without having to inspect transcripts.

Chosen mechanism — a one-time session warning via systemMessage

This is the decision the issue left open across three candidate shapes. Picking one:

Add a small, separate detector hook to disk-hygiene that reads transcript_path from its own
hook input, scans the current session's records for hook_non_blocking_error attachments whose
command names destructive_guard.py, and — at most once per session — emits
{"systemMessage": "..."} naming the guard, the failure count, and the stderr.

Both contract surfaces are confirmed in the
hooks reference (fetched 2026-07-25):

• transcript_path — "Path to conversation JSON" — is a common input field every hook receives.
• systemMessage — "Warning message shown to the user" — is a universal JSON output field,
  available to all hook events.

Why this shape and not the alternatives. A /doctor line and an observability counter both
require someone to go look, which is the failure mode being fixed. A launch self-probe (the shape
suggested by 0.9.3's python3 alias probe in setup check) only catches launch refusal — the
class that is already fixed — and would report "OK" for the live #1423 failure, where the guard
launched fine and then died. Reading the harness's own error attachments is the only cheap mechanism
that covers both classes, because the harness records both identically.

The detector must be a different process from the guard — a guard that cannot launch cannot
report that it did not launch. Keep the detector trivial (stdlib only, no imports from the guard) so
its own failure surface is near-zero. Note the documented caveat that the transcript "is written
asynchronously and may lag the in-memory conversation"; the detector therefore reports failures
from earlier in the session, which is sufficient — the goal is bounded-latency visibility, not
blocking the current call.

Acceptance criteria

1. A new detector hook ships in plugins/disk-hygiene/hooks/hooks.json, separate from the
   engine-gate guard, that reads transcript_path and scans for hook_non_blocking_error records
   naming destructive_guard.py.
2. On finding one or more, it emits a JSON object on stdout containing systemMessage with the
   guard name, the count, and the recorded stderr (truncated). It warns at most once per session.
3. The discriminating test: replaying a transcript containing the exact
   2026-07-25T21:03:30Z record from disk-hygiene: destructive guard exits 1 with empty stderr after 17s — a live fail-open distinct from #1242 #1423 (exit 1, empty stderr, durationMs: 17054) produces a
   warning. A mechanism that stays silent on that record does not satisfy this brief.
4. It also warns on the launch-refusal shape — a record whose stderr is
   Failed to run: Plugin option "…" isn't set. — using one of the 16 historical records as the
   fixture.
5. A clean session with no guard failures produces no systemMessage — no false positives.
6. The detector never blocks: it exits 0 and emits no permissionDecision, whatever it finds.
7. The detector cannot itself fail open silently in a way that matters: if it cannot read the
   transcript, it exits 0 quietly. It must never be the reason a tool call is denied.
8. Tests live in plugins/disk-hygiene/skills/clean/scripts/test_hygiene.py (or a sibling) with
   transcript fixtures for: the disk-hygiene: destructive guard exits 1 with empty stderr after 17s — a live fail-open distinct from #1242 #1423 shape, the launch-refusal shape, a clean session, an
   unreadable transcript_path, and the once-per-session cap.
9. plugins/disk-hygiene/CHANGELOG.md gains an entry and .claude-plugin/plugin.json is version-bumped.
10. README.md and skills/clean/reference/safety-model.md state that guard launch/runtime failures
    are surfaced, and state plainly what remains uncovered (see Out of scope).

Out of scope

• Fixing the disk-hygiene: destructive guard exits 1 with empty stderr after 17s — a live fail-open distinct from #1242 #1423 silent exit-1 defect itself — that is disk-hygiene: destructive guard exits 1 with empty stderr after 17s — a live fail-open distinct from #1242 #1423. This brief makes it visible; that
  one makes it not happen.
• repo-hygiene's guard — verified working. Generalizing the detector to other plugins' guards is a
  deliberate follow-up, not this ticket: the detector matches its own guard's command only.
• Retroactive scanning of past sessions, dashboards, or metric aggregation.
• Changing what the guard classifies as destructive, or the disk_hygiene_enabled kill-switch
  semantics.
• Making the harness itself loud about hook launch failures — upstream's call, not this repo's.

Note on this issue's metadata

The title is now falsified: the guard has launched, and the 73 runs describe a closed window.
Since this carries priority: critical, a title asserting something untrue is its own hazard.
Recommend retitling to something like "disk-hygiene: a guard that never ran is
indistinguishable from one that approved — make launch/runtime failures loud". I have not changed
it; that is the operator's call, as is whether priority: critical still fits now that the
fail-open window has closed and the remaining work is observability.

[kyle-sexton]

This was generated by AI, delegated directly by the repository operator to resolve this blocker.

Amendment to the brief above — acceptance criteria 2 and 3.

As written, those two criteria are satisfiable by a useless warning. The live #1423 record's stderr
is the generic harness string Failed with non-blocking status code: No stderr output — zero
diagnostic content. An implementer could emit "guard failed: No stderr output", pass both criteria,
and leave the operator no better off.

Amend criterion 2 to require the warning to carry exitCode and durationMs from the record,
in addition to the stderr:

2. On finding one or more, it emits a JSON object on stdout containing systemMessage with the
   guard name, the failure count, and — for the most recent failure — its exitCode,
   durationMs, and recorded stderr (truncated). It warns at most once per session.

Those two fields are what actually discriminate the failure classes, and they were what made the
two root causes on this issue separable in the first place:

• durationMs: 2, stderr Plugin option "…" isn't set. → refused to launch; config resolution.
• durationMs: 17054, empty stderr → launched, did work, died silently (disk-hygiene: destructive guard exits 1 with empty stderr after 17s — a live fail-open distinct from #1242 #1423).

Same exitCode: 1, same outward silence, completely different fixes. A warning that omits them
tells the operator something is wrong but not which thing, which is most of the diagnostic distance.

Criterion 3 is unchanged in intent but now inherits the stronger criterion 2: replaying the
2026-07-25T21:03:30Z record must produce a warning that states exitCode: 1 and
durationMs: 17054.

[kyle-sexton]

[kyle-sexton]

This was generated by AI during work-loop execution.

Claimed via the work-loop seam and executed per the operator's brief and its criteria-2/3 amendment
(both posted 2026-07-25T23:46-23:47Z). PR: #1465.

Implements the detector exactly as specified: a new Stop-event hook,
skills/clean/scripts/guard_launch_monitor.py, scans the session transcript for
hook_non_blocking_error records naming destructive_guard.py and emits one systemMessage per
session naming the guard, the failure count, and — for the most recent failure — its exitCode,
durationMs, and truncated stderr, exactly as the amendment requires. Verified against a fixture
shaped like the real #1423 record (exitCode: 1, durationMs: 17054) and, as a manual smoke test,
against a genuine local transcript record from this repo's own history (exitCode: 1,
durationMs: 11, the real config-refusal stderr) — both reproduce correctly in the rendered warning
text.

Registered on Stop, not PreToolUse/PostToolUse, specifically to avoid repeating this repo's own
D-12 incident (docs/adr/0004-...) — a per-tool-call hook cost class — while still catching a failure
promptly, since the guard runs synchronously before the guarded command and Stop fires once per turn.

Did not touch destructive_guard.py and did not re-solve #1423 (already fixed separately by the open,
unmerged #1449) — this PR is scoped to the visibility gap only, per the brief's explicit boundary.

Full details, the empirically-confirmed transcript schema, test coverage, and verification results are
in the PR body and commit.

[kyle-sexton]

Reopening: the guard is still dead, and this issue closing COMPLETED is part of why it survived.

The fix that closed this (#1504, shipped in 0.17.6) routed both wired hooks through hooks/run-python-hook.sh — but registered that launcher in exec form as "command": "bash" + args. Exec form is a bare PATH lookup, so on a Windows host where bash resolves to the WSL relay it reproduces the exact execvpe(/bin/bash) failed failure quoted in the original report. Reproduced verbatim today on a fresh host:

<3>WSL (31 - Relay) ERROR: CreateProcessCommon:818: execvpe(/bin/bash) failed: No such file or directory

So the /bin/bash resolution half of item 1 in this issue was never actually fixed — it moved from destructive-guard.sh to run-python-hook.sh. Fix in progress.