@signalridge/pi-approvals 0.0.0-stage → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 1.2.0
+
+Initial opt-in experimental human approval broker, with explicit pending command reviews, native RPC confirmations, and session-owned fail-closed cleanup.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 signalridge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# @signalridge/pi-approvals
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Opt-in experimental extension**, tested with Pi **1.0.4**. Loading it explicitly installs a session-scoped human approval broker. Root canonical native `edit`, `write`, `bash`, and public `user_bash` execution additionally require the human's explicit `--approvals-native-tools` certification. It does not enable itself or write global configuration. The independent `@signalridge/pi-approval-core` library owns the version-1 contract and reviewed factories.
+
+## Human workflow
+
+Proposed operations wait with an owned footer count. They do **not** open unsolicited dialogs, replace the editor, steal native/foreign dialog focus, or automatically ask a parent model for clarification.
+
+- `/approvals` or `/approvals list` lists pending IDs, source labels, and operation kinds.
+- `/approvals review <id>` or `/approvals approve <id>` opens a full bounded review and a human decision. Typing `approve <id>` without the command/confirmation does not authorize anything.
+- `/approvals deny <id>` closes exactly that request, including while a review/foreign dialog is open; denial opens no UI and never grants another request.
+
+Commands run while tools wait; no `waitForIdle` is used. In TUI mode a full-terminal public overlay shows the escaped full diff or exact command/CWD/source. Header/controls/body fit terminal bounds; narrow terminals use a fully scrollable document fallback, including at one column. **Ctrl+A** approves that one review; **Esc** denies; Up/Down/PgUp/PgDn/Home/End navigate the review. Enter does not approve. There is no automatic next review, so repeated approval keys cannot approve subsequent requests. A currently observed public native/extension dialog must close before a review opens. A synchronous, short-lived non-capturing public overlay bridge borrows the TUI, completing only after its native admission; the review then owns a raw overlay and closes only its identity handle, never the native pop-last callback. Later capturing and nonCapturing overlays therefore survive cancellation, denial, expiry and retirement: the cancelled review closes and releases its review lock without waiting for a foreign dialog to close. The foreign dialog retains focus and remains respondable. An unfocused review renders no rows, so native confirm/select/input questions are not obscured; focus transitions request a redraw and native focus restoration may safely resume the same review. Affirmative completion still requires the review's own focus. Normal editor draft/focus restoration belongs to the public custom-UI host contract; this extension never writes editor text.
+
+Reviews use lossless hard wrapping, never word wrapping that discards a separator. Over-wide or zero-column grapheme clusters and Thai/Lao AM characters rewritten by native output normalization are escaped by code point. The compact fallback additionally exposes preview whitespace as `\u{hex}` (including newlines) and doubles literal preview backslashes, so spaces, data newlines, soft wrapping and literal escape text remain distinguishable. The scrollable header labels this preview representation; operation bytes and hashes are unchanged. Layout is cached across scrolling, and invalidated on width or compact-mode changes. Regression coverage includes actual native terminal writes after normalization, not only pre-normalization composed snapshots.
+
+RPC uses the public native `confirm` transport when the human invokes the command. The client must display the full review and reply to the fresh `extension_ui_request.id` using `extension_ui_response`; lifecycle approval IDs and model text are not transport nonces. RPC clients must preserve human-only response ownership. A dialog timeout denies. Print/JSON/no-UI modes deny immediately, before native filesystem/process mutations.
+
+Each approval is per-operation. There is no allow-all mode or permission cache, no response tool, and no background conversion of built-in bash. Pending operations are immutable; the broker caps pending requests at 32, retains at most 128 metadata-only resolutions, and expires requests after five minutes. Caller cancellation, committed branch/session divergence, reload/invalidation, missing UI, callback errors, and peer retirement fail closed. Native rename/custom-entry appends and parallel results preserve append affinity using full branch-entry fingerprints. Vetoed navigation and aborted summaries do not retire an unchanged session. Committed `session_start` and `session_tree` bindings install fresh brokers and wrapper closures; captured old services remain permanently retired. Neither cancellation nor denial resolves another request.
+
+## Coverage and ownership
+
+A loaded extension always advertises one typed service, including before startup and after unavailable/collision/retirement failures; discovery reports no peer only when the extension is absent. Discovery checks broker liveness, including canonical binding, session/branch and UI availability, even when no request is pending. On retirement or liveness loss it advertises a distinct, present rejecting service, so previously captured post-approval launch guards fail permanently instead of authorizing work after asynchronous startup. An unavailable service never invites ungated fallback or reconnects an old capture. `/approvals` reports the root policy to the human.
+
+**Root certification is required:** `--approvals-native-tools` is a public boolean CLI flag, default **false**. The human certifies that canonical backends are the host's standard local native Pi backends. Without it, root canonical calls and user bash deny clearly, before process/filesystem mutation, and original backends are **not replaced**. The human service can still review independently integrated child/background operations that construct their own known native factories. The model cannot enable this policy through a tool.
+
+With certification, committed session bindings install reviewed definitions only for available admitted canonical tools. Missing/excluded tools are stronger host admission, never activated by this extension. Known selected extension/custom canonical collisions are rejected, not replaced. The exact current stricter active loadout is restored after late registration, including SDK initial allowlists and earlier Plan deactivations. Each canonical call must have a captured reviewed binding of that exact name with matching effective schema/description/source metadata; an empty or partial initial binding never admits a later canonical registration. Such arrivals are blocked, not silently rebound or added to this extension's loadout. Subsequent ownership loss of captured bindings blocks calls and retires requests. Each invocation also rechecks the exact tool's live active admission through post-approval IO, so a later Plan restriction withdraws pending ordinary writes without another approval or restoring excluded tools.
+
+**Public-SDK limitation:** Pi 1.0.4 labels `AgentSession.baseToolsOverride` backends `builtin:<name>`, even when their operations are custom, rejecting, or remote. Public metadata cannot certify backend provenance. The flag is explicit human certification, **not metadata proof**. SDK hosts with overridden backends must omit it and supply an explicit known-backend reviewed integration. Never use this flag to silently substitute unknown custom operations with local operations.
+
+Reviewed bash uses the core's **owned POSIX backend**, not SDK local-backend delegation. The native SDK still owns tool output/truncation. Ownership is rechecked after asynchronous CWD preparation before supervisor spawn and again immediately before command IPC dispatch; a short-lived process-group anchor/IPC reaper owns cancellation, timeout, descendant cleanup and host teardown without changing host signal behavior. Background group members cannot outlive the command. POSIX standalone Node.js with public SEA detection is required: Windows, Bun/compiled Pi, Node SEA applications and unknown interpreter capabilities are refused before approval or subprocess startup. Processes that deliberately escape the group are not sandboxed. See the core README for lifecycle qualifications; no post-dispatch rollback is promised.
+
+## Not a security boundary
+
+Approval is not an OS sandbox. Extensions and local event-bus callbacks are trusted same-process code. Command/mutation-shaped noncanonical calls (own `command`, or `path` plus content/edit properties, including one `input` envelope) and tools declaring these known schema properties even when optional are denied unless exactly one synchronous cooperative adapter advertises the current effective schema by object identity on `signalridge:approvals:adapter:v1`. See the core contract for validators and response shape. No source-name heuristic authorizes aliases; older command adapters without the capability are blocked. Unrelated metadata tools are not blanket-blocked.
+
+The root public hook has no post-handler check. Known schema properties are conservatively classified before later normalizers run; arbitrary unknown properties, schema compositions/references and arbitrary extension semantics are **not** a sandbox. This bounded policy does **not** detect arbitrary evaluation/execution in tools without known command/mutation shapes; those tools, child runtimes, MCP tools, and external processes need separately restricted admission or explicit integrations. Cooperative peers are trusted to gate their final backend operation and to attest only while their own context/binding remains live. Captured services fail closed; absence is not permission to bypass a previously loaded service.
+
+File reviews retain native edit BOM/CRLF/fuzzy/original-batch semantics. Limits: 256 KiB files/input, 64 KiB review, no clipped approval. Before synchronous diff generation, before/after together must have at most 2,048 line tokens counted by `split("\n").length` (including empty/trailing tokens); larger files fail without requesting approval or writing even for small edits. Invalid UTF-8/binary files and target symlink/hardlink aliases are rejected; display controls are explicitly escaped, actual byte hashes are complete. Stable ancestor symlinks are permitted with identity/realpath rechecks. Queue and post-review checks are not OS-atomic against external writers/aliases/processes. Approved write directory creation may remain after a subsequent failure/cancellation; no rollback is promised.
+
+Full reviewed changes/commands can contain secrets. The broker shows them only in human reviews; its pending notices, status, errors, and lifecycle metadata do not echo proposed credentials. Native SDK tool output/error behavior is retained. Loading third-party extensions remains a trust decision.

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@signalridge/pi-approvals",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.2.0",
+  "description": "Opt-in experimental human approval broker for canonical native Pi mutations and bash.",
+  "type": "module",
+  "license": "MIT",
+  "private": false,
+  "keywords": ["pi-package", "pi-extension", "pi", "approvals"],
+  "pi": { "extensions": ["./src/index.ts"] },
+  "piExtension": { "lifecycle": "experimental" },
+  "files": ["README.md", "LICENSE", "CHANGELOG.md", "src"],
+  "scripts": {
+    "lint": "biome check src/ test/ vitest.config.ts --error-on-warnings",
+    "format": "biome check --write src/ test/ vitest.config.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --config vitest.config.ts",
+    "check": "bun run lint && bun run typecheck && bun run test"
+  },
+  "dependencies": { "@signalridge/pi-approval-core": "^1.2.0" },
+  "peerDependencies": { "@earendil-works/pi-coding-agent": "*", "@earendil-works/pi-tui": "*", "typebox": "*" },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.0.4",
+    "@earendil-works/pi-ai": "1.0.4",
+    "@earendil-works/pi-tui": "1.0.4",
+    "typebox": "1.3.27",
+    "@biomejs/biome": "^2.5.7",
+    "@types/node": "^24.10.0",
+    "typescript": "^6.0.0",
+    "vitest": "^4.1.11"
+  },
+  "repository": { "type": "git", "url": "https://github.com/signalridge/pi-extensions", "directory": "packages/pi-approvals" },
+  "homepage": "https://github.com/signalridge/pi-extensions/tree/main/packages/pi-approvals",
+  "bugs": { "url": "https://github.com/signalridge/pi-extensions/issues" },
+  "publishConfig": { "access": "public" }
+}

