@komarspn/pi-permission-system 16.0.2

package/src/rule.ts

@@ -0,0 +1,188 @@
+import { PATH_SURFACES } from "./path-utils";
+import type { PermissionState } from "./types";
+import { wildcardMatch } from "./wildcard-matcher";
+
+/**
+ * Provenance of a rule — which source contributed it.
+ *
+ * Config scopes: "global", "project", "agent", "project-agent".
+ * Synthesized:   "builtin" (universal default / evaluate() fallback),
+ *                "baseline" (conditional MCP metadata auto-allow).
+ * Runtime:       "session" (session approvals).
+ */
+export type RuleOrigin =
+  | "global"
+  | "project"
+  | "agent"
+  | "project-agent"
+  | "builtin"
+  | "baseline"
+  | "session";
+
+/** A single permission rule — the atomic unit of policy. */
+export interface Rule {
+  /** The permission surface: "bash", "read", "mcp", "skill", "external_directory", etc. */
+  surface: string;
+  /** The match pattern: a command glob, tool name, skill name, or "*". */
+  pattern: string;
+  /** The permission decision. */
+  action: PermissionState;
+  /** Custom denial reason for deny rules (optional). */
+  reason?: string;
+  /**
+   * Origin layer — used to derive PermissionCheckResult.source after evaluation.
+   * Not used by evaluate(); purely informational metadata.
+   */
+  layer?: "default" | "baseline" | "config" | "session";
+  /** Which source contributed this rule. */
+  origin: RuleOrigin;
+}
+
+/** An ordered list of rules. Later rules take priority (last-match-wins). */
+export type Ruleset = Rule[];
+
+/**
+ * Pure permission evaluation.
+ *
+ * Returns the last rule in `rules` whose surface and pattern both
+ * wildcard-match the supplied values (last-match-wins).
+ *
+ * When no rule matches, returns a synthetic rule with `defaultAction`
+ * (defaults to "ask" — least privilege).
+ */
+export function evaluate(
+  surface: string,
+  pattern: string,
+  rules: Ruleset,
+  defaultAction?: PermissionState,
+  platform: NodeJS.Platform = process.platform,
+): Rule {
+  const rule = rules.findLast((r) =>
+    ruleMatches(r, surface, pattern, platform),
+  );
+  if (rule !== undefined) return rule;
+  return {
+    surface,
+    pattern,
+    action: defaultAction ?? "ask",
+    origin: "builtin",
+  };
+}
+
+/**
+ * On Windows, path-surface values are canonicalized + lowercased; fold the
+ * pattern→value match (case and separators) so mixed-case / forward-slash
+ * overrides still match. The surface→surface match stays exact.
+ */
+function pathMatchOptions(
+  surface: string,
+  platform: NodeJS.Platform,
+): { caseInsensitive: true; windowsSeparators: true } | undefined {
+  return platform === "win32" && PATH_SURFACES.has(surface)
+    ? { caseInsensitive: true, windowsSeparators: true }
+    : undefined;
+}
+
+function ruleMatches(
+  rule: Rule,
+  surface: string,
+  value: string,
+  platform: NodeJS.Platform,
+): boolean {
+  const matchOptions = pathMatchOptions(surface, platform);
+  return (
+    wildcardMatch(rule.surface, surface) &&
+    wildcardMatch(rule.pattern, value, matchOptions)
+  );
+}
+
+/**
+ * Evaluate a surface against an ordered list of candidate values, stopping at
+ * the first candidate that matches a non-default rule (last-match-wins within
+ * each candidate, first-non-default-wins across candidates).
+ *
+ * Used by MCP (multi-candidate target list) and, uniformly, by all other
+ * surfaces (single-element candidate list).
+ *
+ * Returns the matched rule and the candidate value that produced it.
+ * When every candidate matches only the synthesized default, falls back to
+ * evaluating the first candidate so the caller always receives a concrete
+ * result.
+ */
+/**
+ * Evaluate a surface against multiple values, returning the most restrictive
+ * non-allow result (deny > ask > allow).
+ *
+ * Used by the cross-cutting `path` surface to aggregate permission decisions
+ * across multiple file paths extracted from a single tool call or bash command.
+ *
+ * Returns `null` when all values evaluate to `allow` (no restriction).
+ * Returns the first `deny` immediately (short-circuit).
+ * Returns the first `ask` if no `deny` is found.
+ */
+export function evaluateMostRestrictive(
+  surface: string,
+  values: string[],
+  rules: Ruleset,
+): { rule: Rule; value: string } | null {
+  let worst: { rule: Rule; value: string } | null = null;
+  for (const value of values) {
+    const rule = evaluate(surface, value, rules);
+    if (rule.action === "deny") return { rule, value };
+    if (rule.action === "ask" && worst?.rule.action !== "ask") {
+      worst = { rule, value };
+    }
+  }
+  return worst;
+}
+
+export function evaluateFirst(
+  surface: string,
+  values: string[],
+  rules: Ruleset,
+): { rule: Rule; value: string } {
+  for (const value of values) {
+    const rule = evaluate(surface, value, rules);
+    if (rule.layer !== "default") {
+      return { rule, value };
+    }
+  }
+  // All candidates matched only the synthesized default — use the first.
+  const fallbackValue = values[0] ?? "*";
+  return {
+    rule: evaluate(surface, fallbackValue, rules),
+    value: fallbackValue,
+  };
+}
+
+/**
+ * Evaluate equivalent lookup values as aliases of the same path.
+ *
+ * Unlike `evaluateFirst()`, this preserves rule ordering across aliases: the
+ * last rule that matches any alias wins. This lets absolute allowlists and
+ * legacy relative rules coexist without a catch-all match on the first alias
+ * masking a later, more specific rule on another alias.
+ */
+export function evaluateAnyValue(
+  surface: string,
+  values: string[],
+  rules: Ruleset,
+  platform: NodeJS.Platform = process.platform,
+): { rule: Rule; value: string } {
+  const fallbackValue = values[0] ?? "*";
+  const rule = rules.findLast((r) =>
+    values.some((value) => ruleMatches(r, surface, value, platform)),
+  );
+  if (rule !== undefined) {
+    return {
+      rule,
+      value:
+        values.find((value) => ruleMatches(rule, surface, value, platform)) ??
+        fallbackValue,
+    };
+  }
+  return {
+    rule: evaluate(surface, fallbackValue, rules),
+    value: fallbackValue,
+  };
+}

