@gotgenes/pi-permission-system 16.2.0 → 17.0.0

package/CHANGELOG.md

@@ -5,6 +5,40 @@ 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).
 
+## [17.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v16.2.1...pi-permission-system-v17.0.0) (2026-06-27)
+
+
+### ⚠ BREAKING CHANGES
+
+* **pi-permission-system:** the path surface now also matches the canonical (symlink-resolved) form of bash path-rule tokens, so a path rule can fire on a symlink alias it previously missed, changing decisions on upgrade with no config edit.
+* **pi-permission-system:** the path surface now also matches the canonical (symlink-resolved) form of a tool's file path. A path rule that previously matched only the as-typed spelling now also matches when the path resolves through a symlink to a target the pattern covers, which can change allow/deny decisions on upgrade with no config edit.
+
+### Features
+
+* **pi-permission-system:** add AccessPath.forPath and forLiteral factories ([4323cae](https://github.com/gotgenes/pi-packages/commit/4323cae859907dd62d9cb401c194443717ab752c)), closes [#486](https://github.com/gotgenes/pi-packages/issues/486)
+* **pi-permission-system:** match the canonical form on the bash-path gate ([6ce0c06](https://github.com/gotgenes/pi-packages/commit/6ce0c06b35c12eca32ffce5d4fe974c2f2dee393))
+* **pi-permission-system:** match the canonical form on the path tool gate ([869ca76](https://github.com/gotgenes/pi-packages/commit/869ca761cf3d7a8367eb932106065a866d996ce4))
+
+
+### Documentation
+
+* **pi-permission-system:** document canonical path-surface matching ([9606dce](https://github.com/gotgenes/pi-packages/commit/9606dce744bc1f95bd8424d2bb115a376d9a1191)), closes [#486](https://github.com/gotgenes/pi-packages/issues/486)
+
+## [16.2.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v16.2.0...pi-permission-system-v16.2.1) (2026-06-27)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** floor opaque bash -c/eval wrappers to ask ([#481](https://github.com/gotgenes/pi-packages/issues/481)) ([e69493c](https://github.com/gotgenes/pi-packages/commit/e69493c00a04fdcdc1a972ef04ffee5839c93d2a))
+* **pi-permission-system:** strip env-var assignment prefix from bash command units ([#481](https://github.com/gotgenes/pi-packages/issues/481)) ([1c99fb3](https://github.com/gotgenes/pi-packages/commit/1c99fb3835442dce3cb01b89f26db0a39084b7af))
+
+
+### Documentation
+
+* **pi-permission-system:** document env-prefix stripping and opaque bash-wrapper floor ([#481](https://github.com/gotgenes/pi-packages/issues/481)) ([40c0012](https://github.com/gotgenes/pi-packages/commit/40c001270249ace6a9d471c92063f9f09aa67238))
+* **pi-permission-system:** note opaque-wrapper sentinel in README and skill ([#481](https://github.com/gotgenes/pi-packages/issues/481)) ([e226fe7](https://github.com/gotgenes/pi-packages/commit/e226fe7a49218fac73f2dcb8c84cb13608d48fa0))
+* **pi-permission-system:** note prefix strip and opaque flag in commands() JSDoc ([#481](https://github.com/gotgenes/pi-packages/issues/481)) ([1892098](https://github.com/gotgenes/pi-packages/commit/18920980e0b17b6dd5e51a75fd103663f9313b32))
+
 ## [16.2.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v16.1.0...pi-permission-system-v16.2.0) (2026-06-26)
 
 

package/README.md

@@ -17,9 +17,9 @@ Permission enforcement extension for the [Pi](https://pi.mariozechner.at/) codin
 - **Enforces allow / ask / deny** at tool-call time with UI confirmation dialogs
 - **Controls bash commands** with wildcard pattern matching (`git *: ask`, `rm -rf *: deny`)
 - **Gates MCP and skill access** at server, tool, and skill-name granularity
-- **Protects sensitive file patterns** — cross-cutting `path` rules deny `.env`, `~/.ssh/*`, etc. across all tools and bash at once
+- **Protects sensitive file patterns** — cross-cutting `path` rules deny `.env`, `~/.ssh/*`, etc. across all tools and bash at once, matching both the path as referenced and its symlink-resolved form so a deny cannot be evaded through a symlink alias
 - **Guards external paths** — prompts before file tools or bash commands reach outside `cwd`
-- **Fails closed** — an internal gate error blocks the tool (with a `gate_error` review-log entry), and an unparseable bash command prompts (`ask`) rather than passing silently
+- **Fails closed** — an internal gate error blocks the tool (with a `gate_error` review-log entry), and an unparseable bash command — or an opaque `bash -c`/`eval` wrapper — prompts (`ask`) rather than passing silently
 - **Forwards prompts from subagents** — `ask` policies work even in non-UI execution contexts
 - **Broadcasts UI prompt events** — `permissions:ui_prompt` fires only when the permission system is about to invoke the active user-facing permission UI
 - **Native [`@gotgenes/pi-subagents`](https://github.com/gotgenes/pi-subagents) integration** — in-process child sessions register with the permission system automatically, enabling per-agent policy enforcement and `ask`-state forwarding to the parent UI without configuration
@@ -69,6 +69,7 @@ See [docs/session-approvals.md](docs/session-approvals.md) for details on sessio
 
 The `path` surface is a cross-cutting gate that applies to **all** file access — Pi tools, bash commands, MCP calls, and extension tools alike.
 Extension and MCP tools that operate on paths (via `input.path`, MCP's `input.arguments.path`, or a registered access extractor) are gated by default, so a `path` deny cannot be overridden by a per-tool allow — making it the right place to protect sensitive files like `.env` or `~/.ssh/*` from every tool at once.
+A `path` pattern matches both the path as the agent references it and its canonical (symlink-resolved) form, so a deny still fires when a symlink aliases a sensitive target.
 
 For per-tool path patterns (`read`, `write`, `edit`, `find`, `grep`, `ls`), patterns are matched against the file path from `input.path`.
 This lets you express rules like "allow reads but deny `.env` files" at the individual tool level.

package/package.json

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

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

@@ -17,8 +17,9 @@ export interface ToolAccessIntent {
 /**
  * Precomputed equivalent policy values for a path-shaped surface.
  *
- * Used by the bash-path gate (`path` surface), whose cd-resolved lexical
- * `string[]` carry no canonical-boundary notion.
+ * Not gate-emitted: the resolver produces it internally by unwrapping an
+ * `access-path` intent via `matchValues()`, keeping the low-level manager
+ * string-based (it never imports `AccessPath`). See {@link ResolvedAccessIntent}.
  */
 export interface PathValuesAccessIntent {
   kind: "path-values";
@@ -31,9 +32,9 @@ export interface PathValuesAccessIntent {
 /**
  * An `AccessPath` value object for a path-shaped surface.
  *
- * Used by the external-directory gates; lets `AccessPath` flow into the
- * resolver as a first-class variant so the resolver — not the gate — asks it
- * for `matchValues()` (Tell-Don't-Ask).
+ * Emitted by every path gate (the `path` and `external_directory` surfaces);
+ * lets `AccessPath` flow into the resolver as a first-class variant so the
+ * resolver — not the gate — asks it for `matchValues()` (Tell-Don't-Ask).
  */
 export interface AccessPathAccessIntent {
   kind: "access-path";
@@ -42,11 +43,8 @@ export interface AccessPathAccessIntent {
   agentName?: string;
 }
 
-/** What a gate emits — the full three-variant union. */
-export type AccessIntent =
-  | ToolAccessIntent
-  | PathValuesAccessIntent
-  | AccessPathAccessIntent;
+/** What a gate emits — a raw tool input or an `AccessPath`. */
+export type AccessIntent = ToolAccessIntent | AccessPathAccessIntent;
 
 /**
  * What the manager consumes — the `access-path` variant has already been

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

@@ -20,7 +20,9 @@ import {
  * - {@link value} returns `string` — the lexical absolute form, for display,
  *   approval patterns, decision values, and logs.
  *
- * Construct via {@link forExternalDirectory}; the constructor is private.
+ * Construct via {@link forPath} (resolved, with optional cd-folded base) or
+ * {@link forLiteral} (literal-only, for an unknown base); the constructor is
+ * private.
  */
 export class AccessPath {
   private constructor(
@@ -65,24 +67,45 @@ export class AccessPath {
   }
 
   /**
-   * Build an `AccessPath` for a tool-input or bash-token path resolved against
-   * `cwd`.
+   * Build an `AccessPath` for a tool-input or bash-token path, resolved against
+   * `resolveBase` (the cd-folded effective directory; defaults to `cwd`).
    *
-   * - `matchValues()` returns the same set as the former
-   *   `getExternalDirectoryPolicyValues(pathValue, cwd)` — the lexical alias
-   *   union from `getPathPolicyValues` plus the canonical alias from
-   *   `canonicalNormalizePathForComparison` (#418).
-   * - `boundaryValue()` returns `canonicalNormalizePathForComparison(pathValue, cwd)`,
-   *   which is win32-lowercased (#382) — do not substitute a raw
-   *   `canonicalizePath` output here.
-   * - `value()` returns `normalizePathForComparison(pathValue, cwd)`, the
-   *   absolute lexical form.
+   * Serves every path surface: the tool path gate, the tool external-directory
+   * gate, and the bash path/external-directory gates (which pass a cd-resolved
+   * `resolveBase`).
+   *
+   * - `matchValues()` returns the lexical alias union from `getPathPolicyValues`
+   *   plus the canonical alias from `canonicalNormalizePathForComparison`
+   *   (#418), so a config pattern on either the typed or symlink-resolved form
+   *   matches.
+   * - `boundaryValue()` returns
+   *   `canonicalNormalizePathForComparison(pathValue, resolveBase)`, which is
+   *   win32-lowercased (#382) — do not substitute a raw `canonicalizePath`
+   *   output here.
+   * - `value()` returns `normalizePathForComparison(pathValue, resolveBase)`,
+   *   the absolute lexical form.
    */
-  static forExternalDirectory(pathValue: string, cwd: string): AccessPath {
+  static forPath(
+    pathValue: string,
+    options: { cwd: string; resolveBase?: string },
+  ): AccessPath {
+    const { cwd, resolveBase = cwd } = options;
     return new AccessPath(
-      normalizePathForComparison(pathValue, cwd),
-      getPathPolicyValues(pathValue, { cwd }),
-      canonicalNormalizePathForComparison(pathValue, cwd),
+      normalizePathForComparison(pathValue, resolveBase),
+      getPathPolicyValues(pathValue, { cwd, resolveBase }),
+      canonicalNormalizePathForComparison(pathValue, resolveBase),
     );
   }
+
+  /**
+   * Build a literal-only `AccessPath` for a path whose effective base is
+   * unknown (a relative bash token after a non-literal `cd`).
+   *
+   * Carries no canonical alias and no absolute resolution — `matchValues()` is
+   * `[literal]` (or `[]` when empty) and `boundaryValue()` is `""` — so no
+   * spurious absolute or symlink-resolved rule can match (#393).
+   */
+  static forLiteral(literal: string): AccessPath {
+    return new AccessPath(literal, literal ? [literal] : [], "");
+  }
 }

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

@@ -18,6 +18,12 @@ export interface BashCommand {
    * for a current-shell (top-level) command.
    */
   readonly context?: BashCommandContext;
+  /**
+   * True when this is an opaque-payload wrapper (`bash -c`/`eval`) whose inner
+   * program is not re-parsed; its decision is floored to at least `ask` so it
+   * cannot ride a permissive `allow`.
+   */
+  readonly opaque?: boolean;
 }
 
 // ── Command enumeration ──────────────────────────────────────────────────────
@@ -75,6 +81,9 @@ const NESTED_EXECUTION_CONTEXTS = new Map<string, BashCommandContext>([
  *
  * The enclosing command/subshell is always still emitted whole, so adding the
  * nested units can only ever produce a more-restrictive decision, never weaker.
+ *
+ * Each emitted command unit has any leading `variable_assignment` prefix
+ * stripped (so an env-var prefix cannot defeat a command-pattern rule).
  */
 export function collectCommands(node: TSNode): BashCommand[] {
   const out: BashCommand[] = [];
@@ -93,7 +102,9 @@ function collectCommandsInto(
   if (COMMAND_ENUM_SKIP.has(node.type)) return;
 
   if (node.type === "command") {
-    out.push(makeUnit(node.text, context));
+    out.push(
+      makeUnit(commandUnitText(node), context, isOpaqueWrapperCommand(node)),
+    );
     // A command's text already contains any substitution; descend its subtree
     // to ALSO emit the inner commands of command/process substitutions.
     collectSubstitutionCommands(node, out);
@@ -119,8 +130,74 @@ function collectCommandsInto(
 function makeUnit(
   text: string,
   context: BashCommandContext | undefined,
+  opaque = false,
 ): BashCommand {
-  return context ? { text, context } : { text };
+  const unit: BashCommand = context ? { text, context } : { text };
+  return opaque ? { ...unit, opaque } : unit;
+}
+
+/**
+ * Shell command names whose `-c` flag introduces an opaque inline program.
+ */
+const SHELL_WRAPPER_NAMES = new Set(["bash", "sh", "dash", "zsh", "ksh"]);
+
+/**
+ * True when a `command` node is an opaque-payload wrapper: a shell
+ * (`bash`/`sh`/`dash`/`zsh`/`ksh`) invoked with a `-c` flag, or `eval`. Its
+ * inner program is a quoted argument the enumerator does not re-parse, so the
+ * wrapper's decision is later floored to at least `ask`.
+ *
+ * The command name is matched on its basename (so `/bin/bash -c …` counts), and
+ * a `-c` flag is recognized within a short-flag cluster (`-c`, `-ec`, `-xc`).
+ * A leading `variable_assignment` prefix is skipped, matching `commandUnitText`.
+ */
+function isOpaqueWrapperCommand(node: TSNode): boolean {
+  let commandName: string | undefined;
+  let sawShortFlagC = false;
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child?.isNamed) continue;
+    if (child.type === "variable_assignment") continue;
+    if (commandName === undefined) {
+      commandName = basename(child.text);
+      continue;
+    }
+    const text = child.text;
+    if (text === "--") break;
+    if (text.startsWith("-") && !text.startsWith("--") && text.includes("c")) {
+      sawShortFlagC = true;
+    }
+  }
+  if (commandName === undefined) return false;
+  if (commandName === "eval") return true;
+  return SHELL_WRAPPER_NAMES.has(commandName) && sawShortFlagC;
+}
+
+/** The final path segment of a command name (`/bin/bash` → `bash`). */
+function basename(name: string): string {
+  const slash = name.lastIndexOf("/");
+  return slash === -1 ? name : name.slice(slash + 1);
+}
+
+/**
+ * The command-pattern text of a `command` node, with any leading
+ * `variable_assignment` prefix stripped.
+ *
+ * An env-var prefix (`AWS_PROFILE=prod aws …`, `PGPASSWORD=…`) is part of the
+ * `command` node's text but must not defeat a rule that gates the underlying
+ * command, so matching targets the text from the first non-assignment child
+ * (the `command_name`) onward, sliced verbatim to preserve spacing. A pure
+ * assignment (`FOO=bar`, no `command_name`) runs no command and is returned
+ * unchanged.
+ */
+function commandUnitText(node: TSNode): string {
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child?.isNamed && child.type !== "variable_assignment") {
+      return node.text.slice(child.startIndex - node.startIndex);
+    }
+  }
+  return node.text;
 }
 
 function descendCommandChildren(

package/src/access-intent/bash/cwd-projection.ts

@@ -17,7 +17,6 @@ import {
 } from "#src/access-intent/bash/token-collection";
 import { canonicalizePath } from "#src/canonicalize-path";
 import {
-  getPathPolicyValues,
   isPathWithinDirectory,
   isSafeSystemPath,
   normalizePathForComparison,
@@ -54,8 +53,8 @@ interface PathCandidate {
 export interface BashPathRuleCandidate {
   /** Raw path-like token shown in prompts, logs, and session approvals. */
   readonly token: string;
-  /** Equivalent values used for permission policy matching. */
-  readonly policyValues: readonly string[];
+  /** The path's lexical and canonical forms for permission policy matching. */
+  readonly path: AccessPath;
 }
 
 // ── Walk-time constants ──────────────────────────────────────────────────────
@@ -379,18 +378,20 @@ function isRelativeCandidate(candidate: string): boolean {
   return !candidate.startsWith("/") && !candidate.startsWith("~");
 }
 
-function getPolicyValuesForRuleCandidate(
+function buildRuleCandidatePath(
   candidate: string,
   base: EffectiveBase,
   cwd: string,
-): string[] {
+): AccessPath {
+  // An unknown base + relative candidate stays literal-only: a resolved
+  // absolute or canonical alias would resolve against the wrong directory and
+  // could spuriously match a rule (#393).
   if (base.kind === "unknown" && isRelativeCandidate(candidate)) {
-    const literal = normalizePathPolicyLiteral(candidate);
-    return literal ? [literal] : [];
+    return AccessPath.forLiteral(normalizePathPolicyLiteral(candidate));
   }
 
   const resolveBase = base.kind === "known" ? resolve(cwd, base.offset) : cwd;
-  return getPathPolicyValues(candidate, { cwd, resolveBase });
+  return AccessPath.forPath(candidate, { cwd, resolveBase });
 }
 
 // ── Projection functions ─────────────────────────────────────────────────────
@@ -435,7 +436,7 @@ export function projectExternalPaths(
         seen.add(canonical);
         // The factory recomputes the canonical via canonicalNormalizePathForComparison
         // (win32-lowercased, #382) rather than reusing the raw canonicalizePath output.
-        externalPaths.push(AccessPath.forExternalDirectory(lexical, cwd));
+        externalPaths.push(AccessPath.forPath(lexical, { cwd }));
       }
       continue;
     }
@@ -457,7 +458,7 @@ export function projectExternalPaths(
       seen.add(canonical);
       // The factory recomputes the canonical via canonicalNormalizePathForComparison
       // (win32-lowercased, #382) rather than reusing the raw canonicalizePath output.
-      externalPaths.push(AccessPath.forExternalDirectory(lexical, cwd));
+      externalPaths.push(AccessPath.forPath(lexical, { cwd }));
     }
   }
 
@@ -485,13 +486,14 @@ export function projectRuleCandidates(
     const candidate = classifyTokenAsRuleCandidate(token);
     if (!candidate) continue;
 
-    const policyValues = getPolicyValuesForRuleCandidate(candidate, base, cwd);
-    if (policyValues.length === 0) continue;
+    const path = buildRuleCandidatePath(candidate, base, cwd);
+    const matchValues = path.matchValues();
+    if (matchValues.length === 0) continue;
 
-    const key = policyValues.join("\0");
+    const key = matchValues.join("\0");
     if (seen.has(key)) continue;
     seen.add(key);
-    result.push({ token: candidate, policyValues });
+    result.push({ token: candidate, path });
   }
 
   return result;

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

@@ -8,6 +8,8 @@ import { memoizeAsyncWithRetry } from "#src/async-cache";
 export interface TSNode {
   readonly type: string;
   readonly text: string;
+  /** Absolute byte offset of this node's start in the parsed source. */
+  readonly startIndex: number;
   readonly childCount: number;
   /** False for anonymous tokens (operators, delimiters); true for named nodes. */
   readonly isNamed: boolean;

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

@@ -61,6 +61,9 @@ export class BashProgram {
    * Splits on the shell chain operators (`&&`, `||`, `;`, `|`, `&`, newlines);
    * quotes, command substitution, and subshells are respected by the parser and
    * are NOT split — a subshell or other compound statement is emitted whole.
+   * Each unit has any leading `variable_assignment` prefix stripped, and an
+   * opaque-payload wrapper (`bash -c`/`eval`) is flagged `opaque` so its decision
+   * is floored to `ask`.
    * May be empty (e.g. an empty command or a comment-only line); callers fall
    * back to the whole command so the surface is never evaluated weaker than
    * before.

package/src/builtin-tool-input-formatters.ts

@@ -5,12 +5,12 @@
  * through exactly the same path a third-party extension would use.
  */
 
-import { toRecord } from "./common";
 import type {
   ToolInputFormatter,
   ToolInputFormatterRegistry,
 } from "./tool-input-formatter-registry";
 import { truncateInlineText } from "./tool-input-preview";
+import { toRecord } from "./value-guards";
 
 /** Maximum total length of the generated argument summary (before "with " prefix). */
 const MCP_ARGS_SUMMARY_MAX_LENGTH = 160;

package/src/config-loader.ts

@@ -1,12 +1,5 @@
 import { existsSync, readFileSync } from "node:fs";
 import { normalize } from "node:path";
-import {
-  isDenyWithReason,
-  isPermissionState,
-  normalizeOptionalPositiveInt,
-  normalizeOptionalStringArray,
-  toRecord,
-} from "./common";
 import {
   getGlobalConfigPath,
   getLegacyExtensionConfigPath,
@@ -16,6 +9,13 @@ import {
 } from "./config-paths";
 import { mergeFlatPermissions } from "./permission-merge";
 import type { FlatPermissionConfig, PatternValue } from "./types";
+import {
+  isDenyWithReason,
+  isPermissionState,
+  normalizeOptionalPositiveInt,
+  normalizeOptionalStringArray,
+  toRecord,
+} from "./value-guards";
 
 /**
  * Unified config shape combining runtime knobs and flat permission policy.

package/src/forwarded-permissions/permission-forwarder.ts

@@ -5,7 +5,6 @@ import {
   getActiveAgentNameFromSystemPrompt,
   type SessionEntryView,
 } from "#src/active-agent";
-import { toRecord } from "#src/common";
 import type { ConfigReader } from "#src/config-store";
 import type {
   PermissionDecisionUi,
@@ -31,6 +30,7 @@ import { buildForwardedUiPrompt } from "#src/permission-ui-prompt";
 import type { DebugReviewLogger } from "#src/session-logger";
 import { isSubagentExecutionContext } from "#src/subagent-context";
 import type { SubagentSessionRegistry } from "#src/subagent-registry";
+import { toRecord } from "#src/value-guards";
 import { shouldAutoApprovePermissionState } from "#src/yolo-mode";
 
 import {

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

@@ -19,6 +19,12 @@ import type { PermissionCheckResult } from "#src/types";
  * `commandContext` (set only for a nested command), so the prompt,
  * session-approval suggestion, and decision event scope to that command.
  *
+ * An opaque-payload wrapper unit (`bash -c`/`eval`, flagged `opaque` by the
+ * enumerator) has its inner program hidden behind a quoted argument, so an
+ * `allow` is floored up to a synthetic `ask` (the `<opaque-bash-wrapper>`
+ * pattern) to keep it from riding a permissive rule; an explicit `deny`/`ask`
+ * on the wrapper is left untouched (`deny > ask > allow`).
+ *
  * When `commands` is empty there are two cases. A trivially-empty command (an
  * empty, whitespace-only, or comment-only line) has genuinely nothing to gate,
  * so the whole `command` is resolved as before. A non-empty command that parsed
@@ -56,12 +62,20 @@ export function resolveBashCommandCheck(
   }
 
   const results = commands.map((cmd) => {
-    const result = resolver.resolve({
+    const base = resolver.resolve({
       kind: "tool",
       surface: "bash",
       input: { command: cmd.text },
       agentName,
     });
+    const result =
+      cmd.opaque && base.state === "allow"
+        ? {
+            ...base,
+            state: "ask" as const,
+            matchedPattern: "<opaque-bash-wrapper>",
+          }
+        : base;
     return cmd.context ? { ...result, commandContext: cmd.context } : result;
   });
   return (

package/src/handlers/gates/bash-external-directory.ts

@@ -1,8 +1,8 @@
 import type { BashProgram } from "#src/access-intent/bash/program";
-import { getNonEmptyString, toRecord } from "#src/common";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
+import { getNonEmptyString, toRecord } from "#src/value-guards";
 import type { GateResult } from "./descriptor";
 import { formatBashExternalDirectoryAskPrompt } from "./external-directory-messages";
 import { selectUncoveredExternalPaths } from "./external-directory-policy";

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

@@ -1,9 +1,10 @@
+import type { AccessPath } from "#src/access-intent/access-path";
 import type { BashProgram } from "#src/access-intent/bash/program";
-import { getNonEmptyString, toRecord } from "#src/common";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
 import type { PermissionCheckResult } from "#src/types";
+import { getNonEmptyString, toRecord } from "#src/value-guards";
 import { pickMostRestrictive } from "./candidate-check";
 import type { GateResult } from "./descriptor";
 import { formatPathAskPrompt } from "./path";
@@ -41,20 +42,20 @@ export function describeBashPathGate(
   const tokens = candidates.map(({ token }) => token);
 
   // Tokens whose resolved state needs a check (deny/ask), paired with the raw
-  // token (prompt/decision display) and its policy values (the first of which
-  // is the canonical absolute path the approval pattern is derived from).
+  // token (prompt/decision display) and its `AccessPath` (whose `value()` is
+  // the lexical absolute path the approval pattern is derived from).
   const uncovered: Array<{
     token: string;
-    policyValues: readonly string[];
+    path: AccessPath;
     check: PermissionCheckResult;
   }> = [];
   let allSessionCovered = true;
 
-  for (const { token, policyValues } of candidates) {
+  for (const { token, path } of candidates) {
     const check = resolver.resolve({
-      kind: "path-values",
+      kind: "access-path",
       surface: "path",
-      values: policyValues,
+      path,
       agentName: tcc.agentName ?? undefined,
     });
 
@@ -71,11 +72,11 @@ export function describeBashPathGate(
     }
 
     if (check.state === "deny") {
-      uncovered.push({ token, policyValues, check });
+      uncovered.push({ token, path, check });
       break; // Short-circuit on deny.
     }
     if (check.state === "ask") {
-      uncovered.push({ token, policyValues, check });
+      uncovered.push({ token, path, check });
     }
   }
 
@@ -108,11 +109,10 @@ export function describeBashPathGate(
   // All tokens evaluate to allow — no restriction.
   if (!worstCheck || !worstToken || !worstEntry) return null;
 
-  // Derive the pattern from the canonical absolute policy value (the cd-aware
-  // resolved path), so it matches the values a later call produces. Falls back
-  // to the raw token only when no base was resolvable (no cwd / unknown cd).
-  const approvalBase = worstEntry.policyValues[0] ?? worstToken;
-  const pattern = deriveApprovalPattern(approvalBase);
+  // Derive the pattern from the lexical absolute form (the cd-aware resolved
+  // path), so it matches the values a later call produces. For an unknown base
+  // (`forLiteral`) `value()` is the raw token.
+  const pattern = deriveApprovalPattern(worstEntry.path.value());
   const askMessage = formatPathAskPrompt(
     tcc.toolName,
     worstToken,

package/src/handlers/gates/external-directory.ts

@@ -42,10 +42,9 @@ export function describeExternalDirectoryGate(
   // The boundary decision (above) and the infrastructure-read containment
   // check (below) use the canonical, symlink-resolved path; pattern matching
   // uses the typed and resolved aliases (#418).
-  const accessPath = AccessPath.forExternalDirectory(
-    externalDirectoryPath,
-    tcc.cwd,
-  );
+  const accessPath = AccessPath.forPath(externalDirectoryPath, {
+    cwd: tcc.cwd,
+  });
   const canonicalExtPath = accessPath.boundaryValue();
 
   // ── Pi infrastructure read bypass ──────────────────────────────────────

package/src/handlers/gates/path.ts

@@ -1,4 +1,5 @@
-import { getToolInputPath, normalizePathForComparison } from "#src/path-utils";
+import { AccessPath } from "#src/access-intent/access-path";
+import { getToolInputPath } from "#src/path-utils";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
@@ -22,10 +23,14 @@ export function describePathGate(
   const filePath = getToolInputPath(tcc.toolName, tcc.input, extractors);
   if (!filePath) return null;
 
+  // Emit an access-path intent so the resolver matches the lexical aliases
+  // *and* the canonical (symlink-resolved) form, the same set
+  // `external_directory` matches (#418, #486).
+  const accessPath = AccessPath.forPath(filePath, { cwd: tcc.cwd });
   const check = resolver.resolve({
-    kind: "tool",
+    kind: "access-path",
     surface: "path",
-    input: { path: filePath },
+    path: accessPath,
     agentName: tcc.agentName ?? undefined,
   });
 
@@ -36,10 +41,9 @@ export function describePathGate(
   // "path" key should not trigger path-level prompts (#58).
   if (check.matchedPattern === undefined) return null;
 
-  // Resolve to the canonical (cwd-anchored, absolute) path so the approval
-  // pattern matches the policy values a later call produces.
-  const approvalPath = normalizePathForComparison(filePath, tcc.cwd);
-  const pattern = deriveApprovalPattern(approvalPath);
+  // Derive the approval pattern from the lexical absolute form so it matches
+  // the policy values a later call produces.
+  const pattern = deriveApprovalPattern(accessPath.value());
 
   const descriptor: GateDescriptor = {
     surface: "path",

package/src/handlers/gates/skill-read.ts

@@ -1,8 +1,8 @@
-import { toRecord } from "#src/common";
 import { normalizePathForComparison } from "#src/path-utils";
 import { formatSkillPathAskPrompt } from "#src/permission-prompts";
 import type { SkillPromptEntry } from "#src/skill-prompt-sanitizer";
 import { findSkillPathMatch } from "#src/skill-prompt-sanitizer";
+import { toRecord } from "#src/value-guards";
 import type { GateDescriptor } from "./descriptor";
 import type { ToolCallContext } from "./types";
 

package/src/handlers/gates/tool-call-gate-pipeline.ts

@@ -1,5 +1,4 @@
 import { BashProgram } from "#src/access-intent/bash/program";
-import { getNonEmptyString, toRecord } from "#src/common";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import type { SkillPromptEntry } from "#src/skill-prompt-sanitizer";
 import type { ToolAccessExtractorLookup } from "#src/tool-access-extractor-registry";
@@ -8,6 +7,7 @@ import {
   ToolPreviewFormatter,
   type ToolPreviewFormatterOptions,
 } from "#src/tool-preview-formatter";
+import { getNonEmptyString, toRecord } from "#src/value-guards";
 import { resolveBashCommandCheck } from "./bash-command";
 import { describeBashExternalDirectoryGate } from "./bash-external-directory";
 import { describeBashPathGate } from "./bash-path";