privateer-agent 0.2.1 → 0.3.1

package/src/engine/router.ts

@@ -1,165 +1,11 @@
-import type { LanguageModel, ModelMessage } from "ai";
-import type { Modality } from "../util/images.ts";
-
-export type { Modality };
-
-// The named routes the engine can switch between per turn. `default` is always
-// present (it's the session's configured model); the rest are optional specialized
-// targets resolved from the `router` config block.
-export type RouteName = "default" | "vision" | "document" | "audio" | "video" | "long" | "fast";
-
-// Routes that exist to satisfy a specific input modality, in the order we prefer them
-// when several could cover a turn's requirements.
-const MODALITY_ROUTES: { name: RouteName; modality: Modality }[] = [
-  { name: "vision", modality: "image" },
-  { name: "document", modality: "document" },
-  { name: "audio", modality: "audio" },
-  { name: "video", modality: "video" },
-];
-
-// A resolved, ready-to-stream model plus the per-model knobs that travel with it
-// (Anthropic caching/thinking depend on the model family, so they're per-route) and
-// the set of input modalities it accepts (so the router can satisfy a turn's needs).
-export interface Route {
-  spec: string; // "provider:model"
-  model: LanguageModel;
-  cacheControl: boolean;
-  thinkingBudget?: number;
-  label: string; // short display name for UI notices (the model id tail)
-  supports: Set<Modality>;
-}
-
-export interface RouteSet {
-  default: Route;
-  vision?: Route;
-  document?: Route;
-  audio?: Route;
-  video?: Route;
-  long?: Route;
-  fast?: Route;
-  longThreshold: number; // estimated tokens above which `long` applies
-  fastMaxChars: number; // prompt length at/below which `fast` applies
-}
-
-// What the current turn looks like, used to pick a route.
-export interface RouteSignals {
-  modalities: Set<Modality>; // input modalities anywhere in the conversation (sticky)
-  estTokens: number; // estimated tokens of the whole conversation
-  promptChars: number; // length of the new user prompt
-}
-
-export interface RouteSelection {
-  name: RouteName;
-  route: Route;
-  reason?: string; // short human reason, for the UI notice
-  missing?: Modality[]; // modalities the chosen route can't satisfy (warn)
-}
-
-function covers(route: Route | undefined, required: Set<Modality>): route is Route {
-  if (!route) return false;
-  for (const m of required) if (!route.supports.has(m)) return false;
-  return true;
-}
-
-function missingFrom(route: Route, required: Set<Modality>): Modality[] {
-  return [...required].filter((m) => !route.supports.has(m));
-}
-
-// Candidate routes to consider for an attachment-bearing turn, in preference order:
-// the dedicated modality routes first, then long/fast/default as fallbacks (they may
-// happen to be multimodal). Deduped by identity.
-function candidateRoutes(routes: RouteSet): Route[] {
-  const ordered = [
-    ...MODALITY_ROUTES.map((r) => routes[r.name]),
-    routes.long,
-    routes.fast,
-    routes.default,
-  ].filter((r): r is Route => Boolean(r));
-  return [...new Set(ordered)];
-}
-
-// Pick the model for this turn.
-//   • If the turn requires input modalities, choose the highest-preference route whose
-//     `supports` covers the whole union (capability is a hard requirement). If none
-//     fully covers, fall back to the route covering the most, flagging what's missing.
-//   • Otherwise apply the soft preferences: long (large context) > fast (short prompt)
-//     > default.
-export function selectRoute(routes: RouteSet, s: RouteSignals): RouteSelection {
-  if (s.modalities.size > 0) {
-    const candidates = candidateRoutes(routes);
-    const full = candidates.find((r) => covers(r, s.modalities));
-    if (full) {
-      const name = routeNameOf(routes, full);
-      return { name, route: full, reason: reasonFor(s.modalities) };
-    }
-    // No single route covers everything — pick the one that covers the most and warn.
-    let best = routes.default;
-    let bestMissing = missingFrom(best, s.modalities);
-    for (const r of candidates) {
-      const miss = missingFrom(r, s.modalities);
-      if (miss.length < bestMissing.length) {
-        best = r;
-        bestMissing = miss;
-      }
-    }
-    return {
-      name: routeNameOf(routes, best),
-      route: best,
-      reason: reasonFor(s.modalities),
-      missing: bestMissing,
-    };
-  }
-  if (routes.long && s.estTokens > routes.longThreshold) {
-    return { name: "long", route: routes.long, reason: "long context" };
-  }
-  if (routes.fast && s.promptChars <= routes.fastMaxChars) {
-    return { name: "fast", route: routes.fast, reason: "short prompt" };
-  }
-  return { name: "default", route: routes.default };
-}
-
-function reasonFor(modalities: Set<Modality>): string {
-  return `${[...modalities].join("+")} input`;
-}
-
-// Recover the route name for a resolved Route (for the UI/event). Falls back to
-// "default" if it isn't one of the named slots.
-function routeNameOf(routes: RouteSet, route: Route): RouteName {
-  const names: RouteName[] = ["vision", "document", "audio", "video", "long", "fast"];
-  for (const n of names) if (routes[n] === route) return n;
-  return "default";
-}
-
-const MEDIA_MODALITY: { test: RegExp; modality: Modality }[] = [
-  { test: /^image\//, modality: "image" },
-  { test: /^audio\//, modality: "audio" },
-  { test: /^video\//, modality: "video" },
-  { test: /^application\/pdf$/, modality: "document" },
-];
-
-function modalityOfMediaType(mediaType: string): Modality | null {
-  return MEDIA_MODALITY.find((m) => m.test.test(mediaType))?.modality ?? null;
-}
-
-// The input modalities present anywhere in the conversation. Keyed off the whole
-// history (not just the new message) so that once an attachment is in context,
-// follow-up turns stay on a model that can accept it rather than replaying it to one
-// that can't.
-export function requiredModalities(messages: ModelMessage[]): Set<Modality> {
-  const out = new Set<Modality>();
-  for (const m of messages) {
-    const content = m.content;
-    if (!Array.isArray(content)) continue;
-    for (const part of content) {
-      if (!part || typeof part !== "object" || !("type" in part)) continue;
-      const t = (part as { type: string }).type;
-      if (t === "image") out.add("image");
-      else if (t === "file") {
-        const mt = (part as { mediaType?: string }).mediaType;
-        const mod = mt ? modalityOfMediaType(mt) : null;
-        if (mod) out.add(mod);
-      }
-    }
-  }
-  return out;
-}
+// Route/modality types referenced by the EngineEvent `routed` variant.
+//
+// STUB — the full router (tree-cli/src/engine/router.ts) is DELETE in the
+// migration (Pi's model registry + our models.json generator replace it). Only
+// the two type names survive as part of the relay wire vocabulary, so they live
+// here as a types-only module until the `routed` event's producer is wired in a
+// later phase. Kept structurally identical to the original so events.ts ports
+// verbatim.
+export type Modality = "text" | "image" | "audio" | "video" | "pdf";
+
+export type RouteName = "default" | "vision" | "long-context" | "fast" | (string & {});

package/src/ext/permissionGate.ts

@@ -0,0 +1,216 @@
+// The permission gate — the safe-by-default moat, as a Pi extension.
+//
+// Phase 2. Ties together the ported policy: a `tool_call` hook classifies the
+// call (./…/classify.ts), runs it through the ModeGate policy engine
+// (./…/modeGate.ts → decideAuto), and blocks the tool when the decision is deny.
+// The gate SUSPENDS the turn while an approval is pending (spike-B proven), routes
+// to a LOCAL prompt (ctx.ui) or a REMOTE approver (the relay, Phase 4), and is
+// FAIL-CLOSED: any throw, timeout, or abort blocks the tool. A `tool_result` hook
+// redacts secrets from output before it reaches the model / relay.
+//
+// The load-bearing decision path is `decideToolCall`, kept pure and Pi-free so the
+// ported tests exercise it without a live session.
+
+import type { PermissionMode } from "../config/permissionMode.ts";
+import type { PermissionRequest } from "../permissions/gate.ts";
+import { ModeGate, type AskOutcome } from "../permissions/modeGate.ts";
+import { classifyToolCall } from "../permissions/classify.ts";
+import { redactText } from "../util/redact.ts";
+import { DEFAULT_DENYLIST } from "../permissions/danger.ts";
+
+// The per-tool_call hook context we read (structural subset of Pi's ctx — kept
+// local so the gate stays import-order-safe and unit-testable).
+export interface ToolCallCtx {
+  signal?: AbortSignal;
+  hasUI?: boolean;
+  mode?: "tui" | "rpc" | "json" | "print" | string;
+  // Pi's ExtensionUIContext shape (verified against pi-coding-agent 0.80):
+  // select(title, options: string[]) → chosen string | undefined; confirm(title, message).
+  ui?: {
+    select?: (title: string, options: string[], opts?: unknown) => Promise<string | undefined>;
+    confirm?: (title: string, message: string, opts?: unknown) => Promise<boolean>;
+  };
+}
+
+// Session-scoped state + askers. Mutable fields (mode/allowlist/allowedOutsideRoots)
+// persist across tool_calls; the askers are invoked per call.
+export interface GateController {
+  getMode(): PermissionMode;
+  setMode(mode: PermissionMode): void;
+  allowlist: string[];
+  allowedOutsideRoots: string[];
+  denylist?: string[];
+  cwd: string;
+  confineToCwd?: boolean;
+  getRemote?(): boolean;
+  getNoQuarter?(): boolean;
+  // Local interactive approval via the per-call ctx. Default provided below.
+  localAsk(req: PermissionRequest, ctx: ToolCallCtx): Promise<AskOutcome>;
+  // Remote (relay) approval. Optional until Phase 4; when absent, a remote turn
+  // falls back to localAsk.
+  remoteAsk?(req: PermissionRequest, signal?: AbortSignal): Promise<AskOutcome>;
+  // Secret redactor for tool output. Defaults to redactText.
+  redact?(text: string): string;
+  // Hard ceiling on waiting for a decision before failing closed.
+  approvalTimeoutMs?: number;
+}
+
+export interface GateBlock {
+  block: true;
+  reason: string;
+}
+
+// THE decision path. Classify → policy → decision, fail-closed on any error.
+// Returns a block directive to deny, or undefined to let the tool run.
+export async function decideToolCall(
+  ctrl: GateController,
+  toolName: string,
+  input: unknown,
+  ctx: ToolCallCtx,
+): Promise<GateBlock | undefined> {
+  const req = classifyToolCall(toolName, input, {
+    cwd: ctrl.cwd,
+    confineToCwd: ctrl.confineToCwd,
+    allowedOutsideRoots: ctrl.allowedOutsideRoots,
+  });
+  if (!req) return undefined; // no gate needed — read-only/in-scope/meta
+
+  // Route the ask: a remote-driven turn goes to the relay approver (if wired),
+  // otherwise the local UI. ModeGate decides *whether* to ask; this decides *who*.
+  const ask = (r: PermissionRequest): Promise<AskOutcome> =>
+    ctrl.getRemote?.() && ctrl.remoteAsk
+      ? ctrl.remoteAsk(r, ctx.signal)
+      : ctrl.localAsk(r, ctx);
+
+  const gate = new ModeGate({
+    getMode: ctrl.getMode,
+    setMode: ctrl.setMode,
+    allowlist: ctrl.allowlist,
+    allowedOutsideRoots: ctrl.allowedOutsideRoots,
+    // Default to the built-in dangerous-command patterns so bypass / no-quarter /
+    // headless-subagent runs still force dangerous shell + secret-exfil to "ask"
+    // (→ headless deny). A controller can extend, but never silently disable, this.
+    denylist: ctrl.denylist ?? DEFAULT_DENYLIST,
+    ask,
+    getRemote: ctrl.getRemote,
+    getNoQuarter: ctrl.getNoQuarter,
+  });
+
+  let decision: "allow" | "deny";
+  try {
+    decision = await withTimeout(gate.request(req), ctrl.approvalTimeoutMs, ctx.signal);
+  } catch (err) {
+    // Fail closed: a thrown/aborted/timed-out approval blocks the tool.
+    return {
+      block: true,
+      reason: `Approval unavailable (${(err as Error)?.message ?? "error"}) — blocked by default`,
+    };
+  }
+  if (decision === "deny") {
+    return { block: true, reason: `${req.title} denied by permission gate` };
+  }
+  return undefined;
+}
+
+// Default local asker: prompt via ctx.ui when a UI is present; fail closed
+// (deny) when headless (no UI) — the gate is the real safety, never auto-trust.
+// TODO(verify) the exact ctx.ui.select/confirm API shape against Pi when the TUI
+// is wired (Phase 6); coded defensively for now.
+const ALLOW_ONCE = "Allow once";
+const ALLOW_ALWAYS = "Allow and remember";
+const DENY = "Deny";
+
+export async function defaultLocalAsk(req: PermissionRequest, ctx: ToolCallCtx): Promise<AskOutcome> {
+  if (!ctx.hasUI || !ctx.ui) return "deny"; // headless → fail closed
+  const title = `${req.title}: ${req.detail}`;
+  if (typeof ctx.ui.select === "function") {
+    const choice = await ctx.ui.select(title, [ALLOW_ONCE, ALLOW_ALWAYS, DENY]);
+    if (choice === ALLOW_ONCE) return "allow";
+    if (choice === ALLOW_ALWAYS) return "always";
+    return "deny"; // Deny, or cancel (undefined)
+  }
+  if (typeof ctx.ui.confirm === "function") {
+    return (await ctx.ui.confirm("Permission", title)) ? "allow" : "deny";
+  }
+  return "deny";
+}
+
+// Build the extension factory. Pass to DefaultResourceLoader({ extensionFactories }).
+export function makePermissionGate(ctrl: GateController) {
+  const redact = ctrl.redact ?? redactText;
+  if (!ctrl.localAsk) ctrl.localAsk = defaultLocalAsk;
+
+  // Structural view of the Pi extension API surface we use (documented at
+  // pi.dev/docs/latest/extensions).
+  interface PiExtensionApi {
+    on(
+      event: "tool_call",
+      handler: (
+        event: { toolName: string; toolCallId: string; input: unknown },
+        ctx: ToolCallCtx,
+      ) => Promise<GateBlock | undefined>,
+    ): void;
+    on(
+      event: "tool_result",
+      handler: (
+        event: {
+          toolName: string;
+          toolCallId: string;
+          content: Array<{ type: string; text?: string; [k: string]: unknown }>;
+          details?: unknown;
+          isError?: boolean;
+        },
+        ctx: unknown,
+      ) => { content?: unknown[] } | undefined,
+    ): void;
+  }
+
+  return function permissionGate(pi: PiExtensionApi): void {
+    pi.on("tool_call", (event, ctx) => decideToolCall(ctrl, event.toolName, event.input, ctx));
+
+    // Redact secrets from tool output before it reaches the model / relay.
+    // tool_result delivers content PARTS (per the Pi extension contract), not a
+    // bare string — patch text parts and return a partial { content }; omitted
+    // fields keep their current values.
+    pi.on("tool_result", (event) => {
+      let touched = false;
+      const content = event.content.map((part) => {
+        if (typeof part.text === "string") {
+          const red = redact(part.text);
+          if (red !== part.text) touched = true;
+          return { ...part, text: red };
+        }
+        return part;
+      });
+      return touched ? { content } : undefined;
+    });
+  };
+}
+
+function withTimeout<T>(p: Promise<T>, ms: number | undefined, signal?: AbortSignal): Promise<T> {
+  if (!ms && !signal) return p;
+  return new Promise<T>((resolve, reject) => {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new Error("aborted"));
+    };
+    if (ms) timer = setTimeout(() => reject(new Error("approval timeout")), ms);
+    if (signal) {
+      if (signal.aborted) return onAbort();
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+    p.then(
+      (v) => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+        resolve(v);
+      },
+      (e) => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+        reject(e);
+      },
+    );
+  });
+}

