@gotgenes/pi-permission-system 29.3.0 → 30.1.0

package/CHANGELOG.md

@@ -5,6 +5,34 @@ 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).
 
+## [30.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v30.0.0...pi-permission-system-v30.1.0) (2026-09-02)
+
+
+### Features
+
+* **pi-permission-system:** publish isToolFullyDenied for cross-extension tool pre-filtering ([#815](https://github.com/gotgenes/pi-packages/issues/815)) ([4345b19](https://github.com/gotgenes/pi-packages/commit/4345b199e5a33427e47bb80f9c16cb78fb1e7fbf)), closes [#815](https://github.com/gotgenes/pi-packages/issues/815)
+
+### Bug Fixes
+
+* **pi-permission-system:** stop hiding a tool whose surface has a reachable non-deny rule ([#815](https://github.com/gotgenes/pi-packages/issues/815)) ([ce46b6c](https://github.com/gotgenes/pi-packages/commit/ce46b6c7b9f4c901d6a035f3be6e334f77a76e95)), closes [#815](https://github.com/gotgenes/pi-packages/issues/815)
+
+### Documentation
+
+* **pi-permission-system:** describe tool exposure as surface reachability ([#815](https://github.com/gotgenes/pi-packages/issues/815)) ([71d9696](https://github.com/gotgenes/pi-packages/commit/71d96969e5c33ecc0f38b0a43b0bdaf267622000))
+* **pi-permission-system:** stop recommending getToolPermission for tool pre-filtering ([#815](https://github.com/gotgenes/pi-packages/issues/815)) ([fdf0a38](https://github.com/gotgenes/pi-packages/commit/fdf0a383d5419eaded4b6277ead8264e23aa281d))
+
+## [30.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v29.3.0...pi-permission-system-v30.0.0) (2026-09-02)
+
+
+### Features
+
+* **pi-permission-system:** **breaking:** record a session approval's surface per pattern ([499444d](https://github.com/gotgenes/pi-packages/commit/499444df5a21e289409cbf3b360033a13d0eba56)), closes [#810](https://github.com/gotgenes/pi-packages/issues/810)
+* **pi-permission-system:** grant each external path only the direction its command proved ([aa38c74](https://github.com/gotgenes/pi-packages/commit/aa38c746bf9b82ed0dc96217cf4789aae9f090cd)), closes [#810](https://github.com/gotgenes/pi-packages/issues/810)
+
+### Documentation
+
+* **pi-permission-system:** document per-pattern approval surfaces and mark Phase 14 Step 10 ([5511450](https://github.com/gotgenes/pi-packages/commit/551145024364cc794b3c48256362d69971aa69de)), closes [#810](https://github.com/gotgenes/pi-packages/issues/810)
+
 ## [29.3.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v29.2.0...pi-permission-system-v29.3.0) (2026-09-02)
 
 

package/README.md

@@ -210,6 +210,7 @@ Approve-and-steer, edit diffs, and risk explanations → a downstream package ov
 | [docs/migration/0746-review-log-fields.md](docs/migration/0746-review-log-fields.md)                                           | Review-log fields (breaking) — `message` replaced by request facts, and the `reviewLogFieldMaxWidth` bound           |
 | [docs/migration/0794-keyed-service-locator.md](docs/migration/0794-keyed-service-locator.md)                                   | Keyed service locator (breaking) — `getPermissionsService(sessionId)`, and the repeating ready event                 |
 | [docs/migration/0796-remove-process-root-slot.md](docs/migration/0796-remove-process-root-slot.md)                             | Process-root slot removed (breaking) — `getRootPermissionsService()` and its publish/unpublish pair are gone         |
+| [docs/migration/0810-per-pattern-approval-surfaces.md](docs/migration/0810-per-pattern-approval-surfaces.md)                   | Per-pattern approval surfaces (breaking) — `ForwardedSessionApproval.grants` replaces `surface` + `patterns`         |
 
 ## Development
 

package/dist/public.d.ts

@@ -1,5 +1,19 @@
 import { z } from 'zod';
 
+/**
+ * One session-approval grant: a wildcard pattern approved on one surface.
+ *
+ * A gate proves a direction per accessed path (ADR 0013 §7), so an ask whose
+ * paths disagree records a surface per pattern rather than one for all of them
+ * (#810). This lives in its own module because both the {@link SessionApproval}
+ * value object and the forwarded wire type name it, and those two already
+ * import in one direction.
+ */
+interface ApprovalGrant {
+    readonly surface: string;
+    readonly pattern: string;
+}
+
 declare const permissionStateSchema: z.ZodUnion<readonly [z.ZodLiteral<"allow">, z.ZodLiteral<"deny">, z.ZodLiteral<"ask">]>;
 /** A permission decision. */
 type PermissionState = z.infer<typeof permissionStateSchema>;
@@ -316,16 +330,21 @@ interface PermissionDecisionEvent {
 
 /**
  * The child's session-approval suggestion, relayed to the serving node so a
- * human who grants "the whole session" records the same pattern the child
- * would have recorded locally.
+ * human who grants "the whole session" records the same grants the child would
+ * have recorded locally.
  *
  * A plain data shape (not the `SessionApproval` value object) so it serializes
  * onto the forwarded request; the serving node rebuilds a `SessionApproval`
- * from it via `SessionApproval.multiple`.
+ * from it via `SessionApproval.forGrants`.
+ *
+ * Each grant carries its own surface (#810). The pre-#810 shape — one
+ * `surface` plus a `patterns` list — is rejected by the reader rather than
+ * normalized, so a version-skewed pair drops the suggestion and the serving
+ * dialog offers no whole-session scope; the requesting child still records its
+ * own grant, so the failure is narrow in both directions.
  */
 interface ForwardedSessionApproval {
-    surface: string;
-    patterns: readonly string[];
+    grants: readonly ApprovalGrant[];
 }
 /**
  * The child-fixed facts a gate emits: the surface it evaluated and the match
@@ -512,13 +531,17 @@ interface PermissionQuery {
      */
     checkPermission(surface: string, value?: string, agentName?: string): PermissionCheckResult;
     /**
-     * Query the tool-level permission state for pre-filtering tools before
-     * creating a child session.
+     * Query a surface's catch-all permission state — its blanket policy.
      *
      * Returns `"deny"` | `"allow"` | `"ask"` based on the composed policy.
      * Does not consider command-level rules (e.g. per-bash-command patterns) —
      * use `checkPermission` for runtime invocation gates.
      *
+     * This is **not** the question to ask when pre-filtering a tool list: a
+     * partially permissive surface such as `bash: {"*": "deny", "git *": "ask"}`
+     * answers `"deny"` here while `git status` would still be asked about. Use
+     * {@link PermissionsService.isToolFullyDenied} for that.
+     *
      * @param toolName  - Tool name (e.g. `"bash"`, `"read"`, `"my-extension:tool"`).
      * @param agentName - Optional agent name for per-agent policy resolution.
      */
@@ -538,6 +561,23 @@ interface PermissionQuery {
  * rules internally.
  */
 interface PermissionsService extends PermissionQuery {
+    /**
+     * Whether every value under a tool's surface resolves to `deny`.
+     *
+     * This is the question to ask before withholding a tool from a child
+     * session's tool list, and it is not `getToolPermission`: that reports the
+     * surface's own catch-all, so a partially permissive surface such as
+     * `bash: {"*": "deny", "git *": "ask"}` reads as `"deny"` while `git status`
+     * would still be asked about.
+     *
+     * Rule ordering is honored (last-match-wins), so an exception written *after*
+     * a `deny` catch-all keeps the tool reachable and one written *before* it
+     * does not.
+     *
+     * @param toolName  - Tool name (e.g. `"bash"`, `"read"`, `"my-extension:tool"`).
+     * @param agentName - Optional agent name for per-agent policy resolution.
+     */
+    isToolFullyDenied(toolName: string, agentName?: string): boolean;
     /**
      * Register a custom preview formatter for a specific tool name.
      *

package/docs/configuration.md

@@ -295,6 +295,10 @@ A string value is a catch-all for that surface.
 Unknown or absent tools are not required in the config.
 If a tool is not registered at runtime, this extension blocks it before permission checks run.
 
+A tool is withheld from the model entirely only when **every** pattern configured under its surface resolves to `deny`.
+So `"bash": "deny"` hides the tool, while `"bash": { "*": "deny", "git *": "ask" }` keeps it visible — the agent can attempt a `git` command and be prompted, and everything else is denied at the gate.
+Ordering follows the same last-match-wins rule as every other lookup: an exception written *after* the `deny` catch-all is reachable, while one written *before* it is shadowed and the tool is hidden.
+
 #### Path Patterns for File Tools
 
 For path-bearing tools (`read`, `write`, `edit`, `find`, `grep`, `ls`), an object value maps file-path patterns to actions.
@@ -993,6 +997,9 @@ Avoid arrays, multi-line scalars, and YAML anchors.
 }
 ```
 
+The Bash tool stays visible to the agent here: the three `git` patterns are written after the `deny` catch-all, so they are reachable.
+Every other command is denied at the gate.
+
 ### Read-Only Bash Command Allowlist
 
 The [Read-Only Mode](#read-only-mode) recipe above gates *tools*; this one gates the *bash* surface.
@@ -1142,6 +1149,7 @@ Additional behaviors:
 
 - Unknown/unregistered tools are blocked before permission checks (prevents bypass attempts)
 - Tool filtering is restrict-only: the active set starts from pi's already-active tools (`pi.getActiveTools()`) and only ever has denied tools removed — the permission system never activates a tool pi left off by default (e.g. `find`, `grep`, `ls`)
+- A tool is removed only when every value under its surface resolves to `deny`; a surface with any reachable `allow` or `ask` pattern stays available (see [Tool Surfaces](#tool-surfaces))
 - The `Available tools:` system prompt section is narrowed to match the filtered active tool set: denied tools' lines are dropped, the rest are kept, and the section is removed entirely only when no tool is allowed
 - The narrowed prompt is recomputed and returned on every turn but is byte-stable for a stable policy/agent, so the provider's prompt cache (tools + system prefix) is preserved rather than rewritten each turn
 - Extension-provided tools like `task`, `mcp`, and third-party tools are handled by exact registered name

package/docs/cross-extension-api.md

@@ -69,9 +69,12 @@ interface PermissionsService {
     agentName?: string,
   ): PermissionCheckResult;
 
-  /** Query tool-level permission state for pre-filtering before session creation. */
+  /** Query a surface's catch-all permission state — its blanket policy. */
   getToolPermission(toolName: string, agentName?: string): PermissionState;
 
+  /** Whether every value under a tool's surface resolves to deny; use this to pre-filter a tool list. */
+  isToolFullyDenied(toolName: string, agentName?: string): boolean;
+
   /**
    * Register a custom preview formatter for a specific tool name.
    * Returns a disposer that unregisters the formatter.
@@ -130,14 +133,27 @@ Decomposition needs the tree-sitter parser, which is warmed at `before_agent_sta
 #### `getToolPermission`
 
 Returns `"allow"` | `"deny"` | `"ask"` for a tool name without considering command-level rules.
-Use this to pre-filter a tool list before creating a child session — it avoids calling `checkPermission` per tool and interpreting the full result.
+It reports the surface's own catch-all, so it answers what a surface's blanket policy is.
 
 ```typescript
-const denied = tools.filter(
-  (t) => permissions.getToolPermission(t, agentName) === "deny",
-);
+const blanketPolicy = permissions.getToolPermission("bash", agentName);
 ```
 
+This is not the question to ask when pre-filtering a tool list — use `isToolFullyDenied` for that.
+A surface written as `bash: {"*": "deny", "git *": "ask"}` reports `"deny"` here while `git status` would still be asked about.
+
+#### `isToolFullyDenied`
+
+Returns `true` when every value under the tool's surface resolves to `deny`, and `false` when anything at all could get through.
+Use this to pre-filter a tool list before creating a child session — it avoids calling `checkPermission` per tool and interpreting the full result, and unlike `getToolPermission` it does not withhold a tool that is only partially restricted.
+
+```typescript
+const usable = tools.filter((t) => !permissions.isToolFullyDenied(t, agentName));
+```
+
+Rule ordering is honored (last-match-wins), so an exception written after a `deny` catch-all keeps the tool reachable while one written before it does not.
+It considers config-layer rules only; a runtime session approval does not change the answer.
+
 #### `registerToolInputFormatter`
 
 Register a custom preview formatter for a specific tool name.

package/docs/migration/0810-per-pattern-approval-surfaces.md

@@ -0,0 +1,76 @@
+# Migration guide: a session approval carries a surface per pattern
+
+Starting with the release that closes #810, a session-scoped approval records each of its patterns on the surface that pattern's own access was proven on, instead of recording every pattern on one shared surface.
+
+This is a **breaking change** on one surface, with a second, milder effect during a version-skew window.
+
+| Surface                                                           | Break                                            | Who is affected                                                             |
+| ----------------------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------- |
+| `ForwardedSessionApproval` (a field of `PromptPermissionDetails`) | `surface` and `patterns` removed; `grants` added | Any extension whose registered `Authorizer` reads `details.sessionApproval` |
+| `ForwardedPermissionRequest.sessionApproval` (on-disk wire)       | the old shape is rejected, not normalized        | Anyone running **out-of-process** subagents across mixed versions           |
+
+## What changed, and why it is not just a rename
+
+A permission gate proves a direction for each path it sees: reading `/outside/a.ts` proves a read, redirecting into `/elsewhere/b.ts` proves a write, and an unclassifiable access proves neither.
+The bash external-directory gate aggregates every uncovered path into **one** prompt, so it built one approval covering all of them.
+
+Because that approval held a single surface, it could only be as narrow as the whole prompt agreed.
+A command touching paths in two directions fell back to the direction-neutral family name, which grants both directions.
+So approving
+
+```bash
+cat /outside/a.ts > /elsewhere/b.ts
+```
+
+for the session also granted writes under `/outside` and reads under `/elsewhere` — wider than the prompt named.
+
+Each pattern now carries its own surface, so that approval grants a read under `/outside` and a write under `/elsewhere`, and nothing else.
+
+Two paths in the **same** directory still grant both directions there.
+The recorded pattern is the path's directory scope, so both paths produce the same pattern and the two grants land on the same directory in opposite directions — which is exactly what the prompt showed.
+
+## If you register an `Authorizer`
+
+A chain link receives `PromptPermissionDetails`, whose optional `sessionApproval` field changed shape:
+
+```typescript
+// Before
+const surface = details.sessionApproval?.surface;
+const first = details.sessionApproval?.patterns[0];
+
+// After
+const first = details.sessionApproval?.grants[0];
+const surface = first?.surface;
+const pattern = first?.pattern;
+```
+
+`grants` is a non-empty array of `{ surface, pattern }`, in the order the gate produced them.
+Read each entry's own `surface` — do not assume the first one describes the rest, which is the assumption this change exists to remove.
+
+Most links never touch this field; it exists so a serving node can offer a whole-session grant scope, and links that only rule on the request are unaffected.
+
+## If you run out-of-process subagents
+
+A subagent with no UI writes its ask to a request file that its parent session reads.
+The suggestion travels in that file, and the reader accepts only the new shape — the old one is rejected rather than converted.
+
+That matters only while a parent and a child are running **different** versions of this extension, which happens when an upgrade lands on disk while a parent session is already loaded.
+An in-process child shares its parent's loaded extension and can never skew.
+
+The effect is symmetric and bounded:
+
+- The request is still accepted, and the ask still prompts.
+  Only the suggestion is dropped.
+- With no suggestion, the prompt shows its base four options instead of asking whether the grant covers the whole serving session.
+- Choosing "for this session" then records on the **requesting subagent** — the least-privilege default the two-step dialog already pre-selected.
+
+So a skewed pair loses an affordance; it never produces a wider grant, and there is no upgrade ordering to observe.
+Restart the serving session after upgrading to restore the scope step.
+
+Carrying the old shape alongside the new was considered and declined.
+The wire file turned out to be the smaller of the two breaks: the type is reachable from this package's published type declarations, so replacing its fields breaks a consumer at compile time regardless of what any file on disk contains — and a compatibility shape would have had to be maintained forever to avoid a break that had already happened.
+
+## Related decisions
+
+- [ADR 0006 — Grant-scope selection on forwarded approvals](https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/decisions/0006-forwarded-grant-scope-selection.md), amended by this change.
+- [ADR 0013 — The permission policy model](https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/decisions/0013-permission-policy-model.md), §3–§4 for the read/write axis and §9 for a session approval as a policy source.

package/package.json

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

package/src/approval-grant.ts

@@ -0,0 +1,13 @@
+/**
+ * One session-approval grant: a wildcard pattern approved on one surface.
+ *
+ * A gate proves a direction per accessed path (ADR 0013 §7), so an ask whose
+ * paths disagree records a surface per pattern rather than one for all of them
+ * (#810). This lives in its own module because both the {@link SessionApproval}
+ * value object and the forwarded wire type name it, and those two already
+ * import in one direction.
+ */
+export interface ApprovalGrant {
+  readonly surface: string;
+  readonly pattern: string;
+}

package/src/authority/forwarded-request-server.ts

@@ -350,16 +350,11 @@ export class ForwardedRequestServer implements InboxProcessor {
       return decision;
     }
     if (request.sessionApproval) {
-      this.recorder.recordSessionApproval(
-        SessionApproval.multiple(
-          request.sessionApproval.surface,
-          request.sessionApproval.patterns,
-        ),
-      );
+      const { grants } = request.sessionApproval;
+      this.recorder.recordSessionApproval(SessionApproval.forGrants(grants));
       this.logger.review("forwarded_permission.session_recorded", {
         ...logDetails,
-        surface: request.sessionApproval.surface,
-        patterns: request.sessionApproval.patterns,
+        grants,
       });
     }
     return {

package/src/authority/forwarding-io.ts

@@ -9,6 +9,7 @@ import {
   writeFileSync,
 } from "node:fs";
 
+import type { ApprovalGrant } from "#src/approval-grant";
 import { asDecisionSource } from "#src/authority/decision-source";
 import { isPermissionDecisionState } from "#src/authority/permission-dialog";
 import {
@@ -49,12 +50,34 @@ function asNullableDisplayString(value: unknown): string | null | undefined {
   return undefined;
 }
 
+/** Narrow an unknown value to an `ApprovalGrant`, or `undefined`. */
+function asApprovalGrant(value: unknown): ApprovalGrant | undefined {
+  if (typeof value !== "object" || value === null) {
+    return undefined;
+  }
+  const candidate = value as Partial<ApprovalGrant>;
+  if (
+    typeof candidate.surface !== "string" ||
+    candidate.surface.length === 0 ||
+    typeof candidate.pattern !== "string"
+  ) {
+    return undefined;
+  }
+  return { surface: candidate.surface, pattern: candidate.pattern };
+}
+
 /**
  * Narrow an unknown value to a `ForwardedSessionApproval`, or `undefined`.
  *
  * Tolerant read: the child's session-approval suggestion is optional (absent
- * on an older child) and only accepted when well-formed — a non-empty surface
- * and an all-string patterns array.
+ * on an older child) and only accepted when well-formed — a non-empty `grants`
+ * array whose every entry names a non-empty surface and a pattern. The
+ * pre-#810 shape (`surface` plus `patterns`) is rejected rather than
+ * normalized, so a version-skewed request drops the suggestion and the serving
+ * dialog offers no whole-session scope.
+ *
+ * An empty `grants` array is rejected too: it would record nothing while still
+ * writing a `forwarded_permission.session_recorded` entry claiming it had.
  */
 function asForwardedSessionApproval(
   value: unknown,
@@ -63,15 +86,16 @@ function asForwardedSessionApproval(
     return undefined;
   }
   const candidate = value as Partial<ForwardedSessionApproval>;
-  if (
-    typeof candidate.surface !== "string" ||
-    candidate.surface.length === 0 ||
-    !Array.isArray(candidate.patterns) ||
-    !candidate.patterns.every((pattern) => typeof pattern === "string")
-  ) {
+  if (!Array.isArray(candidate.grants) || candidate.grants.length === 0) {
     return undefined;
   }
-  return { surface: candidate.surface, patterns: [...candidate.patterns] };
+  const grants: ApprovalGrant[] = [];
+  for (const entry of candidate.grants) {
+    const grant = asApprovalGrant(entry);
+    if (!grant) return undefined;
+    grants.push(grant);
+  }
+  return { grants };
 }
 
 /**

package/src/authority/local-user-authorizer.ts

@@ -72,13 +72,13 @@ export class LocalUserAuthorizer implements TerminalAuthorizer {
 function buildRequestOptions(
   details: PromptPermissionDetails,
 ): RequestPermissionOptions | undefined {
-  const pattern = details.sessionApproval?.patterns[0];
-  if (details.forwarding && details.sessionApproval && pattern) {
+  const grant = details.sessionApproval?.grants[0];
+  if (details.forwarding && grant) {
     return {
       sessionScope: buildForwardedScopeLabels(
         details.forwarding.requesterAgentName,
-        details.sessionApproval.surface,
-        pattern,
+        grant.surface,
+        grant.pattern,
       ),
     };
   }

package/src/authority/permission-forwarding.ts

@@ -1,4 +1,5 @@
 import { join } from "node:path";
+import type { ApprovalGrant } from "#src/approval-grant";
 import type { DecisionSource } from "#src/authority/decision-source";
 import type { PermissionUiPromptSource } from "#src/permission-events";
 import type { PromptPayload } from "#src/presentation/prompt-payload";
@@ -83,16 +84,21 @@ export interface ForwardedPromptDisplay {
 
 /**
  * The child's session-approval suggestion, relayed to the serving node so a
- * human who grants "the whole session" records the same pattern the child
- * would have recorded locally.
+ * human who grants "the whole session" records the same grants the child would
+ * have recorded locally.
  *
  * A plain data shape (not the `SessionApproval` value object) so it serializes
  * onto the forwarded request; the serving node rebuilds a `SessionApproval`
- * from it via `SessionApproval.multiple`.
+ * from it via `SessionApproval.forGrants`.
+ *
+ * Each grant carries its own surface (#810). The pre-#810 shape — one
+ * `surface` plus a `patterns` list — is rejected by the reader rather than
+ * normalized, so a version-skewed pair drops the suggestion and the serving
+ * dialog offers no whole-session scope; the requesting child still records its
+ * own grant, so the failure is narrow in both directions.
  */
 export interface ForwardedSessionApproval {
-  surface: string;
-  patterns: readonly string[];
+  grants: readonly ApprovalGrant[];
 }
 
 /**

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

@@ -8,7 +8,6 @@ import type { PermissionSession } from "#src/permission-session";
 import { resolveSkillPromptEntries } from "#src/skill-prompt-sanitizer";
 import { sanitizeAvailableToolsSection } from "#src/system-prompt-sanitizer";
 import { getToolNameFromValue, type ToolRegistry } from "#src/tool-registry";
-import type { PermissionState } from "#src/types";
 
 /** Minimal subset of BeforeAgentStartEvent used by this handler. */
 interface BeforeAgentStartPayload {
@@ -17,16 +16,17 @@ interface BeforeAgentStartPayload {
 
 /**
  * Pure helper: returns true when the tool should be exposed to the agent.
- * Checks the tool-level permission (not command-level) so that a blanket
- * `bash: deny` hides the tool entirely before any invocation is attempted.
+ *
+ * A tool is withheld only when *every* value under its surface resolves to
+ * `deny`, so a blanket `bash: deny` hides the tool entirely while a partially
+ * permissive `bash: {"*": "deny", "git *": "ask"}` keeps it reachable (#815).
  */
 export function shouldExposeTool(
   toolName: string,
   agentName: string | null,
-  getToolPermission: (toolName: string, agentName?: string) => PermissionState,
+  isToolFullyDenied: (toolName: string, agentName?: string) => boolean,
 ): boolean {
-  const toolPermission = getToolPermission(toolName, agentName ?? undefined);
-  return toolPermission !== "deny";
+  return !isToolFullyDenied(toolName, agentName ?? undefined);
 }
 
 /**
@@ -41,7 +41,7 @@ export function shouldExposeTool(
  * - `turnPrep` — brings the node up to date for the turn before anything reads
  *   session state
  * - `session` — encapsulates all mutable session state and lifecycle operations
- * - `resolver` — owns permission-query surface: `getToolPermission`, skill check
+ * - `resolver` — owns permission-query surface: `isToolFullyDenied`, skill check
  * - `toolRegistry` — Pi tool API subset (getActive + setActive)
  */
 export class AgentPrepHandler {
@@ -70,7 +70,7 @@ export class AgentPrepHandler {
       }
       if (
         shouldExposeTool(toolName, agentName, (t, a) =>
-          this.resolver.getToolPermission(t, a),
+          this.resolver.isToolFullyDenied(t, a),
         )
       ) {
         allowedTools.push(toolName);

package/src/handlers/gates/bash-external-directory.ts

@@ -18,11 +18,11 @@ import type { ToolCallContext } from "./types";
  * Returns a `GateDescriptor` with multi-pattern sessionApproval for uncovered paths.
  *
  * Each path is resolved on the narrowest `external_directory`-family surface
- * its own attributed effect names. The session approval holds one surface for
- * all its patterns, so it narrows only when every uncovered path agrees; a
- * mixed-direction ask falls back to the bare family, which is exactly today's
- * width. Closing that last gap needs `(surface, pattern)` pairs on the
- * approval and its forwarded wire form (#810).
+ * its own attributed effect names, and the session approval records one grant
+ * per uncovered path at that same surface (#810) — so an ask mixing a proven
+ * read with a proven write grants each path only its own direction, never both
+ * on both. Two paths sharing a directory derive the same glob and so grant
+ * both directions there, which is what the prompt showed.
  *
  * The shell command (native `bash` or an aliased shell tool) is read from the
  * injected `BashProgram`, which owns the source text it was parsed from, so
@@ -104,17 +104,15 @@ export function describeBashExternalDirectoryGate(
     surface,
   });
 
-  const patterns = uncoveredEntries.map(({ path }) =>
-    normalizer.approvalPatternFor(path),
-  );
-
   return {
     surface,
     input: {},
     payload,
-    sessionApproval: SessionApproval.multiple(
-      approvalSurfaceFor(uncoveredEntries),
-      patterns,
+    sessionApproval: SessionApproval.forGrants(
+      uncoveredEntries.map((entry) => ({
+        surface: entry.surface,
+        pattern: normalizer.approvalPatternFor(entry.path),
+      })),
     ),
     promptDetails: {
       source: "tool_call",
@@ -143,20 +141,3 @@ export function describeBashExternalDirectoryGate(
     preCheck,
   };
 }
-
-/**
- * The surface one session approval can carry for every uncovered path at once.
- *
- * A {@link SessionApproval} holds one surface for all its patterns, so it can
- * narrow only when the whole ask agrees on a direction. The bare family is the
- * fallback because it sugar-expands onto both members — exactly the width a
- * mixed-direction command is granted today, never wider.
- */
-function approvalSurfaceFor(
-  uncoveredEntries: readonly { readonly surface: string }[],
-): string {
-  const surfaces = new Set(uncoveredEntries.map(({ surface }) => surface));
-  return surfaces.size === 1
-    ? [...surfaces][0]
-    : ("external_directory" as const);
-}

package/src/handlers/gates/runner.ts

@@ -209,7 +209,7 @@ export class GateRunner {
     };
     const gateResult = await applyPermissionGate({
       state: check.state,
-      sessionApproval: descriptor.sessionApproval?.toGateApproval(),
+      canGrantForSession: descriptor.sessionApproval?.isRecordable ?? false,
       promptForApproval: async () => {
         const decision = await this.prompter.escalate({
           requestId,
@@ -230,7 +230,7 @@ export class GateRunner {
 
     // 4. Determine whether session approval was granted
     const hasSessionApproval =
-      gateResult.action === "allow" && gateResult.sessionApproval !== undefined;
+      gateResult.action === "allow" && gateResult.forSession === true;
 
     // 5. Emit decision event
     this.emitDecision(

package/src/permission-gate.ts

@@ -13,7 +13,8 @@ export type PermissionGateResult =
   | {
       action: "allow";
       decidedBy: DecisionSource;
-      sessionApproval?: { surface: string; pattern: string };
+      /** Set when the human granted the ask for the whole session. */
+      forSession?: true;
     }
   | { action: "block"; decidedBy: DecisionSource; reason: string };
 
@@ -30,11 +31,16 @@ export interface PermissionGateParams {
   promptForApproval: () => Promise<PermissionPromptDecision>;
 
   /**
-   * Session approval suggestion to record when the user selects
-   * "for this session". When present and the decision is `approved_for_session`,
-   * the result carries the suggestion back to the caller for recording.
+   * Whether this ask has a session-approval suggestion to record when the user
+   * selects "for this session".
+   *
+   * A boolean rather than the suggestion itself: the gate decides only whether
+   * a whole-session grant happened, and the caller records the suggestion it
+   * already holds. Handing the gate the value would ask it to name a single
+   * representative `(surface, pattern)`, which a multi-pattern approval has no
+   * way to choose (#810).
    */
-  sessionApproval?: { surface: string; pattern: string };
+  canGrantForSession: boolean;
 
   /** Write a review-log entry. Called for deny and ask-but-unavailable paths. */
   writeLog: (event: string, extra: Record<string, unknown>) => void;
@@ -102,12 +108,11 @@ export async function applyPermissionGate(
         reason: messages.refusedReason(decision),
       };
     }
-    if (decision.state === "approved_for_session" && params.sessionApproval) {
-      return {
-        action: "allow",
-        decidedBy,
-        sessionApproval: params.sessionApproval,
-      };
+    if (
+      decision.state === "approved_for_session" &&
+      params.canGrantForSession
+    ) {
+      return { action: "allow", decidedBy, forSession: true };
     }
     return { action: "allow", decidedBy };
   }

package/src/permission-manager.ts

@@ -22,6 +22,7 @@ import {
   evaluateAnyValue,
   evaluateFirst,
   floorAllowsToAsk,
+  isSurfaceFullyDenied,
   rewriteAsksToYolo,
 } from "./rule";
 import { mergeScopesWithOrigins } from "./scope-merge";
@@ -83,6 +84,7 @@ export interface ScopedPermissionManager {
     sessionRules?: Ruleset,
   ): PermissionCheckResult;
   getToolPermission(toolName: string, agentName?: string): PermissionState;
+  isToolFullyDenied(toolName: string, agentName?: string): boolean;
   getConfigIssues(agentName?: string): string[];
 }
 
@@ -268,6 +270,24 @@ export class PermissionManager implements ScopedPermissionManager {
     return evaluate(toolName.trim(), "*", composedRules, this.flavor).action;
   }
 
+  /**
+   * Whether every value under a tool's surface resolves to `deny`.
+   *
+   * This is the question tool exposure asks, and it is not
+   * {@link PermissionManager.getToolPermission} — that reports the surface's
+   * catch-all, so `bash: {"*": "deny", "git *": "ask"}` reads as `deny` even
+   * though `git status` would be asked about (#815).
+   *
+   * Reads the same composed rules the catch-all query does, so it inherits the
+   * fail-closed floor and not the yolo rewrite. Neither matters: one touches
+   * only `allow` and the other only `ask`, so neither can create or remove the
+   * `deny` this answer turns on.
+   */
+  isToolFullyDenied(toolName: string, agentName?: string): boolean {
+    const { composedRules } = this.resolvePermissions(agentName);
+    return isSurfaceFullyDenied(toolName.trim(), composedRules, this.flavor);
+  }
+
   /**
    * Unified resolution entry point — dispatches on intent kind.
    *

package/src/permission-resolver.ts

@@ -126,10 +126,19 @@ export class PermissionResolver
     );
   }
 
+  // Reached only through `LocalPermissionsService`'s structural resolver view,
+  // which fallow cannot trace; `tsc` enforces it at that constructor. The
+  // handler's exposure check moved to `isToolFullyDenied` in #815, leaving this
+  // the published cross-extension catch-all query and nothing else.
+  // fallow-ignore-next-line unused-class-member
   getToolPermission(toolName: string, agentName?: string): PermissionState {
     return this.permissionManager.getToolPermission(toolName, agentName);
   }
 
+  isToolFullyDenied(toolName: string, agentName?: string): boolean {
+    return this.permissionManager.isToolFullyDenied(toolName, agentName);
+  }
+
   getConfigIssues(agentName?: string): string[] {
     return this.permissionManager.getConfigIssues(agentName);
   }

package/src/permissions-service.ts

@@ -25,6 +25,7 @@ import type { PermissionCheckResult, PermissionState } from "./types";
 interface ResolverForService {
   resolve(intent: AccessIntent): PermissionCheckResult;
   getToolPermission(toolName: string, agentName?: string): PermissionState;
+  isToolFullyDenied(toolName: string, agentName?: string): boolean;
 }
 
 /** Narrow session view: hands out the cwd-bound path normalizer. */
@@ -81,6 +82,13 @@ export class LocalPermissionsService implements PermissionsService {
     return this.resolver.getToolPermission(toolName, agentName);
   }
 
+  isToolFullyDenied(
+    toolName: string,
+    agentName?: string,
+  ): ReturnType<PermissionsService["isToolFullyDenied"]> {
+    return this.resolver.isToolFullyDenied(toolName, agentName);
+  }
+
   registerToolInputFormatter(
     toolName: string,
     formatter: ToolInputFormatter,

package/src/rule.ts

@@ -1,6 +1,7 @@
 import type { PathFlavor } from "#src/path/path-flavor";
 
 import { PATH_SURFACES } from "./access-intent/path-surfaces";
+import { expandHomePath } from "./expand-home";
 import type { PermissionState } from "./types";
 import { type WildcardMatchOptions, wildcardMatch } from "./wildcard-matcher";
 
@@ -139,6 +140,54 @@ function ruleMatches(
   );
 }
 
+/**
+ * Whether every value on `surface` resolves to `deny`.
+ *
+ * This is a different question from "what does the surface's catch-all say?",
+ * and it carries a different burden of proof: the catch-all answers *what this
+ * surface is*, while this answers *whether anything at all could get through* —
+ * the question tool exposure has to ask before withholding a tool from the
+ * agent entirely.
+ *
+ * Reachability is decided by probing each pattern configured on the surface as
+ * a representative value through {@link evaluate}, so last-match-wins shadowing
+ * is honored: an exception written *after* a `deny` catch-all is reachable,
+ * while one written *before* it is not.
+ *
+ * The probe is an approximation of "does any string resolve non-deny", not a
+ * decision procedure for it. Being wrong in either direction only changes
+ * whether the agent sees the tool — the invocation gate re-evaluates the real
+ * value against the same ruleset either way.
+ */
+export function isSurfaceFullyDenied(
+  surface: string,
+  rules: Ruleset,
+  flavor: PathFlavor,
+): boolean {
+  for (const value of probeValuesForSurface(surface, rules)) {
+    if (evaluate(surface, value, rules, flavor).action !== "deny") return false;
+  }
+  return true;
+}
+
+/**
+ * The representative values {@link isSurfaceFullyDenied} probes: the catch-all,
+ * plus every pattern configured on a rule whose surface reaches `surface`.
+ *
+ * Each pattern is home-expanded because {@link compileWildcardPattern} expands
+ * the *pattern* side only; an unexpanded `~/notes/*` probe would fail to match
+ * its own rule and report the surface denied.
+ */
+function probeValuesForSurface(surface: string, rules: Ruleset): Set<string> {
+  const values = new Set<string>(["*"]);
+  for (const rule of rules) {
+    if (wildcardMatch(rule.surface, surface)) {
+      values.add(expandHomePath(rule.pattern));
+    }
+  }
+  return values;
+}
+
 /**
  * Evaluate a surface against multiple values, returning the most restrictive
  * non-allow result (deny > ask > allow).

package/src/service.ts

@@ -99,13 +99,17 @@ export interface PermissionQuery {
   ): PermissionCheckResult;
 
   /**
-   * Query the tool-level permission state for pre-filtering tools before
-   * creating a child session.
+   * Query a surface's catch-all permission state — its blanket policy.
    *
    * Returns `"deny"` | `"allow"` | `"ask"` based on the composed policy.
    * Does not consider command-level rules (e.g. per-bash-command patterns) —
    * use `checkPermission` for runtime invocation gates.
    *
+   * This is **not** the question to ask when pre-filtering a tool list: a
+   * partially permissive surface such as `bash: {"*": "deny", "git *": "ask"}`
+   * answers `"deny"` here while `git status` would still be asked about. Use
+   * {@link PermissionsService.isToolFullyDenied} for that.
+   *
    * @param toolName  - Tool name (e.g. `"bash"`, `"read"`, `"my-extension:tool"`).
    * @param agentName - Optional agent name for per-agent policy resolution.
    */
@@ -126,6 +130,24 @@ export interface PermissionQuery {
  * rules internally.
  */
 export interface PermissionsService extends PermissionQuery {
+  /**
+   * Whether every value under a tool's surface resolves to `deny`.
+   *
+   * This is the question to ask before withholding a tool from a child
+   * session's tool list, and it is not `getToolPermission`: that reports the
+   * surface's own catch-all, so a partially permissive surface such as
+   * `bash: {"*": "deny", "git *": "ask"}` reads as `"deny"` while `git status`
+   * would still be asked about.
+   *
+   * Rule ordering is honored (last-match-wins), so an exception written *after*
+   * a `deny` catch-all keeps the tool reachable and one written *before* it
+   * does not.
+   *
+   * @param toolName  - Tool name (e.g. `"bash"`, `"read"`, `"my-extension:tool"`).
+   * @param agentName - Optional agent name for per-agent policy resolution.
+   */
+  isToolFullyDenied(toolName: string, agentName?: string): boolean;
+
   /**
    * Register a custom preview formatter for a specific tool name.
    *

package/src/session-approval.ts

@@ -1,54 +1,44 @@
+import type { ApprovalGrant } from "#src/approval-grant";
 import type { ForwardedSessionApproval } from "#src/authority/permission-forwarding";
 
 /**
- * Value object for a session-scoped approval: one surface, one-or-more patterns.
+ * Value object for a session-scoped approval: one or more
+ * {@link ApprovalGrant}s, each pairing a pattern with the surface it was
+ * proven on.
  *
  * Owned by gate descriptors and passed to the session store — the runner never
- * needs to know whether there is one pattern or many.
+ * needs to know how many grants an approval carries, and the store records
+ * each on the surface the grant itself names rather than one shared by all
+ * (#810).
  */
 export class SessionApproval {
-  private constructor(
-    readonly surface: string,
-    readonly patterns: readonly string[],
-  ) {}
+  private constructor(readonly grants: readonly ApprovalGrant[]) {}
 
   /** Create an approval for a single pattern (the common case). */
   static single(surface: string, pattern: string): SessionApproval {
-    return new SessionApproval(surface, [pattern]);
+    return new SessionApproval([{ surface, pattern }]);
   }
 
   /**
-   * Create an approval for multiple patterns (e.g. bash external-directory
-   * gates that cover several uncovered paths in one prompt).
+   * Create an approval from grants that may name different surfaces (e.g. a
+   * bash external-directory ask whose uncovered paths proved different
+   * directions). Returns a defensive copy.
    */
-  static multiple(
-    surface: string,
-    patterns: readonly string[],
-  ): SessionApproval {
-    return new SessionApproval(surface, [...patterns]);
+  static forGrants(grants: readonly ApprovalGrant[]): SessionApproval {
+    return new SessionApproval([...grants]);
   }
 
-  /** Representative pattern for the interactive prompt — the first, if any. */
-  get representativePattern(): string | undefined {
-    return this.patterns[0];
-  }
-
-  /**
-   * Single-pattern shape `applyPermissionGate` echoes back to the caller.
-   * Returns `undefined` when patterns is empty (degenerate case).
-   */
-  toGateApproval(): { surface: string; pattern: string } | undefined {
-    const pattern = this.representativePattern;
-    if (pattern === undefined) return undefined;
-    return { surface: this.surface, pattern };
+  /** Whether this approval carries anything for the session store to record. */
+  get isRecordable(): boolean {
+    return this.grants.length > 0;
   }
 
   /**
    * Plain data shape for relaying this approval on a forwarded request, so the
-   * serving node can record the same pattern(s) as a whole-session grant.
-   * Returns a defensive copy of the patterns.
+   * serving node can record the same grants as a whole-session grant.
+   * Returns a defensive copy.
    */
   toForwardedData(): ForwardedSessionApproval {
-    return { surface: this.surface, patterns: [...this.patterns] };
+    return { grants: [...this.grants] };
   }
 }

package/src/session-rules.ts

@@ -41,14 +41,16 @@ export class SessionRules implements SessionApprovalRecorder {
   }
 
   /**
-   * Record all patterns from a `SessionApproval` value object.
+   * Record every grant from a `SessionApproval` value object.
    *
-   * The loop lives here so callers never need to know whether an approval
-   * carries one pattern or many — they just tell the store to record it.
+   * The loop lives here so callers never need to know how many grants an
+   * approval carries — they just tell the store to record it. Each grant is
+   * recorded on the surface it names, so an ask whose paths proved different
+   * directions grants each path only its own (#810).
    */
   recordSessionApproval(approval: SessionApproval): void {
-    for (const pattern of approval.patterns) {
-      this.approve(approval.surface, pattern);
+    for (const { surface, pattern } of approval.grants) {
+      this.approve(surface, pattern);
     }
   }