@gotgenes/pi-permission-system 13.0.0 → 13.1.1

package/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [13.1.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v13.1.0...pi-permission-system-v13.1.1) (2026-06-13)
+
+
+### Bug Fixes
+
+* preserve forwarded-permission responses dir while requests pending ([#398](https://github.com/gotgenes/pi-packages/issues/398)) ([9914e70](https://github.com/gotgenes/pi-packages/commit/9914e7093c5addee80bd39f2ff99211991b4a238))
+* recreate forwarded-permission responses dir before write ([#398](https://github.com/gotgenes/pi-packages/issues/398)) ([67d34ef](https://github.com/gotgenes/pi-packages/commit/67d34efb33dbda28f363a004d0945c2a4aacea29))
+
+## [13.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v13.0.0...pi-permission-system-v13.1.0) (2026-06-13)
+
+
+### Features
+
+* **pi-permission-system:** add DenyWithReason type and shared guard ([51750e1](https://github.com/gotgenes/pi-packages/commit/51750e188592520798eaf9676a15a709a779cf96)), closes [#395](https://github.com/gotgenes/pi-packages/issues/395)
+* **pi-permission-system:** append custom reason to denial messages ([d8e5756](https://github.com/gotgenes/pi-packages/commit/d8e575632678b806d381f1436dbb06197d742104)), closes [#395](https://github.com/gotgenes/pi-packages/issues/395)
+* **pi-permission-system:** build deny rules with reason in normalizeFlatConfig ([186c15a](https://github.com/gotgenes/pi-packages/commit/186c15a74944bc2800bcea738984021169fabc8d)), closes [#395](https://github.com/gotgenes/pi-packages/issues/395)
+* **pi-permission-system:** preserve deny-with-reason from JSON config ([3201bfd](https://github.com/gotgenes/pi-packages/commit/3201bfd55d68aac1ee87ac452723f6d0783dba6d)), closes [#395](https://github.com/gotgenes/pi-packages/issues/395)
+* **pi-permission-system:** thread deny reason into PermissionCheckResult ([ed712e4](https://github.com/gotgenes/pi-packages/commit/ed712e47458a662e3d1159e2f5096c709ab2ddf5)), closes [#395](https://github.com/gotgenes/pi-packages/issues/395)
+
+
+### Documentation
+
+* **pi-permission-system:** document deny-with-reason config form ([45be4e7](https://github.com/gotgenes/pi-packages/commit/45be4e72c0ca43040cb0f55ca196a0cab0b9fc14)), closes [#395](https://github.com/gotgenes/pi-packages/issues/395)
+
 ## [13.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v12.0.0...pi-permission-system-v13.0.0) (2026-06-12)
 
 

package/config/config.example.json

@@ -25,7 +25,8 @@
       "*": "ask",
       "git *": "ask",
       "git status": "allow",
-      "git diff": "allow"
+      "git diff": "allow",
+      "npm *": { "action": "deny", "reason": "Use pnpm instead" }
     },
     "mcp": { "*": "ask", "mcp_status": "allow", "mcp_list": "allow" },
     "skill": { "*": "ask" },

package/package.json

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

package/schemas/permissions.schema.json

@@ -125,8 +125,34 @@
         "minLength": 1
       },
       "additionalProperties": {
-        "$ref": "#/$defs/permissionState"
+        "oneOf": [
+          {
+            "$ref": "#/$defs/permissionState",
+            "description": "A permission decision for this pattern."
+          },
+          {
+            "$ref": "#/$defs/denyWithReason",
+            "description": "Deny this pattern with an optional custom reason."
+          }
+        ]
       }
+    },
+    "denyWithReason": {
+      "type": "object",
+      "description": "Deny with an optional custom reason shown to the agent when the action is blocked.",
+      "properties": {
+        "action": {
+          "const": "deny",
+          "description": "The permission decision \u2014 must be \"deny\"."
+        },
+        "reason": {
+          "type": "string",
+          "maxLength": 500,
+          "description": "Optional reason shown to the agent when this action is denied."
+        }
+      },
+      "required": ["action"],
+      "additionalProperties": false
     }
   }
 }

package/src/common.ts

@@ -1,4 +1,4 @@
-import type { PermissionState } from "./types";
+import type { DenyWithReason, PermissionState } from "./types";
 
 export function toRecord(value: unknown): Record<string, unknown> {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -38,6 +38,22 @@ export function isPermissionState(value: unknown): value is PermissionState {
   return value === "allow" || value === "deny" || value === "ask";
 }
 
+/**
+ * Narrow type guard: a raw value representing a DenyWithReason object.
+ * Accepts `{ action: "deny" }` and `{ action: "deny", reason: "…" }`.
+ * Rejects a non-string `reason` to keep malformed config out of the rule set.
+ */
+export function isDenyWithReason(value: unknown): value is DenyWithReason {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const record = value as Record<string, unknown>;
+  return (
+    record.action === "deny" &&
+    (record.reason === undefined || typeof record.reason === "string")
+  );
+}
+
 type StackNode = { indent: number; target: Record<string, unknown> };
 
 export function parseSimpleYamlMap(input: string): Record<string, unknown> {

package/src/config-loader.ts

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { normalize } from "node:path";
-
 import {
+  isDenyWithReason,
   isPermissionState,
   normalizeOptionalPositiveInt,
   normalizeOptionalStringArray,
@@ -15,7 +15,7 @@ import {
   getProjectConfigPath,
 } from "./config-paths";
 import { mergeFlatPermissions } from "./permission-merge";
-import type { FlatPermissionConfig } from "./types";
+import type { FlatPermissionConfig, PatternValue } from "./types";
 
 /**
  * Unified config shape combining runtime knobs and flat permission policy.
@@ -127,7 +127,8 @@ function normalizeOptionalBoolean(value: unknown): boolean | undefined {
 
 /**
  * Normalize a raw `permission` value from parsed JSON into a FlatPermissionConfig.
- * Drops non-object top-level values, invalid PermissionState strings, and
+ * Accepts PermissionState strings and DenyWithReason objects inside pattern
+ * maps. Drops non-object top-level values, invalid PermissionState strings, and
  * invalid action values inside object maps.
  */
 function normalizeFlatPermissionValue(
@@ -147,12 +148,15 @@ function normalizeFlatPermissionValue(
         hasAny = true;
       }
     } else if (typeof val === "object" && val !== null && !Array.isArray(val)) {
-      const map: Record<string, import("./types").PermissionState> = {};
+      const map: Record<string, PatternValue> = {};
       let mapHasAny = false;
       for (const [pattern, action] of Object.entries(
         val as Record<string, unknown>,
       )) {
-        if (isPermissionState(action)) {
+        if (isDenyWithReason(action)) {
+          map[pattern] = action;
+          mapHasAny = true;
+        } else if (isPermissionState(action)) {
           map[pattern] = action;
           mapHasAny = true;
         }

package/src/denial-messages.ts

@@ -126,7 +126,8 @@ function buildToolDenyBody(
     parts.push(qualifier);
   }
 
-  return `${parts.join(" ")}.`;
+  // reasonSuffix appends ` Reason: <reason>.` after the sentence-ending period.
+  return `${parts.join(" ")}.${reasonSuffix(check.reason)}`;
 }
 
 /**

package/src/forwarded-permissions/io.ts

@@ -175,13 +175,20 @@ export function getExistingPermissionForwardingLocation(
   return existsSync(location.requestsDir) ? location : null;
 }
 
+/**
+ * Attempt to remove a directory if it is empty.
+ *
+ * Returns `true` when the directory is absent after the call (successfully
+ * removed, or never existed).  Returns `false` when the directory still exists
+ * (non-empty, or a filesystem error prevented removal).
+ */
 export function tryRemoveDirectoryIfEmpty(
   logger: DebugReviewLogger | null,
   path: string,
   description: string,
-): void {
+): boolean {
   if (!existsSync(path)) {
-    return;
+    return true;
   }
 
   let entries: string[];
@@ -193,18 +200,22 @@ export function tryRemoveDirectoryIfEmpty(
       `Failed to inspect ${description} directory '${path}'`,
       error,
     );
-    return;
+    return false;
   }
 
   if (entries.length > 0) {
-    return;
+    return false;
   }
 
   try {
     rmdirSync(path);
+    return true;
   } catch (error) {
-    if (isErrnoCode(error, "ENOENT") || isErrnoCode(error, "ENOTEMPTY")) {
-      return;
+    if (isErrnoCode(error, "ENOENT")) {
+      return true;
+    }
+    if (isErrnoCode(error, "ENOTEMPTY")) {
+      return false;
     }
 
     logPermissionForwardingWarning(
@@ -212,6 +223,7 @@ export function tryRemoveDirectoryIfEmpty(
       `Failed to remove empty ${description} directory '${path}'`,
       error,
     );
+    return false;
   }
 }
 
@@ -219,16 +231,20 @@ export function cleanupPermissionForwardingLocationIfEmpty(
   logger: DebugReviewLogger | null,
   location: PermissionForwardingLocation,
 ): void {
-  tryRemoveDirectoryIfEmpty(
+  // Only remove responses/ when requests/ is already gone — removing responses/
+  // while a request is still pending causes the ENOENT write loop (issue #398).
+  const requestsGone = tryRemoveDirectoryIfEmpty(
     logger,
     location.requestsDir,
     `${location.label} permission forwarding requests`,
   );
-  tryRemoveDirectoryIfEmpty(
-    logger,
-    location.responsesDir,
-    `${location.label} permission forwarding responses`,
-  );
+  if (requestsGone) {
+    tryRemoveDirectoryIfEmpty(
+      logger,
+      location.responsesDir,
+      `${location.label} permission forwarding responses`,
+    );
+  }
   tryRemoveDirectoryIfEmpty(
     logger,
     location.sessionRootDir,

package/src/forwarded-permissions/permission-forwarder.ts

@@ -35,6 +35,7 @@ import { shouldAutoApprovePermissionState } from "#src/yolo-mode";
 
 import {
   cleanupPermissionForwardingLocationIfEmpty,
+  ensureDirectoryExists,
   ensurePermissionForwardingLocation,
   getExistingPermissionForwardingLocation,
   listRequestFiles,
@@ -255,6 +256,20 @@ export class PermissionForwarder implements ApprovalRequester, InboxProcessor {
       return;
     }
 
+    // Defensively recreate responses/ before writing any response — a
+    // concurrent cleanup pass may have removed it between the requestsDir
+    // existence check above and the write inside processSingleForwardedRequest
+    // (the ENOENT write loop reported in issue #398).
+    if (
+      !ensureDirectoryExists(
+        this.logger,
+        location.responsesDir,
+        "permission forwarding responses",
+      )
+    ) {
+      return;
+    }
+
     for (const fileName of requestFiles) {
       const requestPath = join(location.requestsDir, fileName);
       const request = readForwardedPermissionRequest(this.logger, requestPath);

package/src/normalize.ts

@@ -1,4 +1,4 @@
-import { isPermissionState } from "./common";
+import { isDenyWithReason, isPermissionState } from "./common";
 import type { Rule, Ruleset } from "./rule";
 import type { FlatPermissionConfig } from "./types";
 
@@ -7,6 +7,8 @@ import type { FlatPermissionConfig } from "./types";
  *
  * Each key is a surface name. A string value is shorthand for
  * `{ "*": action }`. An object value maps patterns to actions.
+ * A pattern value may be a PermissionState string or a `DenyWithReason`
+ * object (`{ action: "deny", reason?: string }`).
  * Invalid action values are silently skipped.
  *
  * The universal fallback key `"*"` is included if present — callers
@@ -23,7 +25,15 @@ export function normalizeFlatConfig(permission: FlatPermissionConfig): Ruleset {
       // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- defensive null check; value type does not include null but runtime JSON may
     } else if (typeof value === "object" && value !== null) {
       for (const [pattern, action] of Object.entries(value)) {
-        if (isPermissionState(action)) {
+        if (isDenyWithReason(action)) {
+          rules.push({
+            surface,
+            pattern,
+            action: "deny",
+            reason: action.reason,
+            origin: "builtin",
+          });
+        } else if (isPermissionState(action)) {
           rules.push({ surface, pattern, action, origin: "builtin" });
         }
       }

package/src/permission-manager.ts

@@ -322,6 +322,7 @@ function buildCheckResult(
   return {
     toolName,
     state: rule.action,
+    reason: rule.reason,
     matchedPattern:
       rule.layer === "config" || rule.layer === "session"
         ? rule.pattern

package/src/rule.ts

@@ -27,6 +27,8 @@ export interface Rule {
   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.

package/src/types.ts

@@ -4,14 +4,27 @@ import type { RuleOrigin } from "./rule";
 
 export type { RuleOrigin };
 
+/**
+ * A deny action with an optional reason annotation, used when a pattern maps
+ * to an object instead of a plain PermissionState string.
+ */
+export interface DenyWithReason {
+  action: "deny";
+  reason?: string;
+}
+
+/** A pattern value: a PermissionState string OR a DenyWithReason object. */
+export type PatternValue = PermissionState | DenyWithReason;
+
 /**
  * The on-disk permission shape inside the `"permission"` key.
- * Each key is a surface name; values are either a PermissionState string
- * (shorthand for `{ "*": action }`) or a pattern→action map.
+ * A surface value is a PermissionState string (shorthand for `{ "*": action }`)
+ * or a pattern→value map. Pattern values may be a PermissionState string or a
+ * DenyWithReason object. A top-level value is never a bare DenyWithReason.
  */
 export type FlatPermissionConfig = Record<
   string,
-  PermissionState | Record<string, PermissionState>
+  PermissionState | Record<string, PatternValue>
 >;
 
 /**
@@ -34,6 +47,8 @@ export type BashCommandContext =
 export interface PermissionCheckResult {
   toolName: string;
   state: PermissionState;
+  /** Custom denial reason from a deny-with-reason pattern, when present. */
+  reason?: string;
   matchedPattern?: string;
   command?: string;
   target?: string;

package/test/common.test.ts

@@ -3,6 +3,7 @@ import { afterEach, describe, expect, it, test, vi } from "vitest";
 import {
   extractFrontmatter,
   getNonEmptyString,
+  isDenyWithReason,
   isPermissionState,
   normalizeOptionalPositiveInt,
   normalizeOptionalStringArray,
@@ -102,6 +103,33 @@ describe("isPermissionState", () => {
   });
 });
 
+describe("isDenyWithReason", () => {
+  test("returns true for { action: 'deny' } without a reason", () => {
+    expect(isDenyWithReason({ action: "deny" })).toBe(true);
+  });
+
+  test("returns true for { action: 'deny', reason: '...' }", () => {
+    expect(isDenyWithReason({ action: "deny", reason: "Use pnpm" })).toBe(true);
+  });
+
+  test("returns false for non-deny actions", () => {
+    expect(isDenyWithReason({ action: "allow" })).toBe(false);
+    expect(isDenyWithReason({ action: "ask" })).toBe(false);
+  });
+
+  test("returns false for a non-string reason", () => {
+    expect(isDenyWithReason({ action: "deny", reason: 42 })).toBe(false);
+    expect(isDenyWithReason({ action: "deny", reason: null })).toBe(false);
+  });
+
+  test("returns false for non-object types", () => {
+    expect(isDenyWithReason(null)).toBe(false);
+    expect(isDenyWithReason(undefined)).toBe(false);
+    expect(isDenyWithReason("deny")).toBe(false);
+    expect(isDenyWithReason(["deny"])).toBe(false);
+  });
+});
+
 describe("extractFrontmatter", () => {
   test("returns empty string when no frontmatter delimiter", () => {
     expect(extractFrontmatter("# Hello\nSome content")).toBe("");

package/test/config-loader.test.ts

@@ -243,6 +243,49 @@ describe("loadUnifiedConfig", () => {
     });
   });
 
+  it("preserves a deny-with-reason object inside a pattern map", () => {
+    const configPath = join(tempDir, "config.json");
+    writeFileSync(
+      configPath,
+      JSON.stringify({
+        permission: {
+          bash: {
+            "git *": "allow",
+            "npm *": { action: "deny", reason: "Use pnpm instead" },
+          },
+        },
+      }),
+    );
+
+    const result = loadUnifiedConfig(configPath);
+    expect(result.config.permission).toEqual({
+      bash: {
+        "git *": "allow",
+        "npm *": { action: "deny", reason: "Use pnpm instead" },
+      },
+    });
+  });
+
+  it("strips a deny object with a non-string reason (malformed)", () => {
+    const configPath = join(tempDir, "config.json");
+    writeFileSync(
+      configPath,
+      JSON.stringify({
+        permission: {
+          bash: {
+            "git *": "allow",
+            "npm *": { action: "deny", reason: 42 },
+          },
+        },
+      }),
+    );
+
+    const result = loadUnifiedConfig(configPath);
+    expect(result.config.permission).toEqual({
+      bash: { "git *": "allow" },
+    });
+  });
+
   it("returns no permission when the permission field is absent", () => {
     const configPath = join(tempDir, "config.json");
     writeFileSync(configPath, JSON.stringify({ debugLog: false }));

package/test/denial-messages.test.ts

@@ -114,6 +114,67 @@ describe("formatDenyReason", () => {
       );
     });
 
+    test("bash with a custom reason appended after the period", () => {
+      expect(
+        formatDenyReason(
+          toolCtx(
+            toolCheck("bash", {
+              command: "npm install",
+              matchedPattern: "npm *",
+              reason: "Use pnpm instead",
+            }),
+          ),
+        ),
+      ).toBe(
+        "[pi-permission-system] is not permitted to run 'bash' command 'npm install' (matched 'npm *'). Reason: Use pnpm instead.",
+      );
+    });
+
+    test("custom reason with no matched pattern", () => {
+      expect(
+        formatDenyReason(
+          toolCtx(
+            toolCheck("write", {
+              reason: "Write access is disabled for security",
+            }),
+          ),
+        ),
+      ).toBe(
+        "[pi-permission-system] is not permitted to run 'write'. Reason: Write access is disabled for security.",
+      );
+    });
+
+    test("custom reason is included alongside the agent name", () => {
+      expect(
+        formatDenyReason(
+          toolCtx(
+            toolCheck("bash", {
+              command: "yarn build",
+              matchedPattern: "yarn *",
+              reason: "Use pnpm instead",
+            }),
+            "dev-agent",
+          ),
+        ),
+      ).toBe(
+        "[pi-permission-system] Agent 'dev-agent' is not permitted to run 'bash' command 'yarn build' (matched 'yarn *'). Reason: Use pnpm instead.",
+      );
+    });
+
+    test("custom reason on an MCP target", () => {
+      expect(
+        formatDenyReason(
+          toolCtx(
+            mcpCheck("server:deploy", {
+              reason: "Deploy requires approval from a senior engineer",
+            }),
+          ),
+        ),
+      ).toBe(
+        "[pi-permission-system] is not permitted to run MCP target 'server:deploy'. Reason: Deploy requires approval from a senior engineer.",
+      );
+    });
+
     test("MCP source with target on non-mcp toolName", () => {
       expect(
         formatDenyReason(

package/test/forwarded-permissions/io.test.ts

@@ -1,11 +1,24 @@
-import { describe, expect, it, vi } from "vitest";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, describe, expect, it, vi } from "vitest";
 
 import {
+  cleanupPermissionForwardingLocationIfEmpty,
   formatUnknownErrorMessage,
   isErrnoCode,
   logPermissionForwardingError,
   logPermissionForwardingWarning,
+  tryRemoveDirectoryIfEmpty,
 } from "#src/forwarded-permissions/io";
+import { createPermissionForwardingLocation } from "#src/permission-forwarding";
 import type { DebugReviewLogger } from "#src/session-logger";
 
 // ── helpers ────────────────────────────────────────────────────────────────
@@ -130,3 +143,109 @@ describe("logPermissionForwardingError", () => {
     expect(() => logPermissionForwardingError(null, "ignored")).not.toThrow();
   });
 });
+
+// ── tryRemoveDirectoryIfEmpty ──────────────────────────────────────────────
+
+describe("tryRemoveDirectoryIfEmpty", () => {
+  let root: string;
+
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it("returns true when the directory does not exist", () => {
+    root = mkdtempSync(join(tmpdir(), "io-test-"));
+    const absent = join(root, "nonexistent");
+    expect(tryRemoveDirectoryIfEmpty(null, absent, "test")).toBe(true);
+  });
+
+  it("returns true and removes an empty directory", () => {
+    root = mkdtempSync(join(tmpdir(), "io-test-"));
+    const dir = join(root, "empty");
+    mkdirSync(dir);
+    expect(tryRemoveDirectoryIfEmpty(null, dir, "test")).toBe(true);
+    expect(existsSync(dir)).toBe(false);
+  });
+
+  it("returns false and leaves a non-empty directory in place", () => {
+    root = mkdtempSync(join(tmpdir(), "io-test-"));
+    const dir = join(root, "nonempty");
+    mkdirSync(dir);
+    writeFileSync(join(dir, "file.json"), "{}", "utf-8");
+    expect(tryRemoveDirectoryIfEmpty(null, dir, "test")).toBe(false);
+    expect(existsSync(dir)).toBe(true);
+  });
+});
+
+// ── cleanupPermissionForwardingLocationIfEmpty ─────────────────────────────
+
+describe("cleanupPermissionForwardingLocationIfEmpty", () => {
+  let root: string;
+
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it("preserves responses/ when requests/ is non-empty (the concurrent-request race)", () => {
+    root = mkdtempSync(join(tmpdir(), "io-cleanup-"));
+    const forwardingDir = join(root, "forwarding");
+    const location = createPermissionForwardingLocation(
+      forwardingDir,
+      "parent-session",
+    );
+    // Simulate: requests/ has a pending file, responses/ is momentarily empty
+    mkdirSync(location.requestsDir, { recursive: true });
+    mkdirSync(location.responsesDir, { recursive: true });
+    writeFileSync(join(location.requestsDir, "req-b.json"), "{}", "utf-8");
+    // responses/ is empty (sibling subagent A already cleaned up its response)
+
+    cleanupPermissionForwardingLocationIfEmpty(null, location);
+
+    // requests/ is non-empty → should NOT be removed
+    expect(existsSync(location.requestsDir)).toBe(true);
+    // responses/ must survive — removing it causes the ENOENT write loop
+    expect(existsSync(location.responsesDir)).toBe(true);
+    // sessionRoot must also survive while subdirs are present
+    expect(existsSync(location.sessionRootDir)).toBe(true);
+  });
+
+  it("removes both subdirs and sessionRoot when both are empty (normal serial cleanup)", () => {
+    root = mkdtempSync(join(tmpdir(), "io-cleanup-"));
+    const forwardingDir = join(root, "forwarding");
+    const location = createPermissionForwardingLocation(
+      forwardingDir,
+      "parent-session",
+    );
+    mkdirSync(location.requestsDir, { recursive: true });
+    mkdirSync(location.responsesDir, { recursive: true });
+    // Both empty — normal end-of-lifecycle state
+
+    cleanupPermissionForwardingLocationIfEmpty(null, location);
+
+    expect(existsSync(location.requestsDir)).toBe(false);
+    expect(existsSync(location.responsesDir)).toBe(false);
+    expect(existsSync(location.sessionRootDir)).toBe(false);
+  });
+
+  it("leaves responses/ in place when it is non-empty even if requests/ is empty", () => {
+    root = mkdtempSync(join(tmpdir(), "io-cleanup-"));
+    const forwardingDir = join(root, "forwarding");
+    const location = createPermissionForwardingLocation(
+      forwardingDir,
+      "parent-session",
+    );
+    mkdirSync(location.requestsDir, { recursive: true });
+    mkdirSync(location.responsesDir, { recursive: true });
+    writeFileSync(join(location.responsesDir, "resp.json"), "{}", "utf-8");
+    // requests/ is empty, responses/ has a stale response
+
+    cleanupPermissionForwardingLocationIfEmpty(null, location);
+
+    // requests/ is empty so it gets removed
+    expect(existsSync(location.requestsDir)).toBe(false);
+    // responses/ is non-empty → survives
+    expect(existsSync(location.responsesDir)).toBe(true);
+    // sessionRoot survives because responses/ is still present
+    expect(existsSync(location.sessionRootDir)).toBe(true);
+  });
+});

package/test/normalize.test.ts

@@ -163,4 +163,85 @@ describe("normalizeFlatConfig", () => {
       ]);
     });
   });
+
+  describe("deny with reason", () => {
+    test("{ action: 'deny', reason } produces a deny rule carrying the reason", () => {
+      const result = normalizeFlatConfig({
+        bash: { "npm *": { action: "deny", reason: "Use pnpm instead" } },
+      });
+      expect(result).toEqual([
+        {
+          surface: "bash",
+          pattern: "npm *",
+          action: "deny",
+          reason: "Use pnpm instead",
+          origin: "builtin",
+        },
+      ]);
+    });
+
+    test("{ action: 'deny' } without a reason produces a deny rule without reason", () => {
+      const result = normalizeFlatConfig({
+        bash: { "rm -rf *": { action: "deny" } },
+      });
+      expect(result).toEqual([
+        {
+          surface: "bash",
+          pattern: "rm -rf *",
+          action: "deny",
+          origin: "builtin",
+        },
+      ]);
+    });
+
+    test("deny-with-reason and plain strings coexist in the same surface", () => {
+      const result = normalizeFlatConfig({
+        bash: {
+          "git *": "allow",
+          "npm *": { action: "deny", reason: "Use pnpm" },
+          "*": "ask",
+        },
+      });
+      expect(result).toEqual([
+        {
+          surface: "bash",
+          pattern: "git *",
+          action: "allow",
+          origin: "builtin",
+        },
+        {
+          surface: "bash",
+          pattern: "npm *",
+          action: "deny",
+          reason: "Use pnpm",
+          origin: "builtin",
+        },
+        { surface: "bash", pattern: "*", action: "ask", origin: "builtin" },
+      ]);
+    });
+
+    test("top-level deny-with-reason object is treated as a pattern map", () => {
+      // At the surface level, { action: "deny", reason: "..." } is parsed as a
+      // pattern→action map: "action" is a pattern key with action "deny", and
+      // "reason" maps to a non-PermissionState string that is dropped.
+      const result = normalizeFlatConfig({
+        bash: { action: "deny", reason: "Not allowed" } as never,
+      });
+      expect(result).toEqual([
+        {
+          surface: "bash",
+          pattern: "action",
+          action: "deny",
+          origin: "builtin",
+        },
+      ]);
+    });
+
+    test("non-string reason is rejected (malformed config)", () => {
+      const result = normalizeFlatConfig({
+        bash: { "npm *": { action: "deny", reason: 42 } as never },
+      });
+      expect(result).toEqual([]);
+    });
+  });
 });

package/test/permission-forwarder.test.ts

@@ -307,4 +307,63 @@ describe("processInbox", () => {
       rmSync(root, { recursive: true, force: true });
     }
   });
+
+  test("recreates a missing responses/ directory and still writes the response", async () => {
+    const root = mkdtempSync(join(tmpdir(), "permission-forwarding-"));
+    try {
+      const forwardingDir = join(root, "forwarding");
+      const location = createPermissionForwardingLocation(
+        forwardingDir,
+        "parent-session",
+      );
+      // Simulate the race: requests/ exists with a pending file, but
+      // responses/ was removed by a concurrent cleanup pass.
+      mkdirSync(location.requestsDir, { recursive: true });
+      // Deliberately do NOT create location.responsesDir.
+      writeFileSync(
+        join(location.requestsDir, "req-race.json"),
+        JSON.stringify({
+          id: "req-race",
+          createdAt: Date.now(),
+          requesterSessionId: "child-session",
+          targetSessionId: "parent-session",
+          requesterAgentName: "Explore",
+          message: "Allow read?",
+        }),
+        "utf-8",
+      );
+
+      const logger = { review: vi.fn(), debug: vi.fn() };
+      const requestPermissionDecisionFromUi = vi
+        .fn()
+        .mockResolvedValue({ approved: true, state: "approved" as const });
+
+      const forwarder = new PermissionForwarder(
+        makeDeps({
+          forwardingDir,
+          logger,
+          requestPermissionDecisionFromUi,
+        }),
+      );
+
+      await forwarder.processInbox(
+        makeCtx({
+          hasUI: true,
+          sessionManager: {
+            getSessionId: vi.fn(() => "parent-session"),
+          },
+        }),
+      );
+
+      // processInbox must have recreated responses/ and written a response
+      // file — no permission_forwarding.error should have been logged.
+      expect(logger.review).not.toHaveBeenCalledWith(
+        "permission_forwarding.error",
+        expect.anything(),
+      );
+      expect(requestPermissionDecisionFromUi).toHaveBeenCalled();
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
 });

package/test/permission-manager-unified.test.ts

@@ -1245,6 +1245,71 @@ describe("cross-cutting path surface", () => {
     }
   });
 
+  // ── Deny-with-reason ────────────────────────────────────────────────────
+
+  it("deny-with-reason: reason threads through to PermissionCheckResult", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      bash: { "npm *": { action: "deny", reason: "Use pnpm instead" } },
+    });
+    try {
+      const result = manager.checkPermission("bash", {
+        command: "npm install",
+      });
+      expect(result.state).toBe("deny");
+      expect(result.reason).toBe("Use pnpm instead");
+      expect(result.matchedPattern).toBe("npm *");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("deny-without-reason: reason is undefined in PermissionCheckResult", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      bash: { "rm -rf *": "deny" },
+    });
+    try {
+      const result = manager.checkPermission("bash", { command: "rm -rf /" });
+      expect(result.state).toBe("deny");
+      expect(result.reason).toBeUndefined();
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("deny-with-reason on a non-bash surface", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      read: {
+        "*.env": {
+          action: "deny",
+          reason: "Environment files contain secrets",
+        },
+      },
+    });
+    try {
+      const result = manager.checkPermission("read", { path: ".env" });
+      expect(result.state).toBe("deny");
+      expect(result.reason).toBe("Environment files contain secrets");
+      expect(result.matchedPattern).toBe("*.env");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("non-string reason falls through to the default (malformed config)", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      bash: { "npm *": { action: "deny", reason: 42 } },
+    });
+    try {
+      const result = manager.checkPermission("bash", {
+        command: "npm install",
+      });
+      expect(result.state).toBe("ask");
+      expect(result.reason).toBeUndefined();
+    } finally {
+      cleanup();
+    }
+  });
+
   // ── Last-match-wins ordering ────────────────────────────────────────────
 
   it("last-match-wins: catch-all after deny overrides the deny", () => {

package/test/rule.test.ts

@@ -216,6 +216,67 @@ describe("evaluate", () => {
     expect(result.origin).toBe("builtin");
   });
 
+  test("evaluate() propagates reason from the matched deny rule", () => {
+    const rule: Rule = {
+      surface: "bash",
+      pattern: "npm *",
+      action: "deny",
+      reason: "Use pnpm instead",
+      layer: "config",
+      origin: "global",
+    };
+    const result = evaluate("bash", "npm install", [rule]);
+    expect(result.action).toBe("deny");
+    expect(result.reason).toBe("Use pnpm instead");
+  });
+
+  test("evaluate() carries reason through last-match-wins when deny wins", () => {
+    const allowAll: Rule = {
+      surface: "bash",
+      pattern: "*",
+      action: "allow",
+      layer: "config",
+      origin: "global",
+    };
+    const denyNpm: Rule = {
+      surface: "bash",
+      pattern: "npm *",
+      action: "deny",
+      reason: "Use pnpm",
+      layer: "config",
+      origin: "global",
+    };
+    const result = evaluate("bash", "npm install", [allowAll, denyNpm]);
+    expect(result.action).toBe("deny");
+    expect(result.reason).toBe("Use pnpm");
+  });
+
+  test("evaluate() drops reason when a later allow overrides the deny", () => {
+    const denyNpm: Rule = {
+      surface: "bash",
+      pattern: "npm *",
+      action: "deny",
+      reason: "Use pnpm",
+      layer: "config",
+      origin: "global",
+    };
+    const allowInstall: Rule = {
+      surface: "bash",
+      pattern: "npm install",
+      action: "allow",
+      layer: "config",
+      origin: "global",
+    };
+    const result = evaluate("bash", "npm install", [denyNpm, allowInstall]);
+    expect(result.action).toBe("allow");
+    expect(result.reason).toBeUndefined();
+  });
+
+  test("evaluate() synthetic fallback rule has no reason", () => {
+    const result = evaluate("bash", "npm install", []);
+    expect(result.reason).toBeUndefined();
+  });
+
   test("RuleOrigin covers all seven provenance values", () => {
     const origins: RuleOrigin[] = [
       "global",