package/src/scope-merge.ts

@@ -0,0 +1,72 @@
+import { mergeFlatPermissions } from "#src/permission-merge";
+import type { RuleOrigin } from "#src/rule";
+import type { FlatPermissionConfig, ScopeConfig } from "#src/types";
+
+/** Surface → (pattern → originating scope). */
+type OriginMap = Map<string, Map<string, RuleOrigin>>;
+
+/** Result of merging permission objects across scopes with provenance tracking. */
+export interface MergedScopes {
+  /** Fully merged flat permission config (lowest → highest precedence). */
+  mergedPermission: FlatPermissionConfig;
+  /** Maps each surface to a per-pattern origin (which scope contributed it). */
+  origins: OriginMap;
+}
+
+/**
+ * Merge permission objects across scopes (lowest → highest precedence) while
+ * tracking which scope contributed each (surface, pattern) entry.
+ *
+ * Mirrors mergeFlatPermissions() semantics for origin attribution:
+ * - Both base and incoming are objects → shallow-merge: each incoming pattern
+ *   is attributed to this scope; patterns the higher scope does not redefine
+ *   keep their earlier origin.
+ * - Otherwise → full replacement: this scope takes over the entire surface
+ *   entry, discarding all lower-scope attribution.
+ */
+export function mergeScopesWithOrigins(
+  scopes: readonly (readonly [RuleOrigin, ScopeConfig])[],
+): MergedScopes {
+  const origins: OriginMap = new Map();
+  let mergedPermission: FlatPermissionConfig = {};
+
+  for (const [scopeName, scope] of scopes) {
+    if (!scope.permission) continue;
+
+    for (const [surface, value] of Object.entries(scope.permission)) {
+      const baseVal = mergedPermission[surface];
+      /* eslint-disable @typescript-eslint/no-unnecessary-condition -- defensive null/type checks; config values may differ at runtime */
+      const bothObjects =
+        typeof baseVal === "object" &&
+        baseVal !== null &&
+        typeof value === "object" &&
+        value !== null;
+      /* eslint-enable @typescript-eslint/no-unnecessary-condition */
+
+      if (bothObjects) {
+        // Shallow-merge: each incoming pattern is attributed to this scope;
+        // existing patterns from lower scopes keep their earlier origin.
+        if (!origins.has(surface)) origins.set(surface, new Map());
+        for (const pattern of Object.keys(value)) {
+          origins.get(surface)?.set(pattern, scopeName);
+        }
+      } else {
+        // Full replacement: this scope takes over the entire surface entry.
+        const surfaceOrigins = new Map<string, RuleOrigin>();
+        if (typeof value === "string") {
+          surfaceOrigins.set("*", scopeName);
+          // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- defensive null check
+        } else if (typeof value === "object" && value !== null) {
+          for (const pattern of Object.keys(value)) {
+            surfaceOrigins.set(pattern, scopeName);
+          }
+        }
+        origins.set(surface, surfaceOrigins);
+      }
+    }
+
+    mergedPermission = mergeFlatPermissions(mergedPermission, scope.permission);
+  }
+
+  return { mergedPermission, origins };
+}

