@gotgenes/pi-permission-system 23.0.3 → 25.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).
 
+## [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)
+
+
+### ⚠ BREAKING CHANGES
+
+* **pi-permission-system:** an authorizer chain link's `allow` on a forwarded subagent ask raised by the `path` or `external_directory` gate is now downgraded to `defer`, so the request falls through to an interactive prompt. This affects only an operator running an allow-capable third-party link named in `authorizerChain`; the first-party model judge is deny-first and is unaffected, as are forwarded `bash` asks and per-tool-gated asks. See packages/pi-permission-system/docs/migration/0635-forwarded-ask-delegation-envelope.md
+
+### Bug Fixes
+
+* **pi-permission-system:** carry forwarded access facts to the Authorizer Chain ([#635](https://github.com/gotgenes/pi-packages/issues/635)) ([c0790ad](https://github.com/gotgenes/pi-packages/commit/c0790ad6d1d15defaba60097d803618b4d8c461c))
+
 ## [23.0.3](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v23.0.2...pi-permission-system-v23.0.3) (2026-07-26)
 
 

package/dist/public.d.ts

@@ -195,8 +195,10 @@ interface PromptPermissionDetails {
      * The child-fixed access facts the raising gate computed (surface + match
      * set). Rides through the runner to the escalation edge, which completes
      * them into a `ForwardedAccessIntent` by stamping `requesterCwd` and
-     * `principal`. Absent for a serving-node local prompt reconstructed from a
-     * forwarded request.
+     * `principal`. On a serving node these facts are projected back off the
+     * forwarded request, so a forwarded ask reaches the `Authorizer` chain with
+     * the same evidence as a local one; only a version-skew request that carried
+     * no intent leaves this absent.
      */
     accessIntent?: ForwardedAccessFacts;
 }

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.
 
@@ -209,6 +209,9 @@ Three invariants govern the chain:
 
 The chain owner caps every link with a **bounded-delegation checkpoint**: a link's `allow` on an excluded surface (`external_directory` or the `path` surface) is downgraded to `defer`, so a buggy or over-eager judge can never approve access outside your policy.
 Deny and defer are never capped.
+The excluded surface is the **gate** surface the rule fired on, not the tool name displayed in the prompt — so a `write` blocked by a `path` rule is capped.
+This holds for an ask forwarded up from a subagent exactly as it does for a local one.
+See [migration/0635-forwarded-ask-delegation-envelope.md](migration/0635-forwarded-ask-delegation-envelope.md).
 
 Extension authors: register a link from a `permissions:ready` handler via `getPermissionsService().registerAuthorizer(name, authorize)`; the callback receives the ask details and a narrow, session-scoped `PermissionQuery` (`checkPermission` / `getToolPermission`) so it can consult the deterministic engine at gate parity.
 Registration returns a disposer, and only one link may hold a given name.
@@ -584,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
 
@@ -641,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
 {
@@ -658,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/migration/0635-forwarded-ask-delegation-envelope.md

@@ -0,0 +1,42 @@
+# Migration guide: forwarded asks and the bounded-delegation checkpoint
+
+Starting with the release that closes #635, a permission request forwarded up from a subagent carries the **child-fixed access facts** through to the authorizer chain.
+As a side effect, the bounded-delegation checkpoint now applies to forwarded asks the same way it already applied to local ones.
+This is a **breaking change** for one narrow configuration.
+
+## Who is affected
+
+You are affected only if **all** of the following hold:
+
+- You name an authorizer chain link in `authorizerChain`, and
+- that link is **allow-capable** (it can return `allow`, not only `deny` / `defer`), and
+- a subagent forwards an `ask` to your session that was raised by the `path` or `external_directory` gate.
+
+If you run no chain link, or run only a deny-first link — including the first-party [`@gotgenes/pi-permission-model-judge`](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-model-judge), which only ever denies or defers — **nothing changes for you**.
+
+## What changed
+
+The checkpoint downgrades a link's `allow` to `defer` on the excluded surfaces (`path`, `external_directory`), so the request falls through to an interactive prompt instead.
+It selects the surface from the **gate** surface — the surface the matching rule lives on — falling back to the displayed surface when no gate surface is available.
+
+A forwarded request previously arrived with no gate surface, so the checkpoint fell back to the child's *display* surface, which is the tool name (`write`, `edit`, `read`).
+A tool name is not an excluded surface, so a link's `allow` on a forwarded `path`-gated request was honored.
+The identical request made directly in the same session was capped, because a local request always carries its gate surface.
+
+Forwarding was therefore a way around your own delegation boundary: a link could approve `~/.ssh/config` for a subagent that it could not approve for the main session.
+Now the gate surface crosses the forwarding hop, and both paths behave identically.
+
+Unchanged: a forwarded `bash` ask, and a forwarded tool ask gated by a per-tool rule (`write: ask`), are both already on non-excluded surfaces and are not capped.
+`deny` and `defer` verdicts were never capped and still are not.
+
+## What you need to do
+
+Nothing, unless you run an allow-capable link.
+
+If you do, expect an interactive prompt where that link previously auto-approved a forwarded subagent request for a path.
+To keep such a request from prompting, grant it in policy rather than through the link — the `path` and `external_directory` rules in your config are consulted before the chain runs, so an `allow` there resolves the request without reaching an authorizer at all.
+
+## Related
+
+Issue #620 will replace the whole-`path` exclusion with a narrower secret-shaped one, letting a link allow a non-secret path again while keeping secret-shaped paths capped.
+That refinement applies to local and forwarded asks alike, so the two paths stay aligned.

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": "23.0.3",
+  "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/authority/forwarded-request-server.ts

@@ -5,6 +5,7 @@ import {
 } from "#src/authority/forwarder-context";
 import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
 import {
+  type ForwardedAccessFacts,
   type ForwardedAccessIntent,
   type ForwardedPermissionRequest,
   type ForwardedPermissionResponse,
@@ -93,7 +94,14 @@ function formatForwardedPermissionPrompt(
 /**
  * Map a forwarded request onto the escalated ask's details, carrying the
  * forwarded provenance (requester agent/session + the child's original display
- * projection) so `LocalUserAuthorizer` emits a non-degraded broadcast (#292).
+ * projection) so `LocalUserAuthorizer` emits a non-degraded broadcast (#292),
+ * plus the child-fixed access facts so the serving node's `Authorizer` chain
+ * judges a forwarded ask on the same evidence as a local one (ADR 0008; #635).
+ *
+ * The display `surface` and the fact `surface` are distinct and both belong
+ * here: the former is the child's tool name (what the UI shows), the latter the
+ * gate surface the rule fired on (what the bounded-delegation checkpoint
+ * excludes on).
  */
 function buildForwardedAskDetails(
   request: ForwardedPermissionRequest,
@@ -114,6 +122,33 @@ function buildForwardedAskDetails(
     ...(request.sessionApproval
       ? { sessionApproval: request.sessionApproval }
       : {}),
+    // Absent for a version-skew request that carried no intent — which the
+    // delegation envelope reads as "surface undetermined" and fail-safes to
+    // excluded, so absence must stay absence rather than become `undefined`.
+    ...(request.accessIntent
+      ? { accessIntent: toAccessFacts(request.accessIntent) }
+      : {}),
+  };
+}
+
+/**
+ * Project the wire intent down to the child-fixed access facts an `Authorizer`
+ * may see.
+ *
+ * Field-by-field rather than a spread, because this is a disclosure boundary:
+ * `requesterCwd` and `principal` are requester identity for the serving node's
+ * own resolution (ADR 0008 §3) and stay off the ask details. A link that needs
+ * requester identity reads `details.forwarding`. `ForwardedAccessIntent`
+ * extends `ForwardedAccessFacts`, so a spread would type-check while widening
+ * disclosure at runtime; the explicit return type makes any future field on
+ * `ForwardedAccessFacts` a compile error here until it is deliberately
+ * projected or deliberately withheld.
+ */
+function toAccessFacts(intent: ForwardedAccessIntent): ForwardedAccessFacts {
+  return {
+    surface: intent.surface,
+    matchValues: intent.matchValues,
+    boundaryValue: intent.boundaryValue,
   };
 }
 

package/src/authority/permission-prompter.ts

@@ -53,8 +53,10 @@ export interface PromptPermissionDetails {
    * The child-fixed access facts the raising gate computed (surface + match
    * set). Rides through the runner to the escalation edge, which completes
    * them into a `ForwardedAccessIntent` by stamping `requesterCwd` and
-   * `principal`. Absent for a serving-node local prompt reconstructed from a
-   * forwarded request.
+   * `principal`. On a serving node these facts are projected back off the
+   * forwarded request, so a forwarded ask reaches the `Authorizer` chain with
+   * the same evidence as a local one; only a version-skew request that carried
+   * no intent leaves this absent.
    */
   accessIntent?: ForwardedAccessFacts;
 }

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;
 }