@gotgenes/pi-permission-system 30.0.0 → 30.2.0

package/CHANGELOG.md

@@ -5,6 +5,37 @@ 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.2.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v30.1.0...pi-permission-system-v30.2.0) (2026-09-02)
+
+
+### Features
+
+* **pi-permission-system:** offer a both-directions session grant at the ask prompt ([c4c6736](https://github.com/gotgenes/pi-packages/commit/c4c67364b88e74ad439adcc6c442de46a4f90c04)), closes [#813](https://github.com/gotgenes/pi-packages/issues/813)
+
+### Bug Fixes
+
+* **pi-permission-system:** name every path in a forwarded whole-session scope label ([b61c19d](https://github.com/gotgenes/pi-packages/commit/b61c19d77c74e2d8ff233ca556af04f6aacd2c09)), closes [#813](https://github.com/gotgenes/pi-packages/issues/813)
+
+### Documentation
+
+* **pi-permission-system:** document the session-grant direction width ([dae4737](https://github.com/gotgenes/pi-packages/commit/dae473727b4b514761545d8fcc0a5e4824fe35b0)), closes [#813](https://github.com/gotgenes/pi-packages/issues/813)
+
+## [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)
 
 

package/README.md

@@ -66,6 +66,7 @@ All permissions use one of three states:
 
 When the dialog prompts, you can approve once or approve a pattern for the rest of the session.
 In an interactive TUI session the prompt is an inline keybind dialog — `y` approve, `s` approve for this session, `n` deny, `r` deny with a reason — where each hotkey arms and a second press confirms (configurable via `doublePressToConfirm`).
+A file-access ask that proves a single direction offers `b` as well, granting the session both directions instead of only the one the gate proved.
 The prompt shows one fact per line — who is asking, the tool, the matched rule, the value being decided — within a row budget, so a large tool input cannot take over the transcript; `Ctrl+O` (`app.tools.expand`) expands it to the complete request.
 See [docs/configuration.md](docs/configuration.md#inline-permission-dialog-tui) for the hotkeys and [docs/session-approvals.md](docs/session-approvals.md) for session-scoped rules and pattern suggestions.
 

package/dist/public.d.ts

@@ -9,6 +9,7 @@ import { z } from 'zod';
  * 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;
@@ -531,13 +532,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.
      */
@@ -557,6 +562,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

@@ -122,10 +122,15 @@ In an interactive **TUI** session, an `ask` decision opens an inline keybind dia
 | Key | Action                                                            |
 | --- | ----------------------------------------------------------------- |
 | `y` | Approve once                                                      |
-| `s` | Approve for this session                                          |
+| `s` | Approve for this session, in the direction the gate proved        |
+| `b` | Approve for this session in **both** directions (see below)       |
 | `n` | Deny                                                              |
 | `r` | Deny with a reason (opens an inline editor; a reason is required) |
 
+`b` appears only for an ask whose paths all prove the same direction — a read or a write, but not both.
+Every other ask shows the four options above without it.
+See [session-approvals.md](session-approvals.md#grant-direction) for what the two widths grant.
+
 Arrow keys / `j`/`k` move the highlight, `enter` confirms the highlighted option, and `esc` denies.
 With `doublePressToConfirm` enabled (the default), a letter hotkey **arms** its action and shows a `Press y again to approve.` hint; press the same key again to commit.
 Set `doublePressToConfirm` to `false` to commit on the first press.
@@ -295,6 +300,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 +1002,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 +1154,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/session-approvals.md

@@ -1,6 +1,6 @@
 # Session-Scoped Approvals
 
-When any permission resolves to `ask`, the permission dialog offers four options:
+When any permission resolves to `ask`, the permission dialog offers at least these four options:
 
 ```text
 Yes | Yes, allow "<pattern>" for this session | No | No, provide reason
@@ -9,8 +9,42 @@ 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.
 
+A file-access ask adds a fifth option — see [Grant direction](#grant-direction).
+
 Session approvals are ephemeral — they are never persisted to disk and are cleared on `session_shutdown`.
 
+## Grant Direction
+
+The `path` and `external_directory` surfaces carry a read/write axis, and the two directions are independent permissions rather than tiers: a write grant does not imply a read.
+When the gate can prove which direction a request needs — a `>` redirect proves a write, `cat` proves a read, the `read` tool proves a read — the session grant is recorded on that direction alone, which is what the prompt named.
+
+That is least privilege, and it costs a second prompt in the read-after-write flow: approving `echo hello > /tmp/out.txt` grants a write, so a following `cat /tmp/out.txt` asks again.
+So an ask whose paths all prove the **same** direction offers both widths:
+
+```text
+  (y) Yes
+▶ (s) Yes, allow writes to "/tmp/*" for this session
+  (b) Yes, allow reads and writes to "/tmp/*" for this session
+  (n) No
+  (r) No, provide reason
+```
+
+- **`s`** records the proven direction only (`external_directory_write` here).
+  This is the default; a later read of the same path asks again.
+- **`b`** records the bare family key (`external_directory`), which expands onto both directions — exactly the width a config key like `"external_directory": {"/tmp/*": "allow"}` has.
+  A later read of the same path is covered.
+
+The choice is opt-in per ask and never persisted.
+Ignoring `b` grants no more than the prompt named.
+
+`b` is offered only when one direction phrase describes the whole ask.
+A command that proves a read of one path and a write of another (`cat /outside/a.ts > /elsewhere/b.ts`) records each path on its own direction and offers no width choice, because no single label would be true of both.
+Surfaces with no capability axis — `bash`, `mcp`, `skill`, and the per-tool surfaces — never offer it.
+
+Two paths in the **same** directory derive the same glob, so approving them at either width grants that directory what the prompt showed.
+
+The review log records the width every session grant was taken at, as `sessionGrantWidth: "proven"` or `"family"`.
+
 ## Suggested Patterns
 
 The suggested pattern is surface-specific:
@@ -50,6 +84,7 @@ Put the most specific multi-word prefix first (e.g. `"npm run": 3`) before the s
 The review log records session approval decisions:
 
 - `resolution: "approved_for_session"` — when the user approves with the session pattern
+- `sessionGrantWidth: "proven" | "family"` — beside it, the direction width the grant was recorded at (see [Grant direction](#grant-direction))
 - `resolution: "session_approved"` — when a later request is matched by an existing session rule
 
 ## Permission Prompt Summaries

package/package.json

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

package/src/access-intent/path-surfaces.ts

@@ -32,11 +32,26 @@ const DIRECTIONAL_FAMILIES: ReadonlySet<string> = new Set([
   "external_directory",
 ]);
 
+/**
+ * The capability directions, in ADR 0013 §4's normative order.
+ *
+ * The suffixes below derive from these, so a direction word and its surface
+ * suffix cannot drift — the same discipline that keeps the four surface names
+ * spelled exactly once.
+ */
+const CAPABILITY_DIRECTIONS = ["read", "write"] as const;
+
+/** One end of the read/write axis (ADR 0013 §3). */
+export type CapabilityDirection = (typeof CAPABILITY_DIRECTIONS)[number];
+
 /**
  * The capability suffixes, in ADR 0013 §4's normative order: a family's
  * sugar-expanded and folded members are always read-then-write.
  */
-const CAPABILITY_SUFFIXES = ["_read", "_write"] as const;
+const CAPABILITY_SUFFIXES = [
+  `_${CAPABILITY_DIRECTIONS[0]}`,
+  `_${CAPABILITY_DIRECTIONS[1]}`,
+] as const;
 
 /**
  * Surfaces whose patterns are matched against filesystem paths and therefore
@@ -67,6 +82,25 @@ export function surfaceFamilyOf(surface: string): string {
   return surface;
 }
 
+/**
+ * The direction a surface proves, or `null` when it proves neither — a family
+ * name, a non-path surface, or a suffixed name outside the directional
+ * families (`my_tool_read`).
+ *
+ * The inverse of {@link capabilitySurfaceForEffect} over a proven effect, and
+ * the question that decides whether an ask's session grant can be widened.
+ */
+export function capabilityDirectionOf(
+  surface: string,
+): CapabilityDirection | null {
+  if (surfaceFamilyOf(surface) === surface) return null;
+  return (
+    CAPABILITY_DIRECTIONS.find((direction) =>
+      surface.endsWith(`_${direction}`),
+    ) ?? null
+  );
+}
+
 /**
  * A family name's directional members, or `null` when `surface` is not a
  * family name (a directional member itself, or any non-path surface).

package/src/approval-grant.ts

@@ -7,7 +7,71 @@
  * value object and the forwarded wire type name it, and those two already
  * import in one direction.
  */
+import {
+  type CapabilityDirection,
+  capabilityDirectionOf,
+  surfaceFamilyOf,
+} from "#src/access-intent/path-surfaces";
+
 export interface ApprovalGrant {
   readonly surface: string;
   readonly pattern: string;
 }
+
+/**
+ * How wide a session grant is recorded, relative to what the gate proved.
+ *
+ * `"proven"` records each grant on the surface the gate named — the
+ * least-privilege default, and the only width anything produces today.
+ * `"family"` folds a directional surface to its bare family, which
+ * `SessionRules.approve` sugar-expands onto both members (ADR 0013 §4).
+ */
+export type SessionGrantWidth = "proven" | "family";
+
+/**
+ * Whether an off-disk value names a width this node understands.
+ *
+ * The forwarded response is another process's file, so an unrecognized value
+ * is dropped rather than trusted — which lands the grant at `"proven"`, the
+ * least-privilege width, in the skew direction.
+ */
+export function isSessionGrantWidth(
+  value: unknown,
+): value is SessionGrantWidth {
+  return value === "proven" || value === "family";
+}
+
+/**
+ * The same grant on its bare family surface, or the grant itself when it
+ * already names one (or names no directional family at all).
+ *
+ * Widening is a change of surface and never of pattern: the user is saying
+ * "the other direction too", not "more paths".
+ */
+export function widenGrant(grant: ApprovalGrant): ApprovalGrant {
+  const family = surfaceFamilyOf(grant.surface);
+  return family === grant.surface
+    ? grant
+    : { surface: family, pattern: grant.pattern };
+}
+
+/**
+ * The one direction every grant proves, or `null` when they disagree, any of
+ * them proves none, or there are no grants.
+ *
+ * This is the precise reading of "the gate proved a single direction": a
+ * widened grant is offered only when one direction phrase describes the whole
+ * approval, so the prompt can name what it is widening from.
+ */
+export function provenDirectionOf(
+  grants: readonly ApprovalGrant[],
+): CapabilityDirection | null {
+  if (grants.length === 0) return null;
+  const direction = capabilityDirectionOf(grants[0].surface);
+  if (direction === null) return null;
+  return grants.every(
+    (grant) => capabilityDirectionOf(grant.surface) === direction,
+  )
+    ? direction
+    : null;
+}

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

@@ -351,10 +351,13 @@ export class ForwardedRequestServer implements InboxProcessor {
     }
     if (request.sessionApproval) {
       const { grants } = request.sessionApproval;
-      this.recorder.recordSessionApproval(SessionApproval.forGrants(grants));
+      const approval = SessionApproval.forGrants(grants).atWidth(
+        decision.sessionGrantWidth ?? "proven",
+      );
+      this.recorder.recordSessionApproval(approval);
       this.logger.review("forwarded_permission.session_recorded", {
         ...logDetails,
-        grants,
+        grants: approval.grants,
       });
     }
     return {
@@ -403,6 +406,9 @@ export class ForwardedRequestServer implements InboxProcessor {
         // Carried onto the wire so the requester can name what decided inside
         // this session, not merely that this session answered (#726).
         decidedBy: decision.decidedBy,
+        // The child records a subagent-scoped grant itself, so the width the
+        // human chose has to reach it (#813).
+        sessionGrantWidth: decision.sessionGrantWidth,
       } satisfies ForwardedPermissionResponse);
     } catch (error) {
       logPermissionForwardingError(

package/src/authority/forwarding-io.ts

@@ -9,7 +9,7 @@ import {
   writeFileSync,
 } from "node:fs";
 
-import type { ApprovalGrant } from "#src/approval-grant";
+import { type ApprovalGrant, isSessionGrantWidth } from "#src/approval-grant";
 import { asDecisionSource } from "#src/authority/decision-source";
 import { isPermissionDecisionState } from "#src/authority/permission-dialog";
 import {
@@ -495,6 +495,11 @@ export function readForwardedPermissionResponse(
       // record is dropped, but the decision itself still has to reach the
       // requester, so it never rejects the response.
       decidedBy: asDecisionSource(parsed.decidedBy),
+      // Tolerant for the same reason, and least-privilege when it fires: a
+      // dropped width records the grant on the surface the gate proved.
+      sessionGrantWidth: isSessionGrantWidth(parsed.sessionGrantWidth)
+        ? parsed.sessionGrantWidth
+        : undefined,
     };
   } catch (error) {
     logPermissionForwardingWarning(

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

@@ -1,4 +1,5 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { provenDirectionOf } from "#src/approval-grant";
 import type {
   PermissionPromptDecision,
   RequestPermissionOptions,
@@ -8,7 +9,11 @@ import type {
   PromptPreferences,
   requestPermissionDecision,
 } from "#src/authority/permission-prompt-component";
-import { buildForwardedScopeLabels } from "#src/pattern-suggest";
+import {
+  buildDirectionalSessionLabels,
+  buildForwardedScopeLabels,
+  describeGrantTarget,
+} from "#src/pattern-suggest";
 import {
   emitUiPromptEvent,
   type PermissionEventBus,
@@ -65,24 +70,39 @@ export class LocalUserAuthorizer implements TerminalAuthorizer {
 }
 
 /**
- * A forwarded ask carrying a session-approval suggestion offers the scope
- * choice (subagent vs whole session); any other ask keeps its single
- * "for this session" option (custom label when the gate supplied one).
+ * The dialog options this ask offers, composed from three independent groups.
+ *
+ * The label names what the session grant covers (a gate-supplied one, or one
+ * derived from the grants themselves for a path ask). An ask whose grants all
+ * prove the same direction additionally offers the both-directions width
+ * (#813). A forwarded ask additionally offers the scope choice (subagent vs
+ * whole session).
+ *
+ * They compose rather than exclude: a forwarded path ask offers all three, and
+ * an ask that qualifies for none passes `undefined` so the dialog keeps its
+ * defaults.
  */
 function buildRequestOptions(
   details: PromptPermissionDetails,
 ): RequestPermissionOptions | undefined {
-  const grant = details.sessionApproval?.grants[0];
-  if (details.forwarding && grant) {
-    return {
-      sessionScope: buildForwardedScopeLabels(
-        details.forwarding.requesterAgentName,
-        grant.surface,
-        grant.pattern,
-      ),
-    };
-  }
-  return details.sessionLabel
-    ? { sessionLabel: details.sessionLabel }
-    : undefined;
+  const grants = details.sessionApproval?.grants ?? [];
+  const direction = provenDirectionOf(grants);
+  const widths = direction
+    ? buildDirectionalSessionLabels(direction, describeGrantTarget(grants))
+    : null;
+  const sessionLabel = widths?.sessionLabel ?? details.sessionLabel;
+
+  const options: RequestPermissionOptions = {
+    ...(sessionLabel ? { sessionLabel } : {}),
+    ...(widths ? { sessionWidth: { label: widths.widenedLabel } } : {}),
+    ...(details.forwarding && grants.length > 0
+      ? {
+          sessionScope: buildForwardedScopeLabels(
+            details.forwarding.requesterAgentName,
+            grants,
+          ),
+        }
+      : {}),
+  };
+  return Object.keys(options).length > 0 ? options : undefined;
 }

package/src/authority/permission-dialog.ts

@@ -1,3 +1,4 @@
+import type { SessionGrantWidth } from "#src/approval-grant";
 import type { DecisionSource } from "#src/authority/decision-source";
 
 export type PermissionDecisionState =
@@ -23,6 +24,16 @@ export type PermissionPromptDecision = {
    * reads the `unavailable` decider below instead (#772).
    */
   confirmationUnavailable?: true;
+  /**
+   * How wide a whole-session grant the human chose, when they chose one.
+   *
+   * Orthogonal to `state` rather than a value of it: the two directions and
+   * the subagent/serving scope vary independently, and an unrecognized `state`
+   * is rejected outright by the forwarded-response reader, where an
+   * unrecognized field is merely dropped. Absent means `"proven"` — the
+   * direction the gate named, which is what every producer chose before #813.
+   */
+  sessionGrantWidth?: SessionGrantWidth;
   /**
    * What decided this request, stamped by the site that decided it.
    *
@@ -54,6 +65,22 @@ const APPROVE_FOR_SESSION_OPTION = "Yes, for this session";
 const DENY_OPTION = "No";
 const DENY_WITH_REASON_OPTION = "No, provide reason";
 
+/**
+ * A session-granting decision, naming its width only when it is not the
+ * default — so a narrow grant serializes exactly as it did before the width
+ * option existed.
+ */
+function sessionApproval(
+  state: "approved_for_session" | "approved_for_serving_session",
+  width: SessionGrantWidth,
+): UnattributedDecision {
+  return {
+    approved: true,
+    state,
+    ...(width === "family" ? { sessionGrantWidth: width } : {}),
+  };
+}
+
 export function normalizePermissionDenialReason(
   value: unknown,
 ): string | undefined {
@@ -96,6 +123,12 @@ export function isPermissionDecisionState(
 export interface RequestPermissionOptions {
   /** Override the "for this session" option label (e.g. to show the suggested pattern). */
   sessionLabel?: string;
+  /**
+   * Present iff this ask's session grant can be widened to both directions:
+   * its label is the extra option shown beside the proven-direction one
+   * (#813). Absent leaves the prompt exactly four options.
+   */
+  sessionWidth?: { label: string };
   /**
    * Forwarded asks only: when set, choosing the "for this session" option opens
    * a second select asking whether the grant applies to the requesting subagent
@@ -114,16 +147,16 @@ export async function requestPermissionDecisionFromUi(
   options?: RequestPermissionOptions,
 ): Promise<UnattributedDecision> {
   const sessionOption = options?.sessionLabel ?? APPROVE_FOR_SESSION_OPTION;
+  const widthOption = options?.sessionWidth?.label;
   const decisionOptions = [
     APPROVE_OPTION,
     sessionOption,
+    ...(widthOption ? [widthOption] : []),
     DENY_OPTION,
     DENY_WITH_REASON_OPTION,
-  ] as const;
+  ];
 
-  const selected = await ui.select(`${title}\n${message}`, [
-    ...decisionOptions,
-  ]);
+  const selected = await ui.select(`${title}\n${message}`, decisionOptions);
 
   if (selected === APPROVE_OPTION) {
     return {
@@ -132,26 +165,26 @@ export async function requestPermissionDecisionFromUi(
     };
   }
 
-  if (selected === sessionOption) {
+  if (selected === sessionOption || (widthOption && selected === widthOption)) {
+    // The two session options differ only in the width they grant; the scope
+    // question below is the same for both.
+    const width: SessionGrantWidth =
+      selected === widthOption ? "family" : "proven";
     if (options?.sessionScope) {
       const scope = await ui.select(`${title}\nApply this session grant to:`, [
         options.sessionScope.subagentLabel,
         options.sessionScope.servingSessionLabel,
       ]);
-      return {
-        approved: true,
+      return sessionApproval(
         // A cancelled scope select (undefined) falls back to the
         // least-privilege subagent scope.
-        state:
-          scope === options.sessionScope.servingSessionLabel
-            ? "approved_for_serving_session"
-            : "approved_for_session",
-      };
+        scope === options.sessionScope.servingSessionLabel
+          ? "approved_for_serving_session"
+          : "approved_for_session",
+        width,
+      );
     }
-    return {
-      approved: true,
-      state: "approved_for_session",
-    };
+    return sessionApproval("approved_for_session", width);
   }
 
   if (selected === DENY_WITH_REASON_OPTION) {

package/src/authority/permission-forwarding.ts

@@ -1,5 +1,5 @@
 import { join } from "node:path";
-import type { ApprovalGrant } from "#src/approval-grant";
+import type { ApprovalGrant, SessionGrantWidth } 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";
@@ -198,6 +198,16 @@ export type ForwardedPermissionResponse = {
    * rejecting the answer.
    */
   decidedBy?: DecisionSource;
+  /**
+   * How wide a session grant the responder's human chose (#813).
+   *
+   * The child records a subagent-scoped grant itself, so the width has to
+   * survive the hop or the parent's choice is silently narrowed back.
+   * Optional for version-skew tolerance in both directions: an older
+   * responder omits it, and an older requester's allowlist rebuild drops it —
+   * both landing on `"proven"`, the least-privilege width.
+   */
+  sessionGrantWidth?: SessionGrantWidth;
 };
 
 export type PermissionForwardingLocation = {