pi-auto-permissions 0.1.4 → 0.1.5

package/README.md

@@ -165,9 +165,11 @@ writes only to the workspace and temporary roots, keeps protected metadata and
 the extension's durable state read-only, denies network and local binding, and
 applies to descendant processes.
 
-If direct-file path policy construction fails at startup, the fallback admits
-only the four known read-only standard tools and statically denies every `write` or
-`edit`. It does not guess path safety or ask the reviewer to replace missing
+Read-only standard tools and installed custom tools bypass permission runtime
+state entirely, preserving their native success, error, and cancellation
+results. If direct-file path policy construction fails at startup, the fallback
+admits only the four known read-only standard tools and statically denies every
+`write` or `edit`. It does not guess path safety or ask the reviewer to replace missing
 classification.
 
 Only reviewed shell actions reach the reviewer. Its complete semantic policy is:
@@ -187,11 +189,12 @@ Text answers, missing decisions, multiple decisions, and decision calls mixed
 with investigation calls are re-prompted up to twice; only one valid decision
 tool call is accepted. The adapter converts that structured call into a local
 one-field verdict. Exhausted re-prompts, timeouts, missing credentials, provider
-errors, cancellation, state changes, and every other non-allow outcome deny.
-Reviews have one aggregate 90-second deadline, at most three retryable model
-attempts, and denial circuit breakers to prevent loops. The model always sees
-one fixed denial message, while the user notification identifies whether the
-reviewer actually called `deny` or failed for a protocol/runtime reason.
+errors, and state changes block execution but are reported as permission-review
+failures, not Guardian denials. User cancellation is reported as `Operation
+aborted`, emits no denial notification, and does not count toward denial circuit
+breakers. Only an actual `deny` decision receives the fixed permission-denied
+message. Reviews have one aggregate 90-second deadline, at most three retryable
+model attempts, and denial circuit breakers to prevent loops.
 
 A sandbox rejection is returned as an ordinary tool error. The extension does
 not replay a command that may have started. The model may issue a different

package/docs/implementation-plan.md

@@ -156,7 +156,10 @@ Guarantees supported: I5-I10, I14, I17.
 - Enforce one aggregate 90-second deadline and at most three retryable attempts.
 - Convert the structured decision call locally into the exact one-field verdict;
   never interpret free-form model text as a decision.
-- Treat every non-allow/failure as denial and return one fixed denial string.
+- Block execution on every non-allow outcome, but report categories accurately:
+  only a valid `deny` decision is a permission denial; protocol/runtime failures
+  are review failures; user cancellation is `Operation aborted` and does not
+  increment denial breakers.
 - Track three consecutive and ten-of-fifty per-turn shell denial breakers;
   breaker interruption never blocks non-shell passthrough.
 

package/docs/invariants.md

@@ -233,11 +233,13 @@ An Auto review admits an action only if all of the following hold:
 5. the current backend equals the captured backend;
 6. the current canonical request equals the reviewed canonical request.
 
-All other outcomes deny: a valid `deny` call, exhausted decision re-prompts,
-missing model, missing credentials, timeout, cancellation, queue exhaustion,
-oversized input, provider failure, internal exception, revision change, backend
-change, or request change. There is no fallback model and no conversion to
-Unrestricted.
+All other outcomes block execution. A valid `deny` call is reported as a
+permission denial. Exhausted decision re-prompts, missing model or credentials,
+timeout, queue exhaustion, oversized input, provider failure, internal exception,
+revision change, backend change, or request change are reported as review
+failures. User cancellation is reported as `Operation aborted`, emits no denial
+notification, and does not increment denial breakers. There is no fallback model
+and no conversion to Unrestricted.
 
 The reviewer's complete semantic policy is: `Call deny only when the exact
 command is clearly likely to cause severe, difficult-to-reverse harm: broad loss
@@ -346,8 +348,9 @@ control-plane protection still operate, while every model-originated `bash` call
 infrastructure-specific safer-action result.
 
 If construction of the permission engine itself fails after subsystem startup,
-the extension publishes no active runtime, reports `Auto (unavailable)`, and its
-already-registered bash and non-bash gates return the fixed denial. Because the
+the extension publishes no active runtime and reports `Auto (unavailable)`.
+Read-only and custom tools still bypass the extension; bash and trusted standard
+write/edit calls return an enforcement-failure result. Because the
 command host also requires an active runtime, the three extension commands
 report failure rather than mutating state in this condition. A later successful
 Pi session initialization (normally reload or process restart) is required to
@@ -435,7 +438,9 @@ API. Denial returns a fixed tool result to the model:
 
 User-facing selection UI exists only inside explicit user slash commands. A
 permission denial may additionally emit a passive warning notification naming
