@gotgenes/pi-permission-system 36.1.0 → 36.2.1

package/CHANGELOG.md

@@ -5,6 +5,32 @@ 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.2.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v36.2.0...pi-permission-system-v36.2.1) (2026-10-01)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** a reassigned $HOME or $PWD is no longer resolved to its startup value ([#995](https://github.com/gotgenes/pi-packages/issues/995)) ([956fa32](https://github.com/gotgenes/pi-packages/commit/956fa32ecbe6ee3b2954cebbfed8d9a44857c617)), closes [#995](https://github.com/gotgenes/pi-packages/issues/995)
+* **pi-permission-system:** a name read, printf -v, nameref, eval, or source counts as reassigning $HOME ([#995](https://github.com/gotgenes/pi-packages/issues/995)) ([a05a6d3](https://github.com/gotgenes/pi-packages/commit/a05a6d391eb0281d5977a2264aa69958ce8d7549))
+* **pi-permission-system:** ~ is no longer read as the home directory after the command reassigns HOME ([#995](https://github.com/gotgenes/pi-packages/issues/995)) ([998d51b](https://github.com/gotgenes/pi-packages/commit/998d51b36989bf0397beb4028d76e75d3e37666d))
+* **pi-permission-system:** ~ may spell an option when the inherited HOME begins with a dash ([#995](https://github.com/gotgenes/pi-packages/issues/995)) ([f1ee69a](https://github.com/gotgenes/pi-packages/commit/f1ee69a19b3f6880228da88ad2683f9b1f79a980))
+* **pi-permission-system:** a quoted export, let, trap, or quoted eval counts as reassigning $HOME ([#995](https://github.com/gotgenes/pi-packages/issues/995)) ([4406ef4](https://github.com/gotgenes/pi-packages/commit/4406ef429706aa0b7cd77ba9608d0bcb1c2982bc))
+
+### Documentation
+
+* **pi-permission-system:** record that a reassigned $HOME or $PWD is not resolved ([#995](https://github.com/gotgenes/pi-packages/issues/995)) ([e7c8b88](https://github.com/gotgenes/pi-packages/commit/e7c8b88167f05531507cdfaf584dd9e4905a0387))
+
+## [36.2.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v36.1.0...pi-permission-system-v36.2.0) (2026-09-30)
+
+
+### Features
+
+* name the session and the requested tool in prompt notifications ([#996](https://github.com/gotgenes/pi-packages/issues/996)) ([eb49c64](https://github.com/gotgenes/pi-packages/commit/eb49c6494d12749f71130d74b75c578530c89afa)), closes [#996](https://github.com/gotgenes/pi-packages/issues/996)
+
+### Documentation
+
+* describe the session and tool in prompt notifications ([#996](https://github.com/gotgenes/pi-packages/issues/996)) ([c5c74db](https://github.com/gotgenes/pi-packages/commit/c5c74db43235297a39bbe94303225ac50baf0ca4))
+
 ## [36.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v36.0.0...pi-permission-system-v36.1.0) (2026-09-30)
 
 

package/docs/configuration.md

@@ -208,7 +208,17 @@ The two OSC forms raise a desktop notification in terminals that implement them;
 
 Channels are written in the order listed.
 The list is empty by default, so nothing is emitted until you set it; an unknown channel name is a validation error like any other malformed field.
-The notification text is the dialog title (`Permission Required`, or `Permission Required (Subagent)` for a forwarded ask), never the command or path being decided, so nothing from the request lands in your notification history.
+The notification names the session and what is being asked, so it tells you which pane to go to.
+Its title is `pi — <session name>`, or `pi — <directory name>` for a session without a name.
+Its body is the dialog title followed by the tool (or, for an ask that is not a tool call, the gate surface) and the requesting agent when there is one:
+
+| Ask                                         | `osc777` title       | `osc777` body                                  |
+| ------------------------------------------- | -------------------- | ---------------------------------------------- |
+| local `bash` ask in session `refactor-auth` | `pi — refactor-auth` | `Permission Required: bash`                    |
+| `read` forwarded from subagent `scout`      | `pi — refactor-auth` | `Permission Required (Subagent): read (scout)` |
+
+OSC 9 has a single text field, so `osc9` writes the title ahead of the body: `pi — refactor-auth: Permission Required: bash`.
+The notification carries labels only, never the command, path, MCP target, or skill being decided, so nothing the request holds lands in your notification history.
 
 The signal fires once per prompt, when the prompt is actually shown.
 A second ask that waits behind an open dialog signals when its own turn comes, and a forwarded subagent ask signals in the parent session that shows it.
@@ -775,11 +785,11 @@ Quoting is understood, so `ls "$HOME/x"` and `ls $HOME/x` are treated alike.
 What the bash projection resolves:
 
 - Absolute, home-relative (`~/`), parent-traversal (`../`), and separator-bearing tokens, plus redirect targets (`> out.txt`, including a file the redirect creates) and values embedded in long options (`--file=/tmp/patterns`).
-- The plain shell variables `$HOME` / `${HOME}` and `$PWD` / `${PWD}`, so `$HOME/x` is gated exactly as `~/x` and the literal absolute spelling, whether or not the target exists.
+- The plain shell variables `$HOME` / `${HOME}` and `$PWD` / `${PWD}`, so `$HOME/x` is gated exactly as `~/x` and the literal absolute spelling, whether or not the target exists, as long as the command does not reassign them.
 - Relative tokens, against the working directory produced by folding literal current-shell `cd` commands.
 - A bare token (`cat id_rsa`) when it names an existing filesystem entry.
 
-What it deliberately does not resolve: any other variable (`$CONFIG_DIR`), a command substitution (`$(cmd)`), an expansion carrying an operator (`${HOME:-/tmp}`), and a variable reached through an assignment (`CURRENT="$HOME"; ls "$CURRENT"`).
+What it deliberately does not resolve: any other variable (`$CONFIG_DIR`), a command substitution (`$(cmd)`), an expansion carrying an operator (`${HOME:-/tmp}`), a variable reached through an assignment (`CURRENT="$HOME"; ls "$CURRENT"`), and `$HOME`, `$PWD`, or a leading `~` in a command that reassigns the variable anywhere (`HOME=/etc; cat "$HOME/shadow"`), including through `read`, `unset`, `eval`, or `source`.
 A non-literal `cd` (`cd "$DIR"`) makes the working directory unknown, after which relative tokens are kept literal rather than resolved against a guess.
 Commands whose payload is opaque (`bash -c`, `eval`, `sudo`, `xargs`) are floored to `ask` instead of projected.
 The governing record is [ADR 0009](https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/decisions/0009-bash-path-projection-completeness-contract.md), which states what the projection guarantees and which gaps are accepted residuals rather than bugs.

package/package.json

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

package/schemas/permissions.schema.json

@@ -70,7 +70,7 @@
     },
     "promptNotifications": {
       "description": "Terminal notifications to emit when the inline permission dialog opens: bell (BEL), osc9 (OSC 9 notification), osc777 (OSC 777 notification). Omit or leave empty for none. TUI sessions only.",
-      "markdownDescription": "Terminal notifications to emit when the inline permission dialog opens, so a terminal or multiplexer can flag a session waiting on a decision.\n\n- `\"bell\"` writes a BEL — what tmux `monitor-bell` and most terminals react to.\n- `\"osc9\"` writes an OSC 9 desktop notification.\n- `\"osc777\"` writes an OSC 777 desktop notification.\n\nOmit or leave empty for none (the default). Applies to interactive **TUI** sessions only; the notification text is the dialog title, never the request itself.",
+      "markdownDescription": "Terminal notifications to emit when the inline permission dialog opens, so a terminal or multiplexer can flag a session waiting on a decision.\n\n- `\"bell\"` writes a BEL — what tmux `monitor-bell` and most terminals react to.\n- `\"osc9\"` writes an OSC 9 desktop notification.\n- `\"osc777\"` writes an OSC 777 desktop notification.\n\nOmit or leave empty for none (the default). Applies to interactive **TUI** sessions only. The notification names the session and the requested tool and agent, never the command, path, or other value being decided.",
       "default": [],
       "type": "array",
       "items": {

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

@@ -7,7 +7,11 @@ 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 { ARG_NODE_TYPES, SKIP_SUBTREE_TYPES } from "./node-text";
+import {
+  ARG_NODE_TYPES,
+  SKIP_SUBTREE_TYPES,
+  type WordReader,
+} from "./node-text";
 import type { TSNode } from "./parser";
 import { REDIRECT_NODE_TYPES } from "./redirect-analysis";
 import {
@@ -121,6 +125,7 @@ const UNKNOWN_BASE: EffectiveBase = { kind: "unknown" };
 export class BashPathResolver {
   constructor(
     private readonly normalizer: PathNormalizer,
+    private readonly words: WordReader,
     private readonly workdir?: string,
   ) {}
 
@@ -146,6 +151,10 @@ export class BashPathResolver {
    * could then allow this access. #393's unknown base declines the claim
    * instead, keeping an absolute token literal-only and unconditionally
    * external while a relative one is not projected at all.
+   *
+   * 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.
    */
   resolve(
     rootNode: TSNode,
@@ -155,10 +164,13 @@ export class BashPathResolver {
       this.workdir === undefined
         ? CWD_BASE
         : this.deriveBaseFromCdTarget(CWD_BASE, this.workdir);
-    const candidates = this.collectPathCandidates(rootNode, initialBase);
+    const collected = this.collectPathCandidates(rootNode, initialBase);
     for (const salvaged of salvagedRoots) {
-      this.walkForCandidates(salvaged, UNKNOWN_BASE, candidates);
+      this.walkForCandidates(salvaged, UNKNOWN_BASE, collected);
     }
+    const candidates = collected.filter(
+      ({ token }) => !this.words.spellsReboundHome(token),
+    );
     return {
       externalAccesses: this.withWorkdirExternal(
         this.projectExternalPaths(candidates),
@@ -236,7 +248,7 @@ export class BashPathResolver {
       case "redirected_statement":
         return this.walkCurrentShellSequence(node, base, out);
       case "command":
-        tagTokens(collectCommandTokens(node), base, out);
+        tagTokens(collectCommandTokens(node, this.words), base, out);
         return this.foldCd(node, base);
       case "pipeline":
         // tree-sitter-bash mis-groups a redirect-bearing `&&`/`;` list as the
@@ -261,7 +273,7 @@ export class BashPathResolver {
         // substitution interiors: collect every candidate in the subtree tagged
         // with the enclosing base and do not fold their internal `cd`s. (Folding
         // inside substitutions is deferred — conservative, never under-flags.)
-        tagTokens(collectPathCandidateTokens(node), base, out);
+        tagTokens(collectPathCandidateTokens(node, this.words), base, out);
         return base;
     }
   }
@@ -321,7 +333,7 @@ export class BashPathResolver {
       }
       // Downstream stage (after a `|`): subshell — collect against the folded
       // base, do not fold.
-      tagTokens(collectPathCandidateTokens(child), current, out);
+      tagTokens(collectPathCandidateTokens(child, this.words), current, out);
     }
     return current;
   }
@@ -351,7 +363,7 @@ export class BashPathResolver {
         if (child.type === "file_redirect") {
           // Redirect destinations are part of the piped stage; collect them
           // against the folded base without folding.
-          tagTokens(collectRedirectTokens(child), current, out);
+          tagTokens(collectRedirectTokens(child, this.words), current, out);
           continue;
         }
         // The inner statement is the `list`/`command` being redirected; fold its
@@ -361,7 +373,7 @@ export class BashPathResolver {
       return current;
     }
     // Bare `command` or any other shape: a true subshell first stage.
-    tagTokens(collectPathCandidateTokens(node), base, out);
+    tagTokens(collectPathCandidateTokens(node, this.words), base, out);
     return base;
   }
 
@@ -389,7 +401,7 @@ export class BashPathResolver {
         current = this.walkForCandidates(child, current, out);
       } else {
         // Terminal child = the real pipe stage; collect without folding.
-        tagTokens(collectPathCandidateTokens(child), current, out);
+        tagTokens(collectPathCandidateTokens(child, this.words), current, out);
       }
     }
     return current;
@@ -412,7 +424,7 @@ export class BashPathResolver {
    * {@link PathNormalizer}; this method owns only the base-folding state.
    */
   private foldCd(commandNode: TSNode, base: EffectiveBase): EffectiveBase {
-    if (extractCommandName(commandNode) !== "cd") return base;
+    if (extractCommandName(commandNode, this.words) !== "cd") return base;
     const target = cdLiteralTarget(commandNode);
     if (target === null) return UNKNOWN_BASE;
     return this.deriveBaseFromCdTarget(base, target);

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

@@ -1,6 +1,6 @@
 import type { BashCommandContext, FloorExemption } from "#src/types";
 import { EXECUTION_HOST_TYPES, forEachExecutionIn } from "./nested-execution";
-import { readArgWord } from "./node-text";
+import type { WordReader } from "./node-text";
 import { parseUnresolvedWithin } from "./parse-health";
 import type { TSNode } from "./parser";
 import { REDIRECT_NODE_TYPES, redirectMayWriteFile } from "./redirect-analysis";
@@ -105,14 +105,22 @@ interface UnitScope {
    * everything found inside a salvaged region is salvaged.
    */
   readonly salvaged: boolean;
+  /**
+   * How the program's shell expands an argument word. Relayed unchanged: a
+   * program's variables are the same wherever in it a word sits.
+   */
+  readonly words: WordReader;
 }
 
 /** A top-level command in the current shell, writing no file, fully parsed. */
-const TOP_LEVEL_SCOPE: UnitScope = {
-  writesViaRedirect: false,
-  parseUnresolved: false,
-  salvaged: false,
-};
+function topLevelScope(words: WordReader): UnitScope {
+  return {
+    writesViaRedirect: false,
+    parseUnresolved: false,
+    salvaged: false,
+    words,
+  };
+}
 
 /**
  * The scope a salvaged region's own units run under.
@@ -123,11 +131,14 @@ const TOP_LEVEL_SCOPE: UnitScope = {
  * {@link collectHostedCommands} resets it: a redirect established outside the
  * region is the enclosing statement's, not the region's.
  */
-const SALVAGED_SCOPE: UnitScope = {
-  writesViaRedirect: false,
-  parseUnresolved: true,
-  salvaged: true,
-};
+function salvagedScope(words: WordReader): UnitScope {
+  return {
+    writesViaRedirect: false,
+    parseUnresolved: true,
+    salvaged: true,
+    words,
+  };
+}
 
 // ── Node-type vocabulary ─────────────────────────────────────────────────────
 
@@ -244,9 +255,12 @@ const STATEMENT_TYPES = new Set([
  * wrapper unit (`bash -c`/`eval`, or an indirection wrapper such as `sudo`) is
  * tagged with a {@link WrapperKind} so its decision is later floored to `ask`.
  */
-export function collectCommands(node: TSNode): BashCommand[] {
+export function collectCommands(
+  node: TSNode,
+  words: WordReader,
+): BashCommand[] {
   const out: BashCommand[] = [];
-  collectCommandsInto(node, TOP_LEVEL_SCOPE, out);
+  collectCommandsInto(node, topLevelScope(words), out);
   return out;
 }
 
@@ -260,9 +274,12 @@ export function collectCommands(node: TSNode): BashCommand[] {
  * explicit `deny` fires — while its `allow` is still floored to `ask` by the
  * verdict fold (#840).
  */
-export function collectSalvagedCommands(node: TSNode): BashCommand[] {
+export function collectSalvagedCommands(
+  node: TSNode,
+  words: WordReader,
+): BashCommand[] {
   const out: BashCommand[] = [];
-  collectCommandsInto(node, SALVAGED_SCOPE, out);
+  collectCommandsInto(node, salvagedScope(words), out);
   return out;
 }
 
@@ -282,11 +299,14 @@ export function collectSalvagedCommands(node: TSNode): BashCommand[] {
  * (`python3 -c`, `node -e`) out: its payload is another language, so re-parsing
  * it as bash would read a secret out of embedded Python.
  */
-export function inlineShellPayloadNode(command: TSNode): TSNode | null {
+export function inlineShellPayloadNode(
+  command: TSNode,
+  words: WordReader,
+): TSNode | null {
   const nodes = commandWordNodes(command);
   const index = inlineShellPayloadIndex(
     nodes.map((node) => ({
-      ...readArgWord(node),
+      ...words.argWord(node),
       text: node.text,
       offset: node.startIndex,
     })),
@@ -426,7 +446,7 @@ function makeUnit(
  * surely as one on the enclosing statement.
  */
 function makeCommandUnit(node: TSNode, scope: UnitScope): BashCommand {
-  const { text, words } = readCommandUnit(node);
+  const { text, words } = readCommandUnit(node, scope.words);
   return makeUnit(text, scope, {
     wrapperKind: classifyWrapperWords(words),
     executedUnit: executedUnitOf(text, words) ?? undefined,
@@ -482,7 +502,10 @@ function redirectedScope(node: TSNode, scope: UnitScope): UnitScope {
  * A pure assignment (`FOO=bar`, no `command_name`) runs no command, has no
  * words, and keeps its whole text.
  */
-function readCommandUnit(node: TSNode): {
+function readCommandUnit(
+  node: TSNode,
+  reader: WordReader,
+): {
   text: string;
   words: CommandWord[];
 } {
@@ -495,7 +518,11 @@ function readCommandUnit(node: TSNode): {
   let previous: TSNode | undefined;
   for (const word of nodes) {
     if (previous) text += gapBetween(node, previous, word, redirects);
-    words.push({ ...readArgWord(word), text: word.text, offset: text.length });
+    words.push({
+      ...reader.argWord(word),
+      text: word.text,
+      offset: text.length,
+    });
     text += word.text;
     previous = word;
   }
@@ -626,6 +653,7 @@ function collectHostedCommands(
         writesViaRedirect: false,
         parseUnresolved: false,
         salvaged: scope.salvaged,
+        words: scope.words,
       },
       out,
     );

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

@@ -1,5 +1,5 @@
 import type { TSNode } from "./parser";
-import { resolvePlainVariableExpansion } from "./shell-variable-expansion";
+import type { ShellVariables } from "./shell-variable-expansion";
 
 /**
  * Node types whose text content is never a command argument, so no path
@@ -35,13 +35,13 @@ export const ARG_NODE_TYPES = new Set([
  * since a word only the shell decides can spell any option at all.
  */
 export interface ArgWord {
-  /** The string the shell passes after quote removal ({@link resolveNodeText}). */
+  /** The string the shell passes after quote removal ({@link resolveText}). */
   readonly value: string;
   /**
    * Whether `value` may differ from what the program receives: a part only
-   * running the command decides ({@link hasComputedPart}), or a spelling the
+   * running the command decides ({@link computedPart}), or a spelling the
    * shell rewrites before the program sees it — an escape, a glob, a brace
-   * expansion, an ANSI-C string — which {@link resolveNodeText} passes through as written.
+   * expansion, an ANSI-C string — which {@link resolveText} passes through as written.
    */
   readonly computed: boolean;
   /**
@@ -53,17 +53,67 @@ export interface ArgWord {
   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,
-    computed,
-    mayLeadWithDash: computed
-      ? mayExpandToDashWord(node)
-      : value.startsWith("-"),
-  };
+/**
+ * Reads argument nodes as one program's shell expands them: the node-text
+ * reads bound to the {@link ShellVariables} that program rebinds.
+ */
+export class WordReader {
+  constructor(private readonly variables: ShellVariables) {}
+
+  /** Read an argument node into the word the program receives. */
+  argWord(node: TSNode): ArgWord {
+    const value = this.text(node);
+    const tilde = this.variables.readTilde(leadingUnquotedText(node));
+    if (tilde?.known === false) {
+      return { value, computed: true, mayLeadWithDash: true };
+    }
+    const computed =
+      this.isComputed(node) || !isSpelledExactly(node, this.variables);
+    if (tilde) {
+      // The spelling `~` is not what the program receives; it is exact enough
+      // to prove with only while the home it stands for cannot be an option.
+      return {
+        value,
+        computed: computed || tilde.leadsWithDash,
+        mayLeadWithDash:
+          tilde.leadsWithDash || (computed && maySplitIntoWords(node, false)),
+      };
+    }
+    return {
+      value,
+      computed,
+      mayLeadWithDash: computed
+        ? mayExpandToDashWord(node)
+        : value.startsWith("-"),
+    };
+  }
+
+  /** The string the shell passes after quote removal ({@link resolveText}). */
+  text(node: TSNode): string {
+    return resolveText(node, this.variables);
+  }
+
+  /** Whether the node's value is decided at run time ({@link computedPart}). */
+  isComputed(node: TSNode): boolean {
+    return computedPart(node, this.variables);
+  }
+
+  /** Whether a collected token is spelled from a rebound `HOME` ({@link ShellVariables.spellsReboundHome}). */
+  spellsReboundHome(token: string): boolean {
+    return this.variables.spellsReboundHome(token);
+  }
+}
+
+/**
+ * The unquoted literal an argument opens with, where bash expands a tilde
+ * prefix: the word itself, or a concatenation's first part when that is a
+ * word. A tilde after any other part, or inside quotes, stays literal.
+ */
+function leadingUnquotedText(node: TSNode): string {
+  if (node.type === "word") return node.text;
+  if (node.type !== "concatenation") return "";
+  const first = node.child(0);
+  return first?.type === "word" ? first.text : "";
 }
 
 /**
@@ -182,12 +232,12 @@ function quotedLiteralMayLeadWithDash(text: string): boolean | undefined {
 }
 
 /**
- * Whether {@link resolveNodeText} returns exactly the string the shell passes.
+ * Whether {@link resolveText} returns exactly the string the shell passes.
  *
  * Answers `false` for any node type it does not know, which is the
  * fail-closed direction for a caller proving what a word cannot be.
  */
-function isSpelledExactly(node: TSNode): boolean {
+function isSpelledExactly(node: TSNode, variables: ShellVariables): boolean {
   switch (node.type) {
     case "raw_string":
       return true;
@@ -197,27 +247,33 @@ function isSpelledExactly(node: TSNode): boolean {
       return !node.text.includes("\\");
     case "simple_expansion":
     case "expansion":
-      return resolvePlainVariableExpansion(node) !== null;
+      return variables.resolveReference(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);
+      return childrenSpelledExactly(node, variables);
     case "concatenation":
       // The grammar splits `{-i,-n}` into plain words, so the expansion is
       // visible only across the whole concatenation's text.
-      return !BRACE_EXPANSION.test(node.text) && childrenSpelledExactly(node);
+      return (
+        !BRACE_EXPANSION.test(node.text) &&
+        childrenSpelledExactly(node, variables)
+      );
     default:
       return false;
   }
 }
 
 /** A `"` delimiter is spelled exactly; every named child must be too. */
-function childrenSpelledExactly(node: TSNode): boolean {
+function childrenSpelledExactly(
+  node: TSNode,
+  variables: ShellVariables,
+): boolean {
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
     if (!child || child.type === '"') continue;
-    if (!isSpelledExactly(child)) return false;
+    if (!isSpelledExactly(child, variables)) return false;
   }
   return true;
 }
@@ -236,22 +292,22 @@ const BRACE_EXPANSION = /\{[^}]*(,|\.\.)[^}]*\}/;
 /**
  * Whether an argument node's value is decided at run time: it contains a
  * command or process substitution, an arithmetic expansion, or a variable
- * expansion {@link resolvePlainVariableExpansion} cannot resolve.
+ * expansion {@link ShellVariables.resolveReference} cannot resolve.
  *
- * The complement of what {@link resolveNodeText} can spell exactly. A plain
+ * The complement of what {@link resolveText} can spell exactly. A plain
  * `$HOME` / `$PWD` reference resolves, so `"$HOME/out"` is not computed; any
  * other expansion falls back to its own source text there, which names a file
  * that is not the one the shell will touch (ADR 0009's computed-path residual).
  * A single-quoted `'$x'` is a literal.
  */
-export function hasComputedPart(node: TSNode): boolean {
+function computedPart(node: TSNode, variables: ShellVariables): boolean {
   if (COMPUTED_NODE_TYPES.has(node.type)) return true;
   if (VARIABLE_EXPANSION_TYPES.has(node.type)) {
-    return resolvePlainVariableExpansion(node) === null;
+    return variables.resolveReference(node) === null;
   }
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
-    if (child && hasComputedPart(child)) return true;
+    if (child && computedPart(child, variables)) return true;
   }
   return false;
 }
@@ -281,7 +337,7 @@ const VARIABLE_EXPANSION_TYPES: ReadonlySet<string> = new Set([
  *   else `.text` (see `shell-variable-expansion.ts`)
  * - other           → `.text` as fallback
  */
-export function resolveNodeText(node: TSNode): string {
+function resolveText(node: TSNode, variables: ShellVariables): string {
   switch (node.type) {
     case "word":
       return node.text;
@@ -302,7 +358,7 @@ export function resolveNodeText(node: TSNode): string {
         if (!child) continue;
         // Skip the literal `"` delimiters
         if (child.type === '"') continue;
-        result += resolveNodeText(child);
+        result += resolveText(child, variables);
       }
       return result;
     }
@@ -310,13 +366,13 @@ export function resolveNodeText(node: TSNode): string {
       return node.text;
     case "simple_expansion":
     case "expansion":
-      return resolvePlainVariableExpansion(node) ?? node.text;
+      return variables.resolveReference(node) ?? node.text;
     case "concatenation": {
       let result = "";
       for (let i = 0; i < node.childCount; i++) {
         const child = node.child(i);
         if (!child) continue;
-        result += resolveNodeText(child);
+        result += resolveText(child, variables);
       }
       return result;
     }

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

@@ -9,7 +9,9 @@ import {
   collectCommands,
   collectSalvagedCommands,
 } from "./command-enumeration";
+import { WordReader } from "./node-text";
 import { getParser } from "./parser";
+import { ShellVariables } from "./shell-variable-expansion";
 import { withSalvagedRoots } from "./unresolved-salvage";
 
 export type { BashCommand, BashExternalPath, BashPathRuleCandidate };
@@ -62,15 +64,19 @@ export class BashProgram {
 
     try {
       return withSalvagedRoots(tree.rootNode, parser, (salvaged) => {
+        const words = new WordReader(
+          ShellVariables.scan([tree.rootNode, ...salvaged]),
+        );
         const { externalAccesses, ruleCandidates } = new BashPathResolver(
           normalizer,
+          words,
           options?.workdir,
         ).resolve(tree.rootNode, salvaged);
         return new BashProgram(
           command,
           [
-            ...collectCommands(tree.rootNode),
-            ...salvaged.flatMap(collectSalvagedCommands),
+            ...collectCommands(tree.rootNode, words),
+            ...salvaged.flatMap((root) => collectSalvagedCommands(root, words)),
           ],
           externalAccesses,
           ruleCandidates,