@gotgenes/pi-permission-system 30.1.0 → 31.0.0

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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).
 
+## [31.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v30.2.0...pi-permission-system-v31.0.0) (2026-09-02)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** **breaking:** gate a path named as a for or select loop operand ([6189d81](https://github.com/gotgenes/pi-packages/commit/6189d81dc48a26d572bacb91a1b2e7c062634ad9)), closes [#839](https://github.com/gotgenes/pi-packages/issues/839)
+* **pi-permission-system:** **breaking:** gate a path named as a case subject ([dfd2f8d](https://github.com/gotgenes/pi-packages/commit/dfd2f8d682c39dcfe6a903cdeadde18b08a7cc60)), closes [#839](https://github.com/gotgenes/pi-packages/issues/839)
+
+### Documentation
+
+* **pi-permission-system:** commit the instrument behind the statement-operand measurement ([6a708b7](https://github.com/gotgenes/pi-packages/commit/6a708b716f038bf192875a0166ae6a6ab012c3d8)), closes [#839](https://github.com/gotgenes/pi-packages/issues/839)
+* **pi-permission-system:** register the statement-operand measurement script ([e3e8799](https://github.com/gotgenes/pi-packages/commit/e3e879935c6f395d4b2387a6e30e0791bb8fb765)), closes [#839](https://github.com/gotgenes/pi-packages/issues/839)
+* **pi-permission-system:** correct the drift note in the operand measurement ([e300934](https://github.com/gotgenes/pi-packages/commit/e300934c0aad34b3bfd127695219250ca6f4613f)), closes [#839](https://github.com/gotgenes/pi-packages/issues/839)
+
+## [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)
 
 

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;

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.

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.1.0",
+  "version": "31.0.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {
@@ -91,6 +91,7 @@
     "verify:public-types": "bash scripts/verify-public-types.sh",
     "measure:core-coverage": "node scripts/measure-core-coverage.mjs",
     "measure:statement-descent": "node scripts/measure-statement-descent.mjs",
+    "measure:statement-operands": "node scripts/measure-statement-operands.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/src/access-intent/bash/token-collection.ts

@@ -11,7 +11,7 @@ import {
 } from "#src/access-intent/bash/node-text";
 import type { TSNode } from "#src/access-intent/bash/parser";
 import { redirectEffectForDestination } from "#src/access-intent/bash/redirect-analysis";
-import type { TokenEffect } from "#src/access-intent/effect";
+import { type TokenEffect, UNPROVEN_EFFECT } from "#src/access-intent/effect";
 
 /**
  * A collected path-candidate token paired with the effect its position proved.
@@ -29,7 +29,8 @@ export interface PathToken {
 
 /**
  * Recursively visit the AST and collect resolved text of nodes that
- * represent command arguments or redirect destinations.
+ * represent command arguments, redirect destinations, or a statement's own
+ * path operands.
  *
  * Reads no text from `heredoc_body`, `heredoc_end`, or `comment` subtrees, but
  * still descends an execution host for the commands it hosts — an interpolating
@@ -46,6 +47,12 @@ export interface PathToken {
 export function collectPathCandidateTokens(node: TSNode): PathToken[] {
   if (node.type === "command") return collectCommandTokens(node);
   if (node.type === "file_redirect") return collectRedirectTokens(node);
+  if (node.type === "for_statement") {
+    return collectStatementOperandTokens(node, "after-in");
+  }
+  if (node.type === "case_statement") {
+    return collectStatementOperandTokens(node, "before-in");
+  }
   if (EXECUTION_HOST_TYPES.has(node.type)) {
     return collectHostedExecutionTokens(node);
   }
@@ -139,6 +146,70 @@ function collectHostedExecutionTokens(node: TSNode): PathToken[] {
   return tokens;
 }
 
+/**
+ * Which side of a statement's `in` keyword carries its path operands.
+ *
+ * A `for`/`select` word list follows `in`; a `case` subject precedes it.
+ */
+type OperandSide = "before-in" | "after-in";
+
+/**
+ * Collect the tokens of a statement that names its own path operands, rather
+ * than reaching them through a command.
+ *
+ * A path in a `for`/`select` word list or a `case` subject is a child of the
+ * statement node, so the command and redirect collectors never see it and the
+ * loop body cannot recover it — `for f in /etc/shadow; do cat $f; done` carries
+ * the literal only here, and ADR 0009 declines to resolve the body's `$f`
+ * (#839).
+ *
+ * The two statements ask one question with one parameter — which side of the
+ * anonymous `in` keyword is the operand side — so the walk is named here once
+ * rather than spelled twice, as `COMMAND_PREFIX_TYPES` is for the two command
+ * walkers.
+ *
+ * Three properties carry the design:
+ *
+ * 1. A non-operand child falls through to the ordinary recursion, not to
+ *    nothing. That is what keeps the `do_group` reaching the loop body's
+ *    commands; searching it for hosted executions alone would silently drop
+ *    every ordinary body command.
+ * 2. An operand-side child outside {@link ARG_NODE_TYPES} falls through the
+ *    same way, so a bare substitution in the word list is descended for its
+ *    command as before and its operands keep that command's own attribution
+ *    (#807) instead of the statement's.
+ * 3. An operand-side argument node is read *and* searched for hosted
+ *    executions, since a `concatenation` can be both — the pairing
+ *    {@link collectRedirectTokens} already performs on a destination.
+ *
+ * The token carries {@link UNPROVEN_EFFECT}: no command word owns it and no
+ * redirect operator names it, so neither proof source can speak and the gates
+ * consult both directional surfaces.
+ */
+function collectStatementOperandTokens(
+  node: TSNode,
+  operandSide: OperandSide,
+): PathToken[] {
+  const tokens: PathToken[] = [];
+  let seenIn = false;
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child) continue;
+    if (!child.isNamed) {
+      if (child.type === "in") seenIn = true;
+      continue;
+    }
+    const side: OperandSide = seenIn ? "after-in" : "before-in";
+    if (side !== operandSide || !ARG_NODE_TYPES.has(child.type)) {
+      tokens.push(...collectPathCandidateTokens(child));
+      continue;
+    }
+    tokens.push({ token: resolveNodeText(child), effect: UNPROVEN_EFFECT });
+    tokens.push(...collectHostedExecutionTokens(child));
+  }
+  return tokens;
+}
+
 /**
  * Extract the command name from a `command` node.
  * Returns the basename (e.g. `/usr/bin/sed` → `sed`), or undefined

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 = {

package/src/authority/permission-prompt-component.ts

@@ -22,6 +22,7 @@ import {
   type PromptModelConfig,
   type PromptViewState,
   reducePrompt,
+  visibleOptionKeys,
 } from "#src/authority/permission-prompt-decision";
 import {
   completeViewBudget,
@@ -127,12 +128,11 @@ const DEFAULT_SESSION_LABEL = "Yes, for this session";
 const OPTION_LABELS: Record<PromptKey, string> = {
   y: "Yes",
   s: DEFAULT_SESSION_LABEL,
+  b: "Yes, for this session in both directions",
   n: "No",
   r: "No, provide reason",
 };
 
-const OPTION_ORDER: readonly PromptKey[] = ["y", "s", "n", "r"];
-
 export function presentInlinePermissionPrompt(
   view: PermissionPromptView,
   title: string,
@@ -142,6 +142,7 @@ export function presentInlinePermissionPrompt(
   const config: PromptModelConfig = {
     doublePressToConfirm: view.doublePressToConfirm,
     sessionLabel: options?.sessionLabel ?? DEFAULT_SESSION_LABEL,
+    widthLabel: options?.sessionWidth?.label,
     sessionScope: options?.sessionScope,
   };
   return view.ui.custom<UnattributedDecision>(
@@ -330,7 +331,9 @@ class PermissionPromptComponent implements Component {
       return { type: "cancel" };
     }
     if (this.state.step === "decision") {
-      const key = OPTION_ORDER.find((option) => matchesKey(data, option));
+      const key = visibleOptionKeys(this.config).find((option) =>
+        matchesKey(data, option),
+      );
       if (key) {
         return { type: "hotkey", key };
       }
@@ -354,8 +357,8 @@ class PermissionPromptComponent implements Component {
   private renderDecision(width: number): string[] {
     const ask = this.renderAsk(width);
     const lines = [this.theme.fg("accent", this.title), ...ask.lines, ""];
-    for (const key of OPTION_ORDER) {
-      const label = key === "s" ? this.config.sessionLabel : OPTION_LABELS[key];
+    for (const key of visibleOptionKeys(this.config)) {
+      const label = this.labelFor(key);
       const selected = this.state.highlightedKey === key;
       const marker = selected ? "▶" : " ";
       const row = `${marker} (${key}) ${label}`;
@@ -366,6 +369,16 @@ class PermissionPromptComponent implements Component {
     return lines;
   }
 
+  /**
+   * The row label for a key: the two session options carry ask-supplied text
+   * naming what they grant, and the rest are fixed.
+   */
+  private labelFor(key: PromptKey): string {
+    if (key === "s") return this.config.sessionLabel;
+    if (key === "b") return this.config.widthLabel ?? OPTION_LABELS.b;
+    return OPTION_LABELS[key];
+  }
+
   private renderReason(width: number): string[] {
     const lines = [
       this.theme.fg("accent", this.title),

package/src/authority/permission-prompt-decision.ts

@@ -1,3 +1,4 @@
+import type { SessionGrantWidth } from "#src/approval-grant";
 import {
   createDeniedPermissionDecision,
   normalizePermissionDenialReason,
@@ -15,17 +16,45 @@ import {
  * forwards keystrokes to {@link reducePrompt} and renders the returned state.
  */
 
-/** The four decision hotkeys, in display order. */
-export type PromptKey = "y" | "s" | "n" | "r";
+/**
+ * The decision hotkeys, in display order.
+ *
+ * `b` is conditional: it appears only for an ask whose session grant can be
+ * widened to both directions (#813), so the roster an ask actually offers
+ * comes from {@link visibleOptionKeys} rather than from this type.
+ */
+export type PromptKey = "y" | "s" | "b" | "n" | "r";
 
 /** Which sub-view the dialog is showing. */
 export type PromptStep = "decision" | "reason" | "scope";
 
-const OPTION_ORDER: readonly PromptKey[] = ["y", "s", "n", "r"];
+const OPTION_ORDER: readonly PromptKey[] = ["y", "s", "b", "n", "r"];
+
+const NARROW_OPTION_ORDER: readonly PromptKey[] = OPTION_ORDER.filter(
+  (key) => key !== "b",
+);
+
+/**
+ * The decision step's option keys, in display order.
+ *
+ * A function of the config rather than an exported constant, so which options
+ * an ask offers is decided in the model and the component renders whatever it
+ * is handed — two copies of the roster would be two places to teach about a
+ * conditional option.
+ *
+ * The width option is offered iff the ask supplied a label for it, so an ask
+ * that proves no single direction is rendered and navigated exactly as before.
+ */
+export function visibleOptionKeys(
+  config: PromptModelConfig,
+): readonly PromptKey[] {
+  return config.widthLabel ? OPTION_ORDER : NARROW_OPTION_ORDER;
+}
 
 const OPTION_VERBS: Record<PromptKey, string> = {
   y: "approve",
   s: "approve for this session",
+  b: "approve both directions for this session",
   n: "deny",
   r: "deny with a reason",
 };
@@ -36,6 +65,13 @@ export interface PromptModelConfig {
   doublePressToConfirm: boolean;
   /** Label shown beside the approve-for-session option. */
   sessionLabel: string;
+  /**
+   * Label for the both-directions session option (#813).
+   *
+   * Its presence is what offers the option: an ask whose grants prove no
+   * single direction supplies none, and the roster stays four keys.
+   */
+  widthLabel?: string;
   /**
    * Forwarded asks only: when set, confirming `s` opens a second step choosing
    * whether the grant applies to the requesting subagent only (least-privilege
@@ -56,6 +92,15 @@ export interface PromptViewState {
   reasonError?: string;
   /** Scope step: false = subagent-only (default), true = whole serving session. */
   scopeServing: boolean;
+  /**
+   * The width the session option chosen so far would grant.
+   *
+   * Held on the state rather than passed to the scope step, because a
+   * forwarded ask commits the two choices in different steps. Reset to
+   * `"proven"` on every return to the decision step, so a width the user
+   * backed out of cannot ride along with a later narrow choice.
+   */
+  grantWidth: SessionGrantWidth;
 }
 
 /** An input event the reducer understands. */
@@ -81,6 +126,7 @@ export function initialPromptState(
     hint: "",
     reasonError: undefined,
     scopeServing: false,
+    grantWidth: "proven",
   };
 }
 
@@ -116,12 +162,14 @@ function reduceDecisionStep(
     case "nav":
       return render({
         ...state,
-        highlightedKey: shiftKey(state.highlightedKey, event.direction),
+        highlightedKey: shiftKey(config, state.highlightedKey, event.direction),
         armedKey: undefined,
         hint: "",
       });
     case "hotkey":
-      return pressHotkey(config, state, event.key);
+      return visibleOptionKeys(config).includes(event.key)
+        ? pressHotkey(config, state, event.key)
+        : render(state);
     case "confirm":
       return commit(config, state, state.highlightedKey);
     case "cancel":
@@ -170,23 +218,48 @@ function commit(
         reasonError: undefined,
       });
     case "s":
+    case "b": {
+      // The two session options differ only in the width they grant; which
+      // scope they land on is the forwarded scope step's separate question.
+      const grantWidth: SessionGrantWidth = key === "b" ? "family" : "proven";
       if (config.sessionScope) {
         return render({
           ...state,
           step: "scope",
-          highlightedKey: "s",
+          highlightedKey: key,
           armedKey: undefined,
           hint: "",
           scopeServing: false,
+          grantWidth,
         });
       }
       return {
         kind: "decision",
-        decision: { approved: true, state: "approved_for_session" },
+        decision: sessionDecision("approved_for_session", grantWidth),
       };
+    }
   }
 }
 
+/**
+ * A session-granting decision, naming its width only when it is not the
+ * default.
+ *
+ * Absent means `"proven"` everywhere this value travels — the decision, the
+ * gate result, and the forwarded wire — so the narrow grant serializes
+ * exactly as it did before the option existed.
+ */
+function sessionDecision(
+  state: "approved_for_session" | "approved_for_serving_session",
+  width: SessionGrantWidth,
+): UnattributedDecision {
+  return {
+    approved: true,
+    state,
+    ...(width === "family" ? { sessionGrantWidth: width } : {}),
+  };
+}
+
 function reduceReasonStep(
   state: PromptViewState,
   event: PromptEvent,
@@ -198,6 +271,7 @@ function reduceReasonStep(
       armedKey: undefined,
       hint: "",
       reasonError: undefined,
+      grantWidth: "proven",
     });
   }
   if (event.type === "submitReason") {
@@ -226,12 +300,12 @@ function reduceScopeStep(
     case "confirm":
       return {
         kind: "decision",
-        decision: {
-          approved: true,
-          state: state.scopeServing
+        decision: sessionDecision(
+          state.scopeServing
             ? "approved_for_serving_session"
             : "approved_for_session",
-        },
+          state.grantWidth,
+        ),
       };
     case "cancel":
       return render({
@@ -239,17 +313,23 @@ function reduceScopeStep(
         step: "decision",
         armedKey: undefined,
         hint: "",
+        grantWidth: "proven",
       });
     default:
       return render(state);
   }
 }
 
-function shiftKey(current: PromptKey, direction: "up" | "down"): PromptKey {
-  const index = OPTION_ORDER.indexOf(current);
+function shiftKey(
+  config: PromptModelConfig,
+  current: PromptKey,
+  direction: "up" | "down",
+): PromptKey {
+  const keys = visibleOptionKeys(config);
+  const index = keys.indexOf(current);
   const delta = direction === "down" ? 1 : -1;
-  const next = (index + delta + OPTION_ORDER.length) % OPTION_ORDER.length;
-  return OPTION_ORDER[next] ?? current;
+  const next = (index + delta + keys.length) % keys.length;
+  return keys[next] ?? current;
 }
 
 function render(state: PromptViewState): PromptOutcome {

package/src/authority/permission-prompter.ts

@@ -1,3 +1,4 @@
+import type { SessionGrantWidth } from "#src/approval-grant";
 import type { DecisionSource } from "#src/authority/decision-source";
 import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
 import type {
@@ -11,6 +12,25 @@ import type { TerminalAuthorizer } from "./authorizer";
 
 export type PermissionReviewSource = "tool_call" | "skill_input" | "skill_read";
 
+/**
+ * The width a decision's session grant was recorded at, or `undefined` when it
+ * granted nothing for the session.
+ *
+ * Absent means "proven" everywhere else this value travels, but the review log
+ * is read rather than consumed, so a session-granting entry states its width
+ * explicitly instead of leaving the reader to know the default (#813).
+ */
+function recordedGrantWidth(
+  decision: PermissionPromptDecision,
+): SessionGrantWidth | undefined {
+  const grantsForSession =
+    decision.state === "approved_for_session" ||
+    decision.state === "approved_for_serving_session";
+  return grantsForSession
+    ? (decision.sessionGrantWidth ?? "proven")
+    : undefined;
+}
+
 /**
  * Provenance of a forwarded ask: who is really asking, one hop below.
  *
@@ -133,6 +153,7 @@ export class PermissionPrompter implements PermissionPrompterApi {
           : decision.state,
         denialReason: decision.denialReason,
         decidedBy: decision.decidedBy,
+        sessionGrantWidth: recordedGrantWidth(decision),
       },
     );
 
@@ -151,10 +172,14 @@ export class PermissionPrompter implements PermissionPrompterApi {
       resolution?: string;
       denialReason?: string;
       decidedBy?: DecisionSource;
+      sessionGrantWidth?: SessionGrantWidth;
     },
   ): void {
     this.deps.logger.review(event, {
       ...(details.decidedBy ? { decidedBy: details.decidedBy } : {}),
+      ...(details.sessionGrantWidth
+        ? { sessionGrantWidth: details.sessionGrantWidth }
+        : {}),
       requestId: details.requestId,
       source: details.source,
       agentName: details.agentName,

package/src/handlers/gates/runner.ts

@@ -228,9 +228,9 @@ export class GateRunner {
       messages,
     });
 
-    // 4. Determine whether session approval was granted
-    const hasSessionApproval =
-      gateResult.action === "allow" && gateResult.forSession === true;
+    // 4. Determine whether session approval was granted, and at what width
+    const sessionGrant =
+      gateResult.action === "allow" ? gateResult.sessionGrant : undefined;
 
     // 5. Emit decision event
     this.emitDecision(
@@ -242,15 +242,17 @@ export class GateRunner {
         gateResult.action === "allow" ? "allow" : "deny",
         resolutionFor(gateResult.decidedBy, {
           approved: gateResult.action === "allow",
-          forSession: hasSessionApproval,
+          forSession: sessionGrant !== undefined,
         }),
       ),
     );
 
     // 6. Record session approval — tell the store; it owns the per-pattern loop
-    // hasSessionApproval already implies gateResult.action === "allow"
-    if (hasSessionApproval && descriptor.sessionApproval) {
-      this.recorder.recordSessionApproval(descriptor.sessionApproval);
+    // A present grant already implies gateResult.action === "allow".
+    if (sessionGrant && descriptor.sessionApproval) {
+      this.recorder.recordSessionApproval(
+        descriptor.sessionApproval.atWidth(sessionGrant.width),
+      );
     }
 
     if (gateResult.action === "block") {

package/src/pattern-suggest.ts

@@ -1,4 +1,9 @@
-import { PATH_BEARING_TOOLS } from "./access-intent/path-surfaces";
+import {
+  type CapabilityDirection,
+  PATH_BEARING_TOOLS,
+  surfaceFamilyOf,
+} from "./access-intent/path-surfaces";
+import type { ApprovalGrant } from "./approval-grant";
 import { prefix, stripBashCommentLines } from "./bash-arity";
 
 /** The suggestion returned for a "Yes, for this session" dialog option. */
@@ -69,27 +74,90 @@ export interface ForwardedScopeLabels {
   servingSessionLabel: string;
 }
 
+/**
+ * What an approval's grants cover, as one phrase.
+ *
+ * A single grant names its pattern; several name their count, because only the
+ * external-directory gate aggregates an ask over many paths and there is no
+ * pattern that describes them all. Requires at least one grant — an approval
+ * with none is never offered as a session option.
+ */
+export function describeGrantTarget(grants: readonly ApprovalGrant[]): string {
+  return grants.length === 1
+    ? `"${grants[0].pattern}"`
+    : `${grants.length} paths`;
+}
+
+/** The two session-option labels for an ask whose grants prove one direction. */
+export interface DirectionalSessionLabels {
+  /** The proven-direction grant — the least-privilege default. */
+  sessionLabel: string;
+  /** The both-directions grant, offered beside it (#813). */
+  widenedLabel: string;
+}
+
+const DIRECTION_NOUNS: Record<CapabilityDirection, string> = {
+  read: "reads",
+  write: "writes",
+};
+
+/**
+ * Label the two widths a directional ask's session grant can take.
+ *
+ * Both rows name the direction and the target, so the choice between them
+ * contrasts on a stated axis rather than on "wider" (#813).
+ */
+export function buildDirectionalSessionLabels(
+  direction: CapabilityDirection,
+  target: string,
+): DirectionalSessionLabels {
+  return {
+    sessionLabel: `Yes, allow ${DIRECTION_NOUNS[direction]} to ${target} for this session`,
+    widenedLabel: `Yes, allow ${DIRECTION_NOUNS.read} and ${DIRECTION_NOUNS.write} to ${target} for this session`,
+  };
+}
+
 /**
  * Build the two scope labels shown when a human grants a forwarded request
  * "for this session."
  *
  * The subagent option names the requester (least privilege); the whole-session
- * option restates the surface + pattern being granted session-wide.
+ * option restates what is being granted session-wide — every grant, not the
+ * first of them (the residual #810 deferred here).
+ *
+ * The surface is named as the grants' shared **family**, never a directional
+ * member: these labels are built before the dialog runs, so a direction here
+ * could contradict a width the human chooses inside it. Grants that share no
+ * family name no surface at all.
  */
 export function buildForwardedScopeLabels(
   agentName: string | null,
-  surface: string,
-  pattern: string,
+  grants: readonly ApprovalGrant[],
 ): ForwardedScopeLabels {
   const subagentLabel = agentName
     ? `This subagent ('${agentName}') only`
     : "This subagent only";
+  const family = sharedSurfaceFamilyOf(grants);
+  const granted = family
+    ? `${family} ${describeGrantTarget(grants)}`
+    : describeGrantTarget(grants);
   return {
     subagentLabel,
-    servingSessionLabel: `The whole session — allow ${surface} "${pattern}" for parent and all subagents`,
+    servingSessionLabel: `The whole session — allow ${granted} for parent and all subagents`,
   };
 }
 
+/** The family every grant belongs to, or `null` when they disagree. */
+function sharedSurfaceFamilyOf(
+  grants: readonly ApprovalGrant[],
+): string | null {
+  if (grants.length === 0) return null;
+  const family = surfaceFamilyOf(grants[0].surface);
+  return grants.every((grant) => surfaceFamilyOf(grant.surface) === family)
+    ? family
+    : null;
+}
+
 /** Surface-aware human-readable labels for the session-approval option. */
 function buildLabel(pattern: string, surface: string): string {
   switch (surface) {

package/src/permission-gate.ts

@@ -1,3 +1,4 @@
+import type { SessionGrantWidth } from "#src/approval-grant";
 import type { DecisionSource } from "#src/authority/decision-source";
 import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
 
@@ -13,8 +14,15 @@ export type PermissionGateResult =
   | {
       action: "allow";
       decidedBy: DecisionSource;
-      /** Set when the human granted the ask for the whole session. */
-      forSession?: true;
+      /**
+       * Set when the human granted the ask for the whole session, carrying the
+       * width to record it at.
+       *
+       * One field rather than a `forSession` flag beside a width: the width is
+       * meaningless without the grant, and two optional fields could represent
+       * a width for a grant that never happened.
+       */
+      sessionGrant?: { width: SessionGrantWidth };
     }
   | { action: "block"; decidedBy: DecisionSource; reason: string };
 
@@ -112,7 +120,12 @@ export async function applyPermissionGate(
       decision.state === "approved_for_session" &&
       params.canGrantForSession
     ) {
-      return { action: "allow", decidedBy, forSession: true };
+      return {
+        action: "allow",
+        decidedBy,
+        // Absent means the width every producer chose before #813.
+        sessionGrant: { width: decision.sessionGrantWidth ?? "proven" },
+      };
     }
     return { action: "allow", decidedBy };
   }

package/src/session-approval.ts

@@ -1,4 +1,8 @@
-import type { ApprovalGrant } from "#src/approval-grant";
+import {
+  type ApprovalGrant,
+  type SessionGrantWidth,
+  widenGrant,
+} from "#src/approval-grant";
 import type { ForwardedSessionApproval } from "#src/authority/permission-forwarding";
 
 /**
@@ -33,6 +37,20 @@ export class SessionApproval {
     return this.grants.length > 0;
   }
 
+  /**
+   * This approval as recorded at `width`.
+   *
+   * The runner holds a width and an approval and tells the approval to produce
+   * itself — it never inspects a grant's surface. Each grant is folded
+   * individually, so an approval whose patterns proved different directions
+   * keeps one grant per pattern (#810) at either width.
+   */
+  atWidth(width: SessionGrantWidth): SessionApproval {
+    return width === "proven"
+      ? this
+      : new SessionApproval(this.grants.map(widenGrant));
+  }
+
   /**
    * Plain data shape for relaying this approval on a forwarded request, so the
    * serving node can record the same grants as a whole-session grant.