package/src/broker.ts

@@ -0,0 +1,236 @@
+import { randomUUID } from "node:crypto";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  APPROVAL_LIFECYCLE_CHANNEL,
+  type ApprovalEvents,
+  type ApprovalLifecycle,
+  type ApprovalOperation,
+  type ApprovalOutcome,
+  type ApprovalRequestOptions,
+  type ApprovalService,
+  assertCurrent,
+  validateLifecycle,
+  validateOperation,
+} from "@signalridge/pi-approval-core";
+
+export const MAX_PENDING = 32;
+export const MAX_RETAINED = 128;
+export const REQUEST_TIMEOUT_MS = 5 * 60 * 1000;
+interface Pending {
+  readonly id: string;
+  readonly operation: ApprovalOperation;
+  readonly controller: AbortController;
+  readonly check: () => void;
+  readonly finish: (outcome: ApprovalOutcome) => void;
+  reviewing: boolean;
+}
+function fingerprint(ctx: ExtensionContext): readonly string[] {
+  return ctx.sessionManager.getBranch().map((entry) => JSON.stringify(entry));
+}
+function extendsBranch(before: readonly string[], after: readonly string[]): boolean {
+  return before.length <= after.length && before.every((entry, index) => entry === after[index]);
+}
+export class ApprovalBroker {
+  readonly service: ApprovalService;
+  readonly pending = new Map<string, Pending>();
+  readonly retained: ApprovalLifecycle[] = [];
+  private retired = false;
+  private reviewing = false;
+  private readonly boundManager: ExtensionContext["sessionManager"];
+  private readonly boundSession: string;
+  private branch: readonly string[];
+
+  constructor(
+    private readonly events: ApprovalEvents,
+    private readonly currentContext: () => ExtensionContext,
+    private readonly isBound: () => boolean,
+    private readonly timeoutMs = REQUEST_TIMEOUT_MS,
+  ) {
+    const initial = currentContext();
+    this.boundManager = initial.sessionManager;
+    this.branch = fingerprint(initial);
+    this.boundSession = JSON.stringify([
+      initial.sessionManager.getSessionId(),
+      initial.sessionManager.getSessionFile(),
+    ]);
+    this.service = Object.freeze({
+      version: 1,
+      id: randomUUID(),
+      request: (operation: ApprovalOperation, options: ApprovalRequestOptions) => this.request(operation, options),
+    });
+  }
+  private emit(
+    id: string,
+    operation: ApprovalOperation,
+    phase: ApprovalLifecycle["phase"],
+    outcome?: ApprovalOutcome,
+  ): void {
+    const event = validateLifecycle({
+      version: 1,
+      serviceId: this.service.id,
+      requestId: id,
+      source: operation.source,
+      toolCallId: operation.toolCallId,
+      phase,
+      ...(outcome ? { outcome } : {}),
+    });
+    this.events.emit(APPROVAL_LIFECYCLE_CHANNEL, event);
+    if (phase === "resolved") {
+      this.retained.push(event);
+      if (this.retained.length > MAX_RETAINED) this.retained.shift();
+    }
+  }
+  retire(): void {
+    if (this.retired) return;
+    this.retired = true;
+    for (const item of this.pending.values()) item.finish("retired");
+  }
+  /** Discovery must observe retirement even after the last request has resolved. */
+  get isLive(): boolean {
+    try {
+      this.assertLive();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  private assertLive(): ExtensionContext {
+    if (this.retired) throw new Error("Approval service retired");
+    try {
+      if (!this.isBound()) throw new Error("Approval canonical tool bindings were replaced");
+      const ctx = this.currentContext();
+      if (
+        ctx.sessionManager !== this.boundManager ||
+        JSON.stringify([ctx.sessionManager.getSessionId(), ctx.sessionManager.getSessionFile()]) !== this.boundSession
+      )
+        throw new Error("Approval native session changed");
+      const branch = fingerprint(ctx);
+      if (!extendsBranch(this.branch, branch)) throw new Error("Approval native branch diverged");
+      this.branch = branch;
+      if (!ctx.hasUI || (ctx.mode !== "tui" && ctx.mode !== "rpc")) throw new Error("No human approval UI available");
+      return ctx;
+    } catch (error) {
+      this.retire();
+      throw error;
+    }
+  }
+  request(value: ApprovalOperation, options: ApprovalRequestOptions): Promise<void> {
+    try {
+      const operation = validateOperation(value);
+      if (
+        !options ||
+        typeof options.isCurrent !== "function" ||
+        (options.signal !== undefined && !(options.signal instanceof AbortSignal))
+      )
+        throw new Error("Invalid approval owner options");
+      assertCurrent(options);
+      const ctx = this.assertLive();
+      const manager = ctx.sessionManager;
+      const captured = fingerprint(ctx);
+      if (this.pending.size >= MAX_PENDING) throw new Error("Too many pending approvals");
+      const id = randomUUID();
+      const controller = new AbortController();
+      const check = () => {
+        assertCurrent(options);
+        const now = this.assertLive();
+        if (now.sessionManager !== manager || !extendsBranch(captured, fingerprint(now))) {
+          this.retire();
+          throw new Error("Approval native session or branch changed");
+        }
+      };
+      return new Promise<void>((resolve, reject) => {
+        let finished = false;
+        const onAbort = () => finish("cancelled");
+        const timer = setTimeout(() => finish("expired"), this.timeoutMs);
+        const monitor = setInterval(() => {
+          try {
+            check();
+          } catch {
+            finish("retired");
+          }
+        }, 100);
+        const finish = (outcome: ApprovalOutcome) => {
+          if (finished) return;
+          if (outcome === "approved") {
+            try {
+              check();
+            } catch {
+              outcome = "retired";
+            }
+          }
+          if (finished) return;
+          finished = true;
+          clearTimeout(timer);
+          clearInterval(monitor);
+          options.signal?.removeEventListener("abort", onAbort);
+          this.pending.delete(id);
+          controller.abort();
+          try {
+            this.emit(id, operation, "resolved", outcome);
+            this.status();
+          } catch {
+            outcome = "error";
+          }
+          if (outcome === "approved") resolve();
+          else reject(new Error(`Approval ${outcome}`));
+        };
+        this.pending.set(id, { id, operation, controller, check, finish, reviewing: false });
+        options.signal?.addEventListener("abort", onAbort, { once: true });
+        try {
+          check();
+          this.emit(id, operation, "waiting");
+          this.status();
+        } catch {
+          finish("error");
+        }
+      });
+    } catch (error) {
+      return Promise.reject(error);
+    }
+  }
+  private status(): void {
+    const ctx = this.currentContext();
+    if (ctx.hasUI)
+      ctx.ui.setStatus(
+        `approvals:${this.service.id}`,
+        this.pending.size ? `Approvals: ${this.pending.size} (/approvals)` : undefined,
+      );
+  }
+  /** Human command only. Never called from a tool or event-bus response. */
+  async review(
+    id: string,
+    ctx: ExtensionContext,
+    decide: (operation: ApprovalOperation, signal: AbortSignal) => Promise<boolean>,
+    deny = false,
+  ): Promise<void> {
+    const item = this.pending.get(id);
+    if (!item) throw new Error("Unknown pending approval");
+    if (!ctx.hasUI || (ctx.mode !== "tui" && ctx.mode !== "rpc")) throw new Error("No human approval UI available");
+    item.check();
+    // Denial opens no UI and may cancel this or another request while a review is open.
+    if (deny) {
+      try {
+        this.emit(id, item.operation, "respond", "denied");
+        item.finish("denied");
+      } catch (error) {
+        item.finish("error");
+        throw error;
+      }
+      return;
+    }
+    if (this.reviewing || item.reviewing) throw new Error("An approval review is already open");
+    this.reviewing = item.reviewing = true;
+    try {
+      const confirmed = await decide(item.operation, item.controller.signal);
+      if (!this.pending.has(id)) return;
+      item.check();
+      this.emit(id, item.operation, "respond", confirmed === true ? "approved" : "denied");
+      item.finish(confirmed === true ? "approved" : "denied");
+    } catch (error) {
+      item.finish("error");
+      throw error;
+    } finally {
+      this.reviewing = item.reviewing = false;
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,232 @@
+import { randomUUID } from "node:crypto";
+import type { ExtensionAPI, ExtensionContext, ToolDefinition, ToolInfo } from "@earendil-works/pi-coding-agent";
+import {
+  APPROVAL_QUERY_CHANNEL,
+  type ApprovalService,
+  captureApprovalService,
+  createApprovalBashOperations,
+  createApprovalToolDefinitions,
+  hashBytes,
+  queryApprovalAdapter,
+  requiresApprovalAdapter,
+  schemaRequiresApprovalAdapter,
+  validateQuery,
+} from "@signalridge/pi-approval-core";
+import type { TSchema } from "typebox";
+import { ApprovalBroker } from "./broker.js";
+import { confirmOperation } from "./review.js";
+
+const CANONICAL = ["edit", "write", "bash"] as const;
+const NATIVE_FLAG = "approvals-native-tools";
+function unavailable(): ApprovalService {
+  return Object.freeze({
+    version: 1,
+    id: randomUUID(),
+    request: async () => {
+      throw new Error("Approval session is unavailable or not yet bound");
+    },
+  });
+}
+function sameTool(a: ToolInfo, b: ToolInfo | undefined): boolean {
+  return b?.parameters === a.parameters && b.description === a.description && b.sourceInfo.path === a.sourceInfo.path;
+}
+export default function approvals(pi: ExtensionAPI): void {
+  pi.registerFlag(NATIVE_FLAG, {
+    type: "boolean",
+    default: false,
+    description: "Certify canonical backends are standard local native Pi tools; allow reviewed native replacements",
+  });
+  let broker: ApprovalBroker | undefined;
+  let advertised = unavailable();
+  let context: ExtensionContext | undefined;
+  let bindings: readonly ToolInfo[] = [];
+  let bindingFailed = false;
+  let rootReason = "Root canonical calls require explicit --approvals-native-tools certification";
+  let promptDepth = 0;
+  pi.on("ui_prompt_start", () => {
+    promptDepth++;
+  });
+  pi.on("ui_prompt_end", () => {
+    promptDepth = Math.max(0, promptDepth - 1);
+  });
+  const getContext = () => {
+    if (!context) throw new Error("Approval session is not bound");
+    return context;
+  };
+  const isBound = (name?: string) => {
+    const all = pi.getAllTools();
+    return (
+      !bindingFailed &&
+      (name === undefined || bindings.some((captured) => captured.name === name)) &&
+      bindings.every((captured) =>
+        sameTool(
+          captured,
+          all.find((tool) => tool.name === captured.name),
+        ),
+      )
+    );
+  };
+  pi.events.on(APPROVAL_QUERY_CHANNEL, (value) => {
+    const query = validateQuery(value);
+    if (broker && advertised === broker.service && !broker.isLive) advertised = unavailable();
+    query.respond(advertised);
+  });
+  const bind = (ctx: ExtensionContext) => {
+    broker?.retire();
+    context = ctx;
+    bindingFailed = true;
+    rootReason = "Approvals unavailable while binding the session";
+    const previous = bindings;
+    bindings = [];
+    const next = new ApprovalBroker(pi.events, getContext, isBound);
+    broker = next;
+    advertised = next.service;
+    if (pi.getFlag(NATIVE_FLAG) !== true) {
+      bindingFailed = false;
+      rootReason =
+        "Root canonical calls require explicit --approvals-native-tools certification; original backends were not replaced";
+      return;
+    }
+    const existing = pi.getAllTools();
+    const admitted = CANONICAL.filter((name) => existing.some((tool) => tool.name === name));
+    for (const name of admitted) {
+      const tool = existing.find((candidate) => candidate.name === name);
+      if (
+        !tool ||
+        (tool.sourceInfo.path !== `builtin:${name}` &&
+          !previous.some((old) => old.name === name && sameTool(old, tool)))
+      ) {
+        bindingFailed = true;
+        rootReason = `Approvals reject custom canonical ${name}; its backend was not replaced`;
+        return;
+      }
+    }
+    const sessionId = ctx.sessionManager.getSessionId();
+    const settings = pi.getSettings();
+    const marker = `[Approval binding ${next.service.id}]`;
+    // Discovery calls broker.isLive: capture only AFTER synchronous bindings
+    // are complete, or bindingFailed would permanently retire the new broker.
+    let captured: ReturnType<typeof captureApprovalService>;
+    const [edit, write, bash] = createApprovalToolDefinitions({
+      source: "root",
+      request: (operation, options) => {
+        if (!captured || captured.service.id !== next.service.id) throw new Error("Approval service unavailable");
+        return captured.service.request(operation, options);
+      },
+      isCurrent: (callCtx) => {
+        if (!captured) return false;
+        captured.assertCurrent();
+        return (
+          broker === next &&
+          next.isLive &&
+          callCtx.hasUI &&
+          (callCtx.mode === "tui" || callCtx.mode === "rpc") &&
+          callCtx.sessionManager === ctx.sessionManager &&
+          callCtx.sessionManager.getSessionId() === sessionId &&
+          isBound()
+        );
+      },
+      isToolCurrent: (_ctx, name) => isBound(name) && pi.getActiveTools().includes(name),
+      shellPath: settings.shellPath,
+      commandPrefix: settings.shellCommandPrefix,
+    });
+    const active = pi.getActiveTools();
+    // SDK allowlists can reactivate existing tools even on defaultActive:false registration.
+    // Restore the exact current stricter loadout after all late registrations.
+    const register = <T extends TSchema, D, S>(definition: ToolDefinition<T, D, S>) => {
+      if (admitted.some((name) => name === definition.name))
+        pi.registerTool<T, D, S>({
+          ...definition,
+          defaultActive: false,
+          description: `${definition.description}\n${marker}`,
+        });
+    };
+    register(edit);
+    register(write);
+    register(bash);
+    pi.setActiveTools(active);
+    bindings = pi.getAllTools().filter((tool) => admitted.some((name) => name === tool.name));
+    bindingFailed = bindings.length !== admitted.length || !bindings.every((tool) => tool.description.includes(marker));
+    rootReason = bindingFailed ? "Approvals lost canonical tool ownership (extension collision/load order)" : "";
+    if (!bindingFailed) captured = captureApprovalService(pi.events);
+  };
+  pi.on("session_start", (_event, ctx) => bind(ctx));
+  pi.on("session_tree", (_event, ctx) => bind(ctx));
+  pi.on("session_shutdown", () => broker?.retire());
+  pi.on("tool_call", (event) => {
+    if (CANONICAL.some((name) => name === event.toolName)) {
+      if (!broker || rootReason || !isBound(event.toolName)) {
+        if (!isBound()) broker?.retire();
+        return { block: true, reason: rootReason || "Approvals unavailable or canonical binding replaced" };
+      }
+    } else {
+      const effective = pi.getAllTools().find((tool) => tool.name === event.toolName);
+      // Root public hooks have no post-handler boundary. Require the adapter
+      // before later normalizers can populate known optional schema properties.
+      if (requiresApprovalAdapter(event.input) || (effective && schemaRequiresApprovalAdapter(effective.parameters))) {
+        try {
+          if (!effective) throw new Error("No effective tool binding");
+          queryApprovalAdapter(pi.events, event.toolName, effective.parameters);
+        } catch {
+          return {
+            block: true,
+            reason:
+              "Command/mutation-shaped tool requires exactly one live cooperative approval adapter; unreviewed fallback is blocked",
+          };
+        }
+      }
+    }
+  });
+  pi.on("user_bash", (event, ctx) => {
+    const owner = broker;
+    if (rootReason || !owner || !isBound()) throw new Error(rootReason || "Approvals unavailable for user bash");
+    const captured = captureApprovalService(pi.events);
+    if (!captured || captured.service.id !== owner.service.id)
+      throw new Error("Approval service unavailable for user bash");
+    const settings = pi.getSettings();
+    return {
+      operations: createApprovalBashOperations({
+        source: "user-bash",
+        toolCallId: randomUUID(),
+        inputHash: hashBytes(JSON.stringify({ command: event.command, cwd: event.cwd })),
+        request: (operation, options) => captured.service.request(operation, options),
+        isCurrent: () => {
+          captured.assertCurrent();
+          return (
+            broker === owner &&
+            owner.isLive &&
+            ctx.sessionManager === getContext().sessionManager &&
+            isBound("bash") &&
+            pi.getActiveTools().includes("bash")
+          );
+        },
+        shellPath: settings.shellPath,
+      }),
+    };
+  });
+  pi.registerCommand("approvals", {
+    description: "List pending human approvals and root policy; review <id>, approve <id>, or deny <id>",
+    handler: async (args, ctx) => {
+      if (!ctx.hasUI || !broker) throw new Error("No human approval UI available");
+      const [action, id, extra] = args.trim().split(/\s+/u);
+      if (!action || action === "list") {
+        const lines = [...broker.pending.values()].map(
+          (item) => `${item.id}  ${item.operation.source}  ${item.operation.kind}  /approvals review ${item.id}`,
+        );
+        ctx.ui.notify(
+          [
+            rootReason || "Root policy: reviewed native tools",
+            ...(lines.length ? lines : ["No pending approvals"]),
+          ].join("\n"),
+          "info",
+        );
+        return;
+      }
+      if (!id || extra || !["review", "approve", "deny"].includes(action))
+        throw new Error("Usage: /approvals [list | review <id> | approve <id> | deny <id>]");
+      if (action !== "deny" && promptDepth > 0)
+        throw new Error("Close the current native/extension dialog before reviewing approvals");
+      await broker.review(id, ctx, (operation, signal) => confirmOperation(ctx, operation, signal), action === "deny");
+    },
+  });
+}

package/src/review.ts

@@ -0,0 +1,214 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  type Component,
+  matchesKey,
+  type OverlayHandle,
+  type TUI,
+  truncateToWidth,
+  visibleWidth,
+} from "@earendil-works/pi-tui";
+import type { ApprovalOperation } from "@signalridge/pi-approval-core";
+
+const graphemes = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+/** Hard-wrap without discarding a separator at a word boundary. Compact views
+ * encode preview whitespace/backslashes so data newlines cannot look like soft
+ * wrapping, and a literal escape cannot impersonate an encoded separator. */
+function wrapReview(source: string, width: number, exactWhitespace: boolean): string[] {
+  const lines: string[] = [];
+  let line = "";
+  let columns = 0;
+  const append = (value: string) => {
+    for (const { segment } of graphemes.segment(value)) {
+      const size = visibleWidth(segment);
+      if (columns + size > width && line) {
+        lines.push(line);
+        line = "";
+        columns = 0;
+      }
+      line += segment;
+      columns += size;
+    }
+  };
+  for (const { segment } of graphemes.segment(source)) {
+    if (segment === "\n") {
+      if (exactWhitespace) append("\\u{a}");
+      lines.push(line);
+      line = "";
+      columns = 0;
+      continue;
+    }
+    const size = visibleWidth(segment);
+    // Pi's output layer compatibility-decomposes Thai/Lao AM. Preserve the
+    // original source code points instead of approving a normalized lookalike.
+    const encodeCluster =
+      size === 0 ||
+      size > width ||
+      /[\u0e33\u0eb3]/u.test(segment) ||
+      (exactWhitespace && /\p{White_Space}/u.test(segment));
+    append(
+      encodeCluster
+        ? Array.from(segment, (char) => `\\u{${char.codePointAt(0)?.toString(16)}}`).join("")
+        : exactWhitespace
+          ? segment.replaceAll("\\", "\\\\")
+          : segment,
+    );
+  }
+  lines.push(line);
+  return lines;
+}
+
+interface ReviewComponent extends Component {
+  focused: boolean;
+  reconcile(): void;
+  dispose(): void;
+}
+export function createReviewComponent(
+  tui: TUI,
+  operation: ApprovalOperation,
+  signal: AbortSignal,
+  done: (approved: boolean) => void,
+  canComplete: () => boolean = () => true,
+): ReviewComponent {
+  let offset = 0;
+  let height = 1;
+  let total = 1;
+  let finished = false;
+  let focused = false;
+  let decision: boolean | undefined;
+  const header = "APPROVAL REVIEW";
+  const controls = "Ctrl+A approve | Esc deny";
+  const scrolling = "Up/Down/PgUp/PgDn/Home/End scroll";
+  let layout: { width: number; compact: boolean; source: string; lines: string[] } | undefined;
+  const reconcile = () => {
+    if (finished || decision === undefined || !canComplete()) return;
+    finished = true;
+    done(signal.aborted ? false : decision);
+  };
+  const finish = (value: boolean) => {
+    if (finished) return;
+    decision = signal.aborted ? false : value;
+    reconcile();
+    tui.requestRender();
+  };
+  const abort = () => finish(false);
+  signal.addEventListener("abort", abort, { once: true });
+  if (signal.aborted) queueMicrotask(abort);
+  return {
+    get focused() {
+      return focused;
+    },
+    set focused(value: boolean) {
+      if (focused === value) return;
+      focused = value;
+      tui.requestRender();
+      // Native hideOverlay restores focus before its close callback finishes.
+      // Complete only afterward, never pop the foreign overlay in that stack operation.
+      if (value) queueMicrotask(reconcile);
+    },
+    reconcile,
+    render(width: number) {
+      // A native question can take focus without adding an overlay. Do not
+      // obscure it with a full-screen review that cannot receive its answer.
+      if (!focused || finished) return [];
+      width = Math.max(1, width);
+      const rows = Math.max(1, tui.terminal.rows);
+      const compact = width < 40 || rows < 6;
+      if (!layout || layout.width !== width || layout.compact !== compact || layout.source !== operation.preview) {
+        const prefix = compact
+          ? wrapReview(`${header}\n${controls}\n${scrolling}\nPreview whitespace/backslashes escaped`, width, false)
+          : [];
+        layout = {
+          width,
+          compact,
+          source: operation.preview,
+          lines: [...prefix, ...wrapReview(operation.preview, width, compact)],
+        };
+      }
+      const lines = layout.lines;
+      height = compact ? rows : rows - 4;
+      total = lines.length;
+      offset = Math.min(offset, Math.max(0, total - height));
+      const body = lines.slice(offset, offset + height);
+      queueMicrotask(reconcile);
+      if (compact) return body;
+      while (body.length < height) body.push("");
+      return [
+        header,
+        controls,
+        ...body,
+        scrolling,
+        `Lines ${offset + 1}-${Math.min(total, offset + height)}/${total}`,
+      ].map((line) => truncateToWidth(line, width, ""));
+    },
+    handleInput(data: string) {
+      if (finished) return;
+      if (signal.aborted) finish(false);
+      else if (focused && matchesKey(data, "ctrl+a")) finish(true);
+      else if (matchesKey(data, "escape")) finish(false);
+      else {
+        if (matchesKey(data, "up")) offset = Math.max(0, offset - 1);
+        if (matchesKey(data, "down")) offset += 1;
+        if (matchesKey(data, "pageUp")) offset = Math.max(0, offset - Math.max(1, height - 1));
+        if (matchesKey(data, "pageDown")) offset += Math.max(1, height - 1);
+        if (matchesKey(data, "home")) offset = 0;
+        if (matchesKey(data, "end")) offset = Math.max(0, total - height);
+        tui.requestRender();
+      }
+    },
+    invalidate() {},
+    dispose() {
+      finished = true;
+      signal.removeEventListener("abort", abort);
+    },
+  };
+}
+/** Human command only. Borrow the public TUI synchronously, then own an
+ * identity-addressed overlay, never a long-lived native pop-last callback. */
+export async function confirmOperation(
+  ctx: ExtensionContext,
+  operation: ApprovalOperation,
+  signal: AbortSignal,
+): Promise<boolean> {
+  if (!ctx.hasUI || signal.aborted) return false;
+  if (ctx.mode === "rpc")
+    return ctx.ui.confirm("Approve exactly this operation?", operation.preview, { signal, timeout: 60_000 });
+  if (ctx.mode !== "tui") return false;
+  let tui: TUI | undefined;
+  let finishBridge: (() => void) | undefined;
+  await ctx.ui.custom<void>(
+    (host, _theme, _keys, done) => {
+      tui = host;
+      finishBridge = done;
+      return { render: () => [], invalidate() {} };
+    },
+    // Native done pops the last overlay: complete synchronously only after
+    // admission, before any other interaction can interleave. Never touch the
+    // editor text, paste map, cursor or Undo history.
+    { overlay: true, overlayOptions: { nonCapturing: true }, onHandle: () => finishBridge?.() },
+  );
+  if (!tui || signal.aborted) return false;
+  const host = tui;
+  return new Promise<boolean>((resolve, reject) => {
+    let handle: OverlayHandle | undefined;
+    const component = createReviewComponent(
+      host,
+      operation,
+      signal,
+      (approved) => {
+        handle?.hide();
+        component.dispose();
+        resolve(approved);
+      },
+      () => handle !== undefined && (signal.aborted || handle.isFocused()),
+    );
+    try {
+      handle = host.showOverlay(component, { anchor: "top-left", width: "100%", maxHeight: "100%", margin: 0 });
+      component.reconcile();
+    } catch (error) {
+      handle?.hide();
+      component.dispose();
+      reject(error);
+    }
+  });
+}