disk-hygiene: kill switch (disk_hygiene_enabled) cannot reach a skill-frontmatter guard hook — audit-only degrades to prompt-gated

[kyle-sexton]

Summary

The disk-hygiene clean skill's disk_hygiene_enabled userConfig kill switch (false = audit-only
mode, which should deny every deletion lane) cannot be delivered to the skill-frontmatter guard
hook by any channel, so the guard defaults to enabled and audit-only mode degrades from
deny-outright to human-prompt-gated.

Surfaced while fixing #983 (the guard's fail-open on the ${CLAUDE_PLUGIN_DATA} skill-hook launch
refusal, PR #1014). That PR removes the un-launchable ${user_config.*} token from the hook args to
guarantee the guard launches; this issue tracks the capability that removal gives up.

Why no channel reaches the guard

A skill-frontmatter hook has only two ways to receive a userConfig value, and neither works:

1. ${user_config.disk_hygiene_enabled} arg substitution — Claude Code substitutes only
   ${CLAUDE_PLUGIN_ROOT} into skill-hook args (${CLAUDE_PLUGIN_DATA} is plugin-only and refuses
   the launch; ${user_config.*} is, on the evidence, not substituted for skill hooks). Passing it
   would reintroduce the disk-hygiene: guard hook fails to launch on skill-frontmatter hooks referencing ${CLAUDE_PLUGIN_DATA} — live fail-open on 0.4.6 #983 launch-refusal fail-open.
2. CLAUDE_PLUGIN_OPTION_DISK_HYGIENE_ENABLED environment variable — not injected into a
   skill-frontmatter hook's process environment (the disk-hygiene: skill-frontmatter guard reads CLAUDE_PLUGIN_DATA from env but never receives it -> engine lane fails closed on all platforms #376 finding for CLAUDE_PLUGIN_DATA; the
   CLAUDE_PLUGIN_OPTION_* class is likewise absent).

Impact

• Not a regression: on 0.4.6 the hook did not launch at all (disk-hygiene: guard hook fails to launch on skill-frontmatter hooks referencing ${CLAUDE_PLUGIN_DATA} — live fail-open on 0.4.6 #983), so the kill switch never
  functioned there either.
• Fails safe: the guard stays active and forces a human ask prompt before every mutation; the
  model also self-enforces audit-only because the skill body substitution does surface the
  configured value to the model. What is lost is the guard's independent deny-outright enforcement
  in audit-only mode.

Candidate resolutions (needs a design pass)

• Platform: Claude Code adds ${user_config.*} substitution (or CLAUDE_PLUGIN_OPTION_* env
  injection) for skill-frontmatter hooks. Cleanest, but not in the plugin's control.
• Plugin-scoped delivery: a plugin-level hooks.json SessionStart hook (plugin hooks do get
  ${user_config.*}) writes the resolved value to a file under ${CLAUDE_PLUGIN_DATA} that the skill
  guard reads. Works today but adds a per-session component and a file-trust surface — evaluate
  before building.

References

• PR fix(disk-hygiene): stop guard hook fail-open on skill-hook data-root token #1014 / disk-hygiene: guard hook fails to launch on skill-frontmatter hooks referencing ${CLAUDE_PLUGIN_DATA} — live fail-open on 0.4.6 #983 — the fail-open fix that surfaced this.
• disk-hygiene: skill-frontmatter guard reads CLAUDE_PLUGIN_DATA from env but never receives it -> engine lane fails closed on all platforms #376 — skill-frontmatter hooks do not receive CLAUDE_PLUGIN_DATA in env.
• https://code.claude.com/docs/en/plugins-reference (User configuration, Persistent data directory)
• https://code.claude.com/docs/en/hooks (Hooks in skills and agents)

[kyle-sexton]

This was generated by AI during triage.

Triage plan — #1019

Problem restatement

The clean skill's disk_hygiene_enabled kill switch, when false, should make the PreToolUse guard deny the apply lane outright (audit-only), but the guard has no channel to receive that userConfig value in a skill-frontmatter hook, so it defaults to enabled and the apply lane degrades from deny to a human ask prompt. This is fail-safe (still human-gated, and the skill body's ${user_config.*} substitution lets the model self-enforce) but loses the guard's independent deny-outright enforcement.

Scope check — what the kill switch actually controls in the guard

The kill switch's entire effect in destructive_guard.py is one branch: apply → deny (disabled) vs ask (enabled) — see main() lines 344/355–368. scan/preview always allow regardless; PowerShell mutation spellings always ask regardless; and apply already requires an exact canonical shape plus a 24-hex --approval-token plus a human ask. So the lost property is precisely "deny vs ask on an already heavily-gated apply." Real, but bounded — not a silent-deletion path.

What I verified empirically (and what I could not)

The load-bearing premise is unverified — and the docs arguably claim the opposite. This issue only exists if CLAUDE_PLUGIN_OPTION_DISK_HYGIENE_ENABLED does not reach a skill-frontmatter hook's process env. That is an analogy to #376's finding for CLAUDE_PLUGIN_DATA (verified absent from a skill-hook env on 2.1.215) — never verified for the CLAUDE_PLUGIN_OPTION_* var itself. Against it:

