@gotgenes/pi-permission-system 39.1.1 → 40.0.0

package/CHANGELOG.md

@@ -5,6 +5,34 @@ 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).
 
+## [40.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v39.1.2...pi-permission-system-v40.0.0) (2026-10-06)
+
+
+### Features
+
+* **pi-permission-system:** report which spelling of a bash command a rule matched ([9c1a9da](https://github.com/gotgenes/pi-packages/commit/9c1a9da4ee19e25aa6ea8366f3d6a5062e2d3c2c)), closes [#910](https://github.com/gotgenes/pi-packages/issues/910)
+* **pi-permission-system:** show the matching bash spelling in the ask dialog and the review log ([09c1ef6](https://github.com/gotgenes/pi-packages/commit/09c1ef62e9b1fdc6dc4beabc7193ac89ef9496ce)), closes [#910](https://github.com/gotgenes/pi-packages/issues/910)
+
+### Bug Fixes
+
+* **pi-permission-system:** **breaking:** match a bash rule written with an absolute path against the relative spelling of that path ([8883d96](https://github.com/gotgenes/pi-packages/commit/8883d960f4ccbe6131e22959e3acbc35abe2558b)), closes [#910](https://github.com/gotgenes/pi-packages/issues/910)
+
+### Documentation
+
+* **pi-permission-system:** document the absolute argument spelling of a bash command ([29816e7](https://github.com/gotgenes/pi-packages/commit/29816e7664cb2a813f042fe1b41d7b46ce5c870e)), closes [#910](https://github.com/gotgenes/pi-packages/issues/910)
+* **pi-permission-system:** note that a slash-bearing non-path argument is spelled too ([8a21456](https://github.com/gotgenes/pi-packages/commit/8a21456faa43eb86ac0c0cb790cff3e170b73ee2)), closes [#910](https://github.com/gotgenes/pi-packages/issues/910)
+
+## [39.1.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v39.1.1...pi-permission-system-v39.1.2) (2026-10-06)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** a subagent's forwarded bash line is judged command by command on the parent ([0990e92](https://github.com/gotgenes/pi-packages/commit/0990e921868d077868b007682ffbaacc3a00cbc8)), closes [#1030](https://github.com/gotgenes/pi-packages/issues/1030)
+
+### Documentation
+
+* **pi-permission-system:** a forwarded bash line carries every asking command ([5cb6696](https://github.com/gotgenes/pi-packages/commit/5cb6696feb8572247dd6d09d4eb980292c0510f1))
+
 ## [39.1.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v39.1.0...pi-permission-system-v39.1.1) (2026-10-06)
 
 

package/dist/public.d.ts

@@ -63,6 +63,13 @@ interface PermissionCheckResult {
      * {@link floorExemption} says the wrapper's floor has no reason to hold.
      */
     executedUnit?: string;
+    /**
+     * The spelling of the bash unit the winning rule matched, when the rule did
+     * not also match the unit as typed — the absolute spelling of a relative
+     * path argument, say (#910). Display-only: absent whenever the typed text
+     * decided, and dropped by a floor that replaces {@link matchedPattern}.
+     */
+    matchedSpelling?: string;
     /**
      * Set when the winning bash unit is a wrapper the floor no longer covers,
      * naming why (#803, #963). Recorded in the review log so an allow the floor would
@@ -76,6 +83,21 @@ interface PermissionCheckResult {
      * node to clamp its own `allow` with.
      */
     floor?: string;
+    /**
+     * Every unit of the bash chain that resolved to `ask` and was not
+     * session-granted, in chain order, each with its own floor. Set only on an
+     * asking chain winner: the serving node of a forwarded ask judges each one,
+     * since the winner alone would approve commands it never saw.
+     */
+    askingUnits?: readonly AskingBashUnit[];
+}
+/**
+ * One unit of a bash chain the gate left asking, as the serving node of a
+ * forwarded ask needs it: the unit as typed, and the floor that raised it.
+ */
+interface AskingBashUnit {
+    command: string;
+    floor?: string;
 }
 
 /**
@@ -130,6 +152,12 @@ interface PromptRequestFacts {
     readonly value: string;
     /** The matched rule, including a sentinel such as `<indirection-bash-wrapper>`. */
     readonly matchedPattern: string | null;
+    /**
+     * For bash, the spelling of the unit the matched rule matched when it did not
+     * match {@link value} as typed — the absolute spelling of a relative path
+     * argument, say. `null` when the typed text decided.
+     */
+    readonly matchedSpelling: string | null;
     /**
      * Where the offending bash unit runs, when it came from a substitution or a
      * subshell. A fact rather than a rendered clause: it is what makes the
@@ -385,6 +413,14 @@ interface ForwardedAccessFacts {
      * than recomputing it. Absent when no floor was raised.
      */
     floor?: string;
+    /**
+     * Every unit of a bash chain the child left asking, each with its own floor.
+     * `matchValues` names only the chain's winner, and the serving node's answer
+     * approves the whole tool call, so it judges each of these instead. Absent
+     * for a non-bash ask and for a bash ask raised without a chain (the empty
+     * parse), where `matchValues` is the whole command.
+     */
+    askingUnits?: AskingBashUnit[];
 }
 
 type PermissionReviewSource = "tool_call" | "skill_input" | "skill_read";

package/docs/configuration.md

@@ -453,6 +453,41 @@ Control-flow bodies (`if`/`while`/`for`/`case`) and `{ … }` brace groups are n
 
 A command that starts with `~`, `$HOME`, or `${HOME}` also matches a home-anchored pattern spelled any of those ways, or with the absolute home directory (see [Home Directory Expansion in Patterns](#home-directory-expansion-in-patterns)).
 
+A path argument also matches in its absolute spelling.
+Each command is matched as typed and with every path argument replaced by the absolute path it resolves to, against the working directory a literal `cd` earlier in the chain moved to.
+The last rule matching either text wins, as for any other pattern.
+
+```jsonc
+{
+  "permission": {
+    "bash": {
+      "*": "allow",
+      "rm *": "ask",
+      "rm /tmp/agent-builds/*": "allow"
+    }
+  }
+}
+```
+
+With this policy, `cd /tmp && rm agent-builds/x` runs, because `rm agent-builds/x` is also matched as `rm /tmp/agent-builds/x`.
+An absolute `deny` reaches the relative spelling the same way.
+An absolute `allow` written *before* the broader `ask` still loses to it.
+
+Some arguments get no absolute spelling and are matched as typed only:
+
+- an argument after a `cd` whose target is not literal (`cd "$DIR"`, `cd -`, a bare `cd`), since the directory is not known;
+- an argument holding a glob (`*`, `?`, `[`), quoted or not;
+- an argument a variable or substitution computes (`$DIR/x`, `$(pwd)/x`);
+- a bare name such as `config.json` that names nothing on disk;
+- a POSIX absolute path on Windows (`/tmp/x`), which is kept as typed.
+
+The absolute spelling replaces every path argument of a command at once, and it is separate from the home spelling above.
+A rule naming one argument absolute and another relative, or naming both the expanded home and an absolute argument, matches neither text.
+A quoted argument is spelled without its quotes (`rm "a b/c"` is also matched as `rm /tmp/a b/c`).
+Whether an argument is a path is decided by its shape, so a slash-bearing word that is not one is spelled too: `git push origin feature/x` is also matched as `git push origin <cwd>/feature/x`, which only a rule naming that absolute form would match.
+When the spelling is what a rule matched, the prompt shows it on a `matched as` line beside the rule, and the review log records it as `matchedSpelling`.
+A session approval still records the command as typed, so approving `rm agent-builds/x` does not cover a later `rm /tmp/agent-builds/x`.
+
 A leading environment-variable assignment prefix is stripped before matching, so the rule gates the underlying command rather than the prefix.
 So `AWS_PROFILE=prod aws ec2 …` is matched as `aws ec2 …` — a `aws *` rule applies even though the invocation begins with `AWS_PROFILE=`.
 Prefixes like `PGPASSWORD=` and `KUBECONFIG=` are handled the same way.
@@ -541,6 +576,7 @@ Approving one for the session works normally: the floors clamp the decision and
 A subagent's floored ask keeps its floor when it is forwarded to the parent session.
 The parent's `allow` rule does not answer it, so `sudo rm x` from a subagent prompts in the parent even under a parent `bash: *` allow.
 The parent's `deny` still denies, and a grant for the whole parent session or the parent's `yoloMode` still approves.
+A subagent's chained command (`ls && rm -rf /tmp/x`) is judged by the parent command by command: every command the subagent's own policy left asking is forwarded with its floor, and the parent's `deny` or `ask` on any one of them decides, not only on the first.
 
 Because of this, set an explicit `bash` policy rather than relying on a permissive top-level `*`.
 A config whose top-level `*` is `"allow"` with no `bash` `*` policy lets every bash command silently inherit `allow`; the extension emits a startup warning in that case.

package/docs/cross-extension-api.md

@@ -428,16 +428,17 @@ Forwarding is orthogonal to origin: a forwarded subagent prompt keeps its origin
 The facts every render of the ask shows, that no renderer's budget may elide.
 Nested rather than flattened so the event and the prompt payload share one shape: a fact added here reaches the bus without a second hand-maintained declaration.
 
-| Field             | Type                         | Description                                                                                      |
-| ----------------- | ---------------------------- | ------------------------------------------------------------------------------------------------ |
-| `requester`       | `PromptRequester`            | Who is asking, and whether the ask arrived from a subagent                                       |
-| `surface`         | `string`                     | The **gate** surface the rule fired on — `"external_directory"`, `"path"`, `"bash"`, a tool name |
-| `toolName`        | `string \| null`             | The gated tool name; `null` when the ask is not tool-shaped                                      |
-| `invokedToolName` | `string \| null`             | The invoked name when a shell alias re-exposes bash under another name                           |
-| `value`           | `string`                     | The decision-relevant value: the command, path, MCP target, or skill name                        |
-| `matchedPattern`  | `string \| null`             | The matched rule, including a sentinel such as `<indirection-bash-wrapper>`                      |
-| `commandContext`  | `BashCommandContext \| null` | Where the offending bash unit runs, when it came from a substitution or subshell                 |
-| `executedUnit`    | `string \| null`             | For bash, the unit that will actually run, including inside an unstrippable wrapper              |
+| Field             | Type                         | Description                                                                                        |
+| ----------------- | ---------------------------- | -------------------------------------------------------------------------------------------------- |
+| `requester`       | `PromptRequester`            | Who is asking, and whether the ask arrived from a subagent                                         |
+| `surface`         | `string`                     | The **gate** surface the rule fired on — `"external_directory"`, `"path"`, `"bash"`, a tool name   |
+| `toolName`        | `string \| null`             | The gated tool name; `null` when the ask is not tool-shaped                                        |
+| `invokedToolName` | `string \| null`             | The invoked name when a shell alias re-exposes bash under another name                             |
+| `value`           | `string`                     | The decision-relevant value: the command, path, MCP target, or skill name                          |
+| `matchedPattern`  | `string \| null`             | The matched rule, including a sentinel such as `<indirection-bash-wrapper>`                        |
+| `matchedSpelling` | `string \| null`             | For bash, the spelling of the command the rule matched, when it did not match the command as typed |
+| `commandContext`  | `BashCommandContext \| null` | Where the offending bash unit runs, when it came from a substitution or subshell                   |
+| `executedUnit`    | `string \| null`             | For bash, the unit that will actually run, including inside an unstrippable wrapper                |
 
 `PromptRequester` carries `agentName` (`string | null`), `forwarded` (`boolean`), and `sessionId` (`string | null`, the requesting session for a forwarded ask).
 

package/docs/subagent-integration.md

@@ -148,6 +148,7 @@ When `@gotgenes/pi-permission-system` is not installed, an implementation emits
 When a delegated or routed subagent cannot decide an `ask` where it runs — because it has no UI of its own, or because it names a parent session that is answering for it — the confirmation request is forwarded through Pi session directories instead.
 The main interactive session polls for forwarded requests, shows the confirmation prompt, writes the response, and the subagent resumes once that decision is available.
 A parent `allow`/`deny` rule governs a child's escalation directly (the serving node resolves it as recorded authority before prompting), and a "whole session" grant recorded on the parent auto-approves later forwards of the same pattern.
+For a chained bash command, the parent judges every command the child left asking, not only the first, and the most restrictive answer decides.
 The exception is a bash ask the child raised through a [synthetic floor](configuration.md#fail-closed-behavior) (a wrapper such as `sudo` or `bash -c`, or a command the parser could not resolve): the child forwards the floor with the ask, and a parent `allow` rule escalates it to the parent's prompt instead of approving it.
 
 This keeps `ask` policies usable even when the original permission check happens inside a non-UI execution context.

package/package.json

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

package/src/access-intent/bash/bash-path-resolver.ts

@@ -7,6 +7,7 @@ import {
 import { normalizePathPolicyLiteral } from "#src/access-intent/path-normalization";
 import type { PathNormalizer } from "#src/path/path-normalizer";
 import { isSafeSystemPath } from "#src/path/safe-system-paths";
+import type { ArgumentSpeller } from "./command-enumeration";
 import {
   ARG_NODE_TYPES,
   SKIP_SUBTREE_TYPES,
@@ -26,6 +27,7 @@ import {
   collectRedirectTokens,
   extractCommandName,
   type PathToken,
+  type SourceSpan,
   type TokenRole,
 } from "./token-collection";
 
@@ -46,15 +48,13 @@ type EffectiveBase =
   | { readonly kind: "unknown" };
 
 /**
- * A path-candidate token paired with the effective working directory projected
- * onto the point in the command stream where it appears, the effect its
- * position proved, and the role its collector gave it.
+ * A collected {@link PathToken} — its text, the effect its position proved,
+ * the role its collector gave it, and its source span when it is a whole
+ * argument — paired with the effective working directory projected onto the
+ * point in the command stream where it appears.
  */
-interface PathCandidate {
-  readonly token: string;
+interface PathCandidate extends PathToken {
   readonly base: EffectiveBase;
-  readonly effect: TokenEffect;
-  readonly role: TokenRole;
 }
 
 /** A promoted bare token and its resolved path, before an effect is attached. */
@@ -89,6 +89,12 @@ export interface ResolvedBashPaths {
   readonly externalAccesses: readonly BashExternalPath[];
   /** Every path-rule token paired with its cd-aware policy values (#393). */
   readonly ruleCandidates: readonly BashPathRuleCandidate[];
+  /**
+   * The absolute spelling of each primary-tree argument node a rule candidate
+   * resolved to an absolute path, for the command enumerator to spell a unit
+   * with (#910). See {@link BashPathResolver.resolve} for what is left out.
+   */
+  readonly argumentSpellings: ArgumentSpeller;
 }
 
 // ── Walk-time constants ──────────────────────────────────────────────────────
@@ -155,6 +161,11 @@ export class BashPathResolver {
    * A token spelled from a `HOME` the program rebinds leaves both slices before
    * projection: path normalization would otherwise expand its `~`/`$HOME` prefix
    * to the startup home, naming a directory the shell never touches.
+   *
+   * The argument spellings come from the same projection as the rule
+   * candidates, keyed by the source span of a whole-argument token. A salvaged
+   * fragment's tokens carry no span, because its indices are its own re-parse's
+   * and would collide with the primary tree's.
    */
   resolve(
     rootNode: TSNode,
@@ -166,16 +177,21 @@ export class BashPathResolver {
         : this.deriveBaseFromCdTarget(CWD_BASE, this.workdir);
     const collected = this.collectPathCandidates(rootNode, initialBase);
     for (const salvaged of salvagedRoots) {
-      this.walkForCandidates(salvaged, UNKNOWN_BASE, collected);
+      const fragment: PathCandidate[] = [];
+      this.walkForCandidates(salvaged, UNKNOWN_BASE, fragment);
+      collected.push(...fragment.map(withoutSpan));
     }
     const candidates = collected.filter(
       ({ token }) => !this.words.spellsReboundHome(token),
     );
+    const { ruleCandidates, argumentSpellings } =
+      this.projectRuleCandidates(candidates);
     return {
       externalAccesses: this.withWorkdirExternal(
         this.projectExternalPaths(candidates),
       ),
-      ruleCandidates: this.projectRuleCandidates(candidates),
+      ruleCandidates,
+      argumentSpellings,
     };
   }
 
@@ -575,13 +591,15 @@ export class BashPathResolver {
    * A token after a non-literal `cd` keeps only its literal value so no
    * spurious absolute rule can match (#393).
    */
-  private projectRuleCandidates(
-    candidates: readonly PathCandidate[],
-  ): BashPathRuleCandidate[] {
+  private projectRuleCandidates(candidates: readonly PathCandidate[]): {
+    ruleCandidates: BashPathRuleCandidate[];
+    argumentSpellings: ArgumentSpeller;
+  } {
     const seen = new Map<string, number>();
     const result: BashPathRuleCandidate[] = [];
+    const spellings = new Map<string, string>();
 
-    for (const { token, base, effect, role } of candidates) {
+    for (const { token, base, effect, role, span } of candidates) {
       const shaped = admittedByRole(role)
         ? token
         : classifyTokenAsRuleCandidate(token, this.normalizer.flavor);
@@ -594,6 +612,11 @@ export class BashPathResolver {
       const matchValues = probed.path.matchValues();
       if (matchValues.length === 0) continue;
 
+      // Recorded per occurrence, ahead of the fold below, so `cp a/x a/x`
+      // spells both words rather than the first.
+      const spelling = span && this.absoluteSpellingOf(token, probed.path);
+      if (spelling) spellings.set(spanKey(span), spelling);
+
       const key = matchValues.join("\0");
       const index = seen.get(key);
       if (index !== undefined) {
@@ -611,7 +634,35 @@ export class BashPathResolver {
       result.push({ ...probed, effect });
     }
 
-    return result;
+    return {
+      ruleCandidates: result,
+      argumentSpellings: {
+        absoluteSpellingOf: (node) =>
+          spellings.get(
+            spanKey({ start: node.startIndex, end: node.endIndex }),
+          ),
+      },
+    };
+  }
+
+  /**
+   * The absolute spelling of a whole-argument token, or `undefined` when giving
+   * one would invent rather than resolve.
+   *
+   * Absolute only: a token after a non-literal `cd` resolves to its literal,
+   * which is not absolute, so the check that keeps the spelling absolute is
+   * also what keeps that token unspelled (#393). A glob is never spelled,
+   * quoted or not — what it names is decided by expanding it (#822) — and a
+   * token already spelled as it resolves needs no second spelling.
+   */
+  private absoluteSpellingOf(
+    token: string,
+    path: AccessPath,
+  ): string | undefined {
+    if (GLOB_CHARACTERS.test(token)) return undefined;
+    const spelling = path.value();
+    if (!spelling || spelling === token) return undefined;
+    return this.normalizer.isAbsolute(spelling) ? spelling : undefined;
   }
 
   /**
@@ -683,6 +734,24 @@ export class BashPathResolver {
 
 // ── Pure AST/string helpers ──────────────────────────────────────────────────
 
+/** A character that makes the shell expand a word against the filesystem. */
+const GLOB_CHARACTERS = /[*?[]/;
+
+/** The key an argument spelling is filed under: its node's source span. */
+function spanKey({ start, end }: SourceSpan): string {
+  return `${start}:${end}`;
+}
+
+/** A salvaged candidate, which carries no span in the primary tree's coordinates. */
+function withoutSpan({
+  token,
+  effect,
+  role,
+  base,
+}: PathCandidate): PathCandidate {
+  return { token, effect, role, base };
+}
+
 /**
  * True when the statement at `index` is immediately followed by the background
  * operator (`&`) — distinct from the `&&` / `||` / `;` current-shell
@@ -699,8 +768,8 @@ function tagTokens(
   base: EffectiveBase,
   out: PathCandidate[],
 ): void {
-  for (const { token, effect, role } of tokens) {
-    out.push({ token, base, effect, role });
+  for (const token of tokens) {
+    out.push({ ...token, base });
   }
 }
 

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

@@ -77,13 +77,28 @@ export interface BashCommand {
    * Other spellings of {@link text} the shell runs identically, matched with
    * it as aliases of one invocation. Absent when there are none.
    *
-   * Today the only spelling is the home-expanded one, for a unit whose text
-   * opens with `~`, `$HOME`, or `${HOME}` in a program that leaves `HOME`
-   * alone ({@link WordReader.spellHomeAtStart}).
+   * Two producers supply them, each spelling the text on its own: the
+   * home-expanded spelling of a unit whose text opens with `~`, `$HOME`, or
+   * `${HOME}` in a program that leaves `HOME` alone
+   * ({@link WordReader.spellHomeAtStart}), and the argument spelling, in which
+   * every argument word the {@link ArgumentSpeller} resolved to an absolute
+   * path is replaced by that path (#910).
    */
   readonly spellings?: readonly string[];
 }
 
+/**
+ * What the enumerator asks about one argument word of a unit: the absolute
+ * spelling of the path it names, as the party that resolved the program's
+ * paths knows it, or `undefined` when there is none to give.
+ *
+ * Asked by node rather than by text, because only the node says which
+ * occurrence of a token a unit's word is.
+ */
+export interface ArgumentSpeller {
+  absoluteSpellingOf(node: TSNode): string | undefined;
+}
+
 /**
  * What the statement enclosing a command unit establishes about it.
  *
@@ -119,16 +134,27 @@ interface UnitScope {
    * program's variables are the same wherever in it a word sits.
    */
   readonly words: WordReader;
+  /**
+   * What an argument word's absolute spelling is, from the party that resolved
+   * the program's paths. Relayed unchanged, including into nested executions:
+   * it answers by node, so each unit asks about its own words. Absent for a
+   * salvaged region, whose nodes are not the primary tree's.
+   */
+  readonly speller?: ArgumentSpeller;
 }
 
 /** A top-level command in the current shell, writing no file, fully parsed. */
-function topLevelScope(words: WordReader): UnitScope {
-  return {
+function topLevelScope(
+  words: WordReader,
+  speller: ArgumentSpeller | undefined,
+): UnitScope {
+  const scope: UnitScope = {
     writesViaRedirect: false,
     parseUnresolved: false,
     salvaged: false,
     words,
   };
+  return speller === undefined ? scope : { ...scope, speller };
 }
 
 /**
@@ -267,9 +293,10 @@ const STATEMENT_TYPES = new Set([
 export function collectCommands(
   node: TSNode,
   words: WordReader,
+  speller?: ArgumentSpeller,
 ): BashCommand[] {
   const out: BashCommand[] = [];
-  collectCommandsInto(node, topLevelScope(words), out);
+  collectCommandsInto(node, topLevelScope(words, speller), out);
   return out;
 }
 
@@ -462,10 +489,12 @@ function makeUnit(
  * surely as one on the enclosing statement.
  */
 function makeCommandUnit(node: TSNode, scope: UnitScope): BashCommand {
-  const { text, words } = readCommandUnit(node, scope.words);
-  const homeSpelling = scope.words.spellHomeAtStart(text);
+  const { text, words, argumentSpelling } = readCommandUnit(node, scope);
   return makeUnit(text, scope, {
-    spellings: homeSpelling === undefined ? undefined : [homeSpelling],
+    spellings: distinctSpellings(text, [
+      scope.words.spellHomeAtStart(text),
+      argumentSpelling,
+    ]),
     wrapperKind: classifyWrapperWords(words),
     executedUnit: executedUnitOf(text, words) ?? undefined,
     floorExemption: floorExemptionOf(words, redirectedScope(node, scope)),
@@ -520,10 +549,11 @@ function redirectedScope(node: TSNode, scope: UnitScope): UnitScope {
  */
 function readCommandUnit(
   node: TSNode,
-  reader: WordReader,
+  scope: UnitScope,
 ): {
   text: string;
   words: CommandWord[];
+  argumentSpelling?: string;
 } {
   const nodes = commandWordNodes(node);
   if (nodes.length === 0) return { text: node.text, words: [] };
@@ -531,18 +561,47 @@ function readCommandUnit(
   const redirects = hostedRedirects(node);
   const words: CommandWord[] = [];
   let text = "";
+  let spelled = "";
+  let respelled = false;
   let previous: TSNode | undefined;
   for (const word of nodes) {
-    if (previous) text += gapBetween(node, previous, word, redirects);
-    words.push({
-      ...reader.argWord(word),
-      text: word.text,
-      offset: text.length,
-    });
+    if (previous) {
+      const gap = gapBetween(node, previous, word, redirects);
+      text += gap;
+      spelled += gap;
+    }
+    const argWord = scope.words.argWord(word);
+    words.push({ ...argWord, text: word.text, offset: text.length });
     text += word.text;
+    const spelling = argWord.computed
+      ? undefined
+      : scope.speller?.absoluteSpellingOf(word);
+    respelled ||= spelling !== undefined;
+    spelled += spelling ?? word.text;
     previous = word;
   }
-  return { text, words };
+  return respelled
+    ? { text, words, argumentSpelling: spelled }
+    : { text, words };
+}
+
+/**
+ * The spellings that differ from `text`, each once, or `undefined` when none
+ * does — so a unit with nothing to respell keeps the shape it had.
+ */
+function distinctSpellings(
+  text: string,
+  candidates: readonly (string | undefined)[],
+): readonly string[] | undefined {
+  const spellings = [
+    ...new Set(
+      candidates.filter(
+        (spelling): spelling is string =>
+          spelling !== undefined && spelling !== text,
+      ),
+    ),
+  ];
+  return spellings.length === 0 ? undefined : spellings;
 }
 
 /**
@@ -670,6 +729,7 @@ function collectHostedCommands(
         parseUnresolved: false,
         salvaged: scope.salvaged,
         words: scope.words,
+        speller: scope.speller,
       },
       out,
     );

package/src/access-intent/bash/program.ts

@@ -10,7 +10,7 @@ import {
   collectSalvagedCommands,
 } from "./command-enumeration";
 import { WordReader } from "./node-text";
-import { getParser } from "./parser";
+import { type BashReparser, getParser, getWarmBashParser } from "./parser";
 import { ShellVariables } from "./shell-variable-expansion";
 import { withSalvagedRoots } from "./unresolved-salvage";
 
@@ -58,7 +58,33 @@ export class BashProgram {
     normalizer: PathNormalizer,
     options?: { workdir?: string },
   ): Promise<BashProgram> {
-    const parser = await getParser();
+    return BashProgram.build(await getParser(), command, normalizer, options);
+  }
+
+  /**
+   * Parse a bash command synchronously over the warmed parser, or answer `null`
+   * in the pre-warm window so the caller can fall back rather than block.
+   *
+   * Builds exactly the program {@link parse} builds; the service's advisory
+   * query uses it so its answer resolves the same slices the gate does (#309).
+   */
+  static parseSync(
+    command: string,
+    normalizer: PathNormalizer,
+    options?: { workdir?: string },
+  ): BashProgram | null {
+    const parser = getWarmBashParser();
+    if (!parser) return null;
+    return BashProgram.build(parser, command, normalizer, options);
+  }
+
+  /** Parse `command` with `parser` and resolve every slice synchronously. */
+  private static build(
+    parser: BashReparser,
+    command: string,
+    normalizer: PathNormalizer,
+    options?: { workdir?: string },
+  ): BashProgram {
     const tree = parser.parse(command);
     if (!tree) return new BashProgram(command, [], [], []);
 
@@ -67,15 +93,15 @@ export class BashProgram {
         const words = new WordReader(
           ShellVariables.scan([tree.rootNode, ...salvaged]),
         );
-        const { externalAccesses, ruleCandidates } = new BashPathResolver(
-          normalizer,
-          words,
-          options?.workdir,
-        ).resolve(tree.rootNode, salvaged);
+        const { externalAccesses, ruleCandidates, argumentSpellings } =
+          new BashPathResolver(normalizer, words, options?.workdir).resolve(
+            tree.rootNode,
+            salvaged,
+          );
         return new BashProgram(
           command,
           [
-            ...collectCommands(tree.rootNode, words),
+            ...collectCommands(tree.rootNode, words, argumentSpellings),
             ...salvaged.flatMap((root) => collectSalvagedCommands(root, words)),
           ],
           externalAccesses,