package/src/main.ts

@@ -0,0 +1,32 @@
+// Entrypoint. The ONE ordering rule: import ./boot.ts first (env +
+// attestation dispatcher), then dynamically import everything Pi-touching so
+// boot's side effects are guaranteed to have run before any Pi module loads.
+//
+// Phase 1 skeleton: this prints the resolved boot state so `npm start` proves
+// the boot chain end-to-end (env pinned, dispatcher installed) without a TUI.
+// Phases 4/6 replace the body with the daemon/relay wiring and the pi-tui app.
+
+import "./boot.ts";
+
+async function main() {
+  // Only import Pi-touching / config code AFTER boot has run.
+  const { agentDir, globalDir } = await import("./config/paths.ts");
+  const { capturedHosts } = await import("pi-privacy/attest");
+
+  const home = globalDir();
+  const agent = process.env.PI_CODING_AGENT_DIR ?? agentDir();
+
+  console.log("privateer-agent 0.3 — boot skeleton");
+  console.log(`  PRIVATEER_HOME        ${home}`);
+  console.log(`  PI_CODING_AGENT_DIR   ${agent}`);
+  console.log(`  attestation dispatcher installed: yes`);
+  console.log(`  hosts attested so far: ${capturedHosts().size}`);
+  console.log("");
+  console.log("Phases 1–2 skeleton in place (adapter + gate promoted from pi-spike).");
+  console.log("Next: wire a real headless session — see docs/pi-migration-plan.md §2.");
+}
+
+main().catch((err) => {
+  console.error(err?.stack ?? err);
+  process.exit(1);
+});

