@gotgenes/pi-permission-system 27.0.1 → 27.1.1

package/src/access-intent/bash/token-collection.ts

@@ -1,4 +1,5 @@
 import { basename } from "node:path";
+import { proveCommandEffect } from "#src/access-intent/bash/command-effects";
 import {
   EXECUTION_HOST_TYPES,
   forEachNestedExecution,
@@ -10,6 +11,20 @@ import {
   SKIP_SUBTREE_TYPES,
 } 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";
+
+/**
+ * A collected path-candidate token paired with the effect its position proved.
+ *
+ * The pairing is made where the token is *produced*, never by mapping a whole
+ * result: a nested execution's tokens carry their own command's attribution
+ * and must not be overwritten by the enclosing one.
+ */
+export interface PathToken {
+  readonly token: string;
+  readonly effect: TokenEffect;
+}
 
 // ── Public surface ─────────────────────────────────────────────────────────
 
@@ -29,7 +44,7 @@ import type { TSNode } from "#src/access-intent/bash/parser";
  * as path candidates. For all other commands, collects all
  * arguments generically.
  */
-export function collectPathCandidateTokens(node: TSNode): string[] {
+export function collectPathCandidateTokens(node: TSNode): PathToken[] {
   if (node.type === "command") return collectCommandTokens(node);
   if (node.type === "file_redirect") return collectRedirectTokens(node);
   if (EXECUTION_HOST_TYPES.has(node.type)) {
@@ -37,7 +52,7 @@ export function collectPathCandidateTokens(node: TSNode): string[] {
   }
   if (SKIP_SUBTREE_TYPES.has(node.type)) return [];
 
-  const tokens: string[] = [];
+  const tokens: PathToken[] = [];
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
     if (child) tokens.push(...collectPathCandidateTokens(child));
@@ -49,16 +64,25 @@ export function collectPathCandidateTokens(node: TSNode): string[] {
  * Select the collection strategy for a `command` node: pattern-first
  * commands use `collectPatternCommandTokens`; all others use
  * `collectGenericCommandTokens`.
+ *
+ * Every token the command owns carries the effect its head word proves — the
+ * pure-reader core, read through the *raw* head word so a path-qualified
+ * spelling proves nothing. A nested execution collected along the way keeps
+ * its own command's attribution instead.
  */
-export function collectCommandTokens(node: TSNode): string[] {
+export function collectCommandTokens(node: TSNode): PathToken[] {
+  const effect = proveCommandEffect(
+    extractCommandWord(node) ?? "",
+    commandArgumentWords(node),
+  );
   const commandName = extractCommandName(node);
   const config = commandName
     ? PATTERN_FIRST_COMMANDS.get(commandName)
     : undefined;
   const tokens = config
-    ? collectPatternCommandTokens(node, config)
-    : collectGenericCommandTokens(node);
-  return [...tokens, ...collectEmbeddedOptionValues(node)];
+    ? collectPatternCommandTokens(node, config, effect)
+    : collectGenericCommandTokens(node, effect);
+  return [...tokens, ...collectEmbeddedOptionValues(node, effect)];
 }
 
 /**
@@ -72,14 +96,24 @@ export function collectCommandTokens(node: TSNode): string[] {
  * Both passes are needed: a substitution can be the destination outright, or be
  * concatenated into it (`> ${DIR}/$(cmd)`), and a `concatenation` is itself an
  * argument node.
+ *
+ * The operator proves the destination's effect outright, and that proof is
+ * absolute: it overrides whatever the redirected command's own head word
+ * proved, because `> out.txt` writes `out.txt` however read-only the command
+ * in front of it is. A destination the operator names as a file descriptor
+ * (`2>&1`) contributes no token at all.
+ *
+ * Reading the redirect node itself belongs to `redirect-analysis.ts`, which
+ * the command enumerator consults for the same fact (#803).
  */
-export function collectRedirectTokens(node: TSNode): string[] {
-  const tokens: string[] = [];
+export function collectRedirectTokens(node: TSNode): PathToken[] {
+  const tokens: PathToken[] = [];
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
     if (!child) continue;
     if (ARG_NODE_TYPES.has(child.type)) {
-      tokens.push(resolveNodeText(child));
+      const effect = redirectEffectForDestination(node, child);
+      if (effect) tokens.push({ token: resolveNodeText(child), effect });
     }
     tokens.push(...collectHostedExecutionTokens(child));
   }
@@ -97,11 +131,11 @@ export function collectRedirectTokens(node: TSNode): string[] {
  * (`> ${DIR}/$(cmd)`); `forEachNestedExecution` searches strictly within a
  * subtree, so the first case is checked here.
  */
-function collectHostedExecutionTokens(node: TSNode): string[] {
+function collectHostedExecutionTokens(node: TSNode): PathToken[] {
   if (NESTED_EXECUTION_CONTEXTS.has(node.type)) {
     return collectPathCandidateTokens(node);
   }
-  const tokens: string[] = [];
+  const tokens: PathToken[] = [];
   forEachNestedExecution(node, (contextNode) => {
     tokens.push(...collectPathCandidateTokens(contextNode));
   });
@@ -112,14 +146,34 @@ function collectHostedExecutionTokens(node: TSNode): string[] {
  * Extract the command name from a `command` node.
  * Returns the basename (e.g. `/usr/bin/sed` → `sed`), or undefined
  * if the command name cannot be determined (e.g. variable expansion).
+ *
+ * The basename is what {@link PATTERN_FIRST_COMMANDS} needs: `/usr/bin/sed`
+ * parses its arguments exactly as `sed` does. It is the wrong question for a
+ * capability claim, where the directory prefix is the whole point — use
+ * {@link extractCommandWord} there.
  */
 export function extractCommandName(node: TSNode): string | undefined {
+  const word = extractCommandWord(node);
+  return word === undefined ? undefined : basename(word);
+}
+
+/**
+ * Extract the head word of a `command` node exactly as it was written, or
+ * undefined when it cannot be determined (e.g. variable expansion).
+ *
+ * Unbasenamed on purpose: `./grep` and `/tmp/evil/grep` name programs the
+ * pure-reader core's audit never saw, so an effect proof must be able to tell
+ * them from a bare `grep` — the Codex lesson the bare-basename rule encodes.
+ * Documented against {@link extractCommandName}, which answers the other
+ * question.
+ */
+export function extractCommandWord(node: TSNode): string | undefined {
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
     if (!child) continue;
     if (child.type === "command_name") {
       const text = resolveNodeText(child);
-      return text ? basename(text) : undefined;
+      return text === "" ? undefined : text;
     }
   }
   return undefined;
@@ -127,6 +181,25 @@ export function extractCommandName(node: TSNode): string | undefined {
 
 // ── Private helpers and config ─────────────────────────────────────────────
 
+/**
+ * The command's own argument words, which the retraction guards read.
+ *
+ * Reads the argument nodes directly rather than the collected tokens, because
+ * a guard fires on an *option* (`find -delete`) and no collector emits one.
+ */
+function commandArgumentWords(node: TSNode): string[] {
+  const words: string[] = [];
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child) continue;
+    if (child.type === "command_name" || child.type === "variable_assignment")
+      continue;
+    if (!ARG_NODE_TYPES.has(child.type)) continue;
+    words.push(resolveNodeText(child));
+  }
+  return words;
+}
+
 /**
  * A long or short option carrying its value inline: one or two leading dashes,
  * a name containing no `=` or whitespace, then `=` and a non-empty value.
@@ -148,8 +221,11 @@ const OPTION_VALUE_PATTERN = /^-{1,2}[^=\s]+=(.+)$/;
  * here is what lets the projection see option-embedded paths without per-command
  * option tables (ADR 0009, #645).
  */
-function collectEmbeddedOptionValues(node: TSNode): string[] {
-  const values: string[] = [];
+function collectEmbeddedOptionValues(
+  node: TSNode,
+  effect: TokenEffect,
+): PathToken[] {
+  const values: PathToken[] = [];
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
     if (!child) continue;
@@ -158,7 +234,7 @@ function collectEmbeddedOptionValues(node: TSNode): string[] {
     if (!ARG_NODE_TYPES.has(child.type)) continue;
 
     const value = OPTION_VALUE_PATTERN.exec(resolveNodeText(child))?.[1];
-    if (value !== undefined) values.push(value);
+    if (value !== undefined) values.push({ token: value, effect });
   }
   return values;
 }
@@ -322,13 +398,14 @@ function classifyPatternCommandFlag(
 function collectPatternCommandTokens(
   node: TSNode,
   config: PatternCommandConfig,
-): string[] {
+  effect: TokenEffect,
+): PathToken[] {
   const patternPositionals = config.patternPositionals ?? 1;
   let hasExplicitScript = false;
   let positionalsSeen = 0;
   let nextArgAction: "skip" | "extract" | null = null;
   let pastEndOfFlags = false;
-  const tokens: string[] = [];
+  const tokens: PathToken[] = [];
 
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
@@ -353,7 +430,7 @@ function collectPatternCommandTokens(
       continue;
     }
     if (nextArgAction === "extract") {
-      tokens.push(text);
+      tokens.push({ token: text, effect });
       nextArgAction = null;
       continue;
     }
@@ -387,7 +464,7 @@ function collectPatternCommandTokens(
     }
 
     // File argument — collect as path candidate.
-    tokens.push(text);
+    tokens.push({ token: text, effect });
   }
 
   return tokens;
@@ -397,8 +474,11 @@ function collectPatternCommandTokens(
  * Collect all argument tokens from a generic (non-pattern-first) command node,
  * skipping the command name and variable assignments.
  */
-function collectGenericCommandTokens(node: TSNode): string[] {
-  const tokens: string[] = [];
+function collectGenericCommandTokens(
+  node: TSNode,
+  effect: TokenEffect,
+): PathToken[] {
+  const tokens: PathToken[] = [];
   let seenCommandName = false;
 
   for (let i = 0; i < node.childCount; i++) {
@@ -421,7 +501,7 @@ function collectGenericCommandTokens(node: TSNode): string[] {
 
     // Argument nodes: resolve their text and collect.
     if (ARG_NODE_TYPES.has(child.type)) {
-      tokens.push(resolveNodeText(child));
+      tokens.push({ token: resolveNodeText(child), effect });
       continue;
     }
 

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))
+  );
 }