takomi 2.1.45 → 2.5.4

package/.pi/extensions/takomi-subagents/result-heartbeat.ts

@@ -1,55 +1,55 @@
-export const TAKOMI_SUBAGENT_HEARTBEAT_MS = 125;
-
-type Timer = ReturnType<typeof setInterval>;
-
-type HeartbeatState = {
-  takomiSubagentHeartbeatTimer?: Timer;
-  takomiSubagentHeartbeatFrame?: number;
-};
-
-export type TakomiSubagentRenderContext = {
-  state: Record<string, unknown>;
-  invalidate?: () => void;
-};
-
-const activeHeartbeatStates = new Set<HeartbeatState>();
-
-export function clearTakomiSubagentResultHeartbeat(context: TakomiSubagentRenderContext): void {
-  const state = context.state as HeartbeatState;
-  if (state.takomiSubagentHeartbeatTimer !== undefined) {
-    clearInterval(state.takomiSubagentHeartbeatTimer);
-    state.takomiSubagentHeartbeatTimer = undefined;
-  }
-  activeHeartbeatStates.delete(state);
-}
-
-export function ensureTakomiSubagentResultHeartbeat(context: TakomiSubagentRenderContext): void {
-  const state = context.state as HeartbeatState;
-  if (state.takomiSubagentHeartbeatTimer !== undefined || typeof context.invalidate !== "function") return;
-
-  state.takomiSubagentHeartbeatFrame ??= 0;
-  state.takomiSubagentHeartbeatTimer = setInterval(() => {
-    state.takomiSubagentHeartbeatFrame = ((state.takomiSubagentHeartbeatFrame ?? 0) + 1) % 10;
-    try {
-      context.invalidate?.();
-    } catch {
-      // A replaced session makes its row context stale. Stop immediately rather
-      // than retaining the old UI through a failing interval callback.
-      clearTakomiSubagentResultHeartbeat(context);
-    }
-  }, TAKOMI_SUBAGENT_HEARTBEAT_MS);
-  state.takomiSubagentHeartbeatTimer.unref?.();
-  activeHeartbeatStates.add(state);
-}
-
-export function getTakomiSubagentHeartbeatFrame(context: TakomiSubagentRenderContext): number {
-  return (context.state as HeartbeatState).takomiSubagentHeartbeatFrame ?? 0;
-}
-
-export function clearAllTakomiSubagentResultHeartbeats(): void {
-  for (const state of [...activeHeartbeatStates]) {
-    if (state.takomiSubagentHeartbeatTimer !== undefined) clearInterval(state.takomiSubagentHeartbeatTimer);
-    state.takomiSubagentHeartbeatTimer = undefined;
-    activeHeartbeatStates.delete(state);
-  }
-}
+export const TAKOMI_SUBAGENT_HEARTBEAT_MS = 125;
+
+type Timer = ReturnType<typeof setInterval>;
+
+type HeartbeatState = {
+  takomiSubagentHeartbeatTimer?: Timer;
+  takomiSubagentHeartbeatFrame?: number;
+};
+
+export type TakomiSubagentRenderContext = {
+  state: Record<string, unknown>;
+  invalidate?: () => void;
+};
+
+const activeHeartbeatStates = new Set<HeartbeatState>();
+
+export function clearTakomiSubagentResultHeartbeat(context: TakomiSubagentRenderContext): void {
+  const state = context.state as HeartbeatState;
+  if (state.takomiSubagentHeartbeatTimer !== undefined) {
+    clearInterval(state.takomiSubagentHeartbeatTimer);
+    state.takomiSubagentHeartbeatTimer = undefined;
+  }
+  activeHeartbeatStates.delete(state);
+}
+
+export function ensureTakomiSubagentResultHeartbeat(context: TakomiSubagentRenderContext): void {
+  const state = context.state as HeartbeatState;
+  if (state.takomiSubagentHeartbeatTimer !== undefined || typeof context.invalidate !== "function") return;
+
+  state.takomiSubagentHeartbeatFrame ??= 0;
+  state.takomiSubagentHeartbeatTimer = setInterval(() => {
+    state.takomiSubagentHeartbeatFrame = ((state.takomiSubagentHeartbeatFrame ?? 0) + 1) % 10;
+    try {
+      context.invalidate?.();
+    } catch {
+      // A replaced session makes its row context stale. Stop immediately rather
+      // than retaining the old UI through a failing interval callback.
+      clearTakomiSubagentResultHeartbeat(context);
+    }
+  }, TAKOMI_SUBAGENT_HEARTBEAT_MS);
+  state.takomiSubagentHeartbeatTimer.unref?.();
+  activeHeartbeatStates.add(state);
+}
+
+export function getTakomiSubagentHeartbeatFrame(context: TakomiSubagentRenderContext): number {
+  return (context.state as HeartbeatState).takomiSubagentHeartbeatFrame ?? 0;
+}
+
+export function clearAllTakomiSubagentResultHeartbeats(): void {
+  for (const state of [...activeHeartbeatStates]) {
+    if (state.takomiSubagentHeartbeatTimer !== undefined) clearInterval(state.takomiSubagentHeartbeatTimer);
+    state.takomiSubagentHeartbeatTimer = undefined;
+    activeHeartbeatStates.delete(state);
+  }
+}

