@gotgenes/pi-permission-system 39.0.0 → 39.0.2

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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).
 
+## [39.0.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v39.0.1...pi-permission-system-v39.0.2) (2026-10-03)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** stop logging config- and default-allowed bash external paths as session approvals ([1e597c0](https://github.com/gotgenes/pi-packages/commit/1e597c033c58843f298d9fd0f01cf227dc649e60)), closes [#1011](https://github.com/gotgenes/pi-packages/issues/1011)
+
+### Documentation
+
+* **pi-permission-system:** say what external_directory does when the key is absent ([7319277](https://github.com/gotgenes/pi-packages/commit/7319277d338665225d59af21c43b463e94bda6e6)), closes [#1011](https://github.com/gotgenes/pi-packages/issues/1011)
+
+## [39.0.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v39.0.0...pi-permission-system-v39.0.1) (2026-10-03)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** label two paths that share one session glob by that glob ([3ebe54f](https://github.com/gotgenes/pi-packages/commit/3ebe54fc5dd1d7900dfe4927f923e0f223dcb65c)), closes [#989](https://github.com/gotgenes/pi-packages/issues/989)
+* **pi-permission-system:** scope a directory's session approval to that directory, not its parent ([a0bcf97](https://github.com/gotgenes/pi-packages/commit/a0bcf979e1e4bdb8b0c1cf9575432cc6e3ce4525)), closes [#989](https://github.com/gotgenes/pi-packages/issues/989)
+* **pi-permission-system:** name the session-approval scope in a path ask that proves no direction ([483a1ef](https://github.com/gotgenes/pi-packages/commit/483a1ef951dc8c4677a9e02e94c5ce7487535cdf)), closes [#989](https://github.com/gotgenes/pi-packages/issues/989)
+
+### Documentation
+
+* **pi-permission-system:** document directory-scoped session approvals ([402cdf7](https://github.com/gotgenes/pi-packages/commit/402cdf721eb628a4eea926e3310acf1f1e07c8df)), closes [#989](https://github.com/gotgenes/pi-packages/issues/989)
+
 ## [39.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v38.0.2...pi-permission-system-v39.0.0) (2026-10-03)
 
 

package/docs/configuration.md

@@ -789,6 +789,9 @@ Use a pattern map to allow specific directories without opening all external acc
 For example, `read: "allow"` can permit ordinary reads while `external_directory: "ask"` still requires confirmation before reading `../outside.txt` or an absolute path outside `ctx.cwd`.
 Optional-path search tools (`find`, `grep`, `ls`) skip this check when no `path` is provided.
 
+When no `external_directory` key is present, the universal fallback (`permission["*"]`) applies.
+So `"*": "allow"` lets every outside-CWD access through with no prompt and, like any policy allow, no review-log entry; the examples on this page set `"*": "ask"` inside `external_directory` so the boundary asks regardless of the fallback.
+
 #### Allow an outside-CWD cache directory
 
 When an agent keeps reading a local cache outside the working tree — `~/.cargo/registry`, `~/.npm`, `~/go/pkg/mod` — and you want to stop confirming it every time, allow that directory on the `external_directory` surface:

package/docs/session-approvals.md

@@ -59,6 +59,14 @@ The suggested pattern is surface-specific:
 | tool with path (read, write, …) | `read` for `src/foo.ts`      | `src/*`                   |
 | tool catch-all                  | `read` (no extractable path) | `*`                       |
 | external_directory              | `/other/project/src/foo.ts`  | `/other/project/src/*`    |
+| external_directory (directory)  | `ls /other/project`          | `/other/project/*`        |
+
+A path that names an existing directory (`ls`, `find`, `grep`, or an extension tool's directory argument) is scoped to that directory, not its parent.
+The approval records two rules — the directory itself and `<dir>/*` — so a repeated `ls` of the directory and every file beneath it are covered, while a sibling directory such as `/other/project-b` still asks.
+The dialog names the pair by its contents glob, `"/other/project/*"`.
+A path that does not exist yet, or a bash token whose base directory is unknown, keeps the parent-directory scope.
+
+When a path ask proves no read/write direction (an extension tool, or `edit`), the session option names its scope as `Yes, allow access to "<pattern>" for this session`.
 
 ## Bash Arity Table
 

package/package.json

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

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

@@ -2,6 +2,7 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
   buildDirectionalSessionLabels,
   buildForwardedScopeLabels,
+  buildPathAccessSessionLabel,
   describeGrantTarget,
 } from "#src/presentation/pattern-suggest";
 import {
@@ -126,9 +127,10 @@ function unansweredDecision(reason: string): PermissionPromptDecision {
 /**
  * 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
+ * The label names what the session grant covers: the proven direction and
+ * target for a directional path ask, else a gate-supplied label, else the
+ * target alone for a path ask that proves no direction. 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).
  *
@@ -144,7 +146,11 @@ function buildRequestOptions(
   const widths = direction
     ? buildDirectionalSessionLabels(direction, describeGrantTarget(grants))
     : null;
-  const sessionLabel = widths?.sessionLabel ?? details.sessionLabel;
+  const sessionLabel =
+    widths?.sessionLabel ??
+    details.sessionLabel ??
+    buildPathAccessSessionLabel(grants) ??
+    undefined;
 
   const options: RequestPermissionOptions = {
     ...(sessionLabel ? { sessionLabel } : {}),

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

@@ -14,7 +14,10 @@ import type { ToolCallContext } from "./types";
  * Reads the external paths from the injected `BashProgram` and checks whether
  * any reference directories outside the working directory. Returns `null` when the gate
  * does not apply (not a shell invocation, no command, or no external paths found).
- * Returns a `GateBypass` when all paths are allowed (by config or session rule).
+ * Returns `null` when every path is allowed by a config rule or the universal
+ * fallback — like any policy allow, it writes no review entry. Returns a
+ * `GateBypass` recording a session approval when every path is allowed and at
+ * least one was covered by a session grant.
  * Returns a `GateDescriptor` with multi-pattern sessionApproval for uncovered paths.
  *
  * Each path is resolved on the narrowest `external_directory`-family surface
@@ -42,23 +45,29 @@ export function describeBashExternalDirectoryGate(
 
   // Resolve every external path on the external_directory surface and keep the
   // ones not already allowed (config-level allows suppress the prompt just as
-  // session-level allows do); the shared helper single-sources the #418 alias
-  // matching and the worst-uncovered selection.
-  const { uncovered: uncoveredEntries, worstCheck } =
-    selectUncoveredExternalPaths(
-      externalAccesses,
-      resolver,
-      tcc.agentName ?? undefined,
-    );
+  // session-level allows do), noting which allowed ones a session grant
+  // covered; the shared helper single-sources the #418 alias matching and the
+  // worst-uncovered selection.
+  const {
+    uncovered: uncoveredEntries,
+    sessionCovered,
+    worstCheck,
+  } = selectUncoveredExternalPaths(
+    externalAccesses,
+    resolver,
+    tcc.agentName ?? undefined,
+  );
   const uncoveredPaths = uncoveredEntries.map(({ path }) => path.value());
 
   if (uncoveredPaths.length === 0) {
+    // No session grant decided any path: policy alone allowed the command.
+    if (sessionCovered.length === 0) return null;
     return {
       action: "allow",
-      // A whole-command bypass covers every external path at once, and each
-      // may have matched a different session pattern -- so the surface is one
-      // value and the pattern is not. The entry's `externalPaths` lists what
-      // was covered.
+      // A whole-command bypass covers every session-granted path at once, and
+      // each may have matched a different session pattern -- so the surface is
+      // one value and the pattern is not. The entry's `externalPaths` lists the
+      // paths a grant covered, never the ones policy allowed.
       decidedBy: {
         kind: "session_approval",
         surface: "external_directory",
@@ -72,7 +81,7 @@ export function describeBashExternalDirectoryGate(
           toolName: tcc.toolName,
           agentName: tcc.agentName,
           command,
-          externalPaths: externalAccesses.map(({ path }) => path.value()),
+          externalPaths: sessionCovered.map((path) => path.value()),
           resolution: "session_approved",
         },
       },
@@ -109,10 +118,11 @@ export function describeBashExternalDirectoryGate(
     input: {},
     payload,
     sessionApproval: SessionApproval.forGrants(
-      uncoveredEntries.map((entry) => ({
-        surface: entry.surface,
-        pattern: normalizer.approvalPatternFor(entry.path),
-      })),
+      uncoveredEntries.flatMap((entry) =>
+        normalizer
+          .approvalPatternsFor(entry.path)
+          .map((pattern) => ({ surface: entry.surface, pattern })),
+      ),
     ),
     promptDetails: {
       source: "tool_call",

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

@@ -130,10 +130,10 @@ export function describeBashPathGate(
   // All tokens evaluate to allow — no restriction.
   if (!worstCheck || !worstToken || !worstEntry) return null;
 
-  // Derive the pattern from the lexical absolute form (the cd-aware resolved
-  // path), so it matches the values a later call produces. For an unknown base
+  // Derive the patterns from the lexical absolute form (the cd-aware resolved
+  // path), so they match the values a later call produces. For an unknown base
   // (`forLiteral`) `value()` is the raw token.
-  const pattern = normalizer.approvalPatternFor(worstEntry.path);
+  const patterns = normalizer.approvalPatternsFor(worstEntry.path);
   const surface = worstEntry.surface;
   const payload = buildPathAskPayload({
     toolName: tcc.toolName,
@@ -147,7 +147,7 @@ export function describeBashPathGate(
     surface,
     input: { path: worstToken },
     payload,
-    sessionApproval: SessionApproval.single(surface, pattern),
+    sessionApproval: SessionApproval.forPatterns(surface, patterns),
     promptDetails: {
       source: "tool_call",
       agentName: tcc.agentName,

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

@@ -16,9 +16,18 @@ export interface UncoveredExternalPath {
   check: PermissionCheckResult;
 }
 
-/** The uncovered external paths plus the most restrictive check among them. */
-export interface UncoveredExternalPaths {
+/**
+ * How a set of external paths resolved: the uncovered ones, the worst among
+ * them, and which allowed paths a session grant covered.
+ */
+export interface ExternalPathCoverage {
   uncovered: UncoveredExternalPath[];
+  /**
+   * Allowed paths whose winning rule was a session grant. A path allowed by a
+   * config rule or the universal fallback is in neither list, so a caller can
+   * stamp `session_approval` only where a grant actually decided.
+   */
+  sessionCovered: AccessPath[];
   /** Worst check among uncovered paths; `undefined` only when none are uncovered. */
   worstCheck: PermissionCheckResult | undefined;
 }
@@ -60,14 +69,16 @@ export function resolveExternalDirectoryPolicy(
  * 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".
+ * downgraded to the catch-all "ask". Allowed entries a session rule decided
+ * are reported apart, as the provenance a whole-command bypass records.
  */
 export function selectUncoveredExternalPaths(
   accesses: readonly BashExternalPath[],
   resolver: ScopedPermissionResolver,
   agentName: string | undefined,
-): UncoveredExternalPaths {
+): ExternalPathCoverage {
   const uncovered: UncoveredExternalPath[] = [];
+  const sessionCovered: AccessPath[] = [];
   for (const { path, effect } of accesses) {
     const surface = capabilitySurfaceForEffect(
       "external_directory",
@@ -81,10 +92,13 @@ export function selectUncoveredExternalPaths(
     );
     if (check.state !== "allow") {
       uncovered.push({ path, surface, effect, check });
+    } else if (check.source === "session") {
+      sessionCovered.push(path);
     }
   }
   return {
     uncovered,
+    sessionCovered,
     worstCheck: pickMostRestrictive(uncovered.map(({ check }) => check)),
   };
 }

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

@@ -97,7 +97,7 @@ export function describeExternalDirectoryGate(
 
   // ── Build descriptor for permission check ───────────────────────────────
   const resolvedAlias = accessPath.resolvedAlias();
-  const pattern = normalizer.approvalPatternFor(accessPath);
+  const patterns = normalizer.approvalPatternsFor(accessPath);
 
   const payload = buildExternalDirectoryAskPayload({
     toolName: tcc.toolName,
@@ -114,7 +114,7 @@ export function describeExternalDirectoryGate(
     input: {},
     preCheck,
     payload,
-    sessionApproval: SessionApproval.single(surface, pattern),
+    sessionApproval: SessionApproval.forPatterns(surface, patterns),
     promptDetails: buildPathGatePromptDetails(
       tcc,
       externalDirectoryPath,

package/src/handlers/gates/path.ts

@@ -58,9 +58,9 @@ export function describePathGate(
   // "path" key should not trigger path-level prompts (#58).
   if (check.matchedPattern === undefined) return null;
 
-  // Derive the approval pattern from the lexical absolute form so it matches
+  // Derive the approval patterns from the lexical absolute form so they match
   // the policy values a later call produces.
-  const pattern = normalizer.approvalPatternFor(accessPath);
+  const patterns = normalizer.approvalPatternsFor(accessPath);
 
   const payload = buildPathAskPayload({
     toolName: tcc.toolName,
@@ -75,7 +75,7 @@ export function describePathGate(
     surface,
     input: { path: filePath },
     payload,
-    sessionApproval: SessionApproval.single(surface, pattern),
+    sessionApproval: SessionApproval.forPatterns(surface, patterns),
     promptDetails: buildPathGatePromptDetails(
       tcc,
       filePath,

package/src/handlers/gates/tool-call-gate-pipeline.ts

@@ -210,7 +210,7 @@ export class ToolCallGatePipeline {
       return {
         pathAccess: {
           path: accessPath,
-          approvalPattern: normalizer.approvalPatternFor(accessPath),
+          approvalPatterns: normalizer.approvalPatternsFor(accessPath),
         },
         toolCheck: this.resolver.resolve({
           kind: "access-path",

package/src/handlers/gates/tool.ts

@@ -34,7 +34,7 @@ import type { ToolCallContext } from "./types";
  */
 export interface ToolPathAccess {
   readonly path: AccessPath;
-  readonly approvalPattern: string;
+  readonly approvalPatterns: readonly string[];
 }
 
 /**
@@ -42,7 +42,7 @@ export interface ToolPathAccess {
  *
  * Bash → command string; MCP → qualified target; everything else → catch-all
  * wildcard. A path-bearing tool that resolved a path never reaches here — its
- * suggestion comes from the already-derived {@link ToolPathAccess} pattern.
+ * suggestion comes from the already-derived {@link ToolPathAccess} patterns.
  */
 function deriveSuggestionValue(
   toolName: string,
@@ -76,6 +76,40 @@ function gateSurfaceOf(
   return toolName;
 }
 
+/** A session option: the approval to record and the label offering it. */
+interface SessionOption {
+  readonly approval: SessionApproval;
+  readonly label: string;
+}
+
+/** The session option for a path-bearing tool, from its derived patterns. */
+function pathSessionOption(
+  gateSurface: string,
+  approvalPatterns: readonly string[],
+): SessionOption {
+  const suggestion = suggestPathSessionPattern(gateSurface, approvalPatterns);
+  return {
+    approval: SessionApproval.forPatterns(
+      suggestion.surface,
+      suggestion.patterns,
+    ),
+    label: suggestion.label,
+  };
+}
+
+/** The session option for a gate whose value is not a path. */
+function valueSessionOption(
+  toolName: string,
+  gateSurface: string,
+  check: PermissionCheckResult,
+): SessionOption {
+  const suggestion = suggestValueSessionPattern(toolName, gateSurface, check);
+  return {
+    approval: SessionApproval.single(suggestion.surface, suggestion.pattern),
+    label: suggestion.label,
+  };
+}
+
 /**
  * The session approval for a gate whose value is not a path.
  *
@@ -118,10 +152,10 @@ export function describeToolGate(
     PATH_BEARING_TOOLS,
   );
 
-  // Compute session approval suggestion for the "for this session" option.
-  const suggestion = pathAccess
-    ? suggestPathSessionPattern(gateSurface, pathAccess.approvalPattern)
-    : suggestValueSessionPattern(tcc.toolName, gateSurface, check);
+  // The session approval and label for the "for this session" option.
+  const sessionOption = pathAccess
+    ? pathSessionOption(gateSurface, pathAccess.approvalPatterns)
+    : valueSessionOption(tcc.toolName, gateSurface, check);
 
   const payload = buildToolAskPayload({
     check,
@@ -148,16 +182,13 @@ export function describeToolGate(
     surface: gateSurface,
     input: tcc.input,
     payload,
-    sessionApproval: SessionApproval.single(
-      suggestion.surface,
-      suggestion.pattern,
-    ),
+    sessionApproval: sessionOption.approval,
     promptDetails: {
       source: "tool_call",
       agentName: tcc.agentName,
       toolCallId: tcc.toolCallId,
       toolName: tcc.toolName,
-      sessionLabel: suggestion.label,
+      sessionLabel: sessionOption.label,
       accessIntent,
       ...permissionLogContext,
     },

package/src/path/approval-pattern.ts

@@ -1,13 +1,19 @@
 import type { PathFlavor } from "./path-flavor";
 
 /**
- * Derive the wildcard glob to record when a user approves an accessed path for
- * the session: the path's directory scope, with `*` appended.
+ * Derive the wildcard globs to record when a user approves an accessed path
+ * for the session.
  *
- * The scope is the value up to and including its last path separator, so the
- * pattern is spelled with the separator the value itself carries. That matters
- * on a win32 host, where Git Bash tokens are POSIX-shaped while Node's own
- * `sep` is a backslash: deriving `/tmp/logs\*` from `/tmp/logs/` widens the
+ * A non-directory (or a path the caller could not confirm is a directory) is
+ * scoped to its enclosing directory: the value up to and including its last
+ * path separator, with `*` appended. A directory is scoped to itself and its
+ * contents — `D` and `D<sep>*` — rather than to its parent, which would grant
+ * every sibling directory (#989). Two patterns are needed because `D<sep>*`
+ * does not match `D` itself, and `D*` would also match a sibling `D-evil`.
+ *
+ * Each pattern is spelled with the separator the value itself carries. That
+ * matters on a win32 host, where Git Bash tokens are POSIX-shaped while Node's
+ * own `sep` is a backslash: deriving `/tmp/logs\*` from `/tmp/logs/` widens the
  * grant to the parent directory once the `windowsSeparators` fold (#653)
  * normalizes both operands. A value carrying no separator falls back to the
  * current directory, which is what callers see only if they skipped resolving
@@ -17,11 +23,30 @@ import type { PathFlavor } from "./path-flavor";
  * never an ambient `node:path` read, so win32 derivation is decidable — and
  * testable — on a POSIX host (#655).
  */
-export function deriveApprovalPattern(
+export function deriveApprovalPatterns(
   pathValue: string,
   flavor: PathFlavor,
-): string {
+  isDirectory: boolean,
+): readonly string[] {
+  if (!isDirectory) return [parentScopePattern(pathValue, flavor)];
+  return [pathValue, directoryContentsPattern(pathValue, flavor)];
+}
+
+/** The value's enclosing directory scope (up to its last separator) plus `*`. */
+function parentScopePattern(pathValue: string, flavor: PathFlavor): string {
   const lastSeparator = flavor.lastSeparatorIndex(pathValue);
   if (lastSeparator < 0) return `.${flavor.impl.sep}*`;
   return `${pathValue.slice(0, lastSeparator + 1)}*`;
 }
+
+/** Everything beneath a directory value: the value, a separator, then `*`. */
+function directoryContentsPattern(
+  pathValue: string,
+  flavor: PathFlavor,
+): string {
+  const lastSeparator = flavor.lastSeparatorIndex(pathValue);
+  if (lastSeparator === pathValue.length - 1) return `${pathValue}*`;
+  const separator =
+    lastSeparator < 0 ? flavor.impl.sep : pathValue[lastSeparator];
+  return `${pathValue}${separator}*`;
+}

package/src/path/path-normalizer.ts

@@ -1,4 +1,4 @@
-import { existsSync, lstatSync } from "node:fs";
+import { existsSync, lstatSync, statSync } from "node:fs";
 import { AccessPath } from "#src/access-intent/access-path";
 import {
   canonicalNormalizePathForComparison,
@@ -6,7 +6,7 @@ import {
   normalizePathPolicyLiteral,
 } from "#src/access-intent/path-normalization";
 import { classifyToolKind } from "#src/access-intent/tool-kind";
-import { deriveApprovalPattern } from "./approval-pattern";
+import { deriveApprovalPatterns } from "./approval-pattern";
 import { resolveNativeToolTarget } from "./native-tool-target";
 import { isPathOutsideWorkingDirectory } from "./path-containment";
 import type { PathFlavor } from "./path-flavor";
@@ -131,17 +131,41 @@ export class PathNormalizer {
   }
 
   /**
-   * The session-approval glob for an accessed path: its directory scope plus
-   * `*`, derived through the baked flavor.
+   * The session-approval globs for an accessed path, derived through the baked
+   * flavor: an existing directory's own scope (itself and its contents), else
+   * the enclosing directory's scope plus `*`.
    *
    * Takes the already-built {@link AccessPath} — the lexical form is what a
-   * later tool call is matched on, so the pattern must be derived from the
+   * later tool call is matched on, so the patterns must be derived from the
    * same representation the decision displayed (#438). Deriving it here rather
    * than at each gate keeps the platform's separator alphabet with the object
    * that owns the flavor, instead of an ambient `node:path` read (#655).
    */
-  approvalPatternFor(accessPath: AccessPath): string {
-    return deriveApprovalPattern(accessPath.value(), this.flavor);
+  approvalPatternsFor(accessPath: AccessPath): readonly string[] {
+    return deriveApprovalPatterns(
+      accessPath.value(),
+      this.flavor,
+      this.namesDirectory(accessPath),
+    );
+  }
+
+  /**
+   * Whether an accessed path names an existing directory, so its session grant
+   * covers that directory rather than its parent.
+   *
+   * Uses `stat`, following symlinks: a link to a directory is what `ls` lists.
+   * A literal-only path (no canonical form — an unknown base, or a win32
+   * non-mount POSIX absolute) is never probed, since `stat` would resolve it
+   * against the process cwd or a fabricated drive. Any error answers `false`,
+   * which keeps the parent-directory grant callers had before this probe.
+   */
+  private namesDirectory(accessPath: AccessPath): boolean {
+    if (!accessPath.boundaryValue()) return false;
+    try {
+      return statSync(accessPath.value()).isDirectory();
+    } catch {
+      return false;
+    }
   }
 
   /** Platform-aware absoluteness (`win32` vs `posix` rules). */

package/src/presentation/pattern-suggest.ts

@@ -5,9 +5,10 @@ import {
 import {
   type CapabilityDirection,
   PATH_BEARING_TOOLS,
+  surfaceFamilyMembers,
   surfaceFamilyOf,
 } from "#src/access-intent/path-surfaces";
-import type { ApprovalGrant } from "#src/session/approval-grant";
+import { type ApprovalGrant, grantTargets } from "#src/session/approval-grant";
 
 /** The suggestion returned for a "Yes, for this session" dialog option. */
 export interface SessionApprovalSuggestion {
@@ -80,15 +81,16 @@ export interface ForwardedScopeLabels {
 /**
  * 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
+ * A single target 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. Targets, not grants: a directory's
+ * two-grant approval and two paths sharing one glob each count once
+ * ({@link grantTargets}). 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`;
+  const targets = grantTargets(grants);
+  return targets.length === 1 ? `"${targets[0]}"` : `${targets.length} paths`;
 }
 
 /** The two session-option labels for an ask whose grants prove one direction. */
@@ -120,6 +122,25 @@ export function buildDirectionalSessionLabels(
   };
 }
 
+/**
+ * Label a session grant on the `path` / `external_directory` families that
+ * proves no direction (an extension tool, `edit`), so the option still names
+ * its scope instead of the dialog's bare default. Returns `null` when any
+ * grant lies outside those families — their gates supply their own label.
+ */
+export function buildPathAccessSessionLabel(
+  grants: readonly ApprovalGrant[],
+): string | null {
+  const allPathFamily =
+    grants.length > 0 &&
+    grants.every(
+      (grant) => surfaceFamilyMembers(surfaceFamilyOf(grant.surface)) !== null,
+    );
+  return allPathFamily
+    ? `Yes, allow access to ${describeGrantTarget(grants)} for this session`
+    : null;
+}
+
 /**
  * Build the two scope labels shown when a human grants a forwarded request
  * "for this session."
@@ -221,19 +242,37 @@ export function suggestSessionPattern(
   return { surface, pattern, label: buildLabel(pattern, surface) };
 }
 
+/** The suggestion for a path surface: every pattern to record, one label. */
+export interface PathSessionSuggestion {
+  /** The permission surface this approval applies to. */
+  surface: string;
+  /** The wildcard patterns to store as session rules. */
+  patterns: readonly string[];
+  /** Human-readable label for the "for session" dialog option. */
+  label: string;
+}
+
 /**
- * Build the suggestion for a path surface from a pattern the caller already
+ * Build the suggestion for a path surface from patterns the caller already
  * derived through its `PathNormalizer` (#655).
  *
  * The derivation belongs to the normalizer, which owns the session's
  * `PathFlavor`; this module labels the result and must not re-interpret the
- * separators it is handed.
+ * separators it is handed. The label names the approval's target
+ * ({@link grantTargets}), so a directory's pair reads as its contents glob.
  */
 export function suggestPathSessionPattern(
   surface: string,
-  approvalPattern: string,
-): SessionApprovalSuggestion {
-  return suggestExactSessionPattern(surface, approvalPattern);
+  approvalPatterns: readonly string[],
+): PathSessionSuggestion {
+  const targets = grantTargets(
+    approvalPatterns.map((pattern) => ({ surface, pattern })),
+  );
+  return {
+    surface,
+    patterns: approvalPatterns,
+    label: buildLabel(targets.join('", "'), surface),
+  };
 }
 
 /**

package/src/session/approval-grant.ts

@@ -75,3 +75,36 @@ export function provenDirectionOf(
     ? direction
     : null;
 }
+
+/**
+ * The distinct targets an approval covers, for naming it in a prompt.
+ *
+ * A directory approval is recorded as two grants on one surface — the
+ * directory itself (`D`) and its contents (`D/*`) — because no single wildcard
+ * matches both without also matching a sibling like `D-evil`. Here the exact
+ * grant folds into its contents grant, so the pair reads as the one target
+ * `D/*`. Identical patterns (two paths in one directory) collapse to one.
+ */
+export function grantTargets(grants: readonly ApprovalGrant[]): string[] {
+  const targets = grants
+    .filter((grant) => !hasContentsSibling(grant, grants))
+    .map((grant) => grant.pattern);
+  return [...new Set(targets)];
+}
+
+/** Whether `grants` also holds `grant`'s contents pattern on the same surface. */
+function hasContentsSibling(
+  grant: ApprovalGrant,
+  grants: readonly ApprovalGrant[],
+): boolean {
+  return grants.some(
+    (other) =>
+      other.surface === grant.surface &&
+      CONTENTS_SUFFIXES.some(
+        (suffix) => other.pattern === `${grant.pattern}${suffix}`,
+      ),
+  );
+}
+
+/** A separator (either alphabet) followed by the wildcard. */
+const CONTENTS_SUFFIXES = ["/*", "\\*"] as const;

package/src/session/session-approval.ts

@@ -23,6 +23,19 @@ export class SessionApproval {
     return new SessionApproval([{ surface, pattern }]);
   }
 
+  /**
+   * Create an approval whose patterns were all proven on one surface — a
+   * directory approval records the directory and its contents as two patterns.
+   */
+  static forPatterns(
+    surface: string,
+    patterns: readonly string[],
+  ): SessionApproval {
+    return new SessionApproval(
+      patterns.map((pattern) => ({ surface, pattern })),
+    );
+  }
+
   /**
    * Create an approval from grants that may name different surfaces (e.g. a
    * bash external-directory ask whose uncovered paths proved different