@hank-warren/pi-auto-permissions 0.3.0 → 0.4.0

package/NOTICE.md

@@ -4,4 +4,4 @@ This package is a fork of [`@ogulcancelik/pi-auto-permissions`](https://github.c
 
 The original work is Copyright (c) 2026 Can Celik and is used under the MIT License included in [`LICENSE`](LICENSE).
 
-Fork-specific changes are Copyright (c) 2026 Hank Warren and are released under the same MIT License. They include the `reviewEvidence.userAnswerTools` dialog-answer evidence feature, proposed upstream in [ogulcancelik/pi-extensions#24](https://github.com/ogulcancelik/pi-extensions/issues/24) / [PR #25](https://github.com/ogulcancelik/pi-extensions/pull/25), the prompted-review evaluation log with explicit user feedback, and the single-line animated review status widget.
+Fork-specific changes are Copyright (c) 2026 Hank Warren and are released under the same MIT License. They include the `reviewEvidence.userAnswerTools` dialog-answer evidence feature, proposed upstream in [ogulcancelik/pi-extensions#24](https://github.com/ogulcancelik/pi-extensions/issues/24) / [PR #25](https://github.com/ogulcancelik/pi-extensions/pull/25), the prompted-review evaluation log with explicit user feedback, the single-line animated review status widget, guardian dispatch through the host model runtime so extension-registered provider transports apply, and subagent-aware review context for pi-subagents child sessions.

package/README.md

@@ -275,6 +275,16 @@ gh
 
 Group names come from your configured rules. A trusted group bypasses all review for that group, so use it only in projects you control.
 
+## Subagent sessions
+
+When a session is a [pi-subagents](https://github.com/nicobailon/pi-subagents) child (`PI_SUBAGENT_CHILD=1`), the guardian receives additional execution facts with each review — run id, nesting depth, whether the cwd is a linked git worktree, and the checked-out branch — plus a prompt section telling it to judge risk by effect scope and reversibility relative to the subagent's own workspace instead of by command name. Mutations confined to the subagent's isolated worktree, its own feature branch, or resources it created are approvable when they serve the delegated task; `ask_user` is reserved for effects that escape that scope (shared or default branches, host-level configuration, production systems, credentials, data leaving the machine).
+
+Subagent sessions have no interactive user, so an `ask_user` verdict blocks the command immediately with a reason instructing the child to route around the gated operation or report the blocker. Reviewer usage records from subagent sessions carry `"subagent": true` in the usage sidecar.
+
+## Guardian dispatch
+
+Reviewer requests dispatch through the host's model runtime rather than pi-ai's compat layer, so provider transports registered by other extensions (for example `@gotgenes/pi-anthropic-auth` OAuth request shaping) apply to guardian calls. When the runtime seam is unavailable, dispatch falls back to `compat.completeSimple`.
+
 ## Failure behavior
 
 A missing reviewer model, unavailable credentials, malformed response, timeout, cancellation, or oversized review context never auto-approves a command.

package/guardian-transport.ts

@@ -0,0 +1,42 @@
+import { completeSimple } from "@earendil-works/pi-ai/compat";
+
+/**
+ * Guardian model dispatch seam.
+ *
+ * pi-ai's `compat.completeSimple` dispatches through pi-ai's own api registry,
+ * which extension-registered provider transports never reach: pi routes
+ * `pi.registerProvider()` configs only through the coding agent's
+ * `ModelRuntime` -> `provider-composer.streamWith`. Auth-shaping extensions
+ * such as `@gotgenes/pi-anthropic-auth` install their transport wrapper there,
+ * so a reviewer request issued via `compat.completeSimple` reaches Anthropic
+ * unshaped, and Claude Pro/Max OAuth requests fail with the misleading
+ * "extra usage" HTTP 400 (see gotgenes/pi-anthropic-auth
+ * docs/architecture.md, "The remaining gap: pi-ai compat dispatch").
+ *
+ * `ExtensionContext.modelRegistry` is a deliberately narrowed facade over
+ * `ModelRuntime` that re-exports `complete()` but not `completeSimple()` —
+ * and only the simple layer translates the api-agnostic `reasoning` option
+ * into each api's native thinking config. So reach the runtime's
+ * `completeSimple` through the facade's `runtime` field (a public JS field
+ * marked `private` in the .d.ts), and fall back to compat dispatch when a
+ * future pi release renames the seam — degrading to the historical behavior
+ * instead of crashing.
+ */
+export type GuardianCompleteSimple = typeof completeSimple;
+
+let warnedCompatFallback = false;
+
+export function resolveGuardianCompleteSimple(modelRegistry: unknown): GuardianCompleteSimple {
+  const runtime = (modelRegistry as { runtime?: unknown } | null | undefined)?.runtime;
+  const candidate = (runtime as { completeSimple?: unknown } | null | undefined)?.completeSimple;
+  if (typeof candidate === "function") {
+    return candidate.bind(runtime) as GuardianCompleteSimple;
+  }
+  if (!warnedCompatFallback) {
+    warnedCompatFallback = true;
+    console.warn(
+      "[pi-auto-permissions] host ModelRuntime completeSimple is unavailable; falling back to pi-ai compat dispatch. Extension-registered provider transports (e.g. Anthropic OAuth shaping) will not apply to reviewer calls.",
+    );
+  }
+  return completeSimple;
+}

package/index.ts

@@ -1,5 +1,6 @@
 import { cleanupSessionResources, type Message } from "@earendil-works/pi-ai";
-import { completeSimple } from "@earendil-works/pi-ai/compat";
+import { resolveGuardianCompleteSimple } from "./guardian-transport.js";
+import { detectSubagentContext } from "./subagent-context.js";
 import * as PiCodingAgent from "@earendil-works/pi-coding-agent";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
@@ -28,6 +29,7 @@ import {
   buildReviewEnvelope,
   collectReviewEvidence,
   parsePermissionVerdict,
+  SUBAGENT_CONTEXT_SYSTEM_PROMPT,
   type PermissionVerdict,
   type ReviewEvidenceRecord,
 } from "./review.js";
@@ -283,7 +285,14 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
       discardReviewerLineage();
       throw error;
     }
-    const systemPrompt = buildReviewerSystemPrompt(config.systemPrompt, projectInstructions);
+    // Compose policy text first (base + subagent section), then let
+    // buildReviewerSystemPrompt append the untrusted project-instructions
+    // evidence block, keeping policy contiguous and evidence terminal.
+    const subagentContext = detectSubagentContext(ctx.cwd);
+    const policyPrompt = subagentContext
+      ? `${config.systemPrompt}\n\n${SUBAGENT_CONTEXT_SYSTEM_PROMPT}`
+      : config.systemPrompt;
+    const systemPrompt = buildReviewerSystemPrompt(policyPrompt, projectInstructions);
     const fingerprint = reviewerFingerprint(mainSessionId, model, config, systemPrompt, projectTrusted);
     const evidence = collectReviewEvidence(
       ctx.sessionManager.buildContextEntries(),
@@ -308,6 +317,7 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
       cwd: ctx.cwd,
       gate: gate.label,
       group: gate.group,
+      ...(subagentContext ? { execution: subagentContext } : {}),
     };
     const makeUserMessage = (records: readonly ReviewEvidenceRecord[], mode: "full" | "delta"): Message => ({
       role: "user",
@@ -345,7 +355,9 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
       if (!sessionActive || reviewSignal.aborted || reviewerGeneration !== attemptGeneration) {
         throw new Error("review timed out or was cancelled");
       }
-      const response = await completeSimple(
+      // Dispatch through the host ModelRuntime so extension-registered provider
+      // transports (e.g. pi-anthropic-auth OAuth shaping) apply; see guardian-transport.ts.
+      const response = await resolveGuardianCompleteSimple(ctx.modelRegistry)(
         model,
         { systemPrompt, messages },
         {
@@ -365,7 +377,7 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
       if (response.stopReason === "error") {
         throw new Error(response.errorMessage ?? "reviewer request failed");
       }
-      recordReviewerUsage(config, model, response.usage);
+      recordReviewerUsage(config, model, response.usage, subagentContext !== undefined);
       const verdict = parsePermissionVerdict(assistantText(response.content));
       if (!sessionActive || signal?.aborted || reviewerGeneration !== attemptGeneration) {
         throw new Error("review timed out or was cancelled");
@@ -392,10 +404,10 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
    * Reviewer calls never reach the session transcript, so their usage is invisible to
    * tooling that reads session files. Record content-free counters in a sidecar instead.
    */
-  function recordReviewerUsage(config: AutoPermissionsConfig, model: { provider: string; id: string }, usage: unknown): void {
+  function recordReviewerUsage(config: AutoPermissionsConfig, model: { provider: string; id: string }, usage: unknown, subagent: boolean): void {
     if (!config.usageLog.enabled) return;
     try {
-      appendUsageRecord(config.usageLog.path, buildUsageLogRecord(model.provider, model.id, usage));
+      appendUsageRecord(config.usageLog.path, buildUsageLogRecord(model.provider, model.id, usage, "guardian", "auto-permissions", subagent));
     } catch {
       // Usage accounting is optional and must never block a permission decision.
     }
@@ -634,7 +646,10 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
     showReviewDisplay(ctx, config, gate, command, target, "ask_user", detail);
     if (!ctx.hasUI) {
       showReviewDisplay(ctx, config, gate, command, target, "blocked", detail, true);
-      return { block: true, reason: `${gate.label} requires user approval: ${detail}` };
+      return {
+        block: true,
+        reason: `${gate.label} requires user approval: ${detail}\nThis session has no interactive user to ask. Prefer an approach that avoids the gated operation, or report this blocker in your final output instead of retrying the same command.`,
+      };
     }
 
     const evaluationContext = config.evaluationLog.enabled

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-auto-permissions",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Fork of @ogulcancelik/pi-auto-permissions with dialog-answer user evidence: context-aware Bash permissions for Pi with automated guardian review.",
   "type": "module",
   "keywords": [
@@ -40,6 +40,8 @@
     "NOTICE.md",
     "index.ts",
     "config.ts",
+    "guardian-transport.ts",
+    "subagent-context.ts",
     "evaluation-log.ts",
     "gates.ts",
     "review.ts",

package/review.ts

@@ -1,3 +1,5 @@
+import type { SubagentExecutionContext } from "./subagent-context.js";
+
 export type PermissionDecision = "approve" | "revise" | "ask_user";
 
 export interface PermissionVerdict {
@@ -11,6 +13,8 @@ export interface CommandReviewRequest {
   cwd: string;
   gate: string;
   group: string;
+  /** Present only in subagent child sessions; runtime facts for the reviewer. */
+  execution?: SubagentExecutionContext;
 }
 
 export interface ReviewEvidenceRecord {
@@ -52,6 +56,20 @@ Examples:
 Return strict JSON only with this shape:
 {"decision":"approve"|"revise"|"ask_user","reason":"one concise sentence"}`;
 
+/**
+ * Appended to the reviewer system prompt only when the session is a subagent
+ * child (detectSubagentContext). Facts arrive in the request's "execution"
+ * object; this section tells the reviewer how to weigh them.
+ */
+export const SUBAGENT_CONTEXT_SYSTEM_PROMPT = `SUBAGENT EXECUTION CONTEXT
+This session is an autonomous subagent executing a task delegated by a supervising agent session. There is no interactive user: an "ask_user" decision does not open a prompt, it aborts this step with a block. The latest proposed action carries an "execution" object with runtime facts (isolated worktree, checked-out branch, nesting depth).
+The delegated task arrives as this session's USER evidence and carries the supervising session's authorization for the work it describes.
+Judge risk by effect scope and reversibility relative to the subagent's own workspace, not by command name:
+- Mutations confined to the subagent's isolated worktree, or to resources the evidence shows the subagent created (scratch files, branches it created or first pushed, containers, images, test databases), are at most medium risk; approve them when they serve the delegated task.
+- History rewrites and force-pushes are approvable only for branches the evidence shows the subagent created or that the delegated task explicitly directs it to rewrite; a branch being checked out in the subagent's worktree does not by itself establish ownership.
+- Lifecycle commands (including with sudo) for containers or services the subagent itself stood up are part of that workflow. Restarting, reconfiguring, or disabling shared host daemons and system services is host-level configuration, not subagent scope.
+- Reserve "ask_user" for effects that escape the subagent's scope: shared or default branches, remote resources it does not own, host-level configuration, production systems, credential or secret access, and data leaving the machine.`;
+
 const GENERIC_ARGUMENT_KEYS = ["command", "path", "action", "query", "target", "url", "method", "cwd"] as const;
 const NATIVE_COMPACTION_KIND = "openai-codex-native-compaction";
 const NATIVE_COMPACTION_VERSION = 1;

package/subagent-context.ts

@@ -0,0 +1,60 @@
+import { readFileSync, statSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+
+/**
+ * Runtime facts about a subagent child session, forwarded to the guardian as
+ * evidence. Facts only — the guardian judges what they imply; see
+ * SUBAGENT_CONTEXT_SYSTEM_PROMPT in review.ts.
+ *
+ * Detection is based on the environment contract of `pi-subagents`
+ * (nicobailon/pi-subagents), which spawns children with `PI_SUBAGENT_CHILD=1`
+ * plus run id and nesting depth. Absent that env, sessions are treated as
+ * ordinary sessions and review behavior is unchanged.
+ */
+export interface SubagentExecutionContext {
+  subagent: true;
+  /** pi-subagents run id (PI_SUBAGENT_RUN_ID), when present. */
+  runId?: string;
+  /** Nesting depth for nested subagents (PI_SUBAGENT_DEPTH), when > 0. */
+  depth?: number;
+  /** True when cwd is a linked git worktree (`.git` is a gitdir pointer file). */
+  isolatedWorktree: boolean;
+  /** Branch checked out in cwd, when it can be read from git metadata. */
+  branch?: string;
+}
+
+export function detectSubagentContext(
+  cwd: string,
+  env: Record<string, string | undefined> = process.env,
+): SubagentExecutionContext | undefined {
+  if (env.PI_SUBAGENT_CHILD !== "1") return undefined;
+
+  const context: SubagentExecutionContext = { subagent: true, isolatedWorktree: false };
+  // The run id is an attacker-influenced string that reaches the guardian
+  // prompt: cap length and charset so it stays an identifier, not a payload.
+  const runId = env.PI_SUBAGENT_RUN_ID?.trim().replace(/[^\w.:-]/g, "").slice(0, 128);
+  if (runId) context.runId = runId;
+  const depth = Number(env.PI_SUBAGENT_DEPTH ?? "");
+  if (Number.isInteger(depth) && depth > 0) context.depth = depth;
+
+  try {
+    const gitPath = join(cwd, ".git");
+    // A linked worktree has a `.git` pointer *file*; a primary checkout has a
+    // `.git` directory. statSync throws when cwd is not a git checkout at all.
+    if (!statSync(gitPath).isFile()) return context;
+    const gitdirRaw = readFileSync(gitPath, "utf8").match(/^gitdir:\s*(.+?)\s*$/m)?.[1];
+    if (!gitdirRaw) return context;
+    const gitdir = isAbsolute(gitdirRaw) ? gitdirRaw : join(cwd, gitdirRaw);
+    // Submodule checkouts also use a `.git` pointer file, but their gitdirs
+    // live under `.git/modules/<name>` inside a shared primary checkout — they
+    // are not isolated. Linked-worktree gitdirs are guaranteed to live under
+    // `<common>/.git/worktrees/<name>`.
+    if (!/[\\/]worktrees[\\/]/.test(gitdir)) return context;
+    context.isolatedWorktree = true;
+    const branch = readFileSync(join(gitdir, "HEAD"), "utf8").match(/^ref:\s*refs\/heads\/(\S+)/m)?.[1];
+    if (branch) context.branch = branch;
+  } catch {
+    // Not a git checkout or unreadable metadata: report the facts we have.
+  }
+  return context;
+}

package/usage-log.ts

@@ -27,6 +27,8 @@ export interface UsageLogRecord {
   label: string;
   provider: string;
   model: string;
+  /** Present (true) only for reviews issued inside a subagent child session. */
+  subagent?: true;
   usage: UsageLogTotals;
 }
 
@@ -54,6 +56,7 @@ export function buildUsageLogRecord(
   usage: unknown,
   label = "guardian",
   source = "auto-permissions",
+  subagent = false,
 ): UsageLogRecord {
   return {
     v: 1,
@@ -63,6 +66,7 @@ export function buildUsageLogRecord(
     label,
     provider,
     model,
+    ...(subagent ? { subagent: true as const } : {}),
     usage: usageLogTotals(usage),
   };
 }

package/widget-status.ts

@@ -17,7 +17,7 @@ export interface ReviewStatusFrame {
 }
 
 export const WAITING_FRAMES = ["✶", "✸", "✻", "✽"] as const;
-export const WAITING_FRAME_INTERVAL_MS = 120;
+export const WAITING_FRAME_INTERVAL_MS = 300;
 
 export function reviewStatusFrame(
   state: ReviewDisplayState,