@gotgenes/pi-permission-system 39.1.2 → 40.0.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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)
 
 

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
@@ -145,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

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.

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "39.1.2",
+  "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,

package/src/access-intent/bash/token-collection.ts

@@ -39,6 +39,19 @@ export interface PathToken {
   readonly token: string;
   readonly effect: TokenEffect;
   readonly role: TokenRole;
+  /**
+   * The source span of the argument node, set only when {@link token} is that
+   * whole node's resolved text. A token read from part of an argument (an
+   * option's embedded value, a script file glued to its flag) carries none, so
+   * nothing keyed on the span can mistake it for the whole word.
+   */
+  readonly span?: SourceSpan;
+}
+
+/** Where a node sits in the parsed source: `startIndex` to `endIndex`. */
+export interface SourceSpan {
+  readonly start: number;
+  readonly end: number;
 }
 
 // ── Public surface ─────────────────────────────────────────────────────────
@@ -160,7 +173,7 @@ export function collectRedirectTokens(
           i === target && provesTarget(effect, child, token, words)
             ? "redirect-destination"
             : "operand";
-        tokens.push({ token, effect, role });
+        tokens.push(wholeArgumentToken(child, token, effect, role));
       }
     }
     tokens.push(...collectHostedExecutionTokens(child, words));
@@ -271,11 +284,9 @@ function collectStatementOperandTokens(
       tokens.push(...collectPathCandidateTokens(child, words));
       continue;
     }
-    tokens.push({
-      token: words.text(child),
-      effect: UNPROVEN_EFFECT,
-      role: "operand",
-    });
+    tokens.push(
+      wholeArgumentToken(child, words.text(child), UNPROVEN_EFFECT, "operand"),
+    );
     tokens.push(...collectHostedExecutionTokens(child, words));
   }
   return tokens;
@@ -833,7 +844,12 @@ function collectPatternCommandTokens(
         tokens.push(...collectPathCandidateTokens(child, words));
         continue;
       }
-      const discharge = dischargePendingConsumption(consumption, text, effect);
+      const discharge = dischargePendingConsumption(
+        consumption,
+        child,
+        text,
+        effect,
+      );
       if (discharge.token) tokens.push(discharge.token);
       if (discharge.consumed) continue;
     }
