@gotgenes/pi-permission-system 22.0.0 → 23.0.1

package/CHANGELOG.md

@@ -5,6 +5,36 @@ 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.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v23.0.0...pi-permission-system-v23.0.1) (2026-07-25)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** fold separators on both sides of a win32 path match ([50e2ac0](https://github.com/gotgenes/pi-packages/commit/50e2ac0dd66b4b308a676849a09e3fff59e754be)), closes [#653](https://github.com/gotgenes/pi-packages/issues/653)
+
+
+### Documentation
+
+* **pi-permission-system:** record the symmetric win32 separator fold ([e2eea21](https://github.com/gotgenes/pi-packages/commit/e2eea21e0aac1212f46be9680fb59146b90c68f7)), closes [#653](https://github.com/gotgenes/pi-packages/issues/653)
+
+## [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.
@@ -614,15 +618,18 @@ Infrastructure directories include:
 Write tools (`write`, `edit`) to infrastructure paths are **not** auto-allowed and still go through the gate.
 
 On Windows, path matching for `external_directory`, `path`, and the path-bearing tools is case-insensitive and tolerant of either separator (`\` or `/`), matching the case-insensitive filesystem.
-A mixed-case allow override such as `~/AppData/Roaming/npm/node_modules/@earendil-works/pi-coding-agent/*` therefore matches a lowercased, backslash-normalized path value.
-POSIX matching remains case-sensitive.
+The separator folding applies to the rule pattern **and** to the value it is matched against, so either side may be written with either separator.
+A mixed-case allow override such as `~/AppData/Roaming/npm/node_modules/@earendil-works/pi-coding-agent/*` therefore matches a lowercased, backslash-normalized path value, and a forward-slash rule such as `"/dev/null"` matches a value that is also spelled with forward slashes.
+POSIX matching remains case-sensitive and does not fold separators.
 
 #### Git Bash / MSYS paths on Windows
 
 On Windows, Pi executes bash commands through Git Bash, so a bash token that looks like a POSIX absolute path carries MSYS mount semantics rather than native `node:path.win32` semantics.
 The `external_directory` and `path` gates interpret bash tokens accordingly (tool-input paths for `read`/`write`/`edit` keep native Windows semantics, since those tools resolve them through Node's filesystem):
 
-- The safe device paths (`/dev/null`, `/dev/stdin`, `/dev/stdout`, `/dev/stderr`) are recognized as MSYS devices and never trigger the gate — the same exclusion that holds on POSIX, so `echo hi > /dev/null` does not prompt.
+- The safe device paths (`/dev/null`, `/dev/stdin`, `/dev/stdout`, `/dev/stderr`) are recognized as MSYS devices rather than filesystem paths, so they never trigger the `external_directory` gate — the same exclusion that holds on POSIX.
+  The cross-cutting `path` surface still governs them on both platforms: if a `path` rule matches the token, it decides.
+  A device is therefore allow-listed the way any other path is, written as typed — `path: { "/dev/null": "allow" }`.
 - MSYS drive mounts (`/c/…`, `/d/…`) are translated to their Windows equivalent (`C:\…`), so a project file referenced through a mount is matched against its real Windows path and an in-CWD mount is not flagged.
 - Every other POSIX-absolute token (`/tmp/foo`, `/usr/bin`) has an install-dependent target this extension cannot resolve deterministically (Git Bash mounts `/tmp` to `%TEMP%`, MSYS2 to its own root), so it is treated as an external path matched and displayed exactly as typed, never rewritten to `C:\tmp\foo`.
 

package/package.json

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

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

@@ -120,20 +120,12 @@ export class AccessPath {
    * unknown (a relative bash token after a non-literal `cd`).
    *
    * Carries no canonical alias and no absolute resolution — `matchValues()` is
-   * `[literal, ...matchAliases]` (or `[]` when empty) and `boundaryValue()` is
-   * `""` — so no spurious absolute or symlink-resolved rule can match (#393).
-   *
-   * `matchAliases` supplies extra match-only forms that do not change the
-   * display value: a win32 Git Bash POSIX absolute carries a backslash-separated
-   * alias so the separator-folding path matcher can match a `/tmp/*` rule (#533).
+   * `[literal]` (or `[]` when empty) and `boundaryValue()` is `""` — so no
+   * spurious absolute or symlink-resolved rule can match (#393).
    */
-  static forLiteral(
-    literal: string,
-    matchAliases: readonly string[] = [],
-  ): AccessPath {
+  static forLiteral(literal: string): AccessPath {
     if (!literal) return new AccessPath("", [], "");
-    const aliases = [...new Set([literal, ...matchAliases.filter(Boolean)])];
-    return new AccessPath(literal, aliases, "");
+    return new AccessPath(literal, [literal], "");
   }
 
   /**

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";
@@ -60,8 +62,8 @@ export class PathNormalizer {
   }
 
   /** Build a literal-only AccessPath (unknown base after a non-literal `cd`). */
-  forLiteral(literal: string, matchAliases?: readonly string[]): AccessPath {
-    return AccessPath.forLiteral(literal, matchAliases);
+  forLiteral(literal: string): AccessPath {
+    return AccessPath.forLiteral(literal);
   }
 
   /**
@@ -84,17 +86,14 @@ export class PathNormalizer {
         return AccessPath.forDevice(token);
       case "drive-mount":
         return this.forPath(shape.windowsPath, options);
-      case "posix-absolute": {
+      case "posix-absolute":
         // A non-mount POSIX absolute (`/tmp`, `/usr`) has an install-dependent
         // Windows target this package cannot know, so it is kept literal: always
         // external, matched and displayed as typed, never fabricated into
-        // `c:\tmp` (#533). The win32 path matcher folds a rule's separators
-        // (`/` -> `\`), so a forward-slash value is unmatchable; carry a
-        // backslash match alias so a natural `/tmp/*` external_directory rule
-        // still resolves, while `value()` stays as typed for display.
-        const literal = normalizePathPolicyLiteral(token);
-        return this.forLiteral(literal, [literal.replaceAll("/", "\\")]);
-      }
+        // `c:\tmp` (#533). The win32 path matcher folds separators on both the
+        // rule and the value (#653), so a natural `/tmp/*` rule matches the
+        // as-typed literal directly.
+        return this.forLiteral(normalizePathPolicyLiteral(token));
       case "plain":
         return this.forPath(token, options);
     }
@@ -203,4 +202,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.

package/src/wildcard-matcher.ts

@@ -1,10 +1,20 @@
 import { expandHomePath } from "./expand-home";
 
-export type CompiledWildcardPattern<TState> = {
-  pattern: string;
-  state: TState;
-  regex: RegExp;
-};
+/**
+ * A pattern compiled once for repeated matching.
+ *
+ * Matching is a method rather than an exposed `RegExp` so that both halves of
+ * the {@link WildcardMatchOptions} fold stay together: the compiled regex
+ * carries the pattern-side folding, and {@link matches} applies the same
+ * folding to the value. A caller holding the raw regex could apply one without
+ * the other, which is exactly the asymmetry that made forward-slash path rules
+ * inert on Windows (#653).
+ */
+export interface CompiledWildcardPattern<TState> {
+  readonly pattern: string;
+  readonly state: TState;
+  matches(value: string): boolean;
+}
 
 export type WildcardPatternMatch<TState> = {
   state: TState;
@@ -17,8 +27,11 @@ export type WildcardPatternMatch<TState> = {
  *
  * - `caseInsensitive` compiles the pattern with the `i` flag so a mixed-case
  *   pattern matches a lowercased (canonicalized) path value.
- * - `windowsSeparators` rewrites `/` to `\` in the expanded pattern so a
- *   forward-slash pattern matches a backslash-separated path value.
+ * - `windowsSeparators` rewrites `/` to `\` in both the expanded pattern and
+ *   the matched value, so two spellings of the same path match regardless of
+ *   which separator either side was written with. Folding only the pattern
+ *   leaves every forward-slash value (a Git Bash device, an as-typed literal)
+ *   unmatchable (#653).
  */
 export interface WildcardMatchOptions {
   caseInsensitive?: boolean;
@@ -34,10 +47,7 @@ export function compileWildcardPattern<TState>(
   state: TState,
   options?: WildcardMatchOptions,
 ): CompiledWildcardPattern<TState> {
-  let expanded = expandHomePath(pattern);
-  if (options?.windowsSeparators) {
-    expanded = expanded.replaceAll("/", "\\");
-  }
+  const expanded = foldSeparators(expandHomePath(pattern), options);
   let escaped = expanded
     .split("*")
     .map((part) => escapeRegExp(part).replaceAll("\\?", "."))
@@ -50,10 +60,15 @@ export function compileWildcardPattern<TState>(
     escaped = `${escaped.slice(0, -3)}( .*)?`;
   }
 
+  const regex = new RegExp(
+    `^${escaped}$`,
+    options?.caseInsensitive ? "si" : "s",
+  );
+
   return {
     pattern,
     state,
-    regex: new RegExp(`^${escaped}$`, options?.caseInsensitive ? "si" : "s"),
+    matches: (value) => regex.test(foldSeparators(value, options)),
   };
 }
 
@@ -75,7 +90,7 @@ export function findCompiledWildcardMatch<TState>(
   patterns: readonly CompiledWildcardPattern<TState>[],
   name: string,
 ): WildcardPatternMatch<TState> | null {
-  const match = patterns.findLast((p) => p.regex.test(name));
+  const match = patterns.findLast((p) => p.matches(name));
   if (match === undefined) return null;
   return {
     state: match.state,
@@ -95,7 +110,17 @@ export function wildcardMatch(
   value: string,
   options?: WildcardMatchOptions,
 ): boolean {
-  return compileWildcardPattern(pattern, null, options).regex.test(value);
+  return compileWildcardPattern(pattern, null, options).matches(value);
+}
+
+/**
+ * Apply the `windowsSeparators` half of the fold to one operand.
+ *
+ * Called for the pattern at compile time and for the value at match time —
+ * the fold is an equivalence relation, so both sides must pass through it.
+ */
+function foldSeparators(value: string, options?: WildcardMatchOptions): string {
+  return options?.windowsSeparators ? value.replaceAll("/", "\\") : value;
 }
 
 export function findCompiledWildcardMatchForNames<TState>(