@gotgenes/pi-permission-system 18.0.2 → 18.1.1

package/docs/opencode-compatibility.md

@@ -0,0 +1,213 @@
+# OpenCode Compatibility
+
+This extension's flat permission format and evaluation semantics were directly inspired by [OpenCode's permission model](https://opencode.ai/docs/permissions/) (v1.1.x permission rework).
+If you are familiar with OpenCode's permission system, most concepts transfer directly — the same mental model applies.
+
+> **Point-in-time reference.**
+> This comparison reflects OpenCode as of May 2026.
+> See the [official OpenCode permissions docs](https://opencode.ai/docs/permissions/) for the latest upstream behavior.
+
+## What Transfers Directly
+
+The following concepts are shared between OpenCode and this extension:
+
+| Concept                       | Description                                                                                                     |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| Three actions                 | `allow` / `ask` / `deny` — identical semantics                                                                  |
+| Flat `permission` object      | Top-level key in config; surface names as keys                                                                  |
+| `"*"` universal fallback      | Sets the default action when no surface-specific rule matches                                                   |
+| Granular object syntax        | Surface key → string (catch-all) or `{ pattern: action }` map                                                   |
+| Last-match-wins               | When multiple patterns match, the last one in config order wins                                                 |
+| `*` wildcard                  | Matches zero or more of any character (including path separators)                                               |
+| `?` wildcard                  | Matches exactly one character                                                                                   |
+| Home directory expansion      | `~/` and `$HOME/` expand to the OS home directory in patterns                                                   |
+| `external_directory` surface  | Gates access to paths outside the working directory                                                             |
+| `bash` surface                | Command patterns matched against shell commands                                                                 |
+| `skill` surface               | Skill name patterns matched against skill invocations                                                           |
+| `task` surface                | Gates subagent/delegation tool calls                                                                            |
+| Session-scoped approvals      | `once` / `always` / `reject` from the ask dialog; `always` adds a session rule                                  |
+| Per-agent overrides           | Override global permissions for specific agents                                                                 |
+| Tool hiding                   | Denied tools are removed before the agent starts (no wasted turns probing)                                      |
+| Bash path extraction          | Tree-sitter AST parsing to detect external paths in shell commands (see [details below](#bash-path-extraction)) |
+| Bash arity table              | Generates smart approval pattern suggestions (e.g., `git checkout *` not `git *`)                               |
+| Trailing wildcard optionality | `"ls *"` matches bare `"ls"` — the trailing `*` is optional                                                     |
+
+If your OpenCode config uses these features, the equivalent works in this extension with minimal translation (see [Porting Guide](#porting-an-opencode-config) below).
+
+## Where They Diverge
+
+### Summary Table
+
+| Area                       | OpenCode                                                             | This extension                                                                                                                                        |
+| -------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Default fallback           | `"*": "allow"` (permissive)                                          | `"*": "ask"` (least privilege)                                                                                                                        |
+| `.env` file protection     | Built-in `read` rules deny/ask `.env` files                          | No built-in rules; user configures with the cross-cutting `path` surface or per-tool path patterns (see [porting guide](#porting-an-opencode-config)) |
+| Cross-cutting `path` gate  | No equivalent — `.env` protection is per-tool only                   | `path` surface denies/asks across all tools and bash at once; a `path` deny cannot be overridden by a per-tool allow                                  |
+| OpenCode-only surfaces     | `lsp`, `question`, `webfetch`, `websearch`, `todowrite`, `doom_loop` | Not applicable — Pi does not expose these tools or events                                                                                             |
+| File mutation surfaces     | `edit` covers `edit`, `write`, `apply_patch`                         | Separate `write` and `edit` surfaces                                                                                                                  |
+| Search/discovery surfaces  | `glob`, `grep`, `list`                                               | `find`, `grep`, `ls` (Pi tool names)                                                                                                                  |
+| `mcp` surface              | Not a documented permission surface                                  | First-class with server/tool-level granularity                                                                                                        |
+| Top-level string shorthand | `"permission": "allow"` sets all surfaces                            | Not supported; must use an object                                                                                                                     |
+| Per-agent config location  | `agent` key in config JSON or YAML frontmatter                       | YAML frontmatter in agent `.md` files only                                                                                                            |
+| Config file paths          | `~/.config/opencode/opencode.json`                                   | `~/.pi/agent/extensions/pi-permission-system/config.json`                                                                                             |
+| Subagent prompt forwarding | Not documented                                                       | `ask` policies work in non-UI subagent contexts                                                                                                       |
+| Infrastructure auto-allow  | N/A                                                                  | Read-only tools to Pi infra dirs bypass the gate                                                                                                      |
+| Permission review log      | No equivalent documented                                             | Writes decisions to a JSONL audit log                                                                                                                 |
+
+### Notable Differences Explained
+
+#### Default Fallback: `allow` vs `ask`
+
+OpenCode defaults to permissive — most tools work without configuration.
+This extension defaults to least privilege — omitting `"*"` gives you `"ask"` for everything.
+
+If you want OpenCode-like permissiveness:
+
+```jsonc
+{
+  "permission": {
+    "*": "allow",
+    "external_directory": "ask"
+  }
+}
+```
+
+#### File Mutation Surfaces
+
+OpenCode unifies all file writes under a single `edit` permission.
+This extension exposes Pi's actual tool names: `write` (create/overwrite) and `edit` (targeted replacement).
+
+To replicate OpenCode's unified behavior, set both to the same action:
+
+```jsonc
+{
+  "permission": {
+    "write": "ask",
+    "edit": "ask"
+  }
+}
+```
+
+#### MCP Surface (Pi-Only)
+
+This extension provides a first-class `mcp` permission surface with granular server and tool-level control:
+
+```jsonc
+{
+  "permission": {
+    "mcp": {
+      "*": "ask",
+      "mcp_status": "allow",
+      "myServer:*": "ask",
+      "dangerousServer": "deny"
+    }
+  }
+}
+```
+
+OpenCode does not expose MCP as a configurable permission surface.
+
+#### Bash Path Extraction
+
+Both systems use `web-tree-sitter` + `tree-sitter-bash` to parse shell commands into an AST for `external_directory` path detection, but the extraction strategies differ significantly:
+
+**OpenCode** only extracts paths from a hardcoded allowlist of file-manipulating commands (`rm`, `cp`, `mv`, `mkdir`, `touch`, `chmod`, `chown`, `cat`, plus PowerShell equivalents).
+Commands not in the list — including `sed`, `awk`, `grep` — get no path extraction at all.
+For allowlisted commands, all non-flag positional arguments are assumed to be paths.
+
+**This extension** extracts path candidates from all commands generically, then applies additional intelligence:
+
+- A `PATTERN_FIRST_COMMANDS` map understands flag arity for `sed`, `awk`, `grep`, `rg`, and similar tools, distinguishing inline patterns/scripts from file arguments to avoid false positives.
+- Redirect destinations (`> /path/to/file`) are extracted.
+- Heredoc bodies, comments, and variable assignments are skipped.
+
+The result is broader coverage (paths detected in any command, not just a curated list) with fewer false positives on pattern-first commands (no spurious prompts for sed regexes or grep patterns that happen to contain `/`).
+
+## Porting an OpenCode Config
+
+### Before (OpenCode)
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "*": "allow",
+    "bash": {
+      "*": "ask",
+      "git *": "allow",
+      "npm *": "allow",
+      "rm *": "deny"
+    },
+    "edit": {
+      "*": "ask",
+      "src/*.ts": "allow"
+    },
+    "external_directory": {
+      "~/projects/*": "allow"
+    }
+  }
+}
+```
+
+### After (this extension)
+
+```jsonc
+{
+  "$schema": "https://raw.githubusercontent.com/gotgenes/pi-permission-system/main/schemas/permissions.schema.json",
+  "permission": {
+    "*": "allow",
+    "bash": {
+      "*": "ask",
+      "git *": "allow",
+      "npm *": "allow",
+      "rm *": "deny"
+    },
+    "write": "ask",
+    "edit": "ask",
+    "external_directory": {
+      "*": "ask",
+      "~/projects/*": "allow"
+    }
+  }
+}
+```
+
+### Key Translation Steps
+
+1. **Replace `"permission": "allow"`** (top-level string) with `"permission": { "*": "allow" }`.
+2. **Split `edit`** into separate `write` and `edit` entries if you need different policies for create vs. modify.
+   If not, set both to the same action.
+3. **Rename search surfaces**: `glob` → `find`, `list` → `ls`.
+4. **Add `.env` rules manually** if you relied on OpenCode's built-in protection.
+   The `path` surface is the recommended approach — it covers all tools and bash in one rule:
+
+    ```jsonc
+    {
+      "permission": {
+        "path": {
+          "*": "allow",
+          "*.env": "deny",
+          "*.env.*": "deny",
+          "*.env.example": "allow"
+        }
+      }
+    }
+    ```
+
+   Alternatively, use per-tool patterns if you only need to protect specific tools (e.g., `read`):
+
+    ```jsonc
+    {
+      "permission": {
+        "read": {
+          "*": "allow",
+          "*.env": "deny",
+          "*.env.*": "deny",
+          "*.env.example": "allow"
+        }
+      }
+    }
+    ```
+
+5. **Remove OpenCode-only surfaces** (`lsp`, `question`, `webfetch`, `websearch`, `todowrite`, `doom_loop`) — they have no effect in this extension.
+6. **Add `mcp` rules** if you use MCP servers — OpenCode has no equivalent, so this is new configuration.

package/docs/session-approvals.md

@@ -0,0 +1,68 @@
+# Session-Scoped Approvals
+
+When any permission resolves to `ask`, the permission dialog offers four options:
+
+```text
+Yes | Yes, allow "<pattern>" for this session | No | No, provide reason
+```
+
+Selecting **Yes, allow "\<pattern\>" for this session** approves the current request and records the suggested wildcard pattern as a session rule.
+Subsequent requests that match the pattern skip the prompt for the remainder of the session.
+
+Session approvals are ephemeral — they are never persisted to disk and are cleared on `session_shutdown`.
+
+## Suggested Patterns
+
+The suggested pattern is surface-specific:
+
+| Surface                         | Example request              | Suggested session pattern |
+| ------------------------------- | ---------------------------- | ------------------------- |
+| bash                            | `git status --short`         | `git status *`            |
+| mcp (qualified)                 | `exa:search`                 | `exa:*`                   |
+| mcp (munged)                    | `exa_search`                 | `exa_*`                   |
+| skill                           | `librarian`                  | `librarian`               |
+| path                            | `src/.env`                   | `src/*`                   |
+| tool with path (read, write, …) | `read` for `src/foo.ts`      | `src/*`                   |
+| tool catch-all                  | `read` (no extractable path) | `*`                       |
+| external_directory              | `/other/project/src/foo.ts`  | `/other/project/src/*`    |
+
+## Bash Arity Table
+
+Bash pattern suggestions use a curated arity dictionary (`src/bash-arity.ts`) to determine how many tokens define the "human-understandable subcommand."
+Longest matching prefix wins, so `npm run` (arity 3) takes precedence over `npm` (arity 2).
+Unknown commands default to arity 1 (first word only).
+
+| Example command       | Arity entry matched  | Suggested pattern     |
+| --------------------- | -------------------- | --------------------- |
+| `git checkout main`   | `git` → 2            | `git checkout *`      |
+| `npm run dev`         | `npm run` → 3        | `npm run dev*`        |
+| `npm install lodash`  | `npm` → 2            | `npm install *`       |
+| `docker compose up`   | `docker compose` → 3 | `docker compose up *` |
+| `rm -rf node_modules` | `rm` → 1             | `rm *`                |
+| `mytool --verbose`    | (unknown) → 1        | `mytool *`            |
+
+The arity table covers common CLI tools including git, npm/pnpm/yarn/bun, docker, cargo, go, kubectl, gh, and others.
+To add an entry, open `src/bash-arity.ts` and add a key/arity pair to the `ARITY` object.
+Put the most specific multi-word prefix first (e.g. `"npm run": 3`) before the shorter fallback (`"npm": 2`).
+
+## Review Log Entries
+
+The review log records session approval decisions:
+
+- `resolution: "approved_for_session"` — when the user approves with the session pattern
+- `resolution: "session_approved"` — when a later request is matched by an existing session rule
+
+## Permission Prompt Summaries
+
+When a tool permission resolves to `ask`, the prompt is designed to be readable enough for an informed approval decision:
+
+- `bash` prompts show the command and matched bash pattern when available.
+- `mcp` prompts show the derived MCP target and matched rule when available.
+- Built-in file tools show concise summaries, such as the target path and edit/write line counts, instead of raw multiline JSON.
+- Unknown or third-party extension tools show a bounded single-line JSON preview of the input so users are not asked to approve a blind tool name.
+
+Example edit approval prompt:
+
+```text
+Current agent requested tool 'edit' for '.gitignore' (1 replacement: edit #1 replaces 5 lines with 2 lines). Allow this call?
+```

package/docs/subagent-integration.md

@@ -0,0 +1,102 @@
+# Subagent Integration
+
+## Native integration with `@gotgenes/pi-subagents`
+
+[`@gotgenes/pi-subagents`](https://github.com/gotgenes/pi-subagents) is the only subagent extension with native permission-system integration.
+It publishes a child-execution lifecycle on `pi.events`; this package subscribes (see `src/subagent-lifecycle-events.ts`) and registers every in-process child session with the `SubagentSessionRegistry` on the `subagents:child:session-created` event — emitted before `bindExtensions()` fires — and unregisters it on `subagents:child:disposed`.
+Because the event bus dispatches synchronously, the synchronous registration completes before binding proceeds.
+This inverts the former dependency direction: the core no longer looks up this package's service ([ADR-0002] / pi-subagents [#261]).
+
+The `SubagentSessionRegistry` is backed by a process-global singleton (`globalThis` + `Symbol.for()`), accessed via `getSubagentSessionRegistry()` in `src/subagent-registry.ts`.
+This is necessary because each session's `ResourceLoader` creates its own `pi.events` bus: the parent emits `subagents:child:session-created` on the parent's bus, and only the parent's permission-system instance receives it.
+The child's jiti instance runs on a separate bus and never receives the event — but because both instances call `getSubagentSessionRegistry()`, they share the same store, so the parent's registration is visible to the child.
+
+The integration enables:
+
+1. **Deterministic child detection** — `isSubagentExecutionContext()` hits the process-global registry on the first check, no env-var or filesystem heuristics needed.
+2. **Per-agent policy enforcement** - the permission system's `before_agent_start` handler resolves the agent name from the `<active_agent>` system-prompt tag and applies per-agent `permission:` frontmatter overrides.
+3. **`ask`-state forwarding** - when a child triggers an `ask` permission, the request forwards to the parent session's UI through the existing polling mechanism.
+   The parent approves or denies, and the child resumes.
+
+No configuration is required - the integration is automatic when both extensions are installed.
+When `@gotgenes/pi-permission-system` is not installed, `@gotgenes/pi-subagents` emits its lifecycle events with no subscriber - a harmless no-op.
+
+## Permission Forwarding
+
+When a delegated or routed subagent runs without direct UI access, `ask` permissions can still be enforced by forwarding the confirmation request through Pi session directories.
+The main interactive session polls for forwarded requests, shows the confirmation prompt, writes the response, and the subagent resumes once that decision is available.
+
+This keeps `ask` policies usable even when the original permission check happens inside a non-UI execution context.
+
+For in-process child sessions, detection and forwarding use the event-driven registration described above.
+The [Prompt Forwarding RPC](cross-extension-api.md#prompt-forwarding-rpc) remains available as an alternative for extensions that cannot use the service accessor.
+
+---
+
+## Coexistence with Other Subagent Extensions
+
+Subagent extensions implement their own tool restriction mechanisms.
+These compose correctly with the permission system because the two operate at different layers: **visibility** (subagent extension) and **policy** (permission system).
+
+### The Two-Layer Model
+
+```text
+┌─────────────────────────────────────────────────────┐
+│  Layer 1 - Visibility  (subagent extension)          │
+│  Controls which tools are registered / active        │
+│  before the agent session starts.                    │
+├─────────────────────────────────────────────────────┤
+│  Layer 2 - Policy  (pi-permission-system)            │
+│  Controls allow / ask / deny decisions on every      │
+│  tool call, bash command, MCP operation, etc.        │
+└─────────────────────────────────────────────────────┘
+```
+
+### Known Subagent Extensions
+
+| Extension                                                                           | Type       | Permission integration           | Frontmatter key                    |
+| ----------------------------------------------------------------------------------- | ---------- | -------------------------------- | ---------------------------------- |
+| [@gotgenes/pi-subagents](https://github.com/gotgenes/pi-subagents)                  | in-process | ✓ Native (registry + forwarding) | `disallowed_tools:` (CSV denylist) |
+| [tintinweb/pi-subagents](https://github.com/tintinweb/pi-subagents)                 | in-process | ✗ No registration                | `disallowed_tools:` (CSV denylist) |
+| [nicobailon/pi-subagents](https://github.com/nicobailon/pi-subagents)               | subprocess | ✗ Missing env vars               | `tools:` (CSV allowlist)           |
+| [HazAT/pi-interactive-subagents](https://github.com/HazAT/pi-interactive-subagents) | subprocess | ✗ Missing env vars               | `deny-tools:` (CSV denylist)       |
+
+Process-based subagent extensions (nicobailon, HazAT) spawn child processes but do not set the `PI_SUBAGENT_PARENT_SESSION` env var that the permission system needs for `ask`-state forwarding.
+Without that env var, `ask` permissions in child processes are auto-denied.
+See [guides/permission-frontmatter-for-subagent-extensions.md](guides/permission-frontmatter-for-subagent-extensions.md) for the convention that subagent extension authors should follow.
+
+The upstream `tintinweb/pi-subagents` (which `@gotgenes/pi-subagents` forks) does not publish the `subagents:child:session-created` lifecycle event, so it lacks deterministic child detection and `ask`-state forwarding.
+
+### Interaction Rules
+
+1. **Hidden tool → permission system never sees it.**
+   If a subagent extension removes a tool from the active set, the permission system receives no registration or call event for that tool.
+   The permission policy for that tool is irrelevant - it is already gone.
+
+2. **Denied tool → hidden regardless of the subagent extension's allowlist.**
+   If the permission system denies a tool (via `deny` policy or tool filtering), it is removed from the active set before the agent starts.
+   A `tools:` allowlist in a subagent extension cannot restore a tool that the permission system has already hidden.
+
+3. **The two denylist mechanisms are additive, not conflicting.**
+   A tool blocked by either layer stays blocked.
+   Neither layer can silently re-enable what the other has blocked.
+
+### `permission:` Frontmatter is Exclusive to This Extension
+
+The `permission:` key in an agent's YAML frontmatter is read exclusively by `pi-permission-system`.
+It has no interaction with the `tools:`, `disallowed_tools:`, or `deny-tools:` keys consumed by subagent extensions.
+You can freely use both in the same agent file:
+
+```yaml
+---
+# Subagent extension: allow only bash and read in the child session
+tools: bash,read
+# pi-permission-system: still enforce ask on bash within those allowed tools
+permission:
+  bash: ask
+---
+```
+
+In this example the subagent extension restricts visibility to `bash` and `read`, and the permission system then gates every `bash` call with an `ask` prompt - both rules apply independently.
+
+[ADR-0002]: https://github.com/gotgenes/pi-packages/blob/main/packages/pi-subagents/docs/decisions/0002-extensions-on-a-minimal-core.md

package/docs/troubleshooting.md

@@ -0,0 +1,53 @@
+# Troubleshooting
+
+## Common Issues
+
+| Problem                                                           | Cause                                                             | Solution                                                                                                                                          |
+| ----------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Config not applied (everything asks)                              | File not found or parse error                                     | Verify the global config at `~/.pi/agent/extensions/pi-permission-system/config.json` (respects `PI_CODING_AGENT_DIR`); check for trailing commas |
+| Per-agent override not applied                                    | Frontmatter parsing issue                                         | Ensure `---` delimiters at file top; keep YAML simple; restart session                                                                            |
+| Tool blocked as unregistered                                      | Unknown tool name                                                 | Use a registered `mcp` tool for server tools: `{ "tool": "server:tool" }`                                                                         |
+| `/skill:<name>` blocked                                           | Deny policy or confirmation unavailable                           | Check merged `skill` policy (global/project/agent layers). `ask` still requires UI or forwarded confirmation.                                     |
+| External file path blocked                                        | `external_directory` is `ask` without UI or `deny`                | Allow/ask the permission or keep file tools inside the active working directory.                                                                  |
+| Spurious external-path prompt for `cd <subdir> && grep … ../path` | Relative path was resolved against cwd instead of the `cd` target | Fixed in current version — paths after a leading `cd <subdir> &&` are resolved against the cd target, matching actual shell behavior.             |
+| Permission prompt is too verbose                                  | Generic extension tool input is large                             | Built-in file tools are summarized automatically; third-party tools are capped to a bounded one-line JSON preview.                                |
+
+## Diagnostic Logging
+
+Enable `"debugLog": true` in your config to write verbose diagnostics to `logs/pi-permission-system-debug.jsonl`.
+
+On every session start, the extension emits a `config.resolved` entry to both logs listing the resolved config paths and whether each exists.
+This makes it easy to verify which files the extension actually loaded:
+
+```jsonc
+{
+  "event": "config.resolved",
+  "globalConfigPath": "/…/.pi/agent/extensions/pi-permission-system/config.json",
+  "globalConfigExists": true,
+  "projectConfigPath": "/…/my-project/.pi/extensions/pi-permission-system/config.json",
+  "projectConfigExists": false,
+  "agentsDir": "/…/.pi/agent/agents",
+  "agentsDirExists": true,
+  "projectAgentsDir": "/…/my-project/.pi/agents",
+  "projectAgentsDirExists": false,
+  "legacyGlobalPolicyDetected": false,
+  "legacyProjectPolicyDetected": false,
+  "legacyExtensionConfigDetected": false
+}
+```
+
+## Threat Model
+
+**Goal:** Enforce policy at the host level, not the model level.
+
+**What this stops:**
+
+- Agent calling tools it shouldn't use (e.g., `write`, dangerous `bash`)
+- Tool switching attempts (calling non-existent tool names)
+- Accidental escalation via skill loading
+- Unapproved path-bearing tool access outside the active working directory when `external_directory` is `ask` or `deny`
+
+**Limitations:**
+
+- If a dangerous action is possible via an allowed tool, policy must explicitly restrict it
+- This is a permission decision layer, not a sandbox — for true isolation see [Agent Sandboxes](https://engine.build/lab/agent-sandboxes)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "18.0.2",
+  "version": "18.1.1",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {
@@ -15,6 +15,10 @@
     "test",
     "config/config.example.json",
     "schemas/permissions.schema.json",
+    "docs/*.md",
+    "docs/guides",
+    "docs/migration",
+    "docs/assets",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"

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

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

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

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

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

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