@hank-warren/pi-auto-permissions 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @hank-warren/pi-auto-permissions
 
+## 0.19.0
+
+### Minor Changes
+
+- Make subagents revise a command before the human is interrupted, and make approval prompts work over RPC.
+
+  - A subagent session (`PI_SUBAGENT_CHILD=1`, set by `@hank-warren/pi-agents`) is told it is a subagent: a short section appended to its system prompt says that commands needing approval pause the supervising session, so it should prefer in-scope and read-only commands and revise when asked to. On Pi 1.x the section is a named prompt section (`auto_permissions_subagent`), so it never replaces the prompt that Pi and other extensions build, such as the parent's instruction files pi-agents adds to a child.
+  - In a subagent child with a UI, an `ask_user` verdict or a failed review first blocks the command with a revise-first reason instead of prompting. Issuing the same command again unchanged in a later turn escalates it to the human as an ordinary approval prompt, once: a later identical attempt is revised first again. Duplicates within the same turn, such as sibling calls or a codemode `Promise.all`, are refused too, because the model has not seen the first refusal yet. Children without a UI keep the "no interactive user" block.
+  - In RPC mode the approval prompt goes through `ctx.ui.select`. Before this, every approval forwarded over RPC was silently denied, because `custom()` returns nothing there. This applies to any RPC session, not only subagents: a client that never answers the prompt now leaves the command waiting until the turn is cancelled, where it used to be denied at once.
+  - The guardian's subagent section says what an `ask_user` verdict does for that child: revise first and then a human when its prompts surface in a parent, a hard block when it has no UI.
+  - A revise-first refusal is recorded in the denial log and the `auto-permissions:denied` event with `"reviseFirst": true`, keeping the `decisionSource` of the verdict behind it, and the recent denials view labels it "revise first".
+
 ## 0.18.0
 
 ### Minor Changes

package/README.md

@@ -243,7 +243,7 @@ The guardian must return one of three decisions:
 
 - `approve`: execute the command
 - `revise`: block it and tell the main agent what to correct