-the denied tool; that notification is not an approval request.
+the denied tool; that notification is not an approval request. Review/runtime
+failures use a distinct failure result and notification. User cancellation emits
+neither and preserves the native `Operation aborted` result.
 
 ### I12. Direct-tool no-self-elevation invariant
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-auto-permissions",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "A minimal Codex-style Auto/Unrestricted permission guardrail for Pi",
   "type": "module",
   "license": "Apache-2.0",

package/src/guardian/index.ts

@@ -34,6 +34,8 @@ export {
 	GUARDIAN_DEFAULT_MAX_CONCURRENT_REVIEWS,
 	GUARDIAN_DEFAULT_MAX_QUEUED_REVIEWS,
 	GUARDIAN_DENIAL_MESSAGE,
+	GUARDIAN_OPERATION_ABORTED_MESSAGE,
+	GUARDIAN_REVIEW_FAILURE_MESSAGE,
 	GUARDIAN_DECISION_TOOLS,
 	GUARDIAN_INVESTIGATION_TOOLS,
 	GUARDIAN_TOOLS,

package/src/guardian/reviewer.ts

@@ -27,6 +27,9 @@ import { GuardianVerdictError, parseGuardianVerdict } from "./verdict.js";
 
 export const GUARDIAN_DENIAL_MESSAGE =
 	"Permission denied. This action was not executed. No override will be requested. Choose a materially safer action.";
+export const GUARDIAN_REVIEW_FAILURE_MESSAGE =
+	"Permission review failed. This action was not executed.";
+export const GUARDIAN_OPERATION_ABORTED_MESSAGE = "Operation aborted";
 export const GUARDIAN_REVIEW_DEADLINE_MS = 90_000;
 export const GUARDIAN_REVIEW_MAX_ATTEMPTS = 3;
 export const GUARDIAN_DEFAULT_MAX_CONCURRENT_REVIEWS = 4;
@@ -629,14 +632,21 @@ export class GuardianReviewEngine {
 		record = true,
 		verdict?: GuardianVerdict,
 	): GuardianDenyResult {
-		const breaker = record
+		const shouldRecord = record && reason !== "cancelled";
+		const breaker = shouldRecord
 			? this.#circuitBreaker.recordDenial(turnId)
 			: this.#circuitBreaker.snapshot(turnId);
+		const message =
+			reason === "cancelled"
+				? GUARDIAN_OPERATION_ABORTED_MESSAGE
+				: reason === "model_denied" || reason === "circuit_breaker"
+					? GUARDIAN_DENIAL_MESSAGE
+					: GUARDIAN_REVIEW_FAILURE_MESSAGE;
 		const result = {
 			outcome: "deny" as const,
 			attempts,
 			reason,
-			message: GUARDIAN_DENIAL_MESSAGE,
+			message,
 			interruptTurn: breaker.interruptTurn,
 		};
 		return verdict === undefined ? result : { ...result, verdict };

package/src/runtime/permission-engine.ts

@@ -17,6 +17,7 @@ import {
 } from "../domain.ts";
 import {
   GUARDIAN_DENIAL_MESSAGE,
+  GUARDIAN_REVIEW_FAILURE_MESSAGE,
   GuardianReviewEngine,
   guardianReviewBindingsEqual,
   type GuardianDenialReason,
@@ -471,9 +472,15 @@ function admit(route: PermissionExecutionRoute, reviewed: boolean): PermissionAd
 }
 
 function deny(reason: PermissionDenyDecision["reason"]): PermissionDenyDecision {
+  const message =
+    reason === "configuration_fault" ||
+    reason === "sandbox_unavailable" ||
+    reason === "stale_binding"
+      ? GUARDIAN_REVIEW_FAILURE_MESSAGE
+      : GUARDIAN_DENIAL_MESSAGE;
   return {
     outcome: "deny",
-    message: GUARDIAN_DENIAL_MESSAGE,
+    message,
     reason,
     interruptTurn: false,
   };

package/src/tools/bash.ts

@@ -5,7 +5,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
 import {
-  GUARDIAN_DENIAL_MESSAGE,
+  GUARDIAN_REVIEW_FAILURE_MESSAGE,
   type GuardianTranscriptItem,
 } from "../guardian/index.ts";
 import type { PermissionEngine } from "../runtime/index.ts";
@@ -66,8 +66,8 @@ export function registerGuardedBashTool(
     async execute(toolCallId, params, signal, onUpdate, ctx) {
       const runtime = getRuntime();
       if (runtime === null) {
-        notifyPermissionDenied(ctx, "bash");
-        throw new Error(GUARDIAN_DENIAL_MESSAGE);
+        notifyPermissionDenied(ctx, "bash", "configuration_fault");
+        throw new Error(GUARDIAN_REVIEW_FAILURE_MESSAGE);
       }
       await runtime.refreshBackend(ctx);
       const reviewSignal = runtime.signal(signal);
@@ -83,8 +83,8 @@ export function registerGuardedBashTool(
         ...(reviewSignal === undefined ? {} : { signal: reviewSignal }),
       });
       if (decision.outcome === "deny") {
-        notifyPermissionDenied(ctx, "bash", decision.reviewReason);
-        if (decision.interruptTurn) ctx.abort();
+        notifyPermissionDenied(ctx, "bash", decision.reason, decision.reviewReason);
+        if (decision.reviewReason !== "cancelled" && decision.interruptTurn) ctx.abort();
         throw new Error(decision.message);
       }
 

package/src/tools/denial-notice.ts

@@ -7,13 +7,20 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 export function notifyPermissionDenied(
   ctx: Pick<ExtensionContext, "ui">,
   toolName: string,
+  reason: string = "invalid_action",
   reviewReason?: string,
 ): void {
   try {
+    if (reviewReason === "cancelled") return;
+    const explicitDenial =
+      reason === "invalid_action" ||
+      reviewReason === "model_denied" ||
+      reviewReason === "circuit_breaker";
+    const prefix = explicitDenial ? "Permission denied" : "Permission enforcement failed";
     const diagnostic = reviewReason === undefined ? "" : ` Guardian result: ${reviewReason}.`;
     ctx.ui.notify(
-      `Permission denied: ${toolName} action was not executed.${diagnostic}`,
-      "warning",
+      `${prefix}: ${toolName} action was not executed.${diagnostic}`,
+      explicitDenial ? "warning" : "error",
     );
   } catch {
     // A notification failure must not change the fixed fail-closed denial.

package/src/tools/gate.ts

@@ -5,11 +5,12 @@ import type {
   ToolInfo,
 } from "@earendil-works/pi-coding-agent";
 import type { GuardianTranscriptItem } from "../guardian/index.ts";
-import { GUARDIAN_DENIAL_MESSAGE } from "../guardian/index.ts";
+import { GUARDIAN_REVIEW_FAILURE_MESSAGE } from "../guardian/index.ts";
 import type { PermissionEngine } from "../runtime/index.ts";
 import { notifyPermissionDenied } from "./denial-notice.ts";
 
 const DIRECT_FILE_TOOL_NAMES = new Set(["read", "grep", "find", "ls", "write", "edit"]);
+const READ_ONLY_FILE_TOOL_NAMES = new Set(["read", "grep", "find", "ls"]);
 
 export interface PermissionToolGateRuntime {
   readonly engine: PermissionEngine;
@@ -26,14 +27,22 @@ export function registerPermissionToolGate(
 ): void {
   pi.on("tool_call", async (event, ctx) => {
     if (event.toolName === "bash") return;
+
+    const info = findToolInfo(pi, event.toolName);
+    const trustedFileTool = isTrustedStandardFileTool(info, event);
+    // Reads and explicitly installed custom tools are outside this extension's
+    // enforcement surface. Do not touch permission state, lifecycle, or abort
+    // signals for them; their native success/error/cancellation must pass through.
+    if (!trustedFileTool || READ_ONLY_FILE_TOOL_NAMES.has(event.toolName)) return;
+
+    // Only trusted standard write/edit calls reach deterministic path policy.
     const runtime = getRuntime();
     if (runtime === null) {
-      notifyPermissionDenied(ctx, event.toolName);
-      return { block: true, reason: GUARDIAN_DENIAL_MESSAGE };
+      notifyPermissionDenied(ctx, event.toolName, "configuration_fault");
+      return { block: true, reason: GUARDIAN_REVIEW_FAILURE_MESSAGE };
     }
 
     await runtime.refreshStatus(ctx);
-    const info = findToolInfo(pi, event.toolName);
     const reviewSignal = runtime.signal(ctx.signal);
     const decision = await runtime.engine.gate({
       toolCallId: event.toolCallId,
@@ -42,12 +51,12 @@ export function registerPermissionToolGate(
       input: event.input,
       cwd: ctx.cwd,
       toolMetadata: canonicalToolMetadata(info, event.toolName),
-      trustedFileTool: isTrustedStandardFileTool(info, event),
+      trustedFileTool,
       transcript: () => runtime.transcript(ctx),
       ...(reviewSignal === undefined ? {} : { signal: reviewSignal }),
     });
     if (decision.outcome === "admit") return;
-    notifyPermissionDenied(ctx, event.toolName, decision.reviewReason);
+    notifyPermissionDenied(ctx, event.toolName, decision.reason, decision.reviewReason);
     if (decision.interruptTurn) ctx.abort();
     return { block: true, reason: decision.message };
   });