@gotgenes/pi-permission-system 17.1.0 → 18.0.0

package/CHANGELOG.md

@@ -5,6 +5,39 @@ 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)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** gate Windows drive-letter paths in bash external_directory ([#508](https://github.com/gotgenes/pi-packages/issues/508)) ([2d33183](https://github.com/gotgenes/pi-packages/commit/2d331834254f58bcb0782b3da353132821536296))
+
 ## [17.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v17.0.0...pi-permission-system-v17.1.0) (2026-06-28)
 
 

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.0",
+  "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/bash-path-resolver.ts

@@ -347,7 +347,7 @@ export class BashPathResolver {
       // anywhere, so flag it conservatively (resolved against the baked cwd
       // only for a display path). Absolute / `~` candidates are base-independent
       // below.
-      if (base.kind === "unknown" && isRelativeCandidate(candidate)) {
+      if (base.kind === "unknown" && this.isRelativeCandidate(candidate)) {
         const accessPath = this.normalizer.forPath(candidate);
         const canonical = accessPath.boundaryValue();
         if (canonical && !isSafeSystemPath(canonical) && !seen.has(canonical)) {
@@ -421,7 +421,7 @@ export class BashPathResolver {
     // 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)) {
+    if (base.kind === "unknown" && this.isRelativeCandidate(candidate)) {
       return this.normalizer.forLiteral(normalizePathPolicyLiteral(candidate));
     }
 
@@ -431,6 +431,20 @@ export class BashPathResolver {
         : undefined;
     return this.normalizer.forPath(candidate, { resolveBase });
   }
+
+  /**
+   * True when a path candidate is relative (resolved against the effective
+   * directory) rather than absolute or home-relative (`~…`), which are
+   * base-independent.
+   *
+   * Delegates the absoluteness decision to the platform-aware `PathNormalizer`
+   * rather than a POSIX-only `startsWith("/")` check, so Windows drive-letter
+   * paths (`C:/…`, `C:\…`) are correctly treated as absolute on win32 and as
+   * relative on POSIX (where they denote an in-CWD path).
+   */
+  private isRelativeCandidate(candidate: string): boolean {
+    return !this.normalizer.isAbsolute(candidate) && !candidate.startsWith("~");
+  }
 }
 
 // ── Pure AST/string helpers ──────────────────────────────────────────────────
@@ -519,13 +533,3 @@ function literalTextOf(node: TSNode): string | null {
       return null;
   }
 }
-
-/**
- * True when a path candidate is relative (resolved against the effective
- * directory) rather than absolute (`/…`) or home-relative (`~…`), which are
- * base-independent.
- * Used to decide which candidates an unknown base affects.
- */
-function isRelativeCandidate(candidate: string): boolean {
-  return !candidate.startsWith("/") && !candidate.startsWith("~");
-}

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/access-intent/bash/token-classification.ts

@@ -8,6 +8,12 @@
  * Both classifiers share the private `rejectNonPathToken` predicate that captures
  * the seven rejection cases common to both (the production clone this module was
  * extracted to eliminate).
+ *
+ * Both classifiers recognize Windows drive-letter absolute paths (`C:/…`, `C:\…`)
+ * unconditionally on all platforms. On POSIX the token resolves as a real in-CWD
+ * relative path and is gated by the `path` surface; on Windows the `PathNormalizer`
+ * routes it through the absolute-path branch. Shape recognition is platform-independent
+ * string matching; the platform-sensitive absoluteness decision belongs to `PathNormalizer`.
  */
 
 // ── Public classifiers ─────────────────────────────────────────────────────
@@ -19,6 +25,7 @@
  * - Absolute paths (starting with `/`)
  * - Home-relative paths (starting with `~/`)
  * - Parent-traversal paths (containing `..`)
+ * - Windows drive-letter absolute paths (`C:/…` or `C:\…`)
  *
  * Returns the raw token string if it qualifies, or `null` to skip.
  */
@@ -28,6 +35,7 @@ export function classifyTokenAsPathCandidate(token: string): string | null {
   if (token.startsWith("/")) return token;
   if (token.startsWith("~/")) return token;
   if (token.includes("..")) return token;
+  if (WINDOWS_DRIVE_PATH_PATTERN.test(token)) return token;
 
   return null;
 }
@@ -38,8 +46,13 @@ export function classifyTokenAsPathCandidate(token: string): string | null {
  * Accepts the same shapes as `classifyTokenAsPathCandidate`, plus:
  * - Dot-files and `./`-relative paths (starting with `.`)
  * - Any relative path containing `/` (e.g. `src/foo.ts`)
+ * - Windows drive-letter absolute paths (`C:/…` or `C:\…`)
  *
  * The `~/foo` case is covered by `includes("/")` — no separate `~/` branch needed.
+ * The forward-slash drive form (`C:/…`) is also caught by `includes("/")`, but the
+ * explicit `WINDOWS_DRIVE_PATH_PATTERN` branch makes both separator forms first-class
+ * and order-independent, and covers the backslash-only form (`D:\…`) which `includes("/")`
+ * cannot reach.
  *
  * Does NOT require the strict "must start with `/` or `~/` or contain `..`"
  * gate that the external-directory classifier uses.
@@ -52,12 +65,22 @@ export function classifyTokenAsRuleCandidate(token: string): string | null {
   if (token.startsWith(".")) return token;
   if (token.includes("/")) return token; // covers ~/ paths and all relative paths with /
   if (token.includes("..")) return token; // bare ".." (no slash)
+  if (WINDOWS_DRIVE_PATH_PATTERN.test(token)) return token; // backslash-only drive form
 
   return null;
 }
 
 // ── Private rejection predicate ────────────────────────────────────────────
 
+/**
+ * Windows drive-letter absolute path: a single ASCII letter, a colon, then a
+ * separator (`/` or `\`). Matches `C:/…` and `C:\…` but not drive-relative
+ * `C:foo` (no separator) or multi-letter schemes (`https:`, `mailto:`).
+ * Single-letter schemes with `//` (e.g. `c://x`) are already rejected by
+ * `URL_PATTERN` before this pattern is tested.
+ */
+const WINDOWS_DRIVE_PATH_PATTERN = /^[a-zA-Z]:[/\\]/;
+
 /**
  * URL pattern to skip tokens that look like URLs rather than paths.
  */

package/src/handlers/before-agent-start.ts

@@ -84,8 +84,7 @@ export class AgentPrepHandler {
       toolPromptResult.prompt,
       this.resolver,
       agentName,
-      ctx.cwd,
-      this.session.getPlatform(),
+      this.session.getPathNormalizer(),
     );
     this.session.setActiveSkillEntries(skillPromptResult.entries);
     return skillPromptResult.prompt !== event.systemPrompt

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

@@ -1,5 +1,5 @@
 import type { PathNormalizer } from "#src/path-normalizer";
-import { getToolInputPath, isPiInfrastructureRead } from "#src/path-utils";
+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,7 +22,6 @@ export function describeExternalDirectoryGate(
   infraDirs: string[],
   resolver: ScopedPermissionResolver,
   normalizer: PathNormalizer,
-  platform: NodeJS.Platform,
   extractors?: ToolAccessExtractorLookup,
 ): GateResult {
   const externalDirectoryPath = getToolInputPath(
@@ -40,18 +39,9 @@ export function describeExternalDirectoryGate(
   // check (below) use the canonical, symlink-resolved path; pattern matching
   // uses the typed and resolved aliases (#418).
   const accessPath = normalizer.forPath(externalDirectoryPath);
-  const canonicalExtPath = accessPath.boundaryValue();
 
   // ── Pi infrastructure read bypass ──────────────────────────────────────
-  if (
-    isPiInfrastructureRead(
-      tcc.toolName,
-      canonicalExtPath,
-      infraDirs,
-      tcc.cwd,
-      platform,
-    )
-  ) {
+  if (normalizer.isInfrastructureRead(tcc.toolName, accessPath, infraDirs)) {
     return {
       action: "allow",
       log: {

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

@@ -1,4 +1,4 @@
-import { normalizePathForComparison } from "#src/path-utils";
+import type { PathNormalizer } from "#src/path-normalizer";
 import { formatSkillPathAskPrompt } from "#src/permission-prompts";
 import type { SkillPromptEntry } from "#src/skill-prompt-sanitizer";
 import { findSkillPathMatch } from "#src/skill-prompt-sanitizer";
@@ -15,7 +15,7 @@ import type { ToolCallContext } from "./types";
  */
 export function describeSkillReadGate(
   tcc: ToolCallContext,
-  platform: NodeJS.Platform,
+  normalizer: PathNormalizer,
   getActiveSkillEntries: () => SkillPromptEntry[],
 ): GateDescriptor | null {
   const activeSkillEntries = getActiveSkillEntries();
@@ -30,15 +30,11 @@ export function describeSkillReadGate(
     return null;
   }
 
-  const normalizedReadPath = normalizePathForComparison(
-    path,
-    tcc.cwd,
-    platform,
-  );
+  const normalizedReadPath = normalizer.comparableValue(path);
   const matchedSkill = findSkillPathMatch(
     normalizedReadPath,
     activeSkillEntries,
-    platform,
+    normalizer,
   );
 
   if (!matchedSkill) {

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,11 +82,10 @@ export class ToolCallGatePipeline {
     );
 
     const infraDirs = this.inputs.getInfrastructureReadDirs();
-    const platform = this.inputs.getPlatform();
 
     const gateProducers: Array<() => GateResult | Promise<GateResult>> = [
       () =>
-        describeSkillReadGate(tcc, platform, () =>
+        describeSkillReadGate(tcc, normalizer, () =>
           this.inputs.getActiveSkillEntries(),
         ),
       () =>
@@ -96,35 +96,22 @@ export class ToolCallGatePipeline {
           infraDirs,
           this.resolver,
           normalizer,
-          platform,
           this.customExtractors,
         ),
       () => 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;
@@ -144,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,