@gotgenes/pi-permission-system 32.0.0 → 32.0.2

package/CHANGELOG.md

@@ -5,6 +5,29 @@ 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).
 
+## [32.0.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v32.0.1...pi-permission-system-v32.0.2) (2026-09-11)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** keep a forwarded write when a file lock blocks the atomic rename ([d901116](https://github.com/gotgenes/pi-packages/commit/d9011165203b130675a3affd20a2792f7abd7105)), closes [#914](https://github.com/gotgenes/pi-packages/issues/914)
+* **pi-permission-system:** create a forwarding directory blocked by a transient file lock ([245683c](https://github.com/gotgenes/pi-packages/commit/245683c9153712d8991ceb21ece7884b2fb12f2a)), closes [#914](https://github.com/gotgenes/pi-packages/issues/914)
+
+### Documentation
+
+* **pi-permission-system:** record the transient filesystem retry ([eb7ab58](https://github.com/gotgenes/pi-packages/commit/eb7ab58cfd79d15de77bafa6afe8813e9dff7b72)), closes [#914](https://github.com/gotgenes/pi-packages/issues/914)
+
+## [32.0.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v32.0.0...pi-permission-system-v32.0.1) (2026-09-11)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** deny a forbidden command without prompting first ([b840196](https://github.com/gotgenes/pi-packages/commit/b8401962a9eeb012317771fc204c3fde8aa8a9a2)), closes [#899](https://github.com/gotgenes/pi-packages/issues/899)
+
+### Documentation
+
+* **pi-permission-system:** document that a deny on any layer needs no prompt ([e526e95](https://github.com/gotgenes/pi-packages/commit/e526e950ab6d957e6b5bc4d6f7740bcce2e35dca)), closes [#899](https://github.com/gotgenes/pi-packages/issues/899)
+
 ## [32.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v31.1.4...pi-permission-system-v32.0.0) (2026-09-11)
 
 

package/README.md

@@ -97,6 +97,7 @@ The trailing `*` is greedy and crosses subdirectory boundaries, so it allows eve
 
 Four layers compose with most-restrictive-wins: `path` (cross-cutting) → `external_directory` (CWD boundary) → per-tool patterns → `bash` command patterns.
 Because `ask` is more restrictive than `allow`, a `path` allow cannot loosen an `external_directory: ask` boundary — allow outside-CWD directories on `external_directory`.
+And because `deny` is more restrictive than `ask`, a `deny` on any layer refuses the call without prompting, naming the rule that decided.
 See [docs/configuration.md](docs/configuration.md) for the full recipe.
 
 Both path surfaces also carry a **direction**, so you can permit reading somewhere without permitting writing there: `path_read`, `path_write`, `external_directory_read`, and `external_directory_write`.

package/docs/configuration.md

@@ -559,6 +559,10 @@ Use `path` to **deny** sensitive files everywhere (`.env`, `~/.ssh/*`); use `ext
 Because the layers compose with most-restrictive-wins, a `path` allow cannot loosen an `external_directory: ask` boundary — `ask` is more restrictive than `allow`, so the prompt still fires.
 Adding `"~/.cargo/registry": "allow"` to the `path` surface therefore does **not** stop the outside-CWD prompt; put the rule on `external_directory` instead (see below).
 
+The same ordering runs the other way at the top of the scale.
+`deny` is more restrictive than `ask`, so a `deny` on any layer refuses the call **without prompting**, whichever layer carries the rule.
+A `bash: {"find / *": "deny"}` rule therefore suppresses the outside-CWD prompt that `find /` would otherwise raise, and the refusal names the `bash` rule that decided rather than the boundary that asked.
+
 Configs without a `path` key behave identically to before — the gate does not fire.
 When no `path` key is present, the universal fallback (`permission["*"]`) applies: `"*": "allow"` keeps the gate transparent, while `"*": "deny"` would deny all file access via every surface including `path`.
 

package/docs/troubleshooting.md

@@ -2,15 +2,16 @@
 
 ## Common Issues
 
-| Problem                                                           | Cause                                                             | Solution                                                                                                                                          |
-| ----------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Config not applied (everything asks)                              | File not found or parse error                                     | Verify the global config at `~/.pi/agent/extensions/pi-permission-system/config.json` (respects `PI_CODING_AGENT_DIR`); check for trailing commas |
-| Per-agent override not applied                                    | Frontmatter parsing issue                                         | Ensure `---` delimiters at file top; keep YAML simple; restart session                                                                            |
-| Tool blocked as unregistered                                      | Unknown tool name                                                 | Use a registered `mcp` tool for server tools: `{ "tool": "server:tool" }`                                                                         |
-| `/skill:<name>` blocked                                           | Deny policy or confirmation unavailable                           | Check merged `skill` policy (global/project/agent layers). `ask` still requires UI or forwarded confirmation.                                     |
-| External file path blocked                                        | `external_directory` is `ask` without UI or `deny`                | Allow/ask the permission or keep file tools inside the active working directory.                                                                  |
-| Spurious external-path prompt for `cd <subdir> && grep … ../path` | Relative path was resolved against cwd instead of the `cd` target | Fixed in current version — paths after a leading `cd <subdir> &&` are resolved against the cd target, matching actual shell behavior.             |
-| Permission prompt is too verbose                                  | Generic extension tool input is large                             | Built-in file tools are summarized automatically; third-party tools are capped to a bounded one-line JSON preview.                                |
+| Problem                                                                                                 | Cause                                                                                   | Solution                                                                                                                                                                                                                                                                    |
+| ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Config not applied (everything asks)                                                                    | File not found or parse error                                                           | Verify the global config at `~/.pi/agent/extensions/pi-permission-system/config.json` (respects `PI_CODING_AGENT_DIR`); check for trailing commas                                                                                                                           |
+| Per-agent override not applied                                                                          | Frontmatter parsing issue                                                               | Ensure `---` delimiters at file top; keep YAML simple; restart session                                                                                                                                                                                                      |
+| Tool blocked as unregistered                                                                            | Unknown tool name                                                                       | Use a registered `mcp` tool for server tools: `{ "tool": "server:tool" }`                                                                                                                                                                                                   |
+| `/skill:<name>` blocked                                                                                 | Deny policy or confirmation unavailable                                                 | Check merged `skill` policy (global/project/agent layers). `ask` still requires UI or forwarded confirmation.                                                                                                                                                               |
+| External file path blocked                                                                              | `external_directory` is `ask` without UI or `deny`                                      | Allow/ask the permission or keep file tools inside the active working directory.                                                                                                                                                                                            |
+| Spurious external-path prompt for `cd <subdir> && grep … ../path`                                       | Relative path was resolved against cwd instead of the `cd` target                       | Fixed in current version — paths after a leading `cd <subdir> &&` are resolved against the cd target, matching actual shell behavior.                                                                                                                                       |
+| Permission prompt is too verbose                                                                        | Generic extension tool input is large                                                   | Built-in file tools are summarized automatically; third-party tools are capped to a bounded one-line JSON preview.                                                                                                                                                          |
+| Windows: `permission_forwarding.error — EPERM … rename` in the logs, and a subagent's tool call refused | An antivirus scanner or the search indexer held a transient handle on a forwarding file | The write is retried automatically for a short window. If it still fails, enable `debugLog` and look for `permission_forwarding.fs_retried` entries — their `attempts` and `code` say whether retrying is helping — then exclude the forwarding directory from the scanner. |
 
 ## Diagnostic Logging
 

package/package.json

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

package/src/authority/forwarding-io.ts

@@ -29,6 +29,10 @@ import {
   type ForwardedSessionApproval,
   type PermissionForwardingLocation,
 } from "./permission-forwarding";
+import {
+  retryOnTransientFsError,
+  type TransientFsRetryRecord,
+} from "./transient-fs-retry";
 
 /** Valid `permissions:ui_prompt` source values, for tolerant request reads. */
 const UI_PROMPT_SOURCES = [
@@ -217,7 +221,14 @@ export function ensureDirectoryExists(
   description: string,
 ): boolean {
   try {
-    mkdirSync(path, { recursive: true, mode: OWNER_ONLY_DIRECTORY_MODE });
+    recordFsRetry(
+      logger,
+      "mkdir",
+      path,
+      retryOnTransientFsError(() => {
+        mkdirSync(path, { recursive: true, mode: OWNER_ONLY_DIRECTORY_MODE });
+      }),
+    );
     return true;
   } catch (error) {
     logPermissionForwardingError(
@@ -399,17 +410,51 @@ export function writeJsonFileAtomic(
   try {
     // `rename` preserves the temp file's mode, so setting it here is enough —
     // a response overwriting an existing file also comes through a fresh temp.
+    // The temp write is deliberately outside the retry: its failure shape is a
+    // write-denied directory, which no number of attempts resolves.
     writeFileSync(tempPath, JSON.stringify(value), {
       encoding: "utf-8",
       mode: OWNER_ONLY_FILE_MODE,
     });
-    renameSync(tempPath, filePath);
+    recordFsRetry(
+      logger,
+      "rename",
+      filePath,
+      retryOnTransientFsError(() => {
+        renameSync(tempPath, filePath);
+      }),
+    );
   } catch (error) {
     safeDeleteFile(logger, tempPath, "temporary permission-forwarding");
     throw error;
   }
 }
 
+/**
+ * Record a filesystem operation that only succeeded after retrying.
+ *
+ * Debug-only: a recovered write decided nothing, so it does not belong in the
+ * permission-decision record — but `attempts` and `code` are the whole
+ * diagnosis when a host keeps losing writes, and `debugLog` is exactly the
+ * switch a user reaching for that diagnosis turns on.
+ */
+function recordFsRetry(
+  logger: DebugReviewLogger | null,
+  operation: "rename" | "mkdir",
+  path: string,
+  record: TransientFsRetryRecord,
+): void {
+  if (record.attempts === 1) {
+    return;
+  }
+  logger?.debug("permission_forwarding.fs_retried", {
+    operation,
+    path,
+    attempts: record.attempts,
+    code: record.code,
+  });
+}
+
 export function readForwardedPermissionRequest(
   logger: DebugReviewLogger | null,
   filePath: string,

package/src/authority/transient-fs-retry.ts

@@ -0,0 +1,118 @@
+/**
+ * transient-fs-retry.ts — Survive a file lock that is about to clear.
+ *
+ * On Windows a `rename` or `mkdir` is not the POSIX operation of the same
+ * name: an antivirus scanner, the search indexer, or any other process holding
+ * a transient handle on a path fails the call with `EPERM`/`EBUSY`/`EACCES`.
+ * The forwarded-permission writes that ride on those calls are then simply
+ * lost — a child's request write becomes a refused tool call, and a serving
+ * heartbeat goes unpublished (#914).
+ *
+ * A few attempts a few milliseconds apart is enough for the common case. The
+ * decision lives here rather than at either call site so both inherit one
+ * errno set and one budget, and so it can be tested without a filesystem.
+ */
+
+/** Tuning seams, injected so a unit test asserts the backoff without sleeping. */
+export interface TransientFsRetryOptions {
+  delaysMs?: readonly number[];
+  sleep?: (ms: number) => void;
+}
+
+/** How an operation that eventually succeeded got there. */
+export interface TransientFsRetryRecord {
+  /** Attempts made, counting the first — `1` when it succeeded outright. */
+  attempts: number;
+  /** The transient errno that forced the retries, or `null` when there were none. */
+  code: string | null;
+}
+
+/**
+ * Run `operation`, retrying while a transient filesystem lock rejects it.
+ *
+ * Returns how it went, so the caller can record a recovery without this module
+ * having to know anything about logging. An error outside the transient set is
+ * rethrown immediately with no sleep, keeping a permanent `ENOTDIR`/`ENOENT`
+ * exactly as fast as it is today; an exhausted budget rethrows the last error,
+ * so every caller's existing `catch` keeps working unchanged.
+ */
+export function retryOnTransientFsError(
+  operation: () => void,
+  options?: TransientFsRetryOptions,
+): TransientFsRetryRecord {
+  const delaysMs = options?.delaysMs ?? DEFAULT_RETRY_DELAYS_MS;
+  const sleep = options?.sleep ?? sleepBlocking;
+
+  let attempts = 0;
+  let code: string | null = null;
+
+  for (;;) {
+    try {
+      operation();
+      return { attempts: attempts + 1, code };
+    } catch (error) {
+      const transientCode = transientErrorCode(error);
+      if (transientCode === null || attempts >= delaysMs.length) {
+        throw error;
+      }
+      code = transientCode;
+      sleep(delaysMs[attempts] ?? 0);
+      attempts += 1;
+    }
+  }
+}
+
+// ── Module-private ─────────────────────────────────────────────────────────
+
+/**
+ * Three retries, 60 ms of blocking at worst.
+ *
+ * Sized against the two windows it has to fit inside: well under one
+ * `PERMISSION_FORWARDING_POLL_INTERVAL_MS` tick, so a retrying heartbeat write
+ * cannot push the serving node's timer into the next tick, and far under the
+ * grace a forwarding child waits out, so a parent retrying its own writes can
+ * never be the reason a child gives up on it.
+ */
+const DEFAULT_RETRY_DELAYS_MS: readonly number[] = [10, 20, 30];
+
+/**
+ * The errno values a transient lock produces on an otherwise-valid operation.
+ *
+ * This set is the platform gate: `process.platform` is unreadable in `src/`,
+ * and a POSIX host that produces one of these on a rename is in the same
+ * situation a Windows host is — worth one more attempt, and no worse off for
+ * it.
+ */
+const TRANSIENT_FS_ERROR_CODES: ReadonlySet<string> = new Set([
+  "EPERM",
+  "EBUSY",
+  "EACCES",
+]);
+
+/** The transient errno `error` carries, or `null` when retrying cannot help. */
+function transientErrorCode(error: unknown): string | null {
+  if (typeof error !== "object" || error === null || !("code" in error)) {
+    return null;
+  }
+  const { code } = error as { code?: unknown };
+  return typeof code === "string" && TRANSIENT_FS_ERROR_CODES.has(code)
+    ? code
+    : null;
+}
+
+/**
+ * Block the calling thread for `ms`.
+ *
+ * Synchronous because every caller is: the heartbeat publish satisfies a
+ * `void` seam a timer drives. `Atomics.wait` on a never-notified buffer is the
+ * standard blocking sleep and is permitted on Node's main thread.
+ *
+ * The buffer is module-scoped — which persists across same-cwd session
+ * switches — and that is safe here precisely because nothing ever writes to
+ * it: every wait sees the initial zero and times out.
+ */
+const SLEEP_BUFFER = new Int32Array(new SharedArrayBuffer(4));
+
+function sleepBlocking(ms: number): void {
+  Atomics.wait(SLEEP_BUFFER, 0, 0, ms);
+}

package/src/handlers/gates/descriptor.ts

@@ -97,6 +97,81 @@ export interface GateBypass {
 /** Union of possible gate function return values. */
 export type GateResult = GateDescriptor | GateBypass | null;
 
+// ── Resolved-state readers ─────────────────────────────────────────────────
+
+/**
+ * The permission check a descriptor already carries, or `null` when it
+ * resolves nothing of its own.
+ *
+ * Every tool-call gate resolves its own state before the runner sees it —
+ * five of the six stamp a full `preCheck`, and the skill-read gate stamps the
+ * `preResolved` state it read off the matched skill entry. This is the one
+ * place that precedence is expressed, so the runner and the pre-emption
+ * predicate cannot answer it differently.
+ *
+ * A `null` answer is not "allow": it means the caller must resolve the
+ * descriptor itself.
+ */
+export function preResolvedCheckOf(
+  descriptor: GateDescriptor,
+): PermissionCheckResult | null {
+  if (descriptor.preCheck) {
+    return descriptor.preCheck;
+  }
+  if (descriptor.preResolved) {
+    return {
+      state: descriptor.preResolved.state,
+      toolName: descriptor.surface,
+      source: "tool",
+      origin: "builtin",
+    };
+  }
+  return null;
+}
+
+/**
+ * Whether this gate blocks without escalating, whatever the other gates say.
+ *
+ * A `deny` is absorbing: wherever it sits in the pipeline's order, the call is
+ * refused, so no other gate's answer — and no human's — can change the
+ * outcome. That is what makes running it first an ordering change rather than
+ * a semantic one, and it is why the same treatment is *not* extended to `ask`
+ * (#915): two asking gates ask two different questions.
+ *
+ * Subordinate to {@link GateRunner.runDescriptor}'s own precedence, which
+ * tests `source === "session"` before the deny/ask/allow gate is reached — a
+ * session-sourced check is allowed there, so it is not pre-emptive here.
+ * `SessionRules` records only allows, so that combination is unreachable
+ * today; the clause is kept so the predicate is correct on its own terms
+ * rather than by way of a distant invariant, and it errs toward today's
+ * behavior by declining to pre-empt.
+ *
+ * Yolo needs no clause: `resolveYoloGrant` matches an `allow` of origin
+ * `yolo` and an `ask`, never a `deny`.
+ */
+export function isUnconditionalDeny(gate: GateResult): boolean {
+  if (!isGateDescriptor(gate)) {
+    return false;
+  }
+  const check = preResolvedCheckOf(gate);
+  return check !== null && check.state === "deny" && check.source !== "session";
+}
+
+/**
+ * The gates in run order, with any unconditional deny moved to the front.
+ *
+ * A stable partition, so two denying gates keep their relative order (the
+ * earlier one still decides, exactly as before) and the remainder keeps its
+ * own. With no deny present the array is returned unchanged.
+ */
+export function orderDenyFirst(gates: GateResult[]): GateResult[] {
+  const denying = gates.filter((gate) => isUnconditionalDeny(gate));
+  if (denying.length === 0) {
+    return gates;
+  }
+  return [...denying, ...gates.filter((gate) => !isUnconditionalDeny(gate))];
+}
+
 // ── Type guard helpers ─────────────────────────────────────────────────────
 
 /** Check whether a GateResult is a GateBypass (early allow). */

package/src/handlers/gates/runner.ts

@@ -12,13 +12,12 @@ import {
 } from "#src/presentation/agent-renderer";
 import { renderReviewLogFacts } from "#src/presentation/review-log-renderer";
 import type { SessionApprovalRecorder } from "#src/session/session-approval-recorder";
-import type { PermissionCheckResult } from "#src/types";
 import type {
   DecisionEventFacts,
   GateDescriptor,
   GateResult,
 } from "./descriptor";
-import { isGateBypass } from "./descriptor";
+import { isGateBypass, preResolvedCheckOf } from "./descriptor";
 import { buildDecisionEvent, resolveYoloGrant } from "./helpers";
 import type { GateOutcome } from "./types";
 
@@ -89,25 +88,16 @@ export class GateRunner {
     agentName: string | null,
     requestId: string,
   ): Promise<GateOutcome> {
-    // 1. Resolve permission state — pre-check, pre-resolved, or via resolver
-    let check: PermissionCheckResult;
-    if (descriptor.preCheck) {
-      check = descriptor.preCheck;
-    } else if (descriptor.preResolved) {
-      check = {
-        state: descriptor.preResolved.state,
-        toolName: descriptor.surface,
-        source: "tool",
-        origin: "builtin",
-      };
-    } else {
-      check = this.resolver.resolve({
+    // 1. Resolve permission state — what the descriptor already carries, or
+    // via the resolver when it carries nothing.
+    const check =
+      preResolvedCheckOf(descriptor) ??
+      this.resolver.resolve({
         kind: "tool",
         surface: descriptor.surface,
         input: descriptor.input,
         agentName: agentName ?? undefined,
       });
-    }
 
     // The fields every review-log write for this gate shares, whatever the
     // resolution — built once so a field added here reaches all of them. The

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

@@ -18,7 +18,7 @@ import type { PermissionCheckResult } from "#src/types";
 import { resolveBashCommandCheck } from "./bash-command";
 import { describeBashExternalDirectoryGate } from "./bash-external-directory";
 import { describeBashPathGate } from "./bash-path";
-import type { GateResult } from "./descriptor";
+import { type GateResult, orderDenyFirst } from "./descriptor";
 import { describeExternalDirectoryGate } from "./external-directory";
 import { describePathGate } from "./path";
 import type { GateRunner } from "./runner";
@@ -62,7 +62,8 @@ export interface ToolCallGateInputs {
  * - `ToolPreviewFormatter` construction from `getToolPreviewLimits()`
  * - infrastructure-dir list from `getInfrastructureReadDirs()`
  * - all six gate producers in their prescribed order
- * - the run loop that returns the first block outcome, or allow
+ * - the run loop, which runs an unconditionally denying gate ahead of the
+ *   rest and returns the first block outcome, or allow
  */
 export class ToolCallGatePipeline {
   constructor(
@@ -141,8 +142,18 @@ export class ToolCallGatePipeline {
       },
     ];
 
+    // Produce every gate before running any of them, so an unconditional deny
+    // on a later gate is known before an earlier one suspends the call on an
+    // `ask` nobody's answer could change (#899). Producing is side-effect-free
+    // — all logging and event emission happens inside `runner.run` — and the
+    // loop below already produced every gate on any call it did not block.
+    const gates: GateResult[] = [];
     for (const produce of gateProducers) {
-      const outcome = await runner.run(await produce(), tcc.agentName);
+      gates.push(await produce());
+    }
+
+    for (const gate of orderDenyFirst(gates)) {
+      const outcome = await runner.run(gate, tcc.agentName);
       if (outcome.action === "block") {
         return outcome;
       }