@signalridge/pi-approval-core 0.0.0-stage → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 1.2.0
+
+Initial independent approval-core library: validated local service contract v1 and invocation-local reviewed native tool definitions.

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,27 @@
-# Temporary Holding Version
+# @signalridge/pi-approval-core
 
-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.
+Independent, side-effect-free library for local human-approval service discovery and reviewed native Pi tool definitions. Tested against Pi **1.0.4**; host modules are peers. Importing the library installs no extension, settings, listeners, tools, timers, or resources. Calling its factories/discovery functions is explicit.
+
+See [coreAPI.md](coreAPI.md) for the version-1 contract. This is intentionally separate from managed-subagent protocols. The service/request/factory/lifecycle shape remains API v1. Tool-call IDs are opaque bounded Unicode (including provider `|` and native nested `/n` identities), separate from strict source/service/request labels.
+
+`APPROVAL_ADAPTER_QUERY_CHANNEL`, `validateAdapterQuery`, `validateAdapter`, and `queryApprovalAdapter` support explicit cooperative command gates. Exactly one synchronous reply must identify the requested tool and its current effective schema **by object identity**; absent/duplicate/malformed/copied-schema replies deny. Cooperating extensions own their listeners and attest only for live owned gates. Importing this library never registers events. See the contract for the exact query/response shapes.
+
+These factories construct known local backends: public native SDK edit/write operations and an owned POSIX BashOperations backend. An SDK host must explicitly choose this integration; never use public `builtin:<name>` metadata as proof of an arbitrary overridden backend. The approvals extension's separate human `--approvals-native-tools` flag is not required by hosts constructing their own known factories.
+
+## Reviewed native tools
+
+`createApprovalToolDefinitions({ source, request, isCurrent, isToolCurrent?, shellPath?, commandPrefix? })` returns `[edit, write, bash]` definitions for `registerTool` or SDK `customTools`. The host supplies a human-owned request callback and a current-owner predicate retaining the same `captureApprovalService(...).assertCurrent` guard through post-approval IO. Optional `isToolCurrent(ctx, name)` rechecks exact-name binding/admission at each ownership boundary; omitted means no additional admission restriction for compatible hosts. Each invocation revalidates the final parameters with the SDK's schemas, then deep-clones/freezes them **before its first await**. Calls share no approval operation or context.
+
+- Edit uses the public SDK edit factory. Its supplied `readFile` captures exact original bytes; its `writeFile` reviews the actual SDK-generated output, including BOM, line endings, fuzzy matching, and original-file batch semantics. No edit algorithm is reimplemented. The transcript call renderer is a constant, width-clipped ASCII label: it never reads a file or generates a synchronous diff. Complete diffs appear only in human review.
+- Write supplies a no-op `mkdir`, reads a bounded existing/missing target, reviews the actual output, rechecks identity and bytes, then performs the real directory creation and write.
+- Both await approval **inside the SDK factory's existing mutation queue**. Never wrap these definitions in another `withFileMutationQueue`: that queue is non-reentrant and nested acquisition deadlocks. Different files can wait independently. Cancelled calls already queued wait for their predecessor, then fail without requesting approval and release their slot.
+- Bash reviews the exact final command/CWD received at `exec`, retaining the public SDK tool factory, output accumulation and truncation, **not** delegating to `createLocalBashOperations`. A named owned backend uses public `getShellConfig`/`getAgentDir` and Node APIs; after asynchronous read-only CWD access it checks ownership immediately before supervisor spawn and again immediately before command IPC dispatch. Supplied signal, timeout, environment and output callback identities/values are captured before review; default environments preserve the agent `bin` PATH convention. Configured shell arguments and argv/stdin command transport are preserved. The command input hash combines final command/CWD/timeout with the frozen input hash. `createApprovalBashOperations` also supports public `user_bash` interception.
+- The short-lived POSIX supervisor anchors the process group until direct-shell exit, timeout or cancellation, then reclaims remaining group members. IPC disconnect reclaims the group even if the host exits or is killed, without host signal handlers or reusable-PID tracking. Output callback failures reject only after cleanup. Host inherited output pipes drain for at most 250 ms after supervisor exit. Factories/imports start no processes/listeners/timers. This backend deliberately does **not** allow background group members to outlive the foreground command. Reviewed bash requires POSIX and standalone Node.js with the public `process.getBuiltinModule("node:sea").isSea()` probe returning false. Windows, Bun (including Bun-compiled Pi), Node SEA applications and runtimes without that probe are refused **before approval or any subprocess**; no interpreter probe launches the current executable. Other embedding runtimes are not qualified. Processes deliberately escaping the group/session are outside this trusted-process integration, not sandboxed or promised reclaimed. Liveness is checked until irreversible command IPC dispatch; retirement after dispatch cannot roll back a command's effects.
+
+## Bounds and limitations
+
+Files and final inputs are capped at 256 KiB; human review payloads at 64 KiB. Before entering the synchronous line diff, file reviews also require at most **2,048 combined line tokens** across before and after: each text uses `text.split("\n").length`, including the empty text token for a missing file and a trailing empty token after a terminal newline. This conservative work budget rejects even a small edit to a file exceeding it; split the operation into separately reviewed smaller files instead. The byte limits are unchanged. Oversized reviews fail, never approve clipped changes. Invalid UTF-8 and NUL-containing files are rejected. Display controls (including BOM, CR, tabs, bidi/format characters, and ANSI escapes) are shown explicitly as `\\u{hex}`; literal backslashes are doubled. Hashes cover complete actual bytes, not the escaped display.
+
+Target symlinks, nonregular files, and multiply-linked files are denied. Existing ancestor realpaths and lstat identities are captured/rechecked; stable ancestor symlinks are allowed. File identities and bytes are rechecked after approval and, for write, after mkdir. This is **not OS-atomic** against external writers, aliases, other processes, or separately loaded queue implementations. A write failure or cancellation after approved mkdir can leave directories behind; there is no atomic rollback claim.
+
+Approval is **not a sandbox**. Trusted extension callbacks and event-bus peers run in the same process and may access the filesystem or execute arbitrary code. Other execution tools, MCP tools, and external processes require separate restrictions. Human review can expose credentials contained in a proposed change; the library does not log them or send review payloads in lifecycle events.

package/coreAPI.md