-- `ask_user`: open an approval prompt (rendered with [`@hank-warren/pi-permission-selector`](../pi-permission-selector)'s `OptionSelector`): numbered options with `1`–`9` hotkeys, Tab to attach a note that is delivered to the agent as a steering user message, Esc to cancel — which blocks the command
+- `ask_user`: open an approval prompt (rendered with [`@hank-warren/pi-permission-selector`](../pi-permission-selector)'s `OptionSelector`): numbered options with `1`–`9` hotkeys, Tab to attach a note that is delivered to the agent as a steering user message, Esc to cancel — which blocks the command. In RPC mode, as in a pi-agents child whose prompts the parent shows, the prompt is Pi's plain select dialog instead: Allow or Block, without Tab notes. It waits for the RPC client's answer, so a client that never answers holds the command until the turn is cancelled
 
 ## Conversation context and caching
 
@@ -443,9 +443,18 @@ Group names come from your configured rules. A trusted group bypasses guarded re
 
 ## 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).
+When a session is a subagent child (`PI_SUBAGENT_CHILD=1`, set by `@hank-warren/pi-agents` and [pi-subagents](https://github.com/nicobailon/pi-subagents)), 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.
+The child itself is told it is a subagent: a short section appended to its system prompt says that commands needing approval pause the supervising session, so it should prefer in-scope and read-only commands and revise when asked to. On Pi 1.x the section is a named prompt section (`auto_permissions_subagent`), so it never replaces the prompt that Pi and other extensions build, such as the parent's instruction files pi-agents adds to a child.
+
+An `ask_user` verdict in a subagent, or a failed review (timeout, unavailable reviewer, unparsable verdict), never interrupts the human on the first try:
+
+- **Child with a UI** (an RPC child whose prompts surface in the parent, as with pi-agents): the command is blocked with a revise-first reason. Issuing the *same* command again unchanged in a later turn escalates it to the human as an ordinary approval prompt, once: after that, a later identical attempt is revised first again. Duplicates within the same turn (sibling calls, or a codemode `Promise.all`) are refused as well, because the model has not seen the first refusal yet. Any other command gets its own revise-first turn.
+- **Child without a UI**: the command is blocked with a reason instructing the child to route around the gated operation or report the blocker.
+
+The guardian's subagent section says which of these applies, so a child without a UI is never told a human may approve later. A revise-first refusal is recorded in the denial log and the `auto-permissions:denied` event with `"reviseFirst": true`, keeping the `decisionSource` of the verdict behind it, so it stays distinguishable from a guardian's own revise.
+
+Reviewer usage records from subagent sessions carry `"subagent": true` in the usage sidecar.
 
 ## Guardian dispatch
 

package/denial-log.ts

@@ -28,6 +28,12 @@ export interface DenialRecord {
   verdict: DenialVerdict;
   reason: string;
   decisionSource: DenialSource;
+  /**
+   * A subagent's revise-first refusal: `decisionSource` would have gone to the
+   * human (an ask_user verdict or a failed review), and the subagent was told
+   * to revise first. Absent on every other denial.
+   */
+  reviseFirst?: true;
 }
 
 export function buildDenialRecord(input: {
@@ -39,6 +45,7 @@ export function buildDenialRecord(input: {
   verdict: DenialVerdict;
   reason: string;
   decisionSource: DenialSource;
+  reviseFirst?: boolean;
 }): DenialRecord {
   return {
     v: 1,
@@ -52,6 +59,7 @@ export function buildDenialRecord(input: {
     verdict: input.verdict,
     reason: input.reason,
     decisionSource: input.decisionSource,
+    ...(input.reviseFirst ? { reviseFirst: true as const } : {}),
   };
 }
 

package/guardian-reviewer.ts

@@ -24,7 +24,7 @@ import {
   OVERRIDE_FEEDBACK_SYSTEM_PROMPT,
   parsePermissionVerdict,
   SCRIPT_EVIDENCE_SYSTEM_PROMPT,
-  SUBAGENT_CONTEXT_SYSTEM_PROMPT,
+  subagentContextSystemPrompt,
   type PermissionVerdict,
   type ReviewEvidenceRecord,
 } from "./review.js";
@@ -317,7 +317,7 @@ export function createGuardianReviewer(
     const subagentContext = detectSubagentContext(ctx.cwd);
     const basePolicyPrompt = [
       config.systemPrompt,
-      ...(subagentContext ? [SUBAGENT_CONTEXT_SYSTEM_PROMPT] : []),
+      ...(subagentContext ? [subagentContextSystemPrompt(ctx.hasUI)] : []),
     ].join("\n\n");
     // Appended outside config.systemPrompt so sessions using a customized
     // systemPromptFile still learn how to weigh override records. The injected

package/guardian-transport.ts

@@ -22,12 +22,11 @@ import { completeSimple } from "@earendil-works/pi-ai/compat";
  * future pi release renames the seam — degrading to the historical behavior
  * instead of crashing.
  *
- * This file was duplicated verbatim into packages/pi-herdr-auto-title until
- * that package was removed; `DUPLICATED_SOURCES` in `scripts/validate.py`
- * policed the copies. It has one home again. If a second extension package
- * ever needs it, copy it rather than importing across packages by relative
- * path, and register the pair in `DUPLICATED_SOURCES` — which is why every
- * package-specific detail stays behind a parameter (`packageLabel`).
+ * This file is duplicated verbatim in packages/pi-auto-permissions and
+ * packages/pi-auto-name; `DUPLICATED_SOURCES` in `scripts/validate.py` keeps
+ * the copies byte-identical. Edit one and copy it over the other. Every
+ * package-specific detail stays behind a parameter (`packageLabel`) so the
+ * copies never need to differ.
  * The "guardian" in the names is historical: pi-auto-permissions' guardian
  * reviewer was the first caller.
  */

package/index.ts

@@ -26,6 +26,7 @@ import { createSessionOverrides } from "./session-overrides.js";
 import { createGuardianReviewer } from "./guardian-reviewer.js";
 import { registerSettingsCommand } from "./settings-command.js";
 import type { BlockResult, ReviewScope, ReviewTarget } from "./review-scope.js";
+import { detectSubagentContext } from "./subagent-context.js";
 import type { ReviewDisplayState } from "./widget-status.js";
 
 /**
@@ -48,6 +49,8 @@ interface ReviewOutcome {
   reason: string;
   /** What the agent is told; absent means the command runs. */
   block?: string;
+  /** A subagent's revise-first refusal, marked so the denial log tells it from a guardian revise. */
+  reviseFirst?: boolean;
 }
 
 const PROJECT_CONFIG_DIR_NAME = (PiCodingAgent as { CONFIG_DIR_NAME?: string }).CONFIG_DIR_NAME ?? ".pi";
@@ -70,6 +73,22 @@ function denyReason(gate: Gate): string {
   return `Blocked by policy: ${gate.label}\n\n${gate.message ?? "This operation is denied by rule."}\n\nThis is a deny rule: it cannot be overridden by trusted groups or user approval. Choose a different approach.`;
 }
 
+/**
+ * Appended to a subagent child's system prompt. A child that does have a UI
+ * (an RPC child whose prompts surface in the parent) still costs the human an
+ * interruption per prompt, so it is told to revise before it escalates.
+ */
+/** The system prompt section that carries SUBAGENT_PERMISSIONS_PROMPT on Pi versions with a structured prompt. */
+export const SUBAGENT_PROMPT_SECTION = "auto_permissions_subagent";
+
+export const SUBAGENT_PERMISSIONS_PROMPT = `## Auto Permissions (subagent)
+You are running as a subagent. Bash commands that Auto Permissions cannot approve on its own need a human, and asking one pauses the supervising session until they answer. Prefer commands that stay inside your task and working directory, and read-only alternatives where they answer the question. When Auto Permissions asks you to revise a command, change the approach instead of retrying it; re-run a command unchanged only when it is genuinely required and a human should decide.`;
+
+/** What a subagent is told the first time a command would need human approval. */
+export function subagentReviseFirstReason(gateLabel: string, reason: string): string {
+  return `${gateLabel} needs human approval: ${reason}\nYou are a subagent: asking the human pauses the supervising session until they answer. Revise first: get the same result with a command that stays inside your task and working directory (read-only, a narrower target, local instead of remote). If this exact command is genuinely required, run it again unchanged and the request goes to the human.`;
+}
+
 function reviewCancelledResult(): BlockResult {
   return { block: true, reason: "Auto Permissions review cancelled" };
 }
@@ -169,6 +188,14 @@ function assistantToolCalls(message: unknown): AssistantToolCall[] {
 export default function autoPermissionsExtension(pi: ExtensionAPI) {
   const overrides = createSessionOverrides(pi);
   let trustedGroups = new Set<string>();
+  // Set per session: a subagent child (PI_SUBAGENT_CHILD=1) revises before it
+  // asks. `reviseFirst` maps each command it was told to revise to the turn
+  // it was told in; issuing it again unchanged in a *later* turn escalates it
+  // to the human, once: the entry goes with it. Same-turn duplicates (sibling calls, codemode Promise.all)
+  // are refused too, since the model has not yet seen the first refusal.
+  let subagentSession = false;
+  let turnGeneration = 0;
+  const reviseFirst = new Map<string, number>();
   let lastConfigError: string | undefined;
   let lastEvaluationLogError: string | undefined;
   // Guardian calls run in parallel up to config.reviewConcurrency; applying
@@ -242,6 +269,7 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
     verdict: DenialVerdict,
     reason: string,
     decisionSource: DenialSource,
+    reviseFirst = false,
   ): void {
     const { ctx, config, gate, command, target } = scope;
     try {
@@ -253,6 +281,7 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
         verdict,
         reason,
         decisionSource,
+        ...(reviseFirst ? { reviseFirst: true } : {}),
       });
     } catch {
       // Event fan-out is observability, never part of the decision.
@@ -268,6 +297,7 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
         verdict,
         reason,
         decisionSource,
+        reviseFirst,
       }));
     } catch {
       // The denial log is best-effort observability.
@@ -277,7 +307,7 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
   /** The one place a decision is recorded, rendered and returned. */
   function settle(scope: ReviewScope, outcome: ReviewOutcome): BlockResult | undefined {
     if (outcome.verdict && outcome.source) {
-      recordDenial(scope, outcome.verdict, outcome.reason, outcome.source);
+      recordDenial(scope, outcome.verdict, outcome.reason, outcome.source, outcome.reviseFirst === true);
     }
     if (outcome.display) {
       display.show(scope, outcome.display, outcome.detail ?? outcome.reason, true);
@@ -520,6 +550,41 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
     }
   }
 
+  /**
+   * In a subagent with a UI, the first time a command would go to the human it
+   * is refused with a revise-first reason instead. Same-turn duplicates are
+   * refused too; an unchanged retry in a later turn returns undefined, and the
+   * caller asks the human.
+   */
+  function reviseFirstBlock(
+    scope: ReviewScope,
+    reason: string,
+    source: "guardian" | "review_failure",
+    lifecycleSignal: AbortSignal,
+  ): BlockResult | undefined {
+    if (!subagentSession || !scope.ctx.hasUI) return undefined;
+    // As askUser does: a refusal the model will never see must not count as
+    // its revise-first turn, or its retry would go straight to the human.
+    const cancelled = cancelledAfterAwait(scope, lifecycleSignal);
+    if (cancelled) return cancelled;
+    const key = `${scope.gate.label}\0${scope.command}`;
+    const refusedIn = reviseFirst.get(key);
+    if (refusedIn !== undefined && refusedIn !== turnGeneration) {
+      // Escalated now: a later identical attempt is revised first again.
+      reviseFirst.delete(key);
+      return undefined;
+    }
+    if (refusedIn === undefined) reviseFirst.set(key, turnGeneration);
+    return settle(scope, {
+      display: "revise",
+      verdict: "revise",
+      source,
+      reason,
+      block: subagentReviseFirstReason(scope.gate.label, reason),
+      reviseFirst: true,
+    });
+  }
+
   /** Apply one settled review. Runs holding the decision slot. */
   function applyReview(
     scope: ReviewScope,
@@ -527,7 +592,8 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
     lifecycleSignal: AbortSignal,
   ): Promise<BlockResult | undefined> | BlockResult | undefined {
     if (outcome.kind === "failed") {
-      return askUser(scope, `Automatic review failed: ${outcome.reason}`, lifecycleSignal, "review_failure");
+      const reason = `Automatic review failed: ${outcome.reason}`;
+      return reviseFirstBlock(scope, reason, "review_failure", lifecycleSignal) ?? askUser(scope, reason, lifecycleSignal, "review_failure");
     }
     const { verdict } = outcome;
     if (verdict.decision === "approve") {
@@ -542,7 +608,7 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
         block: `Auto Permissions requested revision: ${verdict.reason}\nRevise the command and try again.`,
       });
     }
-    return askUser(scope, verdict.reason, lifecycleSignal, "guardian");
+    return reviseFirstBlock(scope, verdict.reason, "guardian", lifecycleSignal) ?? askUser(scope, verdict.reason, lifecycleSignal, "guardian");
   }
 
   /**
@@ -677,6 +743,7 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
   });
 
   pi.on("turn_end", () => {
+    turnGeneration += 1;
     lastAssistantCalls = [];
     abandonSiblingReviews();
     endScripts();
@@ -755,6 +822,25 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
     return decide(scope, input, lifecycleSignal, early ?? runReview(scope, input, lifecycleSignal));
   });
 
+  pi.on("before_agent_start", (event) => {
+    if (!subagentSession) return;
+    try {
+      if (!loadAutoPermissionsConfig().enabled) return;
+    } catch {
+      // An invalid config fails closed on the first bash call; the guidance still applies.
+    }
+    // On Pi 1.x a returned systemPrompt forces the whole prompt for the run,
+    // dropping what later extensions change in its options (pi-agents adds
+    // the parent's instruction files there), so the guidance goes into a
+    // named section instead. Older Pi takes the prompt as a string.
+    const sections = (event as { systemPromptOptions?: { sections?: Record<string, string> } }).systemPromptOptions?.sections;
+    if (sections) {
+      sections[SUBAGENT_PROMPT_SECTION] = SUBAGENT_PERMISSIONS_PROMPT;
+      return;
+    }
+    return { systemPrompt: `${event.systemPrompt}\n\n${SUBAGENT_PERMISSIONS_PROMPT}` };
+  });
+
   registerSettingsCommand(pi, { overrides, reviewer });
 
   function resetCallTracking(): void {
@@ -782,6 +868,8 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
     if (config) warnAboutMissingReviewerProvider(ctx, config);
 
     resetCallTracking();
+    subagentSession = detectSubagentContext(ctx.cwd) !== undefined;
+    reviseFirst.clear();
     reviewer.startSession(ctx.cwd);
     overrides.restore(ctx.sessionManager.getBranch());
     trustedGroups = ctx.isProjectTrusted() ? loadTrustedGroups(ctx.cwd) : new Set();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-auto-permissions",
-  "version": "0.18.0",
+  "version": "0.19.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": [

package/prompt-select.ts

@@ -22,6 +22,10 @@ export function setHerdrBlocked(pi: ExtensionAPI, active: boolean, label?: strin
  *   idempotent and performs its own teardown, so nothing else is needed)
  * - a host that reports `hasUI` but cannot render custom components
  *
+ * In RPC mode (`hasUI` is true but `custom()` returns undefined) the prompt
+ * goes through `ctx.ui.select`, which the RPC client renders: that is how a
+ * subagent child's approval reaches the human in the parent session.
+ *
  * A Tab-typed note is delivered to the agent as a steering user message,
  * matching what the retired `ExtensionSelectorComponent` monkey patch in
  * pi-permission-selector did.
@@ -33,6 +37,7 @@ export function promptSelect(
   values: string[],
   signal: AbortSignal,
 ): Promise<string | undefined> {
+  if (ctx.mode === "rpc") return ctx.ui.select(title, values, { signal });
   return ctx.ui.custom<string | undefined>((tui, theme, _keybindings, done) => {
     let finished = false;
     const onAbort = () => finish(undefined);

package/review.ts

@@ -174,13 +174,24 @@ Examples:
 Return strict JSON only with this shape:
 {"decision":"approve"|"revise"|"ask_user","reason":"one concise sentence"}`;
 
+/** What an "ask_user" verdict does in a subagent, which depends on whether its prompts can reach a human. */
+const SUBAGENT_ASK_USER = {
+  withUI: `An "ask_user" decision does not reach a human directly: the subagent is first told to revise the command, and the step stays blocked unless a human later approves the same command.`,
+  withoutUI: `An "ask_user" decision cannot reach a human: this subagent has no interactive user, so the command is blocked outright and the subagent must route around it or report the blocker.`,
+};
+
 /**
  * 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.
+ * object; this section tells the reviewer how to weigh them. Whether the child
+ * has a UI is fixed for its session, so the prompt stays cacheable.
  */
-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).
+export function subagentContextSystemPrompt(hasUI: boolean): string {
+  return SUBAGENT_CONTEXT_TEMPLATE.replace("{ASK_USER}", hasUI ? SUBAGENT_ASK_USER.withUI : SUBAGENT_ASK_USER.withoutUI);
+}
+
+const SUBAGENT_CONTEXT_TEMPLATE = `SUBAGENT EXECUTION CONTEXT
+This session is an autonomous subagent executing a task delegated by a supervising agent session. {ASK_USER} 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, but it was authored by the supervising agent, not typed by a human. Delegation authorizes medium-risk work scoped to the subagent's own workspace. It does not blanket-authorize higher risk: approve a high- or critical-risk operation only when the delegated task names the exact operation and target — the same explicit-intent standard a human user's message is held to — and treat irreversible destruction outside the subagent's scope as never authorized by delegation alone, whatever the task's general wording.
 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.

package/settings-command.ts

@@ -136,7 +136,7 @@ export function registerSettingsCommand(
             ts: record.ts,
             gateLabel: record.gate.label,
             command: record.command,
-            verdict: record.verdict,
+            verdict: record.reviseFirst ? "revise first" : record.verdict,
             reason: record.reason,
           }));
         } catch {

package/subagent-context.ts

@@ -4,16 +4,16 @@ 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.
+ * subagentContextSystemPrompt() 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.
+ * Detection is based on the environment contract that `@hank-warren/pi-agents`
+ * and `pi-subagents` (nicobailon/pi-subagents) both use: children are spawned
+ * 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. */
+  /** The subagent's run id (PI_SUBAGENT_RUN_ID), when present. */
   runId?: string;
   /** Nesting depth for nested subagents (PI_SUBAGENT_DEPTH), when > 0. */
   depth?: number;