package/src/service-lifecycle.ts

@@ -0,0 +1,49 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { emitReadyEvent, type PermissionEventBus } from "./permission-events";
+import {
+  type PermissionsService,
+  publishPermissionsService,
+  unpublishPermissionsService,
+} from "./service";
+import { isRegisteredSubagentChild } from "./subagent-context";
+import type { SubagentSessionRegistry } from "./subagent-registry";
+
+/** The session-scoped service lifecycle that the lifecycle handler drives. */
+export interface ServiceLifecycle {
+  activate(ctx: ExtensionContext): void;
+  teardown(): void;
+}
+
+/**
+ * Owns the process-global service publication lifecycle for one extension
+ * instance.
+ *
+ * - `activate` publishes the service (skipped for registered subagent children
+ *   so they never clobber the parent's slot — see #302), then emits the ready
+ *   event.
+ * - `teardown` runs all session-scoped subscription cleanups in order, then
+ *   unpublishes the service.
+ */
+export class PermissionServiceLifecycle implements ServiceLifecycle {
+  constructor(
+    private readonly service: PermissionsService,
+    private readonly registry: SubagentSessionRegistry,
+    private readonly events: PermissionEventBus,
+    private readonly subscriptions: readonly (() => void)[],
+  ) {}
+
+  activate(ctx: ExtensionContext): void {
+    if (!isRegisteredSubagentChild(ctx, this.registry)) {
+      publishPermissionsService(this.service);
+    }
+    emitReadyEvent(this.events);
+  }
+
+  teardown(): void {
+    for (const unsubscribe of this.subscriptions) {
+      unsubscribe();
+    }
+    unpublishPermissionsService(this.service);
+  }
+}

package/src/service.ts

