@gotgenes/pi-permission-system 12.0.0 → 13.0.0

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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).
 
+## [13.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v12.0.0...pi-permission-system-v13.0.0) (2026-06-12)
+
+
+### ⚠ BREAKING CHANGES
+
+* A relative bash path token now also matches absolute allowlist rules naming the same file, resolved against the effective directory after literal cd commands. A token under a config like `path: { "*": "ask", "/workspace/project/*": "allow" }` moves from `ask` to `allow`. Tokens after a non-literal cd (e.g. cd "$DIR") stay conservative and match only their literal form.
+* When Pi's working directory is known, a relative path input now also matches absolute allowlist rules naming the same file. A config like `path: { "*": "ask", "/workspace/project/*": "allow" }` moves a relative `src/App.jsx` from `ask` to `allow`. To keep tighter control, narrow the allowlist patterns or add an explicit `path` deny for the sensitive paths.
+
+### Features
+
+* add alias-aware evaluateAnyValue ([#393](https://github.com/gotgenes/pi-packages/issues/393)) ([2b7d240](https://github.com/gotgenes/pi-packages/commit/2b7d24091fbeb078bcfbc363bc0062199ee1de24))
+* add cd-aware pathRuleCandidates to BashProgram ([#393](https://github.com/gotgenes/pi-packages/issues/393)) ([102a491](https://github.com/gotgenes/pi-packages/commit/102a491ef73e225a6a93008195ff958e4c5bd315))
+* add path-policy value derivation ([#393](https://github.com/gotgenes/pi-packages/issues/393)) ([d34e57f](https://github.com/gotgenes/pi-packages/commit/d34e57fe96c74b2ba87e9d0ebe9be5055db0855f))
+* add resolvePathPolicy resolver method ([#393](https://github.com/gotgenes/pi-packages/issues/393)) ([8ec81da](https://github.com/gotgenes/pi-packages/commit/8ec81da65e7f994beb5f65bead8b11174277fa53))
+* match relative path inputs against absolute allowlists ([#393](https://github.com/gotgenes/pi-packages/issues/393)) ([6d0c564](https://github.com/gotgenes/pi-packages/commit/6d0c564d1d7b48227898d0be5fbbf5c91cc7ca89))
+* normalize path inputs to cwd-aware policy values ([#393](https://github.com/gotgenes/pi-packages/issues/393)) ([3c2784f](https://github.com/gotgenes/pi-packages/commit/3c2784fc2199b4903a0aaa8a22a971c1bfb4969d))
+* resolve bash path tokens with cd-aware policy values ([#393](https://github.com/gotgenes/pi-packages/issues/393)) ([7bcdbe7](https://github.com/gotgenes/pi-packages/commit/7bcdbe708a29448cbfda4a76b7e8917795fbb741))
+
+
+### Documentation
+
+* document cwd-aware path policy matching ([#393](https://github.com/gotgenes/pi-packages/issues/393)) ([8ab53a2](https://github.com/gotgenes/pi-packages/commit/8ab53a2de6c4deea5bbcd9c72a36ec0943e1a69a))
+* **pi-permission-system:** update Development section to current scripts and tooling ([ebda301](https://github.com/gotgenes/pi-packages/commit/ebda301798290f528f930917b6792a5c21379a5d))
+
 ## [12.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v11.0.0...pi-permission-system-v12.0.0) (2026-06-12)
 
 

package/README.md

@@ -70,6 +70,7 @@ Extension and MCP tools that operate on paths (via `input.path`, MCP's `input.ar
 
 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.
+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/*`.
 
 Four layers compose with most-restrictive-wins: `path` (cross-cutting) → `external_directory` (CWD boundary) → per-tool patterns → `bash` command patterns.
 
@@ -104,19 +105,16 @@ For the full reference — all surfaces, runtime knobs, per-agent overrides, mer
 ## Development
 
 ```bash
-pnpm run build       # Type-check TypeScript (no emit)
-pnpm run lint        # Biome lint + format check
-pnpm run lint:fix    # Biome lint + format auto-fix
-pnpm run lint:md     # markdownlint-cli2 on README etc.
-pnpm run lint:all    # lint + lint:md
-pnpm run format      # Biome format --write
-pnpm run test        # Run tests from ./tests
-pnpm run check       # build + lint:all + test
+pnpm run check       # Type-check TypeScript (no emit)
+pnpm run lint        # Biome + ESLint + lint:md
+pnpm run lint:md     # rumdl on README and docs
+pnpm run test        # Run tests from ./test
+pnpm run test:watch  # Run tests in watch mode
 ```
 
 ### Pre-commit hooks
 
-This project uses [prek](https://prek.j178.dev/) to run Biome and markdownlint on staged files before each commit.
+This project uses [prek](https://prek.j178.dev/) to run Biome, ESLint, and rumdl on staged files before each commit.
 Run `pnpm install` to set up hooks automatically.
 
 ## Acknowledgments

package/package.json

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

package/schemas/permissions.schema.json

@@ -53,7 +53,7 @@
     },
     "permission": {
       "description": "Flat permission policy. Each key is a surface name; values are a PermissionState string (catch-all) or a pattern→action map.",
-      "markdownDescription": "Flat permission policy.\n\nEach top-level key is a surface name:\n- `\"*\"` — universal fallback (replaces `defaultPolicy.tools` from the legacy format)\n- Tool names (`read`, `write`, `bash`, `mcp`, `skill`, `external_directory`, `path`, etc.)\n\nA **string** value is shorthand for `{ \"*\": action }` (surface-level catch-all).\nAn **object** value maps wildcard patterns to actions — last matching pattern wins.\n\nFor built-in file tools (`read`, `write`, `edit`, `find`, `grep`, `ls`), patterns are matched against the file path from `input.path`. For example, `\"read\": { \"*\": \"allow\", \"*.env\": \"deny\" }` allows reads but denies `.env` files.\n\nThe `path` surface is a cross-cutting gate that applies to **all** file access: Pi tools, bash commands, MCP calls (via `input.arguments.path`), and extension tools (via `input.path` or a registered access extractor). A `path` deny cannot be overridden by a per-tool allow. Use it to protect sensitive files (`.env`, `~/.ssh/*`) from all path-aware tools at once.\n\n**Merge order (lowest → highest precedence):** global → project → per-agent frontmatter.",
+      "markdownDescription": "Flat permission policy.\n\nEach top-level key is a surface name:\n- `\"*\"` — universal fallback (replaces `defaultPolicy.tools` from the legacy format)\n- Tool names (`read`, `write`, `bash`, `mcp`, `skill`, `external_directory`, `path`, etc.)\n\nA **string** value is shorthand for `{ \"*\": action }` (surface-level catch-all).\nAn **object** value maps wildcard patterns to actions — last matching pattern wins.\n\nFor built-in file tools (`read`, `write`, `edit`, `find`, `grep`, `ls`), patterns are matched against the file path from `input.path`. For example, `\"read\": { \"*\": \"allow\", \"*.env\": \"deny\" }` allows reads but denies `.env` files.\n\nWhen 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/*`. Bash path tokens use the effective directory after literal `cd` commands for this matching; non-literal `cd \"$DIR\"` style commands remain conservative.\n\nThe `path` surface is a cross-cutting gate that applies to **all** file access: Pi tools, bash commands, MCP calls (via `input.arguments.path`), and extension tools (via `input.path` or a registered access extractor). A `path` deny cannot be overridden by a per-tool allow. Use it to protect sensitive files (`.env`, `~/.ssh/*`) from all path-aware tools at once.\n\n**Merge order (lowest → highest precedence):** global → project → per-agent frontmatter.",
       "type": "object",
       "propertyNames": {
         "description": "A surface name or the universal fallback key '*'.",

package/src/config-modal.ts

@@ -16,10 +16,8 @@ interface PermissionSystemConfigController {
   config: CommandConfigStore;
   /** Precomputed global config file path. */
   configPath: string;
-  /** Returns the composed config-layer ruleset for origin display. */
-  permissionManager: { getComposedConfigRules(agentName?: string): Ruleset };
-  /** Provides the active agent name for scoped rule lookup. */
-  session: { readonly lastKnownActiveAgentName: string | null };
+  /** Returns the composed config-layer ruleset for the active agent scope. */
+  getActiveAgentConfigRules(): Ruleset;
 }
 
 const ON_OFF = ["on", "off"];
@@ -206,9 +204,7 @@ function handleArgs(
   }
 
   if (normalized === "show") {
-    const rules = controller.permissionManager.getComposedConfigRules(
-      controller.session.lastKnownActiveAgentName ?? undefined,
-    );
+    const rules = controller.getActiveAgentConfigRules();
     ctx.ui.notify(
       `permission-system: ${summarizeConfig(controller.config.current(), rules)}`,
       "info",

package/src/extension-config.ts

@@ -2,11 +2,7 @@ import { mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import {
-  normalizeOptionalPositiveInt,
-  normalizeOptionalStringArray,
-  toRecord,
-} from "./common";
+import type { UnifiedPermissionConfig } from "./config-loader";
 
 export const EXTENSION_ID = "pi-permission-system";
 
@@ -51,31 +47,21 @@ export function detectMisplacedPermissionKeys(
 }
 
 export function normalizePermissionSystemConfig(
-  raw: unknown,
+  raw: UnifiedPermissionConfig,
 ): PermissionSystemExtensionConfig {
-  const record = toRecord(raw);
-  const piInfrastructureReadPaths = normalizeOptionalStringArray(
-    record.piInfrastructureReadPaths,
-  );
   const result: PermissionSystemExtensionConfig = {
-    debugLog: record.debugLog === true,
-    permissionReviewLog: record.permissionReviewLog !== false,
-    yoloMode: record.yoloMode === true,
+    debugLog: raw.debugLog === true,
+    permissionReviewLog: raw.permissionReviewLog !== false,
+    yoloMode: raw.yoloMode === true,
   };
-  if (piInfrastructureReadPaths !== undefined) {
-    result.piInfrastructureReadPaths = piInfrastructureReadPaths;
+  if (raw.piInfrastructureReadPaths !== undefined) {
+    result.piInfrastructureReadPaths = raw.piInfrastructureReadPaths;
   }
-  const toolInputPreviewMaxLength = normalizeOptionalPositiveInt(
-    record.toolInputPreviewMaxLength,
-  );
-  if (toolInputPreviewMaxLength !== undefined) {
-    result.toolInputPreviewMaxLength = toolInputPreviewMaxLength;
+  if (raw.toolInputPreviewMaxLength !== undefined) {
+    result.toolInputPreviewMaxLength = raw.toolInputPreviewMaxLength;
   }
-  const toolTextSummaryMaxLength = normalizeOptionalPositiveInt(
-    record.toolTextSummaryMaxLength,
-  );
-  if (toolTextSummaryMaxLength !== undefined) {
-    result.toolTextSummaryMaxLength = toolTextSummaryMaxLength;
+  if (raw.toolTextSummaryMaxLength !== undefined) {
+    result.toolTextSummaryMaxLength = raw.toolTextSummaryMaxLength;
   }
   return result;
 }

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

@@ -13,15 +13,3 @@ export async function extractExternalPathsFromBashCommand(
 ): Promise<string[]> {
   return (await BashProgram.parse(command)).externalPaths(cwd);
 }
-
-/**
- * Extract tokens from a bash command that may be file paths, using the broader
- * filter suitable for cross-cutting `path` permission rules.
- *
- * Thin facade over {@link BashProgram.pathTokens}.
- */
-export async function extractTokensForPathRules(
-  command: string,
-): Promise<string[]> {
-  return (await BashProgram.parse(command)).pathTokens();
-}

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

@@ -12,10 +12,12 @@ import type { ToolCallContext } from "./types";
 /**
  * Build a pure descriptor for the cross-cutting path permission gate (bash).
  *
- * Reads path-candidate tokens from the injected `BashProgram` (the broader
- * `path`-rule filter, accepting dot-files and relative paths). Evaluates each
- * token against the `path` permission surface and returns the most
- * restrictive result.
+ * Reads path-rule candidates from the injected `BashProgram` (the broader
+ * `path`-rule filter, accepting dot-files and relative paths). Each candidate
+ * pairs the raw token with cd-aware policy values; the gate evaluates those
+ * values against the `path` permission surface and returns the most
+ * restrictive result, while prompts, logs, and session approvals use the raw
+ * token.
  *
  * Returns `null` when the gate does not apply (tool is not bash, no command,
  * no tokens extracted, or all tokens evaluate to `allow`).
@@ -34,18 +36,18 @@ export function describeBashPathGate(
 
   if (!bashProgram) return null;
 
-  const tokens = bashProgram.pathTokens();
-  if (tokens.length === 0) return null;
+  const candidates = bashProgram.pathRuleCandidates(tcc.cwd);
+  if (candidates.length === 0) return null;
+  const tokens = candidates.map(({ token }) => token);
 
   // Tokens whose resolved state needs a check (deny/ask), paired with the
   // token that produced them so the descriptor can derive its pattern.
   const uncovered: Array<{ token: string; check: PermissionCheckResult }> = [];
   let allSessionCovered = true;
 
-  for (const token of tokens) {
-    const check = resolver.resolve(
-      "path",
-      { path: token },
+  for (const { token, policyValues } of candidates) {
+    const check = resolver.resolvePathPolicy(
+      policyValues,
       tcc.agentName ?? undefined,
     );
 

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

@@ -6,9 +6,11 @@ import {
   classifyTokenAsRuleCandidate,
 } from "#src/handlers/gates/bash-token-classification";
 import {
+  getPathPolicyValues,
   isPathWithinDirectory,
   isSafeSystemPath,
   normalizePathForComparison,
+  normalizePathPolicyLiteral,
 } from "#src/path-utils";
 import type { BashCommandContext } from "#src/types";
 
@@ -98,6 +100,13 @@ interface PathCandidate {
   readonly base: EffectiveBase;
 }
 
+export interface BashPathRuleCandidate {
+  /** Raw path-like token shown in prompts, logs, and session approvals. */
+  readonly token: string;
+  /** Equivalent values used for permission policy matching. */
+  readonly policyValues: readonly string[];
+}
+
 /**
  * A bash command parsed once into a reusable representation.
  *
@@ -139,23 +148,36 @@ export class BashProgram {
   }
 
   /**
-   * Tokens that may be file paths, using the broader `path`-rule filter.
+   * Path-rule candidates paired with their policy lookup values.
    *
-   * Accepts relative paths (`.env`, `src/foo.ts`, `./build`) and absolute
-   * paths; does NOT filter by CWD. Returns deduplicated tokens for rule
-   * evaluation.
+   * When `cwd` is available, each relative token is resolved against the
+   * effective working directory in force at the token's position (folding
+   * literal current-shell `cd` commands), while raw and project-relative
+   * aliases are retained for backward-compatible relative rules. A token after
+   * a non-literal `cd` keeps only its literal value so no spurious absolute
+   * rule can match.
    */
-  pathTokens(): string[] {
+  pathRuleCandidates(cwd?: string): BashPathRuleCandidate[] {
     const seen = new Set<string>();
-    const result: string[] = [];
-    for (const { token } of this.rawCandidates) {
+    const result: BashPathRuleCandidate[] = [];
+
+    for (const { token, base } of this.rawCandidates) {
       const candidate = classifyTokenAsRuleCandidate(token);
       if (!candidate) continue;
-      if (!seen.has(candidate)) {
-        seen.add(candidate);
-        result.push(candidate);
-      }
+
+      const policyValues = getPolicyValuesForRuleCandidate(
+        candidate,
+        base,
+        cwd,
+      );
+      if (policyValues.length === 0) continue;
+
+      const key = policyValues.join("\0");
+      if (seen.has(key)) continue;
+      seen.add(key);
+      result.push({ token: candidate, policyValues });
     }
+
     return result;
   }
 
@@ -894,6 +916,25 @@ function isRelativeCandidate(candidate: string): boolean {
   return !candidate.startsWith("/") && !candidate.startsWith("~");
 }
 
+function getPolicyValuesForRuleCandidate(
+  candidate: string,
+  base: EffectiveBase,
+  cwd: string | undefined,
+): string[] {
+  if (!cwd) {
+    const literal = normalizePathPolicyLiteral(candidate);
+    return literal ? [literal] : [];
+  }
+
+  if (base.kind === "unknown" && isRelativeCandidate(candidate)) {
+    const literal = normalizePathPolicyLiteral(candidate);
+    return literal ? [literal] : [];
+  }
+
+  const resolveBase = base.kind === "known" ? resolve(cwd, base.offset) : cwd;
+  return getPathPolicyValues(candidate, { cwd, resolveBase });
+}
+
 /**
  * Compute the effective base after a command runs. Returns `base` unchanged
  * unless the command is `cd`:

package/src/handlers/gates/bash-token-classification.ts

@@ -1,7 +1,7 @@
 /**
  * Pure, synchronous token-classification helpers for bash path extraction.
  *
- * Exports two classifiers consumed by `bash-path-extractor.ts`:
+ * Exports two classifiers consumed by `bash-program.ts`:
  *   - `classifyTokenAsPathCandidate` — strict gate for the external-directory guard.
  *   - `classifyTokenAsRuleCandidate` — broader gate for cross-cutting `path` rules.
  *

package/src/index.ts

@@ -115,8 +115,10 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   registerPermissionSystemCommand(pi, {
     config: configStore,
     configPath,
-    permissionManager,
-    session,
+    getActiveAgentConfigRules: () =>
+      permissionManager.getComposedConfigRules(
+        session.lastKnownActiveAgentName ?? undefined,
+      ),
   });
 
   const rpcHandles = registerPermissionRpcHandlers(pi.events, {

package/src/input-normalizer.ts

@@ -1,7 +1,6 @@
 import { getNonEmptyString, toRecord } from "./common";
-import { expandHomePath } from "./expand-home";
 import { createMcpPermissionTargets } from "./mcp-targets";
-import { PATH_BEARING_TOOLS } from "./path-utils";
+import { getPathPolicyValues, PATH_BEARING_TOOLS } from "./path-utils";
 
 /**
  * Construct a surface-appropriate input object from a raw value string.
@@ -66,12 +65,13 @@ export function normalizeInput(
   toolName: string,
   input: unknown,
   configuredMcpServerNames: readonly string[],
+  cwd?: string,
 ): NormalizedInput {
   // --- Special surfaces (path, external_directory) ---
   if (SPECIAL_PERMISSION_KEYS.has(toolName)) {
     return {
       surface: toolName,
-      values: [normalizePathSurfaceValue(input)],
+      values: normalizePathSurfaceValues(input, cwd),
       resultExtras: {},
     };
   }
@@ -117,7 +117,7 @@ export function normalizeInput(
   if (PATH_BEARING_TOOLS.has(toolName)) {
     return {
       surface: toolName,
-      values: [normalizePathSurfaceValue(input)],
+      values: normalizePathSurfaceValues(input, cwd),
       resultExtras: {},
     };
   }
@@ -131,15 +131,21 @@ export function normalizeInput(
 }
 
 /**
- * Extract and home-expand the `input.path` lookup value shared by every path
- * surface (`path`, `external_directory`, and the path-bearing tools).
+ * Extract and normalize the path lookup values shared by every path surface
+ * (`path`, `external_directory`, and the path-bearing tools).
  *
  * Missing, empty, or whitespace-only paths collapse to the surface catch-all
- * `"*"`; otherwise `~/…` and `$HOME/…` prefixes are expanded to the OS home
- * directory so values match home-anchored patterns symmetrically with how
- * `compileWildcardPattern` expands the patterns themselves (#350).
+ * `"*"`. When CWD is known, a relative path also produces a normalized
+ * absolute policy value and a project-relative alias while keeping its legacy
+ * relative value, so values match home- and cwd-anchored patterns
+ * symmetrically with how the patterns themselves are expanded (#350).
+ *
+ * Only `input.path` is read — policy values are never sourced from any other
+ * (potentially attacker-controlled) field on the raw tool input.
  */
-function normalizePathSurfaceValue(input: unknown): string {
+function normalizePathSurfaceValues(input: unknown, cwd?: string): string[] {
   const path = getNonEmptyString(toRecord(input).path);
-  return path === null ? "*" : expandHomePath(path);
+  if (path === null) return ["*"];
+  const values = getPathPolicyValues(path, cwd ? { cwd } : {});
+  return values.length > 0 ? values : ["*"];
 }

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,78 @@ 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,
+    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