@gotgenes/pi-permission-system 17.1.1 → 18.0.0

package/CHANGELOG.md

@@ -5,6 +5,32 @@ 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).
 
+## [18.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v17.1.1...pi-permission-system-v18.0.0) (2026-06-29)
+
+
+### ⚠ BREAKING CHANGES
+
+* **pi-permission-system:** A permissions:rpc:check query for a `path` / `external_directory` / path-bearing surface now matches the canonical (symlink-resolved) alias, and a `path` / path-bearing query now evaluates the supplied path instead of collapsing to `*`.
+* **pi-permission-system:** A service (`getPermissionsService().checkPermission`) query for a `path` / `external_directory` / path-bearing surface now matches the canonical (symlink-resolved) alias, and a `path` / path-bearing query now evaluates the supplied path instead of collapsing to `*`. A symlinked path can now match a rule on its canonical target.
+* **pi-permission-system:** a per-tool path rule (e.g. `read: deny *.env`) now also fires when a symlink's resolved target matches the pattern, where previously only the lexically-referenced spelling matched. A symlink alias can no longer evade a per-tool deny/allow.
+
+### Features
+
+* **pi-permission-system:** match the canonical form on service path queries ([be4a3e7](https://github.com/gotgenes/pi-packages/commit/be4a3e7f48e700db4c667ce8176459a1e89820b4))
+* **pi-permission-system:** match the canonical form on the per-tool path gate ([ad36e78](https://github.com/gotgenes/pi-packages/commit/ad36e7860084be7692cb142f50c8818bd013ec38))
+* **pi-permission-system:** match the canonical form on the RPC check query ([bb04ca5](https://github.com/gotgenes/pi-packages/commit/bb04ca5d0bae265570144f7d76dee2bad9269f94))
+
+
+### Bug Fixes
+
+* **pi-permission-system:** remove unused join import; annotate closed findings ([#504](https://github.com/gotgenes/pi-packages/issues/504)) ([eb7c7b2](https://github.com/gotgenes/pi-packages/commit/eb7c7b298e21358d831892545b5dd8d3e9fb340a))
+
+
+### Documentation
+
+* **pi-permission-system:** document canonical per-tool path matching ([bafa492](https://github.com/gotgenes/pi-packages/commit/bafa492cf8517902aea5a44d6ea59d4b33e7f754))
+* **pi-permission-system:** document canonical service/RPC path matching ([35c36fa](https://github.com/gotgenes/pi-packages/commit/35c36fa9f7954aa84eb468954660b5857e067be3))
+
 ## [17.1.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v17.1.0...pi-permission-system-v17.1.1) (2026-06-29)
 
 

package/README.md

@@ -73,6 +73,7 @@ A `path` pattern matches both the path as the agent references it and its canoni
 
 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.
+Like the cross-cutting `path` surface, per-tool patterns match both the referenced path and its canonical (symlink-resolved) form, so a per-tool deny resists symlink-alias evasion.
 When Pi's current working directory is known, relative path inputs also match their cwd-normalized absolute form, so `src/App.jsx` can match both `src/*` and `/workspace/project/*`.
 
 The `external_directory` surface is the CWD-boundary gate: it decides whether reaching **outside** the working tree is allowed, and accepts a pattern map so you can allow specific outside-CWD directories without opening up all external access.

package/package.json

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

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

@@ -32,9 +32,12 @@ export interface PathValuesAccessIntent {
 /**
  * An `AccessPath` value object for a path-shaped surface.
  *
- * 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).
+ * Built for every path-shaped surface: the cross-cutting `path` and
+ * `external_directory` gates, the per-tool path-bearing surfaces
+ * (`read`/`write`/`edit`/`grep`/`find`/`ls`, #502), and the service/RPC policy
+ * queries for those surfaces (#503). Lets `AccessPath` flow into the resolver
+ * as a first-class variant so the resolver — not the producer — asks it for
+ * `matchValues()` (Tell-Don't-Ask).
  */
 export interface AccessPathAccessIntent {
   kind: "access-path";

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

@@ -73,10 +73,6 @@ export class BashProgram {
    * back to the whole command so the surface is never evaluated weaker than
    * before.
    */
-  // Used by resolveBashCommandCheck (bash-command.ts) and tests. Fallow's
-  // syntactic analysis cannot resolve the static-factory return type (private
-  // ctor), so it reports a false positive here.
-  // fallow-ignore-next-line unused-class-member
   commands(): BashCommand[] {
     return [...this.commandUnits];
   }

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

@@ -1,5 +1,7 @@
+import type { AccessPath } from "#src/access-intent/access-path";
 import { BashProgram } from "#src/access-intent/bash/program";
 import type { PathNormalizer } from "#src/path-normalizer";
+import { getPathBearingToolPath } from "#src/path-utils";
 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 +10,7 @@ import {
   ToolPreviewFormatter,
   type ToolPreviewFormatterOptions,
 } from "#src/tool-preview-formatter";
+import type { PermissionCheckResult } from "#src/types";
 import { getNonEmptyString, toRecord } from "#src/value-guards";
 import { resolveBashCommandCheck } from "./bash-command";
 import { describeBashExternalDirectoryGate } from "./bash-external-directory";
@@ -39,8 +42,6 @@ export interface ToolCallGateInputs {
   getToolPreviewLimits(): ToolPreviewFormatterOptions;
   /** The session's path normalizer (platform + cwd baked in). */
   getPathNormalizer(): PathNormalizer;
-  /** The host platform injected at the composition root. */
-  getPlatform(): NodeJS.Platform;
 }
 
 /**
@@ -81,7 +82,6 @@ export class ToolCallGatePipeline {
     );
 
     const infraDirs = this.inputs.getInfrastructureReadDirs();
-    const platform = this.inputs.getPlatform();
 
     const gateProducers: Array<() => GateResult | Promise<GateResult>> = [
       () =>
@@ -101,29 +101,17 @@ export class ToolCallGatePipeline {
       () => describeBashExternalDirectoryGate(tcc, bashProgram, this.resolver),
       () => describeBashPathGate(tcc, bashProgram, this.resolver),
       () => {
-        // Bash commands may chain several sub-commands (`a && b`, `a | b`, …);
-        // evaluate each unit from the shared parse on the bash surface and
-        // select the most restrictive, rather than matching the whole program
-        // string (#301). Other tools evaluate their single input directly.
-        const toolCheck =
-          tcc.toolName === "bash" && bashProgram
-            ? resolveBashCommandCheck(
-                command ?? "",
-                bashProgram.commands(),
-                tcc.agentName ?? undefined,
-                this.resolver,
-              )
-            : this.resolver.resolve({
-                kind: "tool",
-                surface: tcc.toolName,
-                input: tcc.input,
-                agentName: tcc.agentName ?? undefined,
-              });
+        const { toolCheck, accessPath } = this.resolvePerToolCheck(
+          tcc,
+          bashProgram,
+          command,
+          normalizer,
+        );
         const toolDescriptor = describeToolGate(
           tcc,
           toolCheck,
           formatter,
-          platform,
+          accessPath,
         );
         toolDescriptor.preCheck = toolCheck;
         return toolDescriptor;
@@ -143,4 +131,55 @@ export class ToolCallGatePipeline {
 
     return { action: "allow" };
   }
+
+  /**
+   * Resolve the per-tool gate's check, choosing the intent by tool shape:
+   * bash chains its sub-commands; a path-bearing tool with a path emits an
+   * `access-path` intent (so the per-tool surface matches lexical ∪ canonical,
+   * #502); every other tool (and a path-bearing tool with no path) keeps the
+   * raw `tool` intent the manager normalizes.
+   *
+   * Returns the `AccessPath` alongside the check so `describeToolGate` derives
+   * the session-approval value from `accessPath.value()`.
+   */
+  private resolvePerToolCheck(
+    tcc: ToolCallContext,
+    bashProgram: BashProgram | null,
+    command: string | null,
+    normalizer: PathNormalizer,
+  ): { toolCheck: PermissionCheckResult; accessPath?: AccessPath } {
+    if (tcc.toolName === "bash" && bashProgram) {
+      return {
+        toolCheck: resolveBashCommandCheck(
+          command ?? "",
+          bashProgram.commands(),
+          tcc.agentName ?? undefined,
+          this.resolver,
+        ),
+      };
+    }
+
+    const filePath = getPathBearingToolPath(tcc.toolName, tcc.input);
+    if (filePath !== null) {
+      const accessPath = normalizer.forPath(filePath);
+      return {
+        accessPath,
+        toolCheck: this.resolver.resolve({
+          kind: "access-path",
+          surface: tcc.toolName,
+          path: accessPath,
+          agentName: tcc.agentName ?? undefined,
+        }),
+      };
+    }
+
+    return {
+      toolCheck: this.resolver.resolve({
+        kind: "tool",
+        surface: tcc.toolName,
+        input: tcc.input,
+        agentName: tcc.agentName ?? undefined,
+      }),
+    };
+  }
 }

package/src/handlers/gates/tool.ts

@@ -1,8 +1,5 @@
-import {
-  getPathBearingToolPath,
-  normalizePathForComparison,
-  PATH_BEARING_TOOLS,
-} from "#src/path-utils";
+import type { AccessPath } from "#src/access-intent/access-path";
+import { getPathBearingToolPath, PATH_BEARING_TOOLS } from "#src/path-utils";
 import { suggestSessionPattern } from "#src/pattern-suggest";
 import { formatAskPrompt } from "#src/permission-prompts";
 import { SessionApproval } from "#src/session-approval";
@@ -16,20 +13,19 @@ import type { ToolCallContext } from "./types";
  * Derive the value used for session-approval pattern suggestions.
  *
  * Bash → command string; MCP → qualified target;
- * path-bearing tools → the file path resolved to its canonical (cwd-anchored,
- * absolute) form so the suggested pattern matches the policy values a later
- * call produces; others → catch-all wildcard.
+ * path-bearing tools → the `AccessPath`'s lexical absolute form (`value()`),
+ * so the suggested pattern matches the policy values a later call produces;
+ * others (or a path-bearing tool with no path) → catch-all wildcard.
  */
 function deriveSuggestionValue(
   tcc: ToolCallContext,
   check: PermissionCheckResult,
-  platform: NodeJS.Platform,
+  accessPath?: AccessPath,
 ): string {
   if (tcc.toolName === "bash") return check.command ?? "";
   if (tcc.toolName === "mcp") return check.target ?? "mcp";
-  const path = getPathBearingToolPath(tcc.toolName, tcc.input);
-  if (path === null) return "*";
-  return normalizePathForComparison(path, tcc.cwd, platform);
+  if (accessPath) return accessPath.value();
+  return "*";
 }
 
 /**
@@ -42,7 +38,7 @@ export function describeToolGate(
   tcc: ToolCallContext,
   check: PermissionCheckResult,
   formatter: ToolPreviewFormatter,
-  platform: NodeJS.Platform,
+  accessPath?: AccessPath,
 ): GateDescriptor {
   const permissionLogContext = formatter.getPermissionLogContext(
     check,
@@ -53,7 +49,7 @@ export function describeToolGate(
   // Compute session approval suggestion for the "for this session" option.
   const suggestion = suggestSessionPattern(
     tcc.toolName,
-    deriveSuggestionValue(tcc, check, platform),
+    deriveSuggestionValue(tcc, check, accessPath),
   );
 
   const askMessage = formatAskPrompt(

package/src/index.ts

@@ -134,17 +134,21 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
       ),
   });
 
+  // Resolver composes the manager + session ruleset and owns the
+  // access-path → path-values unwrap; the RPC and service route their policy
+  // queries through it, so it is constructed before both.
+  const resolver = new PermissionResolver(permissionManager, sessionRules);
+
   const rpcHandles = registerPermissionRpcHandlers(pi.events, {
-    permissionManager,
-    sessionRules,
+    resolver,
     session,
     requestPermissionDecisionFromUi,
     logger,
   });
 
   const permissionsService = new LocalPermissionsService(
-    permissionManager,
-    sessionRules,
+    resolver,
+    session,
     formatterRegistry,
     accessExtractorRegistry,
   );
@@ -174,8 +178,6 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     setActive: (names: string[]) => pi.setActiveTools(names),
   };
 
-  const resolver = new PermissionResolver(permissionManager, sessionRules);
-
   const audit = new DecisionAudit();
   const lifecycle = new SessionLifecycleHandler(
     session,

package/src/input-normalizer.ts

@@ -1,25 +1,60 @@
+import type { AccessIntent } from "./access-intent/access-intent";
 import { stripBashCommentLines } from "./bash-arity";
 import { createMcpPermissionTargets } from "./mcp-targets";
-import { getPathPolicyValues, PATH_BEARING_TOOLS } from "./path-utils";
+import type { PathNormalizer } from "./path-normalizer";
+import { PATH_SURFACES } from "./path-utils";
 import { getNonEmptyString, toRecord } from "./value-guards";
 
 /**
- * Construct a surface-appropriate input object from a raw value string.
+ * Build the {@link AccessIntent} an external policy query (the `Symbol.for()`
+ * service and the event-bus RPC) feeds to the resolver from a `(surface, value)`
+ * pair.
  *
- * This is the inverse of `normalizeInput()` — it builds the minimal input
- * object that `PermissionManager.checkPermission()` expects for a given
- * surface, from a single string value.
+ * For a path-shaped surface (`path`, `external_directory`, or a path-bearing
+ * tool) carrying a non-empty value, it builds an `AccessPath` and emits an
+ * `access-path` intent, so the resolver matches the lexical aliases ∪ canonical
+ * (symlink-resolved) set — at parity with the gates (#486, #502). Every other
+ * surface, and any value-less surface-level query, keeps the `tool` intent so
+ * the manager's `normalizeInput` `["*"]` fallback is preserved.
+ */
+export function buildAccessIntentForSurface(
+  surface: string,
+  value: string | undefined,
+  normalizer: PathNormalizer,
+  agentName: string | undefined,
+): AccessIntent {
+  const pathValue = getNonEmptyString(value);
+  if (pathValue !== null && PATH_SURFACES.has(surface)) {
+    return {
+      kind: "access-path",
+      surface,
+      path: normalizer.forPath(pathValue),
+      agentName,
+    };
+  }
+  return {
+    kind: "tool",
+    surface,
+    input: buildInputForSurface(surface, value),
+    agentName,
+  };
+}
+
+/**
+ * Construct a surface-appropriate input object from a raw value string for the
+ * `tool`-intent branch of {@link buildAccessIntentForSurface} (the non-path
+ * surfaces and value-less path queries).
  *
- * Used by the event-bus RPC handler and the `Symbol.for()` service accessor
- * so external callers can query policy with `(surface, value)` instead of
- * constructing a full tool-call input payload.
+ * This is the inverse of `normalizeInput()` — it builds the minimal input
+ * object that the manager expects for a given surface, from a single string
+ * value.
  *
  * Note: MCP inputs are complex (server name + tool name derivation). Callers
  * providing an MCP surface receive a best-effort policy evaluation using the
  * value as a pre-qualified target string. Pass the fully-qualified target
  * (e.g. "exa:search" or "exa") directly.
  */
-export function buildInputForSurface(
+function buildInputForSurface(
   surface: string,
   value: string | undefined,
 ): unknown {
@@ -51,12 +86,16 @@ export interface NormalizedInput {
   resultExtras: Record<string, unknown>;
 }
 
-const SPECIAL_PERMISSION_KEYS = new Set(["external_directory", "path"]);
-
 /**
  * Map a raw tool invocation to the surface/values/extras triple needed by
  * `checkPermission()`.
  *
+ * Handles bash, skill, mcp, and extension surfaces. Path-bearing tool surfaces
+ * (`path`, `external_directory`, `read`, `write`, `edit`, `grep`, `find`,
+ * `ls`) now route through the access-path gate (#502) and service/RPC builder
+ * (#503) before reaching the manager, so they never arrive here with a real
+ * path value — all fall through to the extension catch-all `["*"]`.
+ *
  * @param toolName - Normalized (trimmed) tool name from the tool-call event.
  * @param input    - Raw input payload from the tool-call event.
  * @param configuredMcpServerNames - Ordered list of MCP server names from the
@@ -66,18 +105,7 @@ export function normalizeInput(
   toolName: string,
   input: unknown,
   configuredMcpServerNames: readonly string[],
-  platform: NodeJS.Platform,
-  cwd?: string,
 ): NormalizedInput {
-  // --- Special surfaces (path, external_directory) ---
-  if (SPECIAL_PERMISSION_KEYS.has(toolName)) {
-    return {
-      surface: toolName,
-      values: normalizePathSurfaceValues(input, platform, cwd),
-      resultExtras: {},
-    };
-  }
-
   // --- Skill ---
   if (toolName === "skill") {
     const record = toRecord(input);
@@ -120,43 +148,13 @@ export function normalizeInput(
     };
   }
 
-  // --- Path-bearing tools (read, write, edit, grep, find, ls) ---
-  if (PATH_BEARING_TOOLS.has(toolName)) {
-    return {
-      surface: toolName,
-      values: normalizePathSurfaceValues(input, platform, cwd),
-      resultExtras: {},
-    };
-  }
-
-  // --- Extension tools (non-path-bearing) ---
+  // --- All other surfaces (path-bearing tools and extension tools) ---
+  // Path-bearing tools with a present path never reach here — the gate emits
+  // an access-path intent (#502). Missing-path and extension-tool cases both
+  // collapse to the surface catch-all.
   return {
     surface: toolName,
     values: ["*"],
     resultExtras: {},
   };
 }
-
-/**
- * Extract and normalize the path lookup values shared by every path surface
- * (`path`, `external_directory`, and the path-bearing tools).
- *
- * Missing, empty, or whitespace-only paths collapse to the surface catch-all
- * `"*"`. When CWD is known, a relative path also produces a normalized
- * absolute policy value and a project-relative alias while keeping its legacy
- * relative value, so values match home- and cwd-anchored patterns
- * symmetrically with how the patterns themselves are expanded (#350).
- *
- * Only `input.path` is read — policy values are never sourced from any other
- * (potentially attacker-controlled) field on the raw tool input.
- */
-function normalizePathSurfaceValues(
-  input: unknown,
-  platform: NodeJS.Platform,
-  cwd?: string,
-): string[] {
-  const path = getNonEmptyString(toRecord(input).path);
-  if (path === null) return ["*"];
-  const values = getPathPolicyValues(path, cwd ? { cwd } : {}, platform);
-  return values.length > 0 ? values : ["*"];
-}

package/src/permission-event-rpc.ts

@@ -7,7 +7,8 @@
  * permission prompts without importing this package.
  */
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { buildInputForSurface } from "./input-normalizer";
+import { buildAccessIntentForSurface } from "./input-normalizer";
+import type { PathNormalizer } from "./path-normalizer";
 import type {
   PermissionPromptDecision,
   RequestPermissionOptions,
@@ -26,22 +27,26 @@ import {
   PERMISSIONS_RPC_CHECK_CHANNEL,
   PERMISSIONS_RPC_PROMPT_CHANNEL,
 } from "./permission-events";
-import type { ScopedPermissionManager } from "./permission-manager";
+import type { ScopedPermissionResolver } from "./permission-resolver";
 import { buildRpcUiPrompt } from "./permission-ui-prompt";
 import type { ReviewLogger } from "./session-logger";
-import type { SessionRules } from "./session-rules";
 
 /** Dependencies injected into the RPC handler registry. */
 export interface PermissionRpcDeps {
-  /** The shared PermissionManager instance. */
-  permissionManager: Pick<ScopedPermissionManager, "check">;
-  /** The shared SessionRules instance. */
-  sessionRules: Pick<SessionRules, "getRuleset">;
   /**
-   * Narrow session view: provides runtime context.
-   * Used by the prompt handler to check hasUI and access the UI dialog.
+   * The shared resolver: answers an access intent, composing the session
+   * ruleset and unwrapping `access-path` → `path-values` internally so the
+   * RPC check matches the same lexical ∪ canonical set the gates do (#503).
    */
-  session: { getRuntimeContext(): ExtensionContext | null };
+  resolver: Pick<ScopedPermissionResolver, "resolve">;
+  /**
+   * Narrow session view: runtime context for the prompt handler (hasUI / UI
+   * dialog) and the cwd-bound path normalizer for path-surface check queries.
+   */
+  session: {
+    getRuntimeContext(): ExtensionContext | null;
+    getPathNormalizer(): PathNormalizer;
+  };
   /** Show the interactive permission dialog in the parent session UI. */
   requestPermissionDecisionFromUi(
     ui: ExtensionContext["ui"],
@@ -107,12 +112,13 @@ function handleCheckRpc(
       return;
     }
 
-    const input = buildInputForSurface(surface, value);
-    const sessionRules = deps.sessionRules.getRuleset();
-    const result = deps.permissionManager.check(
-      { kind: "tool", surface, input, agentName: agentName ?? undefined },
-      sessionRules,
+    const intent = buildAccessIntentForSurface(
+      surface,
+      value,
+      deps.session.getPathNormalizer(),
+      agentName ?? undefined,
     );
+    const result = deps.resolver.resolve(intent);
 
     const data: PermissionsCheckReplyData = {
       result: result.state,

package/src/permission-manager.ts

@@ -96,7 +96,6 @@ export interface PermissionManagerOptions extends PolicyLoaderOptions {
 export class PermissionManager implements ScopedPermissionManager {
   private readonly agentDir: string | undefined;
   private readonly platform: NodeJS.Platform;
-  private currentCwd: string | undefined;
   private loader: PolicyLoader;
   private readonly resolvedPermissionsCache = new Map<
     string,
@@ -123,8 +122,6 @@ export class PermissionManager implements ScopedPermissionManager {
    * built with explicit paths), only the cache is cleared.
    */
   configureForCwd(cwd: string | undefined | null): void {
-    this.currentCwd =
-      typeof cwd === "string" && cwd.trim().length > 0 ? cwd : undefined;
     if (this.agentDir !== undefined) {
       this.loader = new FilePolicyLoader(
         derivePolicyLoaderOptions(this.agentDir, cwd),
@@ -248,7 +245,9 @@ export class PermissionManager implements ScopedPermissionManager {
   /**
    * Unified resolution entry point — dispatches on intent kind.
    *
-   * `"tool"` → normalizes raw input through `normalizeInput`.
+   * `"tool"` → normalizes raw input through `normalizeInput` (bash, skill, mcp,
+   * 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.
    */
   check(
@@ -280,8 +279,6 @@ export class PermissionManager implements ScopedPermissionManager {
       toolName,
       intent.input,
       this.loader.getConfiguredMcpServerNames(),
-      this.platform,
-      this.currentCwd,
     );
     return buildCheckResult(
       surface,

package/src/permission-session.ts

@@ -85,11 +85,6 @@ export class PermissionSession implements ToolCallGateInputs {
     return this.context;
   }
 
-  /** The host platform injected at the composition root. */
-  getPlatform(): NodeJS.Platform {
-    return this.platform;
-  }
-
   // ── UI notifications ────────────────────────────────────────────────────
 
   /** Surface a warning message to the user via the active UI context, if any. */

package/src/permissions-service.ts

@@ -1,7 +1,7 @@
-import { buildInputForSurface } from "./input-normalizer";
-import type { ScopedPermissionManager } from "./permission-manager";
+import type { AccessIntent } from "./access-intent/access-intent";
+import { buildAccessIntentForSurface } from "./input-normalizer";
+import type { PathNormalizer } from "./path-normalizer";
 import type { PermissionsService } from "./service";
-import type { SessionRules } from "./session-rules";
 import type {
   ToolAccessExtractor,
   ToolAccessExtractorRegistrar,
@@ -10,18 +10,37 @@ import type {
   ToolInputFormatter,
   ToolInputFormatterRegistrar,
 } from "./tool-input-formatter-registry";
+import type { PermissionCheckResult, PermissionState } from "./types";
+
+/**
+ * Resolution surface the service needs: answer a gate-style {@link AccessIntent}
+ * (composing the session ruleset internally) and report a tool-level state.
+ * `PermissionResolver` satisfies it.
+ */
+interface ResolverForService {
+  resolve(intent: AccessIntent): PermissionCheckResult;
+  getToolPermission(toolName: string, agentName?: string): PermissionState;
+}
+
+/** Narrow session view: hands out the cwd-bound path normalizer. */
+interface PathNormalizerProvider {
+  getPathNormalizer(): PathNormalizer;
+}
 
 /**
  * In-process implementation of the cross-extension {@link PermissionsService}.
  *
  * Constructed once in the composition root and backed by the single shared
- * `PermissionManager` and `SessionRules` instances that `PermissionSession`
- * also uses — so service queries and gate-path approvals see the same state.
+ * `PermissionResolver` and `PermissionSession` that the gates also use — so
+ * service queries and gate-path decisions see the same state. Path-shaped
+ * surface queries route through the resolver as an `access-path` intent, so
+ * they match the lexical aliases ∪ canonical (symlink-resolved) set the gates
+ * do (#503); non-path surfaces stay on the `tool` intent.
  */
 export class LocalPermissionsService implements PermissionsService {
   constructor(
-    private readonly permissionManager: ScopedPermissionManager,
-    private readonly sessionRules: Pick<SessionRules, "getRuleset">,
+    private readonly resolver: ResolverForService,
+    private readonly session: PathNormalizerProvider,
     private readonly formatterRegistry: ToolInputFormatterRegistrar,
     private readonly accessExtractorRegistry: ToolAccessExtractorRegistrar,
   ) {}
@@ -31,18 +50,20 @@ export class LocalPermissionsService implements PermissionsService {
     value?: string,
     agentName?: string,
   ): ReturnType<PermissionsService["checkPermission"]> {
-    const input = buildInputForSurface(surface, value);
-    return this.permissionManager.check(
-      { kind: "tool", surface, input, agentName },
-      this.sessionRules.getRuleset(),
+    const intent = buildAccessIntentForSurface(
+      surface,
+      value,
+      this.session.getPathNormalizer(),
+      agentName,
     );
+    return this.resolver.resolve(intent);
   }
 
   getToolPermission(
     toolName: string,
     agentName?: string,
   ): ReturnType<PermissionsService["getToolPermission"]> {
-    return this.permissionManager.getToolPermission(toolName, agentName);
+    return this.resolver.getToolPermission(toolName, agentName);
   }
 
   registerToolInputFormatter(

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

@@ -375,7 +375,7 @@ describe("BashProgram", () => {
       const symlinkCwd = "/private/tmp";
       realpathSync.mockImplementation((p: string) => {
         if (p === "/tmp") return "/private/tmp";
-        if (p.startsWith("/tmp/")) return "/private/tmp" + p.slice(4);
+        if (p.startsWith("/tmp/")) return `/private/tmp${p.slice(4)}`;
         return p;
       });
       const program = await BashProgram.parse(