@gotgenes/pi-permission-system 13.1.2 → 14.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).
 
+## [14.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v13.2.0...pi-permission-system-v14.0.0) (2026-06-17)
+
+
+### ⚠ BREAKING CHANGES
+
+* project agents' `permission:` frontmatter at `<cwd>/.pi/agents/<name>.md` is now read and enforced. Previously the wrong directory (`<cwd>/.pi/agent/agents`) was checked and the frontmatter was silently ignored, so a session may become more restrictive on upgrade.
+
+### Bug Fixes
+
+* correct project agents directory path to &lt;cwd&gt;/.pi/agents ([#428](https://github.com/gotgenes/pi-packages/issues/428)) ([eb5af78](https://github.com/gotgenes/pi-packages/commit/eb5af78193fa3cc574da6b8d80efd643ebce0ef9))
+
+
+### Documentation
+
+* correct project agent override path to &lt;cwd&gt;/.pi/agents ([#428](https://github.com/gotgenes/pi-packages/issues/428)) ([d193d6a](https://github.com/gotgenes/pi-packages/commit/d193d6a61155fb4e4a064800509cdbbd84b0ceb9))
+* fix stale project agents path in troubleshooting and ADR-0001 ([#428](https://github.com/gotgenes/pi-packages/issues/428)) ([95effeb](https://github.com/gotgenes/pi-packages/commit/95effebfd0b2e87db4512c91adc134b2470f26a3))
+
+## [13.2.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v13.1.2...pi-permission-system-v13.2.0) (2026-06-17)
+
+
+### Features
+
+* **pi-permission-system:** add external-directory typed+resolved policy aliases ([#418](https://github.com/gotgenes/pi-packages/issues/418)) ([ae653d1](https://github.com/gotgenes/pi-packages/commit/ae653d11fa52403cc5a78cd0148bc102de923d3c))
+
+
+### Bug Fixes
+
+* **pi-permission-system:** match external_directory patterns against typed and resolved paths ([#418](https://github.com/gotgenes/pi-packages/issues/418)) ([d08e645](https://github.com/gotgenes/pi-packages/commit/d08e64509d980c818708ecd2b7152ba6fc05946d))
+
+
+### Documentation
+
+* **pi-permission-system:** document external_directory symlink alias matching ([#418](https://github.com/gotgenes/pi-packages/issues/418)) ([8760273](https://github.com/gotgenes/pi-packages/commit/876027313457591ab5f175c689aa3074143db388))
+
 ## [13.1.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v13.1.1...pi-permission-system-v13.1.2) (2026-06-16)
 
 

package/package.json

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

package/src/config-paths.ts

@@ -21,6 +21,19 @@ export function getProjectConfigPath(cwd: string): string {
   return join(cwd, ".pi", "extensions", EXTENSION_ID, "config.json");
 }
 
+/**
+ * Directory holding project-scoped custom agent definition files.
+ *
+ * `<cwd>/.pi/agents` is a Pi platform convention, also encoded by
+ * `@gotgenes/pi-subagents`' `loadCustomAgents` (`config/custom-agents.ts`).
+ * The two packages encode it independently — pi-permission-system has no
+ * dependency on pi-subagents (ADR-0002) — so this is this package's
+ * authoritative copy.
+ */
+export function getProjectAgentsDir(cwd: string): string {
+  return join(cwd, ".pi", "agents");
+}
+
 export function getLegacyGlobalPolicyPath(agentDir: string): string {
   return join(agentDir, "pi-permissions.jsonc");
 }

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

@@ -1,4 +1,5 @@
 import { getNonEmptyString, toRecord } from "#src/common";
+import { getExternalDirectoryPolicyValues } from "#src/path-utils";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
@@ -41,10 +42,13 @@ export function describeBashExternalDirectoryGate(
     check: PermissionCheckResult;
   }> = [];
   for (const p of externalPaths) {
-    const check = resolver.resolve(
-      "external_directory",
-      { path: p },
+    // Match each path against both its typed and symlink-resolved aliases on
+    // the external_directory surface, so a config pattern on either form
+    // applies (#418).
+    const check = resolver.resolvePathPolicy(
+      getExternalDirectoryPolicyValues(p, tcc.cwd),
       tcc.agentName ?? undefined,
+      "external_directory",
     );
     if (check.state !== "allow") {
       uncoveredEntries.push({ path: p, check });

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

@@ -199,13 +199,19 @@ export class BashProgram {
   }
 
   /**
-   * Deduplicated paths that resolve outside `cwd`.
+   * Deduplicated paths that resolve outside `cwd`, in their lexical (as-typed,
+   * normalized but not symlink-resolved) form.
    *
    * Each candidate is resolved against the effective working directory in force
    * where it appears, projected by folding a sequence of current-shell `cd`
    * commands (joined by `&&`, `||`, `;`, or a newline). A `cd` inside a
    * pipeline or a backgrounded command runs in a subshell and does not update
    * the running directory.
+   *
+   * The outside-`cwd` decision and the dedup identity use the canonical
+   * (symlink-resolved) form, but the returned value is the lexical form so
+   * `external_directory` config patterns match the path as the user typed it
+   * (#418); the gate re-derives the canonical alias for matching.
    */
   externalPaths(cwd: string): string[] {
     const normalizedCwd = canonicalizePath(
@@ -224,36 +230,37 @@ export class BashProgram {
       // display path). Absolute / `~` candidates are base-independent and
       // resolve normally below.
       if (base.kind === "unknown" && isRelativeCandidate(candidate)) {
-        const normalized = canonicalizePath(
-          normalizePathForComparison(candidate, cwd),
-        );
+        const lexical = normalizePathForComparison(candidate, cwd);
+        const canonical = canonicalizePath(lexical);
         if (
-          normalized &&
+          canonical &&
           normalizedCwd !== "" &&
-          !isSafeSystemPath(normalized) &&
-          !seen.has(normalized)
+          !isSafeSystemPath(canonical) &&
+          !seen.has(canonical)
         ) {
-          seen.add(normalized);
-          externalPaths.push(normalized);
+          seen.add(canonical);
+          externalPaths.push(lexical);
         }
         continue;
       }
 
       const resolveBase =
         base.kind === "known" ? resolve(cwd, base.offset) : cwd;
-      const normalized = canonicalizePath(
-        normalizePathForComparison(candidate, resolveBase),
-      );
-      if (!normalized) continue;
+      const lexical = normalizePathForComparison(candidate, resolveBase);
+      if (!lexical) continue;
+      // The boundary decision and dedup identity use the canonical
+      // (symlink-resolved) form, but the returned value is the lexical form so
+      // config patterns match the path as the user typed it (#418).
+      const canonical = canonicalizePath(lexical);
 
       if (
         normalizedCwd !== "" &&
-        !isSafeSystemPath(normalized) &&
-        !isPathWithinDirectory(normalized, normalizedCwd) &&
-        !seen.has(normalized)
+        !isSafeSystemPath(canonical) &&
+        !isPathWithinDirectory(canonical, normalizedCwd) &&
+        !seen.has(canonical)
       ) {
-        seen.add(normalized);
-        externalPaths.push(normalized);
+        seen.add(canonical);
+        externalPaths.push(lexical);
       }
     }
 

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

@@ -1,9 +1,12 @@
 import {
   canonicalNormalizePathForComparison,
+  getExternalDirectoryPolicyValues,
   getToolInputPath,
   isPathOutsideWorkingDirectory,
   isPiInfrastructureRead,
+  normalizePathForComparison,
 } from "#src/path-utils";
+import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
 import type { ToolAccessExtractorLookup } from "#src/tool-access-extractor-registry";
@@ -22,6 +25,7 @@ import type { ToolCallContext } from "./types";
 export function describeExternalDirectoryGate(
   tcc: ToolCallContext,
   infraDirs: string[],
+  resolver: ScopedPermissionResolver,
   extractors?: ToolAccessExtractorLookup,
 ): GateResult {
   if (!tcc.cwd) return null;
@@ -37,14 +41,17 @@ export function describeExternalDirectoryGate(
     return null;
   }
 
-  const normalizedExtPath = canonicalNormalizePathForComparison(
+  // 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 canonicalExtPath = canonicalNormalizePathForComparison(
     externalDirectoryPath,
     tcc.cwd,
   );
 
   // ── Pi infrastructure read bypass ──────────────────────────────────────
   if (
-    isPiInfrastructureRead(tcc.toolName, normalizedExtPath, infraDirs, tcc.cwd)
+    isPiInfrastructureRead(tcc.toolName, canonicalExtPath, infraDirs, tcc.cwd)
   ) {
     return {
       action: "allow",
@@ -78,11 +85,22 @@ export function describeExternalDirectoryGate(
     tcc.agentName ?? undefined,
   );
 
-  const pattern = deriveApprovalPattern(normalizedExtPath);
+  // Match against both the typed and symlink-resolved aliases on the
+  // external_directory surface, so a config pattern on either form applies
+  // (#418). The runner consumes this preCheck and skips its own resolve.
+  const preCheck = resolver.resolvePathPolicy(
+    getExternalDirectoryPolicyValues(externalDirectoryPath, tcc.cwd),
+    tcc.agentName ?? undefined,
+    "external_directory",
+  );
+  const pattern = deriveApprovalPattern(
+    normalizePathForComparison(externalDirectoryPath, tcc.cwd),
+  );
 
   return {
     surface: "external_directory",
-    input: { path: normalizedExtPath },
+    input: {},
+    preCheck,
     denialContext: {
       kind: "external_directory",
       toolName: tcc.toolName,

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

@@ -81,7 +81,12 @@ export class ToolCallGatePipeline {
         describeSkillReadGate(tcc, () => this.inputs.getActiveSkillEntries()),
       () => describePathGate(tcc, this.resolver, this.customExtractors),
       () =>
-        describeExternalDirectoryGate(tcc, infraDirs, this.customExtractors),
+        describeExternalDirectoryGate(
+          tcc,
+          infraDirs,
+          this.resolver,
+          this.customExtractors,
+        ),
       () => describeBashExternalDirectoryGate(tcc, bashProgram, this.resolver),
       () => describeBashPathGate(tcc, bashProgram, this.resolver),
       () => {

package/src/path-utils.ts

@@ -112,6 +112,26 @@ export function getPathPolicyValues(
   ];
 }
 
+/**
+ * Equivalent `external_directory` policy-match values for a path: the lexical
+ * (as-typed) alias list plus the canonical (symlink-resolved) absolute path.
+ *
+ * The outside-CWD boundary decision uses the canonical form separately; this
+ * helper exists only for pattern matching, so a user's pattern on the typed
+ * path (`/tmp/*`) and on the resolved path (`/private/tmp/*`) both match under
+ * the last-match-wins alias evaluation. On systems where the path is not a
+ * symlink the canonical form equals the lexical absolute alias and the `Set`
+ * collapses it, leaving today's behavior unchanged.
+ */
+export function getExternalDirectoryPolicyValues(
+  pathValue: string,
+  cwd: string,
+): string[] {
+  const lexical = getPathPolicyValues(pathValue, { cwd });
+  const canonical = canonicalNormalizePathForComparison(pathValue, cwd);
+  return canonical ? [...new Set([...lexical, canonical])] : lexical;
+}
+
 function getAbsolutePathPolicyValues(
   pathValue: string,
   options: PathPolicyValueOptions,

package/src/permission-manager.ts

@@ -1,6 +1,10 @@
 import { join } from "node:path";
 import { isPermissionState } from "./common";
-import { getGlobalConfigPath, getProjectConfigPath } from "./config-paths";
+import {
+  getGlobalConfigPath,
+  getProjectAgentsDir,
+  getProjectConfigPath,
+} from "./config-paths";
 import { normalizeInput } from "./input-normalizer";
 import { normalizeFlatConfig } from "./normalize";
 import { PATH_SURFACES } from "./path-utils";
@@ -65,15 +69,18 @@ export interface ScopedPermissionManager {
     sessionRules?: Ruleset,
   ): PermissionCheckResult;
   /**
-   * Evaluate the cross-cutting `path` surface against a caller-supplied set of
-   * equivalent policy values (e.g. bash tokens already resolved against a
-   * preceding literal `cd`). The values are trusted because they are computed
-   * internally, never read from a field on raw tool input.
+   * Evaluate a path-shaped surface (`path` or `external_directory`) against a
+   * caller-supplied set of equivalent policy values (e.g. bash tokens already
+   * resolved against a preceding literal `cd`, or a path's typed and
+   * symlink-resolved aliases). The values are trusted because they are computed
+   * internally, never read from a field on raw tool input. `surface` defaults
+   * to `path`.
    */
   checkPathPolicy(
     values: readonly string[],
     agentName?: string,
     sessionRules?: Ruleset,
+    surface?: string,
   ): PermissionCheckResult;
   getToolPermission(toolName: string, agentName?: string): PermissionState;
   getConfigIssues(agentName?: string): string[];
@@ -277,6 +284,7 @@ export class PermissionManager implements ScopedPermissionManager {
     values: readonly string[],
     agentName?: string,
     sessionRules?: Ruleset,
+    surface = "path",
   ): PermissionCheckResult {
     const { composedRules } = this.resolvePermissions(agentName);
     const fullRules: Ruleset = sessionRules?.length
@@ -285,11 +293,11 @@ export class PermissionManager implements ScopedPermissionManager {
 
     const lookupValues = values.length > 0 ? [...values] : ["*"];
     return buildCheckResult(
-      "path",
+      surface,
       lookupValues,
       {},
-      "path",
-      "path",
+      surface,
+      surface,
       fullRules,
     );
   }
@@ -346,7 +354,7 @@ function derivePolicyLoaderOptions(
     globalConfigPath: getGlobalConfigPath(agentDir),
     agentsDir: join(agentDir, "agents"),
     projectGlobalConfigPath: cwd ? getProjectConfigPath(cwd) : undefined,
-    projectAgentsDir: cwd ? join(cwd, ".pi", "agent", "agents") : undefined,
+    projectAgentsDir: cwd ? getProjectAgentsDir(cwd) : undefined,
   };
 }
 

package/src/permission-resolver.ts

@@ -18,13 +18,16 @@ export interface ScopedPermissionResolver {
     agentName?: string,
   ): PermissionCheckResult;
   /**
-   * Resolve the cross-cutting `path` surface against a caller-supplied set of
-   * equivalent policy values, applying the current session rules. Used by the
-   * bash path gate, which computes cd-aware policy values per token.
+   * Resolve a path-shaped surface against a caller-supplied set of equivalent
+   * policy values, applying the current session rules. Used by the bash path
+   * gate (`path`) and the external-directory gates (`external_directory`),
+   * which compute equivalent path aliases per token. `surface` defaults to
+   * `path`.
    */
   resolvePathPolicy(
     values: readonly string[],
     agentName?: string,
+    surface?: string,
   ): PermissionCheckResult;
 }
 
@@ -63,17 +66,22 @@ export class PermissionResolver implements ScopedPermissionResolver {
   }
 
   /**
-   * Resolve the `path` surface for precomputed policy values, composing the
-   * current session ruleset so callers never thread it by hand.
+   * Resolve a path-shaped surface (`path` or `external_directory`) for
+   * precomputed policy values, composing the current session ruleset so callers
+   * never thread it by hand. `surface` defaults to `path`; the external-directory
+   * gates pass `external_directory` so a path's typed and symlink-resolved
+   * aliases match against the `external_directory` rules.
    */
   resolvePathPolicy(
     values: readonly string[],
     agentName?: string,
+    surface = "path",
   ): PermissionCheckResult {
     return this.permissionManager.checkPathPolicy(
       values,
       agentName,
       this.sessionRules.getRuleset(),
+      surface,
     );
   }
 

package/test/config-paths.test.ts

@@ -9,6 +9,7 @@ import {
   getLegacyExtensionConfigPath,
   getLegacyGlobalPolicyPath,
   getLegacyProjectPolicyPath,
+  getProjectAgentsDir,
   getProjectConfigPath,
   REVIEW_LOG_FILENAME,
 } from "#src/config-paths";
@@ -42,6 +43,10 @@ describe("config-paths", () => {
         join(cwd, ".pi", "extensions", "pi-permission-system", "config.json"),
       );
     });
+
+    it("getProjectAgentsDir returns .pi/agents under cwd", () => {
+      expect(getProjectAgentsDir(cwd)).toBe(join(cwd, ".pi", "agents"));
+    });
   });
 
   describe("legacy paths", () => {

package/test/handlers/external-directory-session-dedup.test.ts

@@ -98,6 +98,19 @@ function makeDeduplicatingHandler(prompter?: GatePrompter): {
     },
   );
 
+  // The external-directory gates resolve through checkPathPolicy (#418); route
+  // it through the same configured checkPermission so session-approval dedup
+  // applies to the typed path alias.
+  vi.mocked(permissionManager.checkPathPolicy).mockImplementation(
+    (values, agentName, rules, surface = "path") =>
+      permissionManager.checkPermission(
+        surface,
+        { path: values[0] ?? "*" },
+        agentName,
+        rules,
+      ),
+  );
+
   const events = makeEvents();
   const reporter = new GateDecisionReporter(logger, events);
   const resolvedPrompter: GatePrompter = prompter ?? {
@@ -351,6 +364,18 @@ describe("session shutdown clears external-directory approvals", () => {
       },
     );
 
+    // The external-directory tool gate resolves through checkPathPolicy (#418);
+    // route it through the same configured checkPermission.
+    vi.mocked(permissionManager.checkPathPolicy).mockImplementation(
+      (values, agentName, rules, surface = "path") =>
+        permissionManager.checkPermission(
+          surface,
+          { path: values[0] ?? "*" },
+          agentName,
+          rules,
+        ),
+    );
+
     const events = makeEvents();
     const reporter = new GateDecisionReporter(logger, events);
     const prompter: GatePrompter = {

package/test/handlers/external-directory-symlink-acceptance.test.ts

@@ -0,0 +1,149 @@
+/**
+ * Acceptance test for issue #418.
+ *
+ * Reproduces the reported bug with a real symlink (no `realpathSync` mock):
+ * an `external_directory` allow configured for the path as the user types it
+ * (`<link>/*`) must allow access even though the OS resolves `<link>` to a
+ * different canonical directory. Exercised end-to-end through the real
+ * `PermissionManager` + `PermissionResolver` for both a path-bearing tool and
+ * a bash command, and for an allow keyed on the symlink-resolved form too.
+ */
+
+import { mkdtempSync, realpathSync, rmSync, symlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { describeBashExternalDirectoryGate } from "#src/handlers/gates/bash-external-directory";
+import { BashProgram } from "#src/handlers/gates/bash-program";
+import {
+  type GateDescriptor,
+  isGateBypass,
+  isGateDescriptor,
+} from "#src/handlers/gates/descriptor";
+import { describeExternalDirectoryGate } from "#src/handlers/gates/external-directory";
+import type { ToolCallContext } from "#src/handlers/gates/types";
+import { PermissionResolver } from "#src/permission-resolver";
+import { SessionRules } from "#src/session-rules";
+import type { ScopeConfig } from "#src/types";
+
+import { createManager } from "#test/helpers/manager-harness";
+
+// ── real symlink fixture ─────────────────────────────────────────────────────
+
+let realDir: string;
+let linkDir: string;
+let cwd: string;
+const tempRoots: string[] = [];
+
+function mkTemp(prefix: string): string {
+  const dir = mkdtempSync(join(tmpdir(), prefix));
+  tempRoots.push(dir);
+  return dir;
+}
+
+beforeEach(() => {
+  realDir = mkTemp("ext-real-");
+  const linkParent = mkTemp("ext-link-");
+  linkDir = join(linkParent, "link");
+  symlinkSync(realDir, linkDir);
+  cwd = mkTemp("ext-cwd-");
+});
+
+afterEach(() => {
+  while (tempRoots.length > 0) {
+    const dir = tempRoots.pop();
+    if (dir) rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+function makeResolver(config: ScopeConfig) {
+  const { manager, cleanup } = createManager(config);
+  manager.configureForCwd(cwd);
+  const resolver = new PermissionResolver(manager, new SessionRules());
+  return { resolver, cleanup };
+}
+
+function readTcc(): ToolCallContext {
+  return {
+    toolName: "read",
+    agentName: null,
+    input: { path: join(linkDir, "file.ts") },
+    toolCallId: "tc-1",
+    cwd,
+  };
+}
+
+// ── tests ────────────────────────────────────────────────────────────────────
+
+describe("external_directory symlink acceptance (#418)", () => {
+  it("allows a path-bearing tool when the allow is keyed on the typed (symlinked) path", () => {
+    const { resolver, cleanup } = makeResolver({
+      permission: {
+        external_directory: { "*": "ask", [`${linkDir}/*`]: "allow" },
+      },
+    });
+    try {
+      const result = describeExternalDirectoryGate(readTcc(), [], resolver);
+      expect(isGateDescriptor(result)).toBe(true);
+      expect((result as GateDescriptor).preCheck?.state).toBe("allow");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("allows a path-bearing tool when the allow is keyed on the resolved path", () => {
+    // Key the allow on the fully symlink-resolved directory (on macOS the
+    // tmpdir root itself is a symlink, e.g. /var -> /private/var).
+    const resolved = realpathSync(realDir);
+    const { resolver, cleanup } = makeResolver({
+      permission: {
+        external_directory: { "*": "ask", [`${resolved}/*`]: "allow" },
+      },
+    });
+    try {
+      const result = describeExternalDirectoryGate(readTcc(), [], resolver);
+      expect(isGateDescriptor(result)).toBe(true);
+      expect((result as GateDescriptor).preCheck?.state).toBe("allow");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("still prompts (ask) when no external_directory allow matches", () => {
+    const { resolver, cleanup } = makeResolver({
+      permission: { external_directory: { "*": "ask" } },
+    });
+    try {
+      const result = describeExternalDirectoryGate(readTcc(), [], resolver);
+      expect(isGateDescriptor(result)).toBe(true);
+      expect((result as GateDescriptor).preCheck?.state).toBe("ask");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("allows a bash command referencing the typed (symlinked) path", async () => {
+    const { resolver, cleanup } = makeResolver({
+      permission: {
+        external_directory: { "*": "ask", [`${linkDir}/*`]: "allow" },
+      },
+    });
+    try {
+      const command = `cat ${join(linkDir, "file.ts")}`;
+      const tcc: ToolCallContext = {
+        toolName: "bash",
+        agentName: null,
+        input: { command },
+        toolCallId: "tc-2",
+        cwd,
+      };
+      const program = await BashProgram.parse(command);
+      const result = describeBashExternalDirectoryGate(tcc, program, resolver);
+      // All external paths are covered by the allow → bypass, no prompt.
+      expect(isGateBypass(result)).toBe(true);
+    } finally {
+      cleanup();
+    }
+  });
+});

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

@@ -84,6 +84,20 @@ describe("describeBashExternalDirectoryGate", () => {
     expect(result).toBeNull();
   });
 
+  it("resolves each external path on the external_directory surface via resolvePathPolicy (#418)", async () => {
+    const resolver = makeResolver(makeCheckResult("ask"));
+    await describeGate(
+      makeTcc({ input: { command: "cat /outside/a.ts" } }),
+      resolver,
+    );
+    expect(resolver.resolvePathPolicy).toHaveBeenCalledWith(
+      ["/outside/a.ts"],
+      undefined,
+      "external_directory",
+    );
+    expect(resolver.resolve).not.toHaveBeenCalled();
+  });
+
   it("returns GateBypass when all external paths are session-covered", async () => {
     const resolver = makeResolver(
       makeCheckResult("allow", { source: "session" }),
@@ -116,11 +130,12 @@ describe("describeBashExternalDirectoryGate", () => {
     // not just session-level allow. This was the bug: source !== "session"
     // kept config-allowed paths in the uncovered set.
     const resolver = makeResolver();
-    resolver.resolve.mockImplementation((_surface: string, input: unknown) => {
-      if ((input as Record<string, unknown>).path)
-        return makeCheckResult("allow", { source: "special" });
-      return makeCheckResult("ask");
-    });
+    resolver.resolvePathPolicy.mockImplementation(
+      (values: readonly string[]) =>
+        values.length > 0
+          ? makeCheckResult("allow", { source: "special" })
+          : makeCheckResult("ask"),
+    );
     const result = await describeGate(makeTcc(), resolver);
     expect(result).not.toBeNull();
     expect(isGateBypass(result)).toBe(true);
@@ -131,12 +146,12 @@ describe("describeBashExternalDirectoryGate", () => {
     // silently downgrading a config-level deny to ask. After the fix, the
     // descriptor's preCheck is derived from the actual path check result.
     const resolver = makeResolver();
-    resolver.resolve.mockImplementation((_surface: string, input: unknown) => {
-      if ((input as Record<string, unknown>).path)
-        return makeCheckResult("deny", { source: "special" });
-      // Path-less catch-all returns ask — should NOT be used as preCheck.
-      return makeCheckResult("ask");
-    });
+    resolver.resolvePathPolicy.mockImplementation(
+      (values: readonly string[]) =>
+        values.length > 0
+          ? makeCheckResult("deny", { source: "special" })
+          : makeCheckResult("ask"),
+    );
     const result = await describeGate(makeTcc(), resolver);
     expect(isGateDescriptor(result)).toBe(true);
     const desc = result as GateDescriptor;
@@ -192,11 +207,12 @@ describe("describeBashExternalDirectoryGate", () => {
   it("config-allowed path is excluded; remaining ask path produces a descriptor", async () => {
     // One path config-allowed, one config-ask → descriptor with only the ask path.
     const resolver = makeResolver();
-    resolver.resolve.mockImplementation((_surface: string, input: unknown) => {
-      if ((input as Record<string, unknown>).path === "/outside/a.ts")
-        return makeCheckResult("allow", { source: "special" });
-      return makeCheckResult("ask");
-    });
+    resolver.resolvePathPolicy.mockImplementation(
+      (values: readonly string[]) =>
+        values.includes("/outside/a.ts")
+          ? makeCheckResult("allow", { source: "special" })
+          : makeCheckResult("ask"),
+    );
     const result = await describeGate(
       makeTcc({ input: { command: "diff /outside/a.ts /outside/b.ts" } }),
       resolver,
@@ -212,11 +228,12 @@ describe("describeBashExternalDirectoryGate", () => {
   it("config-denied path makes worstCheck deny even when another path is ask", async () => {
     // One path config-denied, one config-ask → descriptor with preCheck.state === "deny".
     const resolver = makeResolver();
-    resolver.resolve.mockImplementation((_surface: string, input: unknown) => {
-      if ((input as Record<string, unknown>).path === "/outside/a.ts")
-        return makeCheckResult("deny", { source: "special" });
-      return makeCheckResult("ask");
-    });
+    resolver.resolvePathPolicy.mockImplementation(
+      (values: readonly string[]) =>
+        values.includes("/outside/a.ts")
+          ? makeCheckResult("deny", { source: "special" })
+          : makeCheckResult("ask"),
+    );
     const result = await describeGate(
       makeTcc({ input: { command: "diff /outside/a.ts /outside/b.ts" } }),
       resolver,
@@ -232,12 +249,12 @@ describe("describeBashExternalDirectoryGate", () => {
 
   it("only includes uncovered paths when some are session-covered", async () => {
     const resolver = makeResolver();
-    resolver.resolve.mockImplementation((_surface: string, input: unknown) => {
-      if ((input as Record<string, unknown>).path === "/outside/a.ts") {
-        return makeCheckResult("allow", { source: "session" });
-      }
-      return makeCheckResult("ask");
-    });
+    resolver.resolvePathPolicy.mockImplementation(
+      (values: readonly string[]) =>
+        values.includes("/outside/a.ts")
+          ? makeCheckResult("allow", { source: "session" })
+          : makeCheckResult("ask"),
+    );
     const result = await describeGate(
       makeTcc({ input: { command: "diff /outside/a.ts /outside/b.ts" } }),
       resolver,

package/test/handlers/gates/bash-program.test.ts

@@ -188,11 +188,12 @@ describe("BashProgram", () => {
       });
     });
 
-    it("flags an absolute in-cwd path that resolves externally via a symlink", async () => {
+    it("flags an absolute in-cwd path that resolves externally via a symlink, returning the typed form", async () => {
       // The strict classifier only processes absolute tokens, so the escape
       // surface is `cat /cwd/link/hosts` (absolute) where `link -> /etc`.
-      // Without canonicalization: /projects/my-app/link/hosts looks internal.
-      // With canonicalization: realpathSync resolves it to /etc/hosts.
+      // The boundary decision still uses the canonical form (so the path is
+      // flagged), but the returned value is the typed/lexical form so config
+      // patterns match the path as the user wrote it (#418).
       realpathSync.mockImplementation((p: string) => {
         if (p === "/projects/my-app/link/hosts") return "/etc/hosts";
         return p;
@@ -200,7 +201,9 @@ describe("BashProgram", () => {
       const program = await BashProgram.parse(
         "cat /projects/my-app/link/hosts",
       );
-      expect(program.externalPaths(cwd)).toContain("/etc/hosts");
+      const external = program.externalPaths(cwd);
+      expect(external).toContain("/projects/my-app/link/hosts");
+      expect(external).not.toContain("/etc/hosts");
     });
 
     it("does not flag a token that resolves within a symlinked cwd", async () => {

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

@@ -7,6 +7,10 @@ import type {
 import { isGateBypass, isGateDescriptor } from "#src/handlers/gates/descriptor";
 import { describeExternalDirectoryGate } from "#src/handlers/gates/external-directory";
 import type { ToolCallContext } from "#src/handlers/gates/types";
+import type { ScopedPermissionResolver } from "#src/permission-resolver";
+import type { ToolAccessExtractorLookup } from "#src/tool-access-extractor-registry";
+import { makeResolver } from "#test/helpers/gate-fixtures";
+import { makeCheckResult } from "#test/helpers/handler-fixtures";
 
 // ── helpers ───────────────────────────��────────────────────────────��───────
 
@@ -21,18 +25,31 @@ function makeTcc(overrides: Partial<ToolCallContext> = {}): ToolCallContext {
   };
 }
 
+// Default resolver for descriptor-shape tests that do not assert the resolved
+// state: returns `ask` for the external_directory surface so a descriptor is
+// produced. Tests that assert the typed+resolved matching pass an explicit
+// resolver to `describeExternalDirectoryGate` directly.
+function gateUnderTest(
+  tcc: ToolCallContext,
+  infraDirs: string[],
+  extractors?: ToolAccessExtractorLookup,
+  resolver: ScopedPermissionResolver = makeResolver(
+    makeCheckResult({ state: "ask", toolName: "external_directory" }),
+  ),
+) {
+  return describeExternalDirectoryGate(tcc, infraDirs, resolver, extractors);
+}
+
 // ── tests ────────────────────��────────────────────────────────────��────────
 
 describe("describeExternalDirectoryGate", () => {
   it("returns null when no CWD", () => {
-    const result = describeExternalDirectoryGate(makeTcc({ cwd: undefined }), [
-      "/test/agent",
-    ]);
+    const result = gateUnderTest(makeTcc({ cwd: undefined }), ["/test/agent"]);
     expect(result).toBeNull();
   });
 
   it("returns null when tool is not path-bearing", () => {
-    const result = describeExternalDirectoryGate(
+    const result = gateUnderTest(
       makeTcc({ toolName: "bash", input: { command: "ls" } }),
       ["/test/agent"],
     );
@@ -40,7 +57,7 @@ describe("describeExternalDirectoryGate", () => {
   });
 
   it("returns null when path is inside CWD", () => {
-    const result = describeExternalDirectoryGate(
+    const result = gateUnderTest(
       makeTcc({ input: { path: "/test/project/src/index.ts" } }),
       ["/test/agent"],
     );
@@ -50,7 +67,7 @@ describe("describeExternalDirectoryGate", () => {
   // ── Pi infrastructure read bypass ─────────────────���────────────────────
 
   it("returns GateBypass for read targeting an infra dir", () => {
-    const result = describeExternalDirectoryGate(
+    const result = gateUnderTest(
       makeTcc({
         toolName: "read",
         input: { path: "/test/agent/git/some-package/SKILL.md" },
@@ -71,7 +88,7 @@ describe("describeExternalDirectoryGate", () => {
   });
 
   it("returns GateBypass respecting custom infraDirs", () => {
-    const result = describeExternalDirectoryGate(
+    const result = gateUnderTest(
       makeTcc({
         toolName: "read",
         input: { path: "/custom/infra/SKILL.md" },
@@ -82,7 +99,7 @@ describe("describeExternalDirectoryGate", () => {
   });
 
   it("does NOT bypass for write tools targeting infra dirs", () => {
-    const result = describeExternalDirectoryGate(
+    const result = gateUnderTest(
       makeTcc({
         toolName: "write",
         input: { path: "/test/agent/git/some-file.ts", content: "x" },
@@ -97,14 +114,14 @@ describe("describeExternalDirectoryGate", () => {
   // ── GateDescriptor for external paths ─────────────────────────────────��
 
   it("returns GateDescriptor with surface 'external_directory'", () => {
-    const result = describeExternalDirectoryGate(makeTcc(), ["/test/agent"]);
+    const result = gateUnderTest(makeTcc(), ["/test/agent"]);
     expect(isGateDescriptor(result)).toBe(true);
     const desc = result as GateDescriptor;
     expect(desc.surface).toBe("external_directory");
   });
 
   it("decision value is the external path", () => {
-    const result = describeExternalDirectoryGate(
+    const result = gateUnderTest(
       makeTcc({ input: { path: "/outside/project/file.ts" } }),
       ["/test/agent"],
     ) as GateDescriptor;
@@ -112,16 +129,36 @@ describe("describeExternalDirectoryGate", () => {
     expect(result.decision.surface).toBe("external_directory");
   });
 
-  it("input contains normalized path for checkPermission", () => {
-    const result = describeExternalDirectoryGate(
+  it("carries a precomputed preCheck and an empty input (matching is done by the gate)", () => {
+    const result = gateUnderTest(
       makeTcc({ input: { path: "/outside/project/file.ts" } }),
       ["/test/agent"],
     ) as GateDescriptor;
-    expect(result.input).toHaveProperty("path");
+    expect(result.input).toEqual({});
+    expect(result.preCheck).toBeDefined();
+    expect(result.preCheck?.state).toBe("ask");
+  });
+
+  it("resolves the typed and symlink-resolved aliases on the external_directory surface (#418)", () => {
+    const resolver = makeResolver(
+      makeCheckResult({ state: "ask", toolName: "external_directory" }),
+    );
+    gateUnderTest(
+      makeTcc({ input: { path: "/outside/project/file.ts" } }),
+      ["/test/agent"],
+      undefined,
+      resolver,
+    );
+    expect(resolver.resolvePathPolicy).toHaveBeenCalledWith(
+      ["/outside/project/file.ts"],
+      undefined,
+      "external_directory",
+    );
+    expect(resolver.resolve).not.toHaveBeenCalled();
   });
 
   it("sessionApproval uses deriveApprovalPattern", () => {
-    const result = describeExternalDirectoryGate(
+    const result = gateUnderTest(
       makeTcc({ input: { path: "/outside/project/file.ts" } }),
       ["/test/agent"],
     ) as GateDescriptor;
@@ -131,7 +168,7 @@ describe("describeExternalDirectoryGate", () => {
   });
 
   it("denialContext contains the external path and cwd", () => {
-    const result = describeExternalDirectoryGate(
+    const result = gateUnderTest(
       makeTcc({ input: { path: "/outside/project/file.ts" } }),
       ["/test/agent"],
     ) as GateDescriptor;
@@ -144,7 +181,7 @@ describe("describeExternalDirectoryGate", () => {
   });
 
   it("promptDetails includes path and tool_call source", () => {
-    const result = describeExternalDirectoryGate(
+    const result = gateUnderTest(
       makeTcc({ toolName: "read", agentName: "agent-1", toolCallId: "tc-5" }),
       ["/test/agent"],
     ) as GateDescriptor;
@@ -158,9 +195,7 @@ describe("describeExternalDirectoryGate", () => {
   });
 
   it("logContext includes path and message", () => {
-    const result = describeExternalDirectoryGate(makeTcc(), [
-      "/test/agent",
-    ]) as GateDescriptor;
+    const result = gateUnderTest(makeTcc(), ["/test/agent"]) as GateDescriptor;
     expect(result.logContext).toMatchObject({
       source: "tool_call",
       path: "/outside/project/file.ts",
@@ -173,7 +208,7 @@ describe("describeExternalDirectoryGate", () => {
 
 describe("describeExternalDirectoryGate — extension and MCP tools (#352)", () => {
   it("gates an extension tool with an external input.path", () => {
-    const result = describeExternalDirectoryGate(
+    const result = gateUnderTest(
       makeTcc({
         toolName: "my-ext",
         input: { path: "/outside/project/file.ts" },
@@ -185,7 +220,7 @@ describe("describeExternalDirectoryGate — extension and MCP tools (#352)", ()
   });
 
   it("gates an MCP tool with an external arguments.path", () => {
-    const result = describeExternalDirectoryGate(
+    const result = gateUnderTest(
       makeTcc({
         toolName: "mcp",
         input: { arguments: { path: "/outside/project/file.ts" } },
@@ -203,7 +238,7 @@ describe("describeExternalDirectoryGate — extension and MCP tools (#352)", ()
               typeof input.target === "string" ? input.target : undefined
           : undefined,
     };
-    const result = describeExternalDirectoryGate(
+    const result = gateUnderTest(
       makeTcc({ toolName: "ffgrep", input: { target: "/outside/project/x" } }),
       ["/test/agent"],
       extractors,
@@ -212,7 +247,7 @@ describe("describeExternalDirectoryGate — extension and MCP tools (#352)", ()
   });
 
   it("returns null for an extension tool whose path is inside cwd", () => {
-    const result = describeExternalDirectoryGate(
+    const result = gateUnderTest(
       makeTcc({
         toolName: "my-ext",
         input: { path: "/test/project/src/x.ts" },

package/test/helpers/handler-fixtures.ts

@@ -241,12 +241,14 @@ export function makeHandler(overrides?: {
     vi.mocked(permissionManager.checkPermission).mockImplementation(
       surfaceCheck,
     );
-    // The bash path gate resolves through checkPathPolicy; route it through
-    // the same surface dispatcher so `path` overrides apply to bash tokens.
+    // The bash path and external-directory gates resolve through
+    // checkPathPolicy; route it through the same surface dispatcher (threading
+    // the real surface) so `path` / `external_directory` overrides apply to
+    // bash tokens and tool paths alike (#418).
     vi.mocked(permissionManager.checkPathPolicy).mockImplementation(
-      (values, agentName, sessionRules) =>
+      (values, agentName, sessionRules, surface = "path") =>
         surfaceCheck(
-          "path",
+          surface,
           { path: values[0] ?? "*" },
           agentName,
           sessionRules,

package/test/path-utils.test.ts

@@ -22,6 +22,7 @@ vi.mock("node:fs", () => ({
 
 import {
   canonicalNormalizePathForComparison,
+  getExternalDirectoryPolicyValues,
   getPathBearingToolPath,
   getPathPolicyValues,
   getToolInputPath,
@@ -614,3 +615,36 @@ describe("getPathPolicyValues", () => {
     expect(getPathPolicyValues("   ", { cwd })).toEqual([]);
   });
 });
+
+describe("getExternalDirectoryPolicyValues", () => {
+  const cwd = "/projects/my-app";
+
+  beforeEach(() => {
+    realpathSync.mockReset();
+    realpathSync.mockImplementation((p: string) => p);
+  });
+
+  test("adds the symlink-resolved alias alongside the typed path", () => {
+    // /tmp -> /private/tmp (the macOS symlink from the bug report).
+    realpathSync.mockImplementation((p: string) =>
+      p.startsWith("/tmp") ? `/private${p}` : p,
+    );
+    expect(getExternalDirectoryPolicyValues("/tmp/x", cwd)).toEqual([
+      "/tmp/x",
+      "/private/tmp/x",
+    ]);
+  });
+
+  test("dedups when the canonical form equals the lexical form", () => {
+    expect(getExternalDirectoryPolicyValues("/etc/hosts", cwd)).toEqual([
+      "/etc/hosts",
+    ]);
+  });
+
+  test("keeps the relative aliases for an in-cwd token without duplicating", () => {
+    expect(getExternalDirectoryPolicyValues("src/foo.ts", cwd)).toEqual([
+      "/projects/my-app/src/foo.ts",
+      "src/foo.ts",
+    ]);
+  });
+});

package/test/permission-manager-unified.test.ts

@@ -8,7 +8,11 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { describe, expect, it, test } from "vitest";
-import { getGlobalConfigPath, getProjectConfigPath } from "#src/config-paths";
+import {
+  getGlobalConfigPath,
+  getProjectAgentsDir,
+  getProjectConfigPath,
+} from "#src/config-paths";
 import {
   PermissionManager,
   type ScopedPermissionManager,
@@ -1669,6 +1673,53 @@ describe("PermissionManager — configureForCwd and agentDir option", () => {
       cleanup();
     }
   });
+
+  it("configureForCwd(cwd) derives projectAgentsDir at <cwd>/.pi/agents (regression: #428)", () => {
+    // Bug: old code derived <cwd>/.pi/agent/agents instead of <cwd>/.pi/agents.
+    // This test pins the correct path and verifies agentsDir is unchanged.
+    const { agentDir, cwd, cleanup } = makeAgentDirSetup({
+      globalPermission: { read: "allow" },
+    });
+    try {
+      const manager = new PermissionManager({ agentDir });
+      manager.configureForCwd(cwd);
+      const paths = manager.getResolvedPolicyPaths();
+      expect(paths.projectAgentsDir).toBe(getProjectAgentsDir(cwd));
+      expect(paths.agentsDir).toBe(join(agentDir, "agents"));
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("configureForCwd(cwd) enforces permission: frontmatter from <cwd>/.pi/agents/<agent>.md (regression: #428)", () => {
+    // Bug: wrong directory meant project-agent frontmatter was never loaded.
+    const { agentDir, cwd, cleanup } = makeAgentDirSetup({
+      globalPermission: { read: "allow" },
+    });
+    try {
+      // Write a project agent definition with a deny override.
+      const projectAgentsDir = getProjectAgentsDir(cwd);
+      mkdirSync(projectAgentsDir, { recursive: true });
+      writeFileSync(
+        join(projectAgentsDir, "coder.md"),
+        "---\npermission:\n  read: deny\n---\n# Coder\n",
+      );
+
+      const manager = new PermissionManager({ agentDir });
+      manager.configureForCwd(cwd);
+
+      // Without an agent name: global allow applies.
+      expect(manager.checkPermission("read", { path: "foo.txt" }).state).toBe(
+        "allow",
+      );
+      // With the "coder" agent: project-agent deny overrides global allow.
+      expect(
+        manager.checkPermission("read", { path: "foo.txt" }, "coder").state,
+      ).toBe("deny");
+    } finally {
+      cleanup();
+    }
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -3279,4 +3330,40 @@ describe("checkPathPolicy", () => {
       cleanup();
     }
   });
+
+  it("evaluates against the external_directory surface when one is provided", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      external_directory: { "*": "ask", "/tmp/*": "allow" },
+    });
+    try {
+      const result = manager.checkPathPolicy(
+        ["/tmp/x"],
+        undefined,
+        undefined,
+        "external_directory",
+      );
+      expect(result.state).toBe("allow");
+      expect(result.matchedPattern).toBe("/tmp/*");
+      expect(result.source).toBe("special");
+      expect(result.toolName).toBe("external_directory");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("defaults to the path surface when no surface is provided", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      external_directory: { "*": "ask", "/tmp/*": "allow" },
+      path: { "*": "allow" },
+    });
+    try {
+      // No path rule denies; the external_directory allow must NOT apply here.
+      const result = manager.checkPathPolicy(["/tmp/x"]);
+      expect(result.toolName).toBe("path");
+      expect(result.state).toBe("allow");
+      expect(result.matchedPattern).toBe("*");
+    } finally {
+      cleanup();
+    }
+  });
 });

package/test/permission-resolver.test.ts

@@ -143,6 +143,20 @@ describe("PermissionResolver", () => {
         ["/proj/src/a.ts", "src/a.ts"],
         "agent-x",
         [],
+        "path",
+      );
+    });
+
+    it("forwards an explicit surface to checkPathPolicy", () => {
+      const { resolver, permissionManager } = makeResolver();
+
+      resolver.resolvePathPolicy(["/tmp/x"], "agent-x", "external_directory");
+
+      expect(permissionManager.checkPathPolicy).toHaveBeenCalledWith(
+        ["/tmp/x"],
+        "agent-x",
+        [],
+        "external_directory",
       );
     });