@gotgenes/pi-permission-system 39.0.0 → 39.0.1

package/CHANGELOG.md

@@ -5,6 +5,19 @@ 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.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/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.1",
   "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

@@ -109,10 +109,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.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