@@ -0,0 +1,163 @@
+/**
+ * Cross-extension service accessor backed by `Symbol.for()` on `globalThis`.
+ *
+ * `Symbol.for()` is process-global by spec, so it survives jiti's per-extension
+ * module isolation (`moduleCache: false`). A consumer doing
+ * `import("@gotgenes/pi-permission-system")` gets a fresh module copy, but
+ * `getPermissionsService()` reads from the same `globalThis` slot the provider
+ * wrote to — enabling direct, synchronous, type-safe function calls.
+ *
+ * Best practice: call `getPermissionsService()` per use rather than caching the
+ * reference — this ensures resilience across `/reload` and load-order edge cases.
+ */
+
+import type { ToolAccessExtractor } from "./tool-access-extractor-registry";
+import type { ToolInputFormatter } from "./tool-input-formatter-registry";
+import type { PermissionCheckResult, PermissionState } from "./types";
+
+export type {
+  ForwardedPromptContext,
+  PermissionDecisionEvent,
+  PermissionsPromptReplyData,
+  PermissionsPromptRequest,
+  PermissionsReadyEvent,
+  PermissionsRpcReply,
+  PermissionUiPromptEvent,
+  PermissionUiPromptSource,
+} from "./permission-events";
+export {
+  PERMISSIONS_DECISION_CHANNEL,
+  PERMISSIONS_PROTOCOL_VERSION,
+  PERMISSIONS_READY_CHANNEL,
+  PERMISSIONS_RPC_PROMPT_CHANNEL,
+  PERMISSIONS_UI_PROMPT_CHANNEL,
+} from "./permission-events";
+export type { PermissionCheckResult, PermissionState, ToolInputFormatter };
+
+/** Process-global key for the service slot. */
+const SERVICE_KEY = Symbol.for("@gotgenes/pi-permission-system:service");
+
+/**
+ * Public interface exposed to other extensions via `getPermissionsService()`.
+ *
+ * Mirrors the simplified RPC signature — surface + optional value + optional
+ * agent name — and delegates to `PermissionManager.checkPermission()` with
+ * current session rules internally.
+ */
+export interface PermissionsService {
+  /**
+   * Query the permission policy for a surface and value.
+   *
+   * @param surface   - Permission surface: "bash", "read", "mcp", "skill",
+   *                    "external_directory", etc.
+   * @param value     - The value to evaluate: command string, tool name, skill
+   *                    name, or path. Omit or pass `undefined` for a
+   *                    surface-level query.
+   * @param agentName - Optional agent name for per-agent policy resolution.
+   * @returns Full check result including state, matched pattern, and origin.
+   */
+  checkPermission(
+    surface: string,
+    value?: string,
+    agentName?: string,
+  ): PermissionCheckResult;
+
+  /**
+   * Register a custom preview formatter for a specific tool name.
+   *
+   * The formatter is consulted first inside `ToolPreviewFormatter.formatToolInputForPrompt`;
+   * returning `undefined` falls through to the built-in switch (and ultimately
+   * the JSON default).
+   *
+   * Only one formatter may be registered per tool name — a second call for the
+   * same name throws.  The returned disposer unregisters the formatter.
+   *
+   * @param toolName  - Exact tool name to register for (e.g. `"mcp"`, `"my-server:run"`).
+   * @param formatter - Receives the raw `input` record; return a string to use
+   *                    as the prompt preview, or `undefined` to decline.
+   */
+  registerToolInputFormatter(
+    toolName: string,
+    formatter: ToolInputFormatter,
+  ): () => void;
+
+  /**
+   * Register a custom access-intent extractor for a specific tool name.
+   *
+   * The extractor declares the filesystem path a tool will access so the
+   * cross-cutting `path` and `external_directory` gates can see it. Use it for
+   * tools whose path lives under a non-standard key — built-in file tools and
+   * any tool exposing `input.path` (plus MCP via `input.arguments.path`) are
+   * already covered by convention without registration.
+   *
+   * The extractor receives the raw `input` record and returns the path string,
+   * or `undefined` to decline. Only one extractor may be registered per tool
+   * name — a second call for the same name throws. The returned disposer
+   * unregisters the extractor.
+   *
+   * @param toolName  - Exact tool name to register for (e.g. `"ffgrep"`).
+   * @param extractor - Receives the raw `input` record; return the path string,
+   *                    or `undefined` to decline.
+   */
+  registerToolAccessExtractor(
+    toolName: string,
+    extractor: ToolAccessExtractor,
+  ): () => void;
+
+  /**
+   * Query the tool-level permission state for pre-filtering tools before
+   * creating a child session.
+   *
+   * Returns `"deny"` | `"allow"` | `"ask"` based on the composed policy.
+   * Does not consider command-level rules (e.g. per-bash-command patterns) —
+   * use `checkPermission` for runtime invocation gates.
+   *
+   * @param toolName  - Tool name (e.g. `"bash"`, `"read"`, `"my-extension:tool"`).
+   * @param agentName - Optional agent name for per-agent policy resolution.
+   */
+  getToolPermission(toolName: string, agentName?: string): PermissionState;
+}
+
+/**
+ * Store a `PermissionsService` on `globalThis` so other extensions can
+ * retrieve it via `getPermissionsService()`.
+ *
+ * Called at `session_start` by the top-level (parent) instance only — an
+ * in-process subagent child skips publishing so it cannot clobber the parent's
+ * service. Overwrites any previously published service, which keeps `/reload`
+ * working: a reloaded parent re-publishes its fresh service.
+ */
+export function publishPermissionsService(service: PermissionsService): void {
+  (globalThis as Record<symbol, unknown>)[SERVICE_KEY] = service;
+}
+
+/**
+ * Retrieve the published `PermissionsService`, or `undefined` if the
+ * permission-system extension has not loaded (or has been unloaded).
+ */
+export function getPermissionsService(): PermissionsService | undefined {
+  return (globalThis as Record<symbol, unknown>)[SERVICE_KEY] as
+    | PermissionsService
+    | undefined;
+}
+
+/**
+ * Remove `service` from `globalThis`, but only when the current slot still
+ * holds it (identity compare-and-delete).
+ *
+ * Called during `session_shutdown` to avoid stale references after the
+ * extension is torn down. Scoping the delete to the publishing instance keeps
+ * two cases correct:
+ *
+ * - An in-process subagent child never published the parent's service, so its
+ *   shutdown is a no-op and the parent's slot survives.
+ * - A superseded `/reload` generation no longer owns the slot, so its late
+ *   shutdown cannot wipe the new generation's freshly published service.
+ */
+export function unpublishPermissionsService(service: PermissionsService): void {
+  if (getPermissionsService() !== service) {
+    return;
+  }
+  // eslint-disable-next-line @typescript-eslint/no-dynamic-delete -- Symbol-keyed global property; Map.delete() is not applicable
+  delete (globalThis as Record<symbol, unknown>)[SERVICE_KEY];
+}