@@ -0,0 +1,72 @@
+# Local approval API v1
+
+```ts
+const captured = captureApprovalService(rootPi.events); // capture before first await
+// undefined means no approval extension is loaded. The host decides whether ungated
+// operation is admissible; do not convert a present-but-failing peer into absence.
+const definitions = createApprovalToolDefinitions({
+  source: "child:owned-run-id",
+  request: (operation, options) => {
+    if (!captured) throw new Error("No human approval service");
+    return captured.service.request(operation, options);
+  },
+  isCurrent: (invocationContext) => {
+    if (!captured) return false;
+    captured.assertCurrent(); // SAME capture, including after post-approval IO
+    return callerStillOwns(invocationContext);
+  },
+  // Optional: isToolCurrent: (ctx, name) => exactBindingAndAdmissionStillCurrent(ctx, name),
+});
+// SDK: customTools: [...definitions]; do not copy/forward all child UI methods.
+```
+
+Reviewed bash additionally requires a POSIX standalone Node.js host with public SEA detection. Bun/compiled Pi, Node SEA and missing/unknown probe capabilities reject before the approval callback or any child process. Imports and factory creation remain resource-free, and edit/write do not invoke this bash-only runtime check. The implementation never probes interpreter compatibility by launching `process.execPath`.
+
+`ApprovalService = { readonly version: 1; readonly id: string; request(operation, options): Promise<void> }`.
+
+`ApprovalRequestOptions = { readonly signal?: AbortSignal; readonly isCurrent: () => boolean }`. This is the caller's **current** ownership predicate, not a saved boolean. False, cancellation, and callback exceptions deny. A captured service never reconnects to another peer after retirement.
+
+`ApprovalOperation` is readonly validated bounded data:
+
+- Common: `source`, `toolName`, `cwd`, `toolCallId`, SHA-256 `inputHash`, full bounded human `preview`.
+- `kind: "command"`: `command`; `toolName` is a strict identifier (up to 80 bytes), e.g. `bash` or an explicitly integrated background command tool. The adapter must supply the actual executed command/CWD, not an earlier hook proposal, and generate a truthful escaped preview of all relevant normalized inputs.
+- `kind: "write" | "edit"`: canonical matching `toolName`, absolute `filePath`, `before: ApprovalSnapshot | null`, `after: ApprovalSnapshot`. Edit cannot have a missing original. Snapshots contain exact `text`, `bytes`, and SHA-256 `sha256`; all are checked and frozen. Canonical definitions construct these from actual SDK IO.
+
+Kinds are finite; there is no model-callable response/approve tool. Service functions are human-owned trusted peer closures, **not serialized data**. This event bus is not a serialization or security boundary. Source/service/request labels use strict ASCII identifiers of at most 160 UTF-8 bytes. Provider-owned tool-call identifiers instead use `approvalToolCallId`: nonempty valid Unicode, at most 1024 UTF-8 bytes, preserved exactly without truncation or normalization. This accepts OpenAI Responses `call_…|fc_…` and native nested `/n` suffixes. Lifecycle validation uses the same opaque identity parser. Text is valid Unicode and bounded by UTF-8 byte length.
+
+`APPROVAL_QUERY_CHANNEL` is `signalridge:approvals:query:v1`. Query payload: frozen `{ version: 1, respond(service: unknown): void }`. Trusted peers must respond **synchronously**, with exactly `{ version: 1, id, request }`. No peer => undefined. Any malformed peer or more than one response => error, including duplicate responses from the same peer. Captures check object/function/id identity before and after requests and through the ownership callback while pending. Extensions own subscription registration and cleanup.
+
+`captureApprovalService(events)` returns `undefined` on absence, otherwise frozen `{ service, assertCurrent(): void }`. `service` has exactly the existing v1 shape. The synchronous guard checks the same original peer object, ID and request function with the same sticky retirement as requests, without requesting another human decision. An adapter with asynchronous startup after approval must carry this invocation-local guard to its irreversible dispatch boundary; missing, replaced, duplicate or malformed peers deny without reconnecting.
+
+`APPROVAL_LIFECYCLE_CHANNEL` is `signalridge:approvals:lifecycle:v1`. Payload:
+
+```ts
+{ version: 1, serviceId, requestId, source, toolCallId,
+  phase: "waiting" | "respond" | "resolved",
+  outcome?: "approved" | "denied" | "cancelled" | "retired" | "expired" | "error" }
+```
+
+Waiting has no outcome; respond/resolved require one. Lifecycle events contain bounded metadata only, never commands, diffs, credentials, or snapshots. `validateLifecycle` checks all fields. A child adapter may pause its owned default tool timeout on matching `source`/`toolCallId` waiting and resume on resolved. Events are observational, not authorization responses; approval time must not be conflated with native command timeout. Alternatively bracket the adapter's awaited request callback, which also covers discovery errors.
+
+## Cooperative command-tool capability
+
+`APPROVAL_ADAPTER_QUERY_CHANNEL` is `signalridge:approvals:adapter:v1`.
+
+```ts
+// Query (validated by validateAdapterQuery):
+{ version: 1, toolName: string, respond(value: unknown): void }
+// Response (validated by validateAdapter):
+{ version: 1, toolName: string, parameters: TSchema }
+```
+
+`queryApprovalAdapter(events, toolName, effectiveToolInfo.parameters)` requires exactly one **synchronous** valid response with the requested tool name and the **same schema object** as the current effective `ToolInfo.parameters`. None, duplicate, malformed, wrong-name, copied-schema, and asynchronous replies deny. Validators reject extra fields, prototypes, accessors, and unsupported versions. Tool names are strict ASCII tool identifiers, at most 256 UTF-8 bytes.
+
+A cooperating extension registers its own listener **after** registering its command tools. It responds only for schemas it owns while its context and effective binding remain live. Advertising this capability attests that the tool gates its final native command/CWD through the human service; it is not an authorization grant. The library registers no listeners. Source labels or names alone never establish capability. This is a trusted-extension integration boundary, not an OS sandbox. Older adapters without this protocol are blocked by the approvals extension for command-shaped calls.
+
+`requiresApprovalAdapter(input)` recognizes an own `command`, or `path` plus `content`/`edits`/known old/new-text properties, at the root or one `input` envelope. `schemaRequiresApprovalAdapter(parameters)` also recognizes those known own properties in the schema's root `properties` or one `input.properties`, even when optional. Neither evaluates arbitrary semantics or expands schema references/compositions. This conservative pre-invocation classification prevents known optional normalizer inputs bypassing a root policy without a public post-handler boundary. Managed hosts should additionally recheck actual mutable native arguments after downstream handlers using the originally captured execution name and effective schema.
+
+File factory review generation requires at most 2,048 combined `beforeText.split("\n").length + afterText.split("\n").length` tokens before synchronous diffing; missing before text is empty. Files/inputs remain 256 KiB and completed reviews 64 KiB. No partial review is approved.
+
+The service/request/factory/lifecycle API remains v1, with no added required fields. Root native-backend certification is a separate human CLI policy, not a model-callable permission and not required by factories constructed by a host that knows their backend.
+
+The extension requests no automatic UI: humans use `/approvals` while a tool is paused. Child SDK sessions have no UI by default. Hosts integrating the captured root service should exclude a separately inherited approval extension to avoid shadowing/headless double gates. Preserve stronger admission/Plan restrictions before injecting customTools. No managed-subagent protocol changes or child/background adapter implementations are part of this library.

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@signalridge/pi-approval-core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.2.0",
+  "description": "Side-effect-free local approval contracts and reviewed native Pi tool factories.",
+  "type": "module",
+  "license": "MIT",
+  "private": false,
+  "signalridgePackage": { "kind": "library" },
+  "exports": { ".": { "types": "./src/index.ts", "default": "./src/index.ts" } },
+  "files": ["README.md", "LICENSE", "CHANGELOG.md", "coreAPI.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"
+  },
+  "peerDependencies": { "@earendil-works/pi-coding-agent": "*", "typebox": "*" },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "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-approval-core" },
+  "homepage": "https://github.com/signalridge/pi-extensions/tree/main/packages/pi-approval-core",
+  "bugs": { "url": "https://github.com/signalridge/pi-extensions/issues" },
+  "publishConfig": { "access": "public" }
+}

