@gotgenes/pi-permission-system 18.0.2 → 18.1.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@ 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)
 
 

package/package.json

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

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/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/bash/program.test.ts

@@ -91,6 +91,63 @@ describe("BashProgram", () => {
       expect(fileCandidate?.path.matchValues()).toEqual(["src/foo.ts"]);
       expect(fileCandidate?.path.boundaryValue()).toBe("");
     });
+
+    describe("rule-driven bare-token promotion (#509)", () => {
+      it("promotes a bare token when the matcher says it is promotable", async () => {
+        const isPromotable = (token: string): boolean => token === "id_rsa";
+        const program = await BashProgram.parse(
+          "cat id_rsa",
+          normalizer,
+          isPromotable,
+        );
+        const candidates = program.pathRuleCandidates();
+        expect(candidates.map(({ token }) => token)).toEqual(["id_rsa"]);
+        expect(candidates[0].path.matchValues()).toEqual([
+          "/projects/my-app/id_rsa",
+          "id_rsa",
+        ]);
+      });
+
+      it("does not promote a bare token the matcher rejects", async () => {
+        const isPromotable = (token: string): boolean => token === "id_rsa";
+        const program = await BashProgram.parse(
+          "git status",
+          normalizer,
+          isPromotable,
+        );
+        expect(program.pathRuleCandidates()).toHaveLength(0);
+      });
+
+      it("does not promote any bare token with the default no-op matcher", async () => {
+        const program = await BashProgram.parse("cat id_rsa", normalizer);
+        expect(program.pathRuleCandidates()).toHaveLength(0);
+      });
+
+      it("keeps a promoted token literal-only after an unknown cd (#393)", async () => {
+        const isPromotable = (token: string): boolean => token === "id_rsa";
+        const program = await BashProgram.parse(
+          'cd "$DIR" && cat id_rsa',
+          normalizer,
+          isPromotable,
+        );
+        const candidate = program
+          .pathRuleCandidates()
+          .find((c) => c.token === "id_rsa");
+        expect(candidate?.path.matchValues()).toEqual(["id_rsa"]);
+      });
+
+      it("does not double-promote a token the shape gate already accepts", async () => {
+        // ./id_rsa already passes classifyTokenAsRuleCandidate; the promoted
+        // fallback must not run (and must not duplicate the candidate).
+        const isPromotable = (): boolean => true;
+        const program = await BashProgram.parse(
+          "cat ./id_rsa",
+          normalizer,
+          isPromotable,
+        );
+        expect(program.pathRuleCandidates()).toHaveLength(1);
+      });
+    });
   });
 
   describe("externalPaths", () => {

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

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "vitest";
 
 import {
+  classifyPromotedRuleCandidate,
   classifyTokenAsPathCandidate,
   classifyTokenAsRuleCandidate,
 } from "#src/access-intent/bash/token-classification";
@@ -314,3 +315,49 @@ describe("classifyTokenAsRuleCandidate", () => {
     }
   });
 });
+
+describe("classifyPromotedRuleCandidate", () => {
+  test("shape-eligible bare token promoted when predicate returns true", () => {
+    expect(classifyPromotedRuleCandidate("id_rsa", () => true)).toBe("id_rsa");
+  });
+
+  test("shape-eligible bare token rejected when predicate returns false", () => {
+    expect(classifyPromotedRuleCandidate("id_rsa", () => false)).toBeNull();
+  });
+
+  test("predicate receives the raw token", () => {
+    const isPromotable = (token: string): boolean => token === "key.pem";
+    expect(classifyPromotedRuleCandidate("key.pem", isPromotable)).toBe(
+      "key.pem",
+    );
+    expect(classifyPromotedRuleCandidate("other.pem", isPromotable)).toBeNull();
+  });
+
+  describe("shared rejection still applies regardless of the predicate", () => {
+    test("flag (leading dash) → null", () => {
+      expect(classifyPromotedRuleCandidate("-r", () => true)).toBeNull();
+    });
+
+    test("env assignment → null", () => {
+      expect(classifyPromotedRuleCandidate("FOO=/bar", () => true)).toBeNull();
+    });
+
+    test("URL → null", () => {
+      expect(
+        classifyPromotedRuleCandidate("https://example.com", () => true),
+      ).toBeNull();
+    });
+
+    test("@scope/package → null", () => {
+      expect(classifyPromotedRuleCandidate("@foo/bar", () => true)).toBeNull();
+    });
+
+    test("regex metacharacters → null", () => {
+      expect(classifyPromotedRuleCandidate("foo.*", () => true)).toBeNull();
+    });
+
+    test("empty string → null", () => {
+      expect(classifyPromotedRuleCandidate("", () => true)).toBeNull();
+    });
+  });
+});

