@gotgenes/pi-permission-system 27.0.0 → 27.1.0

package/src/access-intent/bash/wrapper-analysis.ts

@@ -1,13 +1,16 @@
 /**
  * Wrapper interpretation for a bash command unit: what kind of wrapper it is,
- * and — where it can be established — what it actually runs.
+ * what it actually runs, and whether its floor still has a reason to hold.
  *
  * Pure and word-based; the AST walk that produces the words lives in
- * `command-enumeration.ts`. Both questions live here together deliberately: the
- * shape that floors a unit to `ask` and the shape that names its inner command
- * must agree, and two classifiers over the same vocabulary would drift.
+ * `command-enumeration.ts`. The three questions live here together
+ * deliberately: the shape that floors a unit to `ask`, the shape that names its
+ * inner command, and the shape that exempts it must agree, and separate
+ * classifiers over the same vocabulary would drift.
  */
 
+import { proveCommandEffect } from "#src/access-intent/bash/command-effects";
+
 /** One word of a command unit: its text, and its offset into the unit's text. */
 export interface CommandWord {
   readonly text: string;
@@ -62,11 +65,12 @@ export function classifyWrapperWords(
  * The command a wrapper unit actually runs, or `null` when it cannot be
  * established or adds nothing over the unit itself.
  *
- * Display-only (ADR 0011 §3.5, #713): the result is never gated and never
- * becomes a `BashCommand`, so the wrapper floor is untouched. Because it is
- * shown on a decision surface, the rule is to fail to `null` rather than to a
- * guess — an unrecognized option shape yields nothing rather than a remainder
- * that might name the wrong command.
+ * Display-only (ADR 0011 §3.5, #713): the result names what runs, including
+ * the payload of an inline shell, so it deliberately looks *past* a `sh -c`
+ * layer that the gate must not look past. Because it is shown on a decision
+ * surface, the rule is to fail to `null` rather than to a guess — an
+ * unrecognized option shape yields nothing rather than a remainder that might
+ * name the wrong command.
  *
  * Nested wrappers unwrap to the innermost command (`sudo timeout 5 xargs grep
  * foo` → `grep foo`), bounded by {@link MAX_UNWRAP_DEPTH}.
@@ -75,8 +79,93 @@ export function executedUnitOf(
   unitText: string,
   words: readonly CommandWord[],
 ): string | null {
+  const unwrapped = unwrapIndirection(words, unitText);
+  const text = unwrapped.kind === "opaque" ? unwrapped.payload : unwrapped.text;
+  return nothingNew(text, unitText);
+}
+
+/**
+ * True when a wrapper unit's floor has no reason left to hold: the command it
+ * runs is in the pure-reader core, so its *direction* is provable however
+ * unknown its argument feed is (ADR 0013 §11, #803).
+ *
+ * The floor exists because a wrapper hides the command that should be gated,
+ * and the unknowability it guards is unknowability of scope — which stays the
+ * projection's and the path surfaces' job, for wrapped and unwrapped commands
+ * alike. Argument-independence is the core's admission bar, so there are no
+ * arguments that make `grep` write a file.
+ *
+ * Four things must hold, and each is a way the reason could still hold:
+ *
+ * 1. The unit is an indirection wrapper — an ordinary command has no floor.
+ * 2. Unwrapping reached the inner command without passing through an opaque
+ *    payload. `sh -c '…'` carries an unparsed program whose first word says
+ *    nothing about the rest of it, which is why this cannot consult
+ *    {@link executedUnitOf}'s string.
+ * 3. The inner command *proves* a read — bare-basename core word, retraction
+ *    guards applied, so `xargs sort -o /tmp/x` and `xargs find . -delete` are
+ *    not transparent.
+ * 4. The unit writes no file through a redirect, which the caller reads off
+ *    the parse tree and this module never sees.
+ */
+export function isTransparentWrapper(
+  words: readonly CommandWord[],
+  statement: { readonly writesViaRedirect: boolean },
+): boolean {
+  if (statement.writesViaRedirect) return false;
+  if (classifyWrapperWords(words) !== "indirection") return false;
+
+  // Only the peeled words matter here, so the walk is handed no source span to
+  // cut from — the text slice is `executedUnitOf`'s product, not this one's.
+  const unwrapped = unwrapIndirection(words, "");
+  if (unwrapped.kind === "opaque" || unwrapped.layers === 0) return false;
+
+  const head = unwrapped.words.at(0)?.text ?? "";
+  const args = unwrapped.words.slice(1).map((word) => word.text);
+  return proveCommandEffect(head, args).effect === "read";
+}
+
+// ── Unwrapping ───────────────────────────────────────────────────────────────
+
+/**
+ * How an unwrap ended: at the innermost command reachable by peeling
+ * indirection layers, or at an inline-shell payload.
+ *
+ * The two are kept apart because they are different kinds of answer. A peeled
+ * result is a slice of this command line, with words the caller can inspect;
+ * a payload is an inner *program* the enumerator never parsed, so it has text
+ * and nothing else. Collapsing them is how a core-looking first word inside
+ * `sh -c '…'` would come to stand for the whole payload (#803).
+ */
+type UnwrapResult =
+  | { readonly kind: "opaque"; readonly payload: string | null }
+  | {
+      readonly kind: "peeled";
+      readonly text: string;
+      readonly words: readonly CommandWord[];
+      /** How many indirection layers came off; `0` means none did. */
+      readonly layers: number;
+    };
+
+/**
+ * Peel indirection layers off a command unit until an ordinary command, an
+ * opaque payload, or an unrecognized option shape stops the walk.
+ *
+ * Stopping early is not an error: the words peeled so far are returned, and
+ * each caller decides what an incomplete peel is worth — `executedUnitOf`
+ * shows it, {@link isTransparentWrapper} declines it because the head word it
+ * would judge is the wrapper's own.
+ *
+ * `unitText` is the span the peeled `text` is cut from; a caller that wants
+ * only the words passes the empty string and ignores it.
+ */
+function unwrapIndirection(
+  words: readonly CommandWord[],
+  unitText: string,
+): UnwrapResult {
   let text = unitText;
   let current = words;
+  let layers = 0;
 
   for (let depth = 0; depth < MAX_UNWRAP_DEPTH; depth++) {
     const kind = classifyWrapperWords(current);
@@ -85,7 +174,7 @@ export function executedUnitOf(
     if (kind === "opaque-payload") {
       // The payload is an inner *program*, not a slice of this command line, so
       // it is unquoted and terminal — unwrapping it further would need a parse.
-      return nothingNew(opaquePayload(current), unitText);
+      return { kind: "opaque", payload: opaquePayload(current) };
     }
 
     const start = innerCommandIndex(current);
@@ -93,9 +182,10 @@ export function executedUnitOf(
     const end = execTerminatorIndex(current, start);
     text = sliceWords(text, current, start, end).trimEnd();
     current = rebase(current, start, end);
+    layers++;
   }
 
-  return nothingNew(text, unitText);
+  return { kind: "peeled", text, words: current, layers };
 }
 
 /** How many wrapper layers to unwrap before giving up. */

package/src/access-intent/effect.ts

@@ -0,0 +1,56 @@
+/**
+ * A filesystem effect an access can have.
+ *
+ * ADR 0013 §2 reserves a third value, `delete`, as strictly stronger than
+ * `write`; it is not shipped, so nothing can name it in a config or a proof.
+ */
+export type Effect = "read" | "write";
+
+/**
+ * An effect attribution, including the fail-closed base case.
+ *
+ * `unproven` is not a third effect — it is the absence of a proof, and ADR
+ * 0013 §10 makes it consult both directional surfaces, most-restrictive.
+ */
+export type AttributedEffect = Effect | "unproven";
+
+/**
+ * What established an attribution — the blame fact ADR 0013 §7 asks the review
+ * log to record.
+ *
+ * `retracted` is distinct from `unproven` on purpose: "nobody claimed anything
+ * about `pnpm`" and "`find` is a core reader but `-delete` withdrew the claim"
+ * are different diagnoses, and only the second names a line to read.
+ */
+export type EffectSource = "syntax" | "core" | "retracted" | "unproven";
+
+/** A path token's attributed effect, paired with what established it. */
+export interface TokenEffect {
+  readonly effect: AttributedEffect;
+  readonly source: EffectSource;
+}
+
+/** The fail-closed base case: no proof, and nothing to blame for its absence. */
+export const UNPROVEN_EFFECT: TokenEffect = {
+  effect: "unproven",
+  source: "unproven",
+};
+
+/**
+ * Combine two attributions of the same resolved path.
+ *
+ * Agreement keeps the effect, and prefers whichever source has something to
+ * blame — a `retracted` attribution survives a merge with a bare unproven
+ * whichever order the two tokens were collected in. Order-independence
+ * matters because collection order is an accident of the command's shape, and
+ * the blame line is the only reason the source is recorded at all.
+ *
+ * Disagreement falls to {@link UNPROVEN_EFFECT}, because proven-both and
+ * unproven-at-all consult the same two surfaces — ADR 0013's 2026-08-25
+ * amendment reads them as one mechanism, not two — which is what makes the
+ * fold honest rather than lossy.
+ */
+export function mergeTokenEffects(a: TokenEffect, b: TokenEffect): TokenEffect {
+  if (a.effect !== b.effect) return UNPROVEN_EFFECT;
+  return a.source === "unproven" ? b : a;
+}

package/src/access-intent/input-normalizer.ts

@@ -3,7 +3,7 @@ import type { PathNormalizer } from "#src/path-normalizer";
 import { getNonEmptyString, toRecord } from "#src/value-guards";
 import type { AccessIntent, ResolvedAccessIntent } from "./access-intent";
 import { createMcpPermissionTargets } from "./mcp-targets";
-import { PATH_SURFACES } from "./path-surfaces";
+import { PATH_SURFACES, surfaceFamilyOf } from "./path-surfaces";
 import { classifyToolKind } from "./tool-kind";
 
 /**
@@ -95,7 +95,7 @@ function buildInputForSurface(
   const v = value ?? "";
   if (surface === "bash") return { command: v };
   if (surface === "skill") return { name: v };
-  if (surface === "external_directory") return { path: v };
+  if (surfaceFamilyOf(surface) === "external_directory") return { path: v };
   // MCP and tool surfaces: normalizeInput handles them from the surface alone.
   return {};
 }

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

@@ -1,3 +1,5 @@
+import type { AttributedEffect } from "#src/access-intent/effect";
+
 /**
  * File tools that only read — never write — the filesystem.
  * Only these tools are eligible for the Pi infrastructure auto-allow.
@@ -18,13 +20,117 @@ export const PATH_BEARING_TOOLS = new Set([
   "ls",
 ]);
 
+/**
+ * The surface families that carry the read/write capability axis (ADR 0013 §3).
+ *
+ * A bare family name means "both directions": it is what an access whose
+ * direction is proven to be both, or cannot be proven at all, consults — the
+ * fail-closed base case of ADR 0013 §10.
+ */
+const DIRECTIONAL_FAMILIES: ReadonlySet<string> = new Set([
+  "path",
+  "external_directory",
+]);
+
+/**
+ * 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;
+
 /**
  * Surfaces whose patterns are matched against filesystem paths and therefore
- * fold case (and separators) on Windows: the path-bearing tools plus the
- * cross-cutting `path` gate and the `external_directory` boundary gate.
+ * fold case (and separators) on Windows: the path-bearing tools, the
+ * cross-cutting `path` gate, the `external_directory` boundary gate, and each
+ * gate's two directional members.
  */
 export const PATH_SURFACES: ReadonlySet<string> = new Set([
   ...PATH_BEARING_TOOLS,
-  "external_directory",
-  "path",
+  ...DIRECTIONAL_FAMILIES,
+  ...directionalSurfaceNames(),
 ]);
+
+/**
+ * The family a surface belongs to — itself, when it carries no capability
+ * suffix over a directional family.
+ *
+ * A surface that merely ends in `_read` without naming a directional family
+ * (an extension tool called `my_tool_read`) is its own family, so the relation
+ * never captures a name the axis does not own.
+ */
+export function surfaceFamilyOf(surface: string): string {
+  for (const suffix of CAPABILITY_SUFFIXES) {
+    if (!surface.endsWith(suffix)) continue;
+    const family = surface.slice(0, -suffix.length);
+    if (DIRECTIONAL_FAMILIES.has(family)) return family;
+  }
+  return surface;
+}
+
+/**
+ * A family name's directional members, or `null` when `surface` is not a
+ * family name (a directional member itself, or any non-path surface).
+ *
+ * The non-empty tuple is what lets the resolver's family fold be total: it
+ * hands the members straight to `mostRestrictiveOf` with no empty branch.
+ */
+export function surfaceFamilyMembers(
+  surface: string,
+): readonly [string, ...string[]] | null {
+  if (!DIRECTIONAL_FAMILIES.has(surface)) return null;
+  const [read, write] = CAPABILITY_SUFFIXES;
+  return [`${surface}${read}`, `${surface}${write}`];
+}
+
+/**
+ * The narrowest surface in `family` that an attributed effect names.
+ *
+ * An unproven attribution names the bare family, whose two members the
+ * resolver folds most-restrictive — the fail-closed base case of ADR 0013 §10,
+ * which is also where a proven-both access lands.
+ */
+export function capabilitySurfaceForEffect(
+  family: string,
+  effect: AttributedEffect,
+): string {
+  const [read, write] = CAPABILITY_SUFFIXES;
+  switch (effect) {
+    case "read":
+      return `${family}${read}`;
+    case "write":
+      return `${family}${write}`;
+    case "unproven":
+      return family;
+  }
+}
+
+/**
+ * The narrowest surface in `family` that `toolName`'s identity proves.
+ *
+ * A tool's name is one of the three proof sources ADR 0013 §7 names, so it
+ * routes through the same effect-keyed selector every other source does:
+ * `edit` and an unproven bash token reach the bare family by the one path.
+ */
+export function capabilitySurfaceForTool(
+  family: string,
+  toolName: string,
+): string {
+  return capabilitySurfaceForEffect(family, effectProvenByTool(toolName));
+}
+
+/**
+ * The effect a tool's identity proves: the read-only file tools prove a read,
+ * `write` proves a write, and everything else — `edit` (which does both), an
+ * MCP tool, an extension tool — proves nothing.
+ */
+function effectProvenByTool(toolName: string): AttributedEffect {
+  if (READ_ONLY_PATH_BEARING_TOOLS.has(toolName)) return "read";
+  if (toolName === "write") return "write";
+  return "unproven";
+}
+
+function directionalSurfaceNames(): string[] {
+  return [...DIRECTIONAL_FAMILIES].flatMap((family) =>
+    CAPABILITY_SUFFIXES.map((suffix) => `${family}${suffix}`),
+  );
+}

package/src/authority/delegation-envelope.ts

@@ -7,17 +7,25 @@
  * the terminal (a prompt) instead. The checkpoint only ever *tightens* a
  * verdict — it never turns a `defer`/`deny` into an `allow`.
  *
- * The excluded set is the whole `path` surface plus `external_directory`. A
- * finer secret-shaped-`path` exclusion (letting a link allow a non-secret path)
- * is deferred to the allow-capable slice that needs it (#620); until then the
- * conservative whole-surface exclusion ships. The checkpoint is dormant while
- * the only registered links are deny-first (they never `allow`).
+ * The excluded set is the whole `path` surface **family** plus the
+ * `external_directory` family — membership is tested on the family a surface
+ * belongs to, so a directional member (`path_write`) is excluded by
+ * construction and a later capability suffix joins its family for free (ADR
+ * 0013 §4). That is a name-resolution rule, not a scope freeze: it says how a
+ * family name resolves to members, and leaves *which* families are excluded
+ * independently relaxable (#620).
+ *
+ * A finer secret-shaped-`path` exclusion (letting a link allow a non-secret
+ * path) is deferred to the allow-capable slice that needs it (#620); until then
+ * the conservative whole-family exclusion ships. The checkpoint is dormant
+ * while the only registered links are deny-first (they never `allow`).
  */
 
+import { surfaceFamilyOf } from "#src/access-intent/path-surfaces";
 import type { Authorizer } from "./authorizer";
 import type { PromptPermissionDetails } from "./permission-prompter";
 
-/** Surfaces on which a link may never grant an `allow` (ADR 0007 §5). */
+/** Surface families on which a link may never grant an `allow` (ADR 0007 §5). */
 export const DELEGATION_EXCLUDED_SURFACES: ReadonlySet<string> = new Set([
   "external_directory",
   "path",
@@ -49,5 +57,8 @@ export function encloseInDelegationEnvelope(
  */
 function isExcludedSurface(details: PromptPermissionDetails): boolean {
   const surface = details.accessIntent?.surface ?? details.surface ?? undefined;
-  return surface === undefined || DELEGATION_EXCLUDED_SURFACES.has(surface);
+  return (
+    surface === undefined ||
+    DELEGATION_EXCLUDED_SURFACES.has(surfaceFamilyOf(surface))
+  );
 }

package/src/config-schema.ts

@@ -73,13 +73,58 @@ const permissionMapSchema = z
       "A map of wildcard patterns to permission states.\n\nUse `*` for wildcard matching. When multiple patterns match, the **last matching rule wins** — put broad catch-alls first and specific overrides after them.\n\nPattern keys support home directory expansion:\n- `~/path` or `$HOME/path` — expanded to the OS home directory at match time.\n- `~` or `$HOME` alone — expands to the home directory itself.\n\nThe stored pattern is always shown in logs and approval dialogs as written (e.g. `~/dev/*`).",
   });
 
+const surfaceValueSchema = z.union([
+  permissionStateSchema,
+  permissionMapSchema,
+]);
+
+/**
+ * The `path` and `external_directory` families' directional members
+ * (ADR 0013 §3), named so editors offer autocomplete and hover documentation.
+ *
+ * Naming them as properties rather than leaving them to the catchall is also
+ * what lets the loader tell a legal directional key from a misspelled one —
+ * see {@link rejectMisspelledDirectionalKeys}.
+ */
+const DIRECTIONAL_SURFACE_DESCRIPTIONS: Record<
+  string,
+  { description: string; markdownDescription: string }
+> = {
+  path_read: {
+    description:
+      "Cross-cutting gate for reading a file, by path pattern. The useful directional grant.",
+    markdownDescription:
+      'Cross-cutting gate for **reading** a file, matched by path pattern across all path-aware tools.\n\nThis is the directional key worth granting: `"path_read": { "~/dev/*": "allow" }` permits reads without permitting writes.\n\nA bare `"path"` key is sugar that expands into this key **and** `path_write`, with its entries placed first — so an explicit `path_read` entry always has the final say, whatever the key order in the file.',
+  },
+  path_write: {
+    description:
+      "Cross-cutting gate for writing a file, by path pattern. Earns its keep as a restriction.",
+    markdownDescription:
+      'Cross-cutting gate for **writing** a file, matched by path pattern across all path-aware tools.\n\nThis key earns its keep as a *restriction* rather than a grant: `"path_write": { "*": "deny" }` is a coherent read-only-agent posture. A `"path_write": "allow"` on its own does not silence an `edit`, which also reads — grant `path_read` too, or use the bare `"path"` key.',
+  },
+  external_directory_read: {
+    description:
+      "Boundary gate for reading outside the working directory. The relief most asks want.",
+    markdownDescription:
+      'Boundary gate for **reading** a path outside the session working directory.\n\nThe one-line grant for an external root: `"external_directory_read": { "~/dev/*": "allow" }` silences repeated read prompts on a directory outside the tree while a write to the same path still prompts. No parallel `path_read` entry is needed.',
+  },
+  external_directory_write: {
+    description: "Boundary gate for writing outside the working directory.",
+    markdownDescription:
+      'Boundary gate for **writing** to a path outside the session working directory.\n\nA bare `"external_directory"` key is sugar that expands into this key and `external_directory_read`; write this one only to give the two directions different answers.',
+  },
+};
+
 const permissionSchema = z
-  .record(
-    z.string().min(1).meta({
-      description: "A surface name or the universal fallback key '*'.",
-    }),
-    z.union([permissionStateSchema, permissionMapSchema]),
+  .object(
+    Object.fromEntries(
+      Object.entries(DIRECTIONAL_SURFACE_DESCRIPTIONS).map(([key, meta]) => [
+        key,
+        surfaceValueSchema.optional().meta(meta),
+      ]),
+    ),
   )
+  .catchall(surfaceValueSchema)
   .meta({
     description:
       "Flat permission policy. Each key is a surface name; values are a PermissionState string (catch-all) or a pattern→action map.",
@@ -106,9 +151,53 @@ const permissionSchema = z
         mcp: { "*": "ask", mcp_status: "allow", "exa:*": "allow" },
         skill: { "*": "ask", librarian: "allow" },
         external_directory: { "*": "ask", "~/.cargo/registry/*": "allow" },
+        external_directory_read: { "~/dev/*": "allow" },
       },
     ],
-  });
+  })
+  .superRefine(rejectUnusableSurfaceKeys);
+
+/**
+ * Reject the two surface-key spellings that would otherwise sit inert.
+ *
+ * Neither check serializes into the JSON Schema, so an editor will not flag
+ * them; the loader will, fail-closed, with the offending key named.
+ *
+ * 1. A key shaped like a directional surface but misspelled
+ *    (`path_wrote`, `external_directory_reed`). A typo in a *grant* fails safe
+ *    — the rule never fires and the user just gets more prompts — but a typo
+ *    in a *restriction* fails **open**: `path_wrote: {"*": "deny"}` enforces
+ *    nothing at all. The false-positive population is an extension tool
+ *    literally named `path_*` or `external_directory_*`.
+ * 2. An empty key, which `.catchall()` no longer rejects on its own the way
+ *    the record form's `propertyNames: {minLength: 1}` did.
+ */
+function rejectUnusableSurfaceKeys(
+  permission: Record<string, unknown>,
+  ctx: z.core.$RefinementCtx,
+): void {
+  const legalDirectionalKeys = Object.keys(DIRECTIONAL_SURFACE_DESCRIPTIONS);
+  for (const key of Object.keys(permission)) {
+    if (key === "") {
+      ctx.addIssue({
+        code: "custom",
+        path: [key],
+        message: "A surface key must not be empty.",
+      });
+      continue;
+    }
+    if (
+      /^(path|external_directory)_/.test(key) &&
+      !legalDirectionalKeys.includes(key)
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        path: [key],
+        message: `Unknown directional surface key "${key}". The legal spellings are ${legalDirectionalKeys.join(", ")}.`,
+      });
+    }
+  }
+}
 
 const shellToolAliasSchema = z
   .strictObject({

package/src/handlers/gates/bash-command.ts

@@ -2,8 +2,8 @@ import type {
   BashCommand,
   WrapperKind,
 } from "#src/access-intent/bash/command-enumeration";
-import { pickMostRestrictive } from "#src/handlers/gates/candidate-check";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
+import { pickMostRestrictive } from "#src/restrictiveness";
 import type { PermissionCheckResult } from "#src/types";
 
 /**
@@ -60,9 +60,9 @@ export function resolveBashCommandCheck(
 ): PermissionCheckResult {
   if (commands.length === 0) {
     if (isTriviallyEmptyCommand(command)) {
-      return resolveWholeCommand(command, agentName, resolver);
+      return resolveOnBashSurface(command, agentName, resolver);
     }
-    const whole = resolveWholeCommand(command, agentName, resolver);
+    const whole = resolveOnBashSurface(command, agentName, resolver);
     if (whole.state === "deny") {
       return whole;
     }
@@ -77,19 +77,10 @@ export function resolveBashCommandCheck(
   }
 
   const results = commands.map((cmd) => {
-    const base = resolver.resolve({
-      kind: "tool",
-      surface: "bash",
-      input: { command: cmd.text },
-      agentName,
-    });
+    const base = resolveOnBashSurface(cmd.text, agentName, resolver);
     const floored =
       cmd.wrapperKind && base.state === "allow"
-        ? {
-            ...base,
-            state: "ask" as const,
-            matchedPattern: WRAPPER_SENTINEL[cmd.wrapperKind],
-          }
+        ? resolveWrapperUnit(cmd, cmd.wrapperKind, base, agentName, resolver)
         : base;
     const result = cmd.context
       ? { ...floored, commandContext: cmd.context }
@@ -100,10 +91,49 @@ export function resolveBashCommandCheck(
   });
   return (
     pickMostRestrictive(results) ??
-    resolveWholeCommand(command, agentName, resolver)
+    resolveOnBashSurface(command, agentName, resolver)
   );
 }
 
+/**
+ * Resolve a wrapper unit whose own text resolved to `allow`.
+ *
+ * A wrapper hides or indirects the command that should be gated, so its `allow`
+ * is clamped up to a synthetic `ask` naming the kind that caused it — unless
+ * the enumerator established that the floor has no reason left to hold, in
+ * which case the unit is resolved by the rules of the command it runs (ADR 0013
+ * §11, #803).
+ *
+ * Only an `allow` reaches here, which is what makes the exemption unable to
+ * weaken anything: an explicit `deny` or `ask` on the wrapper is decided before
+ * this function is consulted, and no inner rule is read at all.
+ */
+function resolveWrapperUnit(
+  cmd: BashCommand,
+  wrapperKind: WrapperKind,
+  base: PermissionCheckResult,
+  agentName: string | undefined,
+  resolver: ScopedPermissionResolver,
+): PermissionCheckResult {
+  const inner = cmd.floorExemption && cmd.executedUnit;
+  if (!inner) {
+    return {
+      ...base,
+      state: "ask",
+      matchedPattern: WRAPPER_SENTINEL[wrapperKind],
+    };
+  }
+  // The inner command's rule decides, but the unit is still what runs: the
+  // prompt, the decision value, and the session-approval suggestion all read
+  // `command`, and naming a fragment of the command line there would offer a
+  // grant that does not cover what the user is looking at.
+  return {
+    ...resolveOnBashSurface(inner, agentName, resolver),
+    command: base.command,
+    floorExemption: cmd.floorExemption,
+  };
+}
+
 /**
  * True when a command has genuinely nothing to gate: it is empty,
  * whitespace-only, or contains only comment lines (every non-blank line starts
@@ -118,8 +148,14 @@ function isTriviallyEmptyCommand(command: string): boolean {
   return lines.every((line) => line.startsWith("#"));
 }
 
-/** Resolve the whole command string as a single unit on the `bash` surface. */
-function resolveWholeCommand(
+/**
+ * Resolve one command string against the `bash` surface's rules.
+ *
+ * Three callers share it: each command unit of the chain, the whole command
+ * when the chain yields no units, and the inner command of a wrapper the floor
+ * no longer covers.
+ */
+function resolveOnBashSurface(
   command: string,
   agentName: string | undefined,
   resolver: ScopedPermissionResolver,