package/src/session-approval-recorder.ts

@@ -0,0 +1,6 @@
+import type { SessionApproval } from "./session-approval";
+
+/** Records a granted session-scoped approval into the session ruleset. */
+export interface SessionApprovalRecorder {
+  recordSessionApproval(approval: SessionApproval): void;
+}

package/src/session-approval.ts

@@ -0,0 +1,43 @@
+/**
+ * Value object for a session-scoped approval: one surface, one-or-more patterns.
+ *
+ * Owned by gate descriptors and passed to the session store — the runner never
+ * needs to know whether there is one pattern or many.
+ */
+export class SessionApproval {
+  private constructor(
+    readonly surface: string,
+    readonly patterns: readonly string[],
+  ) {}
+
+  /** Create an approval for a single pattern (the common case). */
+  static single(surface: string, pattern: string): SessionApproval {
+    return new SessionApproval(surface, [pattern]);
+  }
+
+  /**
+   * Create an approval for multiple patterns (e.g. bash external-directory
+   * gates that cover several uncovered paths in one prompt).
+   */
+  static multiple(
+    surface: string,
+    patterns: readonly string[],
+  ): SessionApproval {
+    return new SessionApproval(surface, [...patterns]);
+  }
+
+  /** Representative pattern for the interactive prompt — the first, if any. */
+  get representativePattern(): string | undefined {
+    return this.patterns[0];
+  }
+
+  /**
+   * Single-pattern shape `applyPermissionGate` echoes back to the caller.
+   * Returns `undefined` when patterns is empty (degenerate case).
+   */
+  toGateApproval(): { surface: string; pattern: string } | undefined {
+    const pattern = this.representativePattern;
+    if (pattern === undefined) return undefined;
+    return { surface: this.surface, pattern };
+  }
+}

package/src/session-logger.ts

@@ -0,0 +1,91 @@
+import { join } from "node:path";
+import { DEBUG_LOG_FILENAME, REVIEW_LOG_FILENAME } from "./config-paths";
+import {
+  ensurePermissionSystemLogsDirectory,
+  type PermissionSystemExtensionConfig,
+} from "./extension-config";
+import {
+  createPermissionSystemLogger,
+  type PermissionSystemLogger,
+} from "./logging";
+
+/**
+ * Narrowest logging seam — consumers that only write review-log entries.
+ * Injected into `PermissionPrompter` and the RPC handlers.
+ */
+export interface ReviewLogger {
+  review(event: string, details?: Record<string, unknown>): void;
+}
+
+/**
+ * Logging seam for consumers that write both debug and review entries.
+ * Injected into `ConfigStore` and `PermissionForwarder`.
+ */
+export interface DebugReviewLogger extends ReviewLogger {
+  debug(event: string, details?: Record<string, unknown>): void;
+}
+
+/**
+ * Unified logging + notification surface for handler deps.
+ *
+ * Replaces three separate logging fields (`writeDebugLog`,
+ * `writeReviewLog`, `notifyWarning`) with a single typed collaborator.
+ * This is an intermediate abstraction on the path to PermissionSession (#129).
+ */
+export interface SessionLogger extends DebugReviewLogger {
+  warn(message: string): void;
+}
+
+/** Narrow dependencies for constructing a {@link SessionLogger}. */
+export interface SessionLoggerDeps {
+  /** Root logs directory; the debug + review log file paths derive from it. */
+  globalLogsDir: string;
+  /** Reads current config for the debug/review write toggles (call-time). */
+  getConfig: () => PermissionSystemExtensionConfig;
+  /** Surfaces a warning message to the user; called at warn/IO-failure time. */
+  notify: (message: string) => void;
+}
+
+/**
+ * Concrete `SessionLogger` implementation.
+ *
+ * Composes the JSONL log writer, privately owns the IO-failure warning
+ * dedup Set, and routes both IO-failure warnings and explicit warn() calls
+ * through the injected notify sink. No ExtensionRuntime reference required.
+ */
+export class PermissionSessionLogger implements SessionLogger {
+  private readonly writer: PermissionSystemLogger;
+  private readonly reported = new Set<string>();
+  private readonly notify: (message: string) => void;
+
+  constructor(deps: SessionLoggerDeps) {
+    this.writer = createPermissionSystemLogger({
+      getConfig: deps.getConfig,
+      debugLogPath: join(deps.globalLogsDir, DEBUG_LOG_FILENAME),
+      reviewLogPath: join(deps.globalLogsDir, REVIEW_LOG_FILENAME),
+      ensureLogsDirectory: () =>
+        ensurePermissionSystemLogsDirectory(deps.globalLogsDir),
+    });
+    this.notify = deps.notify;
+  }
+
+  debug(event: string, details?: Record<string, unknown>): void {
+    const warning = this.writer.debug(event, details);
+    if (warning) this.reportOnce(warning);
+  }
+
+  review(event: string, details?: Record<string, unknown>): void {
+    const warning = this.writer.review(event, details);
+    if (warning) this.reportOnce(warning);
+  }
+
+  warn(message: string): void {
+    this.notify(message);
+  }
+
+  private reportOnce(warning: string): void {
+    if (this.reported.has(warning)) return;
+    this.reported.add(warning);
+    this.notify(warning);
+  }
+}