package/src/adapters.ts

@@ -0,0 +1,115 @@
+import { IsSchema, type TSchema } from "typebox";
+import { type ApprovalEvents, boundedText } from "./contract.js";
+
+export const APPROVAL_ADAPTER_QUERY_CHANNEL = "signalridge:approvals:adapter:v1";
+export interface ApprovalAdapterQuery {
+  readonly version: 1;
+  readonly toolName: string;
+  readonly respond: (adapter: unknown) => void;
+}
+export interface ApprovalAdapter {
+  readonly version: 1;
+  readonly toolName: string;
+  /** Exact effective public ToolInfo.parameters object, not a copy. */
+  readonly parameters: TSchema;
+}
+function fields(value: unknown, names: string[]): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Invalid approval adapter");
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== null && prototype !== Object.prototype) throw new Error("Invalid approval adapter prototype");
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  if (
+    Reflect.ownKeys(descriptors).some((key) => typeof key !== "string" || !names.includes(key)) ||
+    names.some((key) => !descriptors[key] || !("value" in descriptors[key]))
+  )
+    throw new Error("Invalid approval adapter fields");
+  return value as Record<string, unknown>;
+}
+function toolName(value: unknown): string {
+  const name = boundedText(value, 256);
+  if (!/^[a-zA-Z][a-zA-Z0-9_.:-]*$/u.test(name)) throw new Error("Invalid approval adapter tool name");
+  return name;
+}
+export function validateAdapterQuery(value: unknown): ApprovalAdapterQuery {
+  const item = fields(value, ["version", "toolName", "respond"]);
+  if (item.version !== 1 || typeof item.respond !== "function") throw new Error("Invalid approval adapter query");
+  toolName(item.toolName);
+  return value as ApprovalAdapterQuery;
+}
+export function validateAdapter(value: unknown): ApprovalAdapter {
+  const item = fields(value, ["version", "toolName", "parameters"]);
+  if (item.version !== 1 || !IsSchema(item.parameters)) throw new Error("Invalid approval adapter capability");
+  toolName(item.toolName);
+  return value as ApprovalAdapter;
+}
+/** Conservative known input shapes; not detection of arbitrary execution or mutation. */
+export function requiresApprovalAdapter(input: unknown): boolean {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return false;
+  if (Object.hasOwn(input, "command")) return true;
+  if (
+    Object.hasOwn(input, "path") &&
+    ["content", "edits", "oldText", "newText", "old_text", "new_text"].some((key) => Object.hasOwn(input, key))
+  )
+    return true;
+  const nested = Object.getOwnPropertyDescriptor(input, "input");
+  return (
+    !!nested &&
+    "value" in nested &&
+    nested.value !== input &&
+    !!nested.value &&
+    typeof nested.value === "object" &&
+    (Object.hasOwn(nested.value, "command") ||
+      (Object.hasOwn(nested.value, "path") &&
+        ["content", "edits", "oldText", "newText", "old_text", "new_text"].some((key) =>
+          Object.hasOwn(nested.value, key),
+        )))
+  );
+}
+
+/** Known schema properties also require admission when optional inputs are
+ * filled by downstream normalizers. This is not arbitrary semantic detection.
+ * Only root properties and a single input-envelope are inspected, like inputs.
+ */
+export function schemaRequiresApprovalAdapter(parameters: TSchema): boolean {
+  const descriptor = Object.getOwnPropertyDescriptor(parameters, "properties");
+  const properties: unknown = descriptor && "value" in descriptor ? descriptor.value : undefined;
+  if (!properties || typeof properties !== "object" || Array.isArray(properties)) return false;
+  if (requiresApprovalAdapter(properties)) return true;
+  const envelope = Object.getOwnPropertyDescriptor(properties, "input");
+  if (!envelope || !("value" in envelope) || !envelope.value || typeof envelope.value !== "object") return false;
+  const nested = Object.getOwnPropertyDescriptor(envelope.value, "properties");
+  return !!nested && "value" in nested && requiresApprovalAdapter(nested.value);
+}
+
+/** Trusted cooperative gate attestation, not authorization or an OS sandbox. */
+export function queryApprovalAdapter(events: ApprovalEvents, name: string, parameters: TSchema): ApprovalAdapter {
+  toolName(name);
+  const responses: ApprovalAdapter[] = [];
+  let malformed = false;
+  let open = true;
+  try {
+    events.emit(
+      APPROVAL_ADAPTER_QUERY_CHANNEL,
+      Object.freeze({
+        version: 1,
+        toolName: name,
+        respond: (value: unknown) => {
+          if (!open) return;
+          try {
+            const adapter = validateAdapter(value);
+            if (adapter.toolName !== name || adapter.parameters !== parameters)
+              throw new Error("Adapter identity mismatch");
+            responses.push(adapter);
+          } catch {
+            malformed = true;
+          }
+        },
+      }),
+    );
+  } finally {
+    open = false;
+  }
+  if (malformed || responses.length !== 1)
+    throw new Error("Command tool requires exactly one live cooperative approval adapter");
+  return responses[0];
+}

package/src/bash-supervisor.mjs

