takomi 2.1.26 → 2.1.27

package/.pi/agents/architect.md

@@ -2,7 +2,6 @@
 name: architect
 description: Gather requirements, design architecture, and create implementation-ready plans.
 tools: read,bash,grep,find,ls
-model: gpt-5.4
 ---
 You are the Takomi Architect.
 

package/.pi/agents/coder.md

@@ -2,7 +2,6 @@
 name: coder
 description: Implement, fix, and refactor code with verification and controlled scope.
 tools: read,bash,edit,write,grep,find,ls
-model: gpt-5.4-mini
 ---
 You are the Takomi Code Specialist.
 

package/.pi/agents/designer.md

@@ -2,7 +2,6 @@
 name: designer
 description: Translate requirements into build-ready UI, UX, visual systems, and interaction direction.
 tools: read,bash,grep,find,ls
-model: gemini-3.1-pro-preview
 ---
 You are the Takomi Design Specialist.
 

package/.pi/agents/orchestrator.md

@@ -2,7 +2,6 @@
 name: orchestrator
 description: Coordinate complex projects by decomposing, sequencing, delegating, and synthesizing specialist work.
 tools: read,bash,grep,find,ls
-model: gpt-5.4
 ---
 You are the Takomi Orchestrator.
 

package/.pi/agents/reviewer.md

@@ -2,7 +2,6 @@
 name: reviewer
 description: Review changes for correctness, risk, security, maintainability, and spec compliance.
 tools: read,bash,grep,find,ls
-model: gpt-5.4-mini
 ---
 You are the Takomi Review Specialist.
 

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

@@ -11,6 +11,7 @@ import { registerDiagnostics } from "./diagnostics-tools";
 import { installPrerequisiteGates } from "./prerequisite-gates";
 import { installModelPolicyGate } from "./model-policy-gate";
 import { detectDuplicateTakomiExtensions } from "./extension-conflicts";
+import { loadTakomiModelRoutingSnapshot, renderCompactTakomiModelRoutingSummary } from "../takomi-runtime/model-routing-defaults";
 import type { ContextManagerConfig } from "./types";
 
 export default function takomiContextManager(pi: ExtensionAPI) {
@@ -33,6 +34,8 @@ export default function takomiContextManager(pi: ExtensionAPI) {
 
     const candidates = findCandidates(event.prompt, state.skills, config);
     const rewrite = rewritePrompt(event.systemPrompt, state.skills, candidates, config);
+    const routingSummary = renderCompactTakomiModelRoutingSummary(await loadTakomiModelRoutingSnapshot(ctx.cwd));
+    const rewrittenPrompt = routingSummary ? `${rewrite.prompt}\n\n${routingSummary}` : rewrite.prompt;
     state.report = {
       ...state.report,
       timestamp: new Date().toISOString(),
@@ -43,14 +46,14 @@ export default function takomiContextManager(pi: ExtensionAPI) {
       duplicateExtensionWarnings,
       promptRewrite: {
         attempted: true,
-        changed: rewrite.changed,
+        changed: rewrite.changed || Boolean(routingSummary),
         originalLength: event.systemPrompt.length,
-        rewrittenLength: rewrite.prompt.length,
+        rewrittenLength: rewrittenPrompt.length,
         removedSections: rewrite.removedSections,
         warnings: rewrite.warnings,
       },
     };
 
-    return { systemPrompt: rewrite.prompt };
+    return { systemPrompt: rewrittenPrompt };
   });
 }

package/.pi/extensions/takomi-context-manager/model-policy-gate.ts

@@ -5,6 +5,7 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import type { ContextManagerState } from "./state";
 import { recordBlocked } from "./state";
 import { resolveTakomiRoutingPolicy } from "../takomi-runtime/routing-policy";