@@ -907,7 +923,7 @@ function collectPatternCommandTokens(
     if (!hasExplicitScript && positionalsSeen < patternPositionals) {
       positionalsSeen++; // Skip: this is an inline pattern/script.
     } else {
-      tokens.push({ token: text, effect, role: "operand" });
+      tokens.push(wholeArgumentToken(child, text, effect, "operand"));
     }
     // A quoted token that did not act as a flag above has its embedded value
     // split here instead.
@@ -957,6 +973,7 @@ interface ConsumptionDischarge {
 /** Apply a pending consumption to the argument text that follows its flag. */
 function dischargePendingConsumption(
   role: PatternFlagRole,
+  argument: TSNode,
   text: string,
   effect: TokenEffect,
 ): ConsumptionDischarge {
@@ -964,7 +981,7 @@ function dischargePendingConsumption(
     case "script-file":
       return {
         consumed: true,
-        token: { token: text, effect, role: "operand" },
+        token: wholeArgumentToken(argument, text, effect, "operand"),
       };
     case "script":
     case "value":
@@ -1015,7 +1032,9 @@ function collectGenericCommandTokens(
 
     // Argument nodes: resolve their text and collect.
     if (ARG_NODE_TYPES.has(child.type)) {
-      tokens.push({ token: words.text(child), effect, role: "operand" });
+      tokens.push(
+        wholeArgumentToken(child, words.text(child), effect, "operand"),
+      );
       continue;
     }
 
@@ -1025,3 +1044,21 @@ function collectGenericCommandTokens(
 
   return tokens;
 }
+
+/**
+ * A token that is `node`'s whole resolved text, carrying the node's source span
+ * so a reader of the span knows the token stands for the entire word.
+ */
+function wholeArgumentToken(
+  node: TSNode,
+  token: string,
+  effect: TokenEffect,
+  role: TokenRole,
+): PathToken {
+  return {
+    token,
+    effect,
+    role,
+    span: { start: node.startIndex, end: node.endIndex },
+  };
+}

package/src/handlers/gates/bash-command.ts

@@ -228,14 +228,16 @@ function floorUnparsedUnit(
  * it.
  *
  * Spreads `resolved`, so a `source: "session"` grant survives to `GateRunner`'s
- * session fast path.
+ * session fast path. Drops `matchedSpelling`: it names what the replaced rule
+ * matched, and beside the sentinel it would name a match that did not decide.
  */
 function floorToAsk(
   resolved: PermissionCheckResult,
   sentinel: string,
 ): PermissionCheckResult {
+  const { matchedSpelling: _replaced, ...unspelled } = resolved;
   return {
-    ...resolved,
+    ...unspelled,
     state: "ask",
     matchedPattern: sentinel,
     floor: sentinel,

package/src/logging/command-redaction.ts

@@ -42,6 +42,7 @@ import { isSensitiveName, REDACTED_PLACEHOLDER } from "./log-redaction";
 export const COMMAND_BEARING_LOG_KEYS: ReadonlySet<string> = new Set([
   "command",
   "executedUnit",
+  "matchedSpelling",
 ]);
 
 /** A range of the command to replace, and what to put in its place. */

package/src/policy/permission-manager.ts

@@ -376,7 +376,7 @@ export class PermissionManager implements ScopedPermissionManager {
         intent.command,
         intent.spellings,
       );
-      return buildCheckResult(
+      const { result, matchedValue } = evaluateCheck(
         surface,
         values,
         resultExtras,
@@ -385,6 +385,12 @@ export class PermissionManager implements ScopedPermissionManager {
         fullRules,
         this.flavor,
       );
+      // `values[0]` is the unit as typed, and the evaluator reports the first
+      // value the winning rule matches, so any other value is a spelling the
+      // typed text did not match.
+      return matchedValue === values[0]
+        ? result
+        : { ...result, matchedSpelling: matchedValue };
     }
 
     // kind === "tool"
@@ -423,6 +429,30 @@ function buildCheckResult(
   fullRules: Ruleset,
   flavor: PathFlavor,
 ): PermissionCheckResult {
+  return evaluateCheck(
+    surface,
+    values,
+    resultExtras,
+    normalizedToolName,
+    toolName,
+    fullRules,
+    flavor,
+  ).result;
+}
+
+/**
+ * {@link buildCheckResult}, plus the candidate value the decision was reported
+ * under — for a caller that knows what that value means on its own surface.
+ */
+function evaluateCheck(
+  surface: string,
+  values: string[],
+  resultExtras: Record<string, unknown>,
+  normalizedToolName: string,
+  toolName: string,
+  fullRules: Ruleset,
+  flavor: PathFlavor,
+): { result: PermissionCheckResult; matchedValue: string } {
   const { rule, value } = evaluateAnyValue(surface, values, fullRules, flavor);
 
   // For MCP, replace the normalizer's fallback target with the actual
@@ -433,16 +463,19 @@ function buildCheckResult(
       : resultExtras;
 
   return {
-    toolName,
-    state: rule.action,
-    reason: rule.reason,
-    matchedPattern:
-      rule.layer === "config" || rule.layer === "session"
-        ? rule.pattern
-        : undefined,
-    source: deriveSource(rule, normalizedToolName),
-    origin: rule.origin,
-    ...extras,
+    result: {
+      toolName,
+      state: rule.action,
+      reason: rule.reason,
+      matchedPattern:
+        rule.layer === "config" || rule.layer === "session"
+          ? rule.pattern
+          : undefined,
+      source: deriveSource(rule, normalizedToolName),
+      origin: rule.origin,
+      ...extras,
+    },
+    matchedValue: value,
   };
 }
 

package/src/presentation/dialog-renderer.ts

@@ -222,6 +222,9 @@ function coreFacts(payload: PromptPayload): Fact[] {
   if (request.matchedPattern !== null) {
     facts.push({ label: "rule", text: request.matchedPattern });
   }
+  if (request.matchedSpelling !== null) {
+    facts.push({ label: "matched as", text: request.matchedSpelling });
+  }
   if (request.value !== "" && request.value !== request.toolName) {
     facts.push({ label, text: request.value });
   }

package/src/presentation/forwarded-ask-payload.ts

@@ -56,6 +56,7 @@ function degradedForwardedPayload(
       value: request.value ?? "",
       matchedPattern: null,
       commandContext: null,
+      matchedSpelling: null,
       executedUnit: null,
     },
     // Nothing to carry: the wire no longer relays a sentence, and inventing

package/src/presentation/path-ask-payload.ts

@@ -82,6 +82,7 @@ export function buildBashExternalDirectoryAskPayload(
       value: facts.command,
       matchedPattern: facts.matchedPattern ?? null,
       commandContext: null,
+      matchedSpelling: null,
       executedUnit: null,
     },
     evidence: [
@@ -113,6 +114,7 @@ function pathPayload(
       value: facts.pathValue,
       matchedPattern: facts.matchedPattern ?? null,
       commandContext: null,
+      matchedSpelling: null,
       executedUnit: null,
     },
     evidence,

package/src/presentation/prompt-payload.ts

@@ -63,6 +63,12 @@ export 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
@@ -172,6 +178,9 @@ function asPromptRequestFacts(value: unknown): PromptRequestFacts | undefined {
     candidate.commandContext,
     BASH_COMMAND_CONTEXTS,
   );
+  // Absent from a request a node built before the fact existed, which states
+  // no spelling rather than a malformed one.
+  const matchedSpelling = candidate.matchedSpelling ?? null;
   if (
     !requester ||
     commandContext === undefined ||
@@ -180,6 +189,7 @@ function asPromptRequestFacts(value: unknown): PromptRequestFacts | undefined {
     !isNullableString(candidate.toolName) ||
     !isNullableString(candidate.invokedToolName) ||
     !isNullableString(candidate.matchedPattern) ||
+    !isNullableString(matchedSpelling) ||
     !isNullableString(candidate.executedUnit)
   ) {
     return undefined;
@@ -192,6 +202,7 @@ function asPromptRequestFacts(value: unknown): PromptRequestFacts | undefined {
     invokedToolName: candidate.invokedToolName,
     value: candidate.value,
     matchedPattern: candidate.matchedPattern,
+    matchedSpelling,
     commandContext: commandContext.value,
     executedUnit: candidate.executedUnit,
   };

package/src/presentation/review-log-renderer.ts

@@ -25,6 +25,7 @@ export function renderReviewLogFacts(
   return {
     surface: request.surface,
     ...present("matchedPattern", request.matchedPattern),
+    ...present("matchedSpelling", request.matchedSpelling),
     ...present("executedUnit", request.executedUnit),
     ...present("commandContext", request.commandContext),
     ...present("invokedToolName", request.invokedToolName),

package/src/presentation/skill-ask-payload.ts

@@ -42,6 +42,7 @@ function skillPayload(
       value: skillName,
       matchedPattern: null,
       commandContext: null,
+      matchedSpelling: null,
       executedUnit: null,
     },
     evidence,

package/src/presentation/tool-ask-payload.ts

@@ -44,6 +44,7 @@ export function buildToolAskPayload(facts: ToolAskFacts): PromptPayload {
       invokedToolName: distinctInvokedName(facts),
       value: askValue(check, bash, mcp),
       matchedPattern: check.matchedPattern ?? null,
+      matchedSpelling: check.matchedSpelling ?? null,
       commandContext: check.commandContext ?? null,
       executedUnit: check.executedUnit ?? null,
     },

package/src/service/bash-advisory-check.ts

@@ -1,5 +1,6 @@
-import { parseBashCommandsSync } from "#src/access-intent/bash/sync-commands";
+import { BashProgram } from "#src/access-intent/bash/program";
 import { resolveBashCommandCheck } from "#src/handlers/gates/bash-command";
+import type { PathNormalizer } from "#src/path/path-normalizer";
 import type { ScopedPermissionResolver } from "#src/policy/permission-resolver";
 import type { PermissionCheckResult } from "#src/types";
 
@@ -14,7 +15,11 @@ import type { PermissionCheckResult } from "#src/types";
  * sentinels — `<unparseable-bash-command>` (#452) and `<unparsed-bash-subtree>`
  * (#840) — at parity with the gate.
  *
- * In the pre-warm window (`parseBashCommandsSync` returns `null`) it falls back
+ * The command is parsed by `BashProgram.parseSync` over the session's
+ * `normalizer`, the same builder the gate's program comes from, so every slice
+ * the gate resolves a unit with is resolved here too.
+ *
+ * In the pre-warm window (`parseSync` returns `null`) it falls back
  * to the pre-#309 whole-string match, so the advisory answer is never *weaker*
  * than before — only strengthened once warm.
  *
@@ -25,9 +30,10 @@ export function resolveBashAdvisoryCheck(
   command: string,
   agentName: string | undefined,
   resolver: ScopedPermissionResolver,
+  normalizer: PathNormalizer,
 ): PermissionCheckResult {
-  const commands = parseBashCommandsSync(command);
-  if (commands === null) {
+  const program = BashProgram.parseSync(command, normalizer);
+  if (program === null) {
     return resolver.resolve({
       kind: "tool",
       surface: "bash",
@@ -35,5 +41,10 @@ export function resolveBashAdvisoryCheck(
       agentName,
     });
   }
-  return resolveBashCommandCheck(command, commands, agentName, resolver);
+  return resolveBashCommandCheck(
+    command,
+    program.commands(),
+    agentName,
+    resolver,
+  );
 }

package/src/service/permissions-service.ts

@@ -67,7 +67,12 @@ export class LocalPermissionsService implements PermissionsService {
     // the enforcement gate enforces (#309). A cold parser falls back to the
     // whole-string match inside resolveBashAdvisoryCheck.
     if (surface === "bash") {
-      return resolveBashAdvisoryCheck(value ?? "", agentName, this.resolver);
+      return resolveBashAdvisoryCheck(
+        value ?? "",
+        agentName,
+        this.resolver,
+        this.session.getPathNormalizer(),
+      );
     }
     const intent = buildAccessIntentForSurface(
       surface,

package/src/types.ts

@@ -83,6 +83,13 @@ export 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

package/src/access-intent/bash/sync-commands.ts

@@ -1,43 +0,0 @@
-import {
-  type BashCommand,
-  collectCommands,
-  collectSalvagedCommands,
-} from "./command-enumeration";
-import { WordReader } from "./node-text";
-import { getWarmBashParser } from "./parser";
-import { ShellVariables } from "./shell-variable-expansion";
-import { withSalvagedRoots } from "./unresolved-salvage";
-
-/**
- * Synchronously enumerate the command-pattern units of a bash command using the
- * warmed tree-sitter parser.
- *
- * Returns `null` when the parser has not been warmed yet (the pre-warm window),
- * so the caller can fall back to whole-string matching rather than block. Once
- * warm it mirrors the enumeration the gate performs (`BashProgram.commands()`):
- * chains split, nested substitutions/subshells descend, opaque wrappers flagged
- * (#306). Only the command-pattern surface is produced — no path slices, so no
- * `PathNormalizer` is needed.
- *
- * An unparseable command yields an empty array (the caller's decompose path
- * fails it closed via `resolveBashCommandCheck`, #452).
- */
-export function parseBashCommandsSync(command: string): BashCommand[] | null {
-  const parser = getWarmBashParser();
-  if (!parser) return null;
-  const tree = parser.parse(command);
-  if (!tree) return [];
-  try {
-    return withSalvagedRoots(tree.rootNode, parser, (salvaged) => {
-      const words = new WordReader(
-        ShellVariables.scan([tree.rootNode, ...salvaged]),
-      );
-      return [
-        ...collectCommands(tree.rootNode, words),
-        ...salvaged.flatMap((root) => collectSalvagedCommands(root, words)),
-      ];
-    });
-  } finally {
-    tree.delete();
-  }
-}