disk-hygiene: model-invocable read-only audit skill for orchestrators and subagents

[kyle-sexton]

Split from #5214.

Problem

plugins/disk-hygiene/skills/clean/SKILL.md:5 sets disable-model-invocation: true, and the description says "manual-only". An orchestrator session or a subagent therefore cannot load the skill. The worker had to call scripts/hygiene.py scan directly, without the skill's instructions, and rebuild the flags from the worker brief.

Expected: the read-only audit (scan, classify, report) can be started by a model, so a session can delegate an audit. --execute and the removal lane stay user-only.

Suggested direction: split the read-only audit into a model-invocable skill or action, and keep the --execute path behind the existing user-only confirmation gate.

Additional evidence from #5214: even with a model-invocable audit, a delegated worker cannot build a valid command. The "disk-hygiene guard values" note (hook_python, data_root) comes from a UserPromptExpansion hook whose matcher is disk-hygiene:clean$, so it fires only when a person types the command and no orchestrator or subagent receives it. The fan-out brief's templates contain literal ${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PLUGIN_DATA}, ${CLAUDE_PROJECT_DIR} and <hook-python>, which a worker cannot expand because the guard rejects shell expansion. The bootstrap gap is tracked in the docs issue split from #5214 (item 4).

Decision

Manual-only was deliberate, and the guard and deletion safety are security-class. The owner decides after the evidence posted on #5214 (whether a read-only-only skill can be made unable to reach --execute).

[kyle-sexton]

Owner decision (2026-09-30): Option A1. Add a new, separate model-invocable read-only audit skill (for example disk-hygiene:audit) and keep clean manual-only, accepting the existing guard ask plus the engine approval token as the floor. Four conditions:

1. Leave plugins/disk-hygiene/skills/clean/SKILL.md disable-model-invocation: true untouched. Do not edit hooks.json or destructive_guard.py.
2. The new skill documents only the scan shape and the report, never preview, apply or --execute (preview produces the approval token that apply --execute needs). Its description says read-only and names the handoff to /disk-hygiene:clean for removal. Its triggers are narrow so it does not auto-fire on generic "clean up my disk" requests. It must not rely on skill-frontmatter hooks for safety; it leans on the plugin-level gate.
3. It gets its bootstrap values (hook_python, data_root) from the argument-free kill-switch probe, because the UserPromptExpansion note fires only for a typed disk-hygiene:clean. Ship together with the disk-hygiene: fix run-directory, fan-out brief and --project-dir wording #5520 bootstrap and docs fixes.
4. Before the skill ships, probe how the guard ask on apply --execute behaves headless, under --bg, and under bypassPermissions. If it fails open, fall back to A2 (a plugin-level read-only guard mode or engine read-only subcommand set) for that lane only. A2 is not a prerequisite for the rest.

Approved by the owner with all consensus recommendations on 2026-09-30 (three read-only researchers, majority or judge).

Next: the issue is now agent-ready. An agent implements the new skill under the four conditions, runs the ask probe before merge, and opens a draft PR.

[kyle-sexton]

Closing as completed: PR #5590 (the read-only /disk-hygiene:audit skill, option A1) is merged. All four A1 conditions hold: a separate skill with clean left manual-only; scan and report only, removal handed to /disk-hygiene:clean; bootstrap values from the argument-free kill-switch probe; and the guard's ask probed in headless default (denied), --bg default (parked) and headless bypassPermissions (denied), so the A2 fallback is not triggered. The owner released the hold on 2026-09-30 (PR #5590 comment 5916652283). Hardening for interactive bypassPermissions, auto mode and the Windows PowerShell tool is tracked in #5609.