takomi 2.0.7 → 2.1.0

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

@@ -0,0 +1,133 @@
+import type { AssistantMessage } from "@mariozechner/pi-ai";
+import type { ExtensionContext, ReadonlyFooterDataProvider, Theme } from "@mariozechner/pi-coding-agent";
+import {
+  ellipsizeMiddle,
+  formatFooterNumber,
+  truncateToWidth,
+  visibleWidth,
+} from "./shared";
+
+interface Component {
+  render(width: number): string[];
+  invalidate(): void;
+  dispose?(): void;
+}
+
+interface RenderTui {
+  requestRender(force?: boolean): void;
+}
+
+export type RuntimeHudState = {
+  enabled: boolean;
+  autoOrch: boolean;
+  planMode: boolean;
+  role: string;
+  stage?: string;
+  workflow?: string;
+  activeSessionId?: string;
+  launchMode?: string;
+  subagentsEnabled?: boolean;
+};
+
+type Tone = "accent" | "warning" | "success" | "error" | "muted" | "dim" | "thinkingMinimal";
+
+function stageTone(stage?: string): Tone {
+  switch (stage) {
+    case "genesis":
+      return "thinkingMinimal";
+    case "design":
+      return "accent";
+    case "build":
+      return "warning";
+    default:
+      return "muted";
+  }
+}
+
+function badge(theme: Theme, label: string, tone: Tone): string {
+  return theme.fg(tone, `<${label.toUpperCase()}>`);
+}
+
+export function renderRuntimeStatus(theme: Theme, state: RuntimeHudState): string {
+  const primary = state.stage ?? state.role;
+  const stageBadge = badge(theme, primary, stageTone(state.stage));
+  const auto = state.autoOrch ? theme.fg("accent", "auto") : theme.fg("dim", "manual");
+  const gate = state.launchMode === "manual" ? theme.fg("warning", "review-gate") : theme.fg("accent", "auto-gate");
+  const plan = state.planMode ? theme.fg("warning", "plan") : theme.fg("dim", "direct");
+  const subagents = state.subagentsEnabled === false ? theme.fg("error", "subagents:off") : theme.fg("dim", "subagents:on");
+  return [theme.fg("accent", "Takomi"), stageBadge, theme.fg("dim", `role:${state.role}`), auto, gate, plan, subagents].join(" ");
+}
+
+export function renderRuntimeWidget(theme: Theme, state: RuntimeHudState): string[] {
+  if (!state.enabled) return [];
+  const primary = state.stage ?? state.role;
+  const parts = [
+    theme.fg("accent", "Takomi"),
+    badge(theme, primary, stageTone(state.stage)),
+    theme.fg("dim", `role:${state.role}`),
+    state.autoOrch ? theme.fg("accent", "auto") : theme.fg("dim", "manual"),
+    state.launchMode === "manual" ? theme.fg("warning", "review-gate") : theme.fg("accent", "auto-gate"),
+    state.planMode ? theme.fg("warning", "plan") : theme.fg("dim", "direct"),
+    state.subagentsEnabled === false ? theme.fg("error", "subagents:off") : theme.fg("dim", "subagents:on"),
+    state.workflow ? theme.fg("dim", `wf:${state.workflow}`) : "",
+    state.activeSessionId ? theme.fg("dim", `session:${ellipsizeMiddle(state.activeSessionId, 12)}`) : "",
+  ].filter(Boolean);
+  return [parts.join("  ")];
+}
+
+export class TakomiFooterComponent implements Component {
+  private readonly unsubscribeBranchChange: () => void;
+
+  constructor(
+    private readonly tui: RenderTui,
+    private readonly theme: Theme,
+    private readonly footerData: ReadonlyFooterDataProvider,
+    private readonly ctx: ExtensionContext,
+    private readonly getState: () => RuntimeHudState,
+  ) {
+    this.unsubscribeBranchChange = footerData.onBranchChange(() => {
+      this.tui.requestRender();
+    });
+  }
+
+  dispose(): void {
+    this.unsubscribeBranchChange();
+  }
+
+  invalidate(): void {}
+
+  render(width: number): string[] {
+    const state = this.getState();
+    let input = 0;
+    let output = 0;
+    let cost = 0;
+
+    for (const entry of this.ctx.sessionManager.getBranch()) {
+      if (entry.type === "message" && entry.message.role === "assistant") {
+        const message = entry.message as AssistantMessage;
+        input += message.usage.input;
+        output += message.usage.output;
+        cost += message.usage.cost.total;
+      }
+    }
+
+    const cwd = this.theme.fg("dim", this.ctx.cwd);
+    const stats = this.theme.fg("dim", `up:${formatFooterNumber(input)} down:${formatFooterNumber(output)} $${cost.toFixed(3)}`);
+    const leftPad = " ".repeat(Math.max(1, width - visibleWidth(cwd) - visibleWidth(stats)));
+    const topLine = truncateToWidth(`${cwd}${leftPad}${stats}`, width);
+
+    const extensionStatuses = [...this.footerData.getExtensionStatuses().entries()]
+      .filter(([key]) => key !== "takomi-runtime")
+      .map(([, value]) => value)
+      .filter(Boolean);
+    const runtimeStatus = renderRuntimeStatus(this.theme, state);
+    const left = [runtimeStatus, ...extensionStatuses].join(this.theme.fg("dim", "  |  "));
+    const branch = this.footerData.getGitBranch();
+    const rightText = [this.ctx.model?.id || "no-model", branch ? `git:${branch}` : ""].filter(Boolean).join(" | ");
+    const right = this.theme.fg("dim", rightText);
+    const rightPad = " ".repeat(Math.max(1, width - visibleWidth(left) - visibleWidth(right)));
+    const bottomLine = truncateToWidth(`${left}${rightPad}${right}`, width);
+
+    return [topLine, bottomLine];
+  }
+}

