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

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @hank-warren/pi-auto-permissions
 
+## 0.20.0
+
+### Minor Changes
+
+- Rework the approval prompt so a long command can no longer push Allow/Block off-screen. The dialog shows the command (cut to a preview past a quarter of the terminal; Ctrl+O opens the full command in a scrolling viewer inside the prompt, which matters for commands a codemode script built, since the transcript shows only the script), then the guardian's note behind a `▌` bar in a fixed strong yellow, then the options, which stay pinned while you scroll the session. The review widget steps aside while the prompt is open instead of repeating it, and a settled result's reason now carries a `▌` bar in the outcome's color.
+
+## 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`): the command, then the guardian's note behind a `▌` bar in a fixed strong yellow (gold on dark themes, dark goldenrod on light ones, regardless of the theme's `warning` color), then numbered options. A command taller than a quarter of the terminal is cut to a preview, and the prompt stays pinned while you scroll the session above. Ctrl+O opens the full command in a scrolling viewer inside the prompt (Shift+↑/↓ or the mouse wheel; PgUp/PgDn outside fullscreen) and closes it again — the only complete copy when a codemode script built the command, since the transcript then shows the script. 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
 
@@ -403,7 +403,7 @@ The default UI shows guardian progress as a single animated status line in a tem
 auto permissions · Git commit · ✶ waiting for openai-codex-auto-permissions/gpt-5.6-luna
 ```
 
-A sparkle spinner (`✶ ✸ ✻ ✽`) cycles while the guardian is reviewing and resolves to `✓ approved`, `↻ revision requested`, `? waiting for your approval`, or `✗ blocked`. When approval is needed, a static warning-colored `●` precedes the prompt heading so the active prompt remains visually distinct from the transcript. The guardian's reason, when present, appears on a dim second line; the command itself is not repeated because it is already visible in the Bash tool box. Configure the widget with:
+A sparkle spinner (`✶ ✸ ✻ ✽`) cycles while the guardian is reviewing and resolves to `✓ approved`, `↻ revision requested`, or `✗ blocked`. When approval is needed, the widget row steps aside for the approval dialog, whose static yellow `●` heading keeps it visually distinct from the transcript; with several commands under review, the summary line still counts the ones `waiting for your approval`. The reason, when present, appears on a second line behind a `▌` bar in the outcome's color; the command itself is not repeated because it is already visible in the Bash tool box. Configure the widget with:
 
 ```json
 {
@@ -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/approval-prompt.ts

@@ -0,0 +1,171 @@
+import { CURSOR_MARKER, Key, matchesKey, truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import type { OptionSelector, SelectorTheme } from "@hank-warren/pi-permission-selector/selector.ts";
+
+/** What an approval prompt shows, top to bottom above the options. */
+export interface ApprovalPromptContent {
+  header: string;
+  command: string;
+  /** Who wrote `note`: "Guardian", or "Review failed" for an infrastructure error. */
+  noteLabel: string;
+  note: string;
+  /**
+   * True when the transcript shows this exact command (a model-issued call).
+   * A call a codemode script built shows only the script there.
+   */
+  inTranscript: boolean;
+}
+
+export interface ApprovalPromptTheme extends SelectorTheme {
+  bold(text: string): string;
+  /** Pi 1.x themes report the background they are designed for. */
+  readonly appearance?: string;
+}
+
+/** The slice of pi-tui's mouse event this reads; older pi-tui releases do not export the type. */
+export interface WheelEvent {
+  type: string;
+  wheelDelta?: number;
+}
+
+const MIN_PREVIEW_ROWS = 3;
+/** Rows left for the rest of Pi's input dock when the full command is open. */
+const RESERVED_ROWS = 6;
+const MIN_VIEWER_ROWS = 3;
+/** The note's height while the viewer is open, so a long note cannot crowd the command out. */
+const VIEWER_NOTE_ROWS = 2;
+
+// Fixed rather than the theme's `warning`, which some themes make green or dim:
+// the approval note must read as a caution in every theme.
+const NOTE_YELLOW_DARK = "\x1b[38;2;255;215;0m";
+const NOTE_YELLOW_LIGHT = "\x1b[38;2;184;134;11m";
+const FG_RESET = "\x1b[39m";
+
+export function noteYellow(theme: Pick<ApprovalPromptTheme, "appearance">): (text: string) => string {
+  const color = theme.appearance === "light" ? NOTE_YELLOW_LIGHT : NOTE_YELLOW_DARK;
+  return (text) => `${color}${text}${FG_RESET}`;
+}
+
+/** Plain-text form for hosts that render the title themselves (RPC `ui.select`). */
+export function approvalPromptText(content: Omit<ApprovalPromptContent, "inTranscript">): string {
+  return `${content.header}\n\n${content.command}\n\n${content.noteLabel}: ${content.note}`;
+}
+
+function wrapBlock(text: string, width: number): string[] {
+  const lines: string[] = [];
+  for (const line of text.split("\n")) {
+    if (line.length === 0) lines.push("");
+    else lines.push(...wrapTextWithAnsi(line, width));
+  }
+  return lines;
+}
+
+/**
+ * The approval dialog: header, the command, the reviewer's note, then the
+ * options. It stays compact so the session transcript above keeps its room: a
+ * long command is cut to a preview. Ctrl+O opens the full command in a
+ * scrolling viewer inside the dialog, because the transcript does not always
+ * hold it (a codemode script's calls show only the script).
+ */
+export class ApprovalPrompt {
+  private expanded = false;
+  private scrollTop = 0;
+  private maxScroll = 0;
+  private viewportRows = 0;
+
+  constructor(
+    private readonly opts: {
+      content: ApprovalPromptContent;
+      selector: OptionSelector;
+      theme: ApprovalPromptTheme;
+      terminalRows: () => number;
+      requestRender: () => void;
+    },
+  ) {}
+
+  invalidate(): void {
+    this.opts.selector.invalidate();
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, Key.ctrl("o"))) {
+      this.expanded = !this.expanded;
+      this.scrollTop = 0;
+      this.opts.requestRender();
+      return;
+    }
+    if (this.expanded) {
+      const page = Math.max(1, this.viewportRows - 1);
+      if (matchesKey(data, Key.pageUp)) return this.scrollBy(-page);
+      if (matchesKey(data, Key.pageDown)) return this.scrollBy(page);
+      if (matchesKey(data, Key.shift("up"))) return this.scrollBy(-1);
+      if (matchesKey(data, Key.shift("down"))) return this.scrollBy(1);
+    }
+    this.opts.selector.handleInput(data);
+  }
+
+  /** Scrolls the open viewer; otherwise the wheel falls through to the session. */
+  handleMouse(event: WheelEvent): { handled: true } | undefined {
+    if (!this.expanded || event.type !== "wheel" || !event.wheelDelta || this.maxScroll === 0) return undefined;
+    this.scrollBy(event.wheelDelta);
+    return { handled: true };
+  }
+
+  private scrollBy(lines: number): void {
+    const next = Math.max(0, Math.min(this.maxScroll, this.scrollTop + lines));
+    if (next === this.scrollTop) return;
+    this.scrollTop = next;
+    this.opts.requestRender();
+  }
+
+  private noteLines(width: number): string[] {
+    const { theme, content } = this.opts;
+    const yellow = noteYellow(theme);
+    const text = `${theme.bold(`${content.noteLabel}:`)} ${content.note}`;
+    const inner = Math.max(1, width - 2);
+    let lines = wrapBlock(text, inner);
+    if (this.expanded && lines.length > VIEWER_NOTE_ROWS) {
+      lines = lines.slice(0, VIEWER_NOTE_ROWS);
+      // Reflow the last kept row so the ellipsis always fits.
+      lines[VIEWER_NOTE_ROWS - 1] = truncateToWidth(`${lines[VIEWER_NOTE_ROWS - 1]} …`, inner, "…");
+    }
+    return lines.map((line) => `${yellow("▌ ")}${yellow(line)}`);
+  }
+
+  private preview(command: string[], width: number): string[] {
+    const { theme, content } = this.opts;
+    this.maxScroll = 0;
+    const cap = Math.max(MIN_PREVIEW_ROWS, Math.floor(this.opts.terminalRows() / 4));
+    if (command.length <= cap) return command;
+    const shown = cap - 1;
+    const where = content.inTranscript ? "ctrl+o view all, or scroll the session above" : "ctrl+o view all";
+    const more = `… ${command.length - shown} more lines · ${where}`;
+    return [...command.slice(0, shown), theme.fg("dim", truncateToWidth(more, width))];
+  }
+
+  private viewer(command: string[], width: number, fixedRows: number): string[] {
+    const budget = Math.max(MIN_PREVIEW_ROWS + fixedRows, this.opts.terminalRows() - RESERVED_ROWS);
+    // One row goes to the status line.
+    this.viewportRows = Math.max(MIN_VIEWER_ROWS, budget - fixedRows - 1);
+    this.maxScroll = Math.max(0, command.length - this.viewportRows);
+    this.scrollTop = Math.min(this.scrollTop, this.maxScroll);
+    const last = Math.min(command.length, this.scrollTop + this.viewportRows);
+    const status = `── lines ${this.scrollTop + 1}-${last} of ${command.length} · shift+↑↓/wheel scroll · ctrl+o collapse ──`;
+    return [...command.slice(this.scrollTop, last), this.opts.theme.fg("dim", truncateToWidth(status, width))];
+  }
+
+  render(width: number): string[] {
+    const w = Math.max(1, width);
+    const { theme, content } = this.opts;
+    const header = wrapBlock(`${noteYellow(theme)(theme.bold("●"))} ${content.header}`, w);
+    const note = this.noteLines(w);
+    const options = this.opts.selector.render(w);
+    const command = wrapBlock(content.command, w);
+    const fixedRows = header.length + 1 + 1 + note.length + 1 + options.length;
+    const commandRows = this.expanded ? this.viewer(command, w, fixedRows) : this.preview(command, w);
+    const lines = [...header, "", ...commandRows, "", ...note, "", ...options];
+    // A dock too short for the dialog clips from the top, keeping the options
+    // visible: Pi's layout scrolls a clipped component to its cursor line.
+    lines[lines.length - 1] = `${CURSOR_MARKER}${lines[lines.length - 1]}`;
+    return lines;
+  }
+}

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);
@@ -415,7 +445,13 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
         choice = await promptSelect(
           pi,
           ctx,
-          `${gate.label} — Auto Permissions needs approval\n\n${detail}\n\n${command}`,
+          {
+            header: `${gate.label} — Auto Permissions needs approval`,
+            command,
+            noteLabel: decisionSource === "guardian" ? "Guardian" : "Review failed",
+            note: detail,
+            inTranscript: scope.target.scriptToolCallId === undefined,
+          },
           permissionPromptOptions(config.evaluationLog.enabled),
           promptSignal,
         );
