pi-subagent-feather 0.0.0-stage → 0.2.0

package/extensions/subagent/index.ts

@@ -0,0 +1,693 @@
+// Derived from @eggmasonvalue/pi-subagent 2.0.1 (MIT, copyright eggmasonvalue).
+// Lite receipt format: no child transcript, args, thinking or images in parent details.
+import { spawn, type ChildProcess } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { AgentToolResult, ThinkingLevel } from "@earendil-works/pi-agent-core";
+import { getSupportedThinkingLevels, StringEnum, type Model } from "@earendil-works/pi-ai";
+import { type ExtensionAPI, copyToClipboard, getAgentDir, getPackageDir, getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import { Container, Markdown, Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { ChildCollector, DEFAULT_LIMITS, type CollectorLimits, type CollectorUsage, type KeepMode } from "../../src/collector.ts";
+
+const CHILD_METADATA_SUFFIX = ".subagent.json";
+const INTERNAL_TOOL_NAMES = new Set(["subagent", "subagent_models"]);
+const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const satisfies readonly ThinkingLevel[];
+const THINKING_LEVEL_SET = new Set<string>(THINKING_LEVELS);
+
+interface ChildMetadata {
+  version: 2;
+  cwd: string;
+  model?: string;
+  thinking?: string;
+  tools: string[];
+}
+
+type Status = "running" | "done" | "failed" | "timeout" | "aborted";
+interface Receipt {
+  version: 1;
+  status: Status;
+  label?: string;
+  resumed: boolean;
+  timeoutMs?: number;
+  exitCode: number;
+  sessionFile?: string;
+  sessionId?: string;
+  model?: string;
+  thinking?: string;
+  usage: CollectorUsage;
+  toolCount: number;
+  droppedEvents: number;
+  truncated: boolean;
+  currentTool?: string;
+}
+interface RunResult extends Receipt {
+  output: string;
+  stderr: string;
+  errorMessage?: string;
+}
+type Update = (partial: AgentToolResult<Receipt>) => void;
+
+interface ModelAllowlistLevel {
+	artificialAnalysis?: { intelligence?: number; coding?: number; cost?: number };
+	deepSWE?: { pass?: number; cost?: number };
+}
+
+interface ModelAllowlistEntry {
+	id: string;
+	levels?: Record<string, ModelAllowlistLevel>;
+	description?: string;
+	[key: string]: unknown;
+}
+
+interface ModelAllowlistConfig {
+	enabled?: boolean;
+	allowed?: (string | ModelAllowlistEntry)[];
+	default?: string;
+	defaultThinking?: string;
+}
+
+interface ModelPolicy {
+	enabled: boolean;
+	allowed: Set<string>;
+	metadata: Map<string, ModelAllowlistEntry>;
+	defaultModel?: string;
+	defaultThinking?: string;
+	configPath: string;
+}
+
+interface RunConfig {
+	cwd: string;
+	model?: string;
+	thinking?: string;
+	tools: string[];
+}
+
+
+function getModelAllowlistPath(): string {
+	return path.join(getAgentDir(), "pi-subagent", "models-allowlist.json");
+}
+
+function loadModelPolicy(configPath = getModelAllowlistPath()): { policy: ModelPolicy; error?: string } {
+	const disabled: ModelPolicy = {
+		enabled: false,
+		allowed: new Set(),
+		metadata: new Map(),
+		configPath,
+	};
+	if (!fs.existsSync(configPath)) return { policy: disabled };
+
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(fs.readFileSync(configPath, "utf8"));
+	} catch (error) {
+		return {
+			policy: disabled,
+			error: `Invalid JSON in model allowlist: ${error instanceof Error ? error.message : String(error)}`,
+		};
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+		return { policy: disabled, error: "Model allowlist must be a JSON object." };
+	}
+
+	const config = parsed as ModelAllowlistConfig;
+	if (config.enabled !== undefined && typeof config.enabled !== "boolean") {
+		return { policy: disabled, error: 'Model allowlist field "enabled" must be boolean.' };
+	}
+	if (config.allowed !== undefined && !Array.isArray(config.allowed)) {
+		return { policy: disabled, error: 'Model allowlist field "allowed" must be an array.' };
+	}
+	if (config.default !== undefined && typeof config.default !== "string") {
+		return { policy: disabled, error: 'Model allowlist field "default" must be a string.' };
+	}
+	if (config.defaultThinking !== undefined && typeof config.defaultThinking !== "string") {
+		return { policy: disabled, error: 'Model allowlist field "defaultThinking" must be a string.' };
+	}
+	const defaultThinking = config.defaultThinking?.trim() || undefined;
+	if (defaultThinking && !THINKING_LEVEL_SET.has(defaultThinking)) {
+		return { policy: disabled, error: `Default thinking level "${defaultThinking}" is not recognized by Pi.` };
+	}
+
+	const metadata = new Map<string, ModelAllowlistEntry>();
+	const allowed = new Set<string>();
+	for (const raw of config.allowed ?? []) {
+		if (typeof raw === "string") {
+			const id = raw.trim();
+			if (id) allowed.add(id);
+			continue;
+		}
+		if (raw && typeof raw === "object" && typeof raw.id === "string" && raw.id.trim()) {
+			const entry = { ...raw, id: raw.id.trim() };
+			allowed.add(entry.id);
+			metadata.set(entry.id, entry);
+		}
+	}
+
+	const enabled = config.enabled ?? true;
+	const defaultModel = config.default?.trim() || undefined;
+	if (enabled && allowed.size === 0) {
+		return { policy: disabled, error: 'Model allowlist is enabled but "allowed" is empty.' };
+	}
+	if (enabled && defaultModel && !allowed.has(defaultModel)) {
+		return { policy: disabled, error: 'The default model must also appear in "allowed".' };
+	}
+
+	return { policy: { enabled, allowed, metadata, defaultModel, defaultThinking, configPath } };
+}
+
+function allowedThinkingLevels(entry: ModelAllowlistEntry | undefined): string[] | undefined {
+	if (!entry?.levels || typeof entry.levels !== "object" || Array.isArray(entry.levels)) return undefined;
+	const levels = Object.keys(entry.levels);
+	return levels.length > 0 ? levels : undefined;
+}
+
+interface ModelRegistryView {
+	getAll(): Model<any>[];
+}
+
+function modelMap(registry: ModelRegistryView): Map<string, Model<any>> {
+	return new Map(registry.getAll().map((model) => [`${model.provider}/${model.id}`, model]));
+}
+
+function effectiveThinkingLevels(entry: ModelAllowlistEntry | undefined, model: Model<any>): ThinkingLevel[] {
+	const supported = getSupportedThinkingLevels(model) as ThinkingLevel[];
+	const configured = allowedThinkingLevels(entry);
+	return configured
+		? supported.filter((level) => configured.includes(level))
+		: supported;
+}
+
+function validateModelPolicy(policy: ModelPolicy, registry: ModelRegistryView): string[] {
+	if (!policy.enabled) return [];
+	const errors: string[] = [];
+	const known = modelMap(registry);
+
+	for (const id of policy.allowed) {
+		const model = known.get(id);
+		if (!model) {
+			errors.push(`Allowlisted model "${id}" is not known to Pi.`);
+			continue;
+		}
+		const supported = new Set<string>(getSupportedThinkingLevels(model));
+		for (const level of allowedThinkingLevels(policy.metadata.get(id)) ?? []) {
+			if (!THINKING_LEVEL_SET.has(level)) {
+				errors.push(`Thinking level "${level}" configured for "${id}" is not recognized by Pi.`);
+			} else if (!supported.has(level)) {
+				errors.push(`Thinking level "${level}" is unsupported by "${id}".`);
+			}
+		}
+	}
+	if (policy.defaultThinking && policy.defaultModel) {
+		const defaultModel = known.get(policy.defaultModel);
+		if (defaultModel && !effectiveThinkingLevels(policy.metadata.get(policy.defaultModel), defaultModel).includes(policy.defaultThinking as ThinkingLevel)) {
+			errors.push(`Default thinking level "${policy.defaultThinking}" is not allowed for "${policy.defaultModel}".`);
+		}
+	}
+	return errors;
+}
+
+function resolveFreshModel(
+	requestedModel: string | undefined,
+	thinking: string | undefined,
+	policy: ModelPolicy,
+	registry?: ModelRegistryView,
+): { model?: string; thinking?: string; error?: string } {
+	if (!policy.enabled) return { model: requestedModel?.trim() || undefined };
+	const model = requestedModel?.trim() || policy.defaultModel;
+	if (!model) return { error: "Model policy requires `model`, but no default is configured." };
+	if (!policy.allowed.has(model)) {
+		return { error: `Model "${model}" is not allowed. Call subagent_models for permitted models.` };
+	}
+	const entry = policy.metadata.get(model);
+	const configuredLevels = allowedThinkingLevels(entry);
+	const knownModel = registry ? modelMap(registry).get(model) : undefined;
+	const levels = knownModel ? effectiveThinkingLevels(entry, knownModel) : configuredLevels;
+	const selectedThinking = thinking || policy.defaultThinking;
+	if (!selectedThinking && configuredLevels) {
+		return { error: `Thinking level is required for "${model}". Allowed: ${levels?.join(", ") || "none"}.` };
+	}
+	if (selectedThinking && levels && !levels.includes(selectedThinking)) {
+		return { error: `Thinking level "${selectedThinking}" is not allowed for "${model}". Allowed: ${levels.join(", ") || "none"}.` };
+	}
+	return selectedThinking && !thinking ? { model, thinking: selectedThinking } : { model };
+}
+
+function compactModelCatalog(policy: ModelPolicy, validationErrors: string[], registry: ModelRegistryView) {
+  const known = modelMap(registry);
+  return {
+    policy: policy.enabled,
+    default: policy.defaultModel ?? null,
+    thinking: policy.defaultThinking ?? null,
+    models: Array.from(policy.allowed, id => {
+      const entry = policy.metadata.get(id);
+      const model = known.get(id);
+      return { id, levels: model ? effectiveThinkingLevels(entry, model) : [],
+        ...(entry?.description ? { note: bounded(entry.description, 256) } : {}) };
+    }),
+    ...(validationErrors.length ? { errors: validationErrors } : {}),
+  };
+}
+
+function metadataPath(sessionFile: string): string {
+	return `${sessionFile}${CHILD_METADATA_SUFFIX}`;
+}
+
+function writeChildMetadata(sessionFile: string, metadata: ChildMetadata): void {
+	const destination = metadataPath(sessionFile);
+	const temporary = `${destination}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+	try {
+		fs.writeFileSync(temporary, `${JSON.stringify(metadata, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+		fs.renameSync(temporary, destination);
+	} finally {
+		try {
+			if (fs.existsSync(temporary)) fs.unlinkSync(temporary);
+		} catch {
+			// Preserve the original metadata error.
+		}
+	}
+}
+
+function readChildMetadata(sessionFile: string): ChildMetadata {
+	const file = metadataPath(sessionFile);
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+	} catch {
+		throw new Error(`Subagent runtime metadata not found or invalid: ${file}`);
+	}
+	if (!parsed || typeof parsed !== "object") throw new Error(`Invalid subagent runtime metadata: ${file}`);
+	const value = parsed as Partial<ChildMetadata>;
+	if (value.version !== 2 || typeof value.cwd !== "string" || !Array.isArray(value.tools)) {
+		throw new Error(`Invalid subagent runtime metadata: ${file}`);
+	}
+	return {
+		version: 2,
+		cwd: value.cwd,
+		model: typeof value.model === "string" ? value.model : undefined,
+		thinking: typeof value.thinking === "string" ? value.thinking : undefined,
+		tools: value.tools.filter((tool): tool is string => typeof tool === "string"),
+	};
+}
+
+function expandHome(input: string): string {
+	if (input === "~") return os.homedir();
+	if (input.startsWith("~/") || input.startsWith("~\\")) return path.join(os.homedir(), input.slice(2));
+	return input;
+}
+
+function resolveResumePath(input: string): string {
+	const expanded = expandHome(input.trim());
+	if (!path.isAbsolute(expanded) || path.extname(expanded) !== ".jsonl") {
+		throw new Error("`resume` must be the exact absolute JSONL path returned by an earlier subagent call.");
+	}
+	const resolved = path.resolve(expanded);
+	if (!fs.existsSync(resolved) || !fs.statSync(resolved).isFile()) {
+		throw new Error(`Subagent session not found: ${resolved}`);
+	}
+	return resolved;
+}
+
+function bounded(text: string, bytes: number): string {
+  let used = 0, end = 0;
+  for (const char of text) {
+    const size = Buffer.byteLength(char);
+    if (used + size > bytes) break;
+    used += size; end += char.length;
+  }
+  return Buffer.from(text.slice(0, end), "utf8").toString("utf8");
+}
+
+interface FeatherConfig {
+  limits: CollectorLimits;
+  offlineChildren: boolean;
+  defaultTimeoutMs?: number;
+  resultKeep: KeepMode;
+}
+
+function loadConfig(agentDir = getAgentDir()): FeatherConfig {
+  const file = path.join(agentDir, "pi-subagent-feather", "config.json");
+  if (!fs.existsSync(file)) return { limits: { ...DEFAULT_LIMITS }, offlineChildren: false, resultKeep: "head" };
+  const value = JSON.parse(fs.readFileSync(file, "utf8"));
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`Invalid config: ${file}`);
+  const limits = { ...DEFAULT_LIMITS };
+  const config: FeatherConfig = { limits, offlineChildren: false, resultKeep: "head" };
+  const maximum: CollectorLimits = { resultBytes: 51200, resultLines: 2000, progressBytes: 8192, stderrBytes: 16384, eventBytes: 64 * 1024 * 1024 };
+  for (const key of Object.keys(value)) {
+    if (key in limits) {
+      if (!Number.isInteger(value[key]) || value[key] < 1 || value[key] > maximum[key as keyof CollectorLimits]) throw new Error(`Invalid ${key} in ${file}`);
+      limits[key as keyof CollectorLimits] = value[key];
+    } else if (key === "offlineChildren") {
+      if (typeof value[key] !== "boolean") throw new Error(`Invalid offlineChildren in ${file}`);
+      config.offlineChildren = value[key];
+    } else if (key === "defaultTimeoutMs") {
+      if (!Number.isInteger(value[key]) || value[key] < 1 || value[key] > 2147483647) throw new Error(`Invalid defaultTimeoutMs in ${file}`);
+      config.defaultTimeoutMs = value[key];
+    } else if (key === "resultKeep") {
+      if (value[key] !== "head" && value[key] !== "tail") throw new Error(`Invalid resultKeep in ${file}`);
+      config.resultKeep = value[key];
+    } else {
+      throw new Error(`Unknown config key "${key}" in ${file}`);
+    }
+  }
+  return config;
+}
+
+function resolveSessionFile(sessionDir: string): string | undefined {
+  try {
+    const file = fs.readdirSync(sessionDir).find(name => name.endsWith(".jsonl"));
+    return file ? path.join(sessionDir, file) : undefined;
+  } catch { return undefined; }
+}
+
+function getPiInvocation(args: string[]): { command: string; args: string[] } {
+  const executable = path.basename(process.execPath).toLowerCase();
+  if (!/^(node|bun)(\.exe)?$/.test(executable)) return { command: process.execPath, args };
+  const script = process.argv[1];
+  // Do not relaunch an arbitrary embedding app/test script as if it were Pi.
+  if (script && script.replaceAll("\\", "/").includes("pi-coding-agent/") && fs.existsSync(script)) {
+    return { command: process.execPath, args: [script, ...args] };
+  }
+  const cli = path.join(getPackageDir(), "dist", "cli.js");
+  if (fs.existsSync(cli)) return { command: process.execPath, args: [cli, ...args] };
+  throw new Error("Cannot locate the host Pi CLI for a child process.");
+}
+
+function killChild(proc: ChildProcess): void {
+  if (proc.exitCode !== null || proc.signalCode !== null) return;
+  if (process.platform === "win32" && proc.pid) {
+    const killer = spawn("taskkill.exe", ["/pid", String(proc.pid), "/t", "/f"], { stdio: "ignore", windowsHide: true });
+    killer.on("error", () => proc.kill());
+    killer.on("close", code => { if (code !== 0 && proc.exitCode === null && proc.signalCode === null) proc.kill(); });
+    killer.unref();
+  } else {
+    const stop = (signal: NodeJS.Signals) => {
+      try { if (proc.pid) process.kill(-proc.pid, signal); else proc.kill(signal); } catch { proc.kill(signal); }
+    };
+    stop("SIGTERM");
+    setTimeout(() => { if (proc.exitCode === null && proc.signalCode === null) stop("SIGKILL"); }, 5000).unref();
+  }
+}
+
+// Explicit projection: never spread a RunResult into persisted details.
+function receiptOf(result: Receipt): Receipt {
+  return { version: 1, status: result.status, label: result.label, resumed: result.resumed,
+    timeoutMs: result.timeoutMs, exitCode: result.exitCode, sessionFile: result.sessionFile,
+    sessionId: result.sessionId, model: result.model, thinking: result.thinking,
+    usage: { ...result.usage, cost: { ...result.usage.cost } }, toolCount: result.toolCount,
+    droppedEvents: result.droppedEvents, truncated: result.truncated, currentTool: result.currentTool };
+}
+
+function modelFacingResult(result: RunResult): string {
+  const fields = [`status=${result.status}`];
+  if (result.label) fields.push(`label=${result.label}`);
+  if (result.sessionFile) fields.push(`session=${result.sessionFile}`);
+  const error = result.errorMessage ? `Error: ${result.errorMessage}\n` : "";
+  const output = result.output || (result.status === "failed" ? result.stderr.trim() : "") || "(no output)";
+  const hint = result.truncated ? "\n[Truncated; full text is in the child session.]" : "";
+  return `[${fields.join(" ")}]\n${error}${output}${hint}`;
+}
+
+interface RunChildDependencies {
+  agentDir?: string;
+  invoke?: (args: string[]) => { command: string; args: string[] };
+  limits?: Partial<CollectorLimits>;
+  resultKeep?: KeepMode;
+  offlineChildren?: boolean;
+}
+
+async function runChild(
+  config: RunConfig, task: string, label: string | undefined, timeoutMs: number | undefined,
+  resumePath: string | undefined, signal: AbortSignal | undefined, onUpdate: Update | undefined,
+  dependencies: RunChildDependencies = {},
+): Promise<RunResult> {
+  const feather = loadConfig(dependencies.agentDir);
+  const collector = new ChildCollector({ ...feather.limits, ...dependencies.limits }, { resultKeep: dependencies.resultKeep ?? feather.resultKeep });
+  let sessionFile = resumePath, exitCode = -1, status: Status = "running";
+  const snapshot = (): Receipt => ({ version: 1, status, label, resumed: Boolean(resumePath), timeoutMs, exitCode,
+    sessionFile, sessionId: collector.sessionId, model: config.model ?? collector.model, thinking: config.thinking,
+    usage: collector.usage, toolCount: collector.toolCount, droppedEvents: collector.droppedEvents,
+    truncated: collector.truncated, currentTool: collector.currentTool });
+  if (signal?.aborted) return { ...receiptOf({ ...snapshot(), status: "aborted", exitCode: 1 }), output: "", stderr: "" };
+  const runId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  const sessionDir = path.join(dependencies.agentDir ?? getAgentDir(), "sessions", "subagent-lite", runId);
+  if (!resumePath) await fs.promises.mkdir(sessionDir, { recursive: true });
+  const args = ["--mode", "json", "-p"];
+  if (resumePath) args.push("--session", resumePath); else args.push("--session-dir", sessionDir);
+  if (dependencies.offlineChildren ?? feather.offlineChildren) args.push("--offline");
+  if (config.model) args.push("--model", config.model);
+  if (config.thinking) args.push("--thinking", config.thinking);
+  if (!config.tools.length) args.push("--no-tools"); else args.push("--tools", config.tools.join(","));
+  if (config.tools.some(tool => INTERNAL_TOOL_NAMES.has(tool))) args.push("--extension", path.join(import.meta.dirname, "index.ts"));
+  // No append-system-prompt, promptGuidelines or promptSnippet injection.
+  let aborted = false, timedOut = false;
+  let lastUpdate = 0;
+  let updateTimer: ReturnType<typeof setTimeout> | undefined;
+  const emitUpdate = (force = false) => {
+    if (!onUpdate) return;
+    const remaining = 100 - (Date.now() - lastUpdate);
+    if (!force && remaining > 0) {
+      if (!updateTimer) updateTimer = setTimeout(() => { updateTimer = undefined; emitUpdate(true); }, remaining);
+      return;
+    }
+    if (updateTimer) { clearTimeout(updateTimer); updateTimer = undefined; }
+    lastUpdate = Date.now();
+    if (!sessionFile) sessionFile = resolveSessionFile(sessionDir);
+    // Fresh detached metadata; no mutable collector/event references in the UI.
+    try {
+      onUpdate({ content: [{ type: "text", text: collector.progress() || "(running)" }], details: receiptOf(snapshot()) });
+    } catch { /* Progress UI must not crash a child run or leave it orphaned. */ }
+  };
+  exitCode = await new Promise<number>(resolve => {
+    const invocation = (dependencies.invoke ?? getPiInvocation)(args);
+    const proc = spawn(invocation.command, invocation.args, { cwd: config.cwd, shell: false,
+      detached: process.platform !== "win32", windowsHide: true, stdio: ["pipe", "pipe", "pipe"] });
+    let settled = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const onAbort = () => { if (!timedOut) { aborted = true; if (timer) clearTimeout(timer); killChild(proc); } };
+    const finish = (code: number) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      if (updateTimer) { clearTimeout(updateTimer); updateTimer = undefined; }
+      signal?.removeEventListener("abort", onAbort);
+      collector.endStdout(); collector.endStderr(); collector.finishUsage();
+      resolve(code);
+    };
+    proc.stdin.on("error", () => {});
+    proc.stdout.on("data", (data: Buffer) => { collector.pushStdout(data); emitUpdate(); });
+    proc.stderr.on("data", (data: Buffer) => collector.pushStderr(data));
+    proc.on("error", error => { collector.errorMessage = bounded(error.message, 2048); finish(1); });
+    proc.on("close", code => finish(code ?? 1));
+    if (timeoutMs) timer = setTimeout(() => { if (!aborted) { timedOut = true; killChild(proc); } }, timeoutMs);
+    if (signal?.aborted) onAbort(); else signal?.addEventListener("abort", onAbort, { once: true });
+    proc.stdin.end(task);
+  });
+  if (!sessionFile) sessionFile = resolveSessionFile(sessionDir);
+  if (!resumePath && sessionFile) {
+    try {
+      writeChildMetadata(sessionFile, { version: 2, cwd: config.cwd, model: config.model ?? collector.model, thinking: config.thinking, tools: config.tools });
+    } catch (error) {
+      collector.errorMessage = bounded(`Resume metadata could not be saved: ${String(error)}`, 2048);
+      exitCode = 1;
+    }
+  } else if (!sessionFile && !aborted && !timedOut) {
+    collector.errorMessage = "Child session was not created; this run cannot be resumed."; exitCode = 1;
+  }
+  status = timedOut ? "timeout" : aborted ? "aborted" : exitCode !== 0 || collector.stopReason === "error" || collector.errorMessage ? "failed" : "done";
+  collector.currentTool = undefined;
+  emitUpdate(true);
+  return { ...receiptOf(snapshot()), output: collector.answer(), stderr: collector.stderr, errorMessage: collector.errorMessage };
+}
+
+const SubagentParams = Type.Object({
+  task: Type.String({ minLength: 1, maxLength: 262144, description: "Task or resume instruction; include needed context and desired output." }),
+  label: Type.Optional(Type.String({ minLength: 1, maxLength: 64, pattern: "^[A-Za-z0-9._:-]+$" })),
+  model: Type.Optional(Type.String({ minLength: 1, maxLength: 512, description: "New only. Omit for default; see subagent_models." })),
+  thinking: Type.Optional(StringEnum(THINKING_LEVELS, { description: "New only. Omit for policy/Pi default." })),
+  tools: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 256 }), { uniqueItems: true, maxItems: 256, description: "New only. Omit=inherit except delegation; []=none. Include subagent to allow recursion." })),
+  cwd: Type.Optional(Type.String({ minLength: 1, maxLength: 4096, description: "New only. Defaults to parent cwd." })),
+  timeoutMs: Type.Optional(Type.Integer({ minimum: 1, maximum: 2147483647, description: "Stop after this many ms; partial result is resumable." })),
+  resume: Type.Optional(Type.String({ minLength: 1, maxLength: 4096, description: "Absolute child JSONL path. Cannot combine with model/thinking/tools/cwd." })),
+});
+
+export const __testing = { allowedThinkingLevels, compactModelCatalog, loadModelPolicy, metadataPath,
+  modelFacingResult, readChildMetadata, resolveFreshModel, resolveResumePath, runChild,
+  validateModelPolicy, writeChildMetadata, receiptOf, loadConfig, recentChildSessions, formatBytes,
+  getPiInvocation, SubagentParams };
+
+interface ChildSessionInfo {
+  path: string;
+  mtimeMs: number;
+  bytes: number;
+  sessionId?: string;
+  model?: string;
+  cwd?: string;
+}
+
+function formatBytes(n: number): string {
+  if (n < 1024) return `${n}B`;
+  if (n < 1024 * 1024) return `${Math.round(n / 1024)}KB`;
+  return `${(n / (1024 * 1024)).toFixed(1)}MB`;
+}
+
+/** Recent child sessions (newest first). Read-only: stats, sidecar metadata, first-line id. */
+function recentChildSessions(agentDir = getAgentDir(), max = 24): ChildSessionInfo[] {
+  const root = path.join(agentDir, "sessions", "subagent-lite");
+  let runDirs: string[];
+  try {
+    runDirs = fs.readdirSync(root);
+  } catch {
+    return [];
+  }
+  const sessions: ChildSessionInfo[] = [];
+  for (const run of runDirs) {
+    const dir = path.join(root, run);
+    let names: string[];
+    try {
+      names = fs.readdirSync(dir);
+    } catch {
+      continue;
+    }
+    for (const name of names) {
+      if (!name.endsWith(".jsonl")) continue;
+      const file = path.join(dir, name);
+      let stat: fs.Stats;
+      try {
+        stat = fs.statSync(file);
+      } catch {
+        continue;
+      }
+      if (!stat.isFile()) continue;
+      const info: ChildSessionInfo = { path: file, mtimeMs: stat.mtimeMs, bytes: stat.size };
+      try {
+        const meta = readChildMetadata(file);
+        info.model = meta.model;
+        info.cwd = meta.cwd;
+      } catch {
+        // Sidecar metadata is optional for listing.
+      }
+      try {
+        const fd = fs.openSync(file, "r");
+        try {
+          const buf = Buffer.alloc(512);
+          const read = fs.readSync(fd, buf, 0, 512, 0);
+          const first = JSON.parse(buf.toString("utf8", 0, read).split("\n", 1)[0]);
+          if (first?.type === "session" && first.id) info.sessionId = String(first.id).slice(0, 64);
+        } finally {
+          fs.closeSync(fd);
+        }
+      } catch {
+        // First-line probe is optional.
+      }
+      sessions.push(info);
+    }
+  }
+  return sessions.sort((a, b) => b.mtimeMs - a.mtimeMs).slice(0, max);
+}
+
+export default function (pi: ExtensionAPI) {
+  const running = new Map<AbortController, Promise<RunResult>>();
+  pi.on("session_shutdown", async () => {
+    for (const controller of running.keys()) controller.abort();
+    await Promise.allSettled(running.values());
+    running.clear();
+  });
+  pi.registerCommand("subagents", {
+    description: "List recent subagent child sessions (pick one to copy its resume path)",
+    handler: async (_args, ctx) => {
+      const sessions = recentChildSessions();
+      if (sessions.length === 0) {
+        ctx.ui.notify("No subagent child sessions found.", "info");
+        return;
+      }
+      const lines = sessions.map(s => `${new Date(s.mtimeMs).toLocaleString()} ${formatBytes(s.bytes)} ${s.model ?? "?"} ${s.path}`);
+      if (!ctx.hasUI) {
+        ctx.ui.notify(lines.join("\n"), "info");
+        return;
+      }
+      let picked: string | undefined;
+      try {
+        picked = await ctx.ui.select(`Subagent sessions (${sessions.length})`, lines);
+      } catch {
+        picked = undefined;
+      }
+      if (!picked) return;
+      const chosen = sessions[lines.indexOf(picked)];
+      if (!chosen) return;
+      try {
+        await copyToClipboard(chosen.path);
+        ctx.ui.notify(`Copied resume path: ${chosen.path}`, "info");
+      } catch {
+        ctx.ui.notify(`Resume path: ${chosen.path}`, "info");
+      }
+    },
+  });
+  pi.registerTool({
+    name: "subagent_models", label: "Subagent Models",
+    description: "List child model policy, defaults and supported thinking levels. No child starts.",
+    parameters: Type.Object({}),
+    async execute(_id, _params, _signal, _update, ctx) {
+      const { policy, error } = loadModelPolicy();
+      if (error) throw new Error(error);
+      const catalog = compactModelCatalog(policy, validateModelPolicy(policy, ctx.modelRegistry), ctx.modelRegistry);
+      return { content: [{ type: "text", text: JSON.stringify(catalog) }], details: undefined };
+    },
+  });
+  pi.registerTool({
+    name: "subagent", label: "Subagent Lite",
+    description: "Delegate one task to an isolated Pi. Returns answer and resumable session path; timeout stops the child. Parallel calls are independent.",
+    parameters: SubagentParams,
+    async execute(_id, params, signal, onUpdate, ctx) {
+      if (!params.task.trim()) throw new Error("Subagent task must not be blank.");
+      const { policy, error } = loadModelPolicy();
+      if (error) throw new Error(error);
+      const validation = validateModelPolicy(policy, ctx.modelRegistry);
+      if (validation.length) throw new Error(validation.join("\n"));
+      let resumePath: string | undefined, config: RunConfig;
+      if (params.resume) {
+        if (params.model !== undefined || params.thinking !== undefined || params.tools !== undefined || params.cwd !== undefined) throw new Error("Resume accepts only task, resume, label and timeoutMs.");
+        resumePath = resolveResumePath(params.resume);
+        const saved = readChildMetadata(resumePath);
+        if (policy.enabled && (!saved.model || !policy.allowed.has(saved.model))) throw new Error("Saved child model is missing or no longer permitted.");
+        const model = saved.model ? modelMap(ctx.modelRegistry).get(saved.model) : undefined;
+        const entry = saved.model ? policy.metadata.get(saved.model) : undefined;
+        if (policy.enabled && allowedThinkingLevels(entry) && !saved.thinking) throw new Error("Saved child thinking level is required by current policy.");
+        if (policy.enabled && model && saved.thinking && !effectiveThinkingLevels(entry, model).includes(saved.thinking as ThinkingLevel)) throw new Error("Saved child thinking level is no longer permitted.");
+        config = saved;
+      } else {
+        const selected = resolveFreshModel(params.model, params.thinking, policy, ctx.modelRegistry);
+        if (selected.error) throw new Error(selected.error);
+        config = { cwd: path.resolve(params.cwd ?? ctx.cwd), model: selected.model, thinking: selected.thinking ?? params.thinking,
+          tools: params.tools ? [...new Set(params.tools)] : pi.getActiveTools().filter(name => !INTERNAL_TOOL_NAMES.has(name)) };
+      }
+      const controller = new AbortController();
+      const feather = loadConfig();
+      const child = runChild(config, params.task, params.label, params.timeoutMs ?? feather.defaultTimeoutMs, resumePath,
+        signal ? AbortSignal.any([signal, controller.signal]) : controller.signal, onUpdate,
+        { resultKeep: feather.resultKeep });
+      running.set(controller, child);
+      try {
+        const result = await child;
+        return { content: [{ type: "text", text: modelFacingResult(result) }], details: receiptOf(result), usage: result.usage };
+      } finally { running.delete(controller); }
+    },
+    renderCall(args, theme) {
+      return new Text(`${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", args.label ?? (args.resume ? "resume" : "child"))}\n${theme.fg("dim", bounded(args.task, 160))}`, 0, 0);
+    },
+    renderResult(result, { expanded }, theme) {
+      const receipt = result.details as Receipt | undefined;
+      const text = result.content.filter(part => part.type === "text").map(part => part.text).join("\n");
+      if (!receipt || receipt.version !== 1) return new Text(bounded(text, expanded ? 8192 : 512), 0, 0);
+      const color = receipt.status === "done" ? "success" : receipt.status === "running" || receipt.status === "timeout" ? "warning" : "error";
+      let header = `${theme.fg(color, receipt.status)} ${receipt.label ?? "child"} · ${receipt.toolCount} tools`;
+      if (receipt.currentTool) header += ` · ${receipt.currentTool}`;
+      header += ` · ${receipt.usage.turns} turns · ↑${receipt.usage.input} ↓${receipt.usage.output}`;
+      if (!expanded) return new Text(`${header}\n${theme.fg("dim", bounded(text.split("\n").slice(1, 4).join("\n"), 512))}`, 0, 0);
+      const container = new Container();
+      container.addChild(new Text(header, 0, 0));
+      container.addChild(new Markdown(text, 0, 0, getMarkdownTheme()));
+      return container;
+    },
+  });
+}