@gotgenes/pi-permission-system 12.0.0 → 13.1.0

package/src/path-utils.ts

@@ -2,6 +2,7 @@ import {
   join,
   normalize,
   posix as posixPath,
+  relative,
   resolve,
   win32 as winPath,
 } from "node:path";
@@ -63,6 +64,86 @@ export function isPathWithinDirectory(
   );
 }
 
+export interface PathPolicyValueOptions {
+  /**
+   * Current Pi working directory. When provided, returned values include a
+   * project-relative alias for paths that resolve inside this directory.
+   */
+  cwd?: string;
+  /**
+   * Directory used to resolve `pathValue` into an absolute policy value.
+   * Defaults to `cwd`. Bash uses this for tokens seen after a literal `cd`.
+   */
+  resolveBase?: string;
+}
+
+/**
+ * Normalize a single path-like lookup value without resolving it against CWD.
+ *
+ * Preserves compatibility with existing relative path rules (`src/*`, `*.env`)
+ * while applying the same lexical cleanup as
+ * {@link normalizePathForComparison}: trim, strip simple wrapping quotes,
+ * strip the OpenCode-style leading `@`, and expand `~` / `$HOME`.
+ */
+export function normalizePathPolicyLiteral(pathValue: string): string {
+  const trimmed = pathValue.trim().replace(/^['"]|['"]$/g, "");
+  if (!trimmed) return "";
+  const unprefixed = trimmed.startsWith("@") ? trimmed.slice(1) : trimmed;
+  return expandHomePath(unprefixed);
+}
+
+/**
+ * Return equivalent lookup values for path-policy matching.
+ *
+ * The first value is the cwd/effective-base normalized absolute path when a
+ * base is available. The later values preserve project-relative and raw
+ * relative forms so existing rules like `src/*` and `*.env` continue to match.
+ */
+export function getPathPolicyValues(
+  pathValue: string,
+  options: PathPolicyValueOptions = {},
+): string[] {
+  const literal = normalizePathPolicyLiteral(pathValue);
+  if (!literal) return [];
+  if (literal === "*") return ["*"];
+
+  return [
+    ...new Set([...getAbsolutePathPolicyValues(pathValue, options), literal]),
+  ];
+}
+
+function getAbsolutePathPolicyValues(
+  pathValue: string,
+  options: PathPolicyValueOptions,
+): string[] {
+  const resolveBase = options.resolveBase ?? options.cwd;
+  if (!resolveBase) return [];
+
+  const absolute = normalizePathForComparison(pathValue, resolveBase);
+  if (!absolute) return [];
+
+  return [absolute, ...getCwdRelativePathPolicyValues(absolute, options.cwd)];
+}
+
+function getCwdRelativePathPolicyValues(
+  absolute: string,
+  cwd: string | undefined,
+): string[] {
+  if (!cwd) return [];
+
+  const normalizedCwd = normalizePathForComparison(cwd, cwd);
+  if (!normalizedCwd) return [];
+  if (
+    absolute !== normalizedCwd &&
+    !isPathWithinDirectory(absolute, normalizedCwd)
+  ) {
+    return [];
+  }
+
+  const relativeValue = relative(normalizedCwd, absolute);
+  return relativeValue ? [relativeValue] : [];
+}
+
 /**
  * Paths that are universally safe and should never trigger external-directory checks.
  * These are OS device files: read returns EOF or process streams, write discards or goes to process streams.

package/src/permission-manager.ts

@@ -3,6 +3,7 @@ import { isPermissionState } from "./common";
 import { getGlobalConfigPath, getProjectConfigPath } from "./config-paths";
 import { normalizeInput } from "./input-normalizer";
 import { normalizeFlatConfig } from "./normalize";
+import { PATH_SURFACES } from "./path-utils";
 import {
   FilePolicyLoader,
   type PolicyLoader,
@@ -10,7 +11,7 @@ import {
   type ResolvedPolicyPaths,
 } from "./policy-loader";
 import type { Rule, RuleOrigin, Ruleset } from "./rule";
-import { evaluate, evaluateFirst } from "./rule";
+import { evaluate, evaluateAnyValue, evaluateFirst } from "./rule";
 import { mergeScopesWithOrigins } from "./scope-merge";
 import {
   composeRuleset,
@@ -63,6 +64,17 @@ export interface ScopedPermissionManager {
     agentName?: string,
     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.
+   */
+  checkPathPolicy(
+    values: readonly string[],
+    agentName?: string,
+    sessionRules?: Ruleset,
+  ): PermissionCheckResult;
   getToolPermission(toolName: string, agentName?: string): PermissionState;
   getConfigIssues(agentName?: string): string[];
   getPolicyCacheStamp(agentName?: string): string;
@@ -79,6 +91,7 @@ export interface PermissionManagerOptions extends PolicyLoaderOptions {
 
 export class PermissionManager implements ScopedPermissionManager {
   private readonly agentDir: string | undefined;
+  private currentCwd: string | undefined;
   private loader: PolicyLoader;
   private readonly resolvedPermissionsCache = new Map<
     string,
@@ -104,6 +117,8 @@ 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),
@@ -245,29 +260,79 @@ export class PermissionManager implements ScopedPermissionManager {
       normalizedToolName,
       input,
       this.loader.getConfiguredMcpServerNames(),
+      this.currentCwd,
     );
 
-    const { rule, value } = evaluateFirst(surface, values, fullRules);
+    return buildCheckResult(
+      surface,
+      values,
+      resultExtras,
+      normalizedToolName,
+      toolName,
+      fullRules,
+    );
+  }
 
-    // For MCP, replace the normalizer's fallback target with the actual
-    // matched candidate value so PermissionCheckResult.target is accurate.
-    const extras =
-      surface === "mcp" ? { ...resultExtras, target: value } : resultExtras;
+  checkPathPolicy(
+    values: readonly string[],
+    agentName?: string,
+    sessionRules?: Ruleset,
+  ): PermissionCheckResult {
+    const { composedRules } = this.resolvePermissions(agentName);
+    const fullRules: Ruleset = sessionRules?.length
+      ? [...composedRules, ...sessionRules]
+      : composedRules;
 
-    return {
-      toolName,
-      state: rule.action,
-      matchedPattern:
-        rule.layer === "config" || rule.layer === "session"
-          ? rule.pattern
-          : undefined,
-      source: deriveSource(rule, normalizedToolName),
-      origin: rule.origin,
-      ...extras,
-    };
+    const lookupValues = values.length > 0 ? [...values] : ["*"];
+    return buildCheckResult(
+      "path",
+      lookupValues,
+      {},
+      "path",
+      "path",
+      fullRules,
+    );
   }
 }
 
+/**
+ * Evaluate a normalized surface/values triple and shape the result.
+ *
+ * Path surfaces use {@link evaluateAnyValue} (last-match-wins across equivalent
+ * aliases); every other surface keeps {@link evaluateFirst}. Shared by
+ * `checkPermission` and `checkPathPolicy`.
+ */
+function buildCheckResult(
+  surface: string,
+  values: string[],
+  resultExtras: Record<string, unknown>,
+  normalizedToolName: string,
+  toolName: string,
+  fullRules: Ruleset,
+): PermissionCheckResult {
+  const { rule, value } = PATH_SURFACES.has(surface)
+    ? evaluateAnyValue(surface, values, fullRules)
+    : evaluateFirst(surface, values, fullRules);
+
+  // For MCP, replace the normalizer's fallback target with the actual
+  // matched candidate value so PermissionCheckResult.target is accurate.
+  const extras =
+    surface === "mcp" ? { ...resultExtras, target: value } : resultExtras;
+
+  return {
+    toolName,
+    state: rule.action,
+    reason: rule.reason,
+    matchedPattern:
+      rule.layer === "config" || rule.layer === "session"
+        ? rule.pattern
+        : undefined,
+    source: deriveSource(rule, normalizedToolName),
+    origin: rule.origin,
+    ...extras,
+  };
+}
+
 /**
  * Derive `PolicyLoaderOptions` from an agentDir + an optional cwd.
  * Setting agentsDir explicitly from agentDir removes the hidden

package/src/permission-resolver.ts

@@ -17,6 +17,15 @@ export interface ScopedPermissionResolver {
     input: unknown,
     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.
+   */
+  resolvePathPolicy(
+    values: readonly string[],
+    agentName?: string,
+  ): PermissionCheckResult;
 }
 
 /**
@@ -53,6 +62,21 @@ 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.
+   */
+  resolvePathPolicy(
+    values: readonly string[],
+    agentName?: string,
+  ): PermissionCheckResult {
+    return this.permissionManager.checkPathPolicy(
+      values,
+      agentName,
+      this.sessionRules.getRuleset(),
+    );
+  }
+
   checkPermission(
     surface: string,
     input: unknown,

package/src/permission-session.ts

@@ -150,10 +150,8 @@ export class PermissionSession implements ToolCallGateInputs {
     return this.knownAgentName;
   }
 
-  // Read by config-modal (`controller.session.lastKnownActiveAgentName`).
-  // fallow cannot trace the getter through the command's object-literal
-  // wiring, so it reports a false positive here.
-  // fallow-ignore-next-line unused-class-member
+  // Read by the `index.ts` config-modal adapter closure:
+  // `permissionManager.getComposedConfigRules(session.lastKnownActiveAgentName ?? undefined)`.
   get lastKnownActiveAgentName(): string | null {
     return this.knownAgentName;
   }

package/src/rule.ts

@@ -27,6 +27,8 @@ export interface Rule {
   pattern: string;
   /** The permission decision. */
   action: PermissionState;
+  /** Custom denial reason for deny rules (optional). */
+  reason?: string;
   /**
    * Origin layer — used to derive PermissionCheckResult.source after evaluation.
    * Not used by evaluate(); purely informational metadata.
@@ -55,17 +57,8 @@ export function evaluate(
   defaultAction?: PermissionState,
   platform: NodeJS.Platform = process.platform,
 ): Rule {
-  // On Windows, path-surface values are canonicalized + lowercased; fold the
-  // pattern→value match (case and separators) so mixed-case / forward-slash
-  // overrides still match. The surface→surface match stays exact.
-  const matchOptions =
-    platform === "win32" && PATH_SURFACES.has(surface)
-      ? { caseInsensitive: true, windowsSeparators: true }
-      : undefined;
-  const rule = rules.findLast(
-    (r) =>
-      wildcardMatch(r.surface, surface) &&
-      wildcardMatch(r.pattern, pattern, matchOptions),
+  const rule = rules.findLast((r) =>
+    ruleMatches(r, surface, pattern, platform),
   );
   if (rule !== undefined) return rule;
   return {
@@ -76,6 +69,33 @@ export function evaluate(
   };
 }
 
+/**
+ * On Windows, path-surface values are canonicalized + lowercased; fold the
+ * pattern→value match (case and separators) so mixed-case / forward-slash
+ * overrides still match. The surface→surface match stays exact.
+ */
+function pathMatchOptions(
+  surface: string,
+  platform: NodeJS.Platform,
+): { caseInsensitive: true; windowsSeparators: true } | undefined {
+  return platform === "win32" && PATH_SURFACES.has(surface)
+    ? { caseInsensitive: true, windowsSeparators: true }
+    : undefined;
+}
+
+function ruleMatches(
+  rule: Rule,
+  surface: string,
+  value: string,
+  platform: NodeJS.Platform,
+): boolean {
+  const matchOptions = pathMatchOptions(surface, platform);
+  return (
+    wildcardMatch(rule.surface, surface) &&
+    wildcardMatch(rule.pattern, value, matchOptions)
+  );
+}
+
 /**
  * Evaluate a surface against an ordered list of candidate values, stopping at
  * the first candidate that matches a non-default rule (last-match-wins within
@@ -134,3 +154,35 @@ export function evaluateFirst(
     value: fallbackValue,
   };
 }
+
+/**
+ * Evaluate equivalent lookup values as aliases of the same path.
+ *
+ * Unlike `evaluateFirst()`, this preserves rule ordering across aliases: the
+ * last rule that matches any alias wins. This lets absolute allowlists and
+ * legacy relative rules coexist without a catch-all match on the first alias
+ * masking a later, more specific rule on another alias.
+ */
+export function evaluateAnyValue(
+  surface: string,
+  values: string[],
+  rules: Ruleset,
+  platform: NodeJS.Platform = process.platform,
+): { rule: Rule; value: string } {
+  const fallbackValue = values[0] ?? "*";
+  const rule = rules.findLast((r) =>
+    values.some((value) => ruleMatches(r, surface, value, platform)),
+  );
+  if (rule !== undefined) {
+    return {
+      rule,
+      value:
+        values.find((value) => ruleMatches(rule, surface, value, platform)) ??
+        fallbackValue,
+    };
+  }
+  return {
+    rule: evaluate(surface, fallbackValue, rules),
+    value: fallbackValue,
+  };
+}

package/src/types.ts

@@ -4,14 +4,27 @@ import type { RuleOrigin } from "./rule";
 
 export type { RuleOrigin };
 
+/**
+ * A deny action with an optional reason annotation, used when a pattern maps
+ * to an object instead of a plain PermissionState string.
+ */
+export interface DenyWithReason {
+  action: "deny";
+  reason?: string;
+}
+
+/** A pattern value: a PermissionState string OR a DenyWithReason object. */
+export type PatternValue = PermissionState | DenyWithReason;
+
 /**
  * The on-disk permission shape inside the `"permission"` key.
- * Each key is a surface name; values are either a PermissionState string
- * (shorthand for `{ "*": action }`) or a pattern→action map.
+ * A surface value is a PermissionState string (shorthand for `{ "*": action }`)
+ * or a pattern→value map. Pattern values may be a PermissionState string or a
+ * DenyWithReason object. A top-level value is never a bare DenyWithReason.
  */
 export type FlatPermissionConfig = Record<
   string,
-  PermissionState | Record<string, PermissionState>
+  PermissionState | Record<string, PatternValue>
 >;
 
 /**
@@ -34,6 +47,8 @@ export type BashCommandContext =
 export interface PermissionCheckResult {
   toolName: string;
   state: PermissionState;
+  /** Custom denial reason from a deny-with-reason pattern, when present. */
+  reason?: string;
   matchedPattern?: string;
   command?: string;
   target?: string;

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

@@ -18,10 +18,7 @@ vi.mock("node:fs", () => ({
 }));
 
 import { formatDenyReason } from "#src/denial-messages";
-import {
-  extractExternalPathsFromBashCommand,
-  extractTokensForPathRules,
-} from "#src/handlers/gates/bash-path-extractor";
+import { extractExternalPathsFromBashCommand } from "#src/handlers/gates/bash-path-extractor";
 import { formatBashExternalDirectoryAskPrompt } from "#src/handlers/gates/external-directory-messages";
 
 afterEach(() => {
@@ -957,80 +954,3 @@ describe("bash external-directory denial messages (centralized)", () => {
     expect(result).not.toContain("Hard stop");
   });
 });
-
-describe("extractTokensForPathRules", () => {
-  test("extracts dot-files: cat .env", async () => {
-    const tokens = await extractTokensForPathRules("cat .env");
-    expect(tokens).toContain(".env");
-  });
-
-  test("extracts relative dot-paths: git add src/.env", async () => {
-    const tokens = await extractTokensForPathRules("git add src/.env");
-    expect(tokens).toContain("src/.env");
-  });
-
-  test("extracts nothing from plain words: echo hello", async () => {
-    const tokens = await extractTokensForPathRules("echo hello");
-    expect(tokens).toHaveLength(0);
-  });
-
-  test("extracts ./src and skips flags: rm -rf ./src", async () => {
-    const tokens = await extractTokensForPathRules("rm -rf ./src");
-    expect(tokens).toContain("./src");
-    expect(tokens).not.toContain("-rf");
-  });
-
-  test("extracts absolute paths: cat /etc/hosts", async () => {
-    const tokens = await extractTokensForPathRules("cat /etc/hosts");
-    expect(tokens).toContain("/etc/hosts");
-  });
-
-  test("skips URLs: curl https://example.com", async () => {
-    const tokens = await extractTokensForPathRules("curl https://example.com");
-    expect(tokens).not.toContain("https://example.com");
-  });
-
-  test("extracts slash-containing tokens: cat src/foo.ts", async () => {
-    const tokens = await extractTokensForPathRules("cat src/foo.ts");
-    expect(tokens).toContain("src/foo.ts");
-  });
-
-  test("skips heredoc content", async () => {
-    const tokens = await extractTokensForPathRules("cat <<EOF\n.env\nEOF");
-    expect(tokens).not.toContain(".env");
-  });
-
-  test("skips @scope/package patterns", async () => {
-    const tokens = await extractTokensForPathRules(
-      "npm install @scope/package",
-    );
-    expect(tokens).not.toContain("@scope/package");
-  });
-
-  test("skips env assignments", async () => {
-    const tokens = await extractTokensForPathRules("FOO=/bar command");
-    expect(tokens).not.toContain("FOO=/bar");
-  });
-
-  test("skips bare-slash tokens", async () => {
-    const tokens = await extractTokensForPathRules("ls /");
-    expect(tokens).not.toContain("/");
-  });
-
-  test("extracts redirect targets: echo test > .env", async () => {
-    const tokens = await extractTokensForPathRules("echo test > .env");
-    expect(tokens).toContain(".env");
-  });
-
-  test("extracts multiple path tokens: cp .env .env.backup", async () => {
-    const tokens = await extractTokensForPathRules("cp .env .env.backup");
-    expect(tokens).toContain(".env");
-    expect(tokens).toContain(".env.backup");
-  });
-
-  test("deduplicates repeated tokens", async () => {
-    const tokens = await extractTokensForPathRules("cat .env && rm .env");
-    const envCount = tokens.filter((t) => t === ".env").length;
-    expect(envCount).toBe(1);
-  });
-});

package/test/common.test.ts

@@ -3,6 +3,7 @@ import { afterEach, describe, expect, it, test, vi } from "vitest";
 import {
   extractFrontmatter,
   getNonEmptyString,
+  isDenyWithReason,
   isPermissionState,
   normalizeOptionalPositiveInt,
   normalizeOptionalStringArray,
@@ -102,6 +103,33 @@ describe("isPermissionState", () => {
   });
 });
 
+describe("isDenyWithReason", () => {
+  test("returns true for { action: 'deny' } without a reason", () => {
+    expect(isDenyWithReason({ action: "deny" })).toBe(true);
+  });
+
+  test("returns true for { action: 'deny', reason: '...' }", () => {
+    expect(isDenyWithReason({ action: "deny", reason: "Use pnpm" })).toBe(true);
+  });
+
+  test("returns false for non-deny actions", () => {
+    expect(isDenyWithReason({ action: "allow" })).toBe(false);
+    expect(isDenyWithReason({ action: "ask" })).toBe(false);
+  });
+
+  test("returns false for a non-string reason", () => {
+    expect(isDenyWithReason({ action: "deny", reason: 42 })).toBe(false);
+    expect(isDenyWithReason({ action: "deny", reason: null })).toBe(false);
+  });
+
+  test("returns false for non-object types", () => {
+    expect(isDenyWithReason(null)).toBe(false);
+    expect(isDenyWithReason(undefined)).toBe(false);
+    expect(isDenyWithReason("deny")).toBe(false);
+    expect(isDenyWithReason(["deny"])).toBe(false);
+  });
+});
+
 describe("extractFrontmatter", () => {
   test("returns empty string when no frontmatter delimiter", () => {
     expect(extractFrontmatter("# Hello\nSome content")).toBe("");

package/test/config-loader.test.ts

@@ -243,6 +243,49 @@ describe("loadUnifiedConfig", () => {
     });
   });
 
+  it("preserves a deny-with-reason object inside a pattern map", () => {
+    const configPath = join(tempDir, "config.json");
+    writeFileSync(
+      configPath,
+      JSON.stringify({
+        permission: {
+          bash: {
+            "git *": "allow",
+            "npm *": { action: "deny", reason: "Use pnpm instead" },
+          },
+        },
+      }),
+    );
+
+    const result = loadUnifiedConfig(configPath);
+    expect(result.config.permission).toEqual({
+      bash: {
+        "git *": "allow",
+        "npm *": { action: "deny", reason: "Use pnpm instead" },
+      },
+    });
+  });
+
+  it("strips a deny object with a non-string reason (malformed)", () => {
+    const configPath = join(tempDir, "config.json");
+    writeFileSync(
+      configPath,
+      JSON.stringify({
+        permission: {
+          bash: {
+            "git *": "allow",
+            "npm *": { action: "deny", reason: 42 },
+          },
+        },
+      }),
+    );
+
+    const result = loadUnifiedConfig(configPath);
+    expect(result.config.permission).toEqual({
+      bash: { "git *": "allow" },
+    });
+  });
+
   it("returns no permission when the permission field is absent", () => {
     const configPath = join(tempDir, "config.json");
     writeFileSync(configPath, JSON.stringify({ debugLog: false }));

package/test/config-modal.test.ts

@@ -2,6 +2,7 @@ import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { expect, test, vi } from "vitest";
+import { loadUnifiedConfig } from "#src/config-loader";
 import { registerPermissionSystemCommand } from "#src/config-modal";
 import type { CommandConfigStore } from "#src/config-store";
 import {
@@ -89,8 +90,7 @@ test("permission-system command completions expose top-level config actions", ()
     const controller = {
       config: configStore,
       configPath,
-      permissionManager: { getComposedConfigRules: () => [] as Ruleset },
-      session: { lastKnownActiveAgentName: null },
+      getActiveAgentConfigRules: () => [] as Ruleset,
     };
 
     let definition: {
@@ -146,7 +146,7 @@ test("permission-system command handlers manage config summary, persistence, and
       current: () => config,
       save: (next) => {
         const currentConfig = normalizePermissionSystemConfig(
-          JSON.parse(readFileSync(configPath, "utf-8")) as unknown,
+          loadUnifiedConfig(configPath).config,
         );
         const normalized = normalizePermissionSystemConfig(next);
         writeFileSync(
@@ -155,7 +155,7 @@ test("permission-system command handlers manage config summary, persistence, and
           "utf-8",
         );
         config = normalizePermissionSystemConfig(
-          JSON.parse(readFileSync(configPath, "utf-8")) as unknown,
+          loadUnifiedConfig(configPath).config,
         );
         expect(config).not.toEqual(currentConfig);
       },
@@ -163,8 +163,7 @@ test("permission-system command handlers manage config summary, persistence, and
     const controller = {
       config: configStore,
       configPath,
-      permissionManager: { getComposedConfigRules: () => [] as Ruleset },
-      session: { lastKnownActiveAgentName: null },
+      getActiveAgentConfigRules: () => [] as Ruleset,
     };
 
     let registeredName = "";
@@ -262,8 +261,7 @@ test("show output includes rule origins when getComposedRules is provided", asyn
   const controller = {
     config: { current: () => config, save: () => {} } as CommandConfigStore,
     configPath: "/fake/config.json",
-    permissionManager: { getComposedConfigRules: () => composedRules },
-    session: { lastKnownActiveAgentName: null },
+    getActiveAgentConfigRules: () => composedRules,
   };
 
   let definition: {
@@ -295,8 +293,7 @@ test("show output omits rule summary when getComposedRules is not provided", asy
   const controller = {
     config: { current: () => config, save: () => {} } as CommandConfigStore,
     configPath: "/fake/config.json",
-    permissionManager: { getComposedConfigRules: () => [] as Ruleset },
-    session: { lastKnownActiveAgentName: null },
+    getActiveAgentConfigRules: () => [] as Ruleset,
   };
 
   let definition: {