package/src/permissions/classify.ts

@@ -0,0 +1,172 @@
+import { resolve, isAbsolute, relative } from "node:path";
+import { isProtectedPath } from "./protected.ts";
+import type { PermissionRequest } from "./gate.ts";
+
+// NEW glue for the Pi rewrite. In 0.2 each tool built its own PermissionRequest
+// before calling ctx.gate.request(). Pi's `tool_call` hook instead hands us
+// { toolName, input }, so the classification — which kind of action is this, does
+// it touch a protected/outside path — moves here. Field extraction is defensive
+// across Pi's builtin input shapes (command/cmd, path/file_path/file).
+//
+// Returns null when the call needs no gate (a read-only builtin acting inside
+// scope, or a known-safe meta tool): the hook then lets it run untouched, so
+// ordinary in-cwd work has zero friction.
+
+export interface ScopeOptions {
+  cwd: string;
+  confineToCwd?: boolean; // default true
+  allowedOutsideRoots?: string[];
+}
+
+function resolveInCwd(cwd: string, p: string): string {
+  return isAbsolute(p) ? p : resolve(cwd, p);
+}
+
+function isInsideDir(root: string, abs: string): boolean {
+  if (abs === root) return true;
+  const rel = relative(root, abs);
+  return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+
+// Outside the agent's working-directory scope? Only when confinement is on and the
+// path is neither inside cwd nor inside a session-approved outside root.
+export function isOutsideScope(scope: ScopeOptions, abs: string): boolean {
+  if (scope.confineToCwd === false) return false;
+  if (isInsideDir(scope.cwd, abs)) return false;
+  return !(scope.allowedOutsideRoots ?? []).some((root) => isInsideDir(root, abs));
+}
+
+function str(v: unknown): string {
+  return typeof v === "string" ? v : v == null ? "" : String(v);
+}
+
+function firstPath(input: Record<string, unknown>): string {
+  return str(input.path ?? input.file_path ?? input.file ?? input.filename ?? input.dir ?? input.directory);
+}
+
+// Known-safe read-only / meta builtins that never mutate and never leave the
+// machine: no gate regardless of arguments. Tunable — the conservative default for
+// anything NOT listed here is to ask (see below). TODO(verify) against Pi's full
+// builtin tool catalog as it's enumerated in Phase 5.
+const NON_GATED = new Set([
+  "todo", "todowrite", "todo_write", "todoread", "think", "plan_note",
+]);
+
+// Read-ish builtins: gated ONLY when the target resolves outside scope.
+const READ_TOOLS = new Set(["read", "cat", "grep", "find", "glob", "ls", "tree", "view"]);
+const EDIT_TOOLS = new Set(["edit", "edit_file", "str_replace", "str_replace_editor", "apply_patch", "patch"]);
+const WRITE_TOOLS = new Set(["write", "write_file", "create_file", "create", "save_attachment"]);
+const BASH_TOOLS = new Set(["bash", "shell", "run", "exec", "sh"]);
+
+export function classifyToolCall(
+  toolName: string,
+  input: unknown,
+  scope: ScopeOptions,
+): PermissionRequest | null {
+  const name = toolName.toLowerCase();
+  const obj: Record<string, unknown> =
+    input && typeof input === "object" ? (input as Record<string, unknown>) : {};
+
+  if (NON_GATED.has(name)) return null;
+
+  // Creating a routine is a persistent mutation; surface the trigger + delivery, and
+  // force a human decision (alwaysAsk) when it grants off-machine egress.
+  if (name === "create_routine" || name === "routine") {
+    const label = str(obj.name) || "routine";
+    const trigger = obj.cron ? `cron ${str(obj.cron)}` : obj.at ? `at ${str(obj.at)}` : "(no trigger)";
+    const delivery = Array.isArray(obj.delivery) ? (obj.delivery as unknown[]).map(String) : ["file"];
+    const egress: string[] = [];
+    if (delivery.includes("email")) egress.push("email leaves the machine");
+    if (delivery.some((d) => d.startsWith("webhook:"))) egress.push("posts to a webhook off-machine");
+    return {
+      tool: toolName,
+      kind: "write",
+      title: "Create routine",
+      detail: `${label}: ${trigger} → ${delivery.join(",")}${egress.length ? ` [${egress.join("] [")}]` : ""}`,
+      alwaysAsk: egress.length > 0,
+    };
+  }
+
+  // Shell — the whole command is the detail (danger scanning runs on it).
+  if (BASH_TOOLS.has(name)) {
+    const command = str(obj.command ?? obj.cmd ?? obj.script);
+    return { tool: toolName, kind: "bash", title: "Run command", detail: command };
+  }
+
+  // Write — create/overwrite a file.
+  if (WRITE_TOOLS.has(name)) {
+    const p = firstPath(obj);
+    const abs = resolveInCwd(scope.cwd, p);
+    const outside = isOutsideScope(scope, abs);
+    return {
+      tool: toolName,
+      kind: "write",
+      title: outside ? "Write outside working directory" : "Write file",
+      detail: outside ? abs : p,
+      protected: isProtectedPath(abs),
+      outside,
+      path: abs,
+    };
+  }
+
+  // Edit — modify an existing file.
+  if (EDIT_TOOLS.has(name)) {
+    const p = firstPath(obj);
+    const abs = resolveInCwd(scope.cwd, p);
+    const outside = isOutsideScope(scope, abs);
+    return {
+      tool: toolName,
+      kind: "edit",
+      title: outside ? "Edit outside working directory" : "Edit file",
+      detail: outside ? abs : p,
+      protected: isProtectedPath(abs),
+      outside,
+      path: abs,
+    };
+  }
+
+  // Read-ish — no gate in scope; when the target is outside scope, prompt.
+  if (READ_TOOLS.has(name)) {
+    const p = firstPath(obj);
+    if (!p) return null; // e.g. grep with no explicit path → in-cwd, no gate
+    const abs = resolveInCwd(scope.cwd, p);
+    if (!isOutsideScope(scope, abs)) return null;
+    return {
+      tool: toolName,
+      kind: "read",
+      title: "Read outside working directory",
+      detail: abs,
+      outside: true,
+      path: abs,
+    };
+  }
+
+  // Network reads (web fetch / search / http).
+  if (name.includes("fetch") || name.includes("web") || name.includes("http") || name.includes("url")) {
+    return {
+      tool: toolName,
+      kind: "fetch",
+      title: "Fetch from the network",
+      detail: str(obj.url ?? obj.query ?? obj.q),
+    };
+  }
+
+  // Unknown / custom / MCP tool: we can't prove it's side-effect-free, so
+  // safe-by-default is to prompt. Classified as a bash-kind action (asks in
+  // default/acceptEdits, denies in plan, allows only under bypass). Phase 5 refines
+  // this with MCP destructiveHint → alwaysAsk and a per-tool policy map.
+  return {
+    tool: toolName,
+    kind: "bash",
+    title: `Run ${toolName}`,
+    detail: safeJson(obj),
+  };
+}
+
+function safeJson(v: unknown): string {
+  try {
+    return JSON.stringify(v);
+  } catch {
+    return String(v);
+  }
+}

package/src/permissions/gate.ts

@@ -1,8 +1,10 @@
-// The permission gate is the seam between tools and the user's approval policy.
-// Tools call `gate.request(...)` before any mutation or shell execution; the gate
-// decides allow/deny based on the active permission mode (Phase 4) and may prompt
-// the user interactively. Phase 2 ships a pass-through gate so tools work
-// end-to-end; Phase 4 replaces it with the mode-aware interactive gate.
+// Permission-gate vocabulary — the request shape the policy reasons about, and
+// the decision it returns. Ported from tree-cli/src/permissions/gate.ts, trimmed
+// to types only: in the 0.2 codebase each tool built a PermissionRequest and
+// called ctx.gate.request(); in the Pi rewrite the gate is a `tool_call`
+// extension hook that receives { toolName, input } and derives the request via
+// classifyToolCall (see ./classify.ts). So the pass-through gate is gone; the
+// live policy lives in ./mode.ts + ./modeGate.ts.
 
 export type PermissionDecision = "allow" | "deny";
 
@@ -15,9 +17,9 @@ export interface PermissionRequest {
   detail: string; // the command, or file path + change preview
   protected?: boolean; // target is a guarded file: never auto-approve, always prompt
   // Always require a human decision, ABOVE bypass mode and the allowlist (like a
-  // dangerous shell command). Set for MCP tools that declare themselves
-  // destructive (destructiveHint), so even a "take no prisoners" run can't fire
-  // an irreversible external action silently. The decision is never remembered.
+  // dangerous shell command). Set for tools that declare themselves destructive,
+  // so even a "take no prisoners" run can't fire an irreversible action silently.
+  // The decision is never remembered.
   alwaysAsk?: boolean;
   // Target resolves outside the working directory: never auto-approve (unless bypass),
   // always prompt. `path` carries the absolute target so "always" can remember its dir.
@@ -25,16 +27,11 @@ export interface PermissionRequest {
   path?: string;
 }
 
+// Implemented by ModeGate (./modeGate.ts). The extension builds one per tool_call.
 export interface PermissionGate {
   request(req: PermissionRequest): Promise<PermissionDecision>;
 }
 
-export const autoApproveGate: PermissionGate = {
-  async request() {
-    return "allow";
-  },
-};
-
 export class PermissionDeniedError extends Error {
   constructor(tool: string) {
     super(`Permission denied for ${tool}`);

package/src/permissions/mode.ts

@@ -1,7 +1,11 @@
-import type { PermissionMode } from "../config/schema.ts";
+import type { PermissionMode } from "../config/permissionMode.ts";
 import type { PermissionRequest } from "./gate.ts";
 import { isDangerousCommand } from "./danger.ts";
 
+// Ported verbatim from tree-cli/src/permissions/mode.ts (only the PermissionMode
+// import path changed). This is the pure mode/allowlist policy the gate consults
+// before ever involving the user.
+
 export type AutoDecision = "allow" | "deny" | "ask";
 
 // Is a bash command covered by the allowlist? Entries are command prefixes:
@@ -27,7 +31,7 @@ export function decideAuto(
   // Dangerous shell (destructive / secret-exfil) always confirms — this sits
   // above bypass and the allowlist so an injected command can't run silently.
   if (req.kind === "bash" && isDangerousCommand(req.detail, denylist)) return "ask";
-  // Explicitly destructive actions (e.g. an MCP tool that declares destructiveHint)
+  // Explicitly destructive actions (e.g. a tool that declares destructiveHint)
   // always confirm too — also above bypass, so "skip permissions" can't fire them
   // blind.
   if (req.alwaysAsk) return "ask";