@gotgenes/pi-permission-system 15.0.0 → 15.1.0

package/CHANGELOG.md

@@ -5,6 +5,32 @@ 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).
 
+## [15.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v15.0.1...pi-permission-system-v15.1.0) (2026-06-20)
+
+
+### Features
+
+* **pi-permission-system:** trace tool-call decisions and emit a session summary ([#452](https://github.com/gotgenes/pi-packages/issues/452)) ([528e340](https://github.com/gotgenes/pi-packages/commit/528e340ae38a6b2f431dac1ab92642c1af72c0ac))
+* **pi-permission-system:** warn when a permissive top-level "*" leaves bash ungated ([#452](https://github.com/gotgenes/pi-packages/issues/452)) ([8ef8d0f](https://github.com/gotgenes/pi-packages/commit/8ef8d0fdf39297817c57968f0e345d79c6369d3a))
+
+
+### Bug Fixes
+
+* **pi-permission-system:** prompt instead of allowing an unparseable bash command ([#452](https://github.com/gotgenes/pi-packages/issues/452)) ([538bac1](https://github.com/gotgenes/pi-packages/commit/538bac12e343d613f2e980dabb516a880b90f3fe))
+* **pi-permission-system:** retry tree-sitter parser init instead of caching a rejected promise ([#452](https://github.com/gotgenes/pi-packages/issues/452)) ([468facd](https://github.com/gotgenes/pi-packages/commit/468facd50e9f9ee986121f76546c368851b14edb))
+
+
+### Documentation
+
+* **pi-permission-system:** document fail-closed gate behavior and bash fallback warning ([#452](https://github.com/gotgenes/pi-packages/issues/452)) ([fbb2844](https://github.com/gotgenes/pi-packages/commit/fbb28449afe9d92934769499d874c1cb93241c1b))
+
+## [15.0.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v15.0.0...pi-permission-system-v15.0.1) (2026-06-20)
+
+
+### Bug Fixes
+
+* **permission-system:** bind session approval for current-directory files ([#438](https://github.com/gotgenes/pi-packages/issues/438)) ([083a8e8](https://github.com/gotgenes/pi-packages/commit/083a8e8d9c2a4f6c49af158677d8669b4f099d9f))
+
 ## [15.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v14.0.1...pi-permission-system-v15.0.0) (2026-06-20)
 
 

package/README.md

@@ -19,6 +19,7 @@ Permission enforcement extension for the [Pi](https://pi.mariozechner.at/) codin
 - **Gates MCP and skill access** at server, tool, and skill-name granularity
 - **Protects sensitive file patterns** — cross-cutting `path` rules deny `.env`, `~/.ssh/*`, etc. across all tools and bash at once
 - **Guards external paths** — prompts before file tools or bash commands reach outside `cwd`
+- **Fails closed** — an internal gate error blocks the tool (with a `gate_error` review-log entry), and an unparseable bash command prompts (`ask`) rather than passing silently
 - **Forwards prompts from subagents** — `ask` policies work even in non-UI execution contexts
 - **Broadcasts UI prompt events** — `permissions:ui_prompt` fires only when the permission system is about to invoke the active user-facing permission UI
 - **Native [`@gotgenes/pi-subagents`](https://github.com/gotgenes/pi-subagents) integration** — in-process child sessions register with the permission system automatically, enabling per-agent policy enforcement and `ask`-state forwarding to the parent UI without configuration
@@ -44,6 +45,7 @@ pi install npm:@gotgenes/pi-permission-system
           "*.env.example": "allow"
         },
         "bash": {
+          "*": "ask",
           "rm -rf *": "deny",
           "sudo *": "ask"
         },

package/package.json

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

package/src/async-cache.ts

@@ -0,0 +1,21 @@
+/**
+ * Memoize an async factory, but drop a rejected result so the next call
+ * retries.
+ *
+ * On success the resolved promise is cached and shared across all callers (the
+ * factory runs once). On failure the cache is cleared before the rejection is
+ * re-thrown, so a transient init failure does not poison the memo for the
+ * process lifetime — the next call re-invokes the factory.
+ */
+export function memoizeAsyncWithRetry<T>(
+  factory: () => Promise<T>,
+): () => Promise<T> {
+  let cached: Promise<T> | null = null;
+  return () => {
+    cached ??= factory().catch((error: unknown) => {
+      cached = null; // poisoned result cleared → next call re-attempts
+      throw error;
+    });
+    return cached;
+  };
+}

package/src/config-loader.ts

@@ -365,6 +365,9 @@ export function loadAndMergeConfigs(
   const projectConfig = projectResult.config;
   merged = mergeUnifiedConfigs(merged, projectConfig);
 
+  const bashFallbackIssue = detectPermissiveBashFallback(merged.permission);
+  if (bashFallbackIssue) allIssues.push(bashFallbackIssue);
+
   return {
     global: globalConfig,
     project: projectConfig,
@@ -373,6 +376,38 @@ export function loadAndMergeConfigs(
   };
 }
 
+/**
+ * Detect the config footgun where a permissive top-level `*: allow` leaves the
+ * bash surface ungated, so every bash command silently inherits `allow`.
+ *
+ * Returns one warning string when `permission["*"] === "allow"` and the `bash`
+ * surface neither is a bare string (shorthand for `{ "*": … }`) nor an object
+ * map with an explicit `"*"` key. Returns `undefined` otherwise. The detector
+ * is pure: it takes the merged permission map and returns a message; the caller
+ * owns pushing it onto the issue list.
+ */
+export function detectPermissiveBashFallback(
+  permission: FlatPermissionConfig | undefined,
+): string | undefined {
+  if (permission?.["*"] !== "allow") return undefined;
+
+  // The Record index signature reports an absent surface as the value type, not
+  // `undefined`; read through a Partial view so the absent-bash guard is honest
+  // (an unguarded Object.hasOwn(undefined, …) would throw at runtime).
+  const surfaces: Partial<FlatPermissionConfig> = permission;
+  const bash = surfaces.bash;
+  // A bare string surface is shorthand for `{ "*": action }` — explicitly gated.
+  if (typeof bash === "string") return undefined;
+  // An object map with an explicit `"*"` key is explicitly gated.
+  if (bash && Object.hasOwn(bash, "*")) return undefined;
+
+  return (
+    "Permission config sets a permissive top-level '*': 'allow' with no 'bash' '*' policy, " +
+    "so bash commands silently inherit 'allow'. Set an explicit 'bash' policy " +
+    '(e.g. "bash": { "*": "ask" }) to gate bash commands.'
+  );
+}
+
 /**
  * Load and normalize a unified config file.
  * Returns an empty config with no issues if the file does not exist.

package/src/decision-audit.ts

@@ -0,0 +1,75 @@
+/**
+ * Records the per-call terminal decision so an evaluated-and-allowed call is
+ * distinguishable from a never-evaluated one. The fail-closed boundary owns the
+ * recorder and calls exactly one of `recordDecision` / `recordError` per call.
+ */
+export interface DecisionRecorder {
+  /** Record a terminal allow/block decision (also bumps the tool-call count). */
+  recordDecision(action: "allow" | "block"): void;
+  /** Record a gate error that blocked fail-closed (also bumps the count). */
+  recordError(): void;
+}
+
+/** Narrow logging surface the summary needs: a debug line and a warning. */
+export interface AuditLogger {
+  debug(event: string, details?: Record<string, unknown>): void;
+  warn(message: string): void;
+}
+
+/** Narrow surface the session-shutdown handler depends on. */
+export interface DecisionSummaryWriter {
+  writeSummary(logger: AuditLogger): void;
+}
+
+/**
+ * In-process, per-session decision counters.
+ *
+ * The boundary produces exactly one terminal decision per tool call, so
+ * `toolCalls` must always equal `allowed + blocked + errors`. `writeSummary`
+ * emits the counters on `session_shutdown` and flags any mismatch as a cheap
+ * structural self-check — a mismatch means a code path re-opened a silent
+ * (never-recorded) exit.
+ */
+export class DecisionAudit implements DecisionRecorder {
+  private toolCalls = 0;
+  private allowed = 0;
+  private blocked = 0;
+  private errors = 0;
+
+  recordDecision(action: "allow" | "block"): void {
+    this.toolCalls++;
+    if (action === "allow") {
+      this.allowed++;
+    } else {
+      this.blocked++;
+    }
+  }
+
+  recordError(): void {
+    this.toolCalls++;
+    this.errors++;
+  }
+
+  /**
+   * Emit one `permission.session_summary` debug line with the counters. When
+   * `toolCalls !== allowed + blocked + errors`, also emit a warning — the
+   * invariant violation means a tool call resolved without a recorded terminal
+   * decision (a re-opened silent path).
+   */
+  writeSummary(logger: AuditLogger): void {
+    const counts = {
+      toolCalls: this.toolCalls,
+      allowed: this.allowed,
+      blocked: this.blocked,
+      errors: this.errors,
+    };
+    logger.debug("permission.session_summary", counts);
+    if (this.toolCalls !== this.allowed + this.blocked + this.errors) {
+      logger.warn(
+        `[pi-permission-system] decision audit invariant violated: ${this.toolCalls} tool calls != ` +
+          `${this.allowed} allowed + ${this.blocked} blocked + ${this.errors} errors. ` +
+          "A tool call resolved without a recorded terminal decision.",
+      );
+    }
+  }
+}

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

@@ -19,9 +19,13 @@ import type { PermissionCheckResult } from "#src/types";
  * `commandContext` (set only for a nested command), so the prompt,
  * session-approval suggestion, and decision event scope to that command.
  *
- * When `commands` is empty (an empty command, a comment, or a bare compound
- * statement), the whole `command` is evaluated as before, so the surface is
- * never weaker than the previous behavior.
+ * When `commands` is empty there are two cases. A trivially-empty command (an
+ * empty, whitespace-only, or comment-only line) has genuinely nothing to gate,
+ * so the whole `command` is resolved as before. A non-empty command that parsed
+ * to zero command units (a parse anomaly or an opaque program) fails closed to
+ * a synthetic `ask` so a permissive top-level `*` cannot silently allow an
+ * unparseable command (e.g. `cd /repo && git push` riding a top-level allow on
+ * the empty-parse path) — #452.
  *
  * Pure and synchronous: the (async, tree-sitter) parse happens once in the
  * handler, which passes the decomposed `commands` here.
@@ -32,6 +36,20 @@ export function resolveBashCommandCheck(
   agentName: string | undefined,
   resolver: ScopedPermissionResolver,
 ): PermissionCheckResult {
+  if (commands.length === 0) {
+    if (isTriviallyEmptyCommand(command)) {
+      return resolver.resolve("bash", { command }, agentName);
+    }
+    return {
+      state: "ask",
+      toolName: "bash",
+      source: "bash",
+      origin: "builtin",
+      command,
+      matchedPattern: "<unparseable-bash-command>",
+    };
+  }
+
   const results = commands.map((cmd) => {
     const result = resolver.resolve("bash", { command: cmd.text }, agentName);
     return cmd.context ? { ...result, commandContext: cmd.context } : result;
@@ -41,3 +59,17 @@ export function resolveBashCommandCheck(
     resolver.resolve("bash", { command }, agentName)
   );
 }
+
+/**
+ * True when a command has genuinely nothing to gate: it is empty,
+ * whitespace-only, or contains only comment lines (every non-blank line starts
+ * with `#`). Such a command yields zero command units legitimately, so the
+ * whole-string resolve is safe rather than a parse anomaly.
+ */
+function isTriviallyEmptyCommand(command: string): boolean {
+  const lines = command
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+  return lines.every((line) => line.startsWith("#"));
+}

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

@@ -40,9 +40,14 @@ export function describeBashPathGate(
   if (candidates.length === 0) return null;
   const tokens = candidates.map(({ token }) => token);
 
-  // Tokens whose resolved state needs a check (deny/ask), paired with the
-  // token that produced them so the descriptor can derive its pattern.
-  const uncovered: Array<{ token: string; check: PermissionCheckResult }> = [];
+  // Tokens whose resolved state needs a check (deny/ask), paired with the raw
+  // token (prompt/decision display) and its policy values (the first of which
+  // is the canonical absolute path the approval pattern is derived from).
+  const uncovered: Array<{
+    token: string;
+    policyValues: readonly string[];
+    check: PermissionCheckResult;
+  }> = [];
   let allSessionCovered = true;
 
   for (const { token, policyValues } of candidates) {
@@ -64,11 +69,11 @@ export function describeBashPathGate(
     }
 
     if (check.state === "deny") {
-      uncovered.push({ token, check });
+      uncovered.push({ token, policyValues, check });
       break; // Short-circuit on deny.
     }
     if (check.state === "ask") {
-      uncovered.push({ token, check });
+      uncovered.push({ token, policyValues, check });
     }
   }
 
@@ -93,14 +98,19 @@ export function describeBashPathGate(
 
   // Pick the most restrictive (deny > ask > allow, first-wins) uncovered token.
   const worstCheck = pickMostRestrictive(uncovered.map(({ check }) => check));
-  const worstToken = worstCheck
-    ? (uncovered.find(({ check }) => check === worstCheck)?.token ?? null)
-    : null;
+  const worstEntry = worstCheck
+    ? uncovered.find(({ check }) => check === worstCheck)
+    : undefined;
+  const worstToken = worstEntry?.token ?? null;
 
   // All tokens evaluate to allow — no restriction.
-  if (!worstCheck || !worstToken) return null;
+  if (!worstCheck || !worstToken || !worstEntry) return null;
 
-  const pattern = deriveApprovalPattern(worstToken);
+  // Derive the pattern from the canonical absolute policy value (the cd-aware
+  // resolved path), so it matches the values a later call produces. Falls back
+  // to the raw token only when no base was resolvable (no cwd / unknown cd).
+  const approvalBase = worstEntry.policyValues[0] ?? worstToken;
+  const pattern = deriveApprovalPattern(approvalBase);
   const askMessage = formatPathAskPrompt(
     tcc.toolName,
     worstToken,

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

@@ -1,5 +1,6 @@
 import { createRequire } from "node:module";
 import { basename, isAbsolute, join, resolve } from "node:path";
+import { memoizeAsyncWithRetry } from "#src/async-cache";
 import { canonicalizePath } from "#src/canonicalize-path";
 import {
   classifyTokenAsPathCandidate,
@@ -37,8 +38,6 @@ interface TSParser {
   delete(): void;
 }
 
-let parserPromise: Promise<TSParser> | null = null;
-
 async function initParser(): Promise<TSParser> {
   // Use named imports — web-tree-sitter exports Parser as a named class.
   const { Parser, Language } = await import("web-tree-sitter");
@@ -53,10 +52,10 @@ async function initParser(): Promise<TSParser> {
   return parser;
 }
 
-function getParser(): Promise<TSParser> {
-  parserPromise ??= initParser();
-  return parserPromise;
-}
+// Memoize on success but drop a rejected result so a transient init failure
+// (e.g. a slow WASM load) is retried on the next tool call instead of poisoning
+// the parser for the process lifetime.
+const getParser = memoizeAsyncWithRetry(initParser);
 
 // ── Parsed bash command representation ───────────────────────────────────────
 

package/src/handlers/gates/path.ts

@@ -1,4 +1,4 @@
-import { getToolInputPath } from "#src/path-utils";
+import { getToolInputPath, normalizePathForComparison } from "#src/path-utils";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
@@ -35,7 +35,12 @@ export function describePathGate(
   // "path" key should not trigger path-level prompts (#58).
   if (check.matchedPattern === undefined) return null;
 
-  const pattern = deriveApprovalPattern(filePath);
+  // Resolve to the canonical (cwd-anchored, absolute) path so the approval
+  // pattern matches the policy values a later call produces.
+  const approvalPath = tcc.cwd
+    ? normalizePathForComparison(filePath, tcc.cwd)
+    : filePath;
+  const pattern = deriveApprovalPattern(approvalPath);
 
   const descriptor: GateDescriptor = {
     surface: "path",

package/src/handlers/gates/tool.ts

@@ -1,4 +1,8 @@
-import { getPathBearingToolPath, PATH_BEARING_TOOLS } from "#src/path-utils";
+import {
+  getPathBearingToolPath,
+  normalizePathForComparison,
+  PATH_BEARING_TOOLS,
+} from "#src/path-utils";
 import { suggestSessionPattern } from "#src/pattern-suggest";
 import { formatAskPrompt } from "#src/permission-prompts";
 import { SessionApproval } from "#src/session-approval";
@@ -12,7 +16,9 @@ import type { ToolCallContext } from "./types";
  * Derive the value used for session-approval pattern suggestions.
  *
  * Bash → command string; MCP → qualified target;
- * path-bearing tools → file path; others → catch-all wildcard.
+ * path-bearing tools → the file path resolved to its canonical (cwd-anchored,
+ * absolute) form so the suggested pattern matches the policy values a later
+ * call produces; others → catch-all wildcard.
  */
 function deriveSuggestionValue(
   tcc: ToolCallContext,
@@ -20,7 +26,9 @@ function deriveSuggestionValue(
 ): string {
   if (tcc.toolName === "bash") return check.command ?? "";
   if (tcc.toolName === "mcp") return check.target ?? "mcp";
-  return getPathBearingToolPath(tcc.toolName, tcc.input) ?? "*";
+  const path = getPathBearingToolPath(tcc.toolName, tcc.input);
+  if (path === null) return "*";
+  return tcc.cwd ? normalizePathForComparison(path, tcc.cwd) : path;
 }
 
 /**

package/src/handlers/lifecycle.ts

@@ -1,5 +1,6 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
+import type { DecisionSummaryWriter } from "#src/decision-audit";
 import type { PermissionResolver } from "#src/permission-resolver";
 import type { PermissionSession } from "#src/permission-session";
 import type { ServiceLifecycle } from "#src/service-lifecycle";
@@ -26,6 +27,7 @@ interface ResourcesDiscoverPayload {
  *   `activate` publishes (skipped for registered subagent children) and emits
  *   the ready event; `teardown` unsubscribes all session listeners and unpublishes
  * - `logger` — injected directly; replaces the former `session.logger` reach-through
+ * - `audit` — per-session decision counters; its summary is written on shutdown
  */
 export class SessionLifecycleHandler {
   constructor(
@@ -33,6 +35,7 @@ export class SessionLifecycleHandler {
     private readonly resolver: PermissionResolver,
     private readonly serviceLifecycle: ServiceLifecycle,
     private readonly logger: SessionLogger,
+    private readonly audit: DecisionSummaryWriter,
   ) {}
 
   handleSessionStart(
@@ -84,6 +87,7 @@ export class SessionLifecycleHandler {
     if (ctx) {
       ctx.ui.setStatus(PERMISSION_SYSTEM_STATUS_KEY, undefined);
     }
+    this.audit.writeSummary(this.logger);
     this.session.shutdown();
     this.serviceLifecycle.teardown();
     return Promise.resolve();

package/src/handlers/permission-gate-handler.ts

@@ -20,7 +20,7 @@ import type {
   SkillInputGatePipeline,
 } from "./gates/skill-input-gate-pipeline";
 import type { ToolCallGatePipeline } from "./gates/tool-call-gate-pipeline";
-import type { ToolCallContext } from "./gates/types";
+import type { GateOutcome, ToolCallContext } from "./gates/types";
 
 /** Minimal subset of InputEvent used by handleInput. */
 interface InputPayload {
@@ -49,12 +49,12 @@ export class PermissionGateHandler {
   async handleToolCall(
     event: unknown,
     ctx: ExtensionContext,
-  ): Promise<{ block?: true; reason?: string }> {
+  ): Promise<GateOutcome> {
     this.session.activate(ctx);
 
     const validation = validateRequestedTool(event, this.toolRegistry.getAll());
     if (validation.status === "block") {
-      return { block: true, reason: validation.reason };
+      return { action: "block", reason: validation.reason };
     }
     const toolName = validation.toolName;
 
@@ -74,10 +74,7 @@ export class PermissionGateHandler {
       cwd: ctx.cwd,
     };
 
-    const outcome = await this.pipeline.evaluate(tcc, this.runner);
-    return outcome.action === "block"
-      ? { block: true, reason: outcome.reason }
-      : {};
+    return await this.pipeline.evaluate(tcc, this.runner);
   }
 
   async handleInput(

package/src/handlers/tool-call-boundary.ts

@@ -0,0 +1,91 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { toRecord } from "#src/common";
+import type { DecisionRecorder } from "#src/decision-audit";
+import type { DecisionReporter } from "#src/decision-reporter";
+import type { GateOutcome } from "./gates/types";
+
+/** The SDK-facing result shape for a `tool_call` handler. */
+type ToolCallResult = { block?: true; reason?: string };
+
+/**
+ * Narrow debug surface for the per-call decision trace. The concrete logger
+ * self-gates on `debugLog`, so the boundary emits unconditionally and the
+ * entry is dropped when the toggle is off (no per-call spam in normal use).
+ */
+export interface DecisionTracer {
+  debug(event: string, details?: Record<string, unknown>): void;
+}
+
+/**
+ * The only `tool_call` handler the SDK sees.
+ *
+ * Guarantees fail-closed: it owns the `try/catch → block` and is the sole place
+ * an internal {@link GateOutcome} is translated to the SDK result shape, so
+ * "we didn't decide" can never silently mean "allow."
+ *
+ * The SDK's `emitToolCall` (`@earendil-works/pi-coding-agent`
+ * `dist/core/extensions/runner.js`) awaits the registered handler with **no**
+ * try/catch — unlike `emitUserBash` directly below it, which catches and
+ * continues. A thrown gate therefore yields no `{ block: true }` and the
+ * command runs ungated with nothing logged. This boundary absorbs that throw,
+ * blocks, and writes a `gate_error` review-log entry.
+ *
+ * Fail-closed = **block** (not `ask`) for an unexpected exception: the command
+ * may be unknown and the prompt infrastructure itself may be what threw, so a
+ * hard block is the unambiguous safe outcome.
+ */
+export function createFailClosedToolCall(
+  gate: (event: unknown, ctx: ExtensionContext) => Promise<GateOutcome>,
+  reporter: DecisionReporter,
+  audit: DecisionRecorder,
+  tracer: DecisionTracer,
+): (event: unknown, ctx: ExtensionContext) => Promise<ToolCallResult> {
+  return async (event, ctx) => {
+    try {
+      const outcome = await gate(event, ctx);
+      audit.recordDecision(outcome.action);
+      tracer.debug("permission.decision", {
+        toolName: bestEffortToolName(event),
+        action: outcome.action,
+        ...(outcome.action === "block" ? { reason: outcome.reason } : {}),
+      });
+      return outcome.action === "block"
+        ? { block: true, reason: outcome.reason }
+        : {};
+    } catch (error) {
+      audit.recordError();
+      reporter.writeReviewLog("permission_request.blocked", {
+        toolName: bestEffortToolName(event),
+        command: bestEffortCommand(event),
+        resolution: "gate_error",
+        error: errorMessage(error),
+      });
+      return { block: true, reason: formatGateErrorReason(error) };
+    }
+  };
+}
+
+// ── Defensive event readers (never throw) ──────────────────────────────────
+
+/** Best-effort tool name from a raw event; never throws. */
+function bestEffortToolName(event: unknown): string {
+  const record = toRecord(event);
+  const name = record.name ?? record.toolName;
+  return typeof name === "string" && name ? name : "<unknown>";
+}
+
+/** Best-effort bash command from a raw event; never throws. */
+function bestEffortCommand(event: unknown): string | undefined {
+  const record = toRecord(event);
+  const input = toRecord(record.input ?? record.arguments);
+  return typeof input.command === "string" ? input.command : undefined;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function formatGateErrorReason(error: unknown): string {
+  return `Permission gate failed and blocked the tool call (fail-closed): ${errorMessage(error)}`;
+}

package/src/index.ts

@@ -4,6 +4,7 @@ import { registerBuiltinToolInputFormatters } from "./builtin-tool-input-formatt
 import { registerPermissionSystemCommand } from "./config-modal";
 import { getGlobalConfigPath } from "./config-paths";
 import { ConfigStore } from "./config-store";
+import { DecisionAudit } from "./decision-audit";
 import { GateDecisionReporter } from "./decision-reporter";
 import { computeExtensionPaths } from "./extension-paths";
 import {
@@ -19,6 +20,7 @@ import {
 import { GateRunner } from "./handlers/gates/runner";
 import { SkillInputGatePipeline } from "./handlers/gates/skill-input-gate-pipeline";
 import { ToolCallGatePipeline } from "./handlers/gates/tool-call-gate-pipeline";
+import { createFailClosedToolCall } from "./handlers/tool-call-boundary";
 import { requestPermissionDecisionFromUi } from "./permission-dialog";
 import { registerPermissionRpcHandlers } from "./permission-event-rpc";
 import { PermissionManager } from "./permission-manager";
@@ -163,11 +165,13 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
 
   const resolver = new PermissionResolver(permissionManager, sessionRules);
 
+  const audit = new DecisionAudit();
   const lifecycle = new SessionLifecycleHandler(
     session,
     resolver,
     serviceLifecycle,
     logger,
+    audit,
   );
   const agentPrep = new AgentPrepHandler(session, resolver, toolRegistry);
 
@@ -197,5 +201,13 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   pi.on("session_shutdown", () => lifecycle.handleSessionShutdown());
   pi.on("before_agent_start", (event, ctx) => agentPrep.handle(event, ctx));
   pi.on("input", (event, ctx) => gates.handleInput(event, ctx));
-  pi.on("tool_call", (event, ctx) => gates.handleToolCall(event, ctx));
+  pi.on(
+    "tool_call",
+    createFailClosedToolCall(
+      (event, ctx) => gates.handleToolCall(event, ctx),
+      reporter,
+      audit,
+      logger,
+    ),
+  );
 }

package/src/pattern-suggest.ts

@@ -90,6 +90,10 @@ function buildLabel(pattern: string, surface: string): string {
  *
  * Returns a `SessionApprovalSuggestion` with the surface, the wildcard pattern
  * to store in `SessionRules`, and a human-readable dialog label.
+ *
+ * `value` is expected to be the canonical (cwd-resolved, absolute) path for
+ * path surfaces — callers resolve it before suggesting, so the derived pattern
+ * matches the policy values a later tool call produces.
  */
 export function suggestSessionPattern(
   surface: string,

package/src/session-rules.ts

@@ -58,6 +58,11 @@ export class SessionRules implements SessionApprovalRecorder {
  *
  * 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.