package/.pi/extensions/takomi-subagents/agent-aliases.ts

@@ -0,0 +1,18 @@
+import type { TakomiAgentConfig } from "./agents";
+
+const AGENT_ALIASES: Record<string, string[]> = {
+  general: ["orchestrator", "coder", "architect"],
+  code: ["coder"],
+  build: ["coder", "orchestrator"],
+  design: ["designer"],
+  review: ["reviewer"],
+  architecture: ["architect"],
+};
+
+export function resolveAgentName(name: string, agents: Map<string, TakomiAgentConfig>): string {
+  if (agents.has(name)) return name;
+  const lower = name.toLowerCase();
+  const exactCase = [...agents.keys()].find((agentName) => agentName.toLowerCase() === lower);
+  if (exactCase) return exactCase;
+  return AGENT_ALIASES[lower]?.find((candidate) => agents.has(candidate)) ?? name;
+}

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

@@ -0,0 +1,113 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir, parseFrontmatter } from "@mariozechner/pi-coding-agent";
+import type { TakomiThinkingLevel } from "../../../src/pi-takomi-core";
+
+export type TakomiAgentScope = "user" | "project" | "both";
+
+export type TakomiAgentConfig = {
+  name: string;
+  description: string;
+  tools?: string[];
+  model?: string;
+  fallbackModels?: string[];
+  thinking?: TakomiThinkingLevel;
+  systemPrompt: string;
+  filePath: string;
+  source: "user" | "project";
+};
+
+function splitList(value?: string): string[] | undefined {
+  const parts = value
+    ?.split(",")
+    .map((part) => part.trim())
+    .filter(Boolean);
+  return parts?.length ? parts : undefined;
+}
+
+function normalizeThinking(value?: string): TakomiThinkingLevel | undefined {
+  if (
+    value === "off"
+    || value === "minimal"
+    || value === "low"
+    || value === "medium"
+    || value === "high"
+    || value === "xhigh"
+  ) {
+    return value;
+  }
+  return undefined;
+}
+
+function loadAgentsFromDirectory(agentsDir: string, source: "user" | "project"): TakomiAgentConfig[] {
+  if (!fs.existsSync(agentsDir)) return [];
+
+  const entries = fs.readdirSync(agentsDir, { withFileTypes: true });
+  const agents: TakomiAgentConfig[] = [];
+
+  for (const entry of entries) {
+    if (!entry.name.endsWith(".md")) continue;
+    const filePath = path.join(agentsDir, entry.name);
+    const content = fs.readFileSync(filePath, "utf8");
+    const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
+    if (!frontmatter.name || !frontmatter.description) continue;
+
+    agents.push({
+      name: frontmatter.name,
+      description: frontmatter.description,
+      tools: splitList(frontmatter.tools),
+      model: frontmatter.model,
+      fallbackModels: splitList(frontmatter.fallbackModels ?? frontmatter.fallback_models),
+      thinking: normalizeThinking(frontmatter.thinking),
+      systemPrompt: body,
+      filePath,
+      source,
+    });
+  }
+
+  return agents;
+}
+
+function isDirectory(target: string): boolean {
+  try {
+    return fs.statSync(target).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function findNearestProjectAgentsDirs(cwd: string): string[] {
+  let current = cwd;
+  while (true) {
+    const candidates = [
+      path.join(current, ".pi", "agents"),
+      path.join(current, ".agents"),
+    ].filter(isDirectory);
+    if (candidates.length > 0) return candidates;
+    const parent = path.dirname(current);
+    if (parent === current) return [];
+    current = parent;
+  }
+}
+
+export function discoverTakomiAgents(cwd: string, scope: TakomiAgentScope = "both"): TakomiAgentConfig[] {
+  const projectAgentsDirs = findNearestProjectAgentsDirs(cwd);
+  const localAgents = scope === "user"
+    ? []
+    : projectAgentsDirs.flatMap((agentsDir) => loadAgentsFromDirectory(agentsDir, "project"));
+  const globalAgents = scope === "project" ? [] : loadAgentsFromDirectory(path.join(getAgentDir(), "agents"), "user");
+  const merged = new Map<string, TakomiAgentConfig>();
+
+  for (const agent of globalAgents) {
+    merged.set(agent.name, agent);
+  }
+  for (const agent of localAgents) {
+    merged.set(agent.name, agent);
+  }
+
+  return [...merged.values()];
+}
+
+export function discoverProjectAgents(cwd: string): TakomiAgentConfig[] {
+  return discoverTakomiAgents(cwd, "both");
+}

package/.pi/extensions/takomi-subagents/delegation-plan.ts

@@ -0,0 +1,95 @@
+import type {
+  TakomiDelegationPlan,
+  TakomiDelegationPlanTask,
+  TakomiDispatchPolicy,
+  TakomiLaunchMode,
+  TakomiProfile,
+  TakomiRole,
+  TakomiThinkingLevel,
+  TakomiWorkflowId,
+  VibeLifecycleStage,
+} from "../../../src/pi-takomi-core";
+import type { ChecklistInput } from "../takomi-runtime/shared";
+
+type PlanTaskInput = {
+  id?: string;
+  title?: string;
+  agent: string;
+  task: string;
+  role?: TakomiRole;
+  stage?: VibeLifecycleStage;
+  workflow?: TakomiWorkflowId | string;
+  model?: string;
+  fallbackModels?: string[];
+  thinking?: TakomiThinkingLevel;
+  conversationId?: string;
+  checklist?: ChecklistInput;
+  dispatchPolicy?: TakomiDispatchPolicy;
+  review?: boolean;
+};
+
+type PlanInput = {
+  source: TakomiDelegationPlan["source"];
+  sessionId?: string;
+  launchMode: TakomiLaunchMode;
+  profile: TakomiProfile;
+  tasks: PlanTaskInput[];
+};
+
+function normalizeChecklist(checklist?: ChecklistInput): TakomiDelegationPlanTask["checklist"] {
+  if (!checklist?.length) return undefined;
+  return checklist.map((item) => typeof item === "string" ? { text: item, done: false } : { text: item.text, done: item.done ?? false });
+}
+
+export function createTakomiDelegationPlan(input: PlanInput): TakomiDelegationPlan {
+  const reviewAfterImplementation = input.profile.reviewAfterImplementation ?? input.profile.review?.enabled ?? true;
+  return {
+    planId: `takomi-plan-${Date.now()}`,
+    source: input.source,
+    launchMode: input.launchMode,
+    placement: input.profile.background ? "background" : "foreground",
+    reviewAfterImplementation,
+    createdAt: new Date().toISOString(),
+    sessionId: input.sessionId,
+    tasks: input.tasks.map((task, index) => ({
+      id: task.id ?? `plan-task-${index + 1}`,
+      title: task.title ?? task.task.split(/\r?\n/).find(Boolean)?.slice(0, 80) ?? `Task ${index + 1}`,
+      agent: task.agent,
+      task: task.task,
+      role: task.role,
+      stage: task.stage,
+      workflow: task.workflow,
+      model: task.model,
+      fallbackModels: task.fallbackModels,
+      thinking: task.thinking,
+      conversationId: task.conversationId,
+      checklist: normalizeChecklist(task.checklist),
+      dispatchPolicy: task.dispatchPolicy,
+      review: task.review ?? reviewAfterImplementation,
+      status: "planned",
+    })),
+  };
+}
+
+export function renderTakomiDelegationPlan(plan: TakomiDelegationPlan): string {
+  const lines = [
+    `Takomi delegation plan ${plan.planId}`,
+    `mode=${plan.launchMode} | placement=${plan.placement} | reviewAfterImplementation=${plan.reviewAfterImplementation ? "on" : "off"}`,
+  ];
+  for (const task of plan.tasks) {
+    const checklist = task.checklist?.length ? ` | checklist=${task.checklist.filter((item) => item.done).length}/${task.checklist.length}` : "";
+    const fallback = task.fallbackModels?.length ? ` | fallbacks=${task.fallbackModels.length}` : "";
+    lines.push([
+      `${task.id}: ${task.agent}`,
+      task.model ? `model=${task.model}` : "model=default",
+      task.thinking ? `thinking=${task.thinking}` : "thinking=default",
+      task.workflow ? `workflow=${task.workflow}` : "",
+      task.review ? "review=on" : "review=off",
+      `task=${task.title}${fallback}${checklist}`,
+    ].filter(Boolean).join(" | "));
+  }
+  if (plan.launchMode === "manual") {
+    lines.push("", "Manual launch mode: review or edit agent/task/model/thinking/review settings, then rerun with confirmLaunch=true. Use previewOnly=true to keep reviewing without launch.");
+  }
+  return lines.join("\n");
+}

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

@@ -0,0 +1,26 @@
+import type { TakomiDispatchInput } from "./dispatch";
+
+export function uniqueStrings(values: Array<string | undefined>): string[] {
+  return [...new Set(values.filter((value): value is string => Boolean(value?.trim())))];
+}
+
+export function hasThinkingSuffix(model?: string): boolean {
+  return /:(off|minimal|low|medium|high|xhigh)$/i.test(model ?? "");
+}
+
+export function buildFallbackModels(input: TakomiDispatchInput): string[] {
+  return uniqueStrings([
+    input.agent.model,
+    ...(input.fallbackModels ?? []),
+    ...(input.agent.fallbackModels ?? []),
+  ]);
+}
+
+export function buildSystemPrompt(input: TakomiDispatchInput): string {
+  return [
+    input.agent.systemPrompt,
+    input.workflow ? `\nUse the ${input.workflow} workflow for this task.` : "",
+    input.skills?.length ? `\nUse these skills when relevant: ${input.skills.join(", ")}.` : "",
+    input.thinking ? `\nUse Pi thinking level '${input.thinking}' for this delegated run when the selected model supports it.` : "",
+  ].filter(Boolean).join("\n");
+}

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

@@ -0,0 +1,215 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { TakomiThinkingLevel } from "../../../src/pi-takomi-core";
+import {
+  buildTaskPrompt,
+  runModelPreflight,
+  runPiAgentJson,
+  writeTempPrompt,
+  type ChecklistInput,
+} from "../takomi-runtime/shared";
+import type {
+  TakomiSubagentRuntimeEvent,
+  TakomiSubagentRunPatch,
+} from "../takomi-runtime/subagent-types";
+import type { TakomiAgentConfig } from "./agents";
+import {
+  buildFallbackModels,
+  buildSystemPrompt,
+  hasThinkingSuffix,
+} from "./dispatch-helpers";
+
+export type TakomiDispatchInput = {
+  agent: TakomiAgentConfig;
+  task: string;
+  rootCwd: string;
+  cwd?: string;
+  workflow?: string;
+  skills?: string[];
+  model?: string;
+  fallbackModels?: string[];
+  thinking?: TakomiThinkingLevel;
+  conversationId?: string;
+  checklist?: ChecklistInput;
+  stage?: string;
+  taskLabel?: string;
+  parentTaskId?: string;
+  parentRunKey?: string;
+  boardTaskStatus?: "pending" | "in-progress" | "completed" | "blocked";
+  source: "runtime-board" | "takomi-tool";
+  rerunInstructions?: string;
+};
+
+export type TakomiDispatchResult = {
+  agent: string;
+  task: string;
+  workflow?: string;
+  model?: string;
+  warning?: string;
+  thinking?: TakomiThinkingLevel;
+  conversationId: string;
+  code: number;
+  output: string;
+  stderr: string;
+  preflight: string;
+};
+
+export type TakomiDispatchHooks = {
+  emit?: (event: TakomiSubagentRuntimeEvent) => void;
+  onPatch?: (patch: TakomiSubagentRunPatch, runKey: string) => void | Promise<void>;
+};
+
+export async function dispatchTakomiSubagent(
+  ctx: ExtensionContext,
+  input: TakomiDispatchInput,
+  signal?: AbortSignal,
+  hooks?: TakomiDispatchHooks,
+): Promise<TakomiDispatchResult> {
+  const subagentCwd = input.cwd ? path.resolve(input.rootCwd, input.cwd) : input.rootCwd;
+  const conversationId = input.conversationId || `${input.agent.name}-${Date.now()}`;
+  const runKey = conversationId;
+  const sessionDir = path.join(input.rootCwd, ".pi", "takomi", "subagents");
+  const sessionPath = path.join(sessionDir, `${conversationId}.jsonl`);
+  await mkdir(sessionDir, { recursive: true });
+
+  hooks?.emit?.({
+    type: "start",
+    runKey,
+    state: {
+      agent: input.agent.name,
+      taskLabel: input.taskLabel ?? input.task.split(/\r?\n/)[0]?.trim() ?? input.agent.name,
+      workflow: input.workflow,
+      stage: input.stage,
+      conversationId,
+      parentTaskId: input.parentTaskId,
+      parentRunKey: input.parentRunKey,
+      checklist: input.checklist,
+      boardTaskStatus: input.boardTaskStatus,
+      fallbackModels: input.fallbackModels,
+      thinking: input.thinking ?? input.agent.thinking,
+      summary: "Preparing delegated run.",
+      source: input.source,
+    },
+  });
+
+  const fallbackModels = buildFallbackModels(input);
+  const preflight = await runModelPreflight(ctx, subagentCwd, input.model, fallbackModels, signal);
+  const thinking = input.thinking ?? input.agent.thinking;
+
+  if (preflight.model) {
+    const patch = {
+      model: preflight.model,
+      fallbackModels,
+      thinking,
+      boardTaskStatus: input.boardTaskStatus,
+      checklist: input.checklist,
+      summary: `Model ready: ${preflight.model}${thinking ? ` (${thinking})` : ""}`,
+    };
+    hooks?.emit?.({ type: "update", runKey, patch });
+    await hooks?.onPatch?.(patch, runKey);
+  }
+
+  if (!preflight.model) {
+    const result = {
+      agent: input.agent.name,
+      task: input.task,
+      workflow: input.workflow,
+      model: "",
+      warning: preflight.warning,
+      thinking,
+      conversationId,
+      code: 1,
+      output: "",
+      stderr: preflight.report,
+      preflight: preflight.report,
+    };
+    hooks?.emit?.({
+      type: "block",
+      runKey,
+      patch: {
+        summary: `Subagent ${input.agent.name} blocked before launch.`,
+        boardTaskStatus: input.boardTaskStatus,
+        checklist: input.checklist,
+        fallbackModels,
+        thinking,
+        logs: [preflight.warning || "No model matched the requested run."],
+      },
+    });
+    return result;
+  }
+
+  const promptPath = await writeTempPrompt(input.agent.name, buildSystemPrompt(input));
+  const taskPrompt = buildTaskPrompt({
+    task: input.rerunInstructions?.trim() || input.task,
+    workflow: input.workflow,
+    skills: input.skills,
+    checklist: input.checklist,
+    stage: input.stage,
+  });
+  const args = ["--mode", "json", "--append-system-prompt", promptPath, "--session", sessionPath, taskPrompt];
+  args.unshift("--model", preflight.model);
+  if (thinking && !hasThinkingSuffix(preflight.model)) args.unshift("--thinking", thinking);
+  if (input.agent.tools?.length) args.unshift("--tools", input.agent.tools.join(","));
+
+  const result = await runPiAgentJson(subagentCwd, args, signal, {
+    onAssistantText: (text) => {
+      hooks?.emit?.({ type: "update", runKey, patch: { outputText: text, boardTaskStatus: input.boardTaskStatus, checklist: input.checklist } });
+    },
+    onEventText: (line) => {
+      hooks?.emit?.({ type: "appendLog", runKey, chunk: line });
+    },
+    onStderr: (chunk) => {
+      hooks?.emit?.({ type: "appendLog", runKey, chunk });
+    },
+  });
+
+  const output = result.stdout.trim();
+  const dispatchResult: TakomiDispatchResult = {
+    agent: input.agent.name,
+    task: input.task,
+    workflow: input.workflow,
+    model: preflight.model,
+    warning: preflight.warning,
+    thinking,
+    conversationId,
+    code: result.code,
+    output,
+    stderr: result.stderr.trim(),
+    preflight: preflight.report,
+  };
+
+  if (result.code !== 0) {
+    hooks?.emit?.({
+      type: "block",
+      runKey,
+      patch: {
+        model: preflight.model,
+        fallbackModels,
+        thinking,
+        boardTaskStatus: input.boardTaskStatus,
+        checklist: input.checklist,
+        summary: `Subagent ${input.agent.name} failed.`,
+        outputText: output || undefined,
+        logs: [result.stderr || result.stdout || "No output"],
+      },
+    });
+    return dispatchResult;
+  }
+
+  hooks?.emit?.({
+    type: "complete",
+    runKey,
+    patch: {
+      model: preflight.model,
+      fallbackModels,
+      thinking,
+      boardTaskStatus: input.boardTaskStatus,
+      checklist: input.checklist,
+      summary: output || `Subagent ${input.agent.name} run finished. Checklist-validated task completion is still a board action.`,
+      outputText: output || undefined,
+    },
+  });
+
+  return dispatchResult;
+}

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

@@ -0,0 +1,75 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "typebox";
+import { renderTakomiSubagentCall, renderTakomiSubagentResult } from "./native-render";
+import { executeTakomiSubagentTool } from "./tool-runner";
+
+const ChecklistItemSchema = Type.Object({
+  text: Type.String(),
+  done: Type.Optional(Type.Boolean()),
+});
+
+const ThinkingSchema = Type.Union([
+  Type.Literal("off"),
+  Type.Literal("minimal"),
+  Type.Literal("low"),
+  Type.Literal("medium"),
+  Type.Literal("high"),
+  Type.Literal("xhigh"),
+]);
+
+const TaskSchema = Type.Object({
+  agent: Type.String(),
+  task: Type.String(),
+  workflow: Type.Optional(Type.String()),
+  skills: Type.Optional(Type.Array(Type.String())),
+  model: Type.Optional(Type.String()),
+  fallbackModels: Type.Optional(Type.Array(Type.String())),
+  thinking: Type.Optional(ThinkingSchema),
+  conversationId: Type.Optional(Type.String()),
+  cwd: Type.Optional(Type.String()),
+  checklist: Type.Optional(Type.Array(Type.Union([Type.String(), ChecklistItemSchema]))),
+});
+
+const SubagentParameters = Type.Object({
+  agent: Type.Optional(Type.String({ description: "Agent name for single execution" })),
+  task: Type.Optional(Type.String({ description: "Task for single execution" })),
+  workflow: Type.Optional(Type.String({ description: "Workflow or playbook overlay for this task" })),
+  skills: Type.Optional(Type.Array(Type.String(), { description: "Extra skills to apply during the task" })),
+  model: Type.Optional(Type.String({ description: "Optional per-run model override" })),
+  fallbackModels: Type.Optional(Type.Array(Type.String(), { description: "Optional ordered model fallback list" })),
+  thinking: Type.Optional(ThinkingSchema),
+  conversationId: Type.Optional(Type.String({ description: "Persistent conversation id to resume the same subagent session" })),
+  cwd: Type.Optional(Type.String({ description: "Working directory override" })),
+  checklist: Type.Optional(Type.Array(Type.Union([Type.String(), ChecklistItemSchema]), { description: "Optional checklist for the subagent" })),
+  tasks: Type.Optional(Type.Array(TaskSchema, { description: "Parallel subagent tasks" })),
+  confirmLaunch: Type.Optional(Type.Boolean({ description: "Required to launch immediately in manual Takomi launch mode" })),
+  previewOnly: Type.Optional(Type.Boolean({ description: "Return the delegation plan without launching" })),
+  chain: Type.Optional(Type.Array(TaskSchema, { description: "Sequential chain of subagent tasks" })),
+  agentScope: Type.Optional(Type.Union([Type.Literal("user"), Type.Literal("project"), Type.Literal("both")])),
+  confirmProjectAgents: Type.Optional(Type.Boolean({ description: "Prompt before running project-local agents. Default: true." })),
+});
+
+function registerSubagentTool(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "takomi_subagent",
+    label: "Takomi",
+    description: "Run subagents with Pi-style single, parallel, or chain modes plus Takomi lifecycle metadata.",
+    promptSnippet: "Delegate lifecycle-aware Takomi work to specialist subagents. Use single, tasks, or chain; reuse conversationId for review loops.",
+    promptGuidelines: [
+      "Use this tool during orchestration when a specialist should handle a task.",
+      "Use tasks for independent parallel work and chain for dependent handoffs with {previous}.",
+      "Use model, fallbackModels, and thinking only when deliberate; otherwise let the agent/profile defaults apply.",
+      "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);
+    },
+    renderCall: renderTakomiSubagentCall,
+    renderResult: renderTakomiSubagentResult,
+  });
+}
+
+export default function takomiSubagents(pi: ExtensionAPI) {
+  registerSubagentTool(pi);
+}