@gotgenes/pi-permission-system 35.0.3 → 36.0.0

package/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [36.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v35.0.3...pi-permission-system-v36.0.0) (2026-09-29)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** a digit argument no longer withdraws sed's or awk's read claim ([18df901](https://github.com/gotgenes/pi-packages/commit/18df9012843b5811746098bcd106c52d1bc15510)), closes [#992](https://github.com/gotgenes/pi-packages/issues/992)
+* **pi-permission-system:** **breaking:** a computed argument that may spell an option withdraws find's, fd's, and sort's read claim ([8116d72](https://github.com/gotgenes/pi-packages/commit/8116d725b7d74ec610ef97cfb26e6a2df64a839d)), closes [#992](https://github.com/gotgenes/pi-packages/issues/992)
+* **pi-permission-system:** a quoted "$@" after a literal withdraws find's, fd's, and sort's read claim ([45da982](https://github.com/gotgenes/pi-packages/commit/45da9825f80ce4fe2955081f2692a1bc678ddb26)), closes [#992](https://github.com/gotgenes/pi-packages/issues/992)
+* **pi-permission-system:** a quoted indirect expansion after a literal withdraws find's, fd's, and sort's read claim ([dd78839](https://github.com/gotgenes/pi-packages/commit/dd78839f6327e7de51b1024b07ea21653e34b680)), closes [#992](https://github.com/gotgenes/pi-packages/issues/992)
+* **pi-permission-system:** a quoted variable after a literal withdraws find's, fd's, and sort's read claim ([7727223](https://github.com/gotgenes/pi-packages/commit/7727223ec01b5dd0e8560248dd965e7f638930ae)), closes [#992](https://github.com/gotgenes/pi-packages/issues/992)
+
+### Documentation
+
+* **pi-permission-system:** document the computed-word rule for find, fd, and sort ([9f7deb9](https://github.com/gotgenes/pi-packages/commit/9f7deb9ca270a17c99a820f79e40fa64afc444d0))
+* **pi-permission-system:** name a quoted "$@" among the words that split ([1595490](https://github.com/gotgenes/pi-packages/commit/15954901cc61154ad5548f3b5553b60bb48ab4d6))
+* **pi-permission-system:** name an indirect expansion among the words that split ([7d875c3](https://github.com/gotgenes/pi-packages/commit/7d875c37d4130d06ae1969b4739f030b5ce79dd7))
+* **pi-permission-system:** a quoted variable may split, since it may be a nameref ([0df4871](https://github.com/gotgenes/pi-packages/commit/0df4871f2ca42d4df6639f9bcf7d11d0647b3e31))
+
 ## [35.0.3](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v35.0.2...pi-permission-system-v35.0.3) (2026-09-29)
 
 

package/docs/configuration.md

@@ -896,6 +896,10 @@ Three members are read-only **until an argument says otherwise**, and naming one
 
 A long option is matched by any unambiguous abbreviation too (`sort --out=…` withdraws the claim exactly as `--output` does), and a short letter is matched anywhere in a cluster (`-uo`) or with its value attached (`-o/tmp/x`).
 
+An argument whose value only the shell decides withdraws the claim too when it may arrive beginning with `-`, since it could spell any of these options: `$opt`, `"$dir"`, `$(cmd)`, and a leading glob such as `*` all do.
+One whose first character is a literal other than `-` cannot become an option unless it can split into several words, so `find packages/*/docs` and `find . \( -name a \)` still read.
+A variable can split even inside double quotes (`"x$@"` yields one word per positional parameter, and any variable may be a name reference to an array), so `find /src -name "x$y"` withdraws the claim too.
+
 A core word counts only as a **bare basename**.
 `./grep`, `/usr/bin/grep`, and `bin\grep` name programs this audit never saw, so they prove nothing and consult both surfaces.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "35.0.3",
+  "version": "36.0.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {

package/src/access-intent/bash/command-effects.ts

@@ -16,7 +16,7 @@ import { sedWithdrawsReadClaim } from "./sed-invocation";
  * without reading the host's path language.
  *
  * A guarded word's claim is withdrawn when an argument names one of its
- * write-capable options, yielding `retracted` rather than a write: the command
+ * write-capable options, or is computed and may arrive as one, yielding `retracted` rather than a write: the command
  * may still only read, so the fail-closed base case is the honest answer and
  * `retracted` is the blame line that says why.
  *
@@ -206,17 +206,27 @@ interface RetractionGuard {
  */
 type ClaimWithdrawal = (argWords: readonly ArgWord[]) => boolean;
 
-/** A withdrawal decided by option spellings alone: any argument naming one. */
+/**
+ * A withdrawal decided by option spellings: any argument naming one.
+ *
+ * A computed argument's value is its unresolved source spelling, not what the
+ * program receives, so it is asked only whether it may arrive beginning with
+ * `-`, the shape every guarded option has.
+ */
 function optionGuard(guard: RetractionGuard): ClaimWithdrawal {
   return (argWords) =>
-    argWords.some(({ value }) => retractsClaim(value, guard));
+    argWords.some((word) =>
+      word.computed ? word.mayLeadWithDash : retractsClaim(word.value, guard),
+    );
 }
 
 /**
  * The guarded words and what withdraws each one's claim.
  *
- * `find`, `fd`, and `sort` are guarded by option spellings alone, chosen
- * because their write options spell identically in GNU and BSD. `sed` needs a
+ * `find`, `fd`, and `sort` are guarded by option spellings, chosen because
+ * their write options spell identically in GNU and BSD; a computed argument
+ * that may lead with `-` withdraws their claim too, since it could spell any
+ * of them. `sed` needs a
  * proof over its script too, since a `w` command writes whatever its options
  * say, and `awk` a proof over its program, since `print >` does the same — so
  * each owns a predicate of its own. `find`'s options are single-dash long

package/src/access-intent/bash/node-text.ts

@@ -44,16 +44,143 @@ export interface ArgWord {
    * expansion, an ANSI-C string — which {@link resolveNodeText} passes through as written.
    */
   readonly computed: boolean;
+  /**
+   * Whether the program may receive this argument, or a word split from it,
+   * beginning with `-` — the shape every option has. Exact for a word that is
+   * not computed; for a computed one, `false` only when a literal leading
+   * character survives every rewrite the shell applies.
+   */
+  readonly mayLeadWithDash: boolean;
 }
 
 /** Read an argument node into the word the program receives. */
 export function readArgWord(node: TSNode): ArgWord {
+  const value = resolveNodeText(node);
+  const computed = hasComputedPart(node) || !isSpelledExactly(node);
   return {
-    value: resolveNodeText(node),
-    computed: hasComputedPart(node) || !isSpelledExactly(node),
+    value,
+    computed,
+    mayLeadWithDash: computed
+      ? mayExpandToDashWord(node)
+      : value.startsWith("-"),
   };
 }
 
+/**
+ * Whether a computed word may reach the program — whole, or as one of the
+ * words the shell splits it into — beginning with `-`.
+ *
+ * Globbing, brace expansion, and escape removal each keep a literal prefix, so
+ * a word whose leading character is a literal other than `-` cannot become an
+ * option; an expansion that can split into several words decides nothing,
+ * since only the first of them carries the prefix.
+ */
+function mayExpandToDashWord(node: TSNode): boolean {
+  return (
+    maySplitIntoWords(node, false) || (leadingCharacterMayBeDash(node) ?? true)
+  );
+}
+
+/** Expansions whose unquoted result the shell splits into words. */
+const WORD_SPLITTING_TYPES: ReadonlySet<string> = new Set([
+  "simple_expansion",
+  "expansion",
+  "command_substitution",
+  "arithmetic_expansion",
+]);
+
+/**
+ * Nodes whose inside is never split into the argument's words: a
+ * single-quoted or ANSI-C string, and a process substitution, whose body
+ * belongs to its own command.
+ */
+const UNSPLIT_TYPES: ReadonlySet<string> = new Set([
+  "raw_string",
+  "ansi_c_string",
+  "process_substitution",
+]);
+
+/**
+ * Whether any expansion in the word may produce more than one word.
+ *
+ * Unquoted, every expansion splits. Inside double quotes a command
+ * substitution or arithmetic expansion is one word, but a parameter expansion
+ * may not be: `$@` and `${arr[@]}` expand to one word per element, an indirect
+ * `${!name}` may name either, and any variable may be a nameref
+ * (`declare -n s='arr[@]'`), with nothing in its own spelling to show it. So
+ * every quoted parameter expansion counts, over-counting a joined `$*`.
+ */
+function maySplitIntoWords(node: TSNode, quoted: boolean): boolean {
+  if (WORD_SPLITTING_TYPES.has(node.type)) {
+    return !quoted || PARAMETER_EXPANSION_TYPES.has(node.type);
+  }
+  if (UNSPLIT_TYPES.has(node.type)) return false;
+  const childrenQuoted = quoted || node.type === "string";
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child && maySplitIntoWords(child, childrenQuoted)) return true;
+  }
+  return false;
+}
+
+/** Parameter expansions, which may yield several words even when quoted. */
+const PARAMETER_EXPANSION_TYPES: ReadonlySet<string> = new Set([
+  "simple_expansion",
+  "expansion",
+]);
+
+/**
+ * Whether the first character the word produces may be `-`, or `undefined`
+ * while every part read so far produced nothing (`""`, `''`).
+ *
+ * A part this does not know is non-literal, and so may lead with anything.
+ */
+function leadingCharacterMayBeDash(node: TSNode): boolean | undefined {
+  switch (node.type) {
+    case "word":
+    case "number":
+      return unquotedLiteralMayLeadWithDash(node.text);
+    case "raw_string":
+      return quotedLiteralMayLeadWithDash(node.text.slice(1, -1));
+    case "string_content":
+      return quotedLiteralMayLeadWithDash(node.text);
+    case '"':
+      return undefined;
+    case "process_substitution":
+      // The program receives a `/dev/fd/N` path.
+      return false;
+    case "string":
+    case "concatenation":
+      for (let i = 0; i < node.childCount; i++) {
+        const child = node.child(i);
+        const lead = child ? leadingCharacterMayBeDash(child) : undefined;
+        if (lead !== undefined) return lead;
+      }
+      return undefined;
+    default:
+      return true;
+  }
+}
+
+/**
+ * An unquoted literal: a leading glob or brace can produce any character, and
+ * an escape yields the character after it.
+ */
+function unquotedLiteralMayLeadWithDash(text: string): boolean | undefined {
+  if (text === "") return undefined;
+  if (text.startsWith("\\")) return text.length < 2 || text[1] === "-";
+  return UNDETERMINED_LEAD.test(text);
+}
+
+/** A leading character that may become, or already is, `-`. */
+const UNDETERMINED_LEAD = /^[-*?[{]/;
+
+/** A quoted literal reaches the program as written. */
+function quotedLiteralMayLeadWithDash(text: string): boolean | undefined {
+  if (text === "") return undefined;
+  return text.startsWith("-");
+}
+
 /**
  * Whether {@link resolveNodeText} returns exactly the string the shell passes.
  *
@@ -72,6 +199,9 @@ function isSpelledExactly(node: TSNode): boolean {
     case "expansion":
       return resolvePlainVariableExpansion(node) !== null;
     case "string":
+    // A digit run is an ordinary word to the shell; the grammar's `10#$x` form
+    // carries an expansion child, which answers for itself.
+    case "number":
       return childrenSpelledExactly(node);
     case "concatenation":
       // The grammar splits `{-i,-n}` into plain words, so the expansion is