chore(disk-hygiene): decide guard registration surface — skill-scoped vs plugin-level hooks.json (F1/F5)

[kyle-sexton]

Parent

Source: handoff-inbox item 20260723-021058-disk-hygiene-0-6-4-consumer-audit (findings F1, F5 — priority call-out: "one structural decision resolves lockout scope, kill-switch delivery, and data-root authority simultaneously").

Decision to resolve

Maintainer decision (interview round with the user — not agent-resolvable): where does destructive_guard.py register?

• Option A — move to plugin-level hooks.json exec-form: delivers --disk-hygiene-enabled ${user_config.disk_hygiene_enabled} (guard-enforced audit-only mode) and --authorized-data-root ${CLAUDE_PLUGIN_DATA} directly; observed firing is session-long anyway (per F1), so real scope cost is low. Fixes the misleading GuardTests situation (suite currently proves toggle-denial only via channels the shipped skill hook never receives).
• Option B — keep skill-scoped registration; document observed session-long persistence + release path; accept kill-switch non-delivery as a known limitation.

Decision inputs come from the verification issue (blocker). NOTE: Option A changes when/where a hook fires — likely re-triggers the plugin-acceptance security review (MIGRATION-PLAYBOOK); run and record the review delta as part of the decision record.

Acceptance criteria

• Decision made by maintainer and recorded as a closing comment with rationale
• Security-review re-trigger question answered and recorded
• Implementation issue unblocked with the chosen shape

Blocked by

• Verification issue (F1/F5 harness-behavior verification)

[kyle-sexton]

Option space update (supersedes the A/B framing in the body)

Facts established since the body was written (evidence: #1105 comment + this session's source reads):

• Guard source (0.6.4, destructive_guard.py main()): the Bash lane is deny-by-default for every command that isn't an exact kill-switch probe / scan / preview / apply shape. Naive plugin-level registration therefore denies ALL Bash commands in every session of every consumer. Option A as originally framed is not shippable without a lane redesign.
• Skill-scoped hooks were refused ${CLAUDE_PLUGIN_DATA} (plugin-level substitution only; the plugin's own 0.6.3 CHANGELOG records the refusal) — weakens any keep-skill-scoped option's data-root delivery.
• ${user_config.*} exec-form substitution and CLAUDE_PLUGIN_DATA are docs-verified for plugin-level hooks.json (chore(disk-hygiene): verify hook lifetime + user_config/PLUGIN_DATA delivery channels (F1/F5 decision input) #1105). The CLAUDE_PLUGIN_OPTION_<KEY> env-var reaching skill-frontmatter hook processes is documented broadly but unverified for that surface.
• Every plugin-level option pays: one python3 spawn per Bash/PowerShell call in every consumer session, and on Store-stub machines (F3, fix(disk-hygiene): setup check detects Windows Store python3 alias stub fail-open (F3) #1110) a failed launch on every call session-wide.

Full option set:

• A — move guard to plugin-level hooks.json as-is: not viable (deny-by-default lane, above).
• B — keep skill-scoped, document persistence + kill-switch non-delivery: zero new cost, zero enforcement gain.
• C — keep skill-scoped, guard reads CLAUDE_PLUGIN_OPTION_DISK_HYGIENE_ENABLED: cheapest enforcement path IF the env var reaches skill-hook processes (unverified; add to the interactive repro). Data-root delivery still unsolved per the 0.6.3 refusal.
• D — plugin-level registration, activity-gated guard (exits 0 unless a skill-start marker in CLAUDE_PLUGIN_DATA is live, stale-TTL): bounds firing to actual disk-hygiene activity; pays the per-call spawn everywhere.
• E — split registration (recommended): thin plugin-level exec-form hook (--mode engine-gate or dedicated script) receiving ${user_config.disk_hygiene_enabled} + ${CLAUDE_PLUGIN_DATA}, exiting 0 instantly for anything that isn't an engine-invocation shape; the deny-by-default belt stays skill-scoped and unchanged. Delivers kill switch + data-root through the docs-verified channels; no consumer session sees a deny for unrelated commands; per-call spawn + Store-stub noise still apply (price it in fix(disk-hygiene): setup check detects Windows Store python3 alias stub fail-open (F3) #1110's remediation). Confirm hook matcher semantics (tool-name matchers; command filtering inside the script) against the hooks/skills docs before implementation.

Maintainer decision still required; the recommendation above is the session's, not a resolution.

[kyle-sexton]

Decision (maintainer, 2026-07-23, interview round in session a282a22b): Option E — split registration. Thin plugin-level exec-form hook delivers --disk-hygiene-enabled ${user_config.disk_hygiene_enabled} + --authorized-data-root ${CLAUDE_PLUGIN_DATA} and exits 0 instantly for anything that is not an engine-invocation shape; the deny-by-default belt stays skill-scoped and unchanged. Rationale + full option analysis in the preceding comment; decisive facts: Bash-lane deny-by-default makes whole-guard plugin-level registration unshippable, and skill-scoped hooks were refused ${CLAUDE_PLUGIN_DATA} (0.6.3 CHANGELOG), so plugin-level is the only verified path for both channels.

Security-review question (AC2): YES — E adds a new plugin-level hook = new trust surface; the plugin-acceptance security review re-runs as part of the implementation PR (#1107), delta recorded there per MIGRATION-PLAYBOOK.

Implementation notes for #1107: confirm hook matcher semantics against a fresh skills/hooks docs fetch; engine-gate must stay cheap (single fast-path string check before any parsing) given it fires per shell call in every consumer session; price the Store-stub interaction (#1110) in its docs.

[kyle-sexton]

Decision recorded above; #1107 unblocked.