package/src/session-rules.ts

@@ -0,0 +1,79 @@
+import { dirname, sep } from "node:path";
+
+import type { Ruleset } from "./rule";
+import type { SessionApproval } from "./session-approval";
+import type { SessionApprovalRecorder } from "./session-approval-recorder";
+
+/**
+ * Ephemeral in-memory store of session-scoped permission approvals.
+ *
+ * Each approval is stored as a `Rule` with `action: "allow"`, making the
+ * ruleset directly usable with `evaluate()` — no custom matching engine needed.
+ *
+ * Cleared on session_shutdown — never persisted to disk.
+ */
+export class SessionRules implements SessionApprovalRecorder {
+  private rules: Ruleset = [];
+
+  /** Record a wildcard pattern as approved for the given surface. */
+  approve(surface: string, pattern: string): void {
+    this.rules.push({
+      surface,
+      pattern,
+      action: "allow",
+      layer: "session",
+      origin: "session",
+    });
+  }
+
+  /** Return a defensive copy of the current session ruleset. */
+  getRuleset(): Ruleset {
+    return [...this.rules];
+  }
+
+  /**
+   * Record all patterns from a `SessionApproval` value object.
+   *
+   * The loop lives here so callers never need to know whether an approval
+   * carries one pattern or many — they just tell the store to record it.
+   */
+  recordSessionApproval(approval: SessionApproval): void {
+    for (const pattern of approval.patterns) {
+      this.approve(approval.surface, pattern);
+    }
+  }
+
+  /** Remove all session approvals. */
+  clear(): void {
+    this.rules = [];
+  }
+}
+
+/**
+ * Derive the wildcard glob pattern to approve from a normalized path.
+ *
+ * Returns `<parent-dir>/*` so that `evaluate()` / `wildcardMatch()` matches
+ * all paths under the approved directory — identical semantics to the former
+ * `SessionApprovalCache` prefix matching, using the unified wildcard engine.
+ *
+ * For paths that already end with a separator (directories), the separator
+ * is treated as the directory boundary and `*` is appended directly.
+ *
+ * The path is expected to be the canonical (cwd-resolved, absolute) form used
+ * for policy matching, so the derived pattern matches the same policy values a
+ * later tool call produces. Callers that hold a working directory resolve the
+ * path to that form first; the function itself stays free of cwd state.
+ */
+export function deriveApprovalPattern(normalizedPath: string): string {
+  // If the path already ends with a separator, it's a directory — glob its contents.
+  if (normalizedPath.endsWith(sep)) {
+    return `${normalizedPath}*`;
+  }
+  const dir = dirname(normalizedPath);
+  if (dir === normalizedPath) {
+    // Root path — dirname('/') === '/'
+    return `${dir}*`;
+  }
+  const prefix = dir.endsWith(sep) ? dir : `${dir}${sep}`;
+  return `${prefix}*`;
+}