+import { approvedModelEquivalent, isTakomiModelApproved } from "../takomi-runtime/model-routing-defaults";
 
 type Settings = {
   takomi?: { modelRoutingPolicyFile?: string };
@@ -79,12 +80,21 @@ function isModelLike(value: string): boolean {
     || 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[] {
+  // Providerless names such as "GPT-5.5" are intent labels unless the policy
+  // declares a preferred provider/router header.
   const explicit = (text.match(/[a-z0-9-]+\/[a-z0-9._-]+/gi) ?? []).filter(isModelLike);
+  const preferredProvider = extractPreferredProvider(text);
   const inferred: string[] = [];
-  if (/gpt[- ]?5\.5/i.test(text)) inferred.push("oauth-router/gpt-5.5");
-  if (/gpt[- ]?5\.4(?!\s*mini)/i.test(text)) inferred.push("oauth-router/gpt-5.4");
-  if (/gpt[- ]?5\.4\s*mini/i.test(text)) inferred.push("oauth-router/gpt-5.4-mini");
+  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]);
 }
 
@@ -98,8 +108,8 @@ async function loadSnapshot(cwd: string): Promise<ModelPolicySnapshot> {
   return { approvedModels, preferredModels: settingsModels.length ? unique(settingsModels) : approvedModels, sourceFiles };
 }
 
