@gotgenes/pi-permission-system 24.0.0 → 25.0.0

package/CHANGELOG.md

@@ -5,6 +5,27 @@ 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).
 
+## [25.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v24.0.0...pi-permission-system-v25.0.0) (2026-08-11)
+
+
+### ⚠ BREAKING CHANGES
+
+* **pi-permission-system:** a bash command referencing `$HOME` or `${HOME}` now reaches the `external_directory` gate whether or not the target exists, so a policy with `external_directory: {"*": "ask"}` prompts for commands that previously ran silently. Allow the directory explicitly to restore the old behavior — e.g. `"external_directory": {"~/.cargo/registry/*": "allow"}`. The token shown in prompts, review-log entries, and derived session-approval patterns is now the expanded path rather than the `$HOME/...` spelling; this makes the prompt agree with the approval pattern, which was already derived from the expanded form.
+
+### Features
+
+* **pi-permission-system:** expand ${HOME} alongside $HOME in path patterns ([3ebbd41](https://github.com/gotgenes/pi-packages/commit/3ebbd418e5b85a6dfbc1865c69f62c1f9a3cb144)), closes [#694](https://github.com/gotgenes/pi-packages/issues/694)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** resolve $HOME and $PWD expansions in bash path tokens ([8cbc7ee](https://github.com/gotgenes/pi-packages/commit/8cbc7ee011a3e06dcf047bfe8a467db3aa487721)), closes [#694](https://github.com/gotgenes/pi-packages/issues/694)
+
+
+### Documentation
+
+* **pi-permission-system:** record resolved shell expansions in ADR 0009 and user docs ([caaf5ec](https://github.com/gotgenes/pi-packages/commit/caaf5ec02ef2f7df1e2a922dba0a9afdc121b191)), closes [#694](https://github.com/gotgenes/pi-packages/issues/694)
+
 ## [24.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v23.0.3...pi-permission-system-v24.0.0) (2026-07-26)
 
 

package/docs/configuration.md

@@ -106,7 +106,7 @@ This clamp is deny-preserving and, like `yoloMode`, applied at composition; when
 | `doublePressToConfirm`      | `true`  | Requires a confirming second press of a decision hotkey in the inline TUI dialog (see below). TUI sessions only; set to `false` for single-press.                                                  |
 | `toolInputPreviewMaxLength` | `200`   | Max characters of inline JSON shown in permission prompts for tool inputs. Omit to use the default. Set to a large value to disable truncation.                                                    |
 | `toolTextSummaryMaxLength`  | `80`    | Max characters of inline pattern/path summaries (grep patterns, find globs, ls paths) in permission prompts. Omit to use the default.                                                              |
-| `piInfrastructureReadPaths` | `[]`    | Extra directories to auto-allow for reads, bypassing the `external_directory` gate. Supports `~`/`$HOME` expansion and wildcard patterns (`*`, `?`).                                               |
+| `piInfrastructureReadPaths` | `[]`    | Extra directories to auto-allow for reads, bypassing the `external_directory` gate. Supports `~`/`$HOME`/`${HOME}` expansion and wildcard patterns (`*`, `?`).                                     |
 | `authorizerChain`           | `[]`    | Ordered names of registered live-authority chain links to consult before the terminal authorizer (see [Authorizer chain](#authorizer-chain--case-by-case-decision-links)).                         |
 
 Both logs write to `~/.pi/agent/extensions/pi-permission-system/logs/`.
@@ -136,7 +136,7 @@ Non-TUI contexts (RPC / frontend-driven sessions) keep the single-select prompt
 ### `piInfrastructureReadPaths` patterns
 
 Each entry is either a plain directory prefix or a wildcard pattern.
-Plain entries match any path that starts with the given directory (after `~`/`$HOME` expansion).
+Plain entries match any path that starts with the given directory (after `~`/`$HOME`/`${HOME}` expansion).
 Wildcard entries use `*` (any characters, including `/`) and `?` (exactly one character).
 `*` and `**` are equivalent — both cross directory boundaries.
 
@@ -587,9 +587,22 @@ The pattern is stored and displayed as written (`~/.cargo/registry/*`) in logs a
 For caches you only ever **read**, `piInfrastructureReadPaths` is a lighter alternative — it auto-allows read-only tools (`read`, `find`, `grep`, `ls`) and bypasses the gate entirely, but it does not cover `write`/`edit` or bash.
 Use `external_directory` when the allowance must apply to every tool.
 
-Bash commands are also covered: the extension extracts path-like tokens from the command string and applies the same gate when any resolve outside `ctx.cwd`.
-Quoted strings are stripped first to reduce false positives.
-This is a best-effort heuristic — variable expansion and escaped quotes are not parsed, and relative paths inside subshells are not yet resolved against a per-subshell working directory. (The separate `bash` command-pattern surface does evaluate commands nested inside substitutions and subshells; see that section.) OS device paths (`/dev/null`, `/dev/stdin`, `/dev/stdout`, `/dev/stderr`) are always excluded.
+Bash commands are also covered: the extension parses the command and applies the same gate to every token that resolves outside `ctx.cwd`.
+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`) 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.
+- 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"`).
+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.
+
+(The separate `bash` command-pattern surface does evaluate commands nested inside substitutions and subshells; see that section.) OS device paths (`/dev/null`, `/dev/stdin`, `/dev/stdout`, `/dev/stderr`) are always excluded.
 
 #### Symlinked paths
 
@@ -644,8 +657,9 @@ To allow-list such a path, write the rule using the path as typed — for exampl
 
 ### Home Directory Expansion in Patterns
 
-Pattern keys in any permission surface can start with `~/` or `$HOME/` (or be exactly `~` / `$HOME`).
+Pattern keys in any permission surface can start with `~/`, `$HOME/`, or `${HOME}/` (or be exactly `~`, `$HOME`, or `${HOME}`).
 They are expanded to the OS home directory at match time, so configs are portable across machines and users.
+A prefix is recognized only when it stands alone or precedes a separator, so a longer name (`~username`, `$HOMEDIR`) and a braced expansion carrying an operator (`${HOME:-/tmp}`) are left alone.
 
 ```jsonc
 {
@@ -661,7 +675,7 @@ They are expanded to the OS home directory at match time, so configs are portabl
 The pattern is stored and displayed as written (e.g. `~/development/*`) in logs and approval dialogs.
 
 Path **values** supplied by tool calls and bash commands are expanded the same way.
-This means `~/...`, `$HOME/...`, and the fully-expanded absolute form all match a single home-anchored pattern: a `read` tool called with path `~/.ssh/config`, `$HOME/.ssh/config`, or `/Users/me/.ssh/config` is all caught by a `"~/.ssh/*": "deny"` rule.
+This means `~/...`, `$HOME/...`, `${HOME}/...`, and the fully-expanded absolute form all match a single home-anchored pattern: a `read` tool called with path `~/.ssh/config`, `$HOME/.ssh/config`, `${HOME}/.ssh/config`, or `/Users/me/.ssh/config` is all caught by a `"~/.ssh/*": "deny"` rule.
 
 ---
 

package/docs/opencode-compatibility.md

@@ -20,7 +20,7 @@ The following concepts are shared between OpenCode and this extension:
 | Last-match-wins               | When multiple patterns match, the last one in config order wins                                                 |
 | `*` wildcard                  | Matches zero or more of any character (including path separators)                                               |
 | `?` wildcard                  | Matches exactly one character                                                                                   |
-| Home directory expansion      | `~/` and `$HOME/` expand to the OS home directory in patterns                                                   |
+| Home directory expansion      | `~/`, `$HOME/`, and `${HOME}/` expand to the OS home directory in patterns                                      |
 | `external_directory` surface  | Gates access to paths outside the working directory                                                             |
 | `bash` surface                | Command patterns matched against shell commands                                                                 |
 | `skill` surface               | Skill name patterns matched against skill invocations                                                           |

package/package.json

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

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

@@ -1,4 +1,5 @@
 import type { TSNode } from "#src/access-intent/bash/parser";
+import { resolvePlainVariableExpansion } from "#src/access-intent/bash/shell-variable-expansion";
 
 /**
  * Node types whose subtrees must never be descended into for
@@ -29,6 +30,8 @@ export const ARG_NODE_TYPES = new Set([
  * - `raw_string`    → strip surrounding single quotes
  * - `string`        → strip surrounding double quotes, concatenate children text
  * - `concatenation` → concatenate resolved children
+ * - expansions      → the resolved value of a plain `$HOME`/`$PWD` reference,
+ *   else `.text` (see `shell-variable-expansion.ts`)
  * - other           → `.text` as fallback
  */
 export function resolveNodeText(node: TSNode): string {
@@ -57,9 +60,10 @@ export function resolveNodeText(node: TSNode): string {
       return result;
     }
     case "string_content":
+      return node.text;
     case "simple_expansion":
     case "expansion":
-      return node.text;
+      return resolvePlainVariableExpansion(node) ?? node.text;
     case "concatenation": {
       let result = "";
       for (let i = 0; i < node.childCount; i++) {

package/src/access-intent/bash/shell-variable-expansion.ts

@@ -0,0 +1,77 @@
+/**
+ * Resolution of the shell variable references the bash path projection can
+ * settle statically.
+ *
+ * Runs at token collection, upstream of classification: by the time a token
+ * reaches `classifyTokenAsPathCandidate` it already carries the expanded path,
+ * so `$HOME/x` is accepted by the ordinary absolute-shape branch and needs no
+ * per-variable knowledge in the classifiers (#694). Keeping the vocabulary here
+ * — rather than teaching each classifier a `$HOME` prefix — is what stops the
+ * two from drifting apart, which is the defect this module closes.
+ *
+ * The resolvable set is deliberately tiny and closed. `HOME` is the spelling
+ * `expandHomePath` already resolves for config patterns and path literals, so
+ * resolving it here removes an inconsistency rather than widening the
+ * determinism boundary; `PWD` reads no environment at all. Every other name
+ * keeps its literal text, so ADR 0003's exclusion of ambient host state stands.
+ * See `docs/decisions/0009-bash-path-projection-completeness-contract.md`.
+ */
+import { homedir } from "node:os";
+
+import type { TSNode } from "#src/access-intent/bash/parser";
+
+/**
+ * The value of a plain `$NAME` / `${NAME}` reference, or `null` when the node
+ * is not a plain reference or names a variable outside the resolvable set.
+ *
+ * Plainness is decided structurally, not by matching the node's text: a plain
+ * reference carries exactly one `variable_name` child and nothing else but
+ * delimiters. An operator form (`${HOME:-/tmp}`, `${#HOME}`, `${HOME%/*}`)
+ * carries additional children and is therefore rejected without this module
+ * needing to enumerate bash's expansion operators.
+ */
+export function resolvePlainVariableExpansion(node: TSNode): string | null {
+  const name = plainVariableName(node);
+  return name === null ? null : (RESOLVABLE_VARIABLES.get(name)?.() ?? null);
+}
+
+/**
+ * How each resolvable variable is spelled as a path.
+ *
+ * `PWD` resolves to the base-relative marker rather than a directory: the
+ * shell's working directory at a given point *is* the projection's effective
+ * base, which the resolver already applies via `resolveBase`. Handing back `.`
+ * therefore lands `$PWD/x` on the same footing as `./x` — correct after any
+ * `cd` folding, conservative under an unknown base (#393), and free of both a
+ * threaded base parameter and a platform branch.
+ */
+const RESOLVABLE_VARIABLES: ReadonlyMap<string, () => string> = new Map([
+  ["HOME", homedir],
+  ["PWD", () => "."],
+]);
+
+/** Node types that delimit an expansion without altering what it evaluates to. */
+const EXPANSION_DELIMITERS: ReadonlySet<string> = new Set(["$", "${", "}"]);
+
+/**
+ * The variable a node plainly references, or `null` when it references none —
+ * because it has no `variable_name` child, has more than one, or carries a
+ * child that is neither the name nor a delimiter (an expansion operator and its
+ * operand, or an assignment's `=` and value).
+ */
+function plainVariableName(node: TSNode): string | null {
+  let name: string | null = null;
+
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child) continue;
+    if (child.type === "variable_name") {
+      if (name !== null) return null;
+      name = child.text;
+      continue;
+    }
+    if (!EXPANSION_DELIMITERS.has(child.type)) return null;
+  }
+
+  return name;
+}

package/src/expand-home.ts

@@ -2,27 +2,41 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 
 /**
- * Expand `~` and `$HOME` prefixes in a pattern to the OS home directory.
+ * The spellings of the home directory this package resolves, in every pattern
+ * and path literal.
  *
- * Supported forms:
- * - `~`          → `homedir()`
- * - `~/path`     → `homedir()/path`
- * - `~\path`     → `homedir()\path` (Windows)
- * - `$HOME`      → `homedir()`
- * - `$HOME/path` → `homedir()/path`
- * - `$HOME\path` → `homedir()\path` (Windows)
+ * `$HOME` and `${HOME}` are the two spellings of the same shell variable and
+ * must stay interchangeable: a rule keyed on one form has to match a path
+ * written in the other, and the bash path projection classifies a token by the
+ * shape it has *after* this expansion (#694).
+ */
+const HOME_PREFIXES = ["~", "$HOME", "${HOME}"] as const;
+
+/**
+ * Expand a home-directory prefix in a pattern or path value to the OS home
+ * directory.
+ *
+ * A prefix is recognized only when it stands alone or is followed by a path
+ * separator, so a longer name (`~username`, `$HOMEDIR`, `${HOMEDIR}`) and a
+ * braced parameter expansion carrying an operator (`${HOME:-/tmp}`,
+ * `${HOME%/*}`) are both left untouched.
+ *
+ * Supported forms, for each prefix in {@link HOME_PREFIXES}:
+ * - `<prefix>`       → `homedir()`
+ * - `<prefix>/path`  → `homedir()/path`
+ * - `<prefix>\path`  → `homedir()\path` (Windows)
  *
  * All other patterns are returned unchanged.
  */
 export function expandHomePath(pattern: string): string {
-  if (pattern === "~" || pattern === "$HOME") {
-    return homedir();
-  }
-  if (pattern.startsWith("~/") || pattern.startsWith("~\\")) {
-    return join(homedir(), pattern.slice(2));
-  }
-  if (pattern.startsWith("$HOME/") || pattern.startsWith("$HOME\\")) {
-    return join(homedir(), pattern.slice(6));
+  for (const prefix of HOME_PREFIXES) {
+    if (pattern === prefix) return homedir();
+    if (!pattern.startsWith(prefix)) continue;
+
+    const rest = pattern.slice(prefix.length);
+    if (rest.startsWith("/") || rest.startsWith("\\")) {
+      return join(homedir(), rest.slice(1));
+    }
   }
   return pattern;
 }