@@ -0,0 +1,59 @@
+// One invocation, one POSIX process group. Keeping its leader alive through
+// shell exit/drain avoids ever signalling a released/reusable shell PID.
+// IPC disconnect also reclaims the group when the host exits or is killed,
+// without installing or changing signal handlers in the host.
+import { spawn } from "node:child_process";
+import { constants } from "node:os";
+
+let started = false;
+let finishing = false;
+let timeout;
+function killGroup() {
+  // This process is still the live group leader; never a saved foreign PID.
+  try {
+    process.kill(-process.pid, "SIGKILL");
+  } catch {
+    process.exit(1);
+  }
+}
+function finish(result) {
+  if (finishing) return;
+  finishing = true;
+  clearTimeout(timeout);
+  if (!process.connected) return killGroup();
+  // Deliver the status before killing our own group. Output continues to flow
+  // through inherited stdout/stderr, with a bounded drain in the host.
+  process.send(result, () => killGroup());
+}
+process.on("disconnect", killGroup);
+process.on("error", killGroup);
+process.on("message", (message) => {
+  if (message === "cancel") return killGroup();
+  if (started || !process.connected) return killGroup();
+  started = true;
+  const { shell, args, commandTransport, command, cwd, env, seconds } = message;
+  try {
+    const stdin = commandTransport === "stdin";
+    const child = spawn(shell, stdin ? args : [...args, command], {
+      cwd,
+      env,
+      detached: false,
+      stdio: [stdin ? "pipe" : "ignore", 1, 2],
+      windowsHide: true,
+    });
+    child.once("error", (error) => finish({ error: error.message }));
+    child.once("exit", (code, signal) => {
+      clearTimeout(timeout);
+      // Buffered output remains in the host pipe; descendants must not keep
+      // it open after the command exits. The host drains it before settling.
+      finish({ exitCode: code ?? (signal ? 128 + (constants.signals[signal] ?? 0) : 1) });
+    });
+    if (stdin) {
+      child.stdin.on("error", () => {});
+      child.stdin.end(command);
+    }
+    if (seconds !== undefined) timeout = setTimeout(() => finish({ error: `timeout:${seconds}` }), seconds * 1000);
+  } catch (error) {
+    finish({ error: error.message });
+  }
+});

package/src/contract.ts

