@gotgenes/pi-permission-system 12.0.0 → 13.1.0

package/CHANGELOG.md

@@ -5,6 +5,46 @@ 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.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v13.0.0...pi-permission-system-v13.1.0) (2026-06-13)
+
+
+### Features
+
+* **pi-permission-system:** add DenyWithReason type and shared guard ([51750e1](https://github.com/gotgenes/pi-packages/commit/51750e188592520798eaf9676a15a709a779cf96)), closes [#395](https://github.com/gotgenes/pi-packages/issues/395)
+* **pi-permission-system:** append custom reason to denial messages ([d8e5756](https://github.com/gotgenes/pi-packages/commit/d8e575632678b806d381f1436dbb06197d742104)), closes [#395](https://github.com/gotgenes/pi-packages/issues/395)
+* **pi-permission-system:** build deny rules with reason in normalizeFlatConfig ([186c15a](https://github.com/gotgenes/pi-packages/commit/186c15a74944bc2800bcea738984021169fabc8d)), closes [#395](https://github.com/gotgenes/pi-packages/issues/395)
+* **pi-permission-system:** preserve deny-with-reason from JSON config ([3201bfd](https://github.com/gotgenes/pi-packages/commit/3201bfd55d68aac1ee87ac452723f6d0783dba6d)), closes [#395](https://github.com/gotgenes/pi-packages/issues/395)
+* **pi-permission-system:** thread deny reason into PermissionCheckResult ([ed712e4](https://github.com/gotgenes/pi-packages/commit/ed712e47458a662e3d1159e2f5096c709ab2ddf5)), closes [#395](https://github.com/gotgenes/pi-packages/issues/395)
+
+
+### Documentation
+
+* **pi-permission-system:** document deny-with-reason config form ([45be4e7](https://github.com/gotgenes/pi-packages/commit/45be4e72c0ca43040cb0f55ca196a0cab0b9fc14)), closes [#395](https://github.com/gotgenes/pi-packages/issues/395)
+
+## [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/config/config.example.json

@@ -25,7 +25,8 @@
       "*": "ask",
       "git *": "ask",
       "git status": "allow",
-      "git diff": "allow"
+      "git diff": "allow",
+      "npm *": { "action": "deny", "reason": "Use pnpm instead" }
     },
     "mcp": { "*": "ask", "mcp_status": "allow", "mcp_list": "allow" },
     "skill": { "*": "ask" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "12.0.0",
+  "version": "13.1.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 '*'.",
@@ -125,8 +125,34 @@
         "minLength": 1
       },
       "additionalProperties": {
-        "$ref": "#/$defs/permissionState"
+        "oneOf": [
+          {
+            "$ref": "#/$defs/permissionState",
+            "description": "A permission decision for this pattern."
+          },
+          {
+            "$ref": "#/$defs/denyWithReason",
+            "description": "Deny this pattern with an optional custom reason."
+          }
+        ]
       }
+    },
+    "denyWithReason": {
+      "type": "object",
+      "description": "Deny with an optional custom reason shown to the agent when the action is blocked.",
+      "properties": {
+        "action": {
+          "const": "deny",
+          "description": "The permission decision \u2014 must be \"deny\"."
+        },
+        "reason": {
+          "type": "string",
+          "maxLength": 500,
+          "description": "Optional reason shown to the agent when this action is denied."
+        }
+      },
+      "required": ["action"],
+      "additionalProperties": false
     }
   }
 }

package/src/common.ts

@@ -1,4 +1,4 @@
-import type { PermissionState } from "./types";
+import type { DenyWithReason, PermissionState } from "./types";
 
 export function toRecord(value: unknown): Record<string, unknown> {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -38,6 +38,22 @@ export function isPermissionState(value: unknown): value is PermissionState {
   return value === "allow" || value === "deny" || value === "ask";
 }
 
+/**
+ * Narrow type guard: a raw value representing a DenyWithReason object.
+ * Accepts `{ action: "deny" }` and `{ action: "deny", reason: "…" }`.
+ * Rejects a non-string `reason` to keep malformed config out of the rule set.
+ */
+export function isDenyWithReason(value: unknown): value is DenyWithReason {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const record = value as Record<string, unknown>;
+  return (
+    record.action === "deny" &&
+    (record.reason === undefined || typeof record.reason === "string")
+  );
+}
+
 type StackNode = { indent: number; target: Record<string, unknown> };
 
 export function parseSimpleYamlMap(input: string): Record<string, unknown> {

package/src/config-loader.ts

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { normalize } from "node:path";
-
 import {
+  isDenyWithReason,
   isPermissionState,
   normalizeOptionalPositiveInt,
   normalizeOptionalStringArray,
@@ -15,7 +15,7 @@ import {
   getProjectConfigPath,
 } from "./config-paths";
 import { mergeFlatPermissions } from "./permission-merge";
-import type { FlatPermissionConfig } from "./types";
+import type { FlatPermissionConfig, PatternValue } from "./types";
 
 /**
  * Unified config shape combining runtime knobs and flat permission policy.
@@ -127,7 +127,8 @@ function normalizeOptionalBoolean(value: unknown): boolean | undefined {
 
 /**
  * Normalize a raw `permission` value from parsed JSON into a FlatPermissionConfig.
- * Drops non-object top-level values, invalid PermissionState strings, and
+ * Accepts PermissionState strings and DenyWithReason objects inside pattern
+ * maps. Drops non-object top-level values, invalid PermissionState strings, and
  * invalid action values inside object maps.
  */
 function normalizeFlatPermissionValue(
@@ -147,12 +148,15 @@ function normalizeFlatPermissionValue(
         hasAny = true;
       }
     } else if (typeof val === "object" && val !== null && !Array.isArray(val)) {
-      const map: Record<string, import("./types").PermissionState> = {};
+      const map: Record<string, PatternValue> = {};
       let mapHasAny = false;
       for (const [pattern, action] of Object.entries(
         val as Record<string, unknown>,
       )) {
-        if (isPermissionState(action)) {
+        if (isDenyWithReason(action)) {
+          map[pattern] = action;
+          mapHasAny = true;
+        } else if (isPermissionState(action)) {
           map[pattern] = action;
           mapHasAny = true;
         }

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/denial-messages.ts

@@ -126,7 +126,8 @@ function buildToolDenyBody(
     parts.push(qualifier);
   }
 
-  return `${parts.join(" ")}.`;
+  // reasonSuffix appends ` Reason: <reason>.` after the sentence-ending period.
+  return `${parts.join(" ")}.${reasonSuffix(check.reason)}`;
 }
 
 /**

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/normalize.ts

@@ -1,4 +1,4 @@
-import { isPermissionState } from "./common";
+import { isDenyWithReason, isPermissionState } from "./common";
 import type { Rule, Ruleset } from "./rule";
 import type { FlatPermissionConfig } from "./types";
 
@@ -7,6 +7,8 @@ import type { FlatPermissionConfig } from "./types";
  *
  * Each key is a surface name. A string value is shorthand for
  * `{ "*": action }`. An object value maps patterns to actions.
+ * A pattern value may be a PermissionState string or a `DenyWithReason`
+ * object (`{ action: "deny", reason?: string }`).
  * Invalid action values are silently skipped.
  *
  * The universal fallback key `"*"` is included if present — callers
@@ -23,7 +25,15 @@ export function normalizeFlatConfig(permission: FlatPermissionConfig): Ruleset {
       // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- defensive null check; value type does not include null but runtime JSON may
     } else if (typeof value === "object" && value !== null) {
       for (const [pattern, action] of Object.entries(value)) {
-        if (isPermissionState(action)) {
+        if (isDenyWithReason(action)) {
+          rules.push({
+            surface,
+            pattern,
+            action: "deny",
+            reason: action.reason,
+            origin: "builtin",
+          });
+        } else if (isPermissionState(action)) {
           rules.push({ surface, pattern, action, origin: "builtin" });
         }
       }