disk-hygiene: destructive_guard.py literal-$ authorized-path support in the shell tokenizer (PR #742 follow-up)

[kyle-sexton]

This was generated by AI during triage (#657 sweep housekeeping, T8h batch conversion).

Origin: PR #742 review thread (destructive_guard.py line 141). Folded from a #657 line (checked off there, this issue is the target).

Problem

Literal-$ authorized-path support is missing in the disk-hygiene destructive guard. Repro: _literal_shell_words (plugins/disk-hygiene/skills/clean/scripts/destructive_guard.py, around L56-59) blanket-rejects any command containing $, so an authorized --data-root whose CLAUDE_PLUGIN_DATA path contains a literal $ is rejected before parsing — scan/preview/apply fail closed for those installs despite the argv authority.

Current behavior is fail-closed/fail-loud (deny with visible reason) — over-blocking, the safe direction, outside DEFER-FORBIDDEN. Deferred deliberately by the reporter, not a quick fix.

Fix direction (from the reporting review thread)

Allow $ only inside a single-quoted literal word (bash does NOT expand $ in single quotes; it DOES inside double quotes) — requires a quote-aware tokenizer that still rejects real expansion/$(...)/backtick syntax.

Why this is needs-human, not a mechanical batch fix

This is a change to a security-relevant guard's tokenizer. The stated fix direction is a single design, but it must be implemented and adversarially reviewed by a human before merge — the exact bar this repo already applies to guard-tokenizer changes (see #903/#964's chained-alias-bypass caution: a plausible-looking carve-out in a value/shape guard is exactly the class of change that has reopened bypasses before here). Getting the quote-aware tokenizer wrong (e.g., missing a $(...)-inside-single-quotes edge case, or a mixed-quote word) would silently reopen the injection vector the blanket check exists to block — that is a genuine security review call, not a mechanical rename/consolidation.

Question for the human: does the single-quoted-literal carve-out as scoped above cover the real-world CLAUDE_PLUGIN_DATA-contains-$ cases this repo needs to support, or is the safer path to instead document the $-in-path restriction as an accepted limitation (parallel to #1013's resolution for the guardrails value-blindness case) and tell affected installs to avoid $ in their data-root path?

[kyle-sexton]

This was generated by AI during triage.

Problem

An install whose authorized CLAUDE_PLUGIN_DATA path contains a literal $ can never pass the disk-hygiene guard: _literal_shell_words (plugins/disk-hygiene/skills/clean/scripts/destructive_guard.py:54-94) blanket-rejects any command containing a char in _SHELL_EXPANSION_OR_OPERATOR_CHARS (L13, which includes $) before any quote-aware parsing runs (L56-59), so scan/preview/apply fail closed for that install even though --data-root would exactly match the argv authority. Current behavior is fail-closed/fail-loud over-blocking — the safe direction — mirroring the fail-safe over-block class in #1013.

What the tokenizer actually does with $ today

• L13 puts $ in the blanket expansion/operator rejection set.
• L56-59 iterates every char of the whole command and returns None on the first $ anywhere, so the command is never classified and main() denies it via _bash_denial_guidance (L299-315).
• The quote-aware loop (L60-94) never sees $. Note its unquoted branch (L84-91) rejects only \, ', ", and whitespace — not $. Its single-quoted branch already extracts inner text opaquely and rejects nested quotes (L67-78).

The security-critical implementation detail

A fix is not "drop $ from _SHELL_EXPANSION_OR_OPERATOR_CHARS." Because the unquoted branch does not reject $, that change alone would let an unquoted --data-root $HOME/x tokenize successfully and then be handed to Bash, which expands it — the validated string would differ from the executed string, which is exactly the injection this guard exists to block. A correct carve-out must allow $ only inside a single-quoted word and explicitly reject it unquoted and inside double quotes.

Relevant shell semantics (verified against POSIX shell quoting rules; standard bash behavior)

• Single quotes: no expansion of anything, including $; a single quote cannot even appear inside single quotes. Content is fully literal — so a single-quoted $ is genuinely safe (validated == executed). Parsing is trivial: open ', next ', everything between is literal.
• Double quotes: $, backtick, and \ remain special — $ expands. Must stay rejected.
• Unquoted: $FOO / $(...) expand. Must stay rejected.

The often-cited "why not also carve out *, ~, {" slippery slope applies to unquoted/double-quoted expansion, not to treating single-quoted content as opaque literal — so it does not weigh against Option A below.

Options

A (RECOMMENDED) — Document $-in-data-root as an accepted limitation, and make the denial name it. Do not touch the tokenizer's authority boundary. Add one sentence to _bash_denial_guidance (L299-315) so a denied command containing $ explains the $-in-path restriction instead of failing closed silently, and note the limitation in reference/safety-model.md. Tradeoff: an affected install still can't run the engine — but the population is near-zero ($ in CLAUDE_PLUGIN_DATA is unusual on every platform), there is no reported real install needing it, and this is a security boundary, so this is YAGNI-for-a-guard. Direct precedent: #1013 documents a fail-safe over-block rather than widening a value/shape guard. Fully reversible (docs + one message string); leaves the boundary untouched; the paired denial tweak converts a confusing silent failure into an explained one, which is what makes "document it" actually acceptable rather than merely cheap. Safest-by-default: zero new attack surface.

B — Narrow quote-aware carve-out: allow $ only inside single-quoted words. Move $ out of the blanket check into the tokenizer, permit it in the single-quoted branch, and add explicit rejection of $ in the unquoted branch (L84-91) and the double-quoted branch. This is a legitimately clean option — single-quoted-literal parsing is one of the simplest, safest shell rules — and the model would emit --data-root '/path/with/$/in/it'. Tradeoff: it is still a change to a security guard's tokenizer and must be implemented + adversarially reviewed by a human (the #903/#964 bar); the concrete failure mode to catch is forgetting the unquoted/double-quoted rejection, which reopens the validated≠executed bypass. Reversible (code revert), but any window where it shipped wrong is a live bypass.

C — Broader quote-aware literal tokenizer (treat all single-quoted content as opaque). Superset of B: single-quoted words pass through verbatim for every char, matching real bash semantics most faithfully. Largest change and review surface for the least marginal benefit here (the only reported need is $); reversible.

Recommendation rationale

Option A is safest-by-default: it adds no attack surface to a security boundary, is fully reversible, and is grounded in evidence (near-zero affected population, no reported install, #1013 precedent) rather than in a general "parsing is dangerous" claim — Option B is genuinely clean and is the right escalation if a real install surfaces that needs $ in its data-root path. Suggested trigger for revisiting B: a concrete reported install whose CLAUDE_PLUGIN_DATA legitimately contains $.

Question for the human: ship A (document + fail-loud denial naming the $ restriction) now, keeping B on file with the trigger above? Or is there a known install that already needs $ in its data-root, which would move B to the front?

[kyle-sexton]

Frontier disposition (drain session)

Ruling: Close as not planned.

Deferred from PR #742. Literal-$ authorized-path support in the shell tokenizer has no fired trigger.

Re-open trigger: When a live authorized-path case fails tokenization on literal-$ paths.