@gotgenes/pi-permission-system 21.0.0 → 23.0.0

package/CHANGELOG.md

@@ -5,6 +5,45 @@ 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)
+
+
+### ⚠ BREAKING CHANGES
+
+* **pi-permission-system:** In an untrusted project, project-scoped permission configuration (project config.json and project-agent frontmatter) and project-scoped runtime config (yoloMode, permissionReviewLog, etc.) are no longer loaded until the user grants project trust. Only global policy applies. Grant project trust, or set defaultProjectTrust, to restore the prior behavior.
+
+### Features
+
+* **pi-permission-system:** support skipping project scope in loadAndMergeConfigs ([e5a2e57](https://github.com/gotgenes/pi-packages/commit/e5a2e57b39c7bae44e7ac126b24094c2d5dce155))
+
+
+### Bug Fixes
+
+* **pi-permission-system:** gate project-scoped config on project trust ([f264e71](https://github.com/gotgenes/pi-packages/commit/f264e711b90c7947d805bec654bc78199a76fada))
+
+
+### Documentation
+
+* **pi-permission-system:** document project-trust gating for project config ([e955a29](https://github.com/gotgenes/pi-packages/commit/e955a299156215be57144000d5157481615d8060))
+
 ## [21.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v20.10.0...pi-permission-system-v21.0.0) (2026-07-24)
 
 

package/README.md

@@ -107,6 +107,7 @@ Config lives in one JSON file per scope:
 | Project | `<cwd>/.pi/extensions/pi-permission-system/config.json`   |
 
 Project overrides global; per-agent YAML frontmatter overrides both.
+Project config (policy and runtime knobs) is loaded only once the project is trusted — in an untrusted directory only global config applies, so an untrusted repository cannot loosen your global policy (see [Upgrading](#2200--project-config-requires-project-trust)).
 
 Within a surface map like `bash` or `mcp`, **last matching rule wins** — put broad catch-alls first and specific overrides after.
 
@@ -120,6 +121,13 @@ For the full reference — all surfaces, runtime knobs, per-agent overrides, mer
 
 ## Upgrading
 
+### 22.0.0 — project config requires project trust
+
+Project-scoped configuration (the project `config.json` and project-agent frontmatter — both permission policy and runtime knobs such as `yoloMode`) is now loaded only when Pi reports the project as trusted.
+In an untrusted directory, only global config applies; a skip is surfaced with a warning and a `project_trust.skipped` review-log entry.
+Grant project trust (or set `defaultProjectTrust`) to load a project's config.
+See [docs/migration/0644-project-trust-gating.md](docs/migration/0644-project-trust-gating.md).
+
 ### 16.0.0 — the bash gate now fails closed
 
 The permission gate fails closed: an internal gate error blocks the tool (with a `gate_error` review-log entry) instead of running it ungated, and a non-empty bash command that cannot be parsed resolves to `ask` (sentinel `<unparseable-bash-command>`) rather than falling through to a permissive top-level `*`.
@@ -140,6 +148,7 @@ If you relied on the old permissive behavior for bash, set an explicit permissiv
 | [docs/troubleshooting.md](docs/troubleshooting.md)                                                                             | Common issues, diagnostic logging, threat model                                               |
 | [docs/migration/legacy-to-flat.md](docs/migration/legacy-to-flat.md)                                                           | Migration from pre-v2 config layout                                                           |
 | [docs/migration/strict-config-validation.md](docs/migration/strict-config-validation.md)                                       | Strict config validation (breaking) — rejected configs, and the cross-scope fail-closed clamp |
+| [docs/migration/0644-project-trust-gating.md](docs/migration/0644-project-trust-gating.md)                                     | Project-trust gating (breaking) — project config loads only after project trust               |
 
 ## Development
 

package/docs/configuration.md

@@ -11,6 +11,12 @@ One unified config file per scope:
 
 Project config overrides global config; per-agent frontmatter overrides both.
 
+**Project config requires project trust.**
+Project and project-agent scopes (both permission policy and runtime config such as `yoloMode`) are loaded only when Pi reports the project as trusted (`ctx.isProjectTrusted()`).
+In an untrusted directory, only global (and global-agent) config applies, so an untrusted repository cannot loosen your global policy; the extension surfaces a loud warning plus a `project_trust.skipped` review-log entry when it skips a project scope.
+Grant project trust (or configure `defaultProjectTrust`) to load the project's config; a trust grant reloads project policy on the next `resources_discover` reload.
+See [migration/0644-project-trust-gating.md](migration/0644-project-trust-gating.md).
+
 > **Coming from OpenCode?**
 > This extension's permission model was inspired by OpenCode's.
 > See [OpenCode Compatibility](opencode-compatibility.md) for shared concepts, divergences, and a porting guide.
@@ -463,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/docs/migration/0644-project-trust-gating.md

@@ -0,0 +1,32 @@
+# Migration guide: project-trust gating
+
+Starting with the release that closes #644, the permission-system loads project-scoped configuration only after Pi reports the project as **trusted** (`ctx.isProjectTrusted()`).
+This is a **breaking change** in how config is loaded in an untrusted directory.
+
+## What changed
+
+The extension used to load project-scoped config from the current working directory unconditionally — it never consulted Pi's project-trust decision.
+Because project scope has higher precedence than global, an untrusted repository could ship a `.pi/extensions/pi-permission-system/config.json` that **loosened** an operator's global policy before the user granted trust — for example flipping a global `bash: deny` to `bash: allow`, or setting `yoloMode: true`.
+
+Now, when the project is **not** trusted:
+
+- Project and project-agent **permission policy** scopes are not loaded — only global (and global-agent) policy participates in resolution.
+- Project **runtime config** (`yoloMode`, `permissionReviewLog`, `piInfrastructureReadPaths`, `shellTools`, `authorizerChain`, …) is not merged.
+- Each skip is surfaced loudly: a UI warning and a `project_trust.skipped` entry in the permission review log.
+
+This aligns the extension with Pi's own trust model, which already withholds project-local skills, prompts, and agents from untrusted directories.
+
+## Timing and recovery
+
+Pi resolves the trust decision (including any `defaultProjectTrust` setting) before `session_start`, so the guard sees the effective decision from the first tool call.
+If you grant trust after the session starts, Pi fires `resources_discover` with `reason: "reload"`, and the extension re-reads trust and loads the project **policy** at that point.
+Project **runtime** config (e.g. `yoloMode`) is re-read on the next session start.
+
+## What you need to do
+
+If you only use global config, nothing changes.
+
+If you rely on a project's `.pi/extensions/pi-permission-system/config.json`, **grant the project trust** when Pi prompts (or configure `defaultProjectTrust` to always trust).
+Until then, the project's permission rules and runtime knobs are ignored and only your global policy applies.
+
+If a project's rules stop taking effect after upgrading (surfaces you allowed at the project scope start prompting or denying per global policy), check whether the project is trusted — the review log will contain a `project_trust.skipped` entry naming the untrusted `cwd`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "21.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/config-loader.ts

@@ -286,12 +286,20 @@ export interface MergedConfigResult {
  * Legacy files are detected and warned about. Their content is parsed with the
  * flat-format parser — legacy-format keys (defaultPolicy, tools, bash, etc.)
  * are not translated and contribute no permission rules.
+ *
+ * When `options.includeProjectScope` is `false`, the project-scope steps (4 and
+ * 5) are skipped entirely — neither the legacy project policy nor the new
+ * project config is read or merged. This gates project-local config on project
+ * trust: an untrusted repository cannot loosen the operator's global policy
+ * (#644). It defaults to `true`, preserving the trusted / caller-agnostic path.
  */
 export function loadAndMergeConfigs(
   agentDir: string,
   cwd: string,
   extensionRoot: string,
+  options: { includeProjectScope?: boolean } = {},
 ): MergedConfigResult {
+  const includeProjectScope = options.includeProjectScope !== false;
   const allIssues: string[] = [];
 
   const newGlobalPath = getGlobalConfigPath(agentDir);
@@ -339,8 +347,8 @@ export function loadAndMergeConfigs(
   const globalConfig = globalResult.config;
   merged = mergeUnifiedConfigs(merged, globalConfig);
 
-  // 4. Legacy project policy
-  if (existsSync(legacyProjectPolicyPath)) {
+  // 4. Legacy project policy — skipped when the project scope is withheld.
+  if (includeProjectScope && existsSync(legacyProjectPolicyPath)) {
     const legacy = loadUnifiedConfig(legacyProjectPolicyPath);
     allIssues.push(
       `Legacy project policy found at '${legacyProjectPolicyPath}'. ` +
@@ -351,8 +359,11 @@ export function loadAndMergeConfigs(
     merged = mergeUnifiedConfigs(merged, legacy.config);
   }
 
-  // 5. New project config
-  const projectResult = loadUnifiedConfig(newProjectPath);
+  // 5. New project config — skipped when the project scope is withheld, so an
+  // untrusted project contributes nothing and `project` reports empty.
+  const projectResult = includeProjectScope
+    ? loadUnifiedConfig(newProjectPath)
+    : { config: {}, issues: [] };
   allIssues.push(...projectResult.issues);
   const projectConfig = projectResult.config;
   merged = mergeUnifiedConfigs(merged, projectConfig);

package/src/config-store.ts

@@ -41,7 +41,7 @@ export interface ConfigReader {
  * coupling between the class and test doubles.
  */
 export interface SessionConfigStore extends ConfigReader {
-  refresh(ctx?: ExtensionContext): void;
+  refresh(ctx: ExtensionContext | undefined, projectTrusted: boolean): void;
   logResolvedPaths(cwd?: string): void;
 }
 
@@ -96,14 +96,17 @@ export class ConfigStore implements SessionConfigStore, CommandConfigStore {
    * Reload merged config from disk.
    *
    * If `ctx` is provided, uses it to derive the cwd and sync UI status.
-   * Equivalent to `refreshExtensionConfig(runtime, ctx?)`.
+   * When `projectTrusted` is `false`, the project scope is withheld so an
+   * untrusted repository's runtime config (`yoloMode`, `permissionReviewLog`,
+   * …) cannot loosen the operator's global config (#644).
    */
-  refresh(ctx?: ExtensionContext): void {
+  refresh(ctx: ExtensionContext | undefined, projectTrusted: boolean): void {
     const cwd = ctx?.cwd ?? null;
     const mergeResult = loadAndMergeConfigs(
       this.deps.agentDir,
       cwd ?? "",
       EXTENSION_ROOT,
+      { includeProjectScope: projectTrusted },
     );
     const runtimeConfig = normalizePermissionSystemConfig(mergeResult.merged);
     this.config = runtimeConfig;
@@ -127,6 +130,7 @@ export class ConfigStore implements SessionConfigStore, CommandConfigStore {
       debugLog: runtimeConfig.debugLog,
       permissionReviewLog: runtimeConfig.permissionReviewLog,
       yoloMode: runtimeConfig.yoloMode,
+      projectTrusted,
     });
   }
 

package/src/handlers/before-agent-start.ts

@@ -62,7 +62,11 @@ export class AgentPrepHandler {
     // to whole-string matching.
     this.warmParser();
     this.session.activate(ctx);
-    this.session.refreshConfig(ctx);
+    // Gate the mid-session runtime-config refresh on project trust too, so an
+    // untrusted project cannot slip its runtime config (e.g. `yoloMode`) in
+    // right before agent start after session_start withheld it (#644). The
+    // session_start handler already warned; do not re-warn on every start.
+    this.session.refreshConfig(ctx, ctx.isProjectTrusted());
 
     const agentName = this.session.resolveAgentName(ctx, event.systemPrompt);
     const activeTools = this.toolRegistry.getActive();

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/handlers/lifecycle.ts

@@ -17,6 +17,15 @@ interface ResourcesDiscoverPayload {
   reason: string;
 }
 
+/**
+ * Shown when project config is skipped because the project is untrusted, so the
+ * reduced-scope state is never silent (#644). Exported for assertion in tests.
+ */
+export const UNTRUSTED_PROJECT_MESSAGE =
+  "pi-permission-system: project is not trusted — skipping project-scoped " +
+  "permission configuration. Only global policy applies. Grant project trust " +
+  "to load this project's permission rules.";
+
 /**
  * Handles session lifecycle events: start, reload, and shutdown.
  *
@@ -42,9 +51,13 @@ export class SessionLifecycleHandler {
     event: SessionStartPayload,
     ctx: ExtensionContext,
   ): Promise<void> {
-    this.session.refreshConfig(ctx);
-    this.session.resetForNewSession(ctx);
+    const projectTrusted = ctx.isProjectTrusted();
+    this.session.refreshConfig(ctx, projectTrusted);
+    this.session.resetForNewSession(ctx, projectTrusted);
     this.session.logResolvedConfigPaths();
+    if (!projectTrusted) {
+      this.warnProjectUntrusted(ctx, "session_start");
+    }
 
     const agentName = this.session.resolveAgentName(ctx);
     const policyIssues = this.resolver.getConfigIssues(agentName ?? undefined);
@@ -68,12 +81,19 @@ export class SessionLifecycleHandler {
     return Promise.resolve();
   }
 
-  handleResourcesDiscover(event: ResourcesDiscoverPayload): Promise<void> {
+  handleResourcesDiscover(
+    event: ResourcesDiscoverPayload,
+    ctx: ExtensionContext,
+  ): Promise<void> {
     if (event.reason !== "reload") {
       return Promise.resolve();
     }
 
-    this.session.reload();
+    const projectTrusted = ctx.isProjectTrusted();
+    this.session.reload(projectTrusted);
+    if (!projectTrusted) {
+      this.warnProjectUntrusted(ctx, "resources_discover");
+    }
     this.logger.debug("lifecycle.reload", {
       triggeredBy: "resources_discover",
       reason: event.reason,
@@ -82,6 +102,18 @@ export class SessionLifecycleHandler {
     return Promise.resolve();
   }
 
+  /**
+   * Record the project-trust skip in the review log and surface a loud warning
+   * to the user, so the reduced (global-only) scope is never silent (#644).
+   */
+  private warnProjectUntrusted(
+    ctx: ExtensionContext,
+    phase: "session_start" | "resources_discover",
+  ): void {
+    this.logger.review("project_trust.skipped", { cwd: ctx.cwd, phase });
+    this.logger.warn(UNTRUSTED_PROJECT_MESSAGE);
+  }
+
   handleSessionShutdown(): Promise<void> {
     const ctx = this.session.getRuntimeContext();
     if (ctx) {

package/src/index.ts

@@ -171,7 +171,9 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   // refresh() must run after `session` is assigned: a debug-write IO failure
   // triggers the logger's notify sink — `session.notify(m)` — which no-ops
   // on the null context but requires `session` to be bound.
-  configStore.refresh();
+  // No ctx/trust decision exists at factory init, so withhold the project
+  // scope (fail closed); session_start reloads with the real trust decision.
+  configStore.refresh(undefined, false);
 
   const configPath = getGlobalConfigPath(agentDir);
   registerPermissionSystemCommand(pi, {
@@ -258,8 +260,8 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   pi.on("session_start", (event, ctx) =>
     lifecycle.handleSessionStart(event, ctx),
   );
-  pi.on("resources_discover", (event) =>
-    lifecycle.handleResourcesDiscover(event),
+  pi.on("resources_discover", (event, ctx) =>
+    lifecycle.handleResourcesDiscover(event, ctx),
   );
   pi.on("session_shutdown", () => lifecycle.handleSessionShutdown());
   pi.on("before_agent_start", (event, ctx) => agentPrep.handle(event, ctx));

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
@@ -99,11 +98,15 @@ export class PermissionSession implements ToolCallGateInputs {
   /**
    * Reset all mutable state for a new session.
    *
-   * Configures the injected PermissionManager for `ctx.cwd`, clears skill
+   * Configures the injected PermissionManager for `ctx.cwd` (or global-only
+   * when `projectTrusted` is `false`, withholding the project cwd so an
+   * untrusted project's policy scopes are not loaded, #644), clears skill
    * entries, and activates the new context.
    */
-  resetForNewSession(ctx: ExtensionContext): void {
-    this.permissionManager.configureForCwd(ctx.cwd);
+  resetForNewSession(ctx: ExtensionContext, projectTrusted: boolean): void {
+    this.permissionManager.configureForCwd(
+      projectTrusted ? ctx.cwd : undefined,
+    );
     this.skillEntries = [];
     this.activate(ctx);
   }
@@ -121,9 +124,15 @@ export class PermissionSession implements ToolCallGateInputs {
   /**
    * Reload permission manager and clear skill entries for the current context.
    * Used on config reload (e.g. `resources_discover` with reason "reload").
+   *
+   * When `projectTrusted` is `false` the project cwd is withheld, so a reload
+   * in an untrusted project reloads only global policy; a trust grant on a
+   * later reload re-includes the project scope (#644).
    */
-  reload(): void {
-    this.permissionManager.configureForCwd(this.context?.cwd);
+  reload(projectTrusted: boolean): void {
+    this.permissionManager.configureForCwd(
+      projectTrusted ? this.context?.cwd : undefined,
+    );
     this.skillEntries = [];
   }
 
@@ -168,9 +177,16 @@ export class PermissionSession implements ToolCallGateInputs {
 
   // ── Config ─────────────────────────────────────────────────────────────
 
-  /** Reload merged config from disk; optionally update the stored runtime context. */
-  refreshConfig(ctx?: ExtensionContext): void {
-    this.configStore.refresh(ctx);
+  /**
+   * Reload merged config from disk; optionally update the stored runtime
+   * context. When `projectTrusted` is `false`, the project scope is withheld
+   * so an untrusted project's runtime config is not merged (#644).
+   */
+  refreshConfig(
+    ctx: ExtensionContext | undefined,
+    projectTrusted: boolean,
+  ): void {
+    this.configStore.refresh(ctx, projectTrusted);
   }
 
   /** Write the resolved config path set to the review and debug logs. */
@@ -226,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.