takomi 2.1.45 → 2.5.1

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

@@ -4,7 +4,7 @@ import path from "node:path";
 import type {
   TakomiDispatchDefaults,
   TakomiProfile,
-  TakomiRole,
+  TakomiPersona,
   VibeLifecycleStage,
 } from "../../../src/pi-takomi-core";
 
@@ -18,14 +18,15 @@ export const DEFAULT_TAKOMI_PROFILE: TakomiProfile = {
   roles: {
     orchestrator: { agent: "orchestrator", dispatchPolicy: "subagent" },
     architect: { agent: "architect", dispatchPolicy: "subagent" },
-    design: { agent: "designer", dispatchPolicy: "subagent" },
-    code: { agent: "coder", dispatchPolicy: "subagent" },
-    review: { agent: "reviewer", dispatchPolicy: "review-first" },
+    designer: { agent: "designer", dispatchPolicy: "subagent" },
+    coder: { agent: "coder", dispatchPolicy: "subagent" },
+    worker: { agent: "worker", dispatchPolicy: "subagent" },
+    reviewer: { agent: "reviewer", dispatchPolicy: "review-first" },
   },
   stages: {
     genesis: { agent: "architect", dispatchPolicy: "subagent" },
     design: { agent: "designer", dispatchPolicy: "subagent" },
-    build: { agent: "orchestrator", dispatchPolicy: "subagent" },
+    build: { agent: "coder", dispatchPolicy: "subagent" },
   },
   review: {
     enabled: true,
@@ -57,7 +58,7 @@ function mergeDefaults(
 function mergeProfile(base: TakomiProfile, next?: Partial<TakomiProfile>): TakomiProfile {
   if (!next) return base;
   const roles = { ...(base.roles ?? {}) };
-  for (const [role, defaults] of Object.entries(next.roles ?? {}) as Array<[TakomiRole, TakomiDispatchDefaults]>) {
+  for (const [role, defaults] of Object.entries(next.roles ?? {}) as Array<[TakomiPersona, TakomiDispatchDefaults]>) {
     roles[role] = mergeDefaults(roles[role], defaults);
   }
 
@@ -99,12 +100,12 @@ export async function loadTakomiProfile(cwd: string): Promise<TakomiProfile> {
   const userProfilePath = path.join(os.homedir(), ".pi", "agent", "takomi", "profile.json");
   const projectProfile = await readProfileFile(projectProfilePath);
   const userProfile = await readProfileFile(userProfilePath);
-  return mergeProfile(mergeProfile(DEFAULT_TAKOMI_PROFILE, projectProfile), userProfile);
+  return mergeProfile(mergeProfile(DEFAULT_TAKOMI_PROFILE, userProfile), projectProfile);
 }
 
 export function getProfileDefaults(
   profile: TakomiProfile,
-  role: TakomiRole,
+  role: TakomiPersona,
   stage?: VibeLifecycleStage,
 ): TakomiDispatchDefaults {
   return {

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

@@ -4,7 +4,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 export const TAKOMI_ROUTING_POLICY_RELATIVE = path.join(".pi", "takomi", "model-routing.md");
-export const GLOBAL_TAKOMI_ROUTING_POLICY_PATH = path.join(os.homedir(), ".pi", "takomi", "model-routing.md");
+export const GLOBAL_TAKOMI_ROUTING_POLICY_PATH = path.join(os.homedir(), ".pi", "agent", "takomi", "model-routing.md");
 export const GLOBAL_PI_SETTINGS_PATH = path.join(os.homedir(), ".pi", "agent", "settings.json");
 export const PROJECT_PI_SETTINGS_RELATIVE = path.join(".pi", "settings.json");
 export const BUNDLED_TAKOMI_ROUTING_POLICY_PATH = path.resolve(
@@ -99,59 +99,6 @@ 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);
-  const has54 = /gpt[- ]?5\.4(?!\s*mini)/.test(lower);
-  const hasMini = /gpt[- ]?5\.4\s*mini/.test(lower);
-  if (!has55 && !has54 && !hasMini) return { overrides: {}, detected: [] };
-
-  // 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.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.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) {
-    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 };
-}
-
 export async function resolveTakomiRoutingPolicy(cwd: string): Promise<ResolvedRoutingPolicy> {
   const projectSettingsPath = path.join(cwd, PROJECT_PI_SETTINGS_RELATIVE);
   const projectSettings = await readJsonObject(projectSettingsPath);
@@ -216,9 +163,11 @@ export function previewTakomiRoutingPolicy(cwd: string, input: string, options:
   const settingsPath = scope === "project"
     ? path.join(cwd, PROJECT_PI_SETTINGS_RELATIVE)
     : GLOBAL_PI_SETTINGS_PATH;
-  const { overrides, detected } = deriveSubagentDefaults(policy);
+  const overrides: JsonObject = {};
+  const detected: string[] = [];
 
-  // Resolve named model families from Pi's registry for review visibility. These
+  // Markdown is advisory model-facing guidance. It is never parsed into executable defaults.
+  // Resolve named model families from Pi's registry only for preview visibility.
   // are conditional routing intents, not role-wide defaults, so do not invent
   // agentOverrides merely to make the extraction non-empty.
   const availableModels = [...new Set(options.availableModels ?? [])];
@@ -246,13 +195,6 @@ export async function installTakomiRoutingPolicy(cwd: string, input: string, opt
     : normalizeForSettings(GLOBAL_TAKOMI_ROUTING_POLICY_PATH);
   settings.takomi = takomi;
 
-  if (Object.keys(overrides).length > 0) {
-    const subagents = asObject(settings.subagents);
-    const existingOverrides = asObject(subagents.agentOverrides);
-    subagents.agentOverrides = { ...existingOverrides, ...overrides };
-    settings.subagents = subagents;
-  }
-
   await writeFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
   return { policyPath, settingsPath, settingsUpdated: true, detectedDefaults };
 }
@@ -264,14 +206,91 @@ export function renderRoutingPolicyPreview(preview: RoutingPolicyPreviewResult):
     `Policy path: ${preview.policyPath}`,
     `Settings path: ${preview.settingsPath}`,
     "",
-    preview.detectedDefaults.length ? "Detected routing defaults:" : "Detected routing defaults: none",
+    preview.detectedDefaults.length ? "Advisory model concepts recognized:" : "Advisory model concepts recognized: none",
     ...preview.detectedDefaults.map((item) => `- ${item}`),
     "",
-    overrideLines.length ? "Settings overrides to write:" : "Settings overrides to write: none",
+    overrideLines.length ? "Executable settings changes:" : "Executable settings changes: none (Markdown is advisory only)",
     ...overrideLines,
   ].join("\n");
 }
 
+export type TakomiRoutingConfigUpdate = {
+  defaultProvider?: string;
+  approvedModels?: string[];
+  roleDefaults?: Record<string, { model?: string; thinking?: string; fallbackModels?: string[] }>;
+};
+
+export type TakomiRoutingConfigPreview = {
+  scope: RoutingPolicyInstallScope;
+  settingsPath: string;
+  before: JsonObject;
+  after: JsonObject;
+};
+
+const CANONICAL_ROUTING_ROLES = new Set(["architect", "designer", "coder", "worker", "reviewer", "orchestrator"]);
+
+function validateRoutingConfig(update: TakomiRoutingConfigUpdate, availableModels: string[] = []): void {
+  const allConfigured = [
+    ...(update.approvedModels ?? []),
+    ...Object.values(update.roleDefaults ?? {}).flatMap((entry) => [entry.model, ...(entry.fallbackModels ?? [])]).filter((item): item is string => Boolean(item)),
+  ];
+  for (const role of Object.keys(update.roleDefaults ?? {})) {
+    if (!CANONICAL_ROUTING_ROLES.has(role)) throw new Error(`Unknown Takomi persona '${role}'. Use architect, designer, coder, worker, reviewer, or orchestrator.`);
+  }
+  for (const model of allConfigured) {
+    const base = model.replace(/:(?:off|minimal|low|medium|high|xhigh)$/i, "");
+    if (!base.includes("/")) throw new Error(`Model '${model}' must be provider-qualified.`);
+    if (availableModels.length && !availableModels.includes(base)) throw new Error(`Model '${base}' is not enabled in Pi's available model registry.`);
+  }
+}
+
+export async function previewTakomiRoutingConfig(
+  cwd: string,
+  scope: RoutingPolicyInstallScope,
+  update: TakomiRoutingConfigUpdate,
+  availableModels: string[] = [],
+): Promise<TakomiRoutingConfigPreview> {
+  validateRoutingConfig(update, availableModels);
+  const settingsPath = scope === "project" ? path.join(cwd, PROJECT_PI_SETTINGS_RELATIVE) : GLOBAL_PI_SETTINGS_PATH;
+  const settings = await readJsonObject(settingsPath);
+  const takomi = asObject(settings.takomi);
+  const before = asObject(takomi.routing);
+  const existingRoles = asObject(before.roleDefaults);
+  const nextRoles = { ...existingRoles };
+  for (const [role, value] of Object.entries(update.roleDefaults ?? {})) {
+    nextRoles[role] = { ...asObject(existingRoles[role]), ...value };
+  }
+  const after: JsonObject = {
+    ...before,
+    ...(update.defaultProvider !== undefined ? { defaultProvider: update.defaultProvider } : {}),
+    ...(update.approvedModels !== undefined ? { approvedModels: [...new Set(update.approvedModels)] } : {}),
+    ...(update.roleDefaults !== undefined ? { roleDefaults: nextRoles } : {}),
+  };
+  return { scope, settingsPath, before, after };
+}
+
+export async function installTakomiRoutingConfig(preview: TakomiRoutingConfigPreview): Promise<void> {
+  const settings = await readJsonObject(preview.settingsPath);
+  const takomi = asObject(settings.takomi);
+  takomi.routing = preview.after;
+  settings.takomi = takomi;
+  await mkdir(path.dirname(preview.settingsPath), { recursive: true });
+  await writeFile(preview.settingsPath, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+}
+
+export function renderTakomiRoutingConfigPreview(preview: TakomiRoutingConfigPreview): string {
+  return [
+    `Scope: ${preview.scope}`,
+    `Settings: ${preview.settingsPath}`,
+    "",
+    "Before:",
+    JSON.stringify(preview.before, null, 2),
+    "",
+    "After:",
+    JSON.stringify(preview.after, null, 2),
+  ].join("\n");
+}
+
 export async function loadTakomiRoutingPolicy(cwd: string): Promise<string | undefined> {
   return (await resolveTakomiRoutingPolicy(cwd)).text;
 }

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

@@ -443,38 +443,15 @@ function modelCandidates(requested?: string, fallback?: string | string[]): stri
   return [requested, ...fallbackList].filter(Boolean) as string[];
 }
 
-export async function resolvePreferredModel(ctx: ExtensionContext, requested?: string, fallback?: string | string[]): Promise<{ model?: string; warning?: string }> {
-  const candidates = modelCandidates(requested, fallback);
-  if (candidates.length === 0) return {};
+export async function resolvePreferredModel(ctx: ExtensionContext, requested?: string, _fallback?: string | string[]): Promise<{ model?: string; warning?: string }> {
+  if (!requested) return {};
   const keys = await getAvailableModelKeys(ctx);
-  const exact = candidates.find((candidate) => keys.includes(candidate));
+  const exact = keys.find((key) => key === requested) ?? keys.find((key) => key.toLowerCase() === requested.toLowerCase());
   if (exact) return { model: exact };
-
-  const loweredKeys = keys.map((key) => key.toLowerCase());
-  for (const candidate of candidates) {
-    const idx = loweredKeys.findIndex((key) => key === candidate.toLowerCase());
-    if (idx >= 0) return { model: keys[idx] };
-  }
-
-  for (const candidate of candidates) {
-    const idx = loweredKeys.findIndex((key) => key.includes(candidate.toLowerCase()) || candidate.toLowerCase().includes(key));
-    if (idx >= 0) {
-      return {
-        model: keys[idx],
-        warning: `Requested model '${candidate}' was unavailable; using '${keys[idx]}' instead.`,
-      };
-    }
-  }
-
-  const firstAvailable = keys.find((key) => key.includes("/"));
-  if (firstAvailable) {
-    return {
-      model: firstAvailable,
-      warning: `Requested models '${candidates.join("', '")}' were unavailable; using '${firstAvailable}' instead.`,
-    };
-  }
-
-  return { warning: `No available signed-in model matched '${candidates.join("', '")}'.` };
+  return {
+    model: requested,
+    warning: `Requested model '${requested}' is not currently enabled in Pi's model registry. The exact provider-qualified ID was preserved; no equivalent provider was substituted.`,
+  };
 }
 
 export async function listModelsViaPi(cwd: string, signal?: AbortSignal): Promise<{ ok: boolean; output: string }> {

package/.pi/extensions/takomi-runtime/tool-renderers.ts

@@ -47,7 +47,7 @@ type BoardDetails = {
 };
 
 type BoardArgs = {
-  action?: "init_session" | "expand_stage" | "show_workflows" | "show_session" | "update_task";
+  action?: "init_session" | "expand_stage" | "show_workflows" | "show_session" | "update_task" | "replace_master_plan";
   sessionId?: string;
   taskId?: string;
   stage?: string;

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

@@ -5,6 +5,9 @@ import type { TakomiThinkingLevel } from "../../../src/pi-takomi-core";
 
 export type TakomiAgentScope = "user" | "project" | "both";
 
+export const TAKOMI_PUBLIC_AGENT_NAMES = ["architect", "designer", "coder", "worker", "reviewer", "orchestrator"] as const;
+const TAKOMI_PUBLIC_AGENT_SET = new Set<string>(TAKOMI_PUBLIC_AGENT_NAMES);
+
 export type TakomiAgentConfig = {
   name: string;
   description: string;
@@ -53,6 +56,8 @@ function loadAgentsFromDirectory(agentsDir: string, source: "user" | "project"):
     const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
     if (!frontmatter.name || !frontmatter.description) continue;
 
+    if (!TAKOMI_PUBLIC_AGENT_SET.has(frontmatter.name)) continue;
+
     agents.push({
       name: frontmatter.name,
       description: frontmatter.description,

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

@@ -45,6 +45,7 @@ const TaskSchema = Type.Object({
   conversationId: Type.Optional(Type.String()),
   cwd: Type.Optional(Type.String()),
   checklist: Type.Optional(Type.Array(Type.Union([Type.String(), ChecklistItemSchema]))),
+  requiredCapabilities: Type.Optional(Type.Array(Type.String(), { description: "Capabilities required by the task, such as write-docs or write-code" })),
   acceptance: Type.Optional(AcceptanceSchema),
 });
 
@@ -75,6 +76,7 @@ const SubagentParameters = Type.Object({
   conversationId: Type.Optional(Type.String({ description: "Persistent conversation id to resume the same subagent session" })),
   cwd: Type.Optional(Type.String({ description: "Working directory override" })),
   checklist: Type.Optional(Type.Array(Type.Union([Type.String(), ChecklistItemSchema]), { description: "Optional checklist for the subagent" })),
+  requiredCapabilities: Type.Optional(Type.Array(Type.String(), { description: "Capabilities required by the task, such as write-docs or write-code" })),
   acceptance: Type.Optional(AcceptanceSchema),
   tasks: Type.Optional(Type.Array(TaskSchema, { description: "Parallel subagent tasks" })),
   confirmLaunch: Type.Optional(Type.Boolean({ description: "Required to launch immediately in manual Takomi launch mode" })),
@@ -107,6 +109,8 @@ function registerSubagentTool(pi: ExtensionAPI): void {
       "Set context=fork only when inherited parent-session history is needed; otherwise prefer fresh or the agent default.",
       "Set async=true for long-running work when the parent can continue safely; keep active worktree writes single-threaded unless worktree isolation is enabled.",
       "Set clarify=true when the user asks to preview/edit a subagent run in the native Pi TUI before launch.",
+      "Use only Takomi's canonical personas: architect, designer, coder, worker, reviewer, and orchestrator.",
+      "Set requiredCapabilities for artifact-producing tasks; the runtime blocks inspection-only personas from write-required work.",
       "Use model, fallbackModels, and thinking only when deliberate; otherwise let the agent/profile defaults apply.",
       "If review sends work back to the same agent, reuse the same conversationId for continuity.",
       "If a launch is blocked, cancelled, paused, or review-gated, do not retry automatically; wait for the user's next prompt."

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

@@ -15,6 +15,7 @@ import { resolveAgentName } from "./agent-aliases";
 import { applyTakomiRoutingDefaults, loadTakomiModelRoutingSnapshotSync } from "../takomi-runtime/model-routing-defaults";
 import type { TakomiSubagentToolParams, TakomiSubagentToolTask } from "./tool-runner";
 import { ensureTakomiAsyncLifecycle, getTakomiAsyncLifecycleSnapshot } from "./async-lifecycle";
+import { TAKOMI_PUBLIC_AGENT_NAMES } from "./agents";
 
 type ToolUpdate = (partial: AgentToolResult<Details>) => void;
 
@@ -159,7 +160,12 @@ function withTakomiAgentDefaults(agent: AgentConfig, cwd: string): AgentConfig {
 }
 
 function discoverUnifiedAgents(discoverPiAgents: any, cwd: string, scope: AgentScope): { agents: AgentConfig[] } {
-  return { agents: discoverPiAgents(cwd, scope).agents.map((agent: AgentConfig) => withTakomiAgentDefaults(agent, cwd)) };
+  const publicNames = new Set<string>(TAKOMI_PUBLIC_AGENT_NAMES);
+  return {
+    agents: discoverPiAgents(cwd, scope).agents
+      .filter((agent: AgentConfig) => publicNames.has(agent.name))
+      .map((agent: AgentConfig) => withTakomiAgentDefaults(agent, cwd)),
+  };
 }
 
 function agentNameSet(discoverPiAgents: any, cwd: string): Set<string> {

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

@@ -4,7 +4,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import type { TakomiLaunchMode, TakomiThinkingLevel } from "../../../src/pi-takomi-core";
 import { loadTakomiProfile } from "../takomi-runtime/profile";
 import { hasUserGateAutoProvenance } from "../takomi-runtime/gate-provenance";
-import { applyTakomiRoutingDefaults, loadTakomiModelRoutingSnapshot } from "../takomi-runtime/model-routing-defaults";
+import { applyTakomiRoutingDefaults, isTakomiModelApproved, 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";
@@ -26,6 +26,7 @@ export type TakomiSubagentToolTask = {
   conversationId?: string;
   cwd?: string;
   checklist?: ChecklistItem[];
+  requiredCapabilities?: string[];
   acceptance?: TakomiAcceptanceInput;
 };
 
@@ -92,6 +93,19 @@ function hasProjectAgents(tasks: Array<{ agent: string }>, agents: Map<string, T
   return tasks.some((task) => agents.get(task.agent)?.source === "project");
 }
 
+function taskRequiresWrite(task: TakomiSubagentToolTask): boolean {
+  if (task.requiredCapabilities?.some((capability) => /^(write|edit|write-docs|write-code)$/i.test(capability))) return true;
+  return /\b(?:create|write|author|edit|modify|update|implement|fix)\b[\s\S]{0,100}\b(?:file|files|markdown|document|documents|artifact|artifacts|code|configuration)\b/i.test(task.task);
+}
+
+function capabilityMismatch(task: TakomiSubagentToolTask, agent: TakomiAgentConfig | undefined): string | undefined {
+  if (!agent) return undefined;
+  if (taskRequiresWrite(task) && !agent.tools?.some((tool) => tool === "write" || tool === "edit")) {
+    return `Task assigned to '${task.agent}' requires file writing, but that persona is inspection-only. Choose architect or designer for their authored Markdown, coder for code, or worker for other writable artifacts.`;
+  }
+  return undefined;
+}
+
 function hostTrustsProjectAgents(): boolean {
   return /^(1|true|yes)$/i.test(process.env.TAKOMI_TRUST_PROJECT_AGENTS || "");
 }
@@ -127,6 +141,7 @@ function compactTaskForFingerprint(task: TakomiSubagentToolTask): Record<string,
     conversationId: task.conversationId || undefined,
     cwd: task.cwd,
     checklist: compactChecklistForFingerprint(task.checklist),
+    requiredCapabilities: task.requiredCapabilities?.length ? task.requiredCapabilities : undefined,
     acceptance: task.acceptance,
   };
 }
@@ -332,6 +347,7 @@ function resolveTasks(params: TakomiSubagentToolParams): TakomiSubagentToolTask[
       conversationId: params.conversationId,
       cwd: undefined,
       checklist: params.checklist,
+      requiredCapabilities: params.requiredCapabilities,
       acceptance: params.acceptance,
     }];
   }
@@ -405,6 +421,29 @@ export async function executeTakomiSubagentTool(
     return textResult(message, { results: [], availableAgents: agents.map((agent) => agent.name), agentScope }, true);
   }
 
+  for (const task of tasks) {
+    if (!byName.has(task.agent)) {
+      return textResult(
+        `Unknown or hidden Takomi persona '${task.agent}'. Available personas: ${agents.map((agent) => agent.name).join(", ") || "none"}.`,
+        { results: [], agentScope, task, reason: "unknown-persona" },
+        true,
+      );
+    }
+    const mismatch = capabilityMismatch(task, byName.get(task.agent));
+    if (mismatch) return textResult(`Blocked by Takomi capability validation.\n\n${mismatch}`, { results: [], agentScope, task, reason: "capability-mismatch" }, true);
+    if (task.model && routingSnapshot.approvedModels.length && !isTakomiModelApproved(task.model, routingSnapshot.approvedModels)) {
+      return textResult(
+        `Blocked by Takomi routing policy. Exact model '${task.model}' is not approved. No provider-equivalent substitution was attempted.`,
+        { results: [], agentScope, task, reason: "model-not-approved", approvedModels: routingSnapshot.approvedModels },
+        true,
+      );
+    }
+    const invalidFallback = task.fallbackModels?.find((model) => routingSnapshot.approvedModels.length && !isTakomiModelApproved(model, routingSnapshot.approvedModels));
+    if (invalidFallback) {
+      return textResult(`Blocked by Takomi routing policy. Explicit fallback '${invalidFallback}' is not approved.`, { results: [], agentScope, task, reason: "fallback-not-approved" }, true);
+    }
+  }
+
   if (!mode) {
     return textResult(
       `Provide exactly one mode: agent/task, tasks, or chain.\nAvailable agents: ${agents.map((agent) => `${agent.name} (${agent.source})`).join(", ") || "none"}`,

package/.pi/settings.json

@@ -1,42 +1,45 @@
 {
   "theme": "takomi-noir",
   "takomi": {
-    "modelRoutingPolicyFile": ".pi/takomi/model-routing.md"
-  },
-  "subagents": {
-    "agentOverrides": {
-      "general": {
-        "model": "oauth-router/gpt-5.4",
-        "thinking": "high",
-        "fallbackModels": [
-          "oauth-router/gpt-5.5:low"
-        ]
-      },
-      "orchestrator": {
-        "model": "oauth-router/gpt-5.5",
-        "thinking": "high"
-      },
-      "architect": {
-        "model": "oauth-router/gpt-5.5",
-        "thinking": "high"
-      },
-      "designer": {
-        "model": "oauth-router/gpt-5.4",
-        "thinking": "high",
-        "fallbackModels": [
-          "oauth-router/gpt-5.5:low"
-        ]
-      },
-      "coder": {
-        "model": "oauth-router/gpt-5.4",
-        "thinking": "high",
-        "fallbackModels": [
-          "oauth-router/gpt-5.5:low"
-        ]
-      },
-      "reviewer": {
-        "model": "oauth-router/gpt-5.5",
-        "thinking": "high"
+    "modelRoutingPolicyFile": ".pi/takomi/model-routing.md",
+    "routing": {
+      "defaultProvider": "openai-codex",
+      "approvedModels": [
+        "openai-codex/gpt-5.6-luna",
+        "openai-codex/gpt-5.6-sol",
+        "openai-codex/gpt-5.6-terra"
+      ],
+      "roleDefaults": {
+        "orchestrator": {
+          "model": "openai-codex/gpt-5.6-sol",
+          "thinking": "high"
+        },
+        "architect": {
+          "model": "openai-codex/gpt-5.6-sol",
+          "thinking": "high"
+        },
+        "designer": {
+          "model": "openai-codex/gpt-5.6-sol",
+          "thinking": "medium"
+        },
+        "coder": {
+          "model": "openai-codex/gpt-5.6-terra",
+          "thinking": "high",
+          "fallbackModels": [
+            "openai-codex/gpt-5.6-sol:low"
+          ]
+        },
+        "worker": {
+          "model": "openai-codex/gpt-5.6-luna",
+          "thinking": "high",
+          "fallbackModels": [
+            "openai-codex/gpt-5.6-sol:low"
+          ]
+        },
+        "reviewer": {
+          "model": "openai-codex/gpt-5.6-sol",
+          "thinking": "high"
+        }
       }
     }
   }

package/.pi/takomi/model-routing.md

@@ -1,5 +1,11 @@
 # Takomi Model Routing Policy
 
+## Authority Boundary
+
+This file is natural-language guidance for model judgment. It explains when Sol, Terra, Luna, or a specialist route fits a task. It does not define executable allowlists, providers, fallbacks, or persona defaults; those live under `takomi.routing` in global/project `.pi/settings.json`.
+
+Takomi's public personas are Architect, Designer, Coder, Worker, Reviewer, and Orchestrator. Genesis, Design, and Build are lifecycle stages. Design always means UI/UX, never application architecture.
+
 ## Goal
 
 Choose the cheapest route likely to complete the task correctly.

package/.pi/takomi-profile.json

@@ -1,50 +1,54 @@
-{
-  "version": 1,
-  "autoOrchestrate": true,
-  "launchMode": "auto",
-  "foreground": true,
-  "background": true,
-  "reviewAfterImplementation": true,
-  "roles": {
-    "orchestrator": {
-      "agent": "orchestrator",
-      "dispatchPolicy": "subagent"
-    },
-    "architect": {
-      "agent": "architect",
-      "dispatchPolicy": "subagent"
-    },
-    "design": {
-      "agent": "designer",
-      "dispatchPolicy": "subagent"
-    },
-    "code": {
-      "agent": "coder",
-      "dispatchPolicy": "subagent"
-    },
-    "review": {
-      "agent": "reviewer",
-      "dispatchPolicy": "review-first"
-    }
-  },
-  "stages": {
-    "genesis": {
-      "agent": "architect",
-      "dispatchPolicy": "subagent"
-    },
-    "design": {
-      "agent": "designer",
-      "dispatchPolicy": "subagent"
-    },
-    "build": {
-      "agent": "orchestrator",
-      "dispatchPolicy": "subagent"
-    }
-  },
-  "review": {
-    "enabled": true,
-    "agent": "reviewer",
-    "maxIterations": 2,
-    "sameConversation": true
-  }
-}
+{
+  "version": 1,
+  "autoOrchestrate": true,
+  "launchMode": "auto",
+  "foreground": true,
+  "background": true,
+  "reviewAfterImplementation": true,
+  "roles": {
+    "orchestrator": {
+      "agent": "orchestrator",
+      "dispatchPolicy": "subagent"
+    },
+    "architect": {
+      "agent": "architect",
+      "dispatchPolicy": "subagent"
+    },
+    "designer": {
+      "agent": "designer",
+      "dispatchPolicy": "subagent"
+    },
+    "coder": {
+      "agent": "coder",
+      "dispatchPolicy": "subagent"
+    },
+    "worker": {
+      "agent": "worker",
+      "dispatchPolicy": "subagent"
+    },
+    "reviewer": {
+      "agent": "reviewer",
+      "dispatchPolicy": "review-first"
+    }
+  },
+  "stages": {
+    "genesis": {
+      "agent": "architect",
+      "dispatchPolicy": "subagent"
+    },
+    "design": {
+      "agent": "designer",
+      "dispatchPolicy": "subagent"
+    },
+    "build": {
+      "agent": "coder",
+      "dispatchPolicy": "subagent"
+    }
+  },
+  "review": {
+    "enabled": true,
+    "agent": "reviewer",
+    "maxIterations": 2,
+    "sameConversation": true
+  }
+}