takomi 2.1.44 → 2.1.45

package/.pi/extensions/takomi-context-manager/tool-renderers.ts

@@ -0,0 +1,112 @@
+import { getMarkdownTheme, keyHint } from "@earendil-works/pi-coding-agent";
+import { Container, Markdown, Text, type Component } from "@earendil-works/pi-tui";
+
+type Theme = {
+  fg(color: string, text: string): string;
+  bold(text: string): string;
+};
+
+type ToolResult = {
+  content?: Array<{ type?: string; text?: string }>;
+};
+
+const OSC_SEQUENCE = /\x1B\][\s\S]*?(?:\x07|\x1B\\|$)/g;
+const STRING_TERMINATED_SEQUENCE = /\x1B[PX^_][\s\S]*?(?:\x1B\\|$)/g;
+const CSI_SEQUENCE = /(?:\x1B\[|\x9B)[0-?]*[ -/]*[@-~]/g;
+const ESC_SEQUENCE = /\x1B(?:[()][0-2A-Z0-9]|[=>]|[ -/]*[@-~]?)/g;
+const UNSAFE_CONTROLS = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F-\x9F]/g;
+
+/**
+ * Remove terminal controls at the TUI boundary while retaining Markdown's
+ * printable syntax and line structure. Tool result content remains unchanged.
+ */
+export function sanitizePresentation(value: string): string {
+  return value
+    .replace(OSC_SEQUENCE, "")
+    .replace(STRING_TERMINATED_SEQUENCE, "")
+    .replace(CSI_SEQUENCE, "")
+    .replace(ESC_SEQUENCE, "")
+    .replace(UNSAFE_CONTROLS, "");
+}
+
+/** Read model-facing content without modifying it, then make a presentation-safe copy. */
+export function resultText(result: ToolResult): string {
+  const text = result.content?.filter((part) => part.type === "text").map((part) => part.text ?? "").join("\n") ?? "";
+  return sanitizePresentation(text);
+}
+
+export function renderToolCall(toolName: string, target: string | undefined, theme: Theme): Text {
+  const safeToolName = sanitizePresentation(toolName);
+  const safeTarget = target ? sanitizePresentation(target) : "";
+  return new Text(
+    `${theme.fg("toolTitle", theme.bold(`${safeToolName} `))}${safeTarget ? theme.fg("accent", safeTarget) : ""}`,
+    0,
+    0,
+  );
+}
+
+export function renderCompactCard(options: {
+  status: "success" | "warning" | "error" | "pending";
+  title: string;
+  summary: string;
+  metadata?: string;
+  /** Items render inline on wide terminals and stack below 80 columns. */
+  responsiveMetadata?: string[];
+}, theme: Theme): Component {
+  const status = {
+    success: ["✓", "success"],
+    warning: ["⚠", "warning"],
+    error: ["✗", "error"],
+    pending: ["…", "muted"],
+  } as const;
+  const [icon, color] = status[options.status];
+  const title = sanitizePresentation(options.title);
+  const summary = sanitizePresentation(options.summary);
+  const metadata = options.metadata ? sanitizePresentation(options.metadata) : undefined;
+  const responsiveMetadata = options.responsiveMetadata?.map(sanitizePresentation).filter(Boolean);
+  const header = `${theme.fg(color, icon)} ${theme.fg("accent", theme.bold(title))} ${theme.fg("muted", summary)}`;
+  const hint = keyHint("app.tools.expand", "view details");
+
+  if (!responsiveMetadata?.length) {
+    const detail = metadata ? `${metadata} · ${hint}` : hint;
+    return new Text([header, theme.fg("dim", detail)].join("\n"), 0, 0);
+  }
+
+  return {
+    invalidate() {},
+    render(width: number): string[] {
+      const details = width < 80
+        ? [...responsiveMetadata.map((item) => theme.fg("dim", item)), theme.fg("dim", hint)]
+        : [theme.fg("dim", `${responsiveMetadata.join(" · ")} · ${hint}`)];
+      return new Text([header, ...details].join("\n"), 0, 0).render(width);
+    },
+  };
+}
+
+export function renderExpandedMarkdown(options: {
+  status: "success" | "warning" | "error" | "pending";
+  title: string;
+  summary: string;
+  metadata?: string[];
+  markdown: string;
+}, theme: Theme): Container {
+  const status = {
+    success: ["✓", "success"],
+    warning: ["⚠", "warning"],
+    error: ["✗", "error"],
+    pending: ["…", "muted"],
+  } as const;
+  const [icon, color] = status[options.status];
+  const title = sanitizePresentation(options.title);
+  const summary = sanitizePresentation(options.summary);
+  const container = new Container();
+  container.addChild(new Text(
+    `${theme.fg(color, icon)} ${theme.fg("accent", theme.bold(title))} ${theme.fg("muted", summary)}`,
+    0,
+    0,
+  ));
+  for (const detail of options.metadata ?? []) container.addChild(new Text(theme.fg("dim", sanitizePresentation(detail)), 0, 0));
+  container.addChild(new Text(theme.fg("dim", keyHint("app.tools.expand", "collapse")), 0, 0));
+  container.addChild(new Markdown(sanitizePresentation(options.markdown), 0, 1, getMarkdownTheme()));
+  return container;
+}

