@gotgenes/pi-permission-system 27.0.1 → 27.1.1

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,

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

@@ -17,6 +17,13 @@ import type { ToolCallContext } from "./types";
  * Returns a `GateBypass` when all paths are allowed (by config or session rule).
  * Returns a `GateDescriptor` with multi-pattern sessionApproval for uncovered paths.
  *
+ * Each path is resolved on the narrowest `external_directory`-family surface
+ * its own attributed effect names. The session approval holds one surface for
+ * all its patterns, so it narrows only when every uncovered path agrees; a
+ * mixed-direction ask falls back to the bare family, which is exactly today's
+ * width. Closing that last gap needs `(surface, pattern)` pairs on the
+ * approval and its forwarded wire form (#810).
+ *
  * The shell command (native `bash` or an aliased shell tool) is read from the
  * injected `BashProgram`, which owns the source text it was parsed from, so
  * this gate does not re-derive the input field name (#574).
@@ -30,8 +37,8 @@ export function describeBashExternalDirectoryGate(
   if (!bashProgram) return null;
   const command = bashProgram.commandText();
 
-  const externalPaths = bashProgram.externalPaths();
-  if (externalPaths.length === 0) return null;
+  const externalAccesses = bashProgram.externalAccesses();
+  if (externalAccesses.length === 0) return null;
 
   // Resolve every external path on the external_directory surface and keep the
   // ones not already allowed (config-level allows suppress the prompt just as
@@ -39,7 +46,7 @@ export function describeBashExternalDirectoryGate(
   // matching and the worst-uncovered selection.
   const { uncovered: uncoveredEntries, worstCheck } =
     selectUncoveredExternalPaths(
-      externalPaths,
+      externalAccesses,
       resolver,
       tcc.agentName ?? undefined,
     );
@@ -65,7 +72,7 @@ export function describeBashExternalDirectoryGate(
           toolName: tcc.toolName,
           agentName: tcc.agentName,
           command,
-          externalPaths: externalPaths.map((p) => p.value()),
+          externalPaths: externalAccesses.map(({ path }) => path.value()),
           resolution: "session_approved",
         },
       },
@@ -86,6 +93,7 @@ export function describeBashExternalDirectoryGate(
     resolvedPath: path.resolvedAlias(),
   }));
 
+  const surface = worstEntry.surface;
   const payload = buildBashExternalDirectoryAskPayload({
     command,
     externalPaths: disclosures,
@@ -93,6 +101,7 @@ export function describeBashExternalDirectoryGate(
     agentName: tcc.agentName,
     toolName: tcc.toolName,
     matchedPattern: preCheck.matchedPattern,
+    surface,
   });
 
   const patterns = uncoveredEntries.map(({ path }) =>
@@ -100,17 +109,20 @@ export function describeBashExternalDirectoryGate(
   );
 
   return {
-    surface: "external_directory",
+    surface,
     input: {},
     payload,
-    sessionApproval: SessionApproval.multiple("external_directory", patterns),
+    sessionApproval: SessionApproval.multiple(
+      approvalSurfaceFor(uncoveredEntries),
+      patterns,
+    ),
     promptDetails: {
       source: "tool_call",
       agentName: tcc.agentName,
       toolCallId: tcc.toolCallId,
       toolName: tcc.toolName,
       command,
-      accessIntent: accessFactsFromPath("external_directory", worstEntry.path),
+      accessIntent: accessFactsFromPath(surface, worstEntry.path),
     },
     logContext: {
       source: "tool_call",
@@ -119,11 +131,32 @@ export function describeBashExternalDirectoryGate(
       agentName: tcc.agentName,
       command,
       externalPaths: uncoveredPaths,
+      // The blame line ADR 0013 §7 asks for: `request.surface` already records
+      // the direction, and these two record what established it.
+      effect: worstEntry.effect.effect,
+      effectSource: worstEntry.effect.source,
     },
     decision: {
-      surface: "external_directory",
+      surface,
       value: command,
     },
     preCheck,
   };
 }
+
+/**
+ * The surface one session approval can carry for every uncovered path at once.
+ *
+ * A {@link SessionApproval} holds one surface for all its patterns, so it can
+ * narrow only when the whole ask agrees on a direction. The bare family is the
+ * fallback because it sugar-expands onto both members — exactly the width a
+ * mixed-direction command is granted today, never wider.
+ */
+function approvalSurfaceFor(
+  uncoveredEntries: readonly { readonly surface: string }[],
+): string {
+  const surfaces = new Set(uncoveredEntries.map(({ surface }) => surface));
+  return surfaces.size === 1
+    ? [...surfaces][0]
+    : ("external_directory" as const);
+}

package/src/handlers/gates/bash-path-extractor.ts

@@ -4,7 +4,7 @@ import type { PathNormalizer } from "#src/path-normalizer";
 /**
  * Extract paths from a bash command that resolve outside CWD.
  *
- * Thin facade over {@link BashProgram.externalPaths}; parses the command
+ * Thin facade over {@link BashProgram.externalAccesses}; parses the command
  * through the injected {@link PathNormalizer} (platform + cwd baked in) and
  * returns the cd-aware external paths in their lexical (as-typed) string form.
  * See `BashProgram` for the parsing and resolution semantics.
@@ -18,6 +18,6 @@ export async function extractExternalPathsFromBashCommand(
   normalizer: PathNormalizer,
 ): Promise<string[]> {
   return (await BashProgram.parse(command, normalizer))
-    .externalPaths()
-    .map((p) => p.value());
+    .externalAccesses()
+    .map(({ path }) => path.value());
 }

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

@@ -1,11 +1,13 @@
 import type { AccessPath } from "#src/access-intent/access-path";
 import type { BashProgram } from "#src/access-intent/bash/program";
+import type { TokenEffect } from "#src/access-intent/effect";
+import { capabilitySurfaceForEffect } from "#src/access-intent/path-surfaces";
 import type { PathNormalizer } from "#src/path-normalizer";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import { buildPathAskPayload } from "#src/presentation/path-ask-payload";
+import { pickMostRestrictive } from "#src/restrictiveness";
 import { SessionApproval } from "#src/session-approval";
 import type { PermissionCheckResult } from "#src/types";
-import { pickMostRestrictive } from "./candidate-check";
 import type { GateResult } from "./descriptor";
 import { accessFactsFromPath } from "./helpers";
 import type { ToolCallContext } from "./types";
@@ -15,10 +17,17 @@ import type { ToolCallContext } from "./types";
  *
  * Reads path-rule candidates from the injected `BashProgram` (the broader
  * `path`-rule filter, accepting dot-files and relative paths). Each candidate
- * pairs the raw token with cd-aware policy values; the gate evaluates those
- * values against the `path` permission surface and returns the most
- * restrictive result, while prompts, logs, and session approvals use the raw
- * token.
+ * pairs the raw token with cd-aware policy values and the effect its position
+ * proved; the gate evaluates those values against the narrowest `path`-family
+ * surface that effect names and returns the most restrictive result, while
+ * prompts, logs, and session approvals use the raw token.
+ *
+ * A proven read resolves on `path_read`, a proven write on `path_write`, and
+ * an unproven token on the bare family, whose two members the resolver folds
+ * most-restrictive (ADR 0013 §10). The deciding token's surface is the one the
+ * descriptor, the payload, the access facts, the decision, and the session
+ * approval all carry — a session grant is never wider than what the gate
+ * proved.
  *
  * Returns `null` when the gate does not apply (not a shell invocation, no
  * command, no tokens extracted, or all tokens evaluate to `allow`).
@@ -48,14 +57,17 @@ export function describeBashPathGate(
   const uncovered: Array<{
     token: string;
     path: AccessPath;
+    surface: string;
+    effect: TokenEffect;
     check: PermissionCheckResult;
   }> = [];
   let allSessionCovered = true;
 
-  for (const { token, path } of candidates) {
+  for (const { token, path, effect } of candidates) {
+    const surface = capabilitySurfaceForEffect("path", effect.effect);
     const check = resolver.resolve({
       kind: "access-path",
-      surface: "path",
+      surface,
       path,
       agentName: tcc.agentName ?? undefined,
     });
@@ -73,11 +85,11 @@ export function describeBashPathGate(
     }
 
     if (check.state === "deny") {
-      uncovered.push({ token, path, check });
+      uncovered.push({ token, path, surface, effect, check });
       break; // Short-circuit on deny.
     }
     if (check.state === "ask") {
-      uncovered.push({ token, path, check });
+      uncovered.push({ token, path, surface, effect, check });
     }
   }
 
@@ -122,25 +134,27 @@ export function describeBashPathGate(
   // path), so it matches the values a later call produces. For an unknown base
   // (`forLiteral`) `value()` is the raw token.
   const pattern = normalizer.approvalPatternFor(worstEntry.path);
+  const surface = worstEntry.surface;
   const payload = buildPathAskPayload({
     toolName: tcc.toolName,
     pathValue: worstToken,
     agentName: tcc.agentName,
     matchedPattern: worstCheck.matchedPattern,
+    surface,
   });
 
   return {
-    surface: "path",
+    surface,
     input: { path: worstToken },
     payload,
-    sessionApproval: SessionApproval.single("path", pattern),
+    sessionApproval: SessionApproval.single(surface, pattern),
     promptDetails: {
       source: "tool_call",
       agentName: tcc.agentName,
       toolCallId: tcc.toolCallId,
       toolName: tcc.toolName,
       command,
-      accessIntent: accessFactsFromPath("path", worstEntry.path),
+      accessIntent: accessFactsFromPath(surface, worstEntry.path),
     },
     logContext: {
       source: "tool_call",
@@ -149,9 +163,13 @@ export function describeBashPathGate(
       agentName: tcc.agentName,
       command,
       path: worstToken,
+      // The blame line ADR 0013 §7 asks for: `request.surface` already records
+      // the direction, and these two record what established it.
+      effect: worstEntry.effect.effect,
+      effectSource: worstEntry.effect.source,
     },
     decision: {
-      surface: "path",
+      surface,
       value: worstToken,
     },
     preCheck: worstCheck,

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

@@ -1,11 +1,18 @@
 import type { AccessPath } from "#src/access-intent/access-path";
+import type { BashExternalPath } from "#src/access-intent/bash/bash-path-resolver";
+import type { TokenEffect } from "#src/access-intent/effect";
+import { capabilitySurfaceForEffect } from "#src/access-intent/path-surfaces";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
+import { pickMostRestrictive } from "#src/restrictiveness";
 import type { PermissionCheckResult } from "#src/types";
-import { pickMostRestrictive } from "./candidate-check";
 
 /** An external path whose resolved `external_directory` state is not "allow". */
 export interface UncoveredExternalPath {
   path: AccessPath;
+  /** The family member the path's own effect named, and the check answered. */
+  surface: string;
+  /** What the effect was, and what established it — the review log's blame. */
+  effect: TokenEffect;
   check: PermissionCheckResult;
 }
 
@@ -17,7 +24,11 @@ export interface UncoveredExternalPaths {
 }
 
 /**
- * Resolve one external path's policy on the `external_directory` surface.
+ * Resolve one external path's policy on an `external_directory`-family surface.
+ *
+ * `surface` is the narrowest family member the caller can prove — the bare
+ * family name when it can prove nothing narrower, which the resolver folds
+ * over both directions (ADR 0013 §10).
  *
  * Emits an `access-path` {@link AccessIntent}; the resolver unwraps it via
  * {@link AccessPath.matchValues} so a config pattern on either the typed or
@@ -28,35 +39,48 @@ export interface UncoveredExternalPaths {
 export function resolveExternalDirectoryPolicy(
   path: AccessPath,
   resolver: ScopedPermissionResolver,
+  surface: string,
   agentName: string | undefined,
 ): PermissionCheckResult {
   return resolver.resolve({
     kind: "access-path",
-    surface: "external_directory",
+    surface,
     path,
     agentName,
   });
 }
 
 /**
- * Resolve a set of external paths and select those not already allowed.
+ * Resolve a set of external accesses and select those not already allowed.
  *
- * Each path is resolved via {@link resolveExternalDirectoryPolicy}; entries
- * whose state is not "allow" are collected (filtering on state, not source, so
- * config-level allow rules suppress the prompt just as session-level allow
- * rules do), and the most restrictive uncovered check is returned so a config
- * "deny" is not downgraded to the catch-all "ask".
+ * Each access is resolved via {@link resolveExternalDirectoryPolicy} on the
+ * narrowest family member its own effect names — a proven read on
+ * `external_directory_read`, an unproven one on the bare family, which the
+ * resolver folds over both directions (ADR 0013 §10). Entries whose state is
+ * not "allow" are collected (filtering on state, not source, so config-level
+ * allow rules suppress the prompt just as session-level allow rules do), and
+ * the most restrictive uncovered check is returned so a config "deny" is not
+ * downgraded to the catch-all "ask".
  */
 export function selectUncoveredExternalPaths(
-  paths: readonly AccessPath[],
+  accesses: readonly BashExternalPath[],
   resolver: ScopedPermissionResolver,
   agentName: string | undefined,
 ): UncoveredExternalPaths {
   const uncovered: UncoveredExternalPath[] = [];
-  for (const path of paths) {
-    const check = resolveExternalDirectoryPolicy(path, resolver, agentName);
+  for (const { path, effect } of accesses) {
+    const surface = capabilitySurfaceForEffect(
+      "external_directory",
+      effect.effect,
+    );
+    const check = resolveExternalDirectoryPolicy(
+      path,
+      resolver,
+      surface,
+      agentName,
+    );
     if (check.state !== "allow") {
-      uncovered.push({ path, check });
+      uncovered.push({ path, surface, effect, check });
     }
   }
   return {

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

@@ -1,3 +1,4 @@
+import { capabilitySurfaceForTool } from "#src/access-intent/path-surfaces";
 import { getToolInputPath } from "#src/access-intent/tool-input-path";
 import type { PathNormalizer } from "#src/path-normalizer";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
@@ -71,10 +72,15 @@ export function describeExternalDirectoryGate(
   // ── Build descriptor for permission check ───────────────────────────────
   const resolvedAlias = accessPath.resolvedAlias();
 
+  // The narrowest `external_directory`-family surface this tool's identity
+  // proves; the bare family name folds both directions (ADR 0013 §10).
+  const surface = capabilitySurfaceForTool("external_directory", tcc.toolName);
+
   // The runner consumes this preCheck and skips its own resolve.
   const preCheck = resolveExternalDirectoryPolicy(
     accessPath,
     resolver,
+    surface,
     tcc.agentName ?? undefined,
   );
   const pattern = normalizer.approvalPatternFor(accessPath);
@@ -86,21 +92,22 @@ export function describeExternalDirectoryGate(
     cwd: tcc.cwd,
     agentName: tcc.agentName,
     matchedPattern: preCheck.matchedPattern,
+    surface,
   });
 
   return {
-    surface: "external_directory",
+    surface,
     input: {},
     preCheck,
     payload,
-    sessionApproval: SessionApproval.single("external_directory", pattern),
+    sessionApproval: SessionApproval.single(surface, pattern),
     promptDetails: {
       source: "tool_call",
       agentName: tcc.agentName,
       toolCallId: tcc.toolCallId,
       toolName: tcc.toolName,
       path: externalDirectoryPath,
-      accessIntent: accessFactsFromPath("external_directory", accessPath),
+      accessIntent: accessFactsFromPath(surface, accessPath),
     },
     logContext: {
       source: "tool_call",
@@ -110,7 +117,7 @@ export function describeExternalDirectoryGate(
       path: externalDirectoryPath,
     },
     decision: {
-      surface: "external_directory",
+      surface,
       value: externalDirectoryPath,
     },
   };