package/.pi/extensions/takomi-subagents/subagent-ux.ts

@@ -1,162 +1,162 @@
-import { visibleWidth } from "@earendil-works/pi-tui";
-
-export type TakomiUxChecklistItem = {
-  id: string;
-  index: number;
-  text: string;
-  done: boolean;
-  stateSource: "input" | "agent-reported";
-};
-
-export type TakomiUxTask = {
-  agent: string;
-  task: string;
-  checklist: TakomiUxChecklistItem[];
-};
-
-const CHECKBOX_LINE = /^\s*[-*+]\s+\[([ xX])\]\s+(.+?)\s*$/;
-const ACCEPTANCE_BLOCK = /```acceptance-report\s*[\s\S]*?```/gi;
-const OSC_SEQUENCE = /\x1b\][\s\S]*?(?:\x07|\x1b\\|$)/g;
-const CSI_SEQUENCE = /(?:\x1b\[|\x9b)[0-?]*[ -\/]*[@-~]/g;
-const ESC_SEQUENCE = /\x1b(?:[()][0-2A-Z0-9]|[=>]|[ -\/]*[@-~]?)/g;
-const UNSAFE_CONTROLS = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/g;
-const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
-
-/** Remove terminal control sequences before untrusted values reach Text/Markdown. */
-export function sanitizeUntrustedText(value: string): string {
-  return value
-    .replace(OSC_SEQUENCE, "")
-    .replace(CSI_SEQUENCE, "")
-    .replace(ESC_SEQUENCE, "")
-    .replace(UNSAFE_CONTROLS, "");
-}
-
-/** Sanitize string leaves while retaining native result shape and Markdown syntax. */
-export function sanitizeUntrustedValue<T>(value: T, seen = new WeakMap<object, unknown>()): T {
-  if (typeof value === "string") return sanitizeUntrustedText(value) as T;
-  if (!value || typeof value !== "object") return value;
-  if (seen.has(value as object)) return seen.get(value as object) as T;
-  const output: any = Array.isArray(value) ? [] : {};
-  seen.set(value as object, output);
-  for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
-    output[key] = sanitizeUntrustedValue(child, seen);
-  }
-  return output as T;
-}
-
-export function createTakomiUxTasks(
-  tasks: Array<{ agent: string; task: string; checklist?: Array<string | { text: string; done?: boolean }> }>,
-): TakomiUxTask[] {
-  return tasks.map((task, taskIndex) => ({
-    agent: task.agent,
-    task: task.task,
-    checklist: (task.checklist ?? []).map((item, index) => ({
-      id: `task-${taskIndex + 1}-item-${index + 1}`,
-      index,
-      text: typeof item === "string" ? item : item.text,
-      done: typeof item === "string" ? false : item.done === true,
-      stateSource: "input",
-    })),
-  }));
-}
-
-export function withTakomiUxDetails(details: unknown, tasks: TakomiUxTask[]): Record<string, unknown> {
-  const base = details && typeof details === "object" && !Array.isArray(details)
-    ? details as Record<string, unknown>
-    : {};
-  return { ...base, takomiUx: { tasks } };
-}
-
-function textParts(content: unknown): string[] {
-  if (typeof content === "string") return content.trim() ? [content] : [];
-  if (!Array.isArray(content)) return [];
-  return content
-    .filter((part): part is { type: "text"; text: string } => (
-      Boolean(part) && typeof part === "object" && (part as any).type === "text" && typeof (part as any).text === "string"
-    ))
-    .map((part) => part.text)
-    .filter((text) => text.trim().length > 0);
-}
-
-/** Only explicit, visible assistant text is eligible for compact narrative. */
-export function explicitAssistantTexts(result: any): string[] {
-  if (!Array.isArray(result?.messages)) return [];
-  return result.messages
-    .filter((message: any) => message?.role === "assistant")
-    .flatMap((message: any) => textParts(message.content));
-}
-
-/**
- * Markdown boxes are not structured truth. Exact, unambiguous self-reports may
- * update a uniquely-labelled input item and are retained as agent-reported.
- */
-export function resolvedChecklist(items: TakomiUxChecklistItem[], assistantTexts: string[]): TakomiUxChecklistItem[] {
-  const states = items.map((item) => ({ ...item }));
-  const sourceCounts = new Map<string, number>();
-  for (const item of items) sourceCounts.set(item.text, (sourceCounts.get(item.text) ?? 0) + 1);
-
-  for (const text of assistantTexts) {
-    const reports = text.split(/\r?\n/).map((line) => line.match(CHECKBOX_LINE)).filter(Boolean) as RegExpMatchArray[];
-    const reportCounts = new Map<string, number>();
-    for (const report of reports) {
-      const label = report[2] ?? "";
-      reportCounts.set(label, (reportCounts.get(label) ?? 0) + 1);
-    }
-    for (const report of reports) {
-      const label = report[2] ?? "";
-      if (sourceCounts.get(label) !== 1 || reportCounts.get(label) !== 1) continue;
-      const item = states.find((candidate) => candidate.text === label);
-      if (!item) continue;
-      item.done = (report[1] ?? "").toLowerCase() === "x";
-      item.stateSource = "agent-reported";
-    }
-  }
-  return states;
-}
-
-function cleanNarrative(value: string): string {
-  return sanitizeUntrustedText(value)
-    .replace(ACCEPTANCE_BLOCK, "")
-    .replace(/\r/g, "")
-    .trim();
-}
-
-function meaningfulLines(value: string): string[] {
-  return cleanNarrative(value)
-    .split("\n")
-    .map((line) => line.replace(/\s+/g, " ").trim())
-    .filter(Boolean);
-}
-
-export function clipVisibleLine(line: string, maxColumns: number): string {
-  const safe = sanitizeUntrustedText(line);
-  if (visibleWidth(safe) <= maxColumns) return safe;
-  const target = Math.max(0, maxColumns - 1);
-  let output = "";
-  let width = 0;
-  for (const { segment } of segmenter.segment(safe)) {
-    const nextWidth = visibleWidth(segment);
-    if (width + nextWidth > target) break;
-    output += segment;
-    width += nextWidth;
-  }
-  return `${output}…`;
-}
-
-export function boundNarrative(
-  value: string,
-  options: { maxLines: number; maxColumns: number; from?: "start" | "end" },
-): { lines: string[]; truncated: boolean } {
-  const source = meaningfulLines(value);
-  const selected = options.from === "start" ? source.slice(0, options.maxLines) : source.slice(-options.maxLines);
-  const clipped = selected.map((line) => clipVisibleLine(line, options.maxColumns));
-  return {
-    lines: clipped,
-    truncated: source.length > selected.length || selected.some((line, index) => line !== clipped[index]),
-  };
-}
-
-export function finalAnswer(result: any): string {
-  if (typeof result?.finalOutput === "string" && result.finalOutput.trim()) return cleanNarrative(result.finalOutput);
-  return cleanNarrative(explicitAssistantTexts(result).at(-1) ?? "");
-}
+import { visibleWidth } from "@earendil-works/pi-tui";
+
+export type TakomiUxChecklistItem = {
+  id: string;
+  index: number;
+  text: string;
+  done: boolean;
+  stateSource: "input" | "agent-reported";
+};
+
+export type TakomiUxTask = {
+  agent: string;
+  task: string;
+  checklist: TakomiUxChecklistItem[];
+};
+
+const CHECKBOX_LINE = /^\s*[-*+]\s+\[([ xX])\]\s+(.+?)\s*$/;
+const ACCEPTANCE_BLOCK = /```acceptance-report\s*[\s\S]*?```/gi;
+const OSC_SEQUENCE = /\x1b\][\s\S]*?(?:\x07|\x1b\\|$)/g;
+const CSI_SEQUENCE = /(?:\x1b\[|\x9b)[0-?]*[ -\/]*[@-~]/g;
+const ESC_SEQUENCE = /\x1b(?:[()][0-2A-Z0-9]|[=>]|[ -\/]*[@-~]?)/g;
+const UNSAFE_CONTROLS = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/g;
+const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+/** Remove terminal control sequences before untrusted values reach Text/Markdown. */
+export function sanitizeUntrustedText(value: string): string {
+  return value
+    .replace(OSC_SEQUENCE, "")
+    .replace(CSI_SEQUENCE, "")
+    .replace(ESC_SEQUENCE, "")
+    .replace(UNSAFE_CONTROLS, "");
+}
+
+/** Sanitize string leaves while retaining native result shape and Markdown syntax. */
+export function sanitizeUntrustedValue<T>(value: T, seen = new WeakMap<object, unknown>()): T {
+  if (typeof value === "string") return sanitizeUntrustedText(value) as T;
+  if (!value || typeof value !== "object") return value;
+  if (seen.has(value as object)) return seen.get(value as object) as T;
+  const output: any = Array.isArray(value) ? [] : {};
+  seen.set(value as object, output);
+  for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
+    output[key] = sanitizeUntrustedValue(child, seen);
+  }
+  return output as T;
+}
+
+export function createTakomiUxTasks(
+  tasks: Array<{ agent: string; task: string; checklist?: Array<string | { text: string; done?: boolean }> }>,
+): TakomiUxTask[] {
+  return tasks.map((task, taskIndex) => ({
+    agent: task.agent,
+    task: task.task,
+    checklist: (task.checklist ?? []).map((item, index) => ({
+      id: `task-${taskIndex + 1}-item-${index + 1}`,
+      index,
+      text: typeof item === "string" ? item : item.text,
+      done: typeof item === "string" ? false : item.done === true,
+      stateSource: "input",
+    })),
+  }));
+}
+
+export function withTakomiUxDetails(details: unknown, tasks: TakomiUxTask[]): Record<string, unknown> {
+  const base = details && typeof details === "object" && !Array.isArray(details)
+    ? details as Record<string, unknown>
+    : {};
+  return { ...base, takomiUx: { tasks } };
+}
+
+function textParts(content: unknown): string[] {
+  if (typeof content === "string") return content.trim() ? [content] : [];
+  if (!Array.isArray(content)) return [];
+  return content
+    .filter((part): part is { type: "text"; text: string } => (
+      Boolean(part) && typeof part === "object" && (part as any).type === "text" && typeof (part as any).text === "string"
+    ))
+    .map((part) => part.text)
+    .filter((text) => text.trim().length > 0);
+}
+
+/** Only explicit, visible assistant text is eligible for compact narrative. */
+export function explicitAssistantTexts(result: any): string[] {
+  if (!Array.isArray(result?.messages)) return [];
+  return result.messages
+    .filter((message: any) => message?.role === "assistant")
+    .flatMap((message: any) => textParts(message.content));
+}
+
+/**
+ * Markdown boxes are not structured truth. Exact, unambiguous self-reports may
+ * update a uniquely-labelled input item and are retained as agent-reported.
+ */
+export function resolvedChecklist(items: TakomiUxChecklistItem[], assistantTexts: string[]): TakomiUxChecklistItem[] {
+  const states = items.map((item) => ({ ...item }));
+  const sourceCounts = new Map<string, number>();
+  for (const item of items) sourceCounts.set(item.text, (sourceCounts.get(item.text) ?? 0) + 1);
+
+  for (const text of assistantTexts) {
+    const reports = text.split(/\r?\n/).map((line) => line.match(CHECKBOX_LINE)).filter(Boolean) as RegExpMatchArray[];
+    const reportCounts = new Map<string, number>();
+    for (const report of reports) {
+      const label = report[2] ?? "";
+      reportCounts.set(label, (reportCounts.get(label) ?? 0) + 1);
+    }
+    for (const report of reports) {
+      const label = report[2] ?? "";
+      if (sourceCounts.get(label) !== 1 || reportCounts.get(label) !== 1) continue;
+      const item = states.find((candidate) => candidate.text === label);
+      if (!item) continue;
+      item.done = (report[1] ?? "").toLowerCase() === "x";
+      item.stateSource = "agent-reported";
+    }
+  }
+  return states;
+}
+
+function cleanNarrative(value: string): string {
+  return sanitizeUntrustedText(value)
+    .replace(ACCEPTANCE_BLOCK, "")
+    .replace(/\r/g, "")
+    .trim();
+}
+
+function meaningfulLines(value: string): string[] {
+  return cleanNarrative(value)
+    .split("\n")
+    .map((line) => line.replace(/\s+/g, " ").trim())
+    .filter(Boolean);
+}
+
+export function clipVisibleLine(line: string, maxColumns: number): string {
+  const safe = sanitizeUntrustedText(line);
+  if (visibleWidth(safe) <= maxColumns) return safe;
+  const target = Math.max(0, maxColumns - 1);
+  let output = "";
+  let width = 0;
+  for (const { segment } of segmenter.segment(safe)) {
+    const nextWidth = visibleWidth(segment);
+    if (width + nextWidth > target) break;
+    output += segment;
+    width += nextWidth;
+  }
+  return `${output}…`;
+}
+
+export function boundNarrative(
+  value: string,
+  options: { maxLines: number; maxColumns: number; from?: "start" | "end" },
+): { lines: string[]; truncated: boolean } {
+  const source = meaningfulLines(value);
+  const selected = options.from === "start" ? source.slice(0, options.maxLines) : source.slice(-options.maxLines);
+  const clipped = selected.map((line) => clipVisibleLine(line, options.maxColumns));
+  return {
+    lines: clipped,
+    truncated: source.length > selected.length || selected.some((line, index) => line !== clipped[index]),
+  };
+}
+
+export function finalAnswer(result: any): string {
+  if (typeof result?.finalOutput === "string" && result.finalOutput.trim()) return cleanNarrative(result.finalOutput);
+  return cleanNarrative(explicitAssistantTexts(result).at(-1) ?? "");
+}

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,
     }];
   }
