@gotgenes/pi-permission-system 18.0.1 → 18.1.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).
 
+## [18.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v18.0.2...pi-permission-system-v18.1.0) (2026-07-02)
+
+
+### Features
+
+* **pi-permission-system:** add rule-driven bare-token classifier ([0d693a7](https://github.com/gotgenes/pi-packages/commit/0d693a79478b3e7d9d23c573ec5a085ce8afccfd)), closes [#509](https://github.com/gotgenes/pi-packages/issues/509)
+* **pi-permission-system:** derive promotable path-token matcher from config ([4a29882](https://github.com/gotgenes/pi-packages/commit/4a298827768fe8730b6b51898740d084676d46cd)), closes [#509](https://github.com/gotgenes/pi-packages/issues/509)
+* **pi-permission-system:** gate bash bare filenames via path rules ([4ee201a](https://github.com/gotgenes/pi-packages/commit/4ee201a0f771c732e9ac62562a09d54204b425aa)), closes [#509](https://github.com/gotgenes/pi-packages/issues/509)
+* **pi-permission-system:** promote bare tokens in bash path projection ([f887b7c](https://github.com/gotgenes/pi-packages/commit/f887b7cd3820f085d97105bfa6dc470b35500835)), closes [#509](https://github.com/gotgenes/pi-packages/issues/509)
+
+
+### Documentation
+
+* **pi-permission-system:** document bash bare-filename path promotion ([db7159b](https://github.com/gotgenes/pi-packages/commit/db7159b00af083dc9a7af13c41589ba95376f9ac)), closes [#509](https://github.com/gotgenes/pi-packages/issues/509)
+
+## [18.0.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v18.0.1...pi-permission-system-v18.0.2) (2026-07-01)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** add AccessPath.resolvedAlias() for symlink-target disclosure ([cf6e25c](https://github.com/gotgenes/pi-packages/commit/cf6e25c8a5b672fbab4b41a21240af8ca818971b))
+* **pi-permission-system:** disclose resolved symlink target in tool external-directory messages ([1225e2b](https://github.com/gotgenes/pi-packages/commit/1225e2bcface907a0a4407aadcd744c2398edc19))
+* **pi-permission-system:** disclose resolved symlink targets in bash external-directory messages ([f9fab42](https://github.com/gotgenes/pi-packages/commit/f9fab42b758dd106e67b83a0e3c95fe6fc216687))
+
 ## [18.0.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v18.0.0...pi-permission-system-v18.0.1) (2026-06-30)
 
 

package/package.json

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

package/src/access-intent/access-path.ts

@@ -19,6 +19,9 @@ import {
  *   outside-CWD containment and infra-read checks.
  * - {@link value} returns `string` — the lexical absolute form, for display,
  *   approval patterns, decision values, and logs.
+ * - {@link resolvedAlias} returns `string | undefined` — the canonical form
+ *   only when it names a location distinct from the lexical form, for
+ *   disclosing a symlink target in a prompt or denial message.
  *
  * Construct via {@link forPath} (resolved, with optional cd-folded base) or
  * {@link forLiteral} (literal-only, for an unknown base); the constructor is
@@ -66,6 +69,19 @@ export class AccessPath {
     return this.lexical;
   }
 
+  /**
+   * The canonical (symlink-resolved) form when it names a location distinct
+   * from the lexical form — for disclosing the resolved target in a prompt or
+   * denial message. `undefined` when the path is not a symlink (canonical
+   * equals lexical) or has no canonical (literal-only / empty input).
+   */
+  resolvedAlias(): string | undefined {
+    if (!this.canonical || this.canonical === this.lexical) {
+      return undefined;
+    }
+    return this.canonical;
+  }
+
   /**
    * Build an `AccessPath` for a tool-input or bash-token path, resolved against
    * `resolveBase` (the cd-folded effective directory; defaults to `cwd`).

package/src/access-intent/bash/bash-path-resolver.ts

@@ -5,6 +5,7 @@ import {
 } from "#src/access-intent/bash/node-text";
 import type { TSNode } from "#src/access-intent/bash/parser";
 import {
+  classifyPromotedRuleCandidate,
   classifyTokenAsPathCandidate,
   classifyTokenAsRuleCandidate,
 } from "#src/access-intent/bash/token-classification";
@@ -17,6 +18,10 @@ import {
 import { normalizePathPolicyLiteral } from "#src/access-intent/path-normalization";
 import type { PathNormalizer } from "#src/path-normalizer";
 import { isSafeSystemPath } from "#src/safe-system-paths";
+import type { PathRuleTokenMatcher } from "#src/types";
+
+/** Default promotion predicate: promotes nothing (#509). */
+const NO_PROMOTION: PathRuleTokenMatcher = () => false;
 
 // ── Internal types ───────────────────────────────────────────────────────────
 
@@ -74,20 +79,29 @@ const UNKNOWN_BASE: EffectiveBase = { kind: "unknown" };
 /**
  * Resolves the filesystem paths a parsed bash program references.
  *
- * Holds a {@link PathNormalizer} (platform + cwd baked in) as its collaborator
- * and answers all platform/cwd-dependent questions through it — `cd`-base
- * folding (`isAbsolute`/`joinBase`), per-candidate resolution (`forPath`/
- * `forLiteral`/`resolveBase`), and the outside-cwd boundary decision — so no
- * walk step re-reads the platform or threads the cwd.
+ * Holds a {@link PathNormalizer} (platform + cwd baked in) as its primary
+ * collaborator and answers all platform/cwd-dependent questions through it —
+ * `cd`-base folding (`isAbsolute`/`joinBase`), per-candidate resolution
+ * (`forPath`/`forLiteral`/`resolveBase`), and the outside-cwd boundary
+ * decision — so no walk step re-reads the platform or threads the cwd.
+ *
+ * Also holds an `isPromotablePathToken` predicate (default: promotes nothing)
+ * deciding whether a bare token that fails the broad rule-candidate shape gate
+ * should still be promoted because it matches an active, specific `path` rule
+ * (#509). The resolver never sees the rules themselves — the predicate is
+ * built and owned by `PermissionManager.getPromotablePathTokenMatcher`.
  *
  * Tell-don't-ask: callers hand it a parsed tree and receive the resolved
  * {@link ResolvedBashPaths} slices in one {@link resolve} call; the AST walk,
  * the `cd`-folding state, and the intermediate path candidates stay private.
  * One instance per parse ({@link BashProgram.parse} constructs it with the
- * session normalizer).
+ * session normalizer and promotion predicate).
  */
 export class BashPathResolver {
-  constructor(private readonly normalizer: PathNormalizer) {}
+  constructor(
+    private readonly normalizer: PathNormalizer,
+    private readonly isPromotablePathToken: PathRuleTokenMatcher = NO_PROMOTION,
+  ) {}
 
   /**
    * Resolve a parsed bash program's path references into its external-path and
@@ -387,8 +401,12 @@ export class BashPathResolver {
    * policy lookup values.
    *
    * Filters candidates through the broad path classifier
-   * (`classifyTokenAsRuleCandidate`) and pairs each qualifying token with its
-   * set of policy values (absolute + project-relative + raw).
+   * (`classifyTokenAsRuleCandidate`), falling back to the rule-driven promoted
+   * classifier (`classifyPromotedRuleCandidate`, #509) for a bare token the
+   * broad classifier rejects for shape — promoted only when the injected
+   * `isPromotablePathToken` predicate matches an active, specific `path` rule.
+   * Pairs each qualifying token with its set of policy values (absolute +
+   * project-relative + raw).
    * A token after a non-literal `cd` keeps only its literal value so no
    * spurious absolute rule can match (#393).
    */
@@ -399,7 +417,9 @@ export class BashPathResolver {
     const result: BashPathRuleCandidate[] = [];
 
     for (const { token, base } of candidates) {
-      const candidate = classifyTokenAsRuleCandidate(token);
+      const candidate =
+        classifyTokenAsRuleCandidate(token) ??
+        classifyPromotedRuleCandidate(token, this.isPromotablePathToken);
       if (!candidate) continue;
 
       const path = this.buildRuleCandidatePath(candidate, base);

package/src/access-intent/bash/program.ts

@@ -9,6 +9,7 @@ import {
 } from "#src/access-intent/bash/command-enumeration";
 import { getParser } from "#src/access-intent/bash/parser";
 import type { PathNormalizer } from "#src/path-normalizer";
+import type { PathRuleTokenMatcher } from "#src/types";
 
 export type { BashCommand, BashPathRuleCandidate };
 
@@ -37,10 +38,17 @@ export class BashProgram {
    * through the injected {@link PathNormalizer} (platform + cwd baked in).
    * Heredoc bodies, comments, and other non-argument content are skipped. An
    * unparseable command yields an empty program.
+   *
+   * `isPromotablePathToken`, when supplied, promotes a bare filename token
+   * (e.g. `id_rsa`) into `pathRuleCandidates()` when it matches an active,
+   * specific `path` deny/ask rule (#509). Defaults to promoting nothing, so
+   * callers that only read `externalPaths()` (e.g. `bash-path-extractor.ts`)
+   * are unaffected.
    */
   static async parse(
     command: string,
     normalizer: PathNormalizer,
+    isPromotablePathToken?: PathRuleTokenMatcher,
   ): Promise<BashProgram> {
     const parser = await getParser();
     const tree = parser.parse(command);
@@ -49,6 +57,7 @@ export class BashProgram {
     try {
       const { externalPaths, ruleCandidates } = new BashPathResolver(
         normalizer,
+        isPromotablePathToken,
       ).resolve(tree.rootNode);
       return new BashProgram(
         collectCommands(tree.rootNode),

package/src/access-intent/bash/token-classification.ts

@@ -1,20 +1,25 @@
 /**
  * Pure, synchronous token-classification helpers for bash path extraction.
  *
- * Exports two classifiers consumed by `bash-path-resolver.ts`:
+ * Exports three classifiers consumed by `bash-path-resolver.ts`:
  *   - `classifyTokenAsPathCandidate` — strict gate for the external-directory guard.
  *   - `classifyTokenAsRuleCandidate` — broader gate for cross-cutting `path` rules.
+ *   - `classifyPromotedRuleCandidate` — rule-driven promotion of a bare filename
+ *     (e.g. `id_rsa`) that `classifyTokenAsRuleCandidate` rejects for shape, but
+ *     which matches an active, specific (non-`*`) `path` deny/ask rule (#509).
  *
- * Both classifiers share the private `rejectNonPathToken` predicate that captures
- * the seven rejection cases common to both (the production clone this module was
- * extracted to eliminate).
+ * All three classifiers share the private `rejectNonPathToken` predicate that
+ * captures the seven rejection cases common to them (the production clone this
+ * module was extracted to eliminate).
  *
- * Both classifiers recognize Windows drive-letter absolute paths (`C:/…`, `C:\…`)
- * unconditionally on all platforms. On POSIX the token resolves as a real in-CWD
- * relative path and is gated by the `path` surface; on Windows the `PathNormalizer`
- * routes it through the absolute-path branch. Shape recognition is platform-independent
- * string matching; the platform-sensitive absoluteness decision belongs to `PathNormalizer`.
+ * Both `classifyTokenAsPathCandidate` and `classifyTokenAsRuleCandidate` recognize
+ * Windows drive-letter absolute paths (`C:/…`, `C:\…`) unconditionally on all
+ * platforms. On POSIX the token resolves as a real in-CWD relative path and is
+ * gated by the `path` surface; on Windows the `PathNormalizer` routes it through
+ * the absolute-path branch. Shape recognition is platform-independent string
+ * matching; the platform-sensitive absoluteness decision belongs to `PathNormalizer`.
  */
+import type { PathRuleTokenMatcher } from "#src/types";
 
 // ── Public classifiers ─────────────────────────────────────────────────────
 
@@ -70,6 +75,31 @@ export function classifyTokenAsRuleCandidate(token: string): string | null {
   return null;
 }
 
+/**
+ * Rule-driven promotion classifier for bare filenames (#509).
+ *
+ * A bare token (`id_rsa`) has none of the shapes `classifyTokenAsRuleCandidate`
+ * accepts, so it is dropped before rule evaluation by default — most bash
+ * argument tokens are not file paths (subcommands, branch names, search
+ * patterns). This classifier promotes a bare token into the rule-candidate
+ * surface only when the caller-supplied `isPromotable` predicate says it
+ * matches an active, specific `path` deny/ask rule, closing the bypass without
+ * treating every bare argument as a path.
+ *
+ * Still runs the shared `rejectNonPathToken` prelude first, so a flag,
+ * env-assignment, URL, `@scope` token, or regex-shaped token is never
+ * promoted even if it happens to match a configured pattern.
+ *
+ * Returns the raw token string if it qualifies, or `null` to skip.
+ */
+export function classifyPromotedRuleCandidate(
+  token: string,
+  isPromotable: PathRuleTokenMatcher,
+): string | null {
+  if (rejectNonPathToken(token)) return null;
+  return isPromotable(token) ? token : null;
+}
+
 // ── Private rejection predicate ────────────────────────────────────────────
 
 /**

package/src/denial-messages.ts

@@ -5,6 +5,21 @@ import type { BashCommandContext, PermissionCheckResult } from "./types";
 
 export const EXTENSION_TAG = `[${EXTENSION_ID}]`;
 
+// ── External-path resolved-target disclosure ────────────────────────────────
+
+/** A displayed external path paired with its resolved target, when distinct. */
+export interface ExternalPathDisclosure {
+  /** The path as displayed (typed for tools, lexical-absolute for bash). */
+  path: string;
+  /** The canonical symlink-resolved target; present only when it differs. */
+  resolvedPath?: string;
+}
+
+/** ` (resolves to '<canonical>')` when a distinct target exists, else `""`. */
+export function resolvesToSuffix(resolvedPath?: string): string {
+  return resolvedPath ? ` (resolves to '${resolvedPath}')` : "";
+}
+
 // ── Denial context discriminated union ─────────────────────────────────────
 
 export type DenialContext =
@@ -24,13 +39,14 @@ export type DenialContext =
       kind: "external_directory";
       toolName: string;
       pathValue: string;
+      resolvedPath?: string;
       cwd: string;
       agentName?: string;
     }
   | {
       kind: "bash_external_directory";
       command: string;
-      externalPaths: string[];
+      externalPaths: ExternalPathDisclosure[];
       cwd: string;
       agentName?: string;
     }
@@ -89,9 +105,9 @@ function buildDenyBody(ctx: DenialContext): string {
     case "path":
       return `${subject(ctx.agentName)} is not permitted to access path '${ctx.pathValue}' via tool '${ctx.toolName}'.`;
     case "external_directory":
-      return `${subject(ctx.agentName)} is not permitted to run tool '${ctx.toolName}' for path '${ctx.pathValue}' outside working directory '${ctx.cwd}'.`;
+      return `${subject(ctx.agentName)} is not permitted to run tool '${ctx.toolName}' for path '${ctx.pathValue}'${resolvesToSuffix(ctx.resolvedPath)} outside working directory '${ctx.cwd}'.`;
     case "bash_external_directory":
-      return `${subject(ctx.agentName)} is not permitted to run bash command '${ctx.command}' which references path(s) outside working directory '${ctx.cwd}': ${ctx.externalPaths.join(", ")}.`;
+      return `${subject(ctx.agentName)} is not permitted to run bash command '${ctx.command}' which references path(s) outside working directory '${ctx.cwd}': ${formatExternalPathList(ctx.externalPaths)}.`;
     case "bash_path":
       return `${subject(ctx.agentName)} is not permitted to access path '${ctx.pathValue}' via tool 'bash'.`;
     case "skill_read":
@@ -185,7 +201,7 @@ function buildUnavailableBody(ctx: DenialContext): string {
     case "path":
       return `Accessing '${ctx.pathValue}' requires approval, but no interactive UI is available.`;
     case "external_directory":
-      return `Accessing '${ctx.pathValue}' outside the working directory requires approval, but no interactive UI is available.`;
+      return `Accessing '${ctx.pathValue}'${resolvesToSuffix(ctx.resolvedPath)} outside the working directory requires approval, but no interactive UI is available.`;
     case "bash_external_directory":
       return `Bash command '${ctx.command}' references path(s) outside the working directory and requires approval, but no interactive UI is available.`;
     case "bash_path":
@@ -215,7 +231,7 @@ function buildUserDeniedBody(
     case "path":
       return `User denied access to path '${ctx.pathValue}'.${reasonSuffix(denialReason)}`;
     case "external_directory":
-      return `User denied external directory access for tool '${ctx.toolName}' path '${ctx.pathValue}'.${reasonSuffix(denialReason)}`;
+      return `User denied external directory access for tool '${ctx.toolName}' path '${ctx.pathValue}'${resolvesToSuffix(ctx.resolvedPath)}.${reasonSuffix(denialReason)}`;
     case "bash_external_directory":
       return `User denied external directory access for bash command '${ctx.command}'.${reasonSuffix(denialReason)}`;
     case "bash_path":
@@ -230,3 +246,10 @@ function buildUserDeniedBody(
 function isMcpCheck(check: PermissionCheckResult): boolean {
   return (check.source === "mcp" || check.toolName === "mcp") && !!check.target;
 }
+
+/** Render an external-path disclosure list for the bash deny body's path clause. */
+function formatExternalPathList(paths: ExternalPathDisclosure[]): string {
+  return paths
+    .map(({ path, resolvedPath }) => `${path}${resolvesToSuffix(resolvedPath)}`)
+    .join(", ");
+}

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

@@ -67,9 +67,14 @@ export function describeBashExternalDirectoryGate(
   // config-level "deny" is preserved (not downgraded to the catch-all "ask").
   const preCheck = worstCheck ?? uncoveredEntries[0].check;
 
+  const disclosures = uncoveredEntries.map(({ path }) => ({
+    path: path.value(),
+    resolvedPath: path.resolvedAlias(),
+  }));
+
   const bashExtMessage = formatBashExternalDirectoryAskPrompt(
     command,
-    uncoveredPaths,
+    disclosures,
     tcc.cwd,
     tcc.agentName ?? undefined,
   );
@@ -82,7 +87,7 @@ export function describeBashExternalDirectoryGate(
     denialContext: {
       kind: "bash_external_directory",
       command,
-      externalPaths: uncoveredPaths,
+      externalPaths: disclosures,
       cwd: tcc.cwd,
       agentName: tcc.agentName ?? undefined,
     },

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

@@ -1,20 +1,28 @@
+import {
+  type ExternalPathDisclosure,
+  resolvesToSuffix,
+} from "#src/denial-messages";
+
 export function formatExternalDirectoryAskPrompt(
   toolName: string,
   pathValue: string,
+  resolvedPath: string | undefined,
   cwd: string,
   agentName?: string,
 ): string {
   const subject = agentName ? `Agent '${agentName}'` : "Current agent";
-  return `${subject} requested tool '${toolName}' for path '${pathValue}' outside working directory '${cwd}'. Allow this external directory access?`;
+  return `${subject} requested tool '${toolName}' for path '${pathValue}'${resolvesToSuffix(resolvedPath)} outside working directory '${cwd}'. Allow this external directory access?`;
 }
 
 export function formatBashExternalDirectoryAskPrompt(
   command: string,
-  externalPaths: string[],
+  externalPaths: ExternalPathDisclosure[],
   cwd: string,
   agentName?: string,
 ): string {
   const subject = agentName ? `Agent '${agentName}'` : "Current agent";
-  const pathList = externalPaths.join(", ");
+  const pathList = externalPaths
+    .map(({ path, resolvedPath }) => `${path}${resolvesToSuffix(resolvedPath)}`)
+    .join(", ");
   return `${subject} requested bash command '${command}' which references path(s) outside working directory '${cwd}': ${pathList}. Allow this external directory access?`;
 }

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

@@ -67,9 +67,11 @@ export function describeExternalDirectoryGate(
   }
 
   // ── Build descriptor for permission check ───────────────────────────────
+  const resolvedAlias = accessPath.resolvedAlias();
   const extDirMessage = formatExternalDirectoryAskPrompt(
     tcc.toolName,
     externalDirectoryPath,
+    resolvedAlias,
     tcc.cwd,
     tcc.agentName ?? undefined,
   );
@@ -90,6 +92,7 @@ export function describeExternalDirectoryGate(
       kind: "external_directory",
       toolName: tcc.toolName,
       pathValue: externalDirectoryPath,
+      resolvedPath: resolvedAlias,
       cwd: tcc.cwd,
       agentName: tcc.agentName ?? undefined,
     },

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

@@ -10,7 +10,7 @@ import {
   ToolPreviewFormatter,
   type ToolPreviewFormatterOptions,
 } from "#src/tool-preview-formatter";
-import type { PermissionCheckResult } from "#src/types";
+import type { PathRuleTokenMatcher, PermissionCheckResult } from "#src/types";
 import { getNonEmptyString, toRecord } from "#src/value-guards";
 import { resolveBashCommandCheck } from "./bash-command";
 import { describeBashExternalDirectoryGate } from "./bash-external-directory";
@@ -42,6 +42,11 @@ export interface ToolCallGateInputs {
   getToolPreviewLimits(): ToolPreviewFormatterOptions;
   /** The session's path normalizer (platform + cwd baked in). */
   getPathNormalizer(): PathNormalizer;
+  /**
+   * Predicate deciding whether a bare bash token should be promoted into the
+   * `path` rule-candidate surface (#509), scoped to the given agent.
+   */
+  getPromotablePathTokenMatcher(agentName?: string): PathRuleTokenMatcher;
 }
 
 /**
@@ -73,7 +78,13 @@ export class ToolCallGatePipeline {
     const normalizer = this.inputs.getPathNormalizer();
     const bashProgram =
       tcc.toolName === "bash" && command
-        ? await BashProgram.parse(command, normalizer)
+        ? await BashProgram.parse(
+            command,
+            normalizer,
+            this.inputs.getPromotablePathTokenMatcher(
+              tcc.agentName ?? undefined,
+            ),
+          )
         : null;
 
     const formatter = new ToolPreviewFormatter(

package/src/permission-manager.ts

@@ -15,7 +15,12 @@ import {
   type ResolvedPolicyPaths,
 } from "./policy-loader";
 import type { Rule, RuleOrigin, Ruleset } from "./rule";
-import { evaluate, evaluateAnyValue, evaluateFirst } from "./rule";
+import {
+  evaluate,
+  evaluateAnyValue,
+  evaluateFirst,
+  pathMatchOptions,
+} from "./rule";
 import { mergeScopesWithOrigins } from "./scope-merge";
 import {
   composeRuleset,
@@ -24,10 +29,12 @@ import {
 } from "./synthesize";
 import type {
   FlatPermissionConfig,
+  PathRuleTokenMatcher,
   PermissionCheckResult,
   PermissionState,
 } from "./types";
 import { isPermissionState } from "./value-guards";
+import { wildcardMatch } from "./wildcard-matcher";
 
 const BUILT_IN_TOOL_PERMISSION_NAMES = new Set([
   "bash",
@@ -43,6 +50,9 @@ const SPECIAL_PERMISSION_KEYS = new Set(["external_directory", "path"]);
 /** Universal fallback when permission["*"] is absent from all scopes. */
 const DEFAULT_UNIVERSAL_FALLBACK: PermissionState = "ask";
 
+/** Promotion predicate matching no token — the no-`path`-rules default (#509). */
+const NO_PROMOTION: PathRuleTokenMatcher = () => false;
+
 type FileCacheEntry<TValue> = {
   stamp: string;
   value: TValue;
@@ -76,6 +86,15 @@ export interface ScopedPermissionManager {
   ): PermissionCheckResult;
   getToolPermission(toolName: string, agentName?: string): PermissionState;
   getConfigIssues(agentName?: string): string[];
+  /**
+   * Build a predicate deciding whether a bare bash token should be promoted
+   * into the `path` rule-candidate surface (#509).
+   *
+   * Matches against specific (non-`*`) `path`-surface config rules whose
+   * action is `deny` or `ask` — an allow rule never gates, and `"*"` would
+   * promote every bare bash argument.
+   */
+  getPromotablePathTokenMatcher(agentName?: string): PathRuleTokenMatcher;
 }
 
 export interface PermissionManagerOptions extends PolicyLoaderOptions {
@@ -211,6 +230,37 @@ export class PermissionManager implements ScopedPermissionManager {
     return composedRules.filter((r) => r.layer === "config");
   }
 
+  /**
+   * Build a predicate deciding whether a bare bash token should be promoted
+   * into the `path` rule-candidate surface (#509).
+   *
+   * Filters the composed config ruleset to specific (non-`*`) `path`-surface
+   * deny/ask patterns, then returns a closure matching a token against them
+   * with the platform-correct fold (Windows case-and-separator matching, same
+   * as {@link pathMatchOptions} applies for evaluation) so promotion agrees
+   * with the later `path`-surface decision.
+   *
+   * Returns a matcher rejecting every token when no such rule exists — the
+   * default-config case is unaffected by promotion.
+   */
+  getPromotablePathTokenMatcher(agentName?: string): PathRuleTokenMatcher {
+    const { composedRules } = this.resolvePermissions(agentName);
+    const patterns = composedRules
+      .filter(
+        (r) =>
+          r.layer === "config" &&
+          r.surface === "path" &&
+          r.pattern !== "*" &&
+          r.action !== "allow",
+      )
+      .map((r) => r.pattern);
+    if (patterns.length === 0) return NO_PROMOTION;
+
+    const matchOptions = pathMatchOptions("path", this.platform);
+    return (token) =>
+      patterns.some((pattern) => wildcardMatch(pattern, token, matchOptions));
+  }
+
   /**
    * Get the tool-level permission state for a tool, without considering
    * command-level rules. Used for tool injection decisions.

package/src/permission-session.ts

@@ -19,6 +19,7 @@ import {
   resolveToolPreviewLimits,
   type ToolPreviewFormatterOptions,
 } from "./tool-preview-formatter";
+import type { PathRuleTokenMatcher } from "./types";
 
 /**
  * Encapsulates all mutable session state and exposes operations instead of
@@ -214,4 +215,15 @@ export class PermissionSession implements ToolCallGateInputs {
   getPathNormalizer(): PathNormalizer {
     return this.pathNormalizer;
   }
+
+  /**
+   * Predicate deciding whether a bare bash token should be promoted into the
+   * `path` rule-candidate surface (#509), scoped to the given agent.
+   *
+   * Straight delegate to `permissionManager.getPromotablePathTokenMatcher` —
+   * the manager owns the composed ruleset and the platform-correct match.
+   */
+  getPromotablePathTokenMatcher(agentName?: string): PathRuleTokenMatcher {
+    return this.permissionManager.getPromotablePathTokenMatcher(agentName);
+  }
 }

package/src/rule.ts

@@ -74,7 +74,7 @@ export function evaluate(
  * pattern→value match (case and separators) so mixed-case / forward-slash
  * overrides still match. The surface→surface match stays exact.
  */
-function pathMatchOptions(
+export function pathMatchOptions(
   surface: string,
   platform: NodeJS.Platform,
 ): { caseInsensitive: true; windowsSeparators: true } | undefined {

package/src/types.ts

@@ -16,6 +16,17 @@ export interface DenyWithReason {
 /** A pattern value: a PermissionState string OR a DenyWithReason object. */
 export type PatternValue = PermissionState | DenyWithReason;
 
+/**
+ * Predicate deciding whether a bare bash token should be promoted into the
+ * `path` rule-candidate surface.
+ *
+ * Built by `PermissionManager.getPromotablePathTokenMatcher` from the
+ * composed config ruleset (specific, non-`*` `path` deny/ask patterns) and
+ * threaded through to `BashPathResolver` so promotion policy stays in the
+ * manager while the bash layer only asks the predicate.
+ */
+export type PathRuleTokenMatcher = (token: string) => boolean;
+
 /**
  * The on-disk permission shape inside the `"permission"` key.
  * A surface value is a PermissionState string (shorthand for `{ "*": action }`)

package/test/access-intent/access-path.test.ts

@@ -191,6 +191,67 @@ describe("AccessPath.forPath", () => {
   });
 });
 
+describe("resolvedAlias()", () => {
+  const cwd = "/projects/my-app";
+
+  beforeEach(() => {
+    realpathSync.mockReset();
+    realpathSync.mockImplementation((p: string) => p);
+  });
+
+  test("returns the canonical form when a symlink resolves elsewhere", () => {
+    realpathSync.mockImplementation((p: string) =>
+      p === "/projects/my-app/demo-symlink-passwd" ? "/etc/passwd" : p,
+    );
+    expect(
+      AccessPath.forPath("demo-symlink-passwd", {
+        cwd,
+        platform: "linux",
+      }).resolvedAlias(),
+    ).toBe("/etc/passwd");
+  });
+
+  test("returns undefined when the path has no symlinks (canonical equals lexical)", () => {
+    expect(
+      AccessPath.forPath("/etc/hosts", {
+        cwd,
+        platform: "linux",
+      }).resolvedAlias(),
+    ).toBeUndefined();
+  });
+
+  test("returns undefined for a literal-only path (no canonical)", () => {
+    expect(AccessPath.forLiteral("foo.ts").resolvedAlias()).toBeUndefined();
+  });
+
+  test("returns undefined for empty input", () => {
+    expect(
+      AccessPath.forPath("", { cwd, platform: "linux" }).resolvedAlias(),
+    ).toBeUndefined();
+  });
+
+  test("win32: returns the lowercased canonical form for a real symlink target", () => {
+    realpathSync.mockImplementation((p: string) =>
+      p === "c:\\projects\\app\\link" ? "C:\\Real\\App" : p,
+    );
+    expect(
+      AccessPath.forPath("link", {
+        cwd: "C:\\Projects\\App",
+        platform: "win32",
+      }).resolvedAlias(),
+    ).toBe("c:\\real\\app");
+  });
+
+  test("win32: returns undefined for a case-only difference (both forms lowercased)", () => {
+    expect(
+      AccessPath.forPath("src\\foo.ts", {
+        cwd: "C:\\Projects\\App",
+        platform: "win32",
+      }).resolvedAlias(),
+    ).toBeUndefined();
+  });
+});
+
 describe("AccessPath.forLiteral", () => {
   beforeEach(() => {
     realpathSync.mockReset();