• plugins-reference, User configuration: "All values are exported to hook processes as CLAUDE_PLUGIN_OPTION_<KEY> environment variables" and the documented alternative for shell-form rejection is "Use exec form with args, or read CLAUDE_PLUGIN_OPTION_<KEY> from the hook's environment." No skill-hook carve-out. The guard is exec form and already reads that exact var (guard.py:344). Per the docs alone, it should already work.
• hooks doc, "Hooks in skills and agents": silent on both ${...} substitution and env injection for skill-scoped hooks — it only asserts format parity. ${user_config.*} substitution is documented only for "Plugin hooks" ("Plugin hooks additionally substitute ${user_config.*} values, in exec form only"), which supports the arg-substitution half of the gap but says nothing about the env var.
• PR fix(disk-hygiene): stop guard hook fail-open on skill-hook data-root token #1014's own open-question section already downgrades even the CLAUDE_PLUGIN_DATA skill-hook finding to "unconfirmed on current Claude Code."

I cannot run the live test from triage (needs a plugin-installed session echoing the skill hook's env). First action must be to verify the premise: install the plugin, set disk_hygiene_enabled=false, and confirm whether the guard process sees CLAUDE_PLUGIN_OPTION_DISK_HYGIENE_ENABLED=false. If it does, there is no bug to fix beyond a one-line default and a test — the whole design question below evaporates.

Prior-art findings

• No prior art for option 2 in this repo. Zero SessionStart hooks in any hooks.json; zero user_config-in-hooks.json; nothing that writes a resolved userConfig value to a ${CLAUDE_PLUGIN_DATA} file for another hook to read. Option 2 would be a novel per-session mechanism here.
• Positive control for plugin-level delivery: the format plugins (bash-format, etc.) read CLAUDE_PLUGIN_OPTION_<NAME>_ENABLED via hook::check_enabled in their plugin-level hooks.json hooks. This confirms the injection machinery exists and works for plugin hooks — sharpening the open fact to "does it reach skill-frontmatter hooks."
• Platform precedent for the config-file shape: plugins-reference tells monitor authors (which the docs do say don't receive CLAUDE_PLUGIN_OPTION_*) to "read the value from a config file it owns." That is option 2's shape, blessed for the monitor case — but a monitor's trust context differs from a security guard's (see below).

The security flaw in option 2 (the crux)

A file under ${CLAUDE_PLUGIN_DATA} is model-writable — the engine already writes runs/ there, and the Write tool is not even matched by this Bash/PowerShell PreToolUse hook. The guard's whole purpose is enforcement the model cannot forge. Against the guard's actual adversary (an injected or confused model), whatever can flip the state file can also drive the apply. So option 2 does not restore independent deny-outright enforcement — it only helps an honest model, which is no stronger than the skill-body self-enforcement that already exists. There is no OS privilege boundary between the SessionStart hook and the model's tools (same user), so no writable location gives a real trust boundary. A stale/missing file (skill invoked before SessionStart fires, failed non-blocking launch per #983, or another session's file) would fail open to today's ask-gated behavior — i.e. reproduce the exact documented gap.

Recommendation and routing — needs-human

This is not a T2 single-fork-with-vetoable-default, for two independent reasons:

1. The premise is unverified, and the docs point the other way. Defaulting a security design on top of that is the CRITICAL: git guards fail open on chained inline aliases — one-level re-expansion drops command-line -c/--config-env (case C + config-env H1/H2) #964/fix(guardrails): distinguish --config-env from -c/--config in shared git parser #903 defect class ("guard fails to enforce as designed" gets real care, not a rubber stamp).
2. Even granting the premise, the resolution is a genuine threat-model call, not a cosmetic veto — and option 2 as literally described does not achieve its stated goal.

The specific fork a maintainer must own: Is this guard meant to enforce the kill switch independently of model cooperation?

• If yes (independent authority): a model-writable ${CLAUDE_PLUGIN_DATA} file cannot deliver it — only the platform fix (${user_config.*} substitution or CLAUDE_PLUGIN_OPTION_* injection for skill hooks) can. Then do not build option 2; petition the platform and keep the documented fail-safe gap in the interim.
• If no (defense-in-depth against an honest-but-mistaken model): option 2 adds a real code-level deny the model won't spontaneously bypass, and is worth building despite being forgeable — accepting a novel per-session component and the file-trust surface.

My own lean, offered for the maintainer to weigh, not to default: verify the premise first; if the env var already reaches the skill hook, close as a one-line default fix; if it truly doesn't, the guard's stated "independent enforcement" intent makes the platform fix the only thing that actually restores deny-outright, so I would not build option 2 and would keep the bounded, fail-safe gap documented until the platform closes it. But that is declining to patch a security guard, which is exactly the call to route to a human.