@@ -361,6 +377,31 @@ export async function executeTakomiSubagentTool(
   const agentScope = params.agentScope ?? "both";
 
   if (params.action) {
+    if (params.action === "list") {
+      const agents = discoverTakomiAgents(rootCwd, agentScope);
+      const lines = [
+        "Takomi personas:",
+        ...agents.map((agent) => `- ${agent.name} (${agent.source}): ${agent.description}`),
+        "",
+        "Canonical personas only: architect, designer, coder, worker, reviewer, orchestrator.",
+      ];
+      return textResult(lines.join("\n"), {
+        action: "list",
+        agentScope,
+        availableAgents: agents.map((agent) => ({ name: agent.name, source: agent.source, description: agent.description, tools: agent.tools })),
+        takomi: { action: "list", agentScope },
+      });
+    }
+    if ((params.action === "get" || params.action === "models") && params.agent) {
+      const agents = discoverTakomiAgents(rootCwd, agentScope);
+      if (!agents.some((agent) => agent.name === params.agent)) {
+        return textResult(
+          `Unknown or hidden Takomi persona '${params.agent}'. Available personas: ${agents.map((agent) => agent.name).join(", ") || "none"}.`,
+          { results: [], action: params.action, agentScope, reason: "unknown-persona" },
+          true,
+        );
+      }
+    }
     try {
       const nativeResult: any = await engine.execute(
         "takomi-tool",
@@ -405,6 +446,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.