@pi-archimedes/subagent 1.3.0 → 1.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/subagent",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "type": "module",
   "keywords": [
     "pi-package"
@@ -11,9 +11,10 @@
   ],
   "main": "./src/index.ts",
   "dependencies": {
-    "@pi-archimedes/core": "1.3.0"
+    "@pi-archimedes/core": "1.3.1"
   },
   "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.1.0",
     "@earendil-works/pi-coding-agent": ">=0.1.0",
     "@earendil-works/pi-tui": ">=0.1.0",
     "typebox": ">=1.1.0"
@@ -21,7 +22,7 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "typebox": "^1.1.38",
-    "typescript": "^6.0.0"
+    "typescript": "^6.0.3"
   },
   "pi": {
     "extensions": [

package/src/child.ts

@@ -0,0 +1,299 @@
+/**
+ * Forked child entry point for IPC-based subagent architecture.
+ *
+ * This script is forked by the parent process. It receives an "init" message
+ * with task and configuration, creates an AgentSession, runs the agent loop,
+ * and streams events back to the parent over IPC.
+ *
+ * Usage: node child.js (forked with stdio: ["pipe", "pipe", "pipe", "ipc"])
+ */
+
+import {
+  createAgentSession,
+  SessionManager,
+} from "@earendil-works/pi-coding-agent";
+import type { Model } from "@earendil-works/pi-ai";
+import type { ParentToChild, ChildToParent, SerializedAgentEvent } from "./ipc-types.ts";
+import { createIpcAskTool } from "./ipc-ask-tool.ts";
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+
+interface InitParams {
+  task: string;
+  model: string | undefined;
+  agentName: string | undefined;
+  agentSystemPrompt: string | undefined;
+  agentTools: string[] | undefined;
+  agentModel: string | undefined;
+  agentThinking: string | undefined;
+  cwd: string | undefined;
+}
+
+// ── Model resolution ────────────────────────────────────────────────────────
+
+/**
+ * Known providers' default model ids (subset of pi's defaultModelPerProvider).
+ * Used by buildFallbackModel to pick a template model when the requested
+ * model id isn't in the registry (e.g. newly-released openrouter models).
+ */
+const DEFAULT_MODEL_PER_PROVIDER: Record<string, string | undefined> = {
+  openrouter: "anthropic/claude-sonnet-4-5",
+  anthropic: "claude-sonnet-4-5",
+  openai: "gpt-4o",
+  google: "gemini-2.5-pro",
+  // fall back to first model of provider when undefined
+};
+
+/**
+ * Build a fallback model for a known provider when the exact model id isn't
+ * registered. Mirrors pi's buildFallbackModel(): take the provider's default
+ * model as a template and override id/name with the requested modelId.
+ */
+function buildFallbackModel(provider: string, modelId: string, available: Model<any>[]): Model<any> | undefined {
+  const providerModels = available.filter((m) => m.provider === provider);
+  if (providerModels.length === 0) return undefined;
+  const defaultId = DEFAULT_MODEL_PER_PROVIDER[provider];
+  const baseModel = defaultId
+    ? (providerModels.find((m) => m.id === defaultId) ?? providerModels[0]!)
+    : providerModels[0]!;
+  return { ...baseModel, id: modelId, name: modelId };
+}
+
+interface ModelRegistryLike {
+  find(provider: string, modelId: string): Model<any> | undefined;
+  getAll(): Model<any>[];
+}
+
+/**
+ * Resolve a model reference the same way the pi CLI does (resolveCliModel).
+ *
+ * Supports:
+ * - "provider/modelId" where provider is a known provider
+ * - "modelId" containing slashes (e.g. openrouter's "z-ai/glm-5.2")
+ * - bare "modelId"
+ * - fuzzy/partial matching on id within a provider
+ * - fallback: build a custom model for a known provider when the id isn't
+ *   registered (handles newly-released models like openrouter/z-ai/glm-5.2)
+ *
+ * The registry must include extension-registered providers (e.g. "tama"),
+ * which is why this is called AFTER createAgentSession has loaded
+ * extensions — not with a bare ModelRegistry.create() that only knows
+ * built-ins + models.json.
+ */
+function resolveModel(modelString: string | undefined, registry: ModelRegistryLike): Model<any> | undefined {
+  if (!modelString) return undefined;
+  const cliModel = modelString.trim();
+  if (!cliModel) return undefined;
+
+  const available = registry.getAll();
+  if (available.length === 0) return undefined;
+
+  const lower = cliModel.toLowerCase();
+
+  // Build canonical provider lookup (case-insensitive)
+  const providerMap = new Map<string, string>();
+  for (const m of available) {
+    if (!providerMap.has(m.provider.toLowerCase())) {
+      providerMap.set(m.provider.toLowerCase(), m.provider);
+    }
+  }
+
+  // If the input is a full canonical "provider/id", match it directly.
+  // This handles models whose ids contain slashes (e.g. openrouter "z-ai/glm-5.2").
+  const canonicalMatch = available.find(
+    (m) => `${m.provider}/${m.id}`.toLowerCase() === lower,
+  );
+  if (canonicalMatch) return canonicalMatch;
+
+  // Try interpreting "provider/modelId" when the prefix is a known provider.
+  const slashIndex = cliModel.indexOf("/");
+  if (slashIndex !== -1) {
+    const maybeProvider = cliModel.substring(0, slashIndex);
+    const canonicalProvider = providerMap.get(maybeProvider.toLowerCase());
+    if (canonicalProvider) {
+      const modelId = cliModel.substring(slashIndex + 1);
+      // Exact match within provider
+      const within = available.filter(
+        (m) => m.provider === canonicalProvider && m.id.toLowerCase() === modelId.toLowerCase(),
+      );
+      if (within.length === 1) return within[0];
+      // Fallback: unknown model id on a known provider → build a custom model
+      return buildFallbackModel(canonicalProvider, modelId, available);
+    }
+  }
+
+  // Bare id (no slash, or slash prefix isn't a known provider) — exact id match
+  const idMatches = available.filter((m) => m.id.toLowerCase() === lower);
+  if (idMatches.length === 1) return idMatches[0];
+
+  return undefined;
+}
+
+// ── Thinking level parsing ──────────────────────────────────────────────────
+
+function parseThinkingLevel(level: string | undefined): ThinkingLevel | undefined {
+  if (!level) return undefined;
+  const validLevels: readonly ThinkingLevel[] = [
+    "off",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+  ];
+  if (validLevels.includes(level as ThinkingLevel)) {
+    return level as ThinkingLevel;
+  }
+  return undefined;
+}
+
+// ── Parent message handler ──────────────────────────────────────────────────
+
+let session: Awaited<ReturnType<typeof createAgentSession>>["session"] | null = null;
+
+function handleParentMessage(msg: ParentToChild): void {
+  switch (msg.type) {
+    case "abort": {
+      session?.abort();
+      break;
+    }
+    // "init" is handled synchronously before this listener is set up
+    // "ask_response" is handled by the IPC ask tool's own per-execution listener
+  }
+}
+
+// ── Event serialization ─────────────────────────────────────────────────────
+
+/**
+ * Strip non-serializable fields (functions, symbols) from events.
+ */
+function serializeEvent(event: Record<string, unknown>): Record<string, unknown> {
+  return JSON.parse(JSON.stringify(event));
+}
+
+// ── Send helper ─────────────────────────────────────────────────────────────
+
+function sendToParent(msg: ChildToParent): void {
+  process.send?.(msg);
+}
+
+// ── Main ────────────────────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  // Wait for the "init" message from parent.
+  let initParams: InitParams | null = null;
+
+  const initPromise = new Promise<InitParams>((resolve) => {
+    const handler = (msg: ParentToChild) => {
+      if (msg.type === "init") {
+        process.removeListener("message", handler);
+        resolve({
+          task: msg.task,
+          model: msg.model,
+          agentName: msg.agentName,
+          agentSystemPrompt: msg.agentSystemPrompt,
+          agentTools: msg.agentTools,
+          agentModel: msg.agentModel,
+          agentThinking: msg.agentThinking,
+          cwd: msg.cwd,
+        });
+      }
+    };
+    process.on("message", handler);
+  });
+
+  initParams = await initPromise;
+
+  // Resolve thinking level from agent config.
+  const thinkingLevel = parseThinkingLevel(initParams.agentThinking);
+
+  // Build tools allowlist from agent config.
+  const tools = initParams.agentTools;
+
+  // Build options object — omit undefined values to satisfy exactOptionalPropertyTypes.
+  // NOTE: we deliberately do NOT pass authStorage/modelRegistry/settingsManager —
+  // createAgentSession builds a DefaultResourceLoader that loads extensions
+  // (including custom providers like "tama") and registers them into the
+  // registry. Passing a bare ModelRegistry.create() would skip extension
+  // loading and break custom-provider model resolution.
+  const sessionOptions: Parameters<typeof createAgentSession>[0] = {
+    excludeTools: ["subagent"],
+    customTools: [createIpcAskTool()],
+    sessionManager: SessionManager.inMemory(),
+    ...(thinkingLevel ? { thinkingLevel } : {}),
+    ...(initParams.cwd ? { cwd: initParams.cwd } : {}),
+    ...(tools ? { tools } : {}),
+  };
+
+  // Create the agent session with IPC ask tool for user questions.
+  // The session loads extensions (custom providers) and picks the settings
+  // default model when none is passed.
+  const { session: agentSession } = await createAgentSession(sessionOptions);
+
+  session = agentSession;
+
+  // If a specific model was requested, resolve it through the session's
+  // registry (which now includes extension-registered providers) and switch
+  // to it. This handles "tama/whatevers-hot-n-fresh" and bare ids like "glm".
+  const modelString = initParams.agentModel ?? initParams.model;
+  const resolvedModel = resolveModel(modelString, session.modelRegistry);
+  if (resolvedModel && (session.model?.provider !== resolvedModel.provider || session.model?.id !== resolvedModel.id)) {
+    await session.setModel(resolvedModel);
+  }
+
+  // Bind extensions with empty bindings (no UI, no command context).
+  await session.bindExtensions({});
+
+  // Subscribe to agent events and stream them to parent.
+  session.subscribe((event) => {
+    const serialized = serializeEvent(event);
+    sendToParent({ type: "event", event: serialized as SerializedAgentEvent });
+
+    // On agent_end, exit the process.
+    if (event.type === "agent_end") {
+      const willRetry = (event as { willRetry?: boolean }).willRetry ?? false;
+      if (!willRetry) {
+        // Give events time to flush, then exit.
+        setTimeout(() => {
+          process.exit(0);
+        }, 100);
+      }
+    }
+  });
+
+  // Set up parent message handler for ask_response and abort.
+  process.on("message", handleParentMessage);
+
+  // Send ready signal to parent.
+  sendToParent({ type: "ready" });
+
+  // Start the agent loop.
+  // Prepend the agent's system prompt to the first prompt (no SDK-level systemPrompt option).
+  const fullPrompt = initParams.agentSystemPrompt && initParams.agentSystemPrompt.trim()
+    ? `${initParams.agentSystemPrompt}\n\n---\n\n${initParams.task}`
+    : initParams.task;
+  await session.prompt(fullPrompt);
+}
+
+// ── Graceful shutdown ───────────────────────────────────────────────────────
+
+function gracefulShutdown(signal: string): void {
+  if (session) {
+    session.abort();
+    session.dispose();
+  }
+  process.exit(signal === "SIGTERM" ? 143 : 130);
+}
+
+process.on("SIGTERM", () => gracefulShutdown("SIGTERM"));
+process.on("SIGINT", () => gracefulShutdown("SIGINT"));
+
+// ── Entry point ─────────────────────────────────────────────────────────────
+
+main().catch((err) => {
+  const message = err instanceof Error ? err.message : String(err);
+  sendToParent({ type: "error", message });
+  process.exit(1);
+});

package/src/handlers.ts

@@ -67,20 +67,23 @@ export function handleToolEnd(state: StreamState): void {
 }
 
 /**
- * Handle a tool_result_end event — capture tool output for live display.
+ * Handle a tool_execution_end event — capture tool result output for live display.
+ * The result is in event.result (the tool's return value).
  */
 export function handleToolResult(state: StreamState, event: JsonEvent): void {
-  const toolMessage = event.message as Record<string, unknown> | undefined;
-  if (!toolMessage || toolMessage.role !== "toolResult") return;
+  const result = event.result as Record<string, unknown> | undefined;
+  if (!result) return;
 
-  const toolContent = toolMessage.content as Array<Record<string, unknown>> | string | undefined;
-  const toolName = (toolMessage.toolName as string) ?? "tool";
+  const toolName = (event.toolName as string) ?? "tool";
 
-  if (typeof toolContent === "string" && toolContent.trim()) {
-    const lines = toolContent.split("\n").filter((l) => l.trim());
+  // Extract text content from tool result
+  const content = result.content as Array<Record<string, unknown>> | string | undefined;
+
+  if (typeof content === "string" && content.trim()) {
+    const lines = content.split("\n").filter((l) => l.trim());
     state.recentOutput.push(`[${toolName}] ${lines[0]?.slice(0, ARGS_PREVIEW_MAX)}`);
-  } else if (Array.isArray(toolContent)) {
-    for (const part of toolContent) {
+  } else if (Array.isArray(content)) {
+    for (const part of content) {
       if (part.type === "text" && (part.text as string)?.trim()) {
         const text = part.text as string;
         const lines = text.split("\n").filter((l) => l.trim());

package/src/index.ts

@@ -98,7 +98,7 @@ export function registerSubagent(pi: ExtensionAPI): void {
             agentConfig: t.agent ? findAgent(agents, t.agent) : undefined,
             task: t.task,
             model: t.model,
-            activeModel: ctx.model?.id,
+            activeModel: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined,
             cwd: t.cwd ?? undefined,
           })),
           signal: signal ?? undefined,
@@ -148,7 +148,7 @@ export function registerSubagent(pi: ExtensionAPI): void {
           agentConfig,
           task: params.task,
           model: params.model,
-          activeModel: ctx.model?.id,
+          activeModel: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined,
           cwd: params.cwd ?? undefined,
           signal: signal ?? undefined,
           onUpdate: (progress: SubagentProgress) => {

package/src/ipc-ask-tool.ts

@@ -0,0 +1,242 @@
+/**
+ * Minimal "ask" tool for the forked child process.
+ *
+ * Uses IPC (process.send / process.on("message")) to forward questions
+ * to the parent, which displays the UI and sends back the response.
+ */
+
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+import { randomUUID } from "node:crypto";
+
+// ── Schema (matches the existing ask tool) ───────────────────────────────────
+
+const OptionItemSchema = Type.Object({
+  label: Type.String({ description: "Display label" }),
+});
+
+const QuestionItemSchema = Type.Object({
+  id: Type.String({ description: "Question id" }),
+  question: Type.String({ description: "Question text" }),
+  description: Type.Optional(Type.String({
+    description: "Optional context in Markdown/plain text.",
+  })),
+  options: Type.Array(OptionItemSchema, {
+    description: "Available options. Do not include 'Other'.",
+    minItems: 1,
+  }),
+  multi: Type.Optional(Type.Boolean({ description: "Allow multi-select" })),
+  recommended: Type.Optional(Type.Number({
+    description: "0-indexed recommended option.",
+  })),
+});
+
+const AskParamsSchema = Type.Object({
+  questions: Type.Array(QuestionItemSchema, { description: "Questions to ask", minItems: 1 }),
+});
+
+type AskParams = Static<typeof AskParamsSchema>;
+
+// ── Session content helpers (minimal from packages/ask) ──────────────────────
+
+interface QuestionResult {
+  id: string;
+  question: string;
+  description: string | undefined;
+  options: string[];
+  multi: boolean;
+  selectedOptions: string[];
+  customInput: string | undefined;
+}
+
+function sanitizeForSessionText(value: string): string {
+  return value
+    .replace(/[\r\n\t]/g, " ")
+    .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, "")
+    .replace(/\s{2,}/g, " ")
+    .trim();
+}
+
+function sanitizeMultilineForSessionText(value: string): string {
+  return value
+    .replace(/\r\n/g, "\n")
+    .replace(/\r/g, "\n")
+    .split("\n")
+    .map((line) => sanitizeForSessionText(line))
+    .join("\n")
+    .trim();
+}
+
+function toSessionSafeQuestionResult(result: QuestionResult): QuestionResult {
+  const selectedOptions = result.selectedOptions
+    .map(sanitizeForSessionText)
+    .filter((s) => s.length > 0);
+
+  const rawDescription = result.description;
+  const description = rawDescription == null ? undefined : sanitizeMultilineForSessionText(rawDescription);
+  const rawCustomInput = result.customInput;
+  const customInput = rawCustomInput == null ? undefined : sanitizeForSessionText(rawCustomInput);
+
+  return {
+    id: sanitizeForSessionText(result.id) || "(unknown)",
+    question: sanitizeForSessionText(result.question) || "(empty question)",
+    description: description && description.length > 0 ? description : undefined,
+    options: result.options.map((o) => sanitizeForSessionText(o) || "(empty option)"),
+    multi: result.multi,
+    selectedOptions,
+    customInput: customInput && customInput.length > 0 ? customInput : undefined,
+  };
+}
+
+function formatSelectionForSummary(result: QuestionResult): string {
+  const hasSelected = result.selectedOptions.length > 0;
+  const hasCustom = Boolean(result.customInput);
+
+  if (!hasSelected && !hasCustom) return "(cancelled)";
+  if (hasSelected && hasCustom) {
+    const selected = result.multi ? `[${result.selectedOptions.join(", ")}]` : result.selectedOptions[0] ?? "";
+    return `${selected} + Other: "${result.customInput}"`;
+  }
+  if (hasCustom) return `"${result.customInput}"`;
+  if (result.multi) return `[${result.selectedOptions.join(", ")}]`;
+  return result.selectedOptions[0] ?? "";
+}
+
+function formatQuestionResult(result: QuestionResult): string {
+  return `${result.id}: ${formatSelectionForSummary(result)}`;
+}
+
+function formatQuestionContext(result: QuestionResult, index: number): string {
+  const lines: string[] = [
+    `Question ${index + 1} (${result.id})`,
+    `Prompt: ${result.question}`,
+  ];
+
+  if (result.description) {
+    lines.push("Context:");
+    for (const line of result.description.split("\n")) {
+      lines.push(`  ${line}`);
+    }
+  }
+
+  lines.push("Options:");
+  lines.push(...result.options.map((opt, i) => `  ${i + 1}. ${opt}`));
+  lines.push("Response:");
+
+  const hasSelected = result.selectedOptions.length > 0;
+  const hasCustom = Boolean(result.customInput);
+
+  if (!hasSelected && !hasCustom) {
+    lines.push("  Selected: (cancelled)");
+    return lines.join("\n");
+  }
+
+  if (hasSelected) {
+    const text = result.multi ? `[${result.selectedOptions.join(", ")}]` : result.selectedOptions[0];
+    lines.push(`  Selected: ${text}`);
+  }
+
+  if (hasCustom) {
+    if (!hasSelected) lines.push("  Selected: (Other)");
+    lines.push(`  Custom input: ${result.customInput}`);
+  }
+
+  return lines.join("\n");
+}
+
+function buildAskSessionContent(results: QuestionResult[]): string {
+  const safe = results.map(toSessionSafeQuestionResult);
+  const summary = safe.map(formatQuestionResult).join("\n");
+  const context = safe.map((r, i) => formatQuestionContext(r, i)).join("\n\n");
+  return `User answers:\n${summary}\n\nAnswer context:\n${context}`;
+}
+
+// ── Tool definition ─────────────────────────────────────────────────────────
+
+const ASK_TOOL_DESCRIPTION = `
+Ask the user for clarification when a choice materially affects the outcome.
+
+- Use when multiple valid approaches have different trade-offs.
+- Prefer 2-5 concise options.
+- Use multi=true when multiple answers are valid.
+- Use recommended=<index> (0-indexed) to mark the default option.
+- Use description to provide Markdown/plain context.
+- You can ask multiple related questions in one call using questions[].
+- Do NOT include an 'Other' option; UI adds it automatically.
+`.trim();
+
+export function createIpcAskTool(): ToolDefinition<any, unknown, any> {
+  return {
+    name: "ask",
+    label: "Ask",
+    description: ASK_TOOL_DESCRIPTION,
+    parameters: AskParamsSchema,
+
+    async execute(_toolCallId, params: AskParams, _signal, _onUpdate, _ctx) {
+      const requestId = randomUUID();
+      const questions = params.questions;
+
+      // Send ask_request to parent via IPC.
+      process.send?.({ type: "ask_request", requestId, questions });
+
+      // Await response from parent.
+      const response = await new Promise<{
+        cancelled: boolean;
+        results: Array<{ id: string; selectedOptions: string[]; customInput?: string }>;
+      }>((resolve) => {
+        let resolved = false;
+        const finish = (r: { cancelled: boolean; results: Array<{ id: string; selectedOptions: string[]; customInput?: string }> }) => {
+          if (resolved) return;
+          resolved = true;
+          clearTimeout(timer);
+          process.removeListener("message", listener);
+          resolve(r);
+        };
+
+        const listener = (msg: { type?: string; requestId?: string; cancelled?: boolean; results?: unknown[] }) => {
+          if (msg.type === "ask_response" && msg.requestId === requestId) {
+            finish({
+              cancelled: msg.cancelled ?? true,
+              results: msg.results as Array<{ id: string; selectedOptions: string[]; customInput?: string }>,
+            });
+          }
+        };
+        process.on("message", listener);
+
+        // 5-minute timeout.
+        const timer = setTimeout(() => {
+          finish({ cancelled: true, results: questions.map((q) => ({ id: q.id, selectedOptions: [] })) });
+        }, 5 * 60 * 1000);
+        timer.unref();
+      });
+
+      // Build results matching the existing ask tool's format.
+      const results: QuestionResult[] = questions.map((q, i) => {
+        const r = response.results[i];
+        return {
+          id: q.id,
+          question: q.question,
+          description: q.description && q.description.trim().length > 0 ? q.description : undefined,
+          options: q.options.map((o) => o.label),
+          multi: q.multi ?? false,
+          selectedOptions: r?.selectedOptions ?? [],
+          customInput: r?.customInput ?? undefined,
+        };
+      });
+
+      const contentText = buildAskSessionContent(results);
+
+      if (response.cancelled && results.every((r) => r.selectedOptions.length === 0)) {
+        return {
+          content: [{ type: "text", text: "User cancelled the question." }],
+          details: {},
+        };
+      }
+
+      return {
+        content: [{ type: "text", text: contentText }],
+        details: {},
+      };
+    },
+  };
+}

package/src/ipc-types.ts

@@ -0,0 +1,79 @@
+/**
+ * Shared IPC message types for fork+IPC subagent architecture.
+ *
+ * Parent sends "init" first, then "ask_response" / "abort".
+ * Child sends "ready" after init, then "event" / "ask_request" / "error".
+ */
+
+// ── Parent → Child ──────────────────────────────────────────────────────────
+
+export type ParentToChild =
+  | {
+      type: "ask_response";
+      requestId: string;
+      cancelled: boolean;
+      results: Array<{
+        id: string;
+        selectedOptions: string[];
+        customInput?: string;
+      }>;
+    }
+  | {
+      type: "abort";
+    }
+  | {
+      type: "init";
+      task: string;
+      model?: string;
+      agentName?: string;
+      agentSystemPrompt?: string;
+      agentTools?: string[];
+      agentModel?: string;
+      agentThinking?: string;
+      cwd?: string;
+    };
+
+// ── Serialized agent events ─────────────────────────────────────────────────
+// Matches the event types forwarded by stream.ts. Nested fields use `unknown`
+// because they contain complex objects (AgentMessage, etc.) serialized via
+// JSON.parse(JSON.stringify()). The key point is typing the `type` discriminator
+// and the top-level field names.
+
+export type SerializedAgentEvent =
+  | { type: "agent_start" }
+  | { type: "agent_end"; messages: unknown[]; willRetry?: boolean }
+  | { type: "turn_start" }
+  | { type: "turn_end"; message: unknown; toolResults: unknown[] }
+  | { type: "message_start"; message: unknown }
+  | { type: "message_update"; message: unknown; assistantMessageEvent: unknown }
+  | { type: "message_end"; message: unknown }
+  | { type: "tool_execution_start"; toolCallId: string; toolName: string; args: unknown }
+  | { type: "tool_execution_update"; toolCallId: string; toolName: string; args: unknown; partialResult: unknown }
+  | { type: "tool_execution_end"; toolCallId: string; toolName: string; result: unknown; isError: boolean };
+
+// ── Child → Parent ──────────────────────────────────────────────────────────
+
+export type ChildToParent =
+  | {
+      type: "event";
+      event: SerializedAgentEvent;
+    }
+  | {
+      type: "ask_request";
+      requestId: string;
+      questions: Array<{
+        id: string;
+        question: string;
+        description?: string;
+        options: Array<{ label: string }>;
+        multi?: boolean;
+        recommended?: number;
+      }>;
+    }
+  | {
+      type: "ready";
+    }
+  | {
+      type: "error";
+      message: string;
+    };

package/src/spawn.ts

@@ -1,22 +1,14 @@
-import { spawn, type ChildProcess } from "node:child_process";
-import { execSync } from "node:child_process";
-import { existsSync, writeFileSync, unlinkSync, mkdtempSync, rmdirSync, rmSync } from "node:fs";
-import { createServer, type Socket } from "node:net";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { fork, type ChildProcess } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
 import { getBus, Events } from "@pi-archimedes/core/bus";
+import type { ParentToChild, ChildToParent } from "./ipc-types.js";
 import type { AgentConfig } from "./agents.js";
 
-// Track all temp dirs for cleanup on process exit (graceful shutdown only).
-// Note: SIGKILL/OOM cannot be caught — the exit handler only fires for
-// normal exits and catchable signals (SIGTERM, SIGINT, SIGHUP, etc.).
-const tempDirs = new Set<string>();
-
-process.on("exit", () => {
-  for (const dir of tempDirs) {
-    try { rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ }
-  }
-});
+// Resolve child script path from this file's location
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const childScriptPath = join(__dirname, "child.ts");
 
 export interface SpawnOptions {
   task: string;
@@ -28,186 +20,87 @@ export interface SpawnOptions {
 }
 
 /**
- * Resolve the `pi` command — finds it on PATH.
- */
-export function resolvePiCommand(): { command: string; args: string[] } {
-  let piPath: string;
-  try {
-    piPath = execSync(process.platform === "win32" ? 'where pi' : 'which pi', {
-      encoding: "utf-8",
-    }).trim();
-  } catch {
-    throw new Error("pi command not found on PATH. Is pi installed?");
-  }
-
-  // On Windows, the CLI might be a .cmd script
-  if (process.platform === "win32" && !piPath.endsWith(".cmd") && !piPath.endsWith(".exe")) {
-    const cmdPath = piPath + ".cmd";
-    if (existsSync(cmdPath)) {
-      return { command: "cmd", args: ["/c", cmdPath] };
-    }
-  }
-  return { command: piPath, args: [] };
-}
-
-/**
- * Write system prompt to a temp file for --append-system-prompt.
- */
-function writePromptToFile(agentName: string, prompt: string): { dir: string; filePath: string } {
-  const safeName = agentName.replace(/[^\w.-]+/g, "_");
-  const tmpDir = mkdtempSync(join(tmpdir(), "pi-subagent-"));
-  tempDirs.add(tmpDir);
-  const filePath = join(tmpDir, `prompt-${safeName}.md`);
-  writeFileSync(filePath, prompt, { encoding: "utf-8" });
-  return { dir: tmpDir, filePath };
-}
-
-/**
- * Clean up temp prompt file and directory.
- */
-function cleanupTempFiles(dir: string | null, filePath: string | null): void {
-  if (filePath) {
-    try { unlinkSync(filePath); } catch { /* ignore */ }
-  }
-  if (dir) {
-    try {
-      rmdirSync(dir);
-      tempDirs.delete(dir);
-    } catch { /* leave in Set so exit handler can retry with rmSync */ }
-  }
-}
-
-/**
- * Spawn a child `pi` process in JSON mode.
+ * Spawn a child process via fork() with IPC channel.
  */
 export function spawnSubagent(options: SpawnOptions): ChildProcess {
-  const { command, args: baseArgs } = resolvePiCommand();
-  const args: string[] = [
-    ...baseArgs,
-    "--mode", "json",
-    "-p",
-    "--no-session",
-  ];
+  // Fork the child script with IPC channel
+  const child = fork(childScriptPath, [], {
+    cwd: options.cwd || process.cwd(),
+    env: { ...process.env },
+    execArgv: ["--experimental-strip-types"],
+    stdio: ["ignore", "ignore", "ignore", "ipc"],
+  });
 
-  // Create IPC socket for ask tool responses.
-  // On Unix: filesystem Unix domain socket. On Windows: named pipe (\\.\pipe\).
-  const socketName = `pi-subagent-${Date.now()}-${Math.random().toString(36).slice(2)}`;
-  const socketPath = process.platform === "win32"
-    ? `\\\\.\\pipe\\${socketName}`
-    : join(tmpdir(), socketName);
-  // Only Unix socket files need pre-unlinking; Windows named pipes auto-clean.
-  if (process.platform !== "win32") {
-    try { unlinkSync(socketPath); } catch { /* doesn't exist yet */ }
-  }
-  let clientSocket: Socket | undefined;
-  const pendingAsks = new Map<string, Socket>();
-  const server = createServer((socket: Socket) => {
-    clientSocket = socket;
-    (child as ChildProcess & { clientSocket: Socket | undefined }).clientSocket = socket;
-    // Parse incoming lines from the child's ask tool (ask_request) and forward to bus
-    let buffer = "";
-    socket.on("data", (data: Buffer) => {
-      buffer += data.toString();
-      const lines = buffer.split("\n");
-      buffer = lines.pop() ?? "";
-      for (const line of lines) {
-        try {
-          const msg = JSON.parse(line);
-          if (msg.type === "ask_request" && msg.requestId) {
-            pendingAsks.set(msg.requestId, socket);
-            getBus().emit(Events.ASK_REQUEST, {
-              source: `subagent:${options.agent?.name ?? "general"}`,
-              requestId: msg.requestId,
-              questions: msg.questions,
-            });
-          }
-        } catch { /* ignore non-JSON */ }
+  // Send init message to child with all configuration
+  // Model priority: agent.model > options.model > options.activeModel
+  const model = options.agent?.model ?? options.model ?? options.activeModel;
+  const initBase: Partial<ParentToChild> & { type: "init"; task: string } = {
+    type: "init",
+    task: options.task,
+  };
+  if (model) initBase.model = model;
+  if (options.agent?.name) initBase.agentName = options.agent.name;
+  if (options.agent?.systemPrompt) initBase.agentSystemPrompt = options.agent.systemPrompt;
+  if (options.agent?.tools) initBase.agentTools = options.agent.tools;
+  if (options.agent?.model) initBase.agentModel = options.agent.model;
+  if (options.agent?.thinking) initBase.agentThinking = options.agent.thinking;
+  if (options.cwd) initBase.cwd = options.cwd;
+  child.send(initBase as ParentToChild);
+
+  // Handle messages from child
+  child.on("message", (msg: ChildToParent) => {
+    switch (msg.type) {
+      case "event": {
+        // Forward events to streamEvents via the child's message handler
+        // (streamEvents attaches its own listener)
+        break;
       }
-    });
-    socket.on("close", () => {
-      clientSocket = undefined;
-      (child as ChildProcess & { clientSocket: Socket | undefined }).clientSocket = undefined;
-      // Clean up any pending asks tied to this socket
-      for (const [id, s] of pendingAsks) {
-        if (s === socket) pendingAsks.delete(id);
+      case "ask_request": {
+        // Forward ask requests to the bus for parent's ask dialog
+        getBus().emit(Events.ASK_REQUEST, {
+          source: `subagent:${options.agent?.name ?? "general"}`,
+          requestId: msg.requestId,
+          questions: msg.questions,
+        });
+        break;
+      }
+      case "ready": {
+        // Child is ready — session created
+        break;
+      }
+      case "error": {
+        console.error(`[subagent:child] ${msg.message}`);
+        break;
       }
-    });
-  });
-  server.listen(socketPath); // async, non-blocking
-
-  // Write ask responses back to the child over the originating socket
-  const unsubAskResponse = getBus().on(Events.ASK_RESPONSE, (payload: unknown) => {
-    const data = payload as { requestId: string; cancelled: boolean; results: Array<{ id: string; selectedOptions: string[]; customInput?: string }> };
-    const socket = pendingAsks.get(data.requestId);
-    if (socket && socket.writable) {
-      pendingAsks.delete(data.requestId);
-      socket.write(JSON.stringify({
-        type: "ask_response",
-        requestId: data.requestId,
-        cancelled: data.cancelled,
-        results: data.results,
-      }) + "\n");
-    }
-  });
-  server.on("close", () => {
-    if (process.platform !== "win32") {
-      try { unlinkSync(socketPath); } catch { /* ignore */ }
     }
   });
 
-  // Resolve model with correct priority:
-  // 1. frontmatter model (agent.model)
-  // 2. explicit tool-call model (options.model)
-  // 3. currently active model (options.activeModel)
-  // 4. no --model flag → pi default
-  const modelToUse = options.agent?.model ?? options.model ?? options.activeModel;
-  if (modelToUse) {
-    args.push("--model", modelToUse);
-  }
-
-  // Apply other agent config options
-  if (options.agent) {
-    const agent = options.agent;
-    if (agent.thinking) {
-      args.push("--thinking", agent.thinking);
-    }
-    if (agent.tools && agent.tools.length > 0) {
-      args.push("--tools", agent.tools.join(","));
-    }
-  }
-
-  // Temp files for system prompt
-  let tmpDir: string | null = null;
-  let tmpPath: string | null = null;
-
-  if (options.agent && options.agent.systemPrompt.trim()) {
-    const tmp = writePromptToFile(options.agent.name, options.agent.systemPrompt);
-    tmpDir = tmp.dir;
-    tmpPath = tmp.filePath;
-    args.push("--append-system-prompt", tmpPath);
-  }
-
-  args.push(options.task);
-
-  const child = spawn(command, args, {
-    cwd: options.cwd || process.cwd(),
-    stdio: ["ignore", "pipe", "pipe"],
-    env: {
-      ...process.env,
-      PI_SUBAGENT_SOCKET: socketPath,
-    },
+  // Handle ask responses from bus → send to child via IPC
+  const unsubAskResponse = getBus().on(Events.ASK_RESPONSE, (payload: unknown) => {
+    const data = payload as {
+      requestId: string;
+      cancelled: boolean;
+      results: Array<{ id: string; selectedOptions: string[]; customInput?: string }>;
+    };
+    const responseMsg: ParentToChild = {
+      type: "ask_response",
+      requestId: data.requestId,
+      cancelled: data.cancelled,
+      results: data.results,
+    };
+    child.send(responseMsg);
   });
 
   // Handle abort signal
   let abortHandler: (() => void) | undefined;
   if (options.signal) {
     abortHandler = () => {
+      // Send abort message to child before killing
+      child.send({ type: "abort" });
       if (child.pid && !child.killed) {
         child.kill("SIGTERM");
         const forceKill = setTimeout(() => {
-          if (!child.killed) {
-            child.kill("SIGKILL");
-          }
+          if (!child.killed) child.kill("SIGKILL");
         }, 3000);
         forceKill.unref();
       }
@@ -215,22 +108,17 @@ export function spawnSubagent(options: SpawnOptions): ChildProcess {
     options.signal.addEventListener("abort", abortHandler, { once: true });
   }
 
-  // Clean up temp files and listeners on exit
+  // Clean up on exit
   const exitCleanup = (): void => {
     child.removeListener("exit", exitCleanup);
     child.removeListener("error", exitCleanup);
     if (abortHandler && options.signal) {
       options.signal.removeEventListener("abort", abortHandler);
     }
-    server.close();
     unsubAskResponse();
-    if (clientSocket) clientSocket.destroy();
-    cleanupTempFiles(tmpDir, tmpPath);
   };
   child.on("exit", exitCleanup);
   child.on("error", exitCleanup);
 
-  // Attach client socket reference to child for streamEvents
-  (child as ChildProcess & { clientSocket: Socket | undefined }).clientSocket = clientSocket;
   return child;
 }

package/src/stream.ts

@@ -1,5 +1,5 @@
-import { createInterface } from "node:readline";
 import type { ChildProcess } from "node:child_process";
+import type { ChildToParent } from "./ipc-types.js";
 import type { StreamState, SubagentProgress, SubagentResult } from "./types.js";
 import { getBus, Events } from "@pi-archimedes/core/bus";
 import {
@@ -97,26 +97,21 @@ export function streamEvents(
     // Periodic progress updates for live duration display
     const heartbeat = setInterval(emitProgress, 1000);
 
-    // Collect stderr
-    const stderrParts: string[] = [];
-    child.stderr?.on("data", (data: Buffer) => {
-      stderrParts.push(data.toString());
-    });
-
-    // Parse JSON lines from stdout
-    const rl = createInterface({
-      input: child.stdout!,
-      crlfDelay: Infinity,
-    });
+    // Listen for IPC messages from child
+    child.on("message", (msg: unknown) => {
+      const childMsg = msg as ChildToParent;
 
-    rl.on("line", (line: string) => {
-      let event: JsonEvent;
-      try {
-        event = JSON.parse(line);
-      } catch {
-        return; // Skip non-JSON lines
+      // Handle error messages from child
+      if (childMsg.type === "error") {
+        error = childMsg.message;
+        return;
       }
 
+      // Only process "event" messages (AgentSessionEvent forwarded from child)
+      if (childMsg.type !== "event") return;
+
+      const event = childMsg.event as JsonEvent;
+
       // First event received from the child means the model has engaged —
       // from here on, the user controls lifetime via the abort signal.
       clearStartupTimer();
@@ -141,17 +136,15 @@ export function streamEvents(
         case "tool_execution_end": {
           handleToolEnd(state);
           emitProgress();
+          // Also capture tool result output here (previously in tool_result_end)
+          handleToolResult(state, event);
+          emitProgress();
           break;
         }
         case "turn_start": {
           state.turnCount++;
           break;
         }
-        case "tool_result_end": {
-          handleToolResult(state, event);
-          emitProgress();
-          break;
-        }
         case "message_end": {
           handleMessageEnd(state, event);
           emitProgress();
@@ -171,9 +164,7 @@ export function streamEvents(
       const durationMs = Date.now() - startTime;
       const exitCode = code ?? 1;
 
-      if (stderrParts.length > 0 && exitCode !== 0) {
-        error = stderrParts.join("").trim();
-      }
+      // Error is set via IPC error messages or remains undefined
 
       const result: SubagentResult = {
         agent: callbacks.agent ?? "subagent",