@gotgenes/pi-permission-system 18.1.0 → 18.1.2

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.1.0",
+  "version": "18.1.2",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {
@@ -12,9 +12,12 @@
   },
   "files": [
     "src",
-    "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/access-path.ts

@@ -118,10 +118,35 @@ export class AccessPath {
    * unknown (a relative bash token after a non-literal `cd`).
    *
    * Carries no canonical alias and no absolute resolution — `matchValues()` is
-   * `[literal]` (or `[]` when empty) and `boundaryValue()` is `""` — so no
-   * spurious absolute or symlink-resolved rule can match (#393).
+   * `[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).
+   */
+  static forLiteral(
+    literal: string,
+    matchAliases: readonly string[] = [],
+  ): AccessPath {
+    if (!literal) return new AccessPath("", [], "");
+    const aliases = [...new Set([literal, ...matchAliases.filter(Boolean)])];
+    return new AccessPath(literal, aliases, "");
+  }
+
+  /**
+   * Build an `AccessPath` for a Git Bash/MSYS device path (`/dev/null`,
+   * `/dev/std{in,out,err}`) seen in a bash command on a win32 host.
+   *
+   * The token names an MSYS runtime device, not a filesystem path, so it is
+   * preserved verbatim across all three representations — `value()`,
+   * `boundaryValue()`, and `matchValues()` are the device path itself, never
+   * `win32.resolve`-mangled into `c:\dev\null`. The identical lexical and
+   * canonical forms let the boundary check reach `isSafeSystemPath` (so the
+   * device never triggers `external_directory`) while a config rule still
+   * matches the path as typed.
    */
-  static forLiteral(literal: string): AccessPath {
-    return new AccessPath(literal, literal ? [literal] : [], "");
+  static forDevice(devicePath: string): AccessPath {
+    return new AccessPath(devicePath, [devicePath], devicePath);
   }
 }

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

@@ -315,23 +315,34 @@ export class BashPathResolver {
    * Returns `base` unchanged unless the command is `cd`:
    *
    * - `cd /abs` (absolute literal) → a fresh known base, recovering from an
-   *   earlier unknown base.
+   *   earlier unknown base. On win32 a drive-mount target (`cd /c/x`) folds to
+   *   its translated Windows base, while a non-mount POSIX absolute
+   *   (`cd /tmp`) is not deterministically resolvable and yields unknown (#533).
    * - `cd rel` (relative literal) → fold into a known base, or stay unknown if
    *   the base was already unknown.
    * - `cd "$DIR"` / `cd $(…)` / `cd -` / bare `cd` / `cd ~…` (non-literal) →
    *   unknown.
+   *
+   * The target's platform/MSYS interpretation is delegated to the
+   * {@link PathNormalizer}; this method owns only the base-folding state.
    */
   private foldCd(commandNode: TSNode, base: EffectiveBase): EffectiveBase {
     if (extractCommandName(commandNode) !== "cd") return base;
     const target = cdLiteralTarget(commandNode);
     if (target === null) return UNKNOWN_BASE;
-    if (this.normalizer.isAbsolute(target))
-      return { kind: "known", offset: target };
-    if (base.kind === "unknown") return UNKNOWN_BASE;
-    return {
-      kind: "known",
-      offset: this.normalizer.joinBase(base.offset, target),
-    };
+    const interpreted = this.normalizer.interpretBashCdTarget(target);
+    switch (interpreted.kind) {
+      case "absolute":
+        return { kind: "known", offset: interpreted.value };
+      case "unknown":
+        return UNKNOWN_BASE;
+      case "relative":
+        if (base.kind === "unknown") return UNKNOWN_BASE;
+        return {
+          kind: "known",
+          offset: this.normalizer.joinBase(base.offset, target),
+        };
+    }
   }
 
   // ── Projection ─────────────────────────────────────────────────────────
@@ -376,19 +387,29 @@ export class BashPathResolver {
         base.kind === "known"
           ? this.normalizer.resolveBase(base.offset)
           : undefined;
-      const accessPath = this.normalizer.forPath(candidate, { resolveBase });
+      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, but the returned value is the lexical form so
-      // config patterns match the path as the user typed it (#418).
+      // (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();
-
-      if (
-        this.normalizer.isOutsideWorkingDirectory(lexical) &&
-        !seen.has(canonical)
-      ) {
-        seen.add(canonical);
+      // 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);
       }
     }
@@ -450,7 +471,7 @@ export class BashPathResolver {
       base.kind === "known"
         ? this.normalizer.resolveBase(base.offset)
         : undefined;
-    return this.normalizer.forPath(candidate, { resolveBase });
+    return this.normalizer.forBashToken(candidate, { resolveBase });
   }
 
   /**