package/.pi/extensions/takomi-context-manager/types.ts

@@ -2,6 +2,12 @@ export type SkillRecord = {
   name: string;
   description?: string;
   location?: string;
+  /** Explicit skill metadata, preferred over all other category sources. */
+  category?: string;
+  /** Category supplied by an installer/source registry for this exact skill path. */
+  sourceCategory?: string;
+  /** Package/source identifier used only when no explicit, registry, or path category exists. */
+  packageName?: string;
   source: "systemPromptOptions" | "xml" | "filesystem" | "tool";
 };
 

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

@@ -28,6 +28,7 @@ export type TakomiRuntimeCommandState = {
 type RegisterTakomiCommandOptions = {
   getState(): TakomiRuntimeCommandState;
   updateState(ctx: ExtensionContext, mutator: () => void, message?: string | (() => string)): Promise<void>;
+  recordUserGateAutoProvenance(authorized: boolean): void;
   resetRuntime(ctx: ExtensionCommandContext): Promise<void>;
   setStageAndWorkflow(stage: VibeLifecycleStage, options?: { preserveRole?: boolean }): void;
   createPlanSession(ctx: ExtensionCommandContext, title?: string): Promise<string>;
@@ -36,6 +37,13 @@ type RegisterTakomiCommandOptions = {
 };
 
 export function registerTakomiCommands(pi: ExtensionAPI, options: RegisterTakomiCommandOptions): void {
+  // The custom runtime widget is intentionally absent in idle/direct mode, so
+  // suppress routine notifications only while the changed state remains visible.
+  function hasVisibleRuntimeWidget(): boolean {
+    const state = options.getState();
+    return state.enabled && (state.modeSource ?? "idle") !== "idle";
+  }
+
   async function handleStage(ctx: ExtensionCommandContext, stage: VibeLifecycleStage, prompt?: string): Promise<void> {
     await options.updateState(ctx, () => {
       options.getState().enabled = true;
@@ -75,26 +83,30 @@ export function registerTakomiCommands(pi: ExtensionAPI, options: RegisterTakomi
         state.autoOrch = false;
         state.planMode = true;
         state.launchMode = "manual";
+        options.recordUserGateAutoProvenance(false);
         state.role = "review";
         state.stage = undefined;
         state.workflow = undefined;
         state.modeSource = "manual";
         state.modeReason = "/takomi mode review";
       }
-    }, () => `Takomi mode set to ${mode}`);
+    }, () => hasVisibleRuntimeWidget() ? "" : `Takomi mode set to ${mode}`);
   }
 
   async function handleGate(ctx: ExtensionCommandContext, gate?: string): Promise<void> {
-    if (gate !== "auto" && gate !== "review") {
-      ctx.ui.notify("Usage: /takomi gate <auto|review>", "warning");
+    if (gate !== "auto" && gate !== "review" && gate !== "manual") {
+      ctx.ui.notify("Usage: /takomi gate <auto|review|manual>", "warning");
       return;
     }
+    const auto = gate === "auto";
     await options.updateState(ctx, () => {
       const state = options.getState();
       state.enabled = true;
-      state.launchMode = gate === "review" ? "manual" : "auto";
-      state.autoOrch = gate === "auto";
-    }, () => `Takomi execution gate set to ${gate}`);
+      state.launchMode = auto ? "auto" : "manual";
+      state.autoOrch = auto;
+      // This dedicated entry is the only user-gate authorization signal.
+      options.recordUserGateAutoProvenance(auto);
+    }, () => hasVisibleRuntimeWidget() ? "" : `Takomi execution gate set to ${auto ? "auto" : "review"}`);
   }
 
   async function handleRouting(ctx: ExtensionCommandContext, body?: string): Promise<void> {
@@ -173,20 +185,41 @@ export function registerTakomiCommands(pi: ExtensionAPI, options: RegisterTakomi
     const policyText = scopeMatch?.[2] ?? trimmed.replace(/^set\s+/i, "");
 
     try {
-      const preview = previewTakomiRoutingPolicy(ctx.cwd, policyText, { scope });
+      const availableModels = (() => {
+        try {
+          const available = (ctx as ExtensionCommandContext & { modelRegistry?: { getAvailable?: () => Array<{ provider?: string; id?: string; name?: string }> } }).modelRegistry?.getAvailable?.() ?? [];
+          return available.map((model) => `${model.provider ? `${model.provider}/` : ""}${model.id ?? model.name ?? ""}`).filter(Boolean);
+        } catch {
+          return [];
+        }
+      })();
+      const [preview, activePolicy] = await Promise.all([
+        Promise.resolve(previewTakomiRoutingPolicy(ctx.cwd, policyText, { scope, availableModels })),
+        resolveTakomiRoutingPolicy(ctx.cwd),
+      ]);
+      const replacementWarning = activePolicy.text && activePolicy.text.trim().length > preview.policy.trim().length * 2
+        ? `WARNING: This input is much shorter than the active policy (${preview.policy.length} vs ${activePolicy.text.length} characters). It will replace the file, not merge into it. If the user referred to a full source file or prior policy, inspect and use that complete text instead.`
+        : "This input replaces the selected policy file exactly; it is not merged with the active policy.";
       const reviewPrompt = [
         "Review this Takomi routing policy extraction before it is saved.",
         "",
         "Rules:",
         "- Do not invent providers or model IDs not grounded in the policy.",
-        "- Providerless names like GPT-5.5 are routing intent unless a preferred provider/router is declared.",
-        "- Valid Takomi roles are: general, orchestrator, architect, designer, coder, reviewer.",
-        "- If the extraction is correct and safe, call takomi_apply_routing_policy with the exact policyText and scope below.",
-        "- If it is ambiguous or wrong, explain what the user should clarify and do not call the tool.",
+        "- Providerless names are valid routing intent. Require a provider only when writing an executable model override.",
+        "- Check the available Pi model registry below before asking the user whether a named model exists or what its exact ID is.",
+        "- Conditional task-shape routes do not need to be forced into role-wide defaults or agentOverrides.",
+        "- Valid role-wide Takomi overrides are: general, orchestrator, architect, designer, coder, reviewer. Other headings may still be policy concepts or execution routes.",
+        "- Preserve the user's full authored policy. If this looks like a summary/excerpt and a richer referenced source exists, inspect that source and apply the complete intended text instead of overwriting it with the excerpt.",
+        "- If the extraction is correct and safe, call takomi_apply_routing_policy with the complete intended policyText and scope below.",
+        "- Ask only for unresolved provider/account choices or genuine policy ambiguity; do not ask for facts available from the registry or files.",
         "",
         "Deterministic extraction:",
         renderRoutingPolicyPreview(preview),
         "",
+        replacementWarning,
+        "",
+        availableModels.length ? `Available Pi models:\n${availableModels.map((model) => `- ${model}`).join("\n")}` : "Available Pi models: registry unavailable; inspect it before asking the user if possible.",
+        "",
         "Original policy text:",
         "```",
         preview.policy,
@@ -217,7 +250,7 @@ export function registerTakomiCommands(pi: ExtensionAPI, options: RegisterTakomi
     if (action === "on" || action === "off") {
       await options.updateState(ctx, () => {
         options.getState().subagentsEnabled = action === "on";
-      }, `Takomi subagents ${action}`);
+      }, () => hasVisibleRuntimeWidget() ? "" : `Takomi subagents ${action}`);
       return;
     }
     if (action === "status" || !action) {

package/.pi/extensions/takomi-runtime/gate-provenance.ts

@@ -0,0 +1,24 @@
+export const USER_GATE_AUTO_PROVENANCE_ENTRY = "takomi-user-gate-auto-provenance";
+
+type SessionEntry = {
+  type?: unknown;
+  customType?: unknown;
+  data?: unknown;
+};
+
+function isAuthorizedData(value: unknown): value is { authorized: true } {
+  return typeof value === "object" && value !== null && (value as { authorized?: unknown }).authorized === true;
+}
+
+/**
+ * Reads the latest explicit user gate decision from session history.
+ * This deliberately ignores generic runtime state and profile defaults.
+ */
+export function hasUserGateAutoProvenance(entries: readonly SessionEntry[]): boolean {
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const entry = entries[index];
+    if (entry?.type !== "custom" || entry.customType !== USER_GATE_AUTO_PROVENANCE_ENTRY) continue;
+    return isAuthorizedData(entry.data);
+  }
+  return false;
+}

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

@@ -13,7 +13,6 @@ import {
   getSessionPaths,
   getNextTaskId,
   getWorkflowDefinition,
-  listWorkflowDefinitions,
   markStageExpanded,
   normalizeSessionState,
   renderMasterPlan,
@@ -50,12 +49,27 @@ import {
 } from "./shared";
 import { TakomiContextPanel, wireContextPanel } from "./context-panel";
 import { registerTakomiCommands } from "./commands";
+import { USER_GATE_AUTO_PROVENANCE_ENTRY } from "./gate-provenance";
 import {
   DEFAULT_TAKOMI_PROFILE,
   getProfileDefaults,
   loadTakomiProfile,
 } from "./profile";
 import { installTakomiRoutingPolicy, previewTakomiRoutingPolicy, renderRoutingPolicyPreview, resolveTakomiRoutingPolicy } from "./routing-policy";
+import {
+  discoverWorkflowPlaybooks,
+  showWorkflowCatalogForBoard,
+} from "./workflow-catalog";
+import {
+  renderTakomiBoardCall,
+  renderTakomiBoardResult,
+  renderTakomiModeCall,
+  renderTakomiModeResult,
+  renderTakomiRoutingCall,
+  renderTakomiRoutingResult,
+  renderTakomiWorkflowCall,
+  renderTakomiWorkflowResult,
+} from "./tool-renderers";
 
 type TakomiModeSource = "idle" | "manual" | "model" | "board";
 
@@ -399,6 +413,24 @@ function getIncompleteChecklistItems(checklist?: OrchestratorTask["checklist"]):
     .map((item) => item.text);
 }
 
+type BoardErrorSeverity = "warning" | "error";
+
+function createBoardErrorResult(
+  text: string,
+  code: string,
+  severity: BoardErrorSeverity,
+  details: Record<string, unknown> = {},
+) {
+  return {
+    content: [{ type: "text" as const, text }],
+    // Keep this semantic error independent of Pi's transport-level isError.
+    // Renderers use it to retain warning/error meaning even when Pi does not
+    // pass top-level result flags back into renderResult.
+    details: { ...details, error: { code, message: text, severity } },
+    isError: true,
+  };
+}
+
 function getCompletionGateError(task: Pick<OrchestratorTask, "id" | "title" | "checklist">): string | undefined {
   if (!task.checklist?.length) {
     return `Task ${task.id} cannot be marked completed until it has a checklist.`;
@@ -688,6 +720,10 @@ function installTakomiFooter(ctx: ExtensionContext, stateRef: { current: TakomiS
   ctx.ui.setFooter((tui, theme, footerData) => new TakomiFooterComponent(tui, theme, footerData, ctx, () => stateRef.current));
 }
 
+function hasVisibleRuntimeWidget(state: TakomiState): boolean {
+  return state.enabled && (state.modeSource ?? "idle") !== "idle";
+}
+
 async function refreshUi(
   ctx: ExtensionContext,
   state: TakomiState,
@@ -742,6 +778,12 @@ export default function takomiRuntime(pi: ExtensionAPI) {
     pi.appendEntry(STATE_ENTRY, state);
   }
 
+  // This is intentionally separate from generic runtime-state persistence.
+  // Only user slash-command handlers receive the recorder below.
+  function recordUserGateAutoProvenance(authorized: boolean): void {
+    pi.appendEntry(USER_GATE_AUTO_PROVENANCE_ENTRY, { authorized });
+  }
+
   function syncContextPanelState() {
     contextPanel.setRuntimeState({
       role: state.role,
@@ -829,6 +871,7 @@ export default function takomiRuntime(pi: ExtensionAPI) {
   registerTakomiCommands(pi, {
     getState: () => state,
     updateState,
+    recordUserGateAutoProvenance,
     setStageAndWorkflow: (stage, options) => setStageAndWorkflow(state, stage, options),
     hasGenesisArtifacts,
     subagentController,
@@ -857,12 +900,13 @@ export default function takomiRuntime(pi: ExtensionAPI) {
     },
     resetRuntime: async (ctx) => {
       await updateState(ctx, () => {
+        recordUserGateAutoProvenance(false);
         state = cloneState(DEFAULT_STATE);
         activeSubagentLabel = undefined;
         activeSubagentAgent = undefined;
         activeSubagentTask = undefined;
         activeSubagentStatus = undefined;
-      }, "Takomi runtime state reset");
+      }, () => hasVisibleRuntimeWidget(state) ? "" : "Takomi runtime state reset");
       subagentController.reset(ctx);
       contextPanel.resetSession();
       contextPanel.show(ctx);
@@ -920,7 +964,9 @@ export default function takomiRuntime(pi: ExtensionAPI) {
     syncContextPanelState();
     await refreshUi(ctx, state, footerStateRef);
     const label = state.modeSource === "idle" ? "idle" : `${state.modeSource}:${state.stage ?? state.role}`;
-    return `Takomi mode set to ${label}${state.modeReason ? ` (${state.modeReason})` : ""}.`;
+    const text = `Takomi mode set to ${label}${state.modeReason ? ` (${state.modeReason})` : ""}.`;
+    if (!hasVisibleRuntimeWidget(state)) ctx.ui.notify(text, "info");
+    return text;
   }
 
   pi.registerTool({
@@ -939,12 +985,13 @@ export default function takomiRuntime(pi: ExtensionAPI) {
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const text = await applyTakomiMode(ctx, params.mode, "model", params.reason);
-      ctx.ui.notify(text, "info");
       return {
         content: [{ type: "text", text }],
         details: { mode: params.mode, source: state.modeSource, reason: state.modeReason, role: state.role, stage: state.stage, workflow: state.workflow },
       };
     },
+    renderCall: renderTakomiModeCall,
+    renderResult: (result, options, theme) => renderTakomiModeResult(result, options, theme),
   });
 
   pi.registerTool({
@@ -963,7 +1010,15 @@ export default function takomiRuntime(pi: ExtensionAPI) {
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const scope = params.scope ?? "global";
-      const preview = previewTakomiRoutingPolicy(ctx.cwd, params.policyText, { scope });
+      const availableModels = (() => {
+        try {
+          const available = (ctx as typeof ctx & { modelRegistry?: { getAvailable?: () => Array<{ provider?: string; id?: string; name?: string }> } }).modelRegistry?.getAvailable?.() ?? [];
+          return available.map((model) => `${model.provider ? `${model.provider}/` : ""}${model.id ?? model.name ?? ""}`).filter(Boolean);
+        } catch {
+          return [];
+        }
+      })();
+      const preview = previewTakomiRoutingPolicy(ctx.cwd, params.policyText, { scope, availableModels });
       const result = await installTakomiRoutingPolicy(ctx.cwd, params.policyText, { scope });
       const scopeNote = scope === "global"
         ? "This global policy applies unless a project-local override exists."
@@ -986,6 +1041,8 @@ export default function takomiRuntime(pi: ExtensionAPI) {
         details: { result, preview, reviewNotes: params.reviewNotes },
       };
     },
+    renderCall: renderTakomiRoutingCall,
+    renderResult: (result, options, theme) => renderTakomiRoutingResult(result, options, theme),
   });
 
   pi.registerTool({
@@ -997,20 +1054,10 @@ export default function takomiRuntime(pi: ExtensionAPI) {
       workflow: Type.Optional(StringEnum(["vibe-genesis", "vibe-design", "vibe-build"] as const)),
     }),
     async execute(_toolCallId, params) {
-      if (params.workflow) {
-        const workflow = getWorkflowDefinition(params.workflow);
-        return {
-          content: [{ type: "text", text: `${workflow.title}\n\n${workflow.playbook}` }],
-          details: workflow,
-        };
-      }
-
-      const workflows = listWorkflowDefinitions();
-      return {
-        content: [{ type: "text", text: workflows.map((workflow) => `${workflow.id}: ${workflow.purpose}`).join("\n") }],
-        details: undefined,
-      };
+      return discoverWorkflowPlaybooks(params.workflow);
     },
+    renderCall: renderTakomiWorkflowCall,
+    renderResult: (result, options, theme) => renderTakomiWorkflowResult(result, options, theme),
   });
 
   pi.registerTool({
@@ -1080,16 +1127,12 @@ export default function takomiRuntime(pi: ExtensionAPI) {
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       if (params.action === "show_workflows") {
-        const workflows = listWorkflowDefinitions();
-        return {
-          content: [{ type: "text", text: workflows.map((workflow) => `${workflow.id}: ${workflow.playbook}`).join("\n\n") }],
-          details: { workflows },
-        };
+        return showWorkflowCatalogForBoard();
       }
 
       if (params.action === "show_session") {
         if (!params.sessionId) {
-          return { content: [{ type: "text", text: "sessionId is required for show_session" }], details: {}, isError: true };
+          return createBoardErrorResult("sessionId is required for show_session", "missing-session-id", "warning");
         }
         assertSafeSessionId(params.sessionId);
         const paths = getSessionPaths(ctx.cwd, params.sessionId);
@@ -1108,13 +1151,18 @@ ${stateJson}`
 
       if (params.action === "update_task") {
         if (!params.sessionId || !params.taskId) {
-          return { content: [{ type: "text", text: "sessionId and taskId are required for update_task" }], details: {}, isError: true };
+          return createBoardErrorResult("sessionId and taskId are required for update_task", "missing-task-context", "warning");
         }
         assertSafeTaskId(params.taskId);
         const { state: sessionState } = await loadSessionState(ctx.cwd, params.sessionId);
         const idx = sessionState.tasks.findIndex((task) => task.id === params.taskId);
         if (idx === -1) {
-          return { content: [{ type: "text", text: `Task ${params.taskId} not found in session ${params.sessionId}` }], details: {}, isError: true };
+          return createBoardErrorResult(
+            `Task ${params.taskId} not found in session ${params.sessionId}`,
+            "task-not-found",
+            "error",
+            { sessionId: params.sessionId, taskId: params.taskId },
+          );
         }
         const current = sessionState.tasks[idx];
         const checklist = resolveChecklistState(current.checklist, params.checklist, params.checklistUpdates);
@@ -1127,16 +1175,12 @@ ${stateJson}`
         if (params.status === "completed") {
           const completionGateError = getCompletionGateError(nextTask);
           if (completionGateError) {
-            return {
-              content: [{ type: "text", text: completionGateError }],
-              details: {
-                sessionId: params.sessionId,
-                taskId: current.id,
-                incompleteChecklistItems: getIncompleteChecklistItems(nextTask.checklist),
-                checklist: nextTask.checklist,
-              },
-              isError: true,
-            };
+            return createBoardErrorResult(completionGateError, "completion-gate", "warning", {
+              sessionId: params.sessionId,
+              taskId: current.id,
+              incompleteChecklistItems: getIncompleteChecklistItems(nextTask.checklist),
+              checklist: nextTask.checklist,
+            });
           }
         }
         sessionState.tasks[idx] = nextTask;
@@ -1174,7 +1218,11 @@ ${stateJson}`
 
       if (params.action === "expand_stage") {
         if (!params.sessionId || !params.stage || !params.tasks?.length) {
-          return { content: [{ type: "text", text: "sessionId, stage, and at least one task are required for expand_stage" }], details: {}, isError: true };
+          return createBoardErrorResult(
+            "sessionId, stage, and at least one task are required for expand_stage",
+            "invalid-expansion",
+            "warning",
+          );
         }
 
         const { state: sessionState } = await loadSessionState(ctx.cwd, params.sessionId);
@@ -1257,6 +1305,8 @@ ${stateJson}`
         details: { sessionId: nextState.sessionId, paths, tasks: nextState.tasks, lifecycle: nextState.lifecycle, mode: nextState.mode },
       };
     },
+    renderCall: renderTakomiBoardCall,
+    renderResult: (result, options, theme, context) => renderTakomiBoardResult(result, options, theme, context?.args),
   });
 
   pi.on("input", async (event) => {
@@ -1271,20 +1321,39 @@ ${stateJson}`
       state.enabled = true;
       try {
         const cwd = runtimeCtx?.cwd ?? process.cwd();
-        const preview = previewTakomiRoutingPolicy(cwd, text, { scope: "global" });
+        const availableModels = (() => {
+          try {
+            const available = (runtimeCtx as typeof runtimeCtx & { modelRegistry?: { getAvailable?: () => Array<{ provider?: string; id?: string; name?: string }> } })?.modelRegistry?.getAvailable?.() ?? [];
+            return available.map((model) => `${model.provider ? `${model.provider}/` : ""}${model.id ?? model.name ?? ""}`).filter(Boolean);
+          } catch {
+            return [];
+          }
+        })();
+        const preview = previewTakomiRoutingPolicy(cwd, text, { scope: "global", availableModels });
+        const activePolicy = await resolveTakomiRoutingPolicy(cwd);
+        const replacementWarning = activePolicy.text && activePolicy.text.trim().length > preview.policy.trim().length * 2
+          ? `WARNING: This input is much shorter than the active policy (${preview.policy.length} vs ${activePolicy.text.length} characters). It will replace the file, not merge into it. Inspect any referenced full source before applying.`
+          : "The supplied text replaces the policy file exactly; it is not merged with the current policy.";
         return { action: "transform", text: [
           "Review this Takomi routing policy extraction before it is saved.",
           "",
           "Rules:",
           "- Do not invent providers or model IDs not grounded in the policy.",
-          "- Providerless names like GPT-5.5 are routing intent unless a preferred provider/router is declared.",
-          "- Valid Takomi roles are: general, orchestrator, architect, designer, coder, reviewer.",
-          "- If the extraction is correct and safe, call takomi_apply_routing_policy with scope=global and the exact original policy text.",
-          "- If it is ambiguous or wrong, explain what the user should clarify and do not call the tool.",
+          "- Providerless names are valid routing intent. Require a provider only for executable model overrides.",
+          "- Check the available Pi model registry below before asking whether a named model exists or what its exact ID is.",
+          "- Conditional task routes need not be forced into role-wide agentOverrides.",
+          "- Valid role-wide Takomi overrides are: general, orchestrator, architect, designer, coder, reviewer. Other headings may be policy concepts or execution routes.",
+          "- Preserve the user's complete authored policy. If this is a summary/excerpt and a referenced full source exists, inspect and apply that source rather than overwriting it with the excerpt.",
+          "- If correct and safe, call takomi_apply_routing_policy with scope=global and the complete intended policy text.",
+          "- Ask only for unresolved provider/account choices or genuine ambiguity; do not ask for facts available in registry or files.",
           "",
           "Deterministic extraction:",
           renderRoutingPolicyPreview(preview),
           "",
+          replacementWarning,
+          "",
+          availableModels.length ? `Available Pi models:\n${availableModels.map((model) => `- ${model}`).join("\n")}` : "Available Pi models: registry unavailable; inspect it before asking the user if possible.",
+          "",
           "Original policy text:",
           "```",
           preview.policy,

package/.pi/extensions/takomi-runtime/routing-policy.ts

@@ -205,7 +205,7 @@ export async function resolveTakomiRoutingPolicy(cwd: string): Promise<ResolvedR
   return { source: "missing" };
 }
 
-export function previewTakomiRoutingPolicy(cwd: string, input: string, options: { scope?: RoutingPolicyInstallScope } = {}): RoutingPolicyPreviewResult {
+export function previewTakomiRoutingPolicy(cwd: string, input: string, options: { scope?: RoutingPolicyInstallScope; availableModels?: string[] } = {}): RoutingPolicyPreviewResult {
   const policy = extractQuotedPolicy(input);
   if (!policy) throw new Error("No routing policy text found. Paste the policy after /takomi routing or inside triple quotes.");
 
@@ -217,7 +217,19 @@ export function previewTakomiRoutingPolicy(cwd: string, input: string, options:
     ? path.join(cwd, PROJECT_PI_SETTINGS_RELATIVE)
     : GLOBAL_PI_SETTINGS_PATH;
   const { overrides, detected } = deriveSubagentDefaults(policy);
-  return { scope, policy, policyPath, settingsPath, detectedDefaults: detected, overrides };
+
+  // Resolve named model families from Pi's registry for review visibility. These
+  // are conditional routing intents, not role-wide defaults, so do not invent
+  // agentOverrides merely to make the extraction non-empty.
+  const availableModels = [...new Set(options.availableModels ?? [])];
+  for (const alias of ["luna", "sol", "terra"]) {
+    if (!new RegExp(`\\b${alias}\\b`, "i").test(policy)) continue;
+    const matches = availableModels.filter((model) => new RegExp(`(?:^|/)gpt[-_.]?5\\.6[-_.]?${alias}$`, "i").test(model));
+    if (matches.length === 1) detected.push(`${alias[0].toUpperCase()}${alias.slice(1)} intent resolves to ${matches[0]} (conditional route)`);
+    else if (matches.length > 1) detected.push(`${alias[0].toUpperCase()}${alias.slice(1)} intent matches available models: ${matches.join(", ")}`);
+    else detected.push(`${alias[0].toUpperCase()}${alias.slice(1)} remains a providerless conditional routing intent`);
+  }
+  return { scope, policy, policyPath, settingsPath, detectedDefaults: [...new Set(detected)], overrides };
 }
 
 export async function installTakomiRoutingPolicy(cwd: string, input: string, options: { scope?: RoutingPolicyInstallScope } = {}): Promise<RoutingPolicyInstallResult> {