takomi 2.1.26 → 2.1.28

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

@@ -56,7 +56,7 @@ import {
   getProfileDefaults,
   loadTakomiProfile,
 } from "./profile";
-import { installTakomiRoutingPolicy, resolveTakomiRoutingPolicy } from "./routing-policy";
+import { installTakomiRoutingPolicy, previewTakomiRoutingPolicy, renderRoutingPolicyPreview, resolveTakomiRoutingPolicy } from "./routing-policy";
 
 type TakomiState = {
   enabled: boolean;
@@ -84,6 +84,9 @@ const STATE_ENTRY = "takomi-runtime-state";
 
 let activeProfile: TakomiProfile = DEFAULT_TAKOMI_PROFILE;
 let activeSubagentLabel: string | undefined;
+let activeSubagentAgent: string | undefined;
+let activeSubagentTask: string | undefined;
+let activeSubagentStatus: string | undefined;
 
 const ThinkingSchema = Type.Union([
   Type.Literal("off"),
@@ -665,18 +668,27 @@ export default function takomiRuntime(pi: ExtensionAPI) {
       launchMode: state.launchMode,
       planMode: state.planMode,
       activeSubagent: activeSubagentLabel,
+      activeSubagentAgent,
+      activeSubagentTask,
+      activeSubagentStatus,
     });
   }
 
   async function applySubagentRuntimeEvent(event: TakomiSubagentRuntimeEvent, ctx: ExtensionContext): Promise<void> {
     if (event.type === "start") {
       activeSubagentLabel = `${event.state.agent}: ${event.state.taskLabel}`;
+      activeSubagentAgent = event.state.agent;
+      activeSubagentTask = event.state.taskLabel;
+      activeSubagentStatus = event.state.status ?? "running";
       syncContextPanelState();
     } else if ((event.type === "update" || event.type === "complete" || event.type === "block") && event.patch) {
       const model = event.patch.model ? ` @ ${event.patch.model}` : "";
       const thinking = event.patch.thinking ? ` (${event.patch.thinking})` : "";
       const label = event.patch.summary?.split(/\r?\n/).find(Boolean);
       if (label) activeSubagentLabel = `${label}${model}${thinking}`;
+      if (event.patch.agent) activeSubagentAgent = event.patch.agent;
+      if (event.patch.taskLabel) activeSubagentTask = event.patch.taskLabel;
+      activeSubagentStatus = event.type === "complete" ? "completed" : event.type === "block" ? "blocked" : event.patch.status ?? activeSubagentStatus;
       syncContextPanelState();
     }
     switch (event.type) {
@@ -761,6 +773,9 @@ export default function takomiRuntime(pi: ExtensionAPI) {
       await updateState(ctx, () => {
         state = cloneState(DEFAULT_STATE);
         activeSubagentLabel = undefined;
+        activeSubagentAgent = undefined;
+        activeSubagentTask = undefined;
+        activeSubagentStatus = undefined;
       }, "Takomi runtime state reset");
       subagentController.reset(ctx);
       contextPanel.resetSession();
@@ -799,6 +814,47 @@ export default function takomiRuntime(pi: ExtensionAPI) {
     },
   });
 
+  pi.registerTool({
+    name: "takomi_apply_routing_policy",
+    label: "Takomi Routing",
+    description: "Apply a Takomi model-routing policy after deterministic extraction and active-model review.",
+    promptSnippet: "Save reviewed Takomi model routing policy text to the active global or project policy file.",
+    promptGuidelines: [
+      "Use takomi_apply_routing_policy only after reviewing the deterministic extraction against the original routing policy text.",
+      "Do not call takomi_apply_routing_policy if the policy is ambiguous, invents providers, or maps to non-Takomi roles.",
+    ],
+    parameters: Type.Object({
+      policyText: Type.String({ description: "Original routing policy text to save" }),
+      scope: Type.Optional(StringEnum(["global", "project"] as const)),
+      reviewNotes: Type.Optional(Type.String({ description: "Brief notes from the active-model review" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const scope = params.scope ?? "global";
+      const preview = previewTakomiRoutingPolicy(ctx.cwd, params.policyText, { scope });
+      const result = await installTakomiRoutingPolicy(ctx.cwd, params.policyText, { scope });
+      const scopeNote = scope === "global"
+        ? "This global policy applies unless a project-local override exists."
+        : "This project-local policy overrides the global policy for the current project.";
+      return {
+        content: [{
+          type: "text",
+          text: [
+            `Takomi routing policy saved (${scope}).`,
+            "",
+            `Policy: ${result.policyPath}`,
+            `Settings: ${result.settingsPath}`,
+            "",
+            renderRoutingPolicyPreview(preview),
+            params.reviewNotes ? `\nReview notes:\n${params.reviewNotes}` : "",
+            "",
+            scopeNote,
+          ].filter(Boolean).join("\n"),
+        }],
+        details: { result, preview, reviewNotes: params.reviewNotes },
+      };
+    },
+  });
+
   pi.registerTool({
     name: "takomi_workflow",
     label: "Takomi Workflow",
@@ -1067,11 +1123,28 @@ ${stateJson}`
     if (routingUpdateMatch) {
       state.enabled = true;
       try {
-        const result = await installTakomiRoutingPolicy(runtimeCtx?.cwd ?? process.cwd(), text);
-        const detected = result.detectedDefaults.length ? `\n\nDetected defaults:\n- ${result.detectedDefaults.join("\n- ")}` : "\n\nNo model names were auto-detected; saved policy only.";
-        return { action: "transform", text: `Takomi routing policy has been updated.\n\nPolicy: ${result.policyPath}\nSettings: ${result.settingsPath}${detected}\n\nAcknowledge the update briefly and explain that future Takomi turns will load this policy.` };
+        const cwd = runtimeCtx?.cwd ?? process.cwd();
+        const preview = previewTakomiRoutingPolicy(cwd, text, { scope: "global" });
+        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.",
+          "",
+          "Deterministic extraction:",
+          renderRoutingPolicyPreview(preview),
+          "",
+          "Original policy text:",
+          "```",
+          preview.policy,
+          "```",
+        ].join("\n") };
       } catch (error) {
-        return { action: "transform", text: `Takomi routing policy update failed: ${error instanceof Error ? error.message : String(error)}` };
+        return { action: "transform", text: `Takomi routing policy review failed: ${error instanceof Error ? error.message : String(error)}` };
       }
     }
 
@@ -1144,6 +1217,24 @@ ${stateJson}`
     }
 
     const routingPolicy = await resolveTakomiRoutingPolicy(runtimeCwd);
+    const optionalFeatureContext = (() => {
+      try {
+        const tools = typeof (pi as { getAllTools?: () => Array<{ name?: string }> }).getAllTools === "function"
+          ? (pi as { getAllTools: () => Array<{ name?: string }> }).getAllTools()
+          : [];
+        const toolNames = new Set(tools.map((tool) => tool.name).filter(Boolean));
+        const guidance: string[] = [];
+        if (toolNames.has("ask_user_question")) {
+          guidance.push("Takomi Interview is available: when Genesis, Design, or ambiguous planning would otherwise require guessing, use ask_user_question to ask concise structured questions before proceeding.");
+        }
+        if (toolNames.has("todo")) {
+          guidance.push("Takomi Todo is available as an optional live overlay. You may use todo for short-lived execution visibility, but takomi_board remains the durable lifecycle/task source of truth.");
+        }
+        return guidance.join("\n");
+      } catch {
+        return "";
+      }
+    })();
     const modelPreflightContext = (() => {
       try {
         const available = typeof (ctx as { modelRegistry?: { getAvailable?: () => Array<{ provider?: string; id?: string; name?: string }> } }).modelRegistry?.getAvailable === "function"
@@ -1165,6 +1256,7 @@ ${stateJson}`
       routingPolicy.text
         ? `${routingPolicy.source === "bundled" ? "Bundled" : "Project"} Takomi model routing policy is active. Apply it when choosing parent/subagent models and escalation levels:\n\n${routingPolicy.text}`
         : "No Takomi routing policy file was found. Users can install one with `/takomi routing <policy>` or by saying `Update Takomi routing logic: \"\"\"...\"\"\"`.",
+      optionalFeatureContext,
       modelPreflightContext,
       `Execution mode: ${route.executionMode}. Session recommendation: ${route.sessionRecommendation}.`,
       `Takomi execution gate: ${effectiveState.launchMode === "manual" ? "review" : "auto"}. In review gate mode, show the delegation plan before launching and return to the user after each task with results, verification guidance, and the recommended next step.`,
@@ -1199,8 +1291,10 @@ ${stateJson}`
     runtimeCtx = ctx;
     activeProfile = await loadTakomiProfile(ctx.cwd);
     activeSubagentLabel = undefined;
+    activeSubagentAgent = undefined;
+    activeSubagentTask = undefined;
+    activeSubagentStatus = undefined;
     subagentController.reset(ctx);
-    contextPanel.resetSession();
     const entries = ctx.sessionManager.getEntries();
     for (let i = entries.length - 1; i >= 0; i--) {
       const entry = entries[i] as { type: string; customType?: string; data?: TakomiState };
@@ -1220,6 +1314,7 @@ ${stateJson}`
     }
 
     syncContextPanelState();
+    contextPanel.rebuildFromSession(ctx);
     await refreshUi(ctx, state);
     contextPanel.show(ctx);
     flushPendingSubagentEvents();

package/.pi/extensions/takomi-runtime/model-routing-defaults.ts

@@ -0,0 +1,296 @@
+import * as fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  BUNDLED_TAKOMI_ROUTING_POLICY_PATH,
+  GLOBAL_PI_SETTINGS_PATH,
+  GLOBAL_TAKOMI_ROUTING_POLICY_PATH,
+  PROJECT_PI_SETTINGS_RELATIVE,
+  TAKOMI_ROUTING_POLICY_RELATIVE,
+  resolveTakomiRoutingPolicy,
+} from "./routing-policy";
+
+export const TAKOMI_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
+
+type Settings = {
+  takomi?: { modelRoutingPolicyFile?: string };
+  subagents?: { agentOverrides?: Record<string, unknown> };
+};
+
+export type TakomiAgentModelDefault = {
+  agent: string;
+  model?: string;
+  thinking?: string;
+  fallbackModels?: string[];
+};
+
+export type TakomiModelRoutingSnapshot = {
+  approvedModels: string[];
+  preferredModels: string[];
+  sourceFiles: string[];
+  agentDefaults: TakomiAgentModelDefault[];
+};
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
+function unique(values: string[]): string[] {
+  return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
+}
+
+async function readSettingsFile(filePath: string): Promise<Settings> {
+  try {
+    return JSON.parse(await fs.promises.readFile(filePath, "utf8")) as Settings;
+  } catch {
+    return {};
+  }
+}
+
+function readSettingsFileSync(filePath: string): Settings {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8")) as Settings;
+  } catch {
+    return {};
+  }
+}
+
+function mergeSettings(globalSettings: Settings, projectSettings: Settings): Settings {
+  const globalOverrides = asRecord(globalSettings.subagents?.agentOverrides);
+  const projectOverrides = asRecord(projectSettings.subagents?.agentOverrides);
+  return {
+    ...globalSettings,
+    ...projectSettings,
+    takomi: { ...(globalSettings.takomi ?? {}), ...(projectSettings.takomi ?? {}) },
+    subagents: {
+      ...(globalSettings.subagents ?? {}),
+      ...(projectSettings.subagents ?? {}),
+      agentOverrides: { ...globalOverrides, ...projectOverrides },
+    },
+  };
+}
+
+async function readSettings(cwd: string): Promise<Settings> {
+  const globalSettings = await readSettingsFile(path.join(os.homedir(), ".pi", "agent", "settings.json"));
+  const projectSettings = await readSettingsFile(path.resolve(cwd, ".pi/settings.json"));
+  return mergeSettings(globalSettings, projectSettings);
+}
+
+function readSettingsSync(cwd: string): Settings {
+  const globalSettings = readSettingsFileSync(path.join(os.homedir(), ".pi", "agent", "settings.json"));
+  const projectSettings = readSettingsFileSync(path.resolve(cwd, ".pi/settings.json"));
+  return mergeSettings(globalSettings, projectSettings);
+}
+
+function collectAgentDefaultsFromSettings(settings: Settings): TakomiAgentModelDefault[] {
+  const overrides = asRecord(settings.subagents?.agentOverrides);
+  const defaults: TakomiAgentModelDefault[] = [];
+  for (const [agent, value] of Object.entries(overrides)) {
+    const record = asRecord(value);
+    const fallbackModels = Array.isArray(record.fallbackModels)
+      ? record.fallbackModels.filter((item): item is string => typeof item === "string" && item.trim().length > 0)
+      : undefined;
+    defaults.push({
+      agent,
+      model: typeof record.model === "string" ? record.model : undefined,
+      thinking: typeof record.thinking === "string" ? record.thinking : undefined,
+      fallbackModels,
+    });
+  }
+  return defaults;
+}
+
+function collectModelsFromDefaults(defaults: TakomiAgentModelDefault[]): string[] {
+  const models: string[] = [];
+  for (const record of defaults) {
+    if (record.model) models.push(stripThinkingSuffix(record.model).baseModel);
+    if (Array.isArray(record.fallbackModels)) {
+      for (const fallback of record.fallbackModels) models.push(stripThinkingSuffix(fallback).baseModel);
+    }
+  }
+  return models;
+}
+
+function isModelLike(value: string): boolean {
+  const lower = value.toLowerCase();
+  return /(^|\/)(gpt|claude|gemini|o[0-9]|qwen|deepseek|llama|mistral|kimi|grok|sonnet|haiku|opus|codex|mini|max)/i.test(lower)
+    || lower.includes("oauth-router/")
+    || lower.includes("openai-codex/")
+    || lower.includes("lmstudio/");
+}
+
+function extractPreferredProvider(text: string): string | undefined {
+  const match = text.match(/(?:preferred|default)\s+(?:provider|router)(?:\s*\/\s*(?:provider|router))?\s*:\s*([a-z0-9-]+)/i)
+    ?? text.match(/use\s+([a-z0-9-]+)\s+as\s+(?:the\s+)?(?:provider|router)/i);
+  return match?.[1];
+}
+
+function collectModelsFromPolicy(text: string): string[] {
+  // Provider-agnostic policy text like "GPT-5.5" expresses routing intent, not
+  // a concrete provider. A preferred provider/router header intentionally binds
+  // those intent labels to executable provider-qualified IDs.
+  const explicit = (text.match(/[a-z0-9-]+\/[a-z0-9._-]+/gi) ?? []).filter(isModelLike);
+  const preferredProvider = extractPreferredProvider(text);
+  const inferred: string[] = [];
+  if (preferredProvider && /gpt[- ]?5\.5/i.test(text)) inferred.push(`${preferredProvider}/gpt-5.5`);
+  if (preferredProvider && /gpt[- ]?5\.4(?!\s*mini)/i.test(text)) inferred.push(`${preferredProvider}/gpt-5.4`);
+  if (preferredProvider && /gpt[- ]?5\.4\s*mini/i.test(text)) inferred.push(`${preferredProvider}/gpt-5.4-mini`);
+  return unique([...explicit, ...inferred].map((model) => stripThinkingSuffix(model).baseModel));
+}
+
+function readPolicyTextSync(filePath: string): string | undefined {
+  try {
+    const text = fs.readFileSync(filePath, "utf8").trim();
+    return text || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function resolvePolicySync(cwd: string): { policyPath?: string; text?: string } {
+  const projectSettings = readSettingsFileSync(path.join(cwd, PROJECT_PI_SETTINGS_RELATIVE));
+  const projectTakomi = asRecord(projectSettings.takomi);
+  const configuredProject = typeof projectTakomi.modelRoutingPolicyFile === "string"
+    ? projectTakomi.modelRoutingPolicyFile
+    : TAKOMI_ROUTING_POLICY_RELATIVE;
+  const configuredProjectPath = path.isAbsolute(configuredProject) ? configuredProject : path.join(cwd, configuredProject);
+  const configuredProjectText = readPolicyTextSync(configuredProjectPath);
+  if (configuredProjectText) return { policyPath: configuredProjectPath, text: configuredProjectText };
+
+  const defaultProjectPath = path.join(cwd, TAKOMI_ROUTING_POLICY_RELATIVE);
+  if (path.resolve(defaultProjectPath) !== path.resolve(configuredProjectPath)) {
+    const defaultProjectText = readPolicyTextSync(defaultProjectPath);
+    if (defaultProjectText) return { policyPath: defaultProjectPath, text: defaultProjectText };
+  }
+
+  const globalSettings = readSettingsFileSync(GLOBAL_PI_SETTINGS_PATH);
+  const globalTakomi = asRecord(globalSettings.takomi);
+  const configuredGlobal = typeof globalTakomi.modelRoutingPolicyFile === "string"
+    ? globalTakomi.modelRoutingPolicyFile
+    : GLOBAL_TAKOMI_ROUTING_POLICY_PATH;
+  const configuredGlobalPath = path.isAbsolute(configuredGlobal) ? configuredGlobal : path.join(os.homedir(), configuredGlobal);
+  const configuredGlobalText = readPolicyTextSync(configuredGlobalPath);
+  if (configuredGlobalText) return { policyPath: configuredGlobalPath, text: configuredGlobalText };
+
+  if (path.resolve(configuredGlobalPath) !== path.resolve(GLOBAL_TAKOMI_ROUTING_POLICY_PATH)) {
+    const globalText = readPolicyTextSync(GLOBAL_TAKOMI_ROUTING_POLICY_PATH);
+    if (globalText) return { policyPath: GLOBAL_TAKOMI_ROUTING_POLICY_PATH, text: globalText };
+  }
+
+  const bundledText = readPolicyTextSync(BUNDLED_TAKOMI_ROUTING_POLICY_PATH);
+  return bundledText ? { policyPath: BUNDLED_TAKOMI_ROUTING_POLICY_PATH, text: bundledText } : {};
+}
+
+export function stripThinkingSuffix(model: string): { baseModel: string; thinkingSuffix: string } {
+  const colonIdx = model.lastIndexOf(":");
+  if (colonIdx === -1) return { baseModel: model, thinkingSuffix: "" };
+  const suffix = model.slice(colonIdx + 1).toLowerCase();
+  if (!(TAKOMI_THINKING_LEVELS as readonly string[]).includes(suffix)) return { baseModel: model, thinkingSuffix: "" };
+  return { baseModel: model.slice(0, colonIdx), thinkingSuffix: `:${suffix}` };
+}
+
+export function modelFamily(model: string): string {
+  const baseModel = stripThinkingSuffix(model).baseModel;
+  return baseModel.split("/").at(-1)?.toLowerCase() ?? baseModel.toLowerCase();
+}
+
+export function isTakomiModelApproved(requested: string, approved: string[]): boolean {
+  const requestedBase = stripThinkingSuffix(requested).baseModel;
+  return approved.some((candidate) => stripThinkingSuffix(candidate).baseModel === requestedBase);
+}
+
+export function approvedModelEquivalent(requested: string, approved: string[]): string | undefined {
+  const { thinkingSuffix } = stripThinkingSuffix(requested);
+  const requestedFamily = modelFamily(requested);
+  const equivalent = approved.find((candidate) => modelFamily(candidate) === requestedFamily);
+  return equivalent ? `${stripThinkingSuffix(equivalent).baseModel}${thinkingSuffix}` : undefined;
+}
+
+export function normalizeModelToApproved(requested: string | undefined, approved: string[], fallback?: string): string | undefined {
+  if (!requested) return fallback;
+  if (isTakomiModelApproved(requested, approved)) return requested;
+  return approvedModelEquivalent(requested, approved) ?? fallback ?? requested;
+}
+
+function normalizedAgentKey(agent: string): string {
+  return agent.toLowerCase().replace(/[^a-z0-9]+/g, "");
+}
+
+const DEFAULT_ALIAS_KEYS: Record<string, string[]> = {
+  architect: ["architect", "planner", "oracle", "worker"],
+  orchestrator: ["orchestrator", "planner", "oracle", "worker"],
+  planner: ["planner", "oracle", "worker"],
+  coder: ["coder", "code", "worker", "delegate"],
+  code: ["code", "coder", "worker", "delegate"],
+  designer: ["designer", "design", "worker", "delegate"],
+  design: ["design", "designer", "worker", "delegate"],
+  reviewer: ["reviewer", "review", "oracle"],
+  review: ["review", "reviewer", "oracle"],
+  general: ["general", "worker"],
+};
+
+export function resolveAgentRoutingDefault(snapshot: TakomiModelRoutingSnapshot, agent: string): TakomiAgentModelDefault | undefined {
+  const normalized = normalizedAgentKey(agent);
+  const candidates = [normalized, ...(DEFAULT_ALIAS_KEYS[normalized] ?? []), "worker"].map(normalizedAgentKey);
+  return snapshot.agentDefaults.find((entry) => candidates.includes(normalizedAgentKey(entry.agent)));
+}
+
+export function applyTakomiRoutingDefaults<T extends { agent: string; model?: string; fallbackModels?: string[]; thinking?: string }>(
+  task: T,
+  snapshot: TakomiModelRoutingSnapshot,
+): T {
+  const defaults = resolveAgentRoutingDefault(snapshot, task.agent);
+  if (!snapshot.approvedModels.length && !defaults) return task;
+  const approved = snapshot.approvedModels;
+  const model = normalizeModelToApproved(task.model, approved, defaults?.model);
+  const thinking = task.thinking ?? defaults?.thinking;
+  const mergedFallbacks = unique([...(task.fallbackModels ?? []), ...(defaults?.fallbackModels ?? [])]);
+  const fallbackModels = unique(mergedFallbacks
+    .map((fallback) => normalizeModelToApproved(fallback, approved))
+    .filter((fallback): fallback is string => Boolean(fallback))
+    .filter((fallback) => !approved.length || isTakomiModelApproved(fallback, approved)));
+
+  return {
+    ...task,
+    ...(model ? { model } : {}),
+    ...(thinking ? { thinking } : {}),
+    ...(fallbackModels.length ? { fallbackModels } : {}),
+  };
+}
+
+export async function loadTakomiModelRoutingSnapshot(cwd: string): Promise<TakomiModelRoutingSnapshot> {
+  const settings = await readSettings(cwd);
+  const agentDefaults = collectAgentDefaultsFromSettings(settings);
+  const settingsModels = collectModelsFromDefaults(agentDefaults);
+  const resolvedPolicy = await resolveTakomiRoutingPolicy(cwd);
+  const sourceFiles = resolvedPolicy.policyPath ? [resolvedPolicy.policyPath] : [];
+  const policyModels = resolvedPolicy.text ? collectModelsFromPolicy(resolvedPolicy.text) : [];
+  const approvedModels = unique([...settingsModels, ...policyModels]);
+  return { approvedModels, preferredModels: settingsModels.length ? unique(settingsModels) : approvedModels, sourceFiles, agentDefaults };
+}
+
+export function loadTakomiModelRoutingSnapshotSync(cwd: string): TakomiModelRoutingSnapshot {
+  const settings = readSettingsSync(cwd);
+  const agentDefaults = collectAgentDefaultsFromSettings(settings);
+  const settingsModels = collectModelsFromDefaults(agentDefaults);
+  const resolvedPolicy = resolvePolicySync(cwd);
+  const sourceFiles = resolvedPolicy.policyPath ? [resolvedPolicy.policyPath] : [];
+  const policyModels = resolvedPolicy.text ? collectModelsFromPolicy(resolvedPolicy.text) : [];
+  const approvedModels = unique([...settingsModels, ...policyModels]);
+  return { approvedModels, preferredModels: settingsModels.length ? unique(settingsModels) : approvedModels, sourceFiles, agentDefaults };
+}
+
+export function renderCompactTakomiModelRoutingSummary(snapshot: TakomiModelRoutingSnapshot): string {
+  if (!snapshot.approvedModels.length && !snapshot.agentDefaults.length) return "";
+  const defaultLines = snapshot.agentDefaults
+    .filter((entry) => entry.model)
+    .map((entry) => `- ${entry.agent}: ${entry.model}${entry.thinking ? ` (${entry.thinking})` : ""}${entry.fallbackModels?.length ? `; fallbacks ${entry.fallbackModels.join(", ")}` : ""}`);
+  return [
+    "Active Takomi subagent routing summary:",
+    snapshot.sourceFiles.length ? `Policy source: ${snapshot.sourceFiles.join(", ")}` : "Policy source: settings/defaults",
+    snapshot.approvedModels.length ? `Approved model IDs: ${snapshot.approvedModels.join(", ")}` : "Approved model IDs: none discovered",
+    "When calling takomi_subagent, omit model to use these defaults or use only the approved provider-qualified IDs above. Do not use openai-codex/* when an oauth-router/* equivalent is approved.",
+    defaultLines.length ? "Role defaults:" : "",
+    ...defaultLines,
+  ].filter(Boolean).join("\n");
+}

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

@@ -22,6 +22,15 @@ export type RoutingPolicyInstallResult = {
   detectedDefaults: string[];
 };
 
+export type RoutingPolicyPreviewResult = {
+  scope: RoutingPolicyInstallScope;
+  policy: string;
+  policyPath: string;
+  settingsPath: string;
+  detectedDefaults: string[];
+  overrides: JsonObject;
+};
+
 export type RoutingPolicyInstallScope = "global" | "project";
 export type RoutingPolicySource = "project" | "global" | "bundled" | "missing";
 
@@ -64,6 +73,25 @@ function normalizeForSettings(filePath: string): string {
   return filePath.replaceAll(path.sep, "/");
 }
 
+function extractPreferredProvider(policy: string): string | undefined {
+  const match = policy.match(/(?:preferred|default)\s+(?:provider|router)(?:\s*\/\s*(?:provider|router))?\s*:\s*([a-z0-9-]+)/i)
+    ?? policy.match(/use\s+([a-z0-9-]+)\s+as\s+(?:the\s+)?(?:provider|router)/i);
+  return match?.[1];
+}
+
+function findExplicitProviderModel(policy: string, family: RegExp): string | undefined {
+  const refs = policy.match(/[a-z0-9-]+\/[a-z0-9._-]+/gi) ?? [];
+  return refs.find((ref) => family.test(ref));
+}
+
+function providerModel(preferredProvider: string | undefined, model: string): string | undefined {
+  return preferredProvider ? `${preferredProvider}/${model}` : undefined;
+}
+
+function withOptionalModel(model: string | undefined, thinking: string, extra: JsonObject = {}): JsonObject {
+  return model ? { model, thinking, ...extra } : { thinking, ...extra };
+}
+
 function deriveSubagentDefaults(policy: string): { overrides: JsonObject; detected: string[] } {
   const lower = policy.toLowerCase();
   const has55 = /gpt[- ]?5\.5/.test(lower);
@@ -71,28 +99,29 @@ function deriveSubagentDefaults(policy: string): { overrides: JsonObject; detect
   const hasMini = /gpt[- ]?5\.4\s*mini/.test(lower);
   if (!has55 && !has54 && !hasMini) return { overrides: {}, detected: [] };
 
-  const model55 = "oauth-router/gpt-5.5";
-  const model54 = "oauth-router/gpt-5.4";
-  const modelMini = "oauth-router/gpt-5.4-mini";
+  // Keep generated settings provider-agnostic unless the policy explicitly
+  // declares provider-qualified models or a preferred provider/router header.
+  const preferredProvider = extractPreferredProvider(policy);
+  const model55 = findExplicitProviderModel(policy, /gpt[-_.]?5\.5/i) ?? providerModel(preferredProvider, "gpt-5.5");
+  const model54 = findExplicitProviderModel(policy, /gpt[-_.]?5\.4(?![-_.]?mini)/i) ?? providerModel(preferredProvider, "gpt-5.4");
+  const modelMini = findExplicitProviderModel(policy, /gpt[-_.]?5\.4[-_.]?mini/i) ?? providerModel(preferredProvider, "gpt-5.4-mini");
   const overrides: JsonObject = {};
   const detected: string[] = [];
 
   if (has55) {
-    overrides.oracle = { model: model55, thinking: "high" };
-    overrides.reviewer = { model: model55, thinking: "high" };
-    overrides.planner = { model: model55, thinking: "medium" };
-    detected.push("oracle/reviewer → GPT-5.5 high", "planner → GPT-5.5 medium");
+    overrides.orchestrator = withOptionalModel(model55, "high");
+    overrides.architect = withOptionalModel(model55, "high");
+    overrides.reviewer = withOptionalModel(model55, "high");
+    detected.push(model55 ? `orchestrator/architect/reviewer → ${model55} high` : "orchestrator/architect/reviewer → GPT-5.5 high intent");
   }
   if (has54) {
-    overrides.worker = { model: model54, thinking: "high", fallbackModels: has55 ? [`${model55}:low`] : undefined };
-    overrides.contextBuilder = { model: model54, thinking: "high" };
-    overrides["context-builder"] = { model: model54, thinking: "high" };
-    detected.push("worker/context-builder → GPT-5.4 high");
+    overrides.general = withOptionalModel(model54, "high", model55 ? { fallbackModels: [`${model55}:low`] } : {});
+    overrides.coder = withOptionalModel(model54, "high", model55 ? { fallbackModels: [`${model55}:low`] } : {});
+    overrides.designer = withOptionalModel(model54, "high", model55 ? { fallbackModels: [`${model55}:low`] } : {});
+    detected.push(model54 ? `general/coder/designer → ${model54} high` : "general/coder/designer → GPT-5.4 high intent");
   }
   if (hasMini) {
-    overrides.scout = { model: modelMini, thinking: "high" };
-    overrides.delegate = { model: modelMini, thinking: "high" };
-    detected.push("scout/delegate → GPT-5.4 Mini high");
+    detected.push(modelMini ? `GPT-5.4 Mini available for explicit small-task overrides: ${modelMini}` : "GPT-5.4 Mini available as small-task intent only");
   }
   return { overrides, detected };
 }
@@ -148,7 +177,7 @@ export async function resolveTakomiRoutingPolicy(cwd: string): Promise<ResolvedR
   return { source: "missing" };
 }
 
-export async function installTakomiRoutingPolicy(cwd: string, input: string, options: { scope?: RoutingPolicyInstallScope } = {}): Promise<RoutingPolicyInstallResult> {
+export function previewTakomiRoutingPolicy(cwd: string, input: string, options: { scope?: RoutingPolicyInstallScope } = {}): 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.");
 
@@ -159,6 +188,13 @@ export async function installTakomiRoutingPolicy(cwd: string, input: string, opt
   const settingsPath = scope === "project"
     ? path.join(cwd, PROJECT_PI_SETTINGS_RELATIVE)
     : GLOBAL_PI_SETTINGS_PATH;
+  const { overrides, detected } = deriveSubagentDefaults(policy);
+  return { scope, policy, policyPath, settingsPath, detectedDefaults: detected, overrides };
+}
+
+export async function installTakomiRoutingPolicy(cwd: string, input: string, options: { scope?: RoutingPolicyInstallScope } = {}): Promise<RoutingPolicyInstallResult> {
+  const preview = previewTakomiRoutingPolicy(cwd, input, options);
+  const { scope, policy, policyPath, settingsPath, overrides, detectedDefaults } = preview;
   await mkdir(path.dirname(policyPath), { recursive: true });
   await mkdir(path.dirname(settingsPath), { recursive: true });
   await writeFile(policyPath, `# Takomi Model Routing Policy\n\n${policy}\n`, "utf8");
@@ -170,7 +206,6 @@ export async function installTakomiRoutingPolicy(cwd: string, input: string, opt
     : normalizeForSettings(GLOBAL_TAKOMI_ROUTING_POLICY_PATH);
   settings.takomi = takomi;
 
-  const { overrides, detected } = deriveSubagentDefaults(policy);
   if (Object.keys(overrides).length > 0) {
     const subagents = asObject(settings.subagents);
     const existingOverrides = asObject(subagents.agentOverrides);
@@ -179,7 +214,22 @@ export async function installTakomiRoutingPolicy(cwd: string, input: string, opt
   }
 
   await writeFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
-  return { policyPath, settingsPath, settingsUpdated: true, detectedDefaults: detected };
+  return { policyPath, settingsPath, settingsUpdated: true, detectedDefaults };
+}
+
+export function renderRoutingPolicyPreview(preview: RoutingPolicyPreviewResult): string {
+  const overrideLines = Object.entries(preview.overrides).map(([role, value]) => `- ${role}: ${JSON.stringify(value)}`);
+  return [
+    `Scope: ${preview.scope}`,
+    `Policy path: ${preview.policyPath}`,
+    `Settings path: ${preview.settingsPath}`,
+    "",
+    preview.detectedDefaults.length ? "Detected routing defaults:" : "Detected routing defaults: none",
+    ...preview.detectedDefaults.map((item) => `- ${item}`),
+    "",
+    overrideLines.length ? "Settings overrides to write:" : "Settings overrides to write: none",
+    ...overrideLines,
+  ].join("\n");
 }
 
 export async function loadTakomiRoutingPolicy(cwd: string): Promise<string | undefined> {