@@ -0,0 +1,276 @@
+import { createHash } from "node:crypto";
+
+export const APPROVAL_VERSION = 1;
+export const APPROVAL_QUERY_CHANNEL = "signalridge:approvals:query:v1";
+export const APPROVAL_LIFECYCLE_CHANNEL = "signalridge:approvals:lifecycle:v1";
+export const MAX_FILE_BYTES = 256 * 1024;
+export const MAX_REVIEW_BYTES = 64 * 1024;
+export const MAX_INPUT_BYTES = 256 * 1024;
+
+export interface ApprovalEvents {
+  emit(channel: string, data: unknown): void;
+}
+export interface ApprovalRequestOptions {
+  readonly signal?: AbortSignal;
+  readonly isCurrent: () => boolean;
+}
+export interface ApprovalSnapshot {
+  readonly text: string;
+  readonly bytes: number;
+  readonly sha256: string;
+}
+interface OperationBase {
+  readonly source: string;
+  readonly toolName: string;
+  readonly cwd: string;
+  readonly toolCallId: string;
+  readonly inputHash: string;
+  readonly preview: string;
+}
+export type ApprovalOperation =
+  | (OperationBase & { readonly kind: "command"; readonly command: string })
+  | (OperationBase & {
+      readonly kind: "write" | "edit";
+      readonly toolName: "write" | "edit";
+      readonly filePath: string;
+      readonly before: ApprovalSnapshot | null;
+      readonly after: ApprovalSnapshot;
+    });
+export interface ApprovalService {
+  readonly version: 1;
+  readonly id: string;
+  request(operation: ApprovalOperation, options: ApprovalRequestOptions): Promise<void>;
+}
+export interface ApprovalQuery {
+  readonly version: 1;
+  readonly respond: (service: unknown) => void;
+}
+export type ApprovalPhase = "waiting" | "respond" | "resolved";
+export type ApprovalOutcome = "approved" | "denied" | "cancelled" | "retired" | "expired" | "error";
+export interface ApprovalLifecycle {
+  readonly version: 1;
+  readonly serviceId: string;
+  readonly requestId: string;
+  readonly source: string;
+  readonly toolCallId: string;
+  readonly phase: ApprovalPhase;
+  readonly outcome?: ApprovalOutcome;
+}
+
+function record(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Invalid approval object");
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) throw new Error("Invalid approval prototype");
+  if (Object.values(Object.getOwnPropertyDescriptors(value)).some((descriptor) => !("value" in descriptor)))
+    throw new Error("Invalid approval accessor");
+  return value as Record<string, unknown>;
+}
+function keys(value: Record<string, unknown>, allowed: string[]): void {
+  if (Reflect.ownKeys(value).some((key) => typeof key !== "string" || !allowed.includes(key)))
+    throw new Error("Unknown approval field");
+}
+export function boundedText(value: unknown, max: number): string {
+  if (
+    typeof value !== "string" ||
+    Buffer.byteLength(value) > max ||
+    /[\uD800-\uDFFF]/u.test(value.replace(/[\uD800-\uDBFF][\uDC00-\uDFFF]/gu, ""))
+  ) {
+    throw new Error("Invalid or oversized approval text");
+  }
+  return value;
+}
+export function approvalId(value: unknown): string {
+  const id = boundedText(value, 160);
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9._:/-]*$/u.test(id)) throw new Error("Invalid approval identity");
+  return id;
+}
+/** Provider-owned opaque identity: no normalization, truncation or ASCII restriction. */
+export function approvalToolCallId(value: unknown): string {
+  const id = boundedText(value, 1024);
+  if (!id) throw new Error("Empty approval tool-call identity");
+  return id;
+}
+export function hashBytes(value: string | Buffer): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+function hash(value: unknown): string {
+  if (typeof value !== "string" || !/^[a-f0-9]{64}$/u.test(value)) throw new Error("Invalid approval hash");
+  return value;
+}
+export function snapshot(buffer: Buffer): ApprovalSnapshot {
+  if (buffer.length > MAX_FILE_BYTES) throw new Error("File exceeds approval size limit");
+  const text = buffer.toString("utf8");
+  if (text.includes("\0") || !Buffer.from(text, "utf8").equals(buffer)) throw new Error("Binary or invalid UTF-8 file");
+  return Object.freeze({ text, bytes: buffer.length, sha256: hashBytes(buffer) });
+}
+function validateSnapshot(value: unknown): ApprovalSnapshot {
+  const item = record(value);
+  keys(item, ["text", "bytes", "sha256"]);
+  const verified = snapshot(Buffer.from(boundedText(item.text, MAX_FILE_BYTES)));
+  if (item.bytes !== verified.bytes || hash(item.sha256) !== verified.sha256) throw new Error("Invalid file snapshot");
+  return verified;
+}
+/** Escape display controls, including bidi/format characters, without removing changes. */
+export function escapeDisplay(text: string): string {
+  return text
+    .replace(/\\/gu, "\\\\")
+    .replace(/[\p{C}\p{Zl}\p{Zp}\p{Default_Ignorable_Code_Point}]/gu, (char) =>
+      char === "\n" ? "\n" : `\\u{${char.codePointAt(0)?.toString(16)}}`,
+    );
+}
+export function validateOperation(value: unknown): ApprovalOperation {
+  const item = record(value);
+  const base = {
+    source: approvalId(item.source),
+    cwd: boundedText(item.cwd, 4096),
+    toolCallId: approvalToolCallId(item.toolCallId),
+    inputHash: hash(item.inputHash),
+    preview: boundedText(item.preview, MAX_REVIEW_BYTES),
+  };
+  if (!base.cwd || !base.preview) throw new Error("Empty approval review");
+  if (/[\p{C}\p{Zl}\p{Zp}\p{Default_Ignorable_Code_Point}]/u.test(base.preview.replace(/\n/gu, "")))
+    throw new Error("Approval preview contains unescaped display controls");
+  const common = ["source", "cwd", "toolCallId", "inputHash", "preview", "kind", "toolName"];
+  if (item.kind === "command") {
+    keys(item, [...common, "command"]);
+    const toolName = boundedText(item.toolName, 80);
+    if (!/^[a-zA-Z][a-zA-Z0-9_.:-]*$/u.test(toolName)) throw new Error("Invalid approval tool name");
+    return Object.freeze({
+      ...base,
+      kind: "command",
+      toolName,
+      command: boundedText(item.command, MAX_INPUT_BYTES),
+    });
+  }
+  if ((item.kind === "edit" || item.kind === "write") && item.toolName === item.kind) {
+    keys(item, [...common, "filePath", "before", "after"]);
+    const before = item.before === null ? null : validateSnapshot(item.before);
+    if (item.kind === "edit" && !before) throw new Error("Edit requires an original file");
+    return Object.freeze({
+      ...base,
+      kind: item.kind,
+      toolName: item.kind,
+      filePath: boundedText(item.filePath, 4096),
+      before,
+      after: validateSnapshot(item.after),
+    });
+  }
+  throw new Error("Invalid approval operation kind");
+}
+export function validateLifecycle(value: unknown): ApprovalLifecycle {
+  const item = record(value);
+  keys(item, ["version", "serviceId", "requestId", "source", "toolCallId", "phase", "outcome"]);
+  if (
+    item.version !== 1 ||
+    typeof item.phase !== "string" ||
+    !["waiting", "respond", "resolved"].includes(item.phase) ||
+    (item.outcome !== undefined &&
+      (typeof item.outcome !== "string" ||
+        !["approved", "denied", "cancelled", "retired", "expired", "error"].includes(item.outcome))) ||
+    (item.phase === "waiting" ? item.outcome !== undefined : item.outcome === undefined)
+  )
+    throw new Error("Invalid approval lifecycle");
+  return Object.freeze({
+    version: 1,
+    serviceId: approvalId(item.serviceId),
+    requestId: approvalId(item.requestId),
+    source: approvalId(item.source),
+    toolCallId: approvalToolCallId(item.toolCallId),
+    phase: item.phase as ApprovalPhase,
+    ...(item.outcome ? { outcome: item.outcome as ApprovalOutcome } : {}),
+  });
+}
+export function validateQuery(value: unknown): ApprovalQuery {
+  const item = record(value);
+  keys(item, ["version", "respond"]);
+  if (item.version !== 1 || typeof item.respond !== "function") throw new Error("Invalid approval query");
+  return value as ApprovalQuery;
+}
+function validateService(value: unknown): ApprovalService {
+  const item = record(value);
+  keys(item, ["version", "id", "request"]);
+  if (item.version !== 1 || typeof item.request !== "function") throw new Error("Invalid approval service");
+  approvalId(item.id);
+  return value as ApprovalService;
+}
+function discover(events: ApprovalEvents): ApprovalService | undefined {
+  const peers: ApprovalService[] = [];
+  let malformed = false;
+  let open = true;
+  events.emit(
+    APPROVAL_QUERY_CHANNEL,
+    Object.freeze({
+      version: 1,
+      respond: (value: unknown) => {
+        if (!open) return;
+        try {
+          peers.push(validateService(value));
+        } catch {
+          malformed = true;
+        }
+      },
+    }),
+  );
+  open = false;
+  if (malformed) throw new Error("Malformed approval peer");
+  if (peers.length > 1) throw new Error("Duplicate approval services");
+  return peers[0];
+}
+export function assertCurrent(options: ApprovalRequestOptions): void {
+  if (
+    !options ||
+    typeof options.isCurrent !== "function" ||
+    (options.signal !== undefined && !(options.signal instanceof AbortSignal))
+  )
+    throw new Error("Invalid approval owner options");
+  if (options.signal?.aborted || options.isCurrent() !== true) throw new Error("Approval owner is cancelled or stale");
+}
+/** Local trusted callbacks, not a wire protocol or a serialization/security boundary. */
+export function queryApprovalService(events: ApprovalEvents): ApprovalService | undefined {
+  return captureApprovalService(events)?.service;
+}
+/** A launch may await after approval; retain the SAME peer guard through dispatch. */
+export function captureApprovalService(
+  events: ApprovalEvents,
+): { readonly service: ApprovalService; readonly assertCurrent: () => void } | undefined {
+  const peer = discover(events);
+  if (!peer) return undefined;
+  const id = peer.id;
+  const request = peer.request;
+  let retired = false;
+  const checkPeer = () => {
+    if (retired) throw new Error("Captured approval service retired");
+    try {
+      const current = discover(events);
+      if (!current || current !== peer || current.id !== id || current.request !== request)
+        throw new Error("Approval service unavailable or replaced");
+    } catch (error) {
+      retired = true;
+      throw error;
+    }
+  };
+  const service: ApprovalService = Object.freeze({
+    version: 1,
+    id,
+    request: async (operation: ApprovalOperation, options: ApprovalRequestOptions) => {
+      checkPeer();
+      assertCurrent(options);
+      const callerCurrent = options.isCurrent;
+      const owner = Object.freeze({
+        signal: options.signal,
+        isCurrent: () => {
+          checkPeer();
+          return callerCurrent() === true;
+        },
+      });
+      const response = request.call(peer, validateOperation(operation), owner);
+      if (!(response instanceof Promise) || (await response) !== undefined) {
+        retired = true;
+        throw new Error("Invalid approval service response");
+      }
+      checkPeer();
+      assertCurrent(owner);
+    },
+  });
+  return Object.freeze({ service, assertCurrent: checkPeer });
+}

package/src/files.ts

