takomi 2.1.44 → 2.5.1

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

@@ -1,326 +1,262 @@
-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;
-const PROJECT_TAKOMI_POLICY_ROOT_RELATIVE = path.join(".pi", "takomi");
-const MAX_POLICY_BYTES = 128 * 1024;
-
-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 info = fs.statSync(filePath);
-    if (!info.isFile() || info.size > MAX_POLICY_BYTES) return undefined;
-    const text = fs.readFileSync(filePath, "utf8").trim();
-    return text || undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-function isPathInside(root: string, candidate: string): boolean {
-  const relative = path.relative(root, candidate);
-  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
-}
-
-function resolveSafeProjectPolicyPathSync(cwd: string, configured: string): string | undefined {
-  if (!configured) return undefined;
-
-  const projectPolicyRoot = path.resolve(cwd, PROJECT_TAKOMI_POLICY_ROOT_RELATIVE);
-  const resolvedPath = path.isAbsolute(configured) ? path.resolve(configured) : path.resolve(cwd, configured);
-  if (!isPathInside(projectPolicyRoot, resolvedPath)) return undefined;
-
-  try {
-    const realCwd = fs.realpathSync(cwd);
-    const realRoot = fs.realpathSync(projectPolicyRoot);
-    const realFile = fs.realpathSync(resolvedPath);
-    if (!isPathInside(realCwd, realRoot)) return undefined;
-    if (!isPathInside(realRoot, realFile)) return undefined;
-    return realFile;
-  } catch {
-    return resolvedPath;
-  }
-}
-
-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 = resolveSafeProjectPolicyPathSync(cwd, configuredProject);
-  if (configuredProjectPath) {
-    const configuredProjectText = readPolicyTextSync(configuredProjectPath);
-    if (configuredProjectText) return { policyPath: configuredProjectPath, text: configuredProjectText };
-  }
-
-  const defaultProjectPath = resolveSafeProjectPolicyPathSync(cwd, TAKOMI_ROUTING_POLICY_RELATIVE);
-  if (defaultProjectPath && 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");
-}
+import * as fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { resolveTakomiRoutingPolicy } from "./routing-policy";
+
+export const TAKOMI_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
+
+type RoutingDefaultInput = {
+  model?: unknown;
+  thinking?: unknown;
+  fallbackModels?: unknown;
+};
+
+type RoutingSettings = {
+  takomi?: {
+    modelRoutingPolicyFile?: string;
+    routing?: {
+      defaultProvider?: string;
+      approvedModels?: string[];
+      roleDefaults?: Record<string, RoutingDefaultInput>;
+    };
+  };
+  subagents?: { agentOverrides?: Record<string, RoutingDefaultInput> };
+};
+
+export type TakomiRoutingSource = "explicit task" | "project role default" | "global role default" | "harness default";
+
+export type TakomiAgentModelDefault = {
+  agent: string;
+  model?: string;
+  thinking?: string;
+  fallbackModels?: string[];
+  source?: Exclude<TakomiRoutingSource, "explicit task" | "harness default">;
+};
+
+export type TakomiModelRoutingSnapshot = {
+  approvedModels: string[];
+  preferredModels: string[];
+  sourceFiles: string[];
+  policyFile?: string;
+  policyConflicts?: string[];
+  defaultProvider?: string;
+  agentDefaults: TakomiAgentModelDefault[];
+};
+
+const GLOBAL_SETTINGS = path.join(os.homedir(), ".pi", "agent", "settings.json");
+const CANONICAL_AGENTS = new Set(["architect", "designer", "coder", "worker", "reviewer", "orchestrator"]);
+
+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))];
+}
+
+function canonicalAgent(value: string): string | undefined {
+  const normalized = value.toLowerCase().replace(/[^a-z0-9]+/g, "");
+  const aliases: Record<string, string> = {
+    architecture: "architect",
+    design: "designer",
+    code: "coder",
+    review: "reviewer",
+    general: "worker",
+  };
+  const canonical = aliases[normalized] ?? normalized;
+  return CANONICAL_AGENTS.has(canonical) ? canonical : undefined;
+}
+
+async function readSettings(filePath: string): Promise<RoutingSettings> {
+  try { return JSON.parse(await fs.promises.readFile(filePath, "utf8")) as RoutingSettings; } catch { return {}; }
+}
+
+function readSettingsSync(filePath: string): RoutingSettings {
+  try { return JSON.parse(fs.readFileSync(filePath, "utf8")) as RoutingSettings; } catch { return {}; }
+}
+
+function cleanDefault(agent: string, input: RoutingDefaultInput, source: TakomiAgentModelDefault["source"]): TakomiAgentModelDefault {
+  return {
+    agent,
+    model: typeof input.model === "string" && input.model.trim() ? input.model.trim() : undefined,
+    thinking: typeof input.thinking === "string" && input.thinking.trim() ? input.thinking.trim() : undefined,
+    fallbackModels: Array.isArray(input.fallbackModels)
+      ? unique(input.fallbackModels.filter((item): item is string => typeof item === "string"))
+      : undefined,
+    source,
+  };
+}
+
+function extractDefaults(settings: RoutingSettings, source: TakomiAgentModelDefault["source"]): Map<string, TakomiAgentModelDefault> {
+  const result = new Map<string, TakomiAgentModelDefault>();
+  const legacy = asRecord(settings.subagents?.agentOverrides);
+  for (const [name, value] of Object.entries(legacy)) {
+    const agent = canonicalAgent(name);
+    if (agent) result.set(agent, cleanDefault(agent, asRecord(value), source));
+  }
+  const structured = asRecord(settings.takomi?.routing?.roleDefaults);
+  for (const [name, value] of Object.entries(structured)) {
+    const agent = canonicalAgent(name);
+    if (!agent) continue;
+    const previous = result.get(agent);
+    const next = cleanDefault(agent, asRecord(value), source);
+    result.set(agent, {
+      agent,
+      model: next.model ?? previous?.model,
+      thinking: next.thinking ?? previous?.thinking,
+      fallbackModels: next.fallbackModels ?? previous?.fallbackModels,
+      source,
+    });
+  }
+  return result;
+}
+
+function configuredApprovedModels(settings: RoutingSettings): { present: boolean; models: string[] } {
+  const routing = settings.takomi?.routing;
+  return {
+    present: Boolean(routing && Object.prototype.hasOwnProperty.call(routing, "approvedModels")),
+    models: Array.isArray(routing?.approvedModels) ? unique(routing.approvedModels) : [],
+  };
+}
+
+function modelsFromDefaults(defaults: Iterable<TakomiAgentModelDefault>): string[] {
+  const models: string[] = [];
+  for (const entry of defaults) {
+    if (entry.model) models.push(stripThinkingSuffix(entry.model).baseModel);
+    for (const fallback of entry.fallbackModels ?? []) models.push(stripThinkingSuffix(fallback).baseModel);
+  }
+  return unique(models);
+}
+
+export function mergeTakomiRoutingSettings(globalSettings: RoutingSettings, projectSettings: RoutingSettings, sourceFiles: string[] = []): TakomiModelRoutingSnapshot {
+  const globalDefaults = extractDefaults(globalSettings, "global role default");
+  const projectDefaults = extractDefaults(projectSettings, "project role default");
+  const mergedDefaults = new Map(globalDefaults);
+  for (const [agent, projectDefault] of projectDefaults) {
+    const base = mergedDefaults.get(agent);
+    mergedDefaults.set(agent, {
+      agent,
+      model: projectDefault.model ?? base?.model,
+      thinking: projectDefault.thinking ?? base?.thinking,
+      fallbackModels: projectDefault.fallbackModels ?? base?.fallbackModels,
+      source: "project role default",
+    });
+  }
+
+  const globalApproved = configuredApprovedModels(globalSettings);
+  const projectApproved = configuredApprovedModels(projectSettings);
+  const approvedModels = projectApproved.present
+    ? projectApproved.models
+    : globalApproved.present
+      ? globalApproved.models
+      : modelsFromDefaults(mergedDefaults.values());
+  const defaultProvider = projectSettings.takomi?.routing?.defaultProvider
+    ?? globalSettings.takomi?.routing?.defaultProvider;
+
+  return {
+    approvedModels,
+    preferredModels: approvedModels,
+    sourceFiles,
+    defaultProvider,
+    agentDefaults: [...mergedDefaults.values()],
+  };
+}
+
+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 isTakomiModelApproved(requested: string, approved: string[]): boolean {
+  const requestedBase = stripThinkingSuffix(requested).baseModel;
+  return approved.some((candidate) => stripThinkingSuffix(candidate).baseModel === requestedBase);
+}
+
+export function resolveAgentRoutingDefault(snapshot: TakomiModelRoutingSnapshot, agent: string): TakomiAgentModelDefault | undefined {
+  const canonical = canonicalAgent(agent);
+  return canonical ? snapshot.agentDefaults.find((entry) => entry.agent === canonical) : undefined;
+}
+
+function qualifyDefaultModel(model: string | undefined, defaultProvider: string | undefined): string | undefined {
+  if (!model || model.includes("/") || !defaultProvider) return model;
+  return `${defaultProvider}/${model}`;
+}
+
+export function applyTakomiRoutingDefaults<T extends { agent: string; model?: string; fallbackModels?: string[]; thinking?: string }>(
+  task: T,
+  snapshot: TakomiModelRoutingSnapshot,
+): T {
+  const defaults = resolveAgentRoutingDefault(snapshot, task.agent);
+  const explicitModel = Boolean(task.model);
+  const model = task.model ?? qualifyDefaultModel(defaults?.model, snapshot.defaultProvider);
+  const fallbackSource = task.fallbackModels !== undefined
+    ? task.fallbackModels
+    : explicitModel
+      ? []
+      : defaults?.fallbackModels ?? [];
+  const fallbackModels = unique(fallbackSource.map((item) => qualifyDefaultModel(item, snapshot.defaultProvider) ?? item));
+  return {
+    ...task,
+    ...(model ? { model } : {}),
+    ...(task.thinking ?? defaults?.thinking ? { thinking: task.thinking ?? defaults?.thinking } : {}),
+    ...(fallbackModels.length ? { fallbackModels } : { fallbackModels: undefined }),
+  };
+}
+
+function detectPolicyConflicts(text: string | undefined, snapshot: TakomiModelRoutingSnapshot): string[] {
+  if (!text) return [];
+  const conflicts: string[] = [];
+  const prohibited = [...text.matchAll(/(?:do not|never)\s+use\s+([a-z0-9-]+)/gi)].map((match) => match[1].toLowerCase());
+  for (const provider of prohibited) {
+    const configured = snapshot.approvedModels.filter((model) => stripThinkingSuffix(model).baseModel.toLowerCase().startsWith(`${provider}/`));
+    if (configured.length) conflicts.push(`Policy prohibits provider '${provider}', but executable settings approve: ${configured.join(", ")}`);
+  }
+  const preferred = text.match(/(?:preferred|default)\s+(?:provider|router)\s*:\s*([a-z0-9-]+)/i)?.[1];
+  if (preferred && snapshot.defaultProvider && preferred.toLowerCase() !== snapshot.defaultProvider.toLowerCase()) {
+    conflicts.push(`Policy names default provider '${preferred}', but executable settings use '${snapshot.defaultProvider}'.`);
+  }
+  return conflicts;
+}
+
+export async function loadTakomiModelRoutingSnapshot(cwd: string): Promise<TakomiModelRoutingSnapshot> {
+  const projectPath = path.resolve(cwd, ".pi", "settings.json");
+  const [globalSettings, projectSettings, policy] = await Promise.all([
+    readSettings(GLOBAL_SETTINGS),
+    readSettings(projectPath),
+    resolveTakomiRoutingPolicy(cwd),
+  ]);
+  const files = [GLOBAL_SETTINGS, projectPath].filter((file) => fs.existsSync(file));
+  const snapshot = mergeTakomiRoutingSettings(globalSettings, projectSettings, files);
+  snapshot.policyFile = policy.policyPath;
+  snapshot.policyConflicts = detectPolicyConflicts(policy.text, snapshot);
+  return snapshot;
+}
+
+export function loadTakomiModelRoutingSnapshotSync(cwd: string): TakomiModelRoutingSnapshot {
+  const projectPath = path.resolve(cwd, ".pi", "settings.json");
+  return mergeTakomiRoutingSettings(
+    readSettingsSync(GLOBAL_SETTINGS),
+    readSettingsSync(projectPath),
+    [GLOBAL_SETTINGS, projectPath].filter((file) => fs.existsSync(file)),
+  );
+}
+
+export function renderCompactTakomiModelRoutingSummary(snapshot: TakomiModelRoutingSnapshot): string {
+  if (!snapshot.approvedModels.length && !snapshot.agentDefaults.length) return "";
+  const defaultLines = snapshot.agentDefaults.map((entry) =>
+    `- ${entry.agent}: ${entry.model ?? "Pi default"}${entry.thinking ? ` (${entry.thinking})` : ""}${entry.fallbackModels?.length ? `; fallbacks ${entry.fallbackModels.join(", ")}` : ""} [${entry.source ?? "harness default"}]`
+  );
+  return [
+    "Active Takomi subagent routing summary:",
+    `Executable settings: ${snapshot.sourceFiles.join(", ") || "harness defaults"}`,
+    snapshot.policyFile ? `Advisory routing guidance: ${snapshot.policyFile}` : "",
+    snapshot.approvedModels.length ? `Approved exact model IDs: ${snapshot.approvedModels.join(", ")}` : "Approved exact model IDs: none configured",
+    "Provider-qualified model IDs are atomic. Takomi never substitutes a different provider by model-family matching.",
+    "Resolution: explicit task model → project role default → global role default → harness/Pi default.",
+    ...(snapshot.policyConflicts?.length ? ["ROUTING CONFIGURATION ERROR:", ...snapshot.policyConflicts.map((item) => `- ${item}`)] : []),
+    ...defaultLines,
+  ].filter(Boolean).join("\n");
+}