@gotgenes/pi-permission-system 6.0.2 → 7.0.1

package/CHANGELOG.md

@@ -5,6 +5,41 @@ 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).
 
+## [7.0.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v7.0.0...pi-permission-system-v7.0.1) (2026-05-21)
+
+
+### Documentation
+
+* **retro:** add retro notes for issue [#78](https://github.com/gotgenes/pi-packages/issues/78) ([594d3e1](https://github.com/gotgenes/pi-packages/commit/594d3e13512facbf4b6241b9a394aca8e59c0707))
+* **retro:** add retro notes for issue [#78](https://github.com/gotgenes/pi-packages/issues/78) ([5f93117](https://github.com/gotgenes/pi-packages/commit/5f93117969524af86b28db979649032e860fc72e))
+
+## [7.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v6.0.2...pi-permission-system-v7.0.0) (2026-05-21)
+
+
+### ⚠ BREAKING CHANGES
+
+* GateDescriptor.messages has been replaced by GateDescriptor.denialContext. Any code constructing a GateDescriptor must provide a DenialContext instead of pre-formatted message strings.
+
+### Features
+
+* add centralized denial message formatter ([#78](https://github.com/gotgenes/pi-packages/issues/78)) ([99f2d36](https://github.com/gotgenes/pi-packages/commit/99f2d362d669dd4d6a6a18365fecd42dd0d77eaa))
+
+
+### Bug Fixes
+
+* remove broken relative links in archived plan 0042 ([07bcca4](https://github.com/gotgenes/pi-packages/commit/07bcca49d506f5726ca96a4b9128b77635e84b7e))
+
+
+### Documentation
+
+* add README to archived plans directory ([c3fcb9f](https://github.com/gotgenes/pi-packages/commit/c3fcb9f7f669c1d25207225e807970eea1c9adc8))
+* archive pre-monorepo plans, plan soften denial messages ([#78](https://github.com/gotgenes/pi-packages/issues/78)) ([7709f8f](https://github.com/gotgenes/pi-packages/commit/7709f8f85a0b7c002a943a222f6005d6069245c1))
+
+
+### Code Refactoring
+
+* remove messages from GateDescriptor ([#78](https://github.com/gotgenes/pi-packages/issues/78)) ([d3cae38](https://github.com/gotgenes/pi-packages/commit/d3cae387ea57c23ede6df27156d1a026aa6b58f2))
+
 ## [6.0.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v6.0.1...pi-permission-system-v6.0.2) (2026-05-20)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "6.0.2",
+  "version": "7.0.1",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {
@@ -57,12 +57,12 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
-    "@earendil-works/pi-coding-agent": ">=0.75.0",
-    "@earendil-works/pi-tui": ">=0.75.0",
+    "@earendil-works/pi-coding-agent": "0.75.4",
+    "@earendil-works/pi-tui": "0.75.4",
     "@types/node": "^22.15.3",
+    "rumdl": "^0.1.93",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.5",
-    "rumdl": "^0.1.93"
+    "vitest": "^4.1.5"
   },
   "dependencies": {
     "tree-sitter-bash": "^0.25.1",

package/src/denial-messages.ts

@@ -0,0 +1,179 @@
+import { EXTENSION_ID } from "./extension-config";
+import type { PermissionCheckResult } from "./types";
+
+// ── Extension attribution tag ──────────────────────────────────────────────
+
+export const EXTENSION_TAG = `[${EXTENSION_ID}]`;
+
+// ── Denial context discriminated union ─────────────────────────────────────
+
+export type DenialContext =
+  | {
+      kind: "tool";
+      check: PermissionCheckResult;
+      agentName?: string;
+      input?: unknown;
+    }
+  | {
+      kind: "path";
+      toolName: string;
+      pathValue: string;
+      agentName?: string;
+    }
+  | {
+      kind: "external_directory";
+      toolName: string;
+      pathValue: string;
+      cwd: string;
+      agentName?: string;
+    }
+  | {
+      kind: "bash_external_directory";
+      command: string;
+      externalPaths: string[];
+      cwd: string;
+      agentName?: string;
+    }
+  | {
+      kind: "bash_path";
+      command: string;
+      pathValue: string;
+      agentName?: string;
+    }
+  | {
+      kind: "skill_read";
+      skillName: string;
+      readPath: string;
+      agentName?: string;
+    };
+
+// ── Public formatter API ───────────────────────────────────────────────────
+
+/** Format the block reason when permission policy denies an operation. */
+export function formatDenyReason(ctx: DenialContext): string {
+  return `${EXTENSION_TAG} ${buildDenyBody(ctx)}`;
+}
+
+/** Format the block reason when no interactive UI is available to prompt. */
+export function formatUnavailableReason(ctx: DenialContext): string {
+  return `${EXTENSION_TAG} ${buildUnavailableBody(ctx)}`;
+}
+
+/** Format the block reason when the user denies at an interactive prompt. */
+export function formatUserDeniedReason(
+  ctx: DenialContext,
+  denialReason?: string,
+): string {
+  return `${EXTENSION_TAG} ${buildUserDeniedBody(ctx, denialReason)}`;
+}
+
+// ── Private body builders ──────────────────────────────────────────────────
+
+function subject(agentName?: string): string {
+  return agentName ? `Agent '${agentName}'` : "Current agent";
+}
+
+function reasonSuffix(denialReason?: string): string {
+  return denialReason ? ` Reason: ${denialReason}.` : "";
+}
+
+function buildDenyBody(ctx: DenialContext): string {
+  switch (ctx.kind) {
+    case "tool":
+      return buildToolDenyBody(ctx);
+    case "path":
+      return `${subject(ctx.agentName)} is not permitted to access path '${ctx.pathValue}' via tool '${ctx.toolName}'.`;
+    case "external_directory":
+      return `${subject(ctx.agentName)} is not permitted to run tool '${ctx.toolName}' for path '${ctx.pathValue}' outside working directory '${ctx.cwd}'.`;
+    case "bash_external_directory":
+      return `${subject(ctx.agentName)} is not permitted to run bash command '${ctx.command}' which references path(s) outside working directory '${ctx.cwd}': ${ctx.externalPaths.join(", ")}.`;
+    case "bash_path":
+      return `${subject(ctx.agentName)} is not permitted to access path '${ctx.pathValue}' via tool 'bash'.`;
+    case "skill_read":
+      return `${subject(ctx.agentName)} is not permitted to access skill '${ctx.skillName}' via '${ctx.readPath}'.`;
+  }
+}
+
+function buildToolDenyBody(
+  ctx: Extract<DenialContext, { kind: "tool" }>,
+): string {
+  const parts: string[] = [];
+  const { check, agentName } = ctx;
+
+  if (agentName) {
+    parts.push(`Agent '${agentName}'`);
+  }
+
+  if (isMcpCheck(check)) {
+    parts.push(`is not permitted to run MCP target '${check.target}'`);
+  } else {
+    parts.push(`is not permitted to run '${check.toolName}'`);
+  }
+
+  if (check.command) {
+    parts.push(`command '${check.command}'`);
+  }
+
+  if (check.matchedPattern) {
+    parts.push(`(matched '${check.matchedPattern}')`);
+  }
+
+  return `${parts.join(" ")}.`;
+}
+
+function buildUnavailableBody(ctx: DenialContext): string {
+  switch (ctx.kind) {
+    case "tool": {
+      const { check } = ctx;
+      if (check.toolName === "bash" && check.command) {
+        return `Running bash command '${check.command}' requires approval, but no interactive UI is available.`;
+      }
+      if (isMcpCheck(check)) {
+        return "Using tool 'mcp' requires approval, but no interactive UI is available.";
+      }
+      return `Using tool '${check.toolName}' requires approval, but no interactive UI is available.`;
+    }
+    case "path":
+      return `Accessing '${ctx.pathValue}' requires approval, but no interactive UI is available.`;
+    case "external_directory":
+      return `Accessing '${ctx.pathValue}' outside the working directory requires approval, but no interactive UI is available.`;
+    case "bash_external_directory":
+      return `Bash command '${ctx.command}' references path(s) outside the working directory and requires approval, but no interactive UI is available.`;
+    case "bash_path":
+      return `Bash command '${ctx.command}' accesses path '${ctx.pathValue}' which requires approval, but no interactive UI is available.`;
+    case "skill_read":
+      return `Accessing skill '${ctx.skillName}' requires approval, but no interactive UI is available.`;
+  }
+}
+
+function buildUserDeniedBody(
+  ctx: DenialContext,
+  denialReason?: string,
+): string {
+  switch (ctx.kind) {
+    case "tool": {
+      const { check } = ctx;
+      if (isMcpCheck(check)) {
+        return `User denied MCP target '${check.target}'.${reasonSuffix(denialReason)}`;
+      }
+      if (check.toolName === "bash" && check.command) {
+        return `User denied bash command '${check.command}'.${reasonSuffix(denialReason)}`;
+      }
+      return `User denied tool '${check.toolName}'.${reasonSuffix(denialReason)}`;
+    }
+    case "path":
+      return `User denied access to path '${ctx.pathValue}'.${reasonSuffix(denialReason)}`;
+    case "external_directory":
+      return `User denied external directory access for tool '${ctx.toolName}' path '${ctx.pathValue}'.${reasonSuffix(denialReason)}`;
+    case "bash_external_directory":
+      return `User denied external directory access for bash command '${ctx.command}'.${reasonSuffix(denialReason)}`;
+    case "bash_path":
+      return `User denied path access for bash command '${ctx.command}' (path '${ctx.pathValue}').${reasonSuffix(denialReason)}`;
+    case "skill_read":
+      return `User denied access to skill '${ctx.skillName}'.${reasonSuffix(denialReason)}`;
+  }
+}
+
+function isMcpCheck(check: PermissionCheckResult): boolean {
+  return (check.source === "mcp" || check.toolName === "mcp") && !!check.target;
+}

package/src/handlers/gates/bash-external-directory.ts

@@ -4,11 +4,7 @@ import { deriveApprovalPattern } from "../../session-rules";
 import type { PermissionCheckResult } from "../../types";
 import { extractExternalPathsFromBashCommand } from "./bash-path-extractor";
 import type { GateResult } from "./descriptor";
-import {
-  formatBashExternalDirectoryAskPrompt,
-  formatBashExternalDirectoryDenyReason,
-  formatExternalDirectoryHardStopHint,
-} from "./external-directory-messages";
+import { formatBashExternalDirectoryAskPrompt } from "./external-directory-messages";
 import type { ToolCallContext } from "./types";
 
 /** Function type for checkPermission used by the descriptor factory. */
@@ -92,20 +88,12 @@ export async function describeBashExternalDirectoryGate(
   return {
     surface: "external_directory",
     input: {},
-    messages: {
-      denyReason: formatBashExternalDirectoryDenyReason(
-        command,
-        uncoveredPaths,
-        tcc.cwd,
-        tcc.agentName ?? undefined,
-      ),
-      unavailableReason: `Bash command '${command}' references path(s) outside the working directory and requires approval, but no interactive UI is available.`,
-      userDeniedReason: (decision) => {
-        const reasonSuffix = decision.denialReason
-          ? ` Reason: ${decision.denialReason}.`
-          : "";
-        return `User denied external directory access for bash command '${command}'.${reasonSuffix} ${formatExternalDirectoryHardStopHint()}`;
-      },
+    denialContext: {
+      kind: "bash_external_directory",
+      command,
+      externalPaths: uncoveredPaths,
+      cwd: tcc.cwd,
+      agentName: tcc.agentName ?? undefined,
     },
     sessionApproval: {
       surface: "external_directory",

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

@@ -4,7 +4,7 @@ import { deriveApprovalPattern } from "../../session-rules";
 import type { PermissionCheckResult } from "../../types";
 import { extractTokensForPathRules } from "./bash-path-extractor";
 import type { GateResult } from "./descriptor";
-import { formatPathAskPrompt, formatPathDenyReason } from "./path";
+import { formatPathAskPrompt } from "./path";
 import type { ToolCallContext } from "./types";
 
 /** Function type for checkPermission used by the descriptor factory. */
@@ -111,19 +111,11 @@ export async function describeBashPathGate(
   return {
     surface: "path",
     input: { path: worstToken },
-    messages: {
-      denyReason: formatPathDenyReason(
-        tcc.toolName,
-        worstToken,
-        tcc.agentName ?? undefined,
-      ),
-      unavailableReason: `Bash command '${command}' accesses path '${worstToken}' which requires approval, but no interactive UI is available.`,
-      userDeniedReason: (decision) => {
-        const reasonSuffix = decision.denialReason
-          ? ` Reason: ${decision.denialReason}.`
-          : "";
-        return `User denied path access for bash command '${command}' (path '${worstToken}').${reasonSuffix} Hard stop: this path permission denial is policy-enforced. Do not retry this path, do not attempt a filesystem bypass, and report the block to the user.`;
-      },
+    denialContext: {
+      kind: "bash_path",
+      command,
+      pathValue: worstToken,
+      agentName: tcc.agentName ?? undefined,
     },
     sessionApproval: {
       surface: "path",

package/src/handlers/gates/descriptor.ts

@@ -1,8 +1,6 @@
+import type { DenialContext } from "../../denial-messages";
 import type { PermissionPromptDecision } from "../../permission-dialog";
-import type {
-  PermissionDecisionEvent,
-  PermissionDecisionResolution,
-} from "../../permission-events";
+import type { PermissionDecisionEvent } from "../../permission-events";
 import type { PromptPermissionDetails } from "../../permission-prompter";
 import type { Rule } from "../../rule";
 import type { PermissionCheckResult, PermissionState } from "../../types";
@@ -21,12 +19,8 @@ export interface GateDescriptor {
   surface: string;
   /** Input passed to checkPermission. */
   input: unknown;
-  /** Message strings/factories for each outcome. */
-  messages: {
-    denyReason: string;
-    unavailableReason: string;
-    userDeniedReason: (decision: PermissionPromptDecision) => string;
-  };
+  /** Structured denial context — the runner formats messages from this. */
+  denialContext: DenialContext;
   /**
    * Session-approval suggestion for "for this session" option.
    * Single pattern or multiple patterns (bash external-directory gate).

package/src/handlers/gates/external-directory-messages.ts

@@ -1,7 +1,3 @@
-export function formatExternalDirectoryHardStopHint(): string {
-  return "Hard stop: this external directory permission denial is policy-enforced. Do not retry this path, do not attempt a filesystem bypass, and report the block to the user.";
-}
-
 export function formatExternalDirectoryAskPrompt(
   toolName: string,
   pathValue: string,
@@ -12,25 +8,6 @@ export function formatExternalDirectoryAskPrompt(
   return `${subject} requested tool '${toolName}' for path '${pathValue}' outside working directory '${cwd}'. Allow this external directory access?`;
 }
 
-export function formatExternalDirectoryDenyReason(
-  toolName: string,
-  pathValue: string,
-  cwd: string,
-  agentName?: string,
-): string {
-  const subject = agentName ? `Agent '${agentName}'` : "Current agent";
-  return `${subject} is not permitted to run tool '${toolName}' for path '${pathValue}' outside working directory '${cwd}'. ${formatExternalDirectoryHardStopHint()}`;
-}
-
-export function formatExternalDirectoryUserDeniedReason(
-  toolName: string,
-  pathValue: string,
-  denialReason?: string,
-): string {
-  const reasonSuffix = denialReason ? ` Reason: ${denialReason}.` : "";
-  return `User denied external directory access for tool '${toolName}' path '${pathValue}'.${reasonSuffix} ${formatExternalDirectoryHardStopHint()}`;
-}
-
 export function formatBashExternalDirectoryAskPrompt(
   command: string,
   externalPaths: string[],
@@ -41,14 +18,3 @@ export function formatBashExternalDirectoryAskPrompt(
   const pathList = externalPaths.join(", ");
   return `${subject} requested bash command '${command}' which references path(s) outside working directory '${cwd}': ${pathList}. Allow this external directory access?`;
 }
-
-export function formatBashExternalDirectoryDenyReason(
-  command: string,
-  externalPaths: string[],
-  cwd: string,
-  agentName?: string,
-): string {
-  const subject = agentName ? `Agent '${agentName}'` : "Current agent";
-  const pathList = externalPaths.join(", ");
-  return `${subject} is not permitted to run bash command '${command}' which references path(s) outside working directory '${cwd}': ${pathList}. ${formatExternalDirectoryHardStopHint()}`;
-}

package/src/handlers/gates/external-directory.ts

@@ -6,11 +6,7 @@ import {
 } from "../../path-utils";
 import { deriveApprovalPattern } from "../../session-rules";
 import type { GateResult } from "./descriptor";
-import {
-  formatExternalDirectoryAskPrompt,
-  formatExternalDirectoryDenyReason,
-  formatExternalDirectoryUserDeniedReason,
-} from "./external-directory-messages";
+import { formatExternalDirectoryAskPrompt } from "./external-directory-messages";
 import type { ToolCallContext } from "./types";
 
 /**
@@ -80,20 +76,12 @@ export function describeExternalDirectoryGate(
   return {
     surface: "external_directory",
     input: { path: normalizedExtPath },
-    messages: {
-      denyReason: formatExternalDirectoryDenyReason(
-        tcc.toolName,
-        externalDirectoryPath,
-        tcc.cwd,
-        tcc.agentName ?? undefined,
-      ),
-      unavailableReason: `Accessing '${externalDirectoryPath}' outside the working directory requires approval, but no interactive UI is available.`,
-      userDeniedReason: (decision) =>
-        formatExternalDirectoryUserDeniedReason(
-          tcc.toolName,
-          externalDirectoryPath,
-          decision.denialReason,
-        ),
+    denialContext: {
+      kind: "external_directory",
+      toolName: tcc.toolName,
+      pathValue: externalDirectoryPath,
+      cwd: tcc.cwd,
+      agentName: tcc.agentName ?? undefined,
     },
     sessionApproval: {
       surface: "external_directory",

package/src/handlers/gates/path.ts

@@ -49,19 +49,11 @@ export function describePathGate(
   const descriptor: GateDescriptor = {
     surface: "path",
     input: { path: filePath },
-    messages: {
-      denyReason: formatPathDenyReason(
-        tcc.toolName,
-        filePath,
-        tcc.agentName ?? undefined,
-      ),
-      unavailableReason: `Accessing '${filePath}' requires approval, but no interactive UI is available.`,
-      userDeniedReason: (decision) => {
-        const reasonSuffix = decision.denialReason
-          ? ` Reason: ${decision.denialReason}.`
-          : "";
-        return `User denied access to path '${filePath}'.${reasonSuffix} Hard stop: this path permission denial is policy-enforced. Do not retry this path, do not attempt a filesystem bypass, and report the block to the user.`;
-      },
+    denialContext: {
+      kind: "path",
+      toolName: tcc.toolName,
+      pathValue: filePath,
+      agentName: tcc.agentName ?? undefined,
     },
     sessionApproval: {
       surface: "path",
@@ -96,15 +88,6 @@ export function describePathGate(
   return descriptor;
 }
 
-export function formatPathDenyReason(
-  toolName: string,
-  pathValue: string,
-  agentName?: string,
-): string {
-  const subject = agentName ? `Agent '${agentName}'` : "Current agent";
-  return `${subject} is not permitted to access path '${pathValue}' via tool '${toolName}'. Hard stop: this path permission denial is policy-enforced. Do not retry this path, do not attempt a filesystem bypass, and report the block to the user.`;
-}
-
 export function formatPathAskPrompt(
   toolName: string,
   pathValue: string,

package/src/handlers/gates/runner.ts

@@ -1,3 +1,8 @@
+import {
+  formatDenyReason,
+  formatUnavailableReason,
+  formatUserDeniedReason,
+} from "../../denial-messages";
 import type { PermissionPromptDecision } from "../../permission-dialog";
 import { applyPermissionGate } from "../../permission-gate";
 import type { PermissionCheckResult } from "../../types";
@@ -81,6 +86,14 @@ export async function runGateCheck(
         : undefined
     : undefined;
 
+  // Construct messages from the centralized formatter.
+  const messages = {
+    denyReason: formatDenyReason(descriptor.denialContext),
+    unavailableReason: formatUnavailableReason(descriptor.denialContext),
+    userDeniedReason: (decision: PermissionPromptDecision) =>
+      formatUserDeniedReason(descriptor.denialContext, decision.denialReason),
+  };
+
   let autoApproved = false;
   const gateResult = await applyPermissionGate({
     state: check.state,
@@ -96,7 +109,7 @@ export async function runGateCheck(
     },
     writeLog: deps.writeReviewLog,
     logContext: { ...descriptor.logContext, agentName },
-    messages: descriptor.messages,
+    messages,
   });
 
   // 4. Determine whether session approval was granted

package/src/handlers/gates/skill-read.ts

@@ -1,9 +1,6 @@
 import { toRecord } from "../../common";
 import { normalizePathForComparison } from "../../path-utils";
-import {
-  formatSkillPathAskPrompt,
-  formatSkillPathDenyReason,
-} from "../../permission-prompts";
+import { formatSkillPathAskPrompt } from "../../permission-prompts";
 import type { SkillPromptEntry } from "../../skill-prompt-sanitizer";
 import { findSkillPathMatch } from "../../skill-prompt-sanitizer";
 import type { GateDescriptor } from "./descriptor";
@@ -55,19 +52,11 @@ export function describeSkillReadGate(
   return {
     surface: "skill",
     input: { name: matchedSkill.name },
-    messages: {
-      denyReason: formatSkillPathDenyReason(
-        matchedSkill,
-        path,
-        tcc.agentName ?? undefined,
-      ),
-      unavailableReason: `Accessing skill '${matchedSkill.name}' requires approval, but no interactive UI is available.`,
-      userDeniedReason: (decision) => {
-        const denialReason = decision.denialReason
-          ? ` Reason: ${decision.denialReason}.`
-          : "";
-        return `User denied access to skill '${matchedSkill.name}'.${denialReason}`;
-      },
+    denialContext: {
+      kind: "skill_read",
+      skillName: matchedSkill.name,
+      readPath: path,
+      agentName: tcc.agentName ?? undefined,
     },
     promptDetails: {
       source: "skill_read",

package/src/handlers/gates/tool.ts

@@ -1,10 +1,6 @@
 import { getPathBearingToolPath, PATH_BEARING_TOOLS } from "../../path-utils";
 import { suggestSessionPattern } from "../../pattern-suggest";
-import {
-  formatAskPrompt,
-  formatDenyReason,
-  formatUserDeniedReason,
-} from "../../permission-prompts";
+import { formatAskPrompt } from "../../permission-prompts";
 import { getPermissionLogContext } from "../../tool-input-preview";
 import type { PermissionCheckResult } from "../../types";
 import type { GateDescriptor } from "./descriptor";
@@ -48,18 +44,6 @@ export function describeToolGate(
     deriveSuggestionValue(tcc, check),
   );
 
-  // Build the unavailable-reason message. Bash gets the command embedded.
-  const inputCommand =
-    tcc.toolName === "bash" &&
-    typeof (tcc.input as Record<string, unknown>)?.command === "string"
-      ? ((tcc.input as Record<string, unknown>).command as string)
-      : null;
-  const unavailableReason = inputCommand
-    ? `Running bash command '${inputCommand}' requires approval, but no interactive UI is available.`
-    : tcc.toolName === "mcp"
-      ? "Using tool 'mcp' requires approval, but no interactive UI is available."
-      : `Using tool '${tcc.toolName}' requires approval, but no interactive UI is available.`;
-
   const askMessage = formatAskPrompt(
     check,
     tcc.agentName ?? undefined,
@@ -69,11 +53,11 @@ export function describeToolGate(
   return {
     surface: tcc.toolName,
     input: tcc.input,
-    messages: {
-      denyReason: formatDenyReason(check, tcc.agentName ?? undefined),
-      unavailableReason,
-      userDeniedReason: (decision) =>
-        formatUserDeniedReason(check, decision.denialReason),
+    denialContext: {
+      kind: "tool",
+      check,
+      agentName: tcc.agentName ?? undefined,
+      input: tcc.input,
     },
     sessionApproval: {
       surface: suggestion.surface,