fix(#5255): read ANSI-C quoting ($'…') in the secret-read guard

.changeset/quiet-foxes-quote.md

@@ -0,0 +1,5 @@
+---
+type: Security
+pr: 5285
+---
+**Shell quoting could hide a secret read from the secret-read guard** — `echo $'x\'y'; cat .env` and `cat $'.e\x6ev'` are now blocked. The guard reads `$'…'` under bash, zsh and dash, judges a word by its decoded value, and closes four shapes it allowed: a brace as a heredoc tag, a quote in zsh's arithmetic, `$[ ]` inside `${…}`, and a line continuation inside `${…}` under dash. Nothing it blocked before is allowed. A command it cannot finish scanning is blocked as `command-too-complex`. (#5255)

docs/USER-GUIDE.md

@@ -459,7 +459,7 @@ GSD generates markdown files that become LLM system prompts. This means any user
 - `gsd-prompt-guard.js` — Scans Write/Edit calls to `.planning/` for injection patterns (always active, advisory-only)
 - `gsd-workflow-guard.js` — Warns on file edits outside GSD workflow context (opt-in via `hooks.workflow_guard`)
 - `gsd-write-guard.js` — Hard-blocks a whole-file `Write` that catastrophically shrinks a curated `.planning/` artifact (`ROADMAP.md`, milestone roadmaps, `STATE.md`) below 40% of its on-disk line count; files under 40 lines are exempt. The check is stateless per Write, comparing each payload against the file's *current* on-disk size — a single-shot collapse (the #973 shape) is blocked, but a sequence of individually-tolerated shrinks that erodes the file across several Writes is not detected. For a legitimate milestone reset or large deletion, bypass once with the single-use sentinel — write the target's path into `.planning/.gsd-allow-shrink` (fresh within 15 minutes; consumed by the allowed write) — or, interactively, with `GSD_ALLOW_PLANNING_SHRINK=1` in the runtime's environment. Scope the guarantee accordingly: this stops accidental and single-shot collapse, and is not a defense against a determined agent — the sentinel is a plain file, so anything with shell access can arm one; what it buys is that the bypass becomes a deliberate, path-bound, single-use and auditable action rather than a sentence to reason past (always active, blocking; #2255, fix 3 of #973)
-- `gsd-secret-read-guard.js` — Hard-blocks reads of secret files — `.env`, `.env.<suffix>` and `.secrets`, matched case-insensitively (`.ENV`, `.Secrets`) — through Read (`file_path`), Grep (an explicit `path`, or a `glob` that selects them, judged per brace alternative) and Bash (operands, input redirects, `$( )` / backtick / `<( )` bodies, and `git show <ref>:<path>` shapes). A shell interpreter (`bash`/`sh`/`zsh`/`dash`/`ksh`) has its script scanned however it arrives — `-c '…'`, a `<( )` file operand, a heredoc / here-string, or a pipe from a knowable `echo`/`printf` source (`echo cat .env | bash`) — as do `eval`'s joined operands, a `source`/`.` process-substitution operand, and `find … | xargs cat` pipelines (upstream literal names become the sub-command's read operands). A name is exempt when its **final extension** is `example`, `sample`, `template` or `dist`, so `.env.example` and equally `.env.local.example` / `.env.production.sample` stay readable (they are the templates GSD's own phase prompt reads). Stated cost: the exempt set is that unbounded family, not four fixed names — a real secret is not protected if it is named to end in one of those four extensions. Order matters, and only the last segment counts: `.env.example.local` is a secret and stays blocked. Trailing dots and spaces are stripped before the name is judged, because Windows resolves `.env.`, `.env ` and `.secrets.` to the protected file itself. Existence checks (`[ -f .env ]`, `ls .env*`, `test`, `stat`, `rm`, `touch`, `echo`, …) pass, and so do commands that name a secret without printing it: `git check-ignore`, `git ls-files` and `git rm --cached` on its path, and a one-source `cp`/`mv` whose only secret name is the destination (`cp .env.example .env`); an unlisted option (`-X <file>`, `--pathspec-from-file=`, `-t`, `--backup`, …) keeps the whole command checked (#4856). Not covered, by construction: `$VAR` indirection (`bash -c "$CMD"`), shell globs (`cat .e*`), interpreter one-liners, a piped script from a non-`echo`/`printf` source (`cat gen.sh | bash`, `curl … | sh`), reads inside scripts the agent runs, and a Grep `glob: '*'` reaching a `.env` that is not gitignored — none are statically resolvable by a hook. This replaces the `Read(.env)` / `Read(.env.*)` / `Read(.secrets)` permission deny rules the installer used to write: on Claude Code ≥ 2.1.259 any `Read()` deny rule makes every `cd DIR && grep …` compound prompt for approval even in `auto` mode, while a hook denial is not a permission rule and applies in `auto` and `bypassPermissions` alike (always active, blocking; #4221)
+- `gsd-secret-read-guard.js` — Hard-blocks reads of secret files — `.env`, `.env.<suffix>` and `.secrets`, matched case-insensitively (`.ENV`, `.Secrets`) — through Read (`file_path`), Grep (an explicit `path`, or a `glob` that selects them, judged per brace alternative) and Bash (operands, input redirects, `$( )` / backtick / `<( )` bodies, and `git show <ref>:<path>` shapes). A shell interpreter (`bash`/`sh`/`zsh`/`dash`/`ksh`) has its script scanned however it arrives — `-c '…'`, a `<( )` file operand, a heredoc / here-string, or a pipe from a knowable `echo`/`printf` source (`echo cat .env | bash`) — as do `eval`'s joined operands, a `source`/`.` process-substitution operand, and `find … | xargs cat` pipelines (upstream literal names become the sub-command's read operands). Dollar-quoting is read the way the shell reads it: `$'…'` is judged by its decoded value, so `cat $'.e\x6ev'` is a read of `.env`, and a `\'` inside does not close the word. bash, zsh and dash read the same text differently, so a command holding `$'…'`, `$"…"`, `$${`, `$$(`, or a quote with `((` or `$[` is checked under all three readings as well as the plain scan and blocked on any; nothing the plain scan blocks is allowed. A `$'…'` word that never closes or has no single value to check is blocked outright, unless it follows an even run of `$`: `echo $$'x\'; ls` is the PID and a plain quote (#5255). A Bash command longer than 1,048,576 characters (UTF-16 code units, not bytes; a character outside the BMP, such as most emoji, counts as two) is blocked unscanned (`command-too-large`), and so is one nested deep enough to overflow the parser or needing more than eight times that much scanning (`command-too-complex`). The readings multiply that work, so a commit message written as `git commit -m "$(cat <<'EOF' …` with a `$'\t'` in it, or a quote beside a `((`, is blocked from about 420,000 characters (#5255). A name is exempt when its **final extension** is `example`, `sample`, `template` or `dist`, so `.env.example` and equally `.env.local.example` / `.env.production.sample` stay readable (they are the templates GSD's own phase prompt reads). Stated cost: the exempt set is that unbounded family, not four fixed names — a real secret is not protected if it is named to end in one of those four extensions. Order matters, and only the last segment counts: `.env.example.local` is a secret and stays blocked. Trailing dots and spaces are stripped before the name is judged, because Windows resolves `.env.`, `.env ` and `.secrets.` to the protected file itself. Existence checks (`[ -f .env ]`, `ls .env*`, `test`, `stat`, `rm`, `touch`, `echo`, …) pass, and so do commands that name a secret without printing it: `git check-ignore`, `git ls-files` and `git rm --cached` on its path, and a one-source `cp`/`mv` whose only secret name is the destination (`cp .env.example .env`); an unlisted option (`-X <file>`, `--pathspec-from-file=`, `-t`, `--backup`, …) keeps the whole command checked (#4856). Not covered, by construction: `$VAR` indirection (`bash -c "$CMD"`) and `${…}` defaults (`cat ${x:-.env}`, and `echo ${x:-$(cat .env)}` in a command holding none of those forms, #5523), shell globs (`cat .e*`), interpreter one-liners, a piped script from a non-`echo`/`printf` source (`cat gen.sh | bash`, `curl … | sh`), reads inside scripts the agent runs, and a Grep `glob: '*'` reaching a `.env` that is not gitignored — none are statically resolvable by a hook. This replaces the `Read(.env)` / `Read(.env.*)` / `Read(.secrets)` permission deny rules the installer used to write: on Claude Code ≥ 2.1.259 any `Read()` deny rule makes every `cd DIR && grep …` compound prompt for approval even in `auto` mode, while a hook denial is not a permission rule and applies in `auto` and `bypassPermissions` alike (always active, blocking; #4221)
 
 Git configuration supplied through `-c key=value` is also checked for the two command-valued forms in #5045: a shell alias (`alias.*` whose value starts with `!`) and `diff.external`. Their literal command strings are scanned by the same bounded shell analysis, so `git -c alias.x='!cat .env' x` and `git -c diff.external='cat .env' diff` are blocked. Benign scripts, secret-free templates, ordinary config values, and `core.pager` remain subject to the existing checks. Scanning is conservative: every matching value supplied before the Git subcommand is inspected, even if a later setting replaces it or that subcommand does not invoke it. Behind a Git option the guard does not recognize, the subcommand can no longer be located, so every later `-c` value on the command is inspected. This does not resolve config files, values obtained through `--config-env` / `GIT_CONFIG_*`, other command-valued keys (diff drivers, filters, credential helpers, SSH or GPG commands), or scripts hidden behind the existing indirection and nesting limits; those remain documented gaps.