@@ -520,6 +556,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 +598,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 +614,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 +749,7 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
   });
 
   pi.on("turn_end", () => {
+    turnGeneration += 1;
     lastAssistantCalls = [];
     abandonSiblingReviews();
     endScripts();
@@ -755,6 +828,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 +874,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.20.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": [
@@ -61,6 +61,7 @@
     "widget-status.ts",
     "classify.ts",
     "prompt-select.ts",
+    "approval-prompt.ts",
     "review-display.ts",
     "review-scope.ts",
     "session-overrides.ts",

package/prompt-select.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { OptionSelector } from "@hank-warren/pi-permission-selector/selector.ts";
+import { ApprovalPrompt, type ApprovalPromptContent, approvalPromptText } from "./approval-prompt.js";
 
 /**
  * Tell Herdr this pane is waiting on a human, so a supervising agent can see
@@ -11,9 +12,9 @@ export function setHerdrBlocked(pi: ExtensionAPI, active: boolean, label?: strin
 }
 
 /**
- * Render an approval prompt with the shared `OptionSelector` through
- * `ctx.ui.custom()` (non-overlay, so it swaps into the editor area exactly
- * where `ctx.ui.select` used to render).
+ * Render an approval prompt — an `ApprovalPrompt` wrapping the shared
+ * `OptionSelector` — through `ctx.ui.custom()` (non-overlay, so it swaps into
+ * the editor area exactly where `ctx.ui.select` used to render).
  *
  * Cancellation parity with `ctx.ui.select` — all of these resolve
  * `undefined`, which every caller must treat as deny/cancel, never allow:
@@ -22,6 +23,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.
@@ -29,10 +34,11 @@ export function setHerdrBlocked(pi: ExtensionAPI, active: boolean, label?: strin
 export function promptSelect(
   pi: ExtensionAPI,
   ctx: ExtensionContext,
-  title: string,
+  content: ApprovalPromptContent,
   values: string[],
   signal: AbortSignal,
 ): Promise<string | undefined> {
+  if (ctx.mode === "rpc") return ctx.ui.select(approvalPromptText(content), values, { signal });
   return ctx.ui.custom<string | undefined>((tui, theme, _keybindings, done) => {
     let finished = false;
     const onAbort = () => finish(undefined);
@@ -43,7 +49,6 @@ export function promptSelect(
       done(result);
     };
     const selector = new OptionSelector({
-      title: `${theme.fg("warning", theme.bold("●"))} ${title}`,
       options: values.map((value) => ({ value, label: value })),
       allowComment: true,
       theme,
@@ -64,6 +69,12 @@ export function promptSelect(
     // `done` before the factory resolves is safe: pi marks the dialog closed
     // and never mounts the component.
     if (signal.aborted) onAbort();
-    return selector;
+    return new ApprovalPrompt({
+      content,
+      selector,
+      theme,
+      terminalRows: () => tui.terminal.rows,
+      requestRender: () => tui.requestRender(),
+    });
   });
 }

package/review-display.ts

@@ -76,7 +76,8 @@ export function createReviewDisplay(deps: { isSessionActive: () => boolean }): R
     if (ctx.mode !== "tui") return;
     const rows = [...active.values()];
     const shown = rows.length === 1 ? rows[0] : rows.length === 0 ? settled : undefined;
-    if (rows.length === 0 && !settled) {
+    // A lone review waiting on the human is shown by the approval dialog itself.
+    if ((rows.length === 0 && !settled) || shown?.state === "ask_user") {
       ctx.ui.setWidget(WIDGET_KEY, undefined);
       return;
     }

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;

package/widget-status.ts

@@ -84,8 +84,9 @@ export interface ReviewLinePalette {
 }
 
 /**
- * Render the widget content: one status line, plus a dim detail line only
- * when a guardian reason is present. The command is intentionally omitted —
+ * Render the widget content: one status line, plus a detail line behind a
+ * `▌` bar in the outcome's tone (the approval dialog's note style) only when
+ * a reason is present. The command is intentionally omitted —
  * it is already visible in the bash tool box above.
  */
 export function reviewStatusLines(
@@ -101,7 +102,7 @@ export function reviewStatusLines(
   const lines = [
     `${palette.header("auto permissions")} ${palette.muted(`· ${gateLabel} ·`)} ${status}`,
   ];
-  if (detail) lines.push(palette.muted(detail));
+  if (detail) lines.push(`${palette[frame.tone]("▌")} ${palette.muted(detail)}`);
   return lines;
 }