@@ -0,0 +1,170 @@
+import { constants } from "node:fs";
+import { access, lstat, mkdir, open, realpath, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { generateUnifiedPatch } from "@earendil-works/pi-coding-agent";
+import {
+  type ApprovalOperation,
+  type ApprovalRequestOptions,
+  assertCurrent,
+  escapeDisplay,
+  MAX_FILE_BYTES,
+  MAX_REVIEW_BYTES,
+  snapshot,
+  validateOperation,
+} from "./contract.js";
+
+interface Identity {
+  readonly path: string;
+  readonly token: string | null;
+}
+interface Capture {
+  readonly bytes: Buffer | null;
+  readonly identities: readonly Identity[];
+}
+function missing(error: unknown): boolean {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+async function identity(path: string, target: boolean): Promise<string | null> {
+  try {
+    const stat = await lstat(path);
+    if (target && (!stat.isFile() || stat.isSymbolicLink() || stat.nlink > 1))
+      throw new Error("Approval target must be a regular non-aliased file");
+    if (!target && !stat.isDirectory() && !stat.isSymbolicLink()) throw new Error("Invalid approval ancestor");
+    if (target && stat.size > MAX_FILE_BYTES) throw new Error("File exceeds approval size limit");
+    return JSON.stringify([
+      await realpath(path),
+      stat.dev,
+      stat.ino,
+      stat.mode,
+      ...(target ? [stat.size, stat.mtimeMs, stat.ctimeMs] : []),
+    ]);
+  } catch (error) {
+    if (missing(error)) return null;
+    throw error;
+  }
+}
+async function boundedRead(path: string): Promise<Buffer> {
+  const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.size > MAX_FILE_BYTES)
+      throw new Error("File exceeds approval size limit or is not regular");
+    const buffer = Buffer.alloc(MAX_FILE_BYTES + 1);
+    let count = 0;
+    while (count < buffer.length) {
+      const { bytesRead } = await handle.read(buffer, count, buffer.length - count, count);
+      if (!bytesRead) break;
+      count += bytesRead;
+    }
+    if (count > MAX_FILE_BYTES) throw new Error("File exceeds approval size limit");
+    const result = buffer.subarray(0, count);
+    snapshot(result);
+    return result;
+  } finally {
+    await handle.close();
+  }
+}
+async function capture(path: string): Promise<Capture> {
+  const identities: Identity[] = [];
+  const token = await identity(path, true);
+  identities.push({ path, token });
+  let parent = dirname(path);
+  while (true) {
+    identities.push({ path: parent, token: await identity(parent, false) });
+    const next = dirname(parent);
+    if (next === parent) break;
+    parent = next;
+  }
+  const bytes = token === null ? null : await boundedRead(path);
+  const result = { bytes, identities };
+  await recheck(result);
+  return result;
+}
+async function recheck(captured: Capture, directoriesCreated = false): Promise<void> {
+  for (const [index, item] of captured.identities.entries()) {
+    if (directoriesCreated && index > 0 && item.token === null) {
+      // These directories were absent during review and have just been created.
+      // This is not proof against an external writer racing mkdir/lstat/write.
+      if (!(await lstat(item.path)).isDirectory()) throw new Error("Created approval ancestor changed");
+    } else if ((await identity(item.path, index === 0)) !== item.token)
+      throw new Error("Approval target or ancestor changed");
+  }
+  const target = captured.identities[0];
+  if (!target) throw new Error("Missing approval capture");
+  if (captured.bytes && !(await boundedRead(target.path)).equals(captured.bytes))
+    throw new Error("Approval file contents changed");
+}
+export interface FileInvocation {
+  readonly kind: "write" | "edit";
+  readonly cwd: string;
+  readonly toolCallId: string;
+  readonly source: string;
+  readonly inputHash: string;
+  readonly options: ApprovalRequestOptions;
+  readonly request: (operation: ApprovalOperation, options: ApprovalRequestOptions) => Promise<void>;
+}
+function review(invocation: FileInvocation, path: string, before: Buffer | null, after: Buffer): ApprovalOperation {
+  const prior = before ? snapshot(before) : null;
+  const next = snapshot(after);
+  // Myers line diff is quadratic for disjoint inputs. Bound tokens BEFORE
+  // entering the synchronous SDK diff; byte/payload limits alone cannot do so.
+  // split includes a terminal empty token, deliberately a conservative count.
+  if ((prior?.text ?? "").split("\n").length + next.text.split("\n").length > 2048)
+    throw new Error(
+      "File exceeds approval review computational limit (2048 combined line tokens); changes were not clipped",
+    );
+  // Diff the escaped text so BOM, CRLF and invisible changes are explicit.
+  const patch = generateUnifiedPatch(escapeDisplay(path), escapeDisplay(prior?.text ?? ""), escapeDisplay(next.text));
+  const preview = `Source: ${invocation.source}\nCWD: ${escapeDisplay(invocation.cwd)}\nFile: ${escapeDisplay(path)}\nEscaped display (backslashes doubled; controls shown as \\u{hex})\nBefore: ${prior?.sha256 ?? "missing"}\nAfter: ${next.sha256}\n${patch}`;
+  if (Buffer.byteLength(preview) > MAX_REVIEW_BYTES)
+    throw new Error("Generated review exceeds approval size limit; changes were not clipped");
+  return validateOperation({
+    kind: invocation.kind,
+    toolName: invocation.kind,
+    source: invocation.source,
+    cwd: invocation.cwd,
+    toolCallId: invocation.toolCallId,
+    inputHash: invocation.inputHash,
+    filePath: path,
+    before: prior,
+    after: next,
+    preview,
+  });
+}
+/** Invocation-local operations. The SDK factory owns the only mutation queue. */
+export function createFileOperations(invocation: FileInvocation) {
+  let original: Capture | undefined;
+  return {
+    access: (path: string) => access(path, constants.R_OK | constants.W_OK),
+    // SDK write calls mkdir before writeFile: deliberately defer it until approval.
+    mkdir: async (_dir: string): Promise<void> => {},
+    readFile: async (path: string): Promise<Buffer> => {
+      assertCurrent(invocation.options);
+      original = await capture(path);
+      assertCurrent(invocation.options);
+      if (!original.bytes) throw new Error("Edit target disappeared");
+      return Buffer.from(original.bytes);
+    },
+    writeFile: async (path: string, content: string): Promise<void> => {
+      assertCurrent(invocation.options);
+      const captured = invocation.kind === "edit" ? original : await capture(path);
+      if (!captured) throw new Error("Edit did not capture its input");
+      const after = Buffer.from(content, "utf8");
+      if (after.toString("utf8") !== content) throw new Error("Invalid UTF-8 output");
+      const operation = review(invocation, path, captured.bytes, after);
+      await invocation.request(operation, invocation.options);
+      assertCurrent(invocation.options);
+      await recheck(captured);
+      assertCurrent(invocation.options);
+      if (invocation.kind === "write") {
+        await mkdir(dirname(path), { recursive: true });
+        // Failure after mkdir may leave directories behind; no rollback promise.
+        assertCurrent(invocation.options);
+        await recheck(captured, true);
+        assertCurrent(invocation.options);
+      }
+      await writeFile(path, after);
+      assertCurrent(invocation.options);
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./adapters.js";
+export * from "./contract.js";
+export { type ApprovalToolOptions, createApprovalBashOperations, createApprovalToolDefinitions } from "./tools.js";

package/src/local-bash.ts

@@ -0,0 +1,122 @@
+import { spawn } from "node:child_process";
+import { constants } from "node:fs";
+import { access } from "node:fs/promises";
+import { delimiter, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { type BashOperations, getAgentDir, getShellConfig } from "@earendil-works/pi-coding-agent";
+import { assertCurrent } from "./contract.js";
+import { assertOwnedBashRuntime } from "./local-runtime.js";
+
+/** Owned POSIX local backend; the SDK still owns tool/output/truncation behavior.
+ * A short-lived supervisor is the process-group lifetime anchor and IPC orphan
+ * reaper. No host signal handlers, private SDK helpers or saved-PID kills.
+ */
+export function createOwnedLocalBashOperations(isCurrent: () => boolean, shellPath?: string): BashOperations {
+  return {
+    async exec(command, cwd, execution) {
+      assertOwnedBashRuntime();
+      const { signal, timeout, onData } = execution;
+      if (timeout !== undefined && (!Number.isFinite(timeout) || timeout <= 0 || timeout * 1000 > 2147483647))
+        throw new Error("Invalid bash timeout");
+      const owner = { signal, isCurrent };
+      assertCurrent(owner);
+      const shell = getShellConfig(shellPath);
+      const env = { ...(execution.env ?? process.env) };
+      if (execution.env === undefined) {
+        const key = Object.keys(env).find((key) => key.toLowerCase() === "path") ?? "PATH";
+        const bin = join(getAgentDir(), "bin");
+        const path = env[key] ?? "";
+        if (!path.split(delimiter).includes(bin)) env[key] = [bin, path].filter(Boolean).join(delimiter);
+      }
+      const payload = { ...shell, args: [...shell.args], command, cwd, env, seconds: timeout };
+      try {
+        await access(cwd, constants.F_OK);
+      } catch {
+        throw new Error(`Working directory does not exist: ${cwd}\nCannot execute bash commands.`);
+      }
+      // Avoid allocating a supervisor for an owner already lost during CWD IO.
+      // User-command dispatch is separately guarded at the synchronous IPC send.
+      assertCurrent(owner);
+      const child = spawn(process.execPath, [fileURLToPath(new URL("./bash-supervisor.mjs", import.meta.url))], {
+        cwd,
+        env: {},
+        detached: true,
+        stdio: ["ignore", "pipe", "pipe", "ipc"],
+        windowsHide: true,
+      });
+      return new Promise<{ exitCode: number | null }>((resolve, reject) => {
+        let result: { exitCode?: number; error?: string } | undefined;
+        let failure: unknown;
+        let settled = false;
+        let drain: ReturnType<typeof setTimeout> | undefined;
+        const disconnect = () => {
+          if (child.connected) child.disconnect();
+        };
+        const onAbort = () => disconnect(); // supervisor kills only its STILL-OWNED group
+        const onDataSafe = (data: Buffer) => {
+          if (failure || settled) return;
+          try {
+            onData(data);
+          } catch (error) {
+            failure = error instanceof Error ? error : new Error("Bash output callback failed", { cause: error });
+            disconnect();
+          }
+        };
+        const onMessage = (value: unknown) => {
+          if (!value || typeof value !== "object") return;
+          if ("error" in value && typeof value.error === "string") result = { error: value.error };
+          else if ("exitCode" in value && typeof value.exitCode === "number") result = { exitCode: value.exitCode };
+        };
+        const finish = () => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(drain);
+          signal?.removeEventListener("abort", onAbort);
+          child.removeListener("message", onMessage);
+          child.removeListener("error", onError);
+          child.removeListener("exit", onExit);
+          child.removeListener("close", finish);
+          child.stdout?.removeListener("data", onDataSafe);
+          child.stderr?.removeListener("data", onDataSafe);
+          child.stdout?.destroy();
+          child.stderr?.destroy();
+          disconnect();
+          if (failure) reject(failure);
+          else if (signal?.aborted) reject(new Error("aborted"));
+          else if (result?.error) reject(new Error(result.error));
+          else if (result?.exitCode !== undefined) resolve({ exitCode: result.exitCode });
+          else reject(new Error("Owned bash supervisor terminated without a result"));
+        };
+        const onError = (error: Error) => {
+          failure = error;
+          disconnect();
+          if (!child.pid) finish();
+        };
+        const onExit = () => {
+          // No saved PID remains eligible for signalling after exit. Even
+          // descendants that escaped the group cannot hold our pipes forever.
+          signal?.removeEventListener("abort", onAbort);
+          drain = setTimeout(finish, 250);
+        };
+        child.on("message", onMessage);
+        child.once("error", onError);
+        child.once("exit", onExit);
+        child.once("close", finish);
+        child.stdout?.on("data", onDataSafe);
+        child.stderr?.on("data", onDataSafe);
+        signal?.addEventListener("abort", onAbort, { once: true });
+        if (signal?.aborted) onAbort();
+        else {
+          try {
+            assertCurrent(owner); // The helper has not received a user command before this dispatch.
+            child.send(payload, (error) => {
+              if (error) onError(error);
+            });
+          } catch (error) {
+            onError(error instanceof Error ? error : new Error("Bash IPC dispatch failed", { cause: error }));
+          }
+        }
+      });
+    },
+  };
+}

package/src/local-runtime.ts

@@ -0,0 +1,21 @@
+/** Do not execute a compiled application as though it were a JS interpreter.
+ * This pure capability check never probes by launching process.execPath and
+ * leaves edit/write factories usable on hosts whose bash runtime is refused. */
+export function assertOwnedBashRuntime(): void {
+  const unavailable = () => {
+    throw new Error(
+      "Reviewed local bash requires a POSIX standalone Node.js runtime with public SEA detection; Bun and compiled application runtimes are unsupported",
+    );
+  };
+  if (process.platform === "win32" || process.versions.bun || typeof process.getBuiltinModule !== "function")
+    unavailable();
+  const probe: unknown = process.getBuiltinModule("node:sea");
+  if (
+    !probe ||
+    typeof probe !== "object" ||
+    !("isSea" in probe) ||
+    typeof probe.isSea !== "function" ||
+    probe.isSea() !== false
+  )
+    unavailable();
+}

package/src/tools.ts

@@ -0,0 +1,199 @@
+import {
+  type BashOperations,
+  createBashToolDefinition,
+  createEditToolDefinition,
+  createWriteToolDefinition,
+  type ExtensionToolContext,
+} from "@earendil-works/pi-coding-agent";
+import type { TSchema } from "typebox";
+import { Value } from "typebox/value";
+import {
+  type ApprovalOperation,
+  type ApprovalRequestOptions,
+  approvalId,
+  approvalToolCallId,
+  assertCurrent,
+  boundedText,
+  escapeDisplay,
+  hashBytes,
+  MAX_INPUT_BYTES,
+  validateOperation,
+} from "./contract.js";
+import { createFileOperations } from "./files.js";
+import { createOwnedLocalBashOperations } from "./local-bash.js";
+import { assertOwnedBashRuntime } from "./local-runtime.js";
+
+export interface ApprovalToolOptions {
+  readonly source: string;
+  readonly request: (operation: ApprovalOperation, options: ApprovalRequestOptions) => Promise<void>;
+  /** Called against this invocation's captured context, before and after every gate. Errors deny. */
+  readonly isCurrent: (ctx: ExtensionToolContext) => boolean;
+  /** Optional live exact-name admission; rechecked through file IO and bash dispatch. */
+  readonly isToolCurrent?: (ctx: ExtensionToolContext, name: "edit" | "write" | "bash") => boolean;
+  readonly shellPath?: string;
+  readonly commandPrefix?: string;
+}
+function frozenInput<T>(input: T, schema: TSchema): T {
+  if (!Value.Check(schema, input)) throw new Error("Invalid final tool input schema");
+  const serialized = JSON.stringify(input);
+  boundedText(serialized, MAX_INPUT_BYTES);
+  const copy: T = JSON.parse(serialized);
+  function freeze(value: unknown): void {
+    if (value && typeof value === "object") {
+      for (const child of Object.values(value)) freeze(child);
+      Object.freeze(value);
+    }
+  }
+  freeze(copy);
+  return copy;
+}
+export function createApprovalBashOperations(options: {
+  readonly source: string;
+  readonly toolCallId: string;
+  readonly inputHash: string;
+  readonly request: ApprovalToolOptions["request"];
+  readonly isCurrent: () => boolean;
+  readonly shellPath?: string;
+}): BashOperations {
+  options = Object.freeze({ ...options });
+  const delegate = createOwnedLocalBashOperations(options.isCurrent, options.shellPath);
+  return {
+    exec: async (command, cwd, execution) => {
+      assertOwnedBashRuntime(); // Refuse compiled/unknown runtimes before asking a human or spawning.
+      // Own backend options as well as tool input: callers may retain and mutate
+      // the options/env while human review is pending. Keep signal identity.
+      execution = Object.freeze({
+        ...execution,
+        ...(execution.env === undefined ? {} : { env: Object.freeze({ ...execution.env }) }),
+      });
+      // Gate the final command/cwd received by the native backend, not tool_call input.
+      const owner = { signal: execution.signal, isCurrent: options.isCurrent };
+      assertCurrent(owner);
+      const operation = validateOperation({
+        kind: "command",
+        toolName: "bash",
+        source: options.source,
+        toolCallId: options.toolCallId,
+        inputHash: hashBytes(
+          JSON.stringify({ inputHash: options.inputHash, command, cwd, timeout: execution.timeout }),
+        ),
+        command,
+        cwd,
+        preview: `Source: ${options.source}\nCWD: ${escapeDisplay(cwd)}\nExact command (escaped controls, doubled backslashes):\n${escapeDisplay(command)}`,
+      });
+      await options.request(operation, owner);
+      assertCurrent(owner);
+      return delegate.exec(command, cwd, execution);
+    },
+  };
+}
+/** Definitions work with registerTool or SDK customTools. No registrations occur here. */
+export function createApprovalToolDefinitions(options: ApprovalToolOptions) {
+  options = Object.freeze({ ...options });
+  const source = approvalId(options.source);
+  const editBase = createEditToolDefinition("");
+  const writeBase = createWriteToolDefinition("");
+  const bashBase = createBashToolDefinition("");
+  const edit: typeof editBase = {
+    ...editBase,
+    // No IO/diff on the render path; complete diffs belong to human review.
+    renderCall: () => ({
+      render: (width) => ["edit (human approval required)".slice(0, Math.max(0, Math.floor(width)))],
+      invalidate() {},
+    }),
+    async execute(id, params, signal, update, ctx) {
+      const input = frozenInput(params, editBase.parameters);
+      if (
+        typeof input.path !== "string" ||
+        !Array.isArray(input.edits) ||
+        !input.edits.length ||
+        input.edits.some(
+          (item) =>
+            typeof item.oldText !== "string" ||
+            typeof item.newText !== "string" ||
+            Object.keys(item).some((key) => !["oldText", "newText"].includes(key)),
+        ) ||
+        Object.keys(input).some((key) => !["path", "edits"].includes(key))
+      )
+        throw new Error("Invalid final edit input");
+      const cwd = boundedText(ctx.cwd, 4096);
+      const owner = {
+        signal,
+        isCurrent: () =>
+          options.isCurrent(ctx) &&
+          (options.isToolCurrent === undefined || options.isToolCurrent(ctx, "edit") === true),
+      };
+      assertCurrent(owner);
+      const operations = createFileOperations({
+        kind: "edit",
+        cwd,
+        toolCallId: approvalToolCallId(id),
+        source,
+        inputHash: hashBytes(JSON.stringify(input)),
+        options: owner,
+        request: options.request,
+      });
+      return createEditToolDefinition(cwd, { operations }).execute(id, input, signal, update, ctx);
+    },
+  };
+  const write: typeof writeBase = {
+    ...writeBase,
+    async execute(id, params, signal, update, ctx) {
+      const input = frozenInput(params, writeBase.parameters);
+      if (
+        typeof input.path !== "string" ||
+        typeof input.content !== "string" ||
+        Object.keys(input).some((key) => !["path", "content"].includes(key))
+      )
+        throw new Error("Invalid final write input");
+      const cwd = boundedText(ctx.cwd, 4096);
+      const owner = {
+        signal,
+        isCurrent: () =>
+          options.isCurrent(ctx) &&
+          (options.isToolCurrent === undefined || options.isToolCurrent(ctx, "write") === true),
+      };
+      assertCurrent(owner);
+      const operations = createFileOperations({
+        kind: "write",
+        cwd,
+        toolCallId: approvalToolCallId(id),
+        source,
+        inputHash: hashBytes(JSON.stringify(input)),
+        options: owner,
+        request: options.request,
+      });
+      return createWriteToolDefinition(cwd, { operations }).execute(id, input, signal, update, ctx);
+    },
+  };
+  const bash: typeof bashBase = {
+    ...bashBase,
+    async execute(id, params, signal, update, ctx) {
+      const input = frozenInput(params, bashBase.parameters);
+      if (
+        typeof input.command !== "string" ||
+        (input.timeout !== undefined &&
+          (!Number.isFinite(input.timeout) || input.timeout <= 0 || input.timeout > 2147483.647)) ||
+        Object.keys(input).some((key) => !["command", "timeout"].includes(key))
+      )
+        throw new Error("Invalid final bash input");
+      const cwd = boundedText(ctx.cwd, 4096);
+      const operations = createApprovalBashOperations({
+        source,
+        toolCallId: approvalToolCallId(id),
+        inputHash: hashBytes(JSON.stringify(input)),
+        request: options.request,
+        isCurrent: () =>
+          options.isCurrent(ctx) &&
+          (options.isToolCurrent === undefined || options.isToolCurrent(ctx, "bash") === true),
+        shellPath: options.shellPath,
+      });
+      return createBashToolDefinition(cwd, {
+        operations,
+        commandPrefix: options.commandPrefix,
+        shellPath: options.shellPath,
+      }).execute(id, input, signal, update, ctx);
+    },
+  };
+  return [edit, write, bash] as const;
+}