@gotgenes/pi-permission-system 39.0.2 → 39.0.3

package/CHANGELOG.md

@@ -5,6 +5,18 @@ 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).
 
+## [39.0.3](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v39.0.2...pi-permission-system-v39.0.3) (2026-10-03)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** match a home-prefixed bash rule against a command typed with ~ or $HOME ([af2d24a](https://github.com/gotgenes/pi-packages/commit/af2d24af90e77156cc7a58b5a75d70d1154cce3c)), closes [#981](https://github.com/gotgenes/pi-packages/issues/981)
+
+### Documentation
+
+* **pi-permission-system:** document bash command spellings ([e6cd84f](https://github.com/gotgenes/pi-packages/commit/e6cd84fe1ff5fa3ab7938f576ace1e574cc46409)), closes [#981](https://github.com/gotgenes/pi-packages/issues/981)
+* **pi-permission-system:** accept the HOME-rebinding residual for bash command spellings ([3c787e4](https://github.com/gotgenes/pi-packages/commit/3c787e43e79400fd132cbb6597c51c0448e2b39a)), closes [#981](https://github.com/gotgenes/pi-packages/issues/981)
+
 ## [39.0.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v39.0.1...pi-permission-system-v39.0.2) (2026-10-03)
 
 

package/docs/configuration.md

@@ -451,6 +451,8 @@ A quoted heredoc delimiter (`<<'EOF'` or `<<"EOF"`) does not interpolate, so its
 The enclosing command is still matched without its redirect, so a rule like `npm install` keeps matching `npm install > out.txt`.
 Control-flow bodies (`if`/`while`/`for`/`case`) and `{ … }` brace groups are not descended into; their contents are matched as part of the enclosing statement's text.
 
+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 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.
@@ -1120,6 +1122,21 @@ Path **values** supplied by bash commands and extension tools are expanded the s
 This means `~/...`, `$HOME/...`, `${HOME}/...`, and the fully-expanded absolute form all match a single home-anchored pattern: `cat ~/.ssh/config`, `cat $HOME/.ssh/config`, or `cat /Users/me/.ssh/config` is caught by a `"~/.ssh/*": "deny"` rule.
 Pi's built-in file tools expand only `~`, as Pi itself does: a `read` of `~/.ssh/config` or `/Users/me/.ssh/config` is caught, while a `read` of `$HOME/.ssh/config` opens `<cwd>/$HOME/.ssh/config` and is matched as that file.
 
+A `bash` command that **starts** with a home prefix matches a home-anchored command pattern the same way.
+With `"~/bin/tool *": "deny"`, the commands `~/bin/tool --now`, `$HOME/bin/tool --now`, `${HOME}/bin/tool --now`, and `/Users/me/bin/tool --now` are all denied, and an allow written with `~` covers each of those spellings too.
+The command is still shown, logged, and offered for session approval as typed.
+Three limits apply:
+
+- On Windows, a home-anchored `bash` pattern is compiled with backslash separators, so it matches only a command typed with the backslashed absolute path ([issue #1020](https://github.com/gotgenes/pi-packages/issues/1020)).
+- A command that reassigns `HOME` earlier in the same invocation (`HOME=/tmp/x; ~/bin/tool`, or a `HOME=/tmp/x` prefix) is matched only as typed, because its `~` no longer names your home directory.
+  A reassignment the parser cannot see, such as one through a variable holding the name (`n=HOME; read $n`), is not detected, so the command still matches your home-anchored rules.
+  Writing a command that way takes deliberate effort to evade a rule; run an agent you would not trust with that inside a sandbox rather than relying on command patterns.
+- A home prefix later in the command, in argument position, is matched as typed: a pattern `cat ~/notes` matches the command `cat ~/notes` but not `cat /Users/me/notes`.
+  Gate file access by any spelling on the `path` and `external_directory` surfaces instead.
+
+The `bash` surface matches text, so a `*` in a home-anchored pattern also matches `..`: `~/bin/*` allows `~/bin/../../tmp/x`, exactly as it allows `/Users/me/bin/../../tmp/x`.
+Anchor an allow on the full command (`~/bin/tool *`) rather than a directory wildcard when that matters.
+
 ---
 
 ## Per-Agent Overrides

package/package.json

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

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

@@ -52,16 +52,48 @@ export interface AccessPathAccessIntent {
   agentName?: string;
 }
 
-/** What a gate emits — a raw tool input or an `AccessPath`. */
-export type AccessIntent = ToolAccessIntent | AccessPathAccessIntent;
+/** What a gate emits: a raw tool input, an `AccessPath`, or a bash command unit. */
+export type AccessIntent =
+  | ToolAccessIntent
+  | AccessPathAccessIntent
+  | BashCommandAccessIntent;
+
+/**
+ * One bash command unit, with the other spellings the shell runs identically.
+ *
+ * `command` is the unit as typed: the prompt, the decision value, and the
+ * session-approval suggestion read it. `spellings` come from the program
+ * analysis, the only party that knows what a spelling means in this program
+ * (a `~` names the startup home only while the program leaves `HOME` alone),
+ * and the manager evaluates them with `command` as aliases of one invocation:
+ * the last rule matching any of them decides.
+ *
+ * String-only, so it stays on the manager's side of the ADR-0002 boundary.
+ */
+export interface BashCommandAccessIntent {
+  kind: "bash-command";
+  /**
+   * Always `"bash"`. Typed `string` because the resolver re-surfaces every
+   * intent across a surface family (`{ ...intent, surface }`); `bash` is never
+   * a family, so that never happens to this one.
+   */
+  surface: string;
+  command: string;
+  spellings: readonly string[];
+  agentName?: string;
+}
 
 /**
  * What the manager consumes — the `access-path` variant has already been
- * unwrapped to `path-values` by the resolver via `path.matchValues()`.
+ * unwrapped to `path-values` by the resolver via `path.matchValues()`; a
+ * `bash-command` intent passes through as emitted.
  *
  * The manager stays string-based and never imports `AccessPath`: this is the
  * deliberate boundary formalized in ADR-0002
  * (`docs/decisions/0002-path-values-string-boundary.md`), guarded by a
  * `no-restricted-imports` lint rule on `permission-manager.ts`.
  */
-export type ResolvedAccessIntent = ToolAccessIntent | PathValuesAccessIntent;
+export type ResolvedAccessIntent =
+  | ToolAccessIntent
+  | PathValuesAccessIntent
+  | BashCommandAccessIntent;

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

@@ -73,6 +73,15 @@ export interface BashCommand {
    * unreachable.
    */
   readonly salvaged?: true;
+  /**
+   * 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}).
+   */
+  readonly spellings?: readonly string[];
 }
 
 /**
@@ -409,19 +418,23 @@ function unresolvedScope(node: TSNode, scope: UnitScope): UnitScope {
     : scope;
 }
 
-/** The wrapper facts a `command` node's words establish about its unit. */
-interface WrapperFacts {
+/**
+ * The facts a `command` node's words establish about its unit: the three
+ * wrapper answers, and the other spellings its text has.
+ */
+interface UnitFacts {
   readonly wrapperKind?: WrapperKind;
   readonly executedUnit?: string;
   readonly floorExemption?: FloorExemption;
+  readonly spellings?: readonly string[];
 }
 
 function makeUnit(
   text: string,
   scope: UnitScope,
-  wrapper: WrapperFacts = {},
+  facts: UnitFacts = {},
 ): BashCommand {
-  const { wrapperKind, executedUnit, floorExemption } = wrapper;
+  const { wrapperKind, executedUnit, floorExemption, spellings } = facts;
   const scoped: BashCommand = scope.context
     ? { text, context: scope.context }
     : { text };
@@ -433,7 +446,10 @@ function makeUnit(
   const marked: BashCommand = scope.parseUnresolved
     ? { ...exempted, parseUnresolved: true }
     : exempted;
-  return scope.salvaged ? { ...marked, salvaged: true } : marked;
+  const salvaged: BashCommand = scope.salvaged
+    ? { ...marked, salvaged: true }
+    : marked;
+  return spellings === undefined ? salvaged : { ...salvaged, spellings };
 }
 
 /**
@@ -447,7 +463,9 @@ function makeUnit(
  */
 function makeCommandUnit(node: TSNode, scope: UnitScope): BashCommand {
   const { text, words } = readCommandUnit(node, scope.words);
+  const homeSpelling = scope.words.spellHomeAtStart(text);
   return makeUnit(text, scope, {
+    spellings: homeSpelling === undefined ? undefined : [homeSpelling],
     wrapperKind: classifyWrapperWords(words),
     executedUnit: executedUnitOf(text, words) ?? undefined,
     floorExemption: isTransparentWrapper(words, redirectedScope(node, scope))

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

@@ -102,6 +102,11 @@ export class WordReader {
   spellsReboundHome(token: string): boolean {
     return this.variables.spellsReboundHome(token);
   }
+
+  /** A command unit's text with its leading home prefix spelled out ({@link ShellVariables.spellHomeAtStart}). */
+  spellHomeAtStart(text: string): string | undefined {
+    return this.variables.spellHomeAtStart(text);
+  }
 }
 
 /**

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

@@ -17,7 +17,7 @@
  * See `docs/decisions/0009-bash-path-projection-completeness-contract.md`.
  */
 import { homedir } from "node:os";
-import { hasHomePrefix } from "#src/path/expand-home";
+import { hasHomePrefix, splitHomePrefix } from "#src/path/expand-home";
 
 import type { TSNode } from "./parser";
 
@@ -87,6 +87,24 @@ export class ShellVariables {
     return this.rebound.has("HOME") && hasHomePrefix(token);
   }
 
+  /**
+   * `text` with a leading `~` / `$HOME` / `${HOME}` spelled as the startup
+   * home, or `undefined` when it opens with none or the program rebinds `HOME`.
+   *
+   * The complement of {@link spellsReboundHome}: the spelling a command-pattern
+   * rule written with a home prefix is compiled to, so the rule matches the
+   * command as the shell runs it. The rest is kept verbatim, never
+   * path-normalized, because `..` in an argument is not a path step of the
+   * command's name. A backslash after the prefix gets none, because bash does
+   * not expand a tilde prefix holding a quoted character.
+   */
+  spellHomeAtStart(text: string): string | undefined {
+    if (this.rebound.has("HOME")) return undefined;
+    const rest = splitHomePrefix(text);
+    if (rest === undefined || rest.startsWith("\\")) return undefined;
+    return homedir() + rest;
+  }
+
   /**
    * How a word's leading unquoted text expands when it opens with a tilde
    * prefix that reads `HOME` (`~` or `~/…`; `~user` reads the password

package/src/access-intent/input-normalizer.ts

@@ -125,10 +125,10 @@ export interface NormalizedInput {
   surface: string;
   /**
    * Alternative lookup names for this one access, most-specific first.
-   * MCP is the only surface producing more than one; every other surface
-   * produces a single-element array. Order does not decide which rule wins
-   * (rule position does) — it decides which name the decision is reported
-   * under when the winning rule matches several.
+   * MCP targets and a bash command's spellings are the only sources of more
+   * than one; every other surface produces a single-element array. Order does
+   * not decide which rule wins (rule position does); it decides which name the
+   * decision is reported under when the winning rule matches several.
    */
   values: string[];
   /**
@@ -175,16 +175,7 @@ export function normalizeInput(
     case "bash": {
       const record = toRecord(input);
       const command = typeof record.command === "string" ? record.command : "";
-      // Strip leading shell comment lines so pattern matching operates on the
-      // actual command, not a `# description` prefix agents often prepend.
-      // Fall back to the raw command when stripping leaves nothing, so an
-      // all-comment command still evaluates against its literal text.
-      const matchValue = stripBashCommentLines(command) || command;
-      return {
-        surface: "bash",
-        values: [matchValue],
-        resultExtras: { command },
-      };
+      return normalizeBashCommand(command, []);
     }
 
     // --- MCP ---
@@ -226,3 +217,26 @@ function normalizeMcpTargets(targets: readonly string[]): NormalizedInput {
     resultExtras: { target: values[0] },
   };
 }
+
+/**
+ * The `bash` surface's normalized form: the command as typed, then the other
+ * spellings the shell runs identically, matched as aliases of one invocation.
+ *
+ * Leading shell comment lines are stripped from the typed command so pattern
+ * matching operates on the actual command, not a `# description` prefix agents
+ * often prepend; when stripping leaves nothing, an all-comment command still
+ * evaluates against its literal text. A spelling comes from the program
+ * analysis and is matched as given. `command` stays the typed text, because the
+ * prompt, the decision value, and the session-approval suggestion read it.
+ */
+export function normalizeBashCommand(
+  command: string,
+  spellings: readonly string[],
+): NormalizedInput {
+  const matchValue = stripBashCommentLines(command) || command;
+  return {
+    surface: "bash",
+    values: [...new Set([matchValue, ...spellings])],
+    resultExtras: { command },
+  };
+}

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

@@ -75,7 +75,7 @@ export function resolveBashCommandCheck(
   resolver: ScopedPermissionResolver,
 ): PermissionCheckResult {
   if (isTriviallyEmptyCommand(command)) {
-    return resolveOnBashSurface(command, agentName, resolver);
+    return resolveOnBashSurface(command, [], agentName, resolver);
   }
 
   if (!commands.some((cmd) => cmd.salvaged !== true)) {
@@ -86,7 +86,7 @@ export function resolveBashCommandCheck(
     // from the wreckage: `> f <<'M' 2>&1 | rm -rf /tmp/x` has zero primary
     // units and one salvaged one, and keying the check on the combined list
     // would silently drop a `deny` the pre-salvage gate reached (#875).
-    const whole = resolveOnBashSurface(command, agentName, resolver);
+    const whole = resolveOnBashSurface(command, [], agentName, resolver);
     if (whole.state === "deny") {
       return whole;
     }
@@ -107,7 +107,7 @@ export function resolveBashCommandCheck(
   );
   return (
     pickMostRestrictive(results) ??
-    resolveOnBashSurface(command, agentName, resolver)
+    resolveOnBashSurface(command, [], agentName, resolver)
   );
 }
 
@@ -122,7 +122,12 @@ function resolveCommandUnit(
   agentName: string | undefined,
   resolver: ScopedPermissionResolver,
 ): PermissionCheckResult {
-  const base = resolveOnBashSurface(cmd.text, agentName, resolver);
+  const base = resolveOnBashSurface(
+    cmd.text,
+    cmd.spellings ?? [],
+    agentName,
+    resolver,
+  );
   const floored =
     cmd.wrapperKind && base.state === "allow"
       ? resolveWrapperUnit(cmd, cmd.wrapperKind, base, agentName, resolver)
@@ -204,7 +209,7 @@ function resolveWrapperUnit(
   // `command`, and naming a fragment of the command line there would offer a
   // grant that does not cover what the user is looking at.
   return {
-    ...resolveOnBashSurface(inner, agentName, resolver),
+    ...resolveOnBashSurface(inner, [], agentName, resolver),
     command: base.command,
     floorExemption: cmd.floorExemption,
   };
@@ -225,21 +230,26 @@ function isTriviallyEmptyCommand(command: string): boolean {
 }
 
 /**
- * Resolve one command string against the `bash` surface's rules.
+ * Resolve one command string, and the other spellings the shell runs it by,
+ * against the `bash` surface's rules.
  *
  * Three callers share it: each command unit of the chain, the whole command
  * when the chain yields no units, and the inner command of a wrapper the floor
- * no longer covers.
+ * no longer covers. Only a unit has spellings: they come from the program
+ * analysis that produced it, and the whole command or a wrapper's inner text
+ * has no unit of its own to carry them.
  */
 function resolveOnBashSurface(
   command: string,
+  spellings: readonly string[],
   agentName: string | undefined,
   resolver: ScopedPermissionResolver,
 ): PermissionCheckResult {
   return resolver.resolve({
-    kind: "tool",
+    kind: "bash-command",
     surface: "bash",
-    input: { command },
+    command,
+    spellings,
     agentName,
   });
 }

package/src/path/expand-home.ts

@@ -29,7 +29,7 @@ const HOME_PREFIXES = ["~", "$HOME", "${HOME}"] as const;
  * All other patterns are returned unchanged.
  */
 export function expandHomePath(pattern: string): string {
-  const rest = afterHomePrefix(pattern);
+  const rest = splitHomePrefix(pattern);
   if (rest === undefined) return pattern;
   return rest === "" ? homedir() : join(homedir(), rest.slice(1));
 }
@@ -39,14 +39,18 @@ export function expandHomePath(pattern: string): string {
  * directory.
  */
 export function hasHomePrefix(value: string): boolean {
-  return afterHomePrefix(value) !== undefined;
+  return splitHomePrefix(value) !== undefined;
 }
 
 /**
  * What follows a recognized home prefix (`""`, or a separator and the rest),
  * or `undefined` when `value` has none.
+ *
+ * Exported so a caller that must not path-normalize the rest (a bash command
+ * string, which {@link expandHomePath}'s `join` would rewrite across its
+ * arguments) reads the same prefix table.
  */
-function afterHomePrefix(value: string): string | undefined {
+export function splitHomePrefix(value: string): string | undefined {
   for (const prefix of HOME_PREFIXES) {
     if (!value.startsWith(prefix)) continue;
     const rest = value.slice(prefix.length);

package/src/policy/permission-manager.ts

@@ -1,6 +1,9 @@
 import { join } from "node:path";
 import type { ResolvedAccessIntent } from "#src/access-intent/access-intent";
-import { normalizeInput } from "#src/access-intent/input-normalizer";
+import {
+  normalizeBashCommand,
+  normalizeInput,
+} from "#src/access-intent/input-normalizer";
 import { surfaceFamilyOf } from "#src/access-intent/path-surfaces";
 import { classifyToolKind } from "#src/access-intent/tool-kind";
 import {
@@ -321,9 +324,11 @@ export class PermissionManager implements ScopedPermissionManager {
    * extension surfaces). Path-bearing surfaces arrive as `"path-values"` via
    * the access-path gate (#502) or service/RPC builder (#503).
    * `"path-values"` → evaluates the precomputed values directly.
+   * `"bash-command"` → evaluates a bash command unit and its spellings as
+   * aliases through `normalizeBashCommand`.
    *
    * The manager stays string-based by design: it consumes `ResolvedAccessIntent`
-   * (`tool | path-values`) and never imports `AccessPath`. This deliberate
+   * (`tool | path-values | bash-command`) and never imports `AccessPath`. This deliberate
    * boundary is formalized in ADR-0002
    * (`docs/decisions/0002-path-values-string-boundary.md`) and guarded by a
    * `no-restricted-imports` lint rule on this file.
@@ -357,6 +362,22 @@ export class PermissionManager implements ScopedPermissionManager {
       );
     }
 
+    if (intent.kind === "bash-command") {
+      const { surface, values, resultExtras } = normalizeBashCommand(
+        intent.command,
+        intent.spellings,
+      );
+      return buildCheckResult(
+        surface,
+        values,
+        resultExtras,
+        surface,
+        surface,
+        fullRules,
+        this.flavor,
+      );
+    }
+
     // kind === "tool"
     const toolName = intent.surface.trim();
     const { surface, values, resultExtras } = normalizeInput(

package/src/policy/wildcard-matcher.ts

@@ -42,6 +42,16 @@ function escapeRegExp(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+/**
+ * Compile `pattern` once for repeated matching.
+ *
+ * A leading `~` / `$HOME` / `${HOME}` is expanded on the pattern only. The value
+ * side is not expanded here, because what a home prefix means depends on where
+ * the value came from: a bash program can rebind `HOME`. A value arrives
+ * already spelled by the producer that knows, as an alias matched alongside the
+ * typed text (`AccessPath.matchValues()` for a path, a bash command unit's
+ * `spellings`).
+ */
 export function compileWildcardPattern<TState>(
   pattern: string,
   state: TState,