package/test/composition-root.test.ts

@@ -501,6 +501,79 @@ describe("service path queries evaluate the supplied path (#503)", () => {
   });
 });
 
+describe("bash bare-filename path gating (#509)", () => {
+  // Before #509 a bash bare-filename argument (`cat id_rsa`) bypassed the
+  // `path` surface entirely: the broad classifier only accepted tokens
+  // starting with `.`, containing `/`, containing `..`, or a Windows
+  // drive-letter absolute path. The same file accessed via a prefixed path
+  // (`cat ./id_rsa`) or the `read` tool was already gated. Rule-driven
+  // promotion closes the gap for a bare token matching a specific, non-`*`
+  // `path` deny/ask rule — the literal repro from the issue.
+
+  async function fireBashToolCall(
+    pi: ReturnType<typeof makeFakePi>,
+    ctx: unknown,
+    command: string,
+  ): Promise<{ block?: true; reason?: string }> {
+    return (await pi.fire(
+      "tool_call",
+      { name: "bash", input: { command }, toolCallId: "tc-1" },
+      ctx,
+    )) as { block?: true; reason?: string };
+  }
+
+  it("denies a bare filename matching a specific path deny rule", async () => {
+    const cwd = mkdtempSync(join(tmpdir(), "pi-perm-bare-token-cwd-"));
+    writeGlobalConfig({
+      permission: { "*": "allow", path: { id_rsa: "deny" } },
+    });
+
+    const pi = makeFakePi({ events: createEventBus() });
+    piPermissionSystemExtension(pi as unknown as ExtensionAPI);
+    const ctx = makeChildCtx(cwd, "bare-token-session-deny");
+    await fireSessionStart(pi, ctx);
+
+    const result = await fireBashToolCall(pi, ctx, "cat id_rsa");
+    expect(result.block).toBe(true);
+
+    rmSync(cwd, { recursive: true, force: true });
+  });
+
+  it("denies a bare filename matching a wildcard path deny rule", async () => {
+    const cwd = mkdtempSync(join(tmpdir(), "pi-perm-bare-token-cwd-"));
+    writeGlobalConfig({
+      permission: { "*": "allow", path: { "*.pem": "deny" } },
+    });
+
+    const pi = makeFakePi({ events: createEventBus() });
+    piPermissionSystemExtension(pi as unknown as ExtensionAPI);
+    const ctx = makeChildCtx(cwd, "bare-token-session-wildcard");
+    await fireSessionStart(pi, ctx);
+
+    const result = await fireBashToolCall(pi, ctx, "cat key.pem");
+    expect(result.block).toBe(true);
+
+    rmSync(cwd, { recursive: true, force: true });
+  });
+
+  it("leaves a bare token that does not match any path rule unaffected", async () => {
+    const cwd = mkdtempSync(join(tmpdir(), "pi-perm-bare-token-cwd-"));
+    writeGlobalConfig({
+      permission: { "*": "allow", path: { id_rsa: "deny" } },
+    });
+
+    const pi = makeFakePi({ events: createEventBus() });
+    piPermissionSystemExtension(pi as unknown as ExtensionAPI);
+    const ctx = makeChildCtx(cwd, "bare-token-session-unaffected");
+    await fireSessionStart(pi, ctx);
+
+    const result = await fireBashToolCall(pi, ctx, "git status");
+    expect(result.block).toBeUndefined();
+
+    rmSync(cwd, { recursive: true, force: true });
+  });
+});
+
 describe("multi-instance global service interplay", () => {
   // The fix (#302) scopes the process-global service slot to the publishing
   // instance. The parent publishes at its session_start; an in-process child

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

@@ -186,6 +186,7 @@ describe("ToolCallGatePipeline", () => {
       expect(mockBashProgramParse).toHaveBeenCalledWith(
         "echo hello",
         expect.any(PathNormalizer),
+        expect.any(Function),
       );
     });
 
@@ -202,6 +203,31 @@ describe("ToolCallGatePipeline", () => {
 
       expect(mockBashProgramParse).not.toHaveBeenCalled();
     });
+
+    it("passes the session's promotable path-token matcher into BashProgram.parse (#509)", async () => {
+      const resolver = makeResolver(makeCheckResult());
+      const isPromotable = vi.fn((token: string) => token === "id_rsa");
+      const getPromotablePathTokenMatcher = vi.fn(() => isPromotable);
+      const inputs = makeGateInputs({ getPromotablePathTokenMatcher });
+      const { runner } = makeGateRunner();
+      const pipeline = new ToolCallGatePipeline(resolver, inputs);
+
+      await pipeline.evaluate(
+        makeTcc({
+          toolName: "bash",
+          input: { command: "cat id_rsa" },
+          agentName: "my-agent",
+        }),
+        runner,
+      );
+
+      expect(getPromotablePathTokenMatcher).toHaveBeenCalledWith("my-agent");
+      expect(mockBashProgramParse).toHaveBeenCalledWith(
+        "cat id_rsa",
+        expect.any(PathNormalizer),
+        isPromotable,
+      );
+    });
   });
 
   // ── customExtractors threading (#352) ────────────────────────────────────

package/test/helpers/gate-fixtures.ts

@@ -15,7 +15,7 @@ import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import type { SessionApprovalRecorder } from "#src/session-approval-recorder";
 import type { SkillPromptEntry } from "#src/skill-prompt-sanitizer";
 import type { ToolPreviewFormatterOptions } from "#src/tool-preview-formatter";
-import type { PermissionCheckResult } from "#src/types";
+import type { PathRuleTokenMatcher, PermissionCheckResult } from "#src/types";
 
 import { makeCheckResult } from "#test/helpers/handler-fixtures";
 
@@ -255,6 +255,9 @@ export function makeGateInputs(
     getInfrastructureReadDirs?: () => string[];
     getToolPreviewLimits?: () => ToolPreviewFormatterOptions;
     getPathNormalizer?: () => PathNormalizer;
+    getPromotablePathTokenMatcher?: (
+      agentName?: string,
+    ) => PathRuleTokenMatcher;
   } = {},
 ): ToolCallGateInputs {
   return {
@@ -275,6 +278,9 @@ export function makeGateInputs(
       vi.fn<() => PathNormalizer>(
         () => new PathNormalizer(process.platform, "/test/cwd"),
       ),
+    getPromotablePathTokenMatcher:
+      overrides.getPromotablePathTokenMatcher ??
+      vi.fn<(agentName?: string) => PathRuleTokenMatcher>(() => () => false),
   };
 }
 

package/test/helpers/session-fixtures.ts

@@ -25,7 +25,11 @@ import type { PromptingGatewayLifecycle } from "#src/prompting-gateway";
 import type { Ruleset } from "#src/rule";
 import type { SessionLogger } from "#src/session-logger";
 import { SessionRules } from "#src/session-rules";
-import type { PermissionCheckResult, PermissionState } from "#src/types";
+import type {
+  PathRuleTokenMatcher,
+  PermissionCheckResult,
+  PermissionState,
+} from "#src/types";
 
 // ── Per-collaborator fake factories ────────────────────────────────────────
 
@@ -105,6 +109,9 @@ export function makeFakePermissionManager() {
       .fn<(toolName: string, agentName?: string) => PermissionState>()
       .mockReturnValue("allow"),
     getConfigIssues: vi.fn((): string[] => []),
+    getPromotablePathTokenMatcher: vi
+      .fn<(agentName?: string) => PathRuleTokenMatcher>()
+      .mockReturnValue(() => false),
   };
 }
 

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

@@ -1096,6 +1096,87 @@ describe("PermissionManager with in-memory PolicyLoader", () => {
       ).toBe(true);
     });
   });
+
+  describe("getPromotablePathTokenMatcher (#509)", () => {
+    it("matches a bare token against a specific deny pattern", () => {
+      const manager = makeInMemoryManager({
+        global: { permission: { path: { id_rsa: "deny" } } },
+      });
+      const isPromotable = manager.getPromotablePathTokenMatcher();
+      expect(isPromotable("id_rsa")).toBe(true);
+      expect(isPromotable("other_file")).toBe(false);
+    });
+
+    it("matches a bare token against a specific ask wildcard pattern", () => {
+      const manager = makeInMemoryManager({
+        global: { permission: { path: { "*.pem": "ask" } } },
+      });
+      const isPromotable = manager.getPromotablePathTokenMatcher();
+      expect(isPromotable("key.pem")).toBe(true);
+      expect(isPromotable("key.txt")).toBe(false);
+    });
+
+    it("does not match against the universal '*' path pattern", () => {
+      const manager = makeInMemoryManager({
+        global: { permission: { path: { "*": "ask" } } },
+      });
+      const isPromotable = manager.getPromotablePathTokenMatcher();
+      expect(isPromotable("anything")).toBe(false);
+      expect(isPromotable("status")).toBe(false);
+    });
+
+    it("does not match against an allow-only path pattern", () => {
+      const manager = makeInMemoryManager({
+        global: { permission: { path: { id_rsa: "allow" } } },
+      });
+      const isPromotable = manager.getPromotablePathTokenMatcher();
+      expect(isPromotable("id_rsa")).toBe(false);
+    });
+
+    it("returns a no-op matcher when no path rules exist", () => {
+      const manager = makeInMemoryManager({
+        global: { permission: { read: "allow" } },
+      });
+      const isPromotable = manager.getPromotablePathTokenMatcher();
+      expect(isPromotable("id_rsa")).toBe(false);
+      expect(isPromotable("anything")).toBe(false);
+    });
+
+    it("folds case on an injected win32 platform", () => {
+      const manager = new PermissionManager({
+        policyLoader: createInMemoryPolicyLoader({
+          global: { permission: { path: { id_rsa: "deny" } } },
+        }),
+        platform: "win32",
+      });
+      const isPromotable = manager.getPromotablePathTokenMatcher();
+      expect(isPromotable("ID_RSA")).toBe(true);
+    });
+
+    it("stays case-sensitive on a POSIX platform", () => {
+      const manager = new PermissionManager({
+        policyLoader: createInMemoryPolicyLoader({
+          global: { permission: { path: { id_rsa: "deny" } } },
+        }),
+        platform: "linux",
+      });
+      const isPromotable = manager.getPromotablePathTokenMatcher();
+      expect(isPromotable("ID_RSA")).toBe(false);
+    });
+
+    it("scopes to the requested agent's composed rules", () => {
+      const manager = makeInMemoryManager({
+        global: { permission: { path: { id_rsa: "deny" } } },
+        agent: {
+          coder: { permission: { path: { "secret.key": "deny" } } },
+        },
+      });
+      const globalMatcher = manager.getPromotablePathTokenMatcher();
+      const agentMatcher = manager.getPromotablePathTokenMatcher("coder");
+      expect(globalMatcher("secret.key")).toBe(false);
+      expect(agentMatcher("secret.key")).toBe(true);
+    });
+  });
 });
 
 // ---------------------------------------------------------------------------

package/test/permission-resolver.test.ts

@@ -6,7 +6,11 @@ import { PermissionResolver } from "#src/permission-resolver";
 import type { Ruleset } from "#src/rule";
 import { SessionApproval } from "#src/session-approval";
 import { SessionRules } from "#src/session-rules";
-import type { PermissionCheckResult, PermissionState } from "#src/types";
+import type {
+  PathRuleTokenMatcher,
+  PermissionCheckResult,
+  PermissionState,
+} from "#src/types";
 
 function makePermissionManager() {
   return {
@@ -28,6 +32,9 @@ function makePermissionManager() {
       .fn<(toolName: string, agentName?: string) => PermissionState>()
       .mockReturnValue("allow"),
     getConfigIssues: vi.fn((): string[] => []),
+    getPromotablePathTokenMatcher: vi
+      .fn<(agentName?: string) => PathRuleTokenMatcher>()
+      .mockReturnValue(() => false),
   };
 }