@gotgenes/pi-permission-system 22.0.0 → 23.0.0

package/CHANGELOG.md

@@ -5,6 +5,24 @@ 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).
 
+## [23.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v22.0.0...pi-permission-system-v23.0.0) (2026-07-24)
+
+
+### ⚠ BREAKING CHANGES
+
+* **pi-permission-system:** path values embedded in `--opt=value` bash tokens are now extracted and gated by the `path` and `external_directory` surfaces. Previously they were invisible to both, so a permissive `bash` rule such as `grep *` allowed them. Add an allow pattern on `external_directory` or `path` for an intended target.
+* **pi-permission-system:** bash commands referencing existing bare-named files or in-project symlinks are now gated by `path` rules (matched against the canonical, symlink-resolved form) and by `external_directory` when they resolve outside the working directory. Previously a permissive `bash` allow rule such as `cat *` bypassed both. A bare token naming no file is still dropped, so `git status`-style commands are unaffected. To restore prior behavior for an intended target, add an allow pattern on `external_directory` (for outside-CWD paths) or on `path`.
+
+### Bug Fixes
+
+* **pi-permission-system:** classify path values embedded in --opt=value tokens ([0be19fd](https://github.com/gotgenes/pi-packages/commit/0be19fd209254ea76840747c128d3bc5112a912b)), closes [#645](https://github.com/gotgenes/pi-packages/issues/645)
+* **pi-permission-system:** gate existing bare-named files and symlinks in bash commands ([9467858](https://github.com/gotgenes/pi-packages/commit/9467858cdb8824cbdcf5a05994dd0d6b3784cbaa)), closes [#645](https://github.com/gotgenes/pi-packages/issues/645)
+
+
+### Documentation
+
+* **pi-permission-system:** update architecture and skill docs for probe-based path candidacy ([90c402d](https://github.com/gotgenes/pi-packages/commit/90c402d54edbc857597aca66e0cb5f01bade550f)), closes [#645](https://github.com/gotgenes/pi-packages/issues/645)
+
 ## [22.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v21.0.0...pi-permission-system-v22.0.0) (2026-07-24)
 
 

package/docs/configuration.md

@@ -469,8 +469,12 @@ For bash commands, the extension extracts path-candidate tokens from the command
 The most restrictive result across all tokens determines the outcome.
 When the current working directory is known, relative bash tokens are matched with cwd-normalized policy values, resolved against the effective directory after literal `cd` commands; a token after a non-literal `cd` (e.g. `cd "$DIR"`) stays conservative and matches only its literal form.
 
-A bare filename with no path shape at all (e.g. `id_rsa` in `cat id_rsa`) is also gated when it matches an active, specific (non-`*`) `path` deny/ask rule — so `"id_rsa": "deny"` or `"*.pem": "deny"` blocks the file whether it is referenced by a bare name, a relative path, or the `read` tool.
-A bare token that matches no specific `path` rule (e.g. `status` in `git status`) is left alone, and this promotion never fires against a `"*"` catch-all — only a config that already declares a specific `path` rule is affected.
+A bare filename with no path shape at all (e.g. `id_rsa` in `cat id_rsa`) is also gated, provided it names a file that actually exists — so `"id_rsa": "deny"` or `"*.pem": "deny"` blocks the file whether it is referenced by a bare name, a relative path, or the `read` tool.
+Because the resolved path is matched, this covers a bare **symlink** whose target a rule names: with `".some.secret": "deny"`, `cat a_sym` is denied when `a_sym` points at `.some.secret`.
+A bare token that names nothing (e.g. `status` in `git status`, `build` in `npm run build`) is left alone, so ordinary subcommands and branch names never prompt.
+An existing file that matches no `path` rule is likewise left alone — the catch-all `"*"` entry alone does not gate it.
+
+A path embedded in a long option (e.g. `--file=/tmp/patterns` in `grep --file=/tmp/patterns target`) is extracted and gated like any other path token; an option value that is not path-shaped (e.g. `--format=json`) is ignored.
 
 On Windows, where a backslash is a path separator, a backslash-relative bash argument (e.g. `dir\file` in `cat dir\file`) is gated by a `path` rule the same as its forward-slash equivalent (`dir/file`) and the same as the file accessed through the `read` tool.
 On other platforms a backslash is a legal filename character, so such a token is not treated as a path.

package/package.json

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

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

@@ -5,7 +5,7 @@ import {
 } from "#src/access-intent/bash/node-text";
 import type { TSNode } from "#src/access-intent/bash/parser";
 import {
-  classifyPromotedRuleCandidate,
+  classifyBareTokenCandidate,
   classifyTokenAsPathCandidate,
   classifyTokenAsRuleCandidate,
 } from "#src/access-intent/bash/token-classification";
@@ -18,10 +18,6 @@ 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 ───────────────────────────────────────────────────────────
 
@@ -85,22 +81,20 @@ const UNKNOWN_BASE: EffectiveBase = { kind: "unknown" };
  * (`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`.
+ * A bare token that fails both shape gates is admitted when the normalizer's
+ * existence probe says it names a real filesystem entry (ADR 0009, #645). The
+ * resolver consults no ruleset: candidacy is a filesystem question, and the
+ * policy decision belongs to the gates downstream.
  *
  * 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 and promotion predicate).
+ * session normalizer).
  */
 export class BashPathResolver {
   constructor(
     private readonly normalizer: PathNormalizer,
-    private readonly isPromotablePathToken: PathRuleTokenMatcher = NO_PROMOTION,
     private readonly workdir?: string,
   ) {}
 
@@ -426,7 +420,14 @@ export class BashPathResolver {
 
     for (const { token, base } of candidates) {
       const candidate = classifyTokenAsPathCandidate(token);
-      if (!candidate) continue;
+      if (!candidate) {
+        // A bare token the strict shape gate rejects can still escape the tree
+        // through a symlink, so probe it and apply the ordinary boundary
+        // decision to whatever it resolves to (#645).
+        const probed = this.probeBareToken(token, base);
+        if (probed) this.collectIfExternal(probed.path, seen, externalPaths);
+        continue;
+      }
 
       // Unknown effective directory: a relative candidate could resolve
       // anywhere, so flag it conservatively (resolved against the baked cwd
@@ -446,45 +447,58 @@ export class BashPathResolver {
         base.kind === "known"
           ? this.normalizer.resolveBase(base.offset)
           : undefined;
-      const accessPath = this.normalizer.forBashToken(candidate, {
-        resolveBase,
-      });
-      const lexical = accessPath.value();
-      if (!lexical) continue;
-      // The boundary decision and dedup identity use the canonical
-      // (symlink-resolved) form the AccessPath already derived, but the returned
-      // value is the lexical form so config patterns match the path as the user
-      // typed it (#418). A win32 device path preserves `/dev/null` as its
-      // boundary value, so `isBoundaryOutsideWorkingDirectory` reaches the
-      // safe-path exclusion (#533).
-      const canonical = accessPath.boundaryValue();
-      // A literal-only bash token (a win32 non-mount POSIX absolute like `/tmp`)
-      // has no canonical form; it is foreign to the win32 cwd, so it is always
-      // external. Its lexical value is the dedup identity so two distinct
-      // literal-only paths do not collapse (#533).
-      const isExternal = canonical
-        ? this.normalizer.isBoundaryOutsideWorkingDirectory(canonical)
-        : true;
-      const dedupKey = canonical || lexical;
-
-      if (isExternal && !seen.has(dedupKey)) {
-        seen.add(dedupKey);
-        externalPaths.push(accessPath);
-      }
+      this.collectIfExternal(
+        this.normalizer.forBashToken(candidate, { resolveBase }),
+        seen,
+        externalPaths,
+      );
     }
 
     return externalPaths;
   }
 
+  /**
+   * Record `accessPath` when it resolves outside the working directory and has
+   * not already been collected.
+   *
+   * The boundary decision and dedup identity use the canonical
+   * (symlink-resolved) form the {@link AccessPath} already derived, while the
+   * stored value keeps the lexical form so config patterns match the path as
+   * the user typed it (#418). A win32 device path preserves `/dev/null` as its
+   * boundary value, so `isBoundaryOutsideWorkingDirectory` reaches the
+   * safe-path exclusion (#533).
+   *
+   * A literal-only bash token (a win32 non-mount POSIX absolute like `/tmp`)
+   * has no canonical form; it is foreign to the win32 cwd, so it is always
+   * external. Its lexical value is the dedup identity so two distinct
+   * literal-only paths do not collapse (#533).
+   */
+  private collectIfExternal(
+    accessPath: AccessPath,
+    seen: Set<string>,
+    out: AccessPath[],
+  ): void {
+    const lexical = accessPath.value();
+    if (!lexical) return;
+    const canonical = accessPath.boundaryValue();
+    const isExternal = canonical
+      ? this.normalizer.isBoundaryOutsideWorkingDirectory(canonical)
+      : true;
+    const dedupKey = canonical || lexical;
+    if (isExternal && !seen.has(dedupKey)) {
+      seen.add(dedupKey);
+      out.push(accessPath);
+    }
+  }
+
   /**
    * Project the collected candidates into rule candidates with their cd-aware
    * policy lookup values.
    *
    * Filters candidates through the broad path classifier
-   * (`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.
+   * (`classifyTokenAsRuleCandidate`), falling back to {@link probeBareToken}
+   * for a bare token the broad classifier rejects for shape — admitted only
+   * when it names an existing filesystem entry (#645).
    * On win32 the broad classifier is told to treat a backslash as a path
    * separator, so a backslash-relative token (`dir\file`) is recognized as a
    * rule candidate the same as its forward-slash equivalent (#520); on POSIX
@@ -501,24 +515,62 @@ export class BashPathResolver {
     const result: BashPathRuleCandidate[] = [];
 
     for (const { token, base } of candidates) {
+      const shaped = classifyTokenAsRuleCandidate(
+        token,
+        this.normalizer.flavor,
+      );
       const candidate =
-        classifyTokenAsRuleCandidate(token, this.normalizer.flavor) ??
-        classifyPromotedRuleCandidate(token, this.isPromotablePathToken);
+        shaped === null
+          ? this.probeBareToken(token, base)
+          : { token: shaped, path: this.buildRuleCandidatePath(shaped, base) };
       if (!candidate) continue;
 
-      const path = this.buildRuleCandidatePath(candidate, base);
-      const matchValues = path.matchValues();
+      const matchValues = candidate.path.matchValues();
       if (matchValues.length === 0) continue;
 
       const key = matchValues.join("\0");
       if (seen.has(key)) continue;
       seen.add(key);
-      result.push({ token: candidate, path });
+      result.push(candidate);
     }
 
     return result;
   }
 
+  /**
+   * Promote a bare token the shape gates rejected, when it names an existing
+   * filesystem entry — the existence probe (ADR 0009, #645).
+   *
+   * Most bash argument tokens are not paths (`status`, `build`, `main`), so a
+   * bare token is admitted only when the filesystem confirms it names something
+   * real. Candidacy therefore comes from the filesystem and never from the
+   * ruleset, which keeps the classifiers pure and lets a symlink be matched by
+   * rules naming its *target* — the case raw-token matching could not see.
+   *
+   * Returns `null` when the token's shape rules out a path, when the effective
+   * base is unknown (no concrete directory to resolve against, so the token
+   * stays unpromoted per #393 conservatism), or when nothing exists at the
+   * resolved location.
+   *
+   * Shared by both projections so a promoted token is identical whether it is
+   * being matched against `path` rules or tested against the cwd boundary.
+   */
+  private probeBareToken(
+    token: string,
+    base: EffectiveBase,
+  ): BashPathRuleCandidate | null {
+    const bare = classifyBareTokenCandidate(token);
+    if (bare === null) return null;
+    if (base.kind !== "known") return null;
+
+    const path = this.normalizer.forBashToken(bare, {
+      resolveBase: this.normalizer.resolveBase(base.offset),
+    });
+    const lexical = path.value();
+    if (!lexical || !this.normalizer.entryExists(lexical)) return null;
+    return { token: bare, path };
+  }
+
   private buildRuleCandidatePath(
     candidate: string,
     base: EffectiveBase,

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

@@ -9,7 +9,6 @@ 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 };
 
@@ -40,11 +39,10 @@ export class BashProgram {
    * 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.
+   * A bare token (e.g. `id_rsa`, `outside-link`) enters both slices when it
+   * names an existing filesystem entry — the existence probe the resolver owns
+   * (ADR 0009, #645). No policy is consulted, so every caller gets identical
+   * slices for a given command and working directory.
    *
    * `options.workdir`, when supplied (an aliased shell tool's working directory,
    * #574), seeds the initial effective base — as if the command were prefixed
@@ -54,7 +52,6 @@ export class BashProgram {
   static async parse(
     command: string,
     normalizer: PathNormalizer,
-    isPromotablePathToken?: PathRuleTokenMatcher,
     options?: { workdir?: string },
   ): Promise<BashProgram> {
     const parser = await getParser();
@@ -64,7 +61,6 @@ export class BashProgram {
     try {
       const { externalPaths, ruleCandidates } = new BashPathResolver(
         normalizer,
-        isPromotablePathToken,
         options?.workdir,
       ).resolve(tree.rootNode);
       return new BashProgram(

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

@@ -4,9 +4,16 @@
  * 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).
+ *   - `classifyBareTokenCandidate` — prelude-only gate for a bare token (e.g.
+ *     `id_rsa`, `outside-link`) that `classifyTokenAsRuleCandidate` rejects for
+ *     shape. It answers only "is this shape capable of naming a path?"; whether
+ *     it *does* name one is settled by the resolver's existence probe (#645).
+ *
+ * Token classification is three-valued: definitely-path (shape), definitely-not
+ * (prelude), and unknown (a bare word). These functions own the first two; the
+ * third is resolved against the filesystem rather than against policy, so no
+ * classifier here consults the ruleset — see
+ * `docs/decisions/0009-bash-path-projection-completeness-contract.md`.
  *
  * All three classifiers share the private `rejectNonPathToken` predicate that
  * captures the six rejection cases common to them (the production clone this
@@ -28,7 +35,6 @@
  * never reads `process.platform` itself.
  */
 import type { PathFlavor } from "#src/path/path-flavor";
-import type { PathRuleTokenMatcher } from "#src/types";
 
 // ── Public classifiers ─────────────────────────────────────────────────────
 
@@ -91,28 +97,28 @@ export function classifyTokenAsRuleCandidate(
 }
 
 /**
- * Rule-driven promotion classifier for bare filenames (#509).
+ * Prelude-only classifier for a bare token (#645).
+ *
+ * A bare token (`id_rsa`, `outside-link`) has none of the shapes
+ * `classifyTokenAsRuleCandidate` accepts, because most bash argument tokens are
+ * not file paths (subcommands, branch names, search patterns). This classifier
+ * answers the narrower question the existence probe needs: could this token's
+ * *shape* name a path at all?
  *
- * 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.
+ * It runs only the shared `rejectNonPathToken` prelude, so a flag,
+ * env-assignment, URL, `@scope` token, or regex-shaped token is never a
+ * candidate. Everything else is returned for the caller to probe.
  *
- * 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.
+ * Deliberately consults no policy: candidacy is settled by the filesystem and
+ * the decision by the ruleset, which keeps this module a pure shape function
+ * (ADR 0009). It replaced the rule-driven promotion of #509, which matched a
+ * token's *spelling* against `path` rules and so could never see that a
+ * symlink's target is what a rule names.
  *
  * 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;
+export function classifyBareTokenCandidate(token: string): string | null {
+  return rejectNonPathToken(token) ? null : token;
 }
 
 // ── Private rejection predicate ────────────────────────────────────────────

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

@@ -42,9 +42,10 @@ export function collectCommandTokens(node: TSNode): string[] {
   const config = commandName
     ? PATTERN_FIRST_COMMANDS.get(commandName)
     : undefined;
-  return config
+  const tokens = config
     ? collectPatternCommandTokens(node, config)
     : collectGenericCommandTokens(node);
+  return [...tokens, ...collectEmbeddedOptionValues(node)];
 }
 
 /**
@@ -81,6 +82,42 @@ export function extractCommandName(node: TSNode): string | undefined {
 
 // ── Private helpers and config ─────────────────────────────────────────────
 
+/**
+ * A long or short option carrying its value inline: one or two leading dashes,
+ * a name containing no `=` or whitespace, then `=` and a non-empty value.
+ * Only the first `=` separates, so `--opt=/tmp/a=b` yields `/tmp/a=b`.
+ */
+const OPTION_VALUE_PATTERN = /^-{1,2}[^=\s]+=(.+)$/;
+
+/**
+ * The values embedded in this command's `--opt=value` argument tokens.
+ *
+ * Read straight from the argument nodes rather than from the collected token
+ * list, because a pattern-first command's collector classifies a flag and never
+ * emits it — so `grep --file=/tmp/patterns` would otherwise lose the path.
+ *
+ * This is token *preprocessing*, not classification: the extracted value is
+ * handed to the ordinary shape classifiers and existence probe, so
+ * `--file=/tmp/patterns` reaches the path surfaces while `--format=json`
+ * yields a bare `json` that names nothing and is dropped. Keeping the split
+ * here is what lets the projection see option-embedded paths without per-command
+ * option tables (ADR 0009, #645).
+ */
+function collectEmbeddedOptionValues(node: TSNode): string[] {
+  const values: string[] = [];
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child) continue;
+    if (child.type === "command_name" || child.type === "variable_assignment")
+      continue;
+    if (!ARG_NODE_TYPES.has(child.type)) continue;
+
+    const value = OPTION_VALUE_PATTERN.exec(resolveNodeText(child))?.[1];
+    if (value !== undefined) values.push(value);
+  }
+  return values;
+}
+
 interface PatternCommandConfig {
   /** Flags that consume the next argument as a non-path value (pattern, separator, etc.) */
   readonly argConsumingFlags: ReadonlySet<string>;

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

@@ -15,7 +15,7 @@ import {
   ToolPreviewFormatter,
   type ToolPreviewFormatterOptions,
 } from "#src/tool-preview-formatter";
-import type { PathRuleTokenMatcher, PermissionCheckResult } from "#src/types";
+import type { PermissionCheckResult } from "#src/types";
 import { resolveBashCommandCheck } from "./bash-command";
 import { describeBashExternalDirectoryGate } from "./bash-external-directory";
 import { describeBashPathGate } from "./bash-path";
@@ -52,11 +52,6 @@ export interface ToolCallGateInputs {
    * tool is gated through the bash stack at parity with native `bash` (#574).
    */
   getShellToolAliases(): ShellToolsConfig | undefined;
-  /**
-   * 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;
 }
 
 /**
@@ -93,12 +88,9 @@ export class ToolCallGatePipeline {
     );
     const normalizer = this.inputs.getPathNormalizer();
     const bashProgram = shell?.command
-      ? await BashProgram.parse(
-          shell.command,
-          normalizer,
-          this.inputs.getPromotablePathTokenMatcher(tcc.agentName ?? undefined),
-          { workdir: shell.workdir },
-        )
+      ? await BashProgram.parse(shell.command, normalizer, {
+          workdir: shell.workdir,
+        })
       : null;
 
     const formatter = new ToolPreviewFormatter(

package/src/path-normalizer.ts

@@ -1,3 +1,5 @@
+import { lstatSync } from "node:fs";
+
 import type { PathFlavor } from "#src/path/path-flavor";
 
 import { AccessPath } from "./access-intent/access-path";
@@ -203,4 +205,30 @@ export class PathNormalizer {
       this.flavor,
     );
   }
+
+  /**
+   * True when `absolutePath` names an existing filesystem entry.
+   *
+   * The existence probe that resolves an *unknown* bash token: a bare word is a
+   * path candidate iff it names something real (ADR 0009, #645). Uses `lstat`,
+   * not `stat`, so a symlink counts as an entry even when its target is
+   * dangling — the link is the operand the command names, and dropping it would
+   * reopen the bypass this probe closes.
+   *
+   * Any error (ENOENT, ENOTDIR, EACCES, ELOOP) answers `false`: an entry the
+   * gate cannot confirm is not promoted, leaving the token exactly as
+   * unrestricted as it is today.
+   *
+   * Lives here beside {@link forPath}'s canonicalization so the package keeps a
+   * single filesystem edge for path interpretation.
+   */
+  entryExists(absolutePath: string): boolean {
+    if (!absolutePath) return false;
+    try {
+      lstatSync(absolutePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
 }

package/src/permission-manager.ts

@@ -22,7 +22,6 @@ import {
   evaluateAnyValue,
   evaluateFirst,
   floorAllowsToAsk,
-  pathMatchOptions,
   rewriteAsksToYolo,
 } from "./rule";
 import { mergeScopesWithOrigins } from "./scope-merge";
@@ -33,21 +32,16 @@ import {
 } from "./synthesize";
 import type {
   FlatPermissionConfig,
-  PathRuleTokenMatcher,
   PermissionCheckResult,
   PermissionState,
 } from "./types";
 import { isPermissionState } from "./types";
-import { wildcardMatch } from "./wildcard-matcher";
 
 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;
-
 /** Default yolo reader — yolo disabled unless the composition root injects one. */
 const YOLO_DISABLED = (): boolean => false;
 
@@ -90,15 +84,6 @@ 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 {
@@ -271,37 +256,6 @@ 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.flavor);
-    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

@@ -20,7 +20,6 @@ import {
   resolveToolPreviewLimits,
   type ToolPreviewFormatterOptions,
 } from "./tool-preview-formatter";
-import type { PathRuleTokenMatcher } from "./types";
 
 /**
  * Encapsulates all mutable session state and exposes operations instead of
@@ -243,15 +242,4 @@ 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/types.ts

@@ -17,17 +17,6 @@ export type {
   RuleOrigin,
 };
 
-/**
- * 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;
-
 /**
  * Per-scope permission config shape after loading and validation.
  * Holds only the flat permission map — all policy is expressed there.