-function collectRequestedModelRefs(input: unknown): Array<{ holder: Record<string, unknown>; key: string; value: string }> {
-  const refs: Array<{ holder: Record<string, unknown>; key: string; value: string }> = [];
+function collectRequestedModelRefs(input: unknown): Array<{ holder: Record<string, unknown>; key: string; value: string; index?: number }> {
+  const refs: Array<{ holder: Record<string, unknown>; key: string; value: string; index?: number }> = [];
   function visit(value: unknown): void {
     if (!value || typeof value !== "object") return;
     if (Array.isArray(value)) {
@@ -111,7 +121,9 @@ function collectRequestedModelRefs(input: unknown): Array<{ holder: Record<strin
       if (typeof record[key] === "string") refs.push({ holder: record, key, value: record[key] });
     }
     if (Array.isArray(record.fallbackModels)) {
-      record.fallbackModels = record.fallbackModels.filter((item) => typeof item === "string");
+      const fallbackModels = record.fallbackModels.filter((item): item is string => typeof item === "string");
+      record.fallbackModels = fallbackModels;
+      fallbackModels.forEach((value: string, index: number) => refs.push({ holder: record, key: "fallbackModels", value, index }));
     }
     for (const key of ["tasks", "chain"]) visit(record[key]);
   }
@@ -119,9 +131,12 @@ function collectRequestedModelRefs(input: unknown): Array<{ holder: Record<strin
   return refs;
 }
 
-function approvedEquivalent(requested: string, approved: string[]): string | undefined {
-  const requestedFamily = modelFamily(requested);
-  return approved.find((candidate) => modelFamily(candidate) === requestedFamily);
+function setModelRef(ref: { holder: Record<string, unknown>; key: string; value: string; index?: number }, value: string): void {
+  if (ref.key === "fallbackModels" && typeof ref.index === "number" && Array.isArray(ref.holder.fallbackModels)) {
+    ref.holder.fallbackModels[ref.index] = value;
+    return;
+  }
+  ref.holder[ref.key] = value;
 }
 
 function isModelFailure(text: string): boolean {
@@ -170,16 +185,16 @@ export function installModelPolicyGate(pi: ExtensionAPI, state: ContextManagerSt
     const refs = collectRequestedModelRefs(event.input);
     const corrections: string[] = [];
     for (const ref of refs) {
-      if (approved.includes(ref.value)) continue;
-      const equivalent = approvedEquivalent(ref.value, approved);
+      if (isTakomiModelApproved(ref.value, approved)) continue;
+      const equivalent = approvedModelEquivalent(ref.value, approved);
       if (equivalent) {
-        ref.holder[ref.key] = equivalent;
+        setModelRef(ref, equivalent);
         corrections.push(`${ref.value} -> ${equivalent}`);
         continue;
       }
       const recovery = await askForInvalidModelRecovery(ctx, ref.value, approved);
       if (recovery.action === "retry") {
-        ref.holder[ref.key] = recovery.model;
+        setModelRef(ref, recovery.model);
         corrections.push(`${ref.value} -> ${recovery.model} (user selected recovery)`);
         continue;
       }

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

@@ -7,7 +7,7 @@ import type {
 } from "../../../src/pi-takomi-core";
 import { commandHelp, completions, statusText, workflowPrompt } from "./command-text";
 import type { TakomiSubagentController } from "./subagent-types";
-import { installTakomiRoutingPolicy, resolveTakomiRoutingPolicy, type RoutingPolicyInstallScope } from "./routing-policy";
+import { previewTakomiRoutingPolicy, renderRoutingPolicyPreview, resolveTakomiRoutingPolicy, type RoutingPolicyInstallScope } from "./routing-policy";
 import { collectTakomiStats, renderTakomiStats } from "./takomi-stats.js";
 
 export type TakomiRuntimeCommandState = {
@@ -158,12 +158,29 @@ export function registerTakomiCommands(pi: ExtensionAPI, options: RegisterTakomi
     const policyText = scopeMatch?.[2] ?? trimmed.replace(/^set\s+/i, "");
 
     try {
-      const result = await installTakomiRoutingPolicy(ctx.cwd, policyText, { scope });
-      const detected = result.detectedDefaults.length ? `\n\nDetected defaults:\n- ${result.detectedDefaults.join("\n- ")}` : "\n\nNo model names were auto-detected; saved policy only.";
-      const overrideNote = scope === "global"
-        ? "\n\nThis will be used by every project unless that project has its own .pi/takomi/model-routing.md override."
-        : "\n\nThis project-local policy overrides the global policy for the current project.";
-      ctx.ui.notify(`Takomi routing policy updated (${scope}).\n\nPolicy: ${result.policyPath}\nSettings: ${result.settingsPath}${detected}${overrideNote}`, "info");
+      const preview = previewTakomiRoutingPolicy(ctx.cwd, policyText, { scope });
+      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.",
+        "",
+        "Deterministic extraction:",
+        renderRoutingPolicyPreview(preview),
+        "",
+        "Original policy text:",
+        "```",
+        preview.policy,
+        "```",
+        "",
+        `Tool call to apply if safe: takomi_apply_routing_policy({ scope: ${JSON.stringify(scope)}, policyText: <original policy text> })`,
+      ].join("\n");
+      ctx.ui.notify("Takomi routing extraction prepared. Sending it to the active model for review before saving.", "info");
+      pi.sendUserMessage(reviewPrompt);
     } catch (error) {
       ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
     }

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;
@@ -799,6 +799,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 +1108,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)}` };
       }
     }
 

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> {

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

@@ -12,6 +12,7 @@ import {
   type SubagentState,
 } from "./pi-subagents-internal";
 import { resolveAgentName } from "./agent-aliases";
+import { applyTakomiRoutingDefaults, loadTakomiModelRoutingSnapshotSync } from "../takomi-runtime/model-routing-defaults";
 import type { TakomiSubagentToolParams, TakomiSubagentToolTask } from "./tool-runner";
 
 type ToolUpdate = (partial: AgentToolResult<Details>) => void;
@@ -135,9 +136,18 @@ function defaultChildExtensions(): string[] {
   return candidates.filter((candidate) => fs.existsSync(candidate));
 }
 
-function withTakomiAgentDefaults(agent: AgentConfig): AgentConfig {
+function withTakomiAgentDefaults(agent: AgentConfig, cwd: string): AgentConfig {
+  const routed = applyTakomiRoutingDefaults({
+    agent: agent.name,
+    model: agent.model,
+    fallbackModels: agent.fallbackModels,
+    thinking: agent.thinking,
+  }, loadTakomiModelRoutingSnapshotSync(cwd));
   return {
     ...agent,
+    model: routed.model,
+    fallbackModels: routed.fallbackModels,
+    thinking: routed.thinking,
     systemPromptMode: agent.systemPromptMode ?? "replace",
     inheritProjectContext: agent.inheritProjectContext ?? true,
     inheritSkills: agent.inheritSkills ?? false,
@@ -147,7 +157,7 @@ function withTakomiAgentDefaults(agent: AgentConfig): AgentConfig {
 }
 
 function discoverUnifiedAgents(discoverPiAgents: any, cwd: string, scope: AgentScope): { agents: AgentConfig[] } {
-  return { agents: discoverPiAgents(cwd, scope).agents.map(withTakomiAgentDefaults) };
+  return { agents: discoverPiAgents(cwd, scope).agents.map((agent: AgentConfig) => withTakomiAgentDefaults(agent, cwd)) };
 }
 
 function agentNameSet(discoverPiAgents: any, cwd: string): Set<string> {

package/.pi/extensions/takomi-subagents/tool-runner.ts

@@ -2,6 +2,7 @@ import path from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
 import type { TakomiThinkingLevel } from "../../../src/pi-takomi-core";
 import { loadTakomiProfile } from "../takomi-runtime/profile";
+import { applyTakomiRoutingDefaults, loadTakomiModelRoutingSnapshot } from "../takomi-runtime/model-routing-defaults";
 import { resolveAgentName } from "./agent-aliases";
 import { discoverTakomiAgents, type TakomiAgentConfig, type TakomiAgentScope } from "./agents";
 import { createTakomiDelegationPlan, renderTakomiDelegationPlan } from "./delegation-plan";
@@ -202,10 +203,11 @@ export async function executeTakomiSubagentTool(
   const agents = discoverTakomiAgents(rootCwd, agentScope);
   const byName = new Map<string, TakomiAgentConfig>(agents.map((agent) => [agent.name, agent]));
   const mode = resolveMode(params);
-  const tasks = resolveTasks(params).map((task) => ({
+  const routingSnapshot = await loadTakomiModelRoutingSnapshot(rootCwd);
+  const tasks = resolveTasks(params).map((task) => applyTakomiRoutingDefaults({
     ...task,
     agent: resolveAgentName(task.agent, byName),
-  }));
+  }, routingSnapshot));
 
   if (!mode) {
     return textResult(

package/.pi/settings.json

@@ -5,41 +5,39 @@
   },
   "subagents": {
     "agentOverrides": {
-      "oracle": {
-        "model": "oauth-router/gpt-5.5",
-        "thinking": "high"
+      "general": {
+        "model": "oauth-router/gpt-5.4",
+        "thinking": "high",
+        "fallbackModels": [
+          "oauth-router/gpt-5.5:low"
+        ]
       },
-      "reviewer": {
+      "orchestrator": {
         "model": "oauth-router/gpt-5.5",
         "thinking": "high"
       },
-      "planner": {
+      "architect": {
         "model": "oauth-router/gpt-5.5",
-        "thinking": "medium"
+        "thinking": "high"
       },
-      "worker": {
+      "designer": {
         "model": "oauth-router/gpt-5.4",
         "thinking": "high",
         "fallbackModels": [
           "oauth-router/gpt-5.5:low"
         ]
       },
-      "contextBuilder": {
+      "coder": {
         "model": "oauth-router/gpt-5.4",
-        "thinking": "high"
-      },
-      "context-builder": {
-        "model": "oauth-router/gpt-5.4",
-        "thinking": "high"
-      },
-      "scout": {
-        "model": "oauth-router/gpt-5.4-mini",
-        "thinking": "high"
+        "thinking": "high",
+        "fallbackModels": [
+          "oauth-router/gpt-5.5:low"
+        ]
       },
-      "delegate": {
-        "model": "oauth-router/gpt-5.4-mini",
+      "reviewer": {
+        "model": "oauth-router/gpt-5.5",
         "thinking": "high"
       }
     }
   }
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "takomi",
-  "version": "2.1.26",
+  "version": "2.1.27",
   "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": {