Skip to content

Follow or refuse text that runs unread (#163, part 3) - #184

Merged
paureis merged 9 commits into
mainfrom
fix/163-hidden-calls
Nov 5, 2026
Merged

paureis merged 9 commits into
mainfrom
fix/163-hidden-calls

Conversation

@paureis

@paureis paureis commented Nov 5, 2026

Copy link
Copy Markdown
Owner

Part of #163 (PR 3 of 5, the hidden-call family). Design: docs/superpowers/specs/2026-11-04-fail-closed-design.md.

The bug. A guarded CLI ran unseen when the text naming it wasn't read as a call, in forms like echo '...' | bash, trap '...' EXIT, ${x:-$(az ...)}, bash -c -e '...', Set-Alias a az, t(){ "$@"; }; t gh ... and $RUN gh deploy. The existing path for eval "$(...)" never fired, because $( ) left an empty word.

The fix: follow or refuse.

  • Followed: literal text piped into a shell or iex, here-strings, trap, ${x:-$(...)}, bash's full option grammar, aliases from the next line on, Set-Alias, New-Alias.
  • Refused, only for the CLIs the line names, naming no value: eval "$(...)", sh -c "$(...)", source <(...), bash <(...), unknown text piped into a shell or iex, a line's function that runs its words, and a command word known only at run time, with or without arguments ($c, $RUN gh deploy, $(cat c) x). "$(command -v az)" and (Get-Command az).Source still read as that CLI.
  • Variables: a plain variable set in a branch (if, for, case, after && or ||), or a PowerShell block, is unknown after it, so only a value that picks the account stops.

Decisions to know about.

  • A line that names no guarded CLI passes, however unreadable: curl ... | bash, eval "$(cat f)". Stopping these would cost about 40 lines in 30 days and there's nothing to name. THREAT_MODEL.md says so.
  • That includes gc f | iex, which got an accidental "ask" on main because a marker's text held the word cloudpin.
  • A CLI whose every mention is exempt or already read before the unknown text doesn't stop: gh pr list; cat f | bash.
  • A lone $c | x or if ($c) stays a value, so a line read both ways on Windows keeps working.

Evidence

  • npm run typecheck exit 0; npx vitest run: 4340 passed, 19 skipped.
  • Mutations re-run on the final code: 39 of 39 and 104 of 104 killed, plus 1 re-pointed and killed. One more here: 30 tests fail.
  • Real shells with printers (210 forms, Git Bash and PowerShell 5.1, one PATH, aborting unless each name resolves to a printer): main allowed 133 that really ran; 115 now deny, 18 stay allowed (17 name no CLI, by decision; 1 is exempt).
  • The built hook, end to end, with a right pin: ordinary substitutions pass (gh pr create --title "$(cat t)", git commit -m "$(cat f)", curl ... | bash, $RUN ls, an exempt call), named calls behind unread text deny, and a folder with no pin file passes.
  • On 32,352 of the owner's real commands (counts only): 4 new stops, 1 gone, read by the shell that ran them; 2 new stops read as the other shell.

Not tested

pwsh, zsh, watch. pwsh - is from about_Pwsh; bare pwsh with piped input isn't in the docs and only adds a check.

Left open

Remove-Item alias:a isn't read, so it over-refuses. echo x | cmd isn't read. if c; then s=pinned; az --subscription $s; fi denies, a small false stop.

🤖 Generated with Claude Code

paureis and others added 9 commits November 4, 2026 22:03
invocation, namedClis and cantTell move, unchanged, to src/hidden-calls.ts:
shellwords.ts is near the file-size limit, and the next change adds to them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A line can run text cloudpin read as data, and the guarded CLI ran with no
objection. What can be read is now read, with the existing readers:

- literal text piped into a shell: echo, cat with a heredoc or here-string
- trap's string, where it is written and again as the line ends
- $( ) and backticks inside ${x:-...}, and ${CLI:-az} as a named CLI
- bash -c -e and the like: options are read as bash reads them, so a script
  file is a script file and -s reads standard input
- aliases: bash's from the next line on, PowerShell's from the next statement
- a PowerShell variable changed in a block is unknown from there on

What can't be read stops the guarded CLIs the line names, through cantTell,
with no value in the message: unknown text piped into a shell, eval or sh -c of
a substitution, source <( ), a bare $c or "$c" command word.

The can't-tell path for a substitution never fired, because $( ) left an empty
word: the tokenizer now puts DYNAMIC_WORD in its place, so a command line a word
holds says it can't be read, here-strings and npx -c included.

A line that names no guarded CLI has nothing to stop, so curl ... | bash passes.
A call already read before the text ran before it, and exempt calls pass.

One old test changed: Get-Content | iex; az version now passes, as az version
is exempt, so that test names az group list instead.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Mutation testing the last commit left 23 of 114 alive. Eight were code that
changed no result, now gone: trap's checks for `-`, -l and -p, whose string runs
nothing; reading trap in this shell where it is written, as the read at the end
already sees aliases; the marker strip in namedClis; an alias kept as unknown,
now refused where it is defined. Real Git Bash takes `bash +c 'x'` as -c, which
the code had wrong. The rest get a test each.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
CHANGELOG line, ROADMAP's family marked done, AGENTS row for hidden-calls.ts.
THREAT_MODEL gets one limit: the aim was "never a silent allow", and text that
can't be read on a line naming no guarded CLI now passes on purpose. Also a test
for the one mutation left alive: `||` then a new line is not a pipe.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Unchanged: shellwords.ts is near the file-size limit, and the next fix adds to it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
$RUN gh deploy, $CMD x; gh repo view and $(cat c) x were read as a call with
those words, or not at all, while a printer showed the CLI really ran. A word
that is wholly an expansion now stops the CLIs the line names, with or without
arguments, as a bare $c does. A call already read still ran before it, exempt
calls and lines naming no CLI pass, and with no pin in sight nothing stops.

Kept as they were: text around it makes a script's path, a value alone before a
pipe or in if ($c) is PowerShell's writing, and a word that looks the CLI up
("$(command -v az)", (Get-Command az).Source) runs that CLI, so it reads as one.

Three old tests that named the old reading now expect "can't tell":
$TOOL group list # az, $DEPLOY_TOOL deploy # uses vercel, cloudpin exec -- $x.

The pwsh readings cite about_Pwsh, with pwsh not installed here.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
s=other; if false; then s=pinned; fi; az --subscription $s read pinned while
real bash used other, and false && s=pinned did too. A plain assignment inside
if, while, until, for or case, or after && or ||, now makes the name unknown from
there on, as a PowerShell block does. Only a value that picks the account stops:
one word that isn't a flag stays one word, so gh pr list $s still passes.

Not widened: false && export X=y and test -d a && cd a stay read as if they ran.
A literal read back inside the same branch is also unknown there, a small cost.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A line read as PowerShell never reaches the branch rule's reader, so the dialect
check is gone. The rest get a test each: gcm, a quoted "if", a value of several
words, and what follows esac.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@paureis
paureis merged commit 39ffae4 into main Nov 5, 2026
4 checks passed
@paureis
paureis deleted the fix/163-hidden-calls branch November 5, 2026 03:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant