@gotgenes/pi-permission-system 36.2.0 → 37.0.0

package/CHANGELOG.md

@@ -5,6 +5,38 @@ 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).
 
+## [37.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v36.2.1...pi-permission-system-v37.0.0) (2026-10-02)
+
+
+### Features
+
+* **pi-permission-system:** **breaking:** require Pi 1.0.0 or later ([9c76ae3](https://github.com/gotgenes/pi-packages/commit/9c76ae30dd58b0a94524f753f7c72ff356231294)), closes [#970](https://github.com/gotgenes/pi-packages/issues/970)
+
+### Bug Fixes
+
+* **pi-permission-system:** keep prompt sections other extensions add, such as <mcp_servers> ([1abdfe4](https://github.com/gotgenes/pi-packages/commit/1abdfe4901a27cb8ff3d85a965fc07b3be874624)), closes [#999](https://github.com/gotgenes/pi-packages/issues/999)
+* **pi-permission-system:** keep later prompt sections when a skill is denied ([dafd83b](https://github.com/gotgenes/pi-packages/commit/dafd83b075b01ef39335822f8b5122c56ee00b97)), closes [#999](https://github.com/gotgenes/pi-packages/issues/999)
+
+### Documentation
+
+* **pi-permission-system:** note the Pi 1.0.0 requirement under Upgrading ([5bc932c](https://github.com/gotgenes/pi-packages/commit/5bc932cf9936728c0e3c551fdbea6a7009108958)), closes [#970](https://github.com/gotgenes/pi-packages/issues/970)
+* **pi-permission-system:** record prompt changes through systemPromptOptions ([b11051f](https://github.com/gotgenes/pi-packages/commit/b11051f1365a635b67e70dea126c8a49ff9ef31b)), closes [#999](https://github.com/gotgenes/pi-packages/issues/999)
+
+## [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)
 
 

package/README.md

@@ -155,6 +155,12 @@ Third-party packages are maintained by their authors; review one before granting
 
 ## Upgrading
 
+### The major after 36.x — requires Pi 1.0.0
+
+The extension now requires `@earendil-works/pi-coding-agent` and `@earendil-works/pi-tui` 1.0.0 or later.
+Upgrade Pi to 1.0.0 before upgrading this package; on an older Pi, stay on the 36.x line.
+No configuration change is needed.
+
 ### 22.0.0 — project config requires project trust
 
 Project-scoped configuration (the project `config.json` and project-agent frontmatter — both permission policy and runtime knobs such as `yoloMode`) is now loaded only when Pi reports the project as trusted.

package/docs/configuration.md

@@ -785,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.
@@ -1314,11 +1314,11 @@ permission:
 
 The extension integrates via Pi's lifecycle hooks:
 
-| Hook                 | Behavior                                                                                                                                                                                                      |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `before_agent_start` | Filters the active tool set (restrict-only), restates the tool list and guidelines at the end of the system prompt to match (except under a custom system prompt outside a subagent), and hides denied skills |
-| `tool_call`          | Enforces permissions for every tool invocation                                                                                                                                                                |
-| `input`              | Intercepts `/skill:<name>` requests and enforces skill policy                                                                                                                                                 |
+| Hook                 | Behavior                                                                                                                                                                                |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `before_agent_start` | Filters the active tool set (restrict-only), states a subagent child's own tool list and rules, and hides denied skills, all through pi's prompt options rather than a rewritten prompt |
+| `tool_call`          | Enforces permissions for every tool invocation                                                                                                                                          |
+| `input`              | Intercepts `/skill:<name>` requests and enforces skill policy                                                                                                                           |
 
 Additional behaviors:
 
@@ -1326,16 +1326,18 @@ Additional behaviors:
 - Tool filtering is restrict-only: the active set starts from pi's already-active tools (`pi.getActiveTools()`) and only ever has denied tools removed — the permission system never activates a tool pi left off by default (e.g. `find`, `grep`, `ls`)
 - Policy is applied to the tool surface pi has activated over the session, not to the previous turn's filtered result, so removing a `deny` rule restores the tool it had hidden without restarting pi.
   A tool that stops being active for any other reason (another extension deactivating it, pi unregistering it) is not restored.
-- On the turn a tool is restored, it is callable immediately but its `Available tools:` line reappears one turn later: pi builds the prompt parts an extension receives before the extension runs, so the restored tool has no one-line description to render until it is already active
 - A tool is removed only when every value under its surface resolves to `deny`; a surface with any reachable `allow` or `ask` pattern stays available (see [Tool Surfaces](#tool-surfaces))
-- The tool list and guidelines are **relocated** rather than edited in place: the copies pi wrote are removed, and this session's own are rendered at the end of the system prompt, after the working directory pi states last.
-  They take the shape pi writes them in: `Available tools:` and `Guidelines:` sections after a `Current working directory:` footer through pi 0.85, and `<tools>` and `<rules>` sections after a `<cwd>` section from pi 0.86.
-  Each session states its own tool surface, which is what keeps a subagent child's inherited prompt byte-identical to its parent's (see [ADR 0014](decisions/0014-tool-surface-is-node-local-prose.md)); the tool list moves to the end of the prompt for every session on pi's default prompt, whether or not anything is denied.
-  A custom system prompt (`.pi/SYSTEM.md`, `~/.pi/agent/SYSTEM.md`, `--system-prompt`) is left exactly as pi built it: pi writes no tool list or rules under one, and this extension adds none either, so the prompt describes tools only if you wrote that yourself.
+- Every change this extension makes to the system prompt goes through pi's `systemPromptOptions`; it never returns a rewritten prompt.
+  A returned prompt is sent as the whole prompt, which would drop the sections other extensions add after this one runs, such as pi's `<mcp_servers>` list of `codemode` and `deferred` MCP servers (see [ADR 0015](decisions/0015-prompt-changes-through-system-prompt-options.md)).
+- On pi's default prompt, the tool list and guidelines stay where pi writes them, as its `<tools>` and `<rules>` sections, and pi renders them from the filtered active set, so a denied tool and its guidelines are absent and a restored tool is listed on the turn it returns.
+- A custom system prompt (`.pi/SYSTEM.md`, `~/.pi/agent/SYSTEM.md`, `--system-prompt`) is left exactly as pi built it: pi writes no tool list or rules under one, and this extension adds none either, so the prompt describes tools only if you wrote that yourself.
   Tool filtering and enforcement still apply, and the model still receives only the allowed tools in the request's tool list.
-  A subagent child is the exception: its prompt is always a custom one assembled by the subagent extension, so it still gets its own tool list and rules at the end, while any custom text it inherited stays untouched.
-- The rendered sections follow pi's own rules: a tool is listed only when pi supplied a one-line description for it, and the guideline bullets are the allowed tools' own contributions, then any rules another extension added to `systemPromptOptions.promptGuidelines`, around pi's built-in ones
-- The prompt is recomputed and returned on every turn but is stable across turns for a stable policy/agent, so the provider's prompt cache (tools + system prefix) is preserved rather than rewritten each turn.
+  A subagent child is the exception: its prompt is always a custom one assembled by the subagent extension, so it gets its own `<tools>` and `<rules>` sections, placed after the working directory, while any custom text it inherited stays untouched.
+  The child's sections follow pi's own rules: a tool is listed only when pi supplied a one-line description for it, and the guideline bullets are the allowed tools' own contributions, then any rules another extension added to `systemPromptOptions.promptGuidelines`, around pi's built-in ones.
+- A subagent child running with `@gotgenes/pi-subagents` needs a release that drops the parent's `<tools>` and `<rules>` from the prompt the child inherits; with an older one, the child shows the parent's tool list as well as its own.
+- A denied skill is removed from the skills catalogue pi renders.
+  A skill listed in text pi did not render, such as your own `SYSTEM.md`, is not edited out; using it is still gated.
+- The prompt options are recomputed on every turn but are stable across turns for a stable policy/agent, so the provider's prompt cache is preserved rather than rewritten each turn.
   A policy change is an intentional cache transition, as a mid-session agent switch already is.
 - Extension-provided tools like `task`, `mcp`, and third-party tools are handled by exact registered name
 - Generic extension-tool approval prompts include a bounded input preview; built-in file tools use concise human-readable summaries

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "36.2.0",
+  "version": "37.0.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {
@@ -63,13 +63,13 @@
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.79.0",
-    "@earendil-works/pi-tui": ">=0.79.0"
+    "@earendil-works/pi-coding-agent": ">=1.0.0",
+    "@earendil-works/pi-tui": ">=1.0.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.11",
-    "@earendil-works/pi-coding-agent": "0.79.1",
-    "@earendil-works/pi-tui": "0.79.1",
+    "@earendil-works/pi-coding-agent": "1.0.0",
+    "@earendil-works/pi-tui": "1.0.0",
     "@types/node": "^22.15.3",
     "rollup": "^4.63.1",
     "rollup-plugin-dts": "^6.5.1",

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,