disk-hygiene: guard hook fails to launch on skill-frontmatter hooks referencing ${CLAUDE_PLUGIN_DATA} — live fail-open on 0.4.6

[kyle-sexton]

Summary

SKILL.md:13 registers the PreToolUse hook with:

args: ["${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/destructive_guard.py",
       "--authorized-data-root", "${CLAUDE_PLUGIN_DATA}",
       "--disk-hygiene-enabled", "${user_config.disk_hygiene_enabled}"]

The 0.4.1 fix (#376) assumed "inline placeholder substitution resolves in exec-form hook args where
environment injection does not." That premise is now false for skill-scoped hooks.

Empirical reproduction (live, this session, plugin version 0.4.6)

PreToolUse:Bash hook error
Failed to run: Hook command references ${CLAUDE_PLUGIN_DATA} but only ${CLAUDE_PLUGIN_ROOT} is
available for skill hooks (${CLAUDE_PLUGIN_DATA} is plugin-only). Command: python3 ${CLAUDE_PLUGIN_ROOT}/…

Claude Code refuses to launch the hook process at all when its args reference ${CLAUDE_PLUGIN_DATA}
in a skill-scoped context. Per the plugin's own documented doctrine, "Claude Code treats a failed hook
launch as a non-blocking error" — so the destructive-action guard never runs. Confirmed live: a bare
python hygiene.py scan ... call executed completely ungated, no denial, no substitution — the guard
simply never fired.

Why this isn't just a doc bug

This is the same fail-open shape #380 fixed (interpreter resolution) recurring through a different
vector (hook launch failure via an unsupported substitution token). It also directly relates to what
#386/D2 already flags as a false premise in the docs — but #386 frames that as a doc-accuracy
issue. It undersells it: the doc isn't just wrong, the mechanism it describes doesn't work at all, and
the guard is currently non-functional on skill-frontmatter hooks as a result.

Suggested direction (not prescriptive — needs its own research pass)

• Determine what values are legitimately substitutable in skill-scoped hook args (confirmed:
  ${CLAUDE_PLUGIN_ROOT} works). If CLAUDE_PLUGIN_DATA truly cannot reach a skill hook by any
  channel (arg substitution or env), the guard needs a different authority source — e.g. derive the
  data root deterministically from ${CLAUDE_PLUGIN_ROOT} if the data-root path is a fixed sibling
  under .claude/plugins/data/<plugin-name>/, or petition the Claude Code runtime to add data-root
  substitution support for skill hooks (may be a platform gap, not something the plugin alone can fix).
• Add a regression test that actually exercises the hook launch path, not just
  destructive_guard.py's internal arg-parsing once launched — that's the part currently untested and
  currently broken.
• Cross-link/reopen disk-hygiene: skill-frontmatter guard reads CLAUDE_PLUGIN_DATA from env but never receives it -> engine lane fails closed on all platforms #376 (its fix didn't hold) and bump disk-hygiene: doc corrections — Windows mislabeled 'full', false CLAUDE_PLUGIN_DATA premise repeated, PowerShell-lane gaps #386's severity once this is understood as
  live-exploitable rather than doc-only.

Related

#376, #380, #386