pi-harness-delegate 0.6.1 → 0.7.0

package/extensions/run-registry.ts

@@ -17,7 +17,7 @@
  * `acquireRun`/`countActiveRuns` directly.
  */
 
-import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { agentDir } from './config.ts';
 
@@ -35,6 +35,23 @@ function isAlive(pid: number): boolean {
   }
 }
 
+/** A `.json.tmp` this old can't be an in-flight write — acquireRun renames it within microseconds. */
+export const STALE_TMP_MS = 60_000;
+
+/**
+ * Remove a leftover `<pid>-<harness>-<rand>.json.tmp` if its writer crashed between write and
+ * rename (embedded pid dead) or it's older than `STALE_TMP_MS`. A live writer's tmp is left alone.
+ */
+function reapTmp(full: string, name: string): void {
+  try {
+    const pid = Number(name.split('-', 1)[0]);
+    const dead = !Number.isInteger(pid) || pid <= 0 || !isAlive(pid);
+    if (dead || Date.now() - statSync(full).mtimeMs > STALE_TMP_MS) rmSync(full, { force: true });
+  } catch {
+    // best-effort (already renamed/removed by its writer, or unreadable)
+  }
+}
+
 export interface RunHandle {
   file: string;
 }
@@ -45,7 +62,17 @@ export function acquireRun(harness: string, mode: string): RunHandle | null {
     const dir = runsDir();
     mkdirSync(dir, { recursive: true });
     const file = join(dir, `${process.pid}-${harness}-${Math.random().toString(36).slice(2, 8)}.json`);
-    writeFileSync(file, JSON.stringify({ pid: process.pid, harness, mode, startedAt: Date.now() }));
+    // Write-then-rename so a concurrent countActiveRuns() never sees a half-written entry: it
+    // treats unparseable `.json` files as corrupt and deletes them, which would silently drop a
+    // live run's registration mid-write. `.tmp` files are invisible to it (it only reads `.json`).
+    const tmp = `${file}.tmp`;
+    try {
+      writeFileSync(tmp, JSON.stringify({ pid: process.pid, harness, mode, startedAt: Date.now() }));
+      renameSync(tmp, file);
+    } catch (err) {
+      rmSync(tmp, { force: true });
+      throw err;
+    }
     return { file };
   } catch {
     return null;
@@ -63,7 +90,7 @@ export function releaseRun(handle: RunHandle | null): void {
 }
 
 /** Count active runs across processes (optionally filtered to one harness), cleaning up
- *  entries left behind by dead processes. Returns 0 (never throws) if the registry is unreadable. */
+ *  entries — and abandoned `.json.tmp` writes — left behind by dead processes. Returns 0 (never throws) if the registry is unreadable. */
 export function countActiveRuns(harness?: string): number {
   let files: string[];
   try {
@@ -73,6 +100,12 @@ export function countActiveRuns(harness?: string): number {
   }
   let count = 0;
   for (const f of files) {
+    // only complete entries count — `<entry>.json.tmp` writes (see acquireRun) are skipped, but
+    // reaped once they're demonstrably abandoned (crashed writer), so they don't pile up forever
+    if (f.endsWith('.json.tmp')) {
+      reapTmp(join(runsDir(), f), f);
+      continue;
+    }
     if (!f.endsWith('.json')) continue;
     const full = join(runsDir(), f);
     try {

package/extensions/runner.ts

@@ -21,12 +21,63 @@ export interface RunHarnessOptions {
 export interface HarnessResult extends StreamedResult {
   streamedText: string;
   harness: string;
+  /** Set when the runner itself killed the run for exceeding `maxBudgetUsd` (host enforcement). */
+  budgetExceeded?: boolean;
+}
+
+/**
+ * Host-side `maxBudgetUsd` enforcement for a harness with no native budget flag: true once the
+ * harness's own streamed running total (`totalCostUsd`) goes over the cap. A harness that reports
+ * no cost (`null`) can never trip this — `delegate()` flags that budget as unenforced instead.
+ */
+export function isOverBudget(
+  harness: Harness,
+  maxBudgetUsd: number | undefined,
+  r: StreamedResult | null,
+  baselineUsd = 0,
+): boolean {
+  return r !== null && isCostOverBudget(harness, maxBudgetUsd, r.totalCostUsd, baselineUsd);
+}
+
+/**
+ * The cost-only core of `isOverBudget`. `baselineUsd` is subtracted first: a harness whose reported
+ * total is *session*-cumulative (opencode over ACP) already includes every prior turn's spend on a
+ * resume, so only the delta since this run started counts against this run's cap.
+ */
+export function isCostOverBudget(
+  harness: Harness,
+  maxBudgetUsd: number | undefined,
+  costUsd: number | null | undefined,
+  baselineUsd = 0,
+): boolean {
+  return (
+    maxBudgetUsd !== undefined &&
+    harness.nativeBudget !== true &&
+    typeof costUsd === 'number' &&
+    costUsd - baselineUsd > maxBudgetUsd
+  );
+}
+
+/** The result recorded for a run the host stopped over budget. */
+export function budgetStoppedResult(r: StreamedResult, streamedText: string): StreamedResult {
+  return {
+    ...r,
+    isError: true,
+    stopReason: 'budget_exceeded',
+    result: r.result || streamedText || '(stopped: budget exceeded)',
+  };
 }
 
 import { DEFAULT_TIMEOUT_MS } from './harnesses/types.ts';
 
 export function runHarness(opts: RunHarnessOptions): Promise<HarnessResult> {
   return new Promise((resolve, reject) => {
+    // Already cancelled (e.g. the user hit cancel while this run was still being set up) —
+    // never spawn a process just to kill it.
+    if (opts.signal?.aborted) {
+      reject(new Error('cancelled'));
+      return;
+    }
     const args = opts.harness.buildArgs({
       prompt: opts.prompt,
       cwd: opts.cwd,
@@ -48,17 +99,25 @@ export function runHarness(opts: RunHarnessOptions): Promise<HarnessResult> {
     const MAX_STREAMED = 5 * 1024 * 1024; // 5MB cap to prevent OOM on compromised harness
     const MAX_ACTIVITIES = 5000;
 
-    const finish = (r: StreamedResult) => {
+    const finish = (r: StreamedResult, budgetExceeded = false) => {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
+      opts.signal?.removeEventListener('abort', onAbort);
       const ttft = firstTokenAt !== null ? firstTokenAt - startAt : r.ttftMs;
-      resolve({ ...r, ttftMs: ttft, streamedText: state.streamedText, harness: opts.harness.name });
+      resolve({
+        ...r,
+        ttftMs: ttft,
+        streamedText: state.streamedText,
+        harness: opts.harness.name,
+        ...(budgetExceeded ? { budgetExceeded: true } : {}),
+      });
     };
     const fail = (err: Error) => {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
+      opts.signal?.removeEventListener('abort', onAbort);
       reject(err);
     };
 
@@ -90,6 +149,10 @@ export function runHarness(opts: RunHarnessOptions): Promise<HarnessResult> {
         // merge streamedText into result if empty
         if (!outcome.result.result) outcome.result.result = state.streamedText;
         state.result = outcome.result;
+        if (!settled && isOverBudget(opts.harness, opts.maxBudgetUsd, state.result)) {
+          proc.kill('SIGKILL');
+          finish(budgetStoppedResult(state.result, state.streamedText), true);
+        }
       }
     });
 
@@ -120,13 +183,12 @@ export function runHarness(opts: RunHarnessOptions): Promise<HarnessResult> {
     }, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
     timer.unref?.();
 
-    opts.signal?.addEventListener(
-      'abort',
-      () => {
-        proc.kill('SIGKILL');
-        fail(new Error('cancelled'));
-      },
-      { once: true },
-    );
+    // Removed again in finish()/fail() — a long-lived signal (e.g. one shared by a fan-out, or the
+    // tool call's own) must not accumulate a dead listener per run.
+    function onAbort(): void {
+      proc.kill('SIGKILL');
+      fail(new Error('cancelled'));
+    }
+    opts.signal?.addEventListener('abort', onAbort, { once: true });
   });
 }

package/extensions/subcommands.ts

@@ -0,0 +1,227 @@
+/** `/delegate list|status|config|config init` subcommand UIs. Split out of index.ts with no behavior change. */
+
+import { readdirSync } from 'node:fs';
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { Key, matchesKey, truncateToWidth } from '@earendil-works/pi-tui';
+import { aggregateSpend, formatSpend } from './activity.ts';
+import { activeCount } from './concurrency.ts';
+import {
+  buildConfigReport,
+  describeConfigSource,
+  getMaxConcurrent,
+  outputsDir as getOutputsDir,
+  legacyOutputsDir,
+  loadConfigWithSource,
+  nonDefaultConfig,
+  writeDelegateConfig,
+} from './config.ts';
+import { isProjectTrusted } from './engine.ts';
+import { ALIASES, detectAll, getHarness, HARNESS_NAMES, isKnownHarness } from './harnesses/registry.ts';
+import { readAllHistory } from './history.ts';
+import { type DelegateTemplate, loadTemplates } from './templates.ts';
+export function formatTemplateRow(t: DelegateTemplate): string {
+  const parts = [
+    t.name,
+    `[${t.permission}]`,
+    t.model ? `model=${t.model}` : '',
+    t.defaultTask ? '↳ default task' : '',
+    t.harness ? `(${t.harness})` : '',
+  ];
+  return `${parts.filter(Boolean).join('  ')}  —  ${t.description}`;
+}
+
+export async function showModes(ctx: ExtensionContext, harnessFilter?: string): Promise<void> {
+  const all = new Map<string, DelegateTemplate>();
+  const trusted = isProjectTrusted(ctx);
+  // collect from all harnesses if no filter
+  if (harnessFilter) {
+    for (const [k, v] of loadTemplates(ctx.cwd, harnessFilter, trusted)) all.set(k, v);
+  } else {
+    for (const h of [...HARNESS_NAMES, 'shared']) {
+      for (const [k, v] of loadTemplates(ctx.cwd, h, trusted)) if (!all.has(k)) all.set(k, v);
+    }
+    // also load without harness param
+    for (const [k, v] of loadTemplates(ctx.cwd, undefined, trusted)) if (!all.has(k)) all.set(k, v);
+  }
+  const rows = [...all.values()].map(formatTemplateRow);
+  if (!ctx.hasUI) {
+    process.stdout.write(`${rows.join('\n')}\n`);
+    return;
+  }
+  await ctx.ui.custom((tui, theme, _kb, done) => {
+    let offset = 0;
+    const height = 12;
+    return {
+      render(width: number): string[] {
+        const header = theme.fg(
+          'accent',
+          `delegate — modes${harnessFilter ? ` (${harnessFilter})` : ''} (↑↓ scroll · any key to close)`,
+        );
+        const visible = rows.slice(offset, offset + height);
+        return [header, ...visible.map(l => theme.fg('muted', truncateToWidth(l, width)))];
+      },
+      handleInput(data: string): void {
+        if (matchesKey(data, Key.up) && offset > 0) {
+          offset--;
+          tui.requestRender();
+        } else if (matchesKey(data, Key.down) && offset < rows.length - 1) {
+          offset++;
+          tui.requestRender();
+        } else {
+          done(undefined);
+        }
+      },
+      invalidate() {},
+    };
+  });
+}
+
+export async function showStatus(ctx: ExtensionContext, harnessFilter?: string): Promise<void> {
+  const { config: cfg, source } = loadConfigWithSource();
+  const detection = await detectAll();
+  const trusted = isProjectTrusted(ctx);
+  const allHarnesses = harnessFilter ? [harnessFilter].filter(h => isKnownHarness(h)) : HARNESS_NAMES;
+  const lines: string[] = [];
+  lines.push(`delegate — status${harnessFilter ? ` (${harnessFilter})` : ''}`);
+  lines.push(...describeConfigSource(source));
+  lines.push(`defaultHarness: ${cfg.defaultHarness} · defaultMode: ${cfg.defaultMode} · model: ${cfg.model ?? '—'}`);
+  lines.push(
+    `maxConcurrent: ${typeof cfg.maxConcurrent === 'number' ? cfg.maxConcurrent : JSON.stringify(cfg.maxConcurrent)} · maxTranscripts: ${cfg.maxTranscripts}`,
+  );
+  lines.push(
+    trusted
+      ? 'project trust: trusted — project-local templates (.pi/delegate/templates/) are loaded'
+      : "project trust: untrusted — project-local templates skipped (trust this project via pi's trust prompt, or set defaultProjectTrust, to load them)",
+  );
+  lines.push('');
+  lines.push('harness              binary   ok  version              outputs  templates  active');
+  lines.push('─'.repeat(78));
+  for (const h of harnessFilter ? allHarnesses : HARNESS_NAMES) {
+    const det = detection[h] ?? { ok: false };
+    const harness = getHarness(h);
+    const bin = harness?.binary ?? h;
+    const ver = det.version ? det.version.slice(0, 18) : det.hint ? '—' : '—';
+    const ok = det.ok ? '✓' : '✗';
+    let outputs = 0;
+    try {
+      outputs = readdirSync(getOutputsDir(h)).filter(f => f.endsWith('.md')).length;
+    } catch {}
+    let templates = 0;
+    try {
+      templates = loadTemplates(ctx.cwd, h, trusted).size;
+    } catch {}
+    // cross-process count via the file registry, combined with the in-process counter as a fallback
+    const active = activeCount(h);
+    const cap = getMaxConcurrent(cfg, h);
+    const activeCol = `${active}/${cap > 0 ? cap : '∞'}`;
+    const hint = !det.ok && det.hint ? `  ← ${det.hint}` : '';
+    lines.push(
+      `${h.padEnd(20)} ${bin.padEnd(8)} ${ok.padEnd(3)} ${ver.padEnd(20)} ${String(outputs).padEnd(8)} ${String(templates).padEnd(10)} ${activeCol}${hint}`,
+    );
+  }
+  const historyEntries = harnessFilter ? readAllHistory().filter(e => e.harness === harnessFilter) : readAllHistory();
+  const spend = aggregateSpend(historyEntries.map(e => ({ harness: e.harness, cost: e.cost })));
+  lines.push('');
+  lines.push('spend:');
+  for (const h of harnessFilter ? allHarnesses : HARNESS_NAMES) {
+    const s = spend.byHarness[h];
+    lines.push(`  ${h}: ${s ? formatSpend(s) : '$0.000 over 0 run(s)'}`);
+  }
+  if (!harnessFilter) lines.push(`  total: ${formatSpend(spend.total)}`);
+  if (!harnessFilter) {
+    const globalCap = getMaxConcurrent(cfg);
+    lines.push('');
+    lines.push(
+      `global active: ${activeCount()}/${globalCap > 0 ? globalCap : '∞'} · aliases: ${
+        Object.entries(ALIASES)
+          .map(([k, v]) => `${k}→${v}`)
+          .join(', ') || '—'
+      }`,
+    );
+    lines.push(`outputs dir: ${getOutputsDir()} (plus ${legacyOutputsDir()} legacy)`);
+  }
+  if (!ctx.hasUI) {
+    process.stdout.write(`${lines.join('\n')}\n`);
+    return;
+  }
+  await ctx.ui.custom((tui, theme, _kb, done) => {
+    let offset = 0;
+    const height = 14;
+    return {
+      render(width: number): string[] {
+        const header = theme.fg(
+          'accent',
+          `delegate status${harnessFilter ? ` — ${harnessFilter}` : ''} (↑↓ scroll · any key to close)`,
+        );
+        const visible = lines.slice(offset, offset + height);
+        return [header, ...visible.map(l => theme.fg('muted', truncateToWidth(l, width)))];
+      },
+      handleInput(data: string): void {
+        if (matchesKey(data, Key.up) && offset > 0) {
+          offset--;
+          tui.requestRender();
+        } else if (matchesKey(data, Key.down) && offset < lines.length - 1) {
+          offset++;
+          tui.requestRender();
+        } else done(undefined);
+      },
+      invalidate() {},
+    };
+  });
+}
+
+/**
+ * `/delegate config` — the discoverability gap `/delegate status`'s provenance line only hints at:
+ * shows exactly what was read from `settings.json` (or why it wasn't) plus the effective config
+ * with defaults filled in, formatted as a paste-ready JSON block under the `delegate` key. Print-
+ * only — writing is a separate, explicit action (`/delegate config init`, below), never triggered
+ * from this default view.
+ */
+export async function showConfig(ctx: ExtensionContext): Promise<void> {
+  const result = loadConfigWithSource();
+  const lines = ['delegate — config', '', ...buildConfigReport(result)];
+  if (!ctx.hasUI) {
+    process.stdout.write(`${lines.join('\n')}\n`);
+    return;
+  }
+  await ctx.ui.custom((tui, theme, _kb, done) => {
+    let offset = 0;
+    const height = 20;
+    return {
+      render(width: number): string[] {
+        const header = theme.fg('accent', `delegate config — ${result.source.file} (↑↓ scroll · any key to close)`);
+        const visible = lines.slice(offset, offset + height);
+        return [header, ...visible.map(l => theme.fg('muted', truncateToWidth(l, width)))];
+      },
+      handleInput(data: string): void {
+        if (matchesKey(data, Key.up) && offset > 0) {
+          offset--;
+          tui.requestRender();
+        } else if (matchesKey(data, Key.down) && offset < lines.length - 1) {
+          offset++;
+          tui.requestRender();
+        } else done(undefined);
+      },
+      invalidate() {},
+    };
+  });
+}
+
+/**
+ * `/delegate config init` — the one place this extension ever writes to `settings.json`, and only
+ * because a human explicitly typed this subcommand. Writes the current effective config (defaults
+ * merged with whatever was already on disk, minus anything still at its default — pinning defaults would
+ * stop later releases' default changes reaching the user) into the `delegate` key via `writeDelegateConfig()`
+ * (read-modify-write, atomic, refuses on an unparseable file rather than clobbering it). This is
+ * also the practical fix for the legacy-`claudeDelegate`-only gap `describeConfigSource` warns
+ * about: writing an explicit `delegate` key (with the correctly-resolved values already folded
+ * in — the legacy migration already ran before this point) makes it win from then on, without
+ * this command ever touching or deleting the old `claudeDelegate` key itself.
+ */
+export async function initConfig(ctx: ExtensionContext): Promise<void> {
+  const result = loadConfigWithSource();
+  const write = writeDelegateConfig(nonDefaultConfig(result.config));
+  const msg = write.ok ? `✓ ${write.message}` : `✗ ${write.message}`;
+  if (!ctx.hasUI) process.stdout.write(`${msg}\n`);
+  else ctx.ui.notify?.(msg, write.ok ? 'info' : 'warning');
+}

package/extensions/templates.ts

@@ -30,6 +30,8 @@ export interface DelegateTemplate {
   defaultScope?: string;
   /** Host-run shell command executed after the harness exits to check its claims (e.g. `bun test`). */
   verify?: string;
+  /** Extra directories the harness may access (`addDirs: ../shared, /opt/lib` — comma-separated). */
+  addDirs?: string[];
   prompt: string;
   harness?: string;
 }
@@ -65,6 +67,15 @@ export function normalizePermission(
   return { permission: 'edit', permissionMode: 'acceptEdits' };
 }
 
+/** Comma-separated frontmatter list (`a, b`) — undefined when absent or empty. */
+function parseList(raw: string | undefined): string[] | undefined {
+  const items = (raw ?? '')
+    .split(',')
+    .map(s => s.trim())
+    .filter(Boolean);
+  return items.length > 0 ? items : undefined;
+}
+
 /** Parse a template file: frontmatter (---\nkey: value\n---) + markdown body. */
 export function parseTemplate(text: string): DelegateTemplate | null {
   const m = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(text.trimStart());
@@ -98,6 +109,7 @@ export function parseTemplate(text: string): DelegateTemplate | null {
     defaultTask: meta.defaultTask || undefined,
     defaultScope: meta.defaultScope || undefined,
     verify: meta.verify || undefined,
+    addDirs: parseList(meta.addDirs),
     prompt: m[2].trim(),
     harness: meta.harness || undefined,
   };

package/extensions/validate.ts

@@ -0,0 +1,214 @@
+/**
+ * Input validation for values that end up on a harness's (or `gh`'s) command line.
+ *
+ * `sessionId`, `model`, and `pr` all reach `spawn()`/`pi.exec()` argv — no shell, so no shell
+ * injection, but a value starting with `-` would be parsed by the target CLI as a *flag* (argument
+ * injection: e.g. a `sessionId` of `--dangerously-bypass-…` or a `pr` of `--repo=evil/x`). These
+ * values are model-settable on the `delegate` tool, and the model's context is attacker-influenceable,
+ * so they're validated once at the shared `delegate()` entry (both tool and `/delegate` paths) and
+ * up front on fan-out — never left to each harness's `buildArgs`.
+ */
+
+import { realpathSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+
+const SESSION_ID_RE = /^[A-Za-z0-9._:-]{1,128}$/;
+const PR_NUMBER_RE = /^\d{1,10}$/;
+const PR_SHORTHAND_RE = /^[A-Za-z0-9_.-]{1,100}\/[A-Za-z0-9_.-]{1,100}#\d{1,10}$/;
+// http(s)://<host>/<owner>/<repo>/pull/<n>[/files|?…|#…] — any host (GitHub Enterprise), but no
+// userinfo (`user:pass@`) and nothing that isn't actually a pull-request URL.
+const PR_URL_RE = /^https?:\/\/[^/@\s]+\/[^/\s]+\/[^/\s]+\/pull\/\d{1,10}(?:[/?#]\S*)?$/;
+// biome-ignore lint/suspicious/noControlCharactersInRegex: rejecting control characters is the point
+const CONTROL_RE = /[\u0000-\u001f\u007f]/;
+
+/** Returns an error message, or null when `id` is an acceptable session id. */
+export function sessionIdError(id: string): string | null {
+  if (id.startsWith('-') || !SESSION_ID_RE.test(id))
+    return `invalid sessionId ${JSON.stringify(id.slice(0, 60))} — expected 1-128 chars of [A-Za-z0-9._:-], not starting with "-" (use the session id from a previous run's details)`;
+  return null;
+}
+
+/** Returns an error message, or null when `model` is an acceptable model name. */
+export function modelError(model: string): string | null {
+  if (model.length === 0 || model.length > 200 || model.startsWith('-') || CONTROL_RE.test(model))
+    return `invalid model ${JSON.stringify(model.slice(0, 60))} — must be a non-empty name, not starting with "-"`;
+  return null;
+}
+
+/** Returns an error message, or null when `pr` is a PR number, an http(s) pull-request URL
+ *  (`<host>/<owner>/<repo>/pull/<n>`, no userinfo), or `owner/repo#n`. */
+export function prError(pr: string): string | null {
+  const bad = `invalid pr ${JSON.stringify(pr.slice(0, 80))} — expected a PR number, an http(s) PR URL, or owner/repo#123`;
+  if (pr.startsWith('-') || CONTROL_RE.test(pr)) return bad;
+  if (PR_NUMBER_RE.test(pr) || PR_SHORTHAND_RE.test(pr)) return null;
+  if (PR_URL_RE.test(pr)) return null;
+  return bad;
+}
+
+/**
+ * Returns an error message, or null when `dir` is an acceptable extra directory path. Judged on its
+ * *resolved* form, which is what actually reaches argv (`mergeAddDirs` resolves every entry against
+ * cwd): an absolute path can't be parsed as a flag, so a legitimate relative dir like `-foo`
+ * (→ `<cwd>/-foo`) is fine. Empty, oversized, and control-character entries are still rejected.
+ */
+export function addDirError(dir: string, cwd: string = process.cwd()): string | null {
+  const bad = `invalid addDirs entry ${JSON.stringify(dir.slice(0, 80))} — must be a non-empty path without control characters`;
+  if (dir.length === 0 || dir.length > 4096 || CONTROL_RE.test(dir)) return bad;
+  const abs = resolve(cwd, dir);
+  if (!isAbsolute(abs) || abs.startsWith('-')) return bad;
+  return null;
+}
+
+export interface ValidatableInputs {
+  sessionId?: string;
+  model?: string;
+  pr?: string;
+  addDirs?: string[];
+  /** What relative `addDirs` resolve against (the run's cwd). */
+  cwd?: string;
+}
+
+/** Throws a clear Error on the first invalid argv-bound input; returns normally otherwise. */
+export function validateDelegateInputs(inputs: ValidatableInputs): void {
+  const errors = [
+    inputs.sessionId !== undefined ? sessionIdError(inputs.sessionId) : null,
+    inputs.model !== undefined ? modelError(inputs.model) : null,
+    inputs.pr !== undefined ? prError(inputs.pr) : null,
+    ...(inputs.addDirs ?? []).map(d => addDirError(d, inputs.cwd)),
+  ];
+  const first = errors.find((e): e is string => e !== null);
+  if (first) throw new Error(first);
+}
+
+type ConfirmCtx = Pick<ExtensionContext, 'hasUI'> & { ui?: { confirm?: ExtensionContext['ui']['confirm'] } };
+
+/**
+ * The one danger-confirmation primitive shared by the tool and command paths: with a UI, ask via
+ * `ctx.ui.confirm` (a decline or a throwing dialog counts as "no"); without one there is nobody to
+ * ask, so fail closed. Resolves only on an explicit approval; throws the caller's message otherwise.
+ */
+async function askDangerConfirmation(
+  ctx: ConfirmCtx,
+  opts: { task: string; body: string; noUiError: string; declinedError: string },
+): Promise<void> {
+  if (!ctx.hasUI || typeof ctx.ui?.confirm !== 'function') throw new Error(opts.noUiError);
+  const task = opts.task.length > 200 ? `${opts.task.slice(0, 199)}…` : opts.task;
+  let ok = false;
+  try {
+    ok = await ctx.ui.confirm('Allow dangerous delegation?', `${opts.body}\n\nTask: ${task}`);
+  } catch {
+    ok = false;
+  }
+  if (!ok) throw new Error(opts.declinedError);
+}
+
+/**
+ * Gate a model-requested `allowDangerous: true` on the `delegate` tool behind a human: a tool
+ * param is model-settable (prompt-injection reachable), and `danger` means an unrestricted
+ * harness, so the model alone must never be able to grant it. With a UI, ask via
+ * `ctx.ui.confirm`; without one there is nobody to ask, so fail closed with a clear error. The
+ * `/delegate` command path uses `confirmDangerousCommand` instead.
+ */
+export async function confirmDangerousToolCall(
+  ctx: ConfirmCtx,
+  summary: { harness?: string; mode?: string; task: string },
+): Promise<void> {
+  const target = `${summary.harness ?? 'default harness'} ${summary.mode ?? 'default mode'}`;
+  await askDangerConfirmation(ctx, {
+    task: summary.task,
+    body: `The agent wants to run ${target} with DANGER permission (unrestricted: no sandbox, no approval prompts).`,
+    noUiError: `allowDangerous requested for ${target}, but there is no interactive UI to confirm it with — refusing (danger permission needs a human's explicit approval; run it from an interactive session)`,
+    declinedError: `allowDangerous for ${target} was declined by the user`,
+  });
+}
+
+/**
+ * Gate a human-typed `/delegate --allow-dangerous` behind the same interactive confirm. A human
+ * typed the flag, but it's one token away from an unrestricted run (and also escalates a
+ * non-danger template), so it's confirmed once more naming exactly what will run — one prompt
+ * covering every harness of a fan-out. Headless sessions never honor it: there's no one to
+ * confirm with, so it fails closed exactly like the tool path.
+ */
+export async function confirmDangerousCommand(
+  ctx: ConfirmCtx,
+  summary: { harnesses: string[]; mode: string; task: string },
+): Promise<void> {
+  const n = summary.harnesses.length;
+  const names = summary.harnesses.join(', ');
+  const target = `${names} ${summary.mode}`;
+  await askDangerConfirmation(ctx, {
+    task: summary.task,
+    body: `--allow-dangerous: run "${summary.mode}" on ${n > 1 ? `all ${n} harnesses (${names})` : names} with DANGER permission — full, unrestricted permissions (no sandbox, no approval prompts). Applies to this invocation only.`,
+    noUiError: `--allow-dangerous for ${target} needs interactive confirmation, but there is no UI — refusing (a headless /delegate never runs with danger permission)`,
+    declinedError: `--allow-dangerous for ${target} was declined — nothing was run`,
+  });
+}
+
+/** realpath of `p`, or — when `p` doesn't exist yet — realpath of its nearest existing ancestor
+ *  with the missing tail re-appended, so a not-yet-created dir under a symlink still resolves
+ *  through that symlink. */
+function realpathOrAncestor(p: string): string {
+  let cur = p;
+  const tail: string[] = [];
+  for (;;) {
+    try {
+      return join(realpathSync(cur), ...tail);
+    } catch {
+      const parent = dirname(cur);
+      if (parent === cur) return p;
+      tail.unshift(basename(cur));
+      cur = parent;
+    }
+  }
+}
+
+/**
+ * The model-supplied `addDirs` entries that resolve **outside** `cwd` — after `resolve()` against
+ * `cwd` and symlink resolution on both sides, so neither `..` nor a symlink inside the repo
+ * pointing out of it escapes. Empty when every entry stays inside the working directory.
+ */
+export function addDirsOutsideCwd(cwd: string, addDirs: string[] | undefined): string[] {
+  if (!addDirs || addDirs.length === 0) return [];
+  const root = realpathOrAncestor(resolve(cwd));
+  const out: string[] = [];
+  for (const d of addDirs) {
+    const real = realpathOrAncestor(resolve(cwd, d));
+    const rel = relative(root, real);
+    const inside = rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+    if (!inside) out.push(real);
+  }
+  return out;
+}
+
+/**
+ * Gate model-requested `addDirs` on the `delegate` tool. `addDirs` widens what the harness may
+ * touch — on `codex`/`claude`/`amp` the extra dir is writable on any non-readonly run, and even a
+ * `readonly` run can read it — so a model-set entry (prompt-injection reachable, same trust model as
+ * `allowDangerous`/`verify`) may only stay inside the working directory on its own. Anything that
+ * resolves outside it needs a human's `ctx.ui.confirm`; with no UI, fail closed. Template
+ * frontmatter (trusted on-disk config) and the human-typed `/delegate --add-dir` never call this.
+ */
+export async function confirmToolAddDirs(
+  ctx: Pick<ExtensionContext, 'hasUI' | 'cwd'> & { ui?: { confirm?: ExtensionContext['ui']['confirm'] } },
+  addDirs: string[] | undefined,
+): Promise<void> {
+  const outside = addDirsOutsideCwd(ctx.cwd, addDirs);
+  if (outside.length === 0) return;
+  const list = outside.join(', ');
+  if (!ctx.hasUI || typeof ctx.ui?.confirm !== 'function') {
+    throw new Error(
+      `addDirs outside the working directory requested (${list}), but there is no interactive UI to confirm it with — refusing (extra directories outside the project need a human's explicit approval)`,
+    );
+  }
+  let ok = false;
+  try {
+    ok = await ctx.ui.confirm(
+      'Allow access outside the project?',
+      `The agent wants the delegated harness to access directories outside ${ctx.cwd}:\n\n${outside.map(d => `  ${d}`).join('\n')}\n\nOn non-readonly runs these may be writable.`,
+    );
+  } catch {
+    ok = false;
+  }
+  if (!ok) throw new Error(`addDirs outside the working directory (${list}) were declined by the user`);
+}