takomi 2.1.3 → 2.1.4

package/.pi/extensions/takomi-runtime/shared.ts

@@ -194,6 +194,13 @@ export type RunHooks = {
 export type JsonRunHooks = {
   onAssistantText?: (text: string) => void;
   onEventText?: (line: string) => void;
+  onToolEvent?: (event: {
+    type: "start" | "update" | "end";
+    toolName: string;
+    args?: string;
+    isError?: boolean;
+    summary?: string;
+  }) => void;
   onStderr?: (chunk: string) => void;
 };
 
@@ -346,6 +353,18 @@ export async function runPiAgentJson(cwd: string, args: string[], signal?: Abort
         const messageText = summarizeJsonEvent(event);
         if (messageText) hooks?.onEventText?.(messageText);
 
+        if (event.type === "tool_execution_start") {
+          const toolName = typeof event.toolName === "string" ? event.toolName : "tool";
+          const args = typeof event.args === "string" ? event.args : event.args ? JSON.stringify(event.args) : undefined;
+          hooks?.onToolEvent?.({ type: "start", toolName, args, summary: messageText });
+        } else if (event.type === "tool_execution_update") {
+          const toolName = typeof event.toolName === "string" ? event.toolName : "tool";
+          hooks?.onToolEvent?.({ type: "update", toolName, summary: messageText });
+        } else if (event.type === "tool_execution_end") {
+          const toolName = typeof event.toolName === "string" ? event.toolName : "tool";
+          hooks?.onToolEvent?.({ type: "end", toolName, isError: event.isError === true, summary: messageText });
+        }
+
         if (event.type === "message_end") {
           const message = event.message;
           if (message && typeof message === "object" && (message as { role?: string }).role === "assistant") {

package/.pi/extensions/takomi-runtime/subagent-types.ts

@@ -25,6 +25,13 @@ export type TakomiSubagentRun = {
   boardTaskStatus?: TakomiBoardTaskStatus;
   summary?: string;
   outputText?: string;
+  currentTool?: string;
+  currentToolArgs?: string;
+  currentToolStartedAt?: number;
+  recentTools?: Array<{ tool: string; args: string; endMs: number }>;
+  recentOutput?: string[];
+  toolCount?: number;
+  sessionFile?: string;
   logs: string[];
   startedAt: number;
   updatedAt: number;

package/.pi/extensions/takomi-subagents/dispatch.ts

@@ -53,6 +53,16 @@ export type TakomiDispatchResult = {
   output: string;
   stderr: string;
   preflight: string;
+  startedAt?: number;
+  endedAt?: number;
+  lastActivityAt?: number;
+  currentTool?: string;
+  currentToolArgs?: string;
+  currentToolStartedAt?: number;
+  recentTools?: Array<{ tool: string; args: string; endMs: number }>;
+  recentOutput?: string[];
+  toolCount?: number;
+  sessionFile?: string;
 };
 
 export type TakomiDispatchHooks = {
@@ -72,6 +82,21 @@ export async function dispatchTakomiSubagent(
   const sessionDir = path.join(input.rootCwd, ".pi", "takomi", "subagents");
   const sessionPath = path.join(sessionDir, `${conversationId}.jsonl`);
   await mkdir(sessionDir, { recursive: true });
+  const startedAt = Date.now();
+  let lastActivityAt = startedAt;
+  let currentTool: string | undefined;
+  let currentToolArgs: string | undefined;
+  let currentToolStartedAt: number | undefined;
+  let toolCount = 0;
+  let recentTools: Array<{ tool: string; args: string; endMs: number }> = [];
+  let recentOutput: string[] = [];
+
+  const appendRecentOutput = (text: string) => {
+    const lines = text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+    if (!lines.length) return;
+    recentOutput = [...recentOutput, ...lines].slice(-8);
+    lastActivityAt = Date.now();
+  };
 
   hooks?.emit?.({
     type: "start",
@@ -123,6 +148,13 @@ export async function dispatchTakomiSubagent(
       output: "",
       stderr: preflight.report,
       preflight: preflight.report,
+      startedAt,
+      endedAt: Date.now(),
+      lastActivityAt,
+      recentTools,
+      recentOutput,
+      toolCount,
+      sessionFile: sessionPath,
     };
     hooks?.emit?.({
       type: "block",
@@ -154,13 +186,62 @@ export async function dispatchTakomiSubagent(
 
   const result = await runPiAgentJson(subagentCwd, args, signal, {
     onAssistantText: (text) => {
-      hooks?.emit?.({ type: "update", runKey, patch: { outputText: text, boardTaskStatus: input.boardTaskStatus, checklist: input.checklist } });
+      appendRecentOutput(text);
+      hooks?.emit?.({
+        type: "update",
+        runKey,
+        patch: {
+          outputText: text,
+          recentOutput,
+          currentTool,
+          currentToolArgs,
+          currentToolStartedAt,
+          recentTools,
+          toolCount,
+          boardTaskStatus: input.boardTaskStatus,
+          checklist: input.checklist,
+        },
+      });
     },
     onEventText: (line) => {
+      appendRecentOutput(line);
       hooks?.emit?.({ type: "appendLog", runKey, chunk: line });
+      hooks?.emit?.({ type: "update", runKey, patch: { recentOutput, boardTaskStatus: input.boardTaskStatus, checklist: input.checklist } });
+    },
+    onToolEvent: (event) => {
+      lastActivityAt = Date.now();
+      if (event.type === "start") {
+        currentTool = event.toolName;
+        currentToolArgs = event.args;
+        currentToolStartedAt = Date.now();
+        toolCount += 1;
+      } else if (event.type === "end") {
+        recentTools = [...recentTools, { tool: event.toolName, args: currentTool === event.toolName ? currentToolArgs ?? "" : "", endMs: Date.now() }].slice(-8);
+        if (currentTool === event.toolName) {
+          currentTool = undefined;
+          currentToolArgs = undefined;
+          currentToolStartedAt = undefined;
+        }
+      }
+      hooks?.emit?.({
+        type: "update",
+        runKey,
+        patch: {
+          currentTool,
+          currentToolArgs,
+          currentToolStartedAt,
+          recentTools,
+          recentOutput,
+          toolCount,
+          boardTaskStatus: input.boardTaskStatus,
+          checklist: input.checklist,
+        },
+      });
     },
     onStderr: (chunk) => {
+      appendRecentOutput(chunk);
       hooks?.emit?.({ type: "appendLog", runKey, chunk });
+      hooks?.emit?.({ type: "update", runKey, patch: { recentOutput, boardTaskStatus: input.boardTaskStatus, checklist: input.checklist } });
     },
   });
 
@@ -177,6 +258,16 @@ export async function dispatchTakomiSubagent(
     output,
     stderr: result.stderr.trim(),
     preflight: preflight.report,
+    startedAt,
+    endedAt: Date.now(),
+    lastActivityAt,
+    currentTool,
+    currentToolArgs,
+    currentToolStartedAt,
+    recentTools,
+    recentOutput,
+    toolCount,
+    sessionFile: sessionPath,
   };
 
   if (result.code !== 0) {

package/.pi/extensions/takomi-subagents/index.ts

@@ -1,7 +1,7 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { Type } from "typebox";
 import { renderTakomiSubagentCall, renderTakomiSubagentResult } from "./native-render";
-import { executeTakomiSubagentTool } from "./tool-runner";
+import { createTakomiPiSubagentsEngine } from "./pi-subagents-engine";
 
 const ChecklistItemSchema = Type.Object({
   text: Type.String(),
@@ -50,6 +50,7 @@ const SubagentParameters = Type.Object({
 });
 
 function registerSubagentTool(pi: ExtensionAPI): void {
+  const engine = createTakomiPiSubagentsEngine(pi);
   pi.registerTool({
     name: "takomi_subagent",
     label: "Takomi",
@@ -62,8 +63,8 @@ function registerSubagentTool(pi: ExtensionAPI): void {
       "If review sends work back to the same agent, reuse the same conversationId for continuity.",
     ],
     parameters: SubagentParameters,
-    async execute(_toolCallId, params, signal, onUpdate, ctx) {
-      return executeTakomiSubagentTool(pi, params, signal, onUpdate, ctx);
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      return engine.execute(toolCallId, params, signal, onUpdate as any, ctx);
     },
     renderCall: renderTakomiSubagentCall,
     renderResult: renderTakomiSubagentResult,

package/.pi/extensions/takomi-subagents/live-updates.ts

@@ -16,11 +16,30 @@ type LiveTask = {
   conversationId?: string;
 };
 
+function mergeRecentTools(
+  existing: Array<{ tool: string; args: string; endMs: number }> | undefined,
+  incoming: Array<{ tool: string; args: string; endMs: number }> | undefined,
+): Array<{ tool: string; args: string; endMs: number }> | undefined {
+  if (!incoming?.length) return existing;
+  return incoming.slice(-8);
+}
+
 function appendLine(value: string, line: string): string {
   const next = [value, line.trim()].filter(Boolean).join("\n");
   return next.split(/\r?\n/).slice(-12).join("\n");
 }
 
+function compactOutputPreview(text: string): string[] {
+  const lines = text
+    .split(/\r?\n/)
+    .map((line) => line.replace(/\s+/g, " ").trim())
+    .filter(Boolean)
+    .filter((line) => !/^\*\*[^*]+\*\*\s+I\s/i.test(line))
+    .filter((line) => !/\bI need to make sure\b/i.test(line))
+    .filter((line) => !/\bI want the user to\b/i.test(line));
+  return lines.slice(-3);
+}
+
 export function createTakomiLiveUpdateBridge(
   tasks: LiveTask[],
   mode: "single" | "parallel" | "chain",
@@ -38,6 +57,11 @@ export function createTakomiLiveUpdateBridge(
     output: "Queued.",
     stderr: "",
     preflight: "",
+    startedAt: Date.now(),
+    lastActivityAt: Date.now(),
+    recentTools: [],
+    recentOutput: ["Queued."],
+    toolCount: 0,
   }));
 
   const emit = () => {
@@ -54,23 +78,52 @@ export function createTakomiLiveUpdateBridge(
     event(index: number, event: TakomiSubagentRuntimeEvent): void {
       const current = results[index];
       if (!current) return;
+      current.lastActivityAt = Date.now();
       if (event.type === "start") {
+        current.startedAt = current.startedAt ?? Date.now();
         current.conversationId = event.state.conversationId ?? current.conversationId;
         current.thinking = event.state.thinking ?? current.thinking;
+        current.sessionFile = event.state.sessionFile ?? current.sessionFile;
         current.output = event.state.summary ?? "Starting.";
+        current.recentOutput = [current.output].filter(Boolean).slice(-8);
       } else if (event.type === "update") {
         current.model = event.patch.model ?? current.model;
         current.thinking = event.patch.thinking ?? current.thinking;
+        current.sessionFile = event.patch.sessionFile ?? current.sessionFile;
+        current.currentTool = event.patch.currentTool;
+        current.currentToolArgs = event.patch.currentToolArgs;
+        current.currentToolStartedAt = event.patch.currentToolStartedAt;
+        current.recentTools = mergeRecentTools(current.recentTools, event.patch.recentTools);
+        current.toolCount = event.patch.toolCount ?? current.toolCount;
         current.output = event.patch.outputText ?? event.patch.summary ?? current.output;
+        current.recentOutput = event.patch.recentOutput
+          ?? (event.patch.outputText ? compactOutputPreview(event.patch.outputText) : current.recentOutput);
         if (event.patch.logs?.length) current.output = appendLine(current.output, event.patch.logs.join("\n"));
       } else if (event.type === "appendLog") {
         current.output = appendLine(current.output, event.chunk);
+        current.recentOutput = [...(current.recentOutput ?? []), event.chunk.trim()].filter(Boolean).slice(-8);
       } else if (event.type === "complete") {
         current.code = 0;
+        current.endedAt = Date.now();
+        current.currentTool = undefined;
+        current.currentToolArgs = undefined;
+        current.currentToolStartedAt = undefined;
         current.output = event.patch?.outputText ?? event.patch?.summary ?? current.output;
+        current.recentOutput = event.patch?.recentOutput ?? current.recentOutput;
+        current.recentTools = mergeRecentTools(current.recentTools, event.patch?.recentTools);
+        current.toolCount = event.patch?.toolCount ?? current.toolCount;
+        current.sessionFile = event.patch?.sessionFile ?? current.sessionFile;
       } else if (event.type === "block") {
         current.code = 1;
+        current.endedAt = Date.now();
+        current.currentTool = undefined;
+        current.currentToolArgs = undefined;
+        current.currentToolStartedAt = undefined;
         current.output = event.patch?.outputText ?? event.patch?.summary ?? current.output;
+        current.recentOutput = event.patch?.recentOutput ?? current.recentOutput;
+        current.recentTools = mergeRecentTools(current.recentTools, event.patch?.recentTools);
+        current.toolCount = event.patch?.toolCount ?? current.toolCount;
+        current.sessionFile = event.patch?.sessionFile ?? current.sessionFile;
         if (event.patch?.logs?.length) current.stderr = event.patch.logs.join("\n");
       }
       emit();

package/.pi/extensions/takomi-subagents/native-render.ts

@@ -1,174 +1,37 @@
-import { renderSubagentResult, syncResultAnimation } from "pi-subagents/src/tui/render";
-import type { AgentToolResult } from "@mariozechner/pi-agent-core";
-import type { Details, SingleResult, AgentProgress } from "pi-subagents/src/shared/types";
-import type { Theme } from "@mariozechner/pi-coding-agent";
-import { Container, Markdown, Spacer, Text } from "@mariozechner/pi-tui";
-import type { TakomiDispatchResult } from "./dispatch";
-import type { TakomiSubagentToolParams } from "./tool-runner";
-
-type ToolResult = {
-  content?: Array<{ type: string; text?: string }>;
-  details?: {
-    results?: TakomiDispatchResult[];
-    mode?: "single" | "parallel" | "chain";
-    agentScope?: string;
-    plan?: unknown;
-  };
-  isError?: boolean;
-};
-
-function taskList(params: TakomiSubagentToolParams): Array<{ agent: string; task: string }> {
-  if (params.chain?.length) return params.chain;
-  if (params.tasks?.length) return params.tasks;
-  if (params.agent || params.task) return [{ agent: params.agent ?? "...", task: params.task ?? "..." }];
-  return [];
-}
-
-export function renderTakomiSubagentCall(params: TakomiSubagentToolParams, theme: Theme) {
-  const tasks = taskList(params);
-  const mode = params.chain?.length ? "chain" : params.tasks?.length ? "parallel" : "single";
-  if (tasks.length === 1) {
-    return new Text(
-      `${theme.fg("toolTitle", theme.bold("takomi_subagent "))}${theme.fg("accent", tasks[0]?.agent || "?")}`,
-      0,
-      0,
-    );
-  }
-  return new Text(
-    `${theme.fg("toolTitle", theme.bold("takomi_subagent "))}${mode} (${tasks.length})`,
-    0,
-    0,
-  );
-}
-
-function parseTakomiOutput(outputText: string) {
-  const rawLines = outputText.split(/\r?\n/);
-  const textLines: string[] = [];
-  const recentTools: Array<{ tool: string; args: string; endMs: number }> = [];
-  let currentTool: string | undefined;
-  let currentToolArgs: string | undefined;
-
-  for (const line of rawLines) {
-    if (!line.trim()) continue;
-
-    // 1. Check for tool lifecycle markers
-    if (line.startsWith("Tool start: ")) {
-      currentTool = line.replace("Tool start: ", "").trim();
-      continue;
-    }
-    if (line.startsWith("Tool complete: ") || line.startsWith("Tool failed: ")) {
-      const toolName = line.replace(/Tool (complete|failed): /, "").trim();
-      recentTools.push({ tool: toolName, args: "", endMs: Date.now() });
-      if (currentTool === toolName) {
-        currentTool = undefined;
-        currentToolArgs = undefined;
-      }
-      continue;
-    }
-
-    // 2. Handle JSON blobs (tool calls)
-    const jsonStartIdx = line.indexOf('{"');
-    if (jsonStartIdx !== -1) {
-      const beforeJson = line.substring(0, jsonStartIdx).trim();
-      if (beforeJson) textLines.push(beforeJson);
-
-      const jsonPart = line.substring(jsonStartIdx);
-      try {
-        const parsed = JSON.parse(jsonPart);
-        const toolName = parsed.tool || (parsed.command ? parsed.command.split(" ")[0] : undefined);
-        if (toolName) {
-          const args = parsed.args ? JSON.stringify(parsed.args) : (parsed.command || "");
-          currentTool = toolName;
-          currentToolArgs = args;
-        }
-      } catch (e) {
-        if (jsonPart.trim().length > 1) {
-          textLines.push(jsonPart);
-        }
-      }
-      continue;
-    }
-
-    // 3. Skip lone brackets
-    const trimmed = line.trim();
-    if (trimmed === "{" || trimmed === "}") continue;
-
-    // 4. Everything else is text (thoughts)
-    textLines.push(line);
-  }
-
-  return { textLines, recentTools, currentTool, currentToolArgs };
-}
-
-export function renderTakomiSubagentResult(result: ToolResult, options: { expanded?: boolean; isPartial?: boolean }, theme: Theme, context: any) {
-  const details = result.details;
-  const results = details?.results ?? [];
-
-  if (results.length === 0) {
-    const text = result.content?.find((item) => item.type === "text")?.text ?? "(no output)";
-    return new Text(text, 0, 0);
-  }
-
-  const mappedResults: SingleResult[] = results.map((r, i) => {
-    const isRunning = r.code === -1;
-    const outputText = r.output || r.stderr || "";
-    const { textLines, recentTools, currentTool, currentToolArgs } = parseTakomiOutput(outputText);
-    
-    const recentOutput = textLines.slice(-5);
-
-    const progress: AgentProgress | undefined = isRunning ? {
-      index: i,
-      agent: r.agent,
-      status: "running",
-      task: r.task || "",
-      lastActivityAt: Date.now(),
-      currentTool,
-      currentToolArgs,
-      currentToolStartedAt: currentTool ? Date.now() : undefined,
-      recentTools,
-      recentOutput,
-      toolCount: recentTools.length + (currentTool ? 1 : 0),
-      tokens: 0,
-      durationMs: 0,
-    } : {
-      index: i,
-      agent: r.agent,
-      status: "completed", // Takomi results in mappedResults are usually final if code !== -1
-      task: r.task || "",
-      lastActivityAt: Date.now(),
-      recentTools,
-      recentOutput: [],
-      toolCount: recentTools.length,
-      tokens: 0,
-      durationMs: 0,
-    };
-
-    return {
-      agent: r.agent,
-      task: r.task || "",
-      exitCode: isRunning ? 0 : r.code,
-      model: r.model,
-      usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 },
-      progress,
-      truncation: isRunning ? undefined : {
-        text: textLines.join("\n").replace(/\n/g, "  \n"),
-        truncated: false
-      }
-    };
-  });
-
-  const mappedDetails: Details = {
-    mode: details?.mode ?? "single",
-    results: mappedResults,
-    chainAgents: details?.mode === "chain" ? results.map(r => r.agent) : undefined,
-  };
-
-  const agentToolResult: AgentToolResult<Details> = {
-    content: result.content as any || [],
-    details: mappedDetails,
-  };
-
-  syncResultAnimation(agentToolResult, context);
-  return renderSubagentResult(agentToolResult, { expanded: options.expanded ?? false }, theme);
-}
-
+import { renderSubagentResult, syncResultAnimation } from "pi-subagents/src/tui/render";
+import type { AgentToolResult } from "@mariozechner/pi-agent-core";
+import type { Details } from "pi-subagents/src/shared/types";
+import type { Theme } from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+import type { TakomiSubagentToolParams } from "./tool-runner";
+
+type ToolResult = AgentToolResult<Details>;
+
+function taskList(params: TakomiSubagentToolParams): Array<{ agent: string; task: string }> {
+  if (params.chain?.length) return params.chain;
+  if (params.tasks?.length) return params.tasks;
+  if (params.agent || params.task) return [{ agent: params.agent ?? "...", task: params.task ?? "..." }];
+  return [];
+}
+
+export function renderTakomiSubagentCall(params: TakomiSubagentToolParams, theme: Theme) {
+  const tasks = taskList(params);
+  const mode = params.chain?.length ? "chain" : params.tasks?.length ? "parallel" : "single";
+  if (tasks.length === 1) {
+    return new Text(
+      `${theme.fg("toolTitle", theme.bold("takomi_subagent "))}${theme.fg("accent", tasks[0]?.agent || "?")}`,
+      0,
+      0,
+    );
+  }
+  return new Text(
+    `${theme.fg("toolTitle", theme.bold("takomi_subagent "))}${mode} (${tasks.length})`,
+    0,
+    0,
+  );
+}
+
+export function renderTakomiSubagentResult(result: ToolResult, options: { expanded?: boolean; isPartial?: boolean }, theme: Theme, context: any) {
+  syncResultAnimation(result, context);
+  return renderSubagentResult(result, { expanded: options.expanded ?? false }, theme);
+}

package/.pi/extensions/takomi-subagents/pi-subagents-engine.ts

@@ -0,0 +1,228 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { AgentToolResult } from "@mariozechner/pi-agent-core";
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { createSubagentExecutor, type SubagentParamsLike } from "pi-subagents/src/runs/foreground/subagent-executor";
+import { discoverAgents as discoverPiAgents, type AgentConfig, type AgentScope } from "pi-subagents/src/agents/agents";
+import {
+  DEFAULT_ARTIFACT_CONFIG,
+  TEMP_ARTIFACTS_DIR,
+  type Details,
+  type ExtensionConfig,
+  type SubagentState,
+} from "pi-subagents/src/shared/types";
+import { resolveAgentName } from "./agent-aliases";
+import type { TakomiSubagentToolParams, TakomiSubagentToolTask } from "./tool-runner";
+
+type ToolUpdate = (partial: AgentToolResult<Details>) => void;
+
+function getSubagentSessionRoot(parentSessionFile: string | null): string {
+  if (parentSessionFile) {
+    const baseName = path.basename(parentSessionFile, ".jsonl");
+    return path.join(path.dirname(parentSessionFile), baseName);
+  }
+  return fs.mkdtempSync(path.join(os.tmpdir(), "takomi-subagent-session-"));
+}
+
+function expandTilde(value: string): string {
+  return value.startsWith("~/") ? path.join(os.homedir(), value.slice(2)) : value;
+}
+
+function createState(): SubagentState {
+  return {
+    baseCwd: process.cwd(),
+    currentSessionId: null,
+    asyncJobs: new Map(),
+    foregroundRuns: new Map(),
+    foregroundControls: new Map(),
+    lastForegroundControlId: null,
+    pendingForegroundControlNotices: new Map(),
+    cleanupTimers: new Map(),
+    lastUiContext: null,
+    poller: null,
+    completionSeen: new Map(),
+    watcher: null,
+    watcherRestartTimer: null,
+    resultFileCoalescer: {
+      schedule: () => false,
+      clear: () => {},
+    },
+  };
+}
+
+function resolveMode(params: TakomiSubagentToolParams): "single" | "parallel" | "chain" | undefined {
+  const hasChain = Boolean(params.chain?.length);
+  const hasParallel = Boolean(params.tasks?.length);
+  const hasSingle = Boolean(params.agent && params.task);
+  if (Number(hasChain) + Number(hasParallel) + Number(hasSingle) !== 1) return undefined;
+  return hasChain ? "chain" : hasParallel ? "parallel" : "single";
+}
+
+function resolveTasks(params: TakomiSubagentToolParams): TakomiSubagentToolTask[] {
+  if (params.chain?.length) return params.chain;
+  if (params.tasks?.length) return params.tasks;
+  if (params.agent && params.task) {
+    return [{
+      agent: params.agent,
+      task: params.task,
+      workflow: params.workflow,
+      skills: params.skills,
+      model: params.model,
+      fallbackModels: params.fallbackModels,
+      thinking: params.thinking,
+      conversationId: params.conversationId,
+      cwd: params.cwd,
+      checklist: params.checklist,
+    }];
+  }
+  return [];
+}
+
+function normalizeThinking(value: unknown): string | undefined {
+  return typeof value === "string" && ["off", "minimal", "low", "medium", "high", "xhigh"].includes(value) ? value : undefined;
+}
+
+function buildTakomiTaskPrompt(task: TakomiSubagentToolTask): string {
+  const checklist = task.checklist?.length
+    ? [
+        "Checklist:",
+        ...task.checklist.map((item) => typeof item === "string" ? `- [ ] ${item}` : `- [${item.done ? "x" : " "}] ${item.text}`),
+      ].join("\n")
+    : "";
+  const takomiContext = [
+    task.workflow ? `Takomi workflow: ${task.workflow}` : "",
+    task.skills?.length ? `Takomi skills/context overlays: ${task.skills.join(", ")}` : "",
+    checklist,
+  ].filter(Boolean).join("\n\n");
+
+  return takomiContext ? `${takomiContext}\n\n${task.task}` : task.task;
+}
+
+function modelWithThinking(model: string | undefined, thinking: string | undefined): string | undefined {
+  const level = normalizeThinking(thinking);
+  if (!model || !level || level === "off") return model;
+  if (/:(off|minimal|low|medium|high|xhigh)$/i.test(model)) return model;
+  return `${model}:${level}`;
+}
+
+function defaultChildExtensions(): string[] {
+  // Child runs must not auto-load every user/project extension because this repo
+  // currently has both global and project Takomi extensions, which causes tool
+  // name conflicts in children. But model providers such as oauth-router are
+  // extensions too, so we explicitly allow the provider extension through.
+  const candidates = [
+    path.join(os.homedir(), ".pi", "agent", "extensions", "oauth-router", "index.ts"),
+  ];
+  return candidates.filter((candidate) => fs.existsSync(candidate));
+}
+
+function withTakomiAgentDefaults(agent: AgentConfig): AgentConfig {
+  return {
+    ...agent,
+    systemPromptMode: agent.systemPromptMode ?? "replace",
+    inheritProjectContext: agent.inheritProjectContext ?? true,
+    inheritSkills: agent.inheritSkills ?? false,
+    defaultContext: agent.defaultContext ?? "fresh",
+    extensions: [...new Set([...(agent.extensions ?? []), ...defaultChildExtensions()])],
+  };
+}
+
+function discoverUnifiedAgents(cwd: string, scope: AgentScope): { agents: AgentConfig[] } {
+  return { agents: discoverPiAgents(cwd, scope).agents.map(withTakomiAgentDefaults) };
+}
+
+function agentNameSet(cwd: string): Set<string> {
+  return new Set(discoverUnifiedAgents(cwd, "both").agents.map((agent) => agent.name));
+}
+
+function mapSingleTask(task: TakomiSubagentToolTask, names: Set<string>) {
+  const resolvedAgent = resolveAgentName(task.agent, new Map([...names].map((name) => [name, { name } as any])));
+  return {
+    agent: resolvedAgent,
+    task: buildTakomiTaskPrompt({ ...task, agent: resolvedAgent }),
+    cwd: task.cwd,
+    model: modelWithThinking(task.model, task.thinking),
+  };
+}
+
+function toSubagentParams(params: TakomiSubagentToolParams, rootCwd: string): SubagentParamsLike {
+  const mode = resolveMode(params);
+  const tasks = resolveTasks(params);
+  const names = agentNameSet(rootCwd);
+  if (!mode) throw new Error("Provide exactly one mode: agent/task, tasks, or chain.");
+
+  const base = {
+    agentScope: params.agentScope ?? "both",
+    cwd: rootCwd,
+    context: "fresh" as const,
+    async: false,
+    clarify: false,
+    includeProgress: true,
+  };
+
+  if (mode === "single") {
+    const task = tasks[0]!;
+    const mapped = mapSingleTask(task, names);
+    return {
+      ...base,
+      agent: mapped.agent,
+      task: mapped.task,
+      cwd: task.cwd ? path.resolve(rootCwd, task.cwd) : rootCwd,
+      model: mapped.model,
+    };
+  }
+
+  if (mode === "parallel") {
+    return {
+      ...base,
+      tasks: tasks.map((task) => mapSingleTask(task, names)),
+    };
+  }
+
+  return {
+    ...base,
+    chain: tasks.map((task) => {
+      const mapped = mapSingleTask(task, names);
+      return {
+        agent: mapped.agent,
+        task: mapped.task,
+        cwd: task.cwd,
+        model: mapped.model,
+      };
+    }),
+  };
+}
+
+export function createTakomiPiSubagentsEngine(pi: ExtensionAPI) {
+  const state = createState();
+  const config: ExtensionConfig = {
+    maxSubagentDepth: 2,
+    asyncByDefault: false,
+    forceTopLevelAsync: false,
+  };
+  const executor = createSubagentExecutor({
+    pi,
+    state,
+    config,
+    asyncByDefault: false,
+    tempArtifactsDir: TEMP_ARTIFACTS_DIR,
+    getSubagentSessionRoot,
+    expandTilde,
+    discoverAgents: discoverUnifiedAgents,
+  });
+
+  return {
+    async execute(
+      id: string,
+      params: TakomiSubagentToolParams,
+      signal: AbortSignal | undefined,
+      onUpdate: ToolUpdate | undefined,
+      ctx: ExtensionContext,
+    ): Promise<AgentToolResult<Details>> {
+      const rootCwd = params.cwd ? path.resolve(ctx.cwd, params.cwd) : ctx.cwd;
+      const subagentParams = toSubagentParams(params, rootCwd);
+      return executor.execute(id, subagentParams, signal ?? new AbortController().signal, onUpdate, ctx);
+    },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "takomi",
-  "version": "2.1.3",
+  "version": "2.1.4",
   "description": "🎯 Stop wrestling with AI. Start building with purpose. The artisan's toolkit for agent workflows, Codex skills, and original Takomi capabilities like 21st.dev integration.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -44,6 +44,7 @@ import { runDoctor } from './doctor.js';
 import { ensurePiInstalled, ensurePiSubagentsInstalled, launchTakomiHarness, printPiInstallResult, printPiSubagentsInstallResult } from './pi-harness.js';
 import { installPiHarnessAssets, printPiInstallSummary, syncPiHarnessAssets, validatePiHarnessInstall } from './pi-installer.js';
 import { installBundledSkills, printSkillsInstallSummary, validateSkillsInstall } from './skills-installer.js';
+import { notifyIfTakomiUpdateAvailable, printTakomiUpdateStatus, upgradeTakomiPackage } from './update-check.js';
 
 const packageJson = await fs.readJson(PATHS.packageJson);
 const program = new Command();
@@ -713,6 +714,18 @@ program
   .description('Run Pi/Takomi installation diagnostics')
   .action(() => runDoctor({ version: program.version() }));
 
+program
+  .command('check-update')
+  .description('Check whether a newer Takomi package is available')
+  .action(() => printTakomiUpdateStatus(program.version()));
+
+program
+  .command('upgrade')
+  .description('Manually update the global Takomi CLI package from npm')
+  .action(() => {
+    process.exitCode = upgradeTakomiPackage();
+  });
+
 // Update from GitHub (EXISTING — enhanced)
 program
   .command('update')
@@ -783,6 +796,7 @@ program
   });
 
 if (process.argv.length <= 2) {
+  notifyIfTakomiUpdateAvailable(program.version());
   const exitCode = await launchTakomiHarness(process.cwd());
   process.exitCode = exitCode;
 } else {

package/src/update-check.js

@@ -0,0 +1,140 @@
+import fs from 'fs-extra';
+import os from 'os';
+import path from 'path';
+import https from 'https';
+import { spawnSync } from 'child_process';
+import pc from 'picocolors';
+
+const CHECK_INTERVAL_MS = 12 * 60 * 60 * 1000;
+const CACHE_PATH = path.join(os.homedir(), '.takomi', 'update-check.json');
+const REGISTRY_URL = 'https://registry.npmjs.org/takomi/latest';
+
+function parseVersion(version = '') {
+  const [core] = String(version).replace(/^v/, '').split('-');
+  return core.split('.').map((part) => Number.parseInt(part, 10) || 0);
+}
+
+export function isNewerVersion(latest, current) {
+  const a = parseVersion(latest);
+  const b = parseVersion(current);
+  for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
+    const left = a[i] || 0;
+    const right = b[i] || 0;
+    if (left > right) return true;
+    if (left < right) return false;
+  }
+  return false;
+}
+
+function fetchLatestPackageInfo(timeoutMs = 2500) {
+  return new Promise((resolve) => {
+    const req = https.get(REGISTRY_URL, {
+      headers: {
+        'accept': 'application/json',
+        'user-agent': 'takomi-update-check',
+      },
+      timeout: timeoutMs,
+    }, (res) => {
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', () => {
+        if (res.statusCode && res.statusCode >= 400) return resolve(null);
+        try {
+          resolve(JSON.parse(body));
+        } catch {
+          resolve(null);
+        }
+      });
+    });
+    req.on('timeout', () => {
+      req.destroy();
+      resolve(null);
+    });
+    req.on('error', () => resolve(null));
+  });
+}
+
+async function readCache() {
+  try {
+    return await fs.readJson(CACHE_PATH);
+  } catch {
+    return null;
+  }
+}
+
+async function writeCache(cache) {
+  try {
+    await fs.ensureDir(path.dirname(CACHE_PATH));
+    await fs.writeJson(CACHE_PATH, cache, { spaces: 2 });
+  } catch {
+    // Update checks must never block normal Takomi startup.
+  }
+}
+
+export async function getLatestTakomiVersion({ currentVersion, force = false } = {}) {
+  const now = Date.now();
+  const cache = await readCache();
+  if (!force && cache?.checkedAt && now - cache.checkedAt < CHECK_INTERVAL_MS) {
+    return cache;
+  }
+
+  const info = await fetchLatestPackageInfo();
+  const latestVersion = typeof info?.version === 'string' ? info.version : null;
+  const next = {
+    checkedAt: now,
+    currentVersion,
+    latestVersion,
+    updateAvailable: Boolean(latestVersion && currentVersion && isNewerVersion(latestVersion, currentVersion)),
+  };
+  await writeCache(next);
+  return next;
+}
+
+export function notifyIfTakomiUpdateAvailable(currentVersion) {
+  if (process.env.TAKOMI_NO_UPDATE_CHECK === '1') return;
+
+  // Fire-and-forget by design: launching the Takomi harness must never wait on
+  // network, DNS, npm registry latency, or cache file IO.
+  setTimeout(() => {
+    getLatestTakomiVersion({ currentVersion })
+      .then((result) => {
+        if (!result?.updateAvailable) return;
+        console.log(pc.yellow(`\n⬆ Takomi ${result.latestVersion} is available (installed: ${currentVersion}).`));
+        console.log(pc.dim('  Run: takomi upgrade'));
+        console.log(pc.dim('  Disable this check with TAKOMI_NO_UPDATE_CHECK=1.\n'));
+      })
+      .catch(() => {
+        // Silent: update checks must never affect harness startup or usage.
+      });
+  }, 0).unref?.();
+}
+
+export async function printTakomiUpdateStatus(currentVersion) {
+  const result = await getLatestTakomiVersion({ currentVersion, force: true });
+  if (!result?.latestVersion) {
+    console.log(pc.yellow('Could not check the npm registry for Takomi updates.'));
+    return;
+  }
+  if (result.updateAvailable) {
+    console.log(pc.yellow(`Takomi ${result.latestVersion} is available (installed: ${currentVersion}).`));
+    console.log(pc.dim('Run: takomi upgrade'));
+    return;
+  }
+  console.log(pc.green(`Takomi is up to date (${currentVersion}).`));
+}
+
+export function upgradeTakomiPackage() {
+  console.log(pc.cyan('Updating Takomi from npm...\n'));
+  const command = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  const result = spawnSync(command, ['install', '-g', 'takomi@latest'], {
+    stdio: 'inherit',
+    shell: process.platform === 'win32',
+  });
+  if (result.status === 0) {
+    console.log(pc.green('\nTakomi updated. Run `takomi --version` to confirm.'));
+    return 0;
+  }
+  console.log(pc.red('\nTakomi update failed. Try manually: npm install -g takomi@latest'));
+  return result.status || 1;
+}