takomi 2.1.44 → 2.1.45

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

@@ -3,13 +3,17 @@ import path from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 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 { resolveAgentName } from "./agent-aliases";
 import { discoverTakomiAgents, type TakomiAgentConfig, type TakomiAgentScope } from "./agents";
 import { createTakomiDelegationPlan, renderTakomiDelegationPlan } from "./delegation-plan";
+import { rememberDetachedLaunch, resolveDetachedStatusResult } from "./detached-results";
 import { createTakomiPiSubagentsEngine } from "./pi-subagents-engine";
+import { createTakomiUxTasks, withTakomiUxDetails } from "./subagent-ux";
 
 type ChecklistItem = string | { text: string; done?: boolean };
+export type TakomiAcceptanceInput = false | "auto" | "none" | "attested" | "checked" | "verified" | "reviewed" | Record<string, unknown>;
 
 export type TakomiSubagentToolTask = {
   agent: string;
@@ -22,6 +26,7 @@ export type TakomiSubagentToolTask = {
   conversationId?: string;
   cwd?: string;
   checklist?: ChecklistItem[];
+  acceptance?: TakomiAcceptanceInput;
 };
 
 export type TakomiSubagentToolParams = Partial<TakomiSubagentToolTask> & {
@@ -50,10 +55,18 @@ const MAX_PARALLEL_TASKS = 8;
 const HARD_STOP_TTL_MS = 10 * 60 * 1000;
 const ENGINES = new WeakMap<ExtensionAPI, ReturnType<typeof createTakomiPiSubagentsEngine>>();
 
+type UserTurnMarker = {
+  sessionId?: string;
+  count: number;
+  lastEntryId?: string;
+  entryIds: string[];
+};
+
 type HardStopRecord = {
   at: number;
   reason: string;
   message: string;
+  userTurnMarker?: UserTurnMarker;
 };
 
 const RECENT_HARD_STOPS = new WeakMap<ExtensionAPI, Map<string, HardStopRecord>>();
@@ -66,6 +79,11 @@ function getEngine(pi: ExtensionAPI): ReturnType<typeof createTakomiPiSubagentsE
   return engine;
 }
 
+export function invalidateTakomiPiSubagentsEngine(pi: ExtensionAPI): void {
+  ENGINES.get(pi)?.dispose();
+  ENGINES.delete(pi);
+}
+
 function textResult<TDetails extends Record<string, unknown>>(text: string, details: TDetails, isError?: boolean) {
   return { content: [{ type: "text" as const, text }], details, isError };
 }
@@ -78,6 +96,10 @@ function hostTrustsProjectAgents(): boolean {
   return /^(1|true|yes)$/i.test(process.env.TAKOMI_TRUST_PROJECT_AGENTS || "");
 }
 
+function isProjectAgentApprovalHardStop(record: HardStopRecord | undefined): boolean {
+  return record?.reason === "project-agent-approval-required" || record?.reason === "project-agent-denied";
+}
+
 function hardStopStore(pi: ExtensionAPI): Map<string, HardStopRecord> {
   const existing = RECENT_HARD_STOPS.get(pi);
   if (existing) return existing;
@@ -86,22 +108,78 @@ function hardStopStore(pi: ExtensionAPI): Map<string, HardStopRecord> {
   return next;
 }
 
+type TakomiRunMode = "single" | "parallel" | "chain";
+
+function compactChecklistForFingerprint(checklist: ChecklistItem[] | undefined): Array<{ text: string; done: boolean }> | undefined {
+  if (!checklist?.length) return undefined;
+  return checklist.map((item) => typeof item === "string" ? { text: item, done: false } : { text: item.text, done: item.done ?? false });
+}
+
 function compactTaskForFingerprint(task: TakomiSubagentToolTask): Record<string, unknown> {
   return {
     agent: task.agent,
     task: task.task,
-    workflow: task.workflow,
-    skills: task.skills,
-    model: task.model,
-    fallbackModels: task.fallbackModels,
+    workflow: task.workflow || undefined,
+    skills: task.skills?.length ? task.skills : undefined,
+    model: task.model || undefined,
+    fallbackModels: task.fallbackModels?.length ? task.fallbackModels : undefined,
     thinking: task.thinking,
-    conversationId: task.conversationId,
+    conversationId: task.conversationId || undefined,
     cwd: task.cwd,
+    checklist: compactChecklistForFingerprint(task.checklist),
+    acceptance: task.acceptance,
   };
 }
 
-function createRunFingerprint(rootCwd: string, mode: "single" | "parallel" | "chain" | undefined, tasks: TakomiSubagentToolTask[]): string {
-  return JSON.stringify({ rootCwd, mode, tasks: tasks.map(compactTaskForFingerprint) });
+const IMPLICIT_CONTEXT = "implicit" as const;
+type CanonicalContext = typeof IMPLICIT_CONTEXT | "fresh" | "fork";
+
+function canonicalContextForFingerprint(context: TakomiSubagentToolParams["context"]): CanonicalContext {
+  // Omission delegates context selection to native pi-subagents, whose built-in
+  // and settings defaults are authoritative. Never approximate that resolution
+  // with Takomi-only discovery: implicit input is its own approval semantic.
+  return context ?? IMPLICIT_CONTEXT;
+}
+
+function canonicalContextsForFingerprint(
+  params: TakomiSubagentToolParams,
+  tasks: TakomiSubagentToolTask[],
+): CanonicalContext[] {
+  const context = canonicalContextForFingerprint(params.context);
+  // `context` is a global override. When omitted, each native task resolves its
+  // own default, but all retain the distinct implicit-input sentinel here.
+  return tasks.map(() => context);
+}
+
+function effectiveConcurrencyForFingerprint(mode: TakomiRunMode, concurrency: number | undefined): number | undefined {
+  if (mode !== "parallel") return undefined;
+  return typeof concurrency === "number" && Number.isInteger(concurrency) && concurrency >= 1 ? concurrency : 4;
+}
+
+function createRunFingerprint(
+  rootCwd: string,
+  mode: TakomiRunMode,
+  tasks: TakomiSubagentToolTask[],
+  params: TakomiSubagentToolParams,
+  agentScope: TakomiAgentScope,
+): string {
+  const context = canonicalContextForFingerprint(params.context);
+  return JSON.stringify({
+    rootCwd,
+    mode,
+    tasks: tasks.map(compactTaskForFingerprint),
+    launch: {
+      context: {
+        global: context,
+        perTask: canonicalContextsForFingerprint(params, tasks),
+      },
+      async: params.async === true,
+      concurrency: effectiveConcurrencyForFingerprint(mode, params.concurrency),
+      worktree: mode === "parallel" && params.worktree === true,
+      clarify: params.clarify === true,
+      agentScope,
+    },
+  });
 }
 
 function hardStopResult(message: string, details: Record<string, unknown>) {
@@ -112,8 +190,34 @@ function hardStopResult(message: string, details: Record<string, unknown>) {
   ].join("\n"), { ...details, takomiHardStop: true }, true);
 }
 
-function rememberHardStop(pi: ExtensionAPI, fingerprint: string, reason: string, message: string): void {
-  hardStopStore(pi).set(fingerprint, { at: Date.now(), reason, message });
+function rememberHardStop(
+  pi: ExtensionAPI,
+  fingerprint: string,
+  reason: string,
+  message: string,
+  userTurnMarker?: UserTurnMarker,
+): void {
+  hardStopStore(pi).set(fingerprint, { at: Date.now(), reason, message, userTurnMarker });
+}
+
+function readUserTurnMarker(ctx: ExtensionContext): UserTurnMarker {
+  const userEntries = ctx.sessionManager.getEntries().filter((entry) => entry.type === "message" && entry.message.role === "user");
+  const entryIds = userEntries.map((entry) => entry.id);
+  return {
+    sessionId: ctx.sessionManager.getSessionId(),
+    count: userEntries.length,
+    lastEntryId: entryIds.at(-1),
+    entryIds,
+  };
+}
+
+function hasStrictlyNewerUserTurn(record: HardStopRecord, current: UserTurnMarker): boolean {
+  const recorded = record.userTurnMarker;
+  if (!recorded || recorded.sessionId !== current.sessionId || current.count <= recorded.count) return false;
+  if (!recorded.lastEntryId) return true;
+
+  const recordedTurnIndex = current.entryIds.indexOf(recorded.lastEntryId);
+  return recordedTurnIndex >= 0 && recordedTurnIndex < current.entryIds.length - 1;
 }
 
 function consumeExpiredHardStop(pi: ExtensionAPI, fingerprint: string): HardStopRecord | undefined {
@@ -146,12 +250,6 @@ async function resolveRelativeCwd(root: string, value: string | undefined, label
   return realCandidate;
 }
 
-async function validateTaskCwds(root: string, tasks: TakomiSubagentToolTask[]): Promise<void> {
-  for (const [index, task] of tasks.entries()) {
-    await resolveRelativeCwd(root, task.cwd, `tasks[${index}].cwd`);
-  }
-}
-
 function getTextContent(result: any): string {
   return (result?.content ?? [])
     .map((item: any) => item?.type === "text" && typeof item.text === "string" ? item.text : "")
@@ -234,6 +332,7 @@ function resolveTasks(params: TakomiSubagentToolParams): TakomiSubagentToolTask[
       conversationId: params.conversationId,
       cwd: undefined,
       checklist: params.checklist,
+      acceptance: params.acceptance,
     }];
   }
   return [];
@@ -255,6 +354,10 @@ export async function executeTakomiSubagentTool(
   }
   const profile = await loadTakomiProfile(rootCwd);
   const runtimeLaunchMode = readRuntimeLaunchMode(ctx);
+  const userTurnMarker = readUserTurnMarker(ctx);
+  // Auto launch mode may come from a model, profile, default, or restored
+  // runtime state. None of those are project-agent authorization.
+  const userGateAutoAuthorized = hasUserGateAutoProvenance(ctx.sessionManager.getEntries());
   const agentScope = params.agentScope ?? "both";
 
   if (params.action) {
@@ -266,10 +369,13 @@ export async function executeTakomiSubagentTool(
         onUpdate as any,
         ctx,
       );
+      const resolvedResult = params.action === "status"
+        ? await resolveDetachedStatusResult(pi, params, nativeResult)
+        : nativeResult;
       return {
-        ...nativeResult,
+        ...resolvedResult,
         details: {
-          ...(nativeResult?.details ?? {}),
+          ...(resolvedResult?.details ?? {}),
           takomi: {
             action: params.action,
             agentScope,
@@ -289,11 +395,11 @@ export async function executeTakomiSubagentTool(
   let tasks: TakomiSubagentToolTask[];
   try {
     const rawTasks = resolveTasks(params);
-    await validateTaskCwds(rootCwd, rawTasks);
-    tasks = rawTasks.map((task) => applyTakomiRoutingDefaults({
+    tasks = await Promise.all(rawTasks.map(async (task, index) => applyTakomiRoutingDefaults({
       ...task,
       agent: resolveAgentName(task.agent, byName),
-    }, routingSnapshot));
+      cwd: await resolveRelativeCwd(rootCwd, task.cwd, `tasks[${index}].cwd`),
+    }, routingSnapshot)));
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     return textResult(message, { results: [], availableAgents: agents.map((agent) => agent.name), agentScope }, true);
@@ -310,17 +416,23 @@ export async function executeTakomiSubagentTool(
     return textResult(`Too many parallel tasks (${tasks.length}). Max is ${MAX_PARALLEL_TASKS}.`, { results: [], agentScope }, true);
   }
 
-  const fingerprint = createRunFingerprint(rootCwd, mode, tasks);
+  const fingerprint = createRunFingerprint(rootCwd, mode, tasks, params, agentScope);
+  const projectAgentsAuthorized = userGateAutoAuthorized || hostTrustsProjectAgents();
   const recentHardStop = consumeExpiredHardStop(pi, fingerprint);
-  if (recentHardStop) {
+  const authorizationOverridesHardStop = projectAgentsAuthorized && isProjectAgentApprovalHardStop(recentHardStop);
+  const consumesReviewGate = recentHardStop?.reason === "review-gate"
+    && params.confirmLaunch === true
+    && params.previewOnly !== true
+    && hasStrictlyNewerUserTurn(recentHardStop, userTurnMarker);
+  if (recentHardStop && !authorizationOverridesHardStop && !consumesReviewGate) {
     return hardStopResult(
       `Subagent launch blocked: the same request was already stopped (${recentHardStop.reason}).\n${recentHardStop.message}`,
       { results: [], availableAgents: agents.map((agent) => agent.name), agentScope, mode, blockedAt: recentHardStop.at, reason: recentHardStop.reason },
     );
   }
+  if (authorizationOverridesHardStop || consumesReviewGate) hardStopStore(pi).delete(fingerprint);
 
-  const projectAgentsTrusted = hostTrustsProjectAgents();
-  if (!projectAgentsTrusted && hasProjectAgents(tasks, byName)) {
+  if (!projectAgentsAuthorized && hasProjectAgents(tasks, byName)) {
     const names = tasks.map((task) => byName.get(task.agent)).filter((agent): agent is TakomiAgentConfig => agent?.source === "project").map((agent) => agent.name);
     const uniqueNames = [...new Set(names)].join(", ");
     if (!ctx.hasUI) {
@@ -356,9 +468,9 @@ export async function executeTakomiSubagentTool(
   if (params.previewOnly) {
     return textResult(renderTakomiDelegationPlan(plan), { plan, availableAgents: agents.map((agent) => agent.name), agentScope, mode });
   }
-  if (plan.launchMode === "manual" && !params.confirmLaunch) {
+  if (plan.launchMode === "manual" && !consumesReviewGate) {
     const message = `${renderTakomiDelegationPlan(plan)}\n\nReview gate is awaiting explicit user approval.`;
-    rememberHardStop(pi, fingerprint, "review-gate", "Review gate displayed a delegation plan and paused before launch.");
+    rememberHardStop(pi, fingerprint, "review-gate", "Review gate displayed a delegation plan and paused before launch.", userTurnMarker);
     return hardStopResult(message, { plan, availableAgents: agents.map((agent) => agent.name), agentScope, mode });
   }
   try {
@@ -367,15 +479,33 @@ export async function executeTakomiSubagentTool(
       : mode === "parallel"
         ? { ...params, cwd: rootCwd, tasks, agentScope }
         : { ...params, cwd: rootCwd, chain: tasks, agentScope };
+    const uxTasks = createTakomiUxTasks(tasks);
+    const nativeOnUpdate = onUpdate
+      ? (partial: any) => onUpdate({
+          ...partial,
+          details: withTakomiUxDetails(partial?.details, uxTasks),
+        })
+      : undefined;
 
     const nativeResult: any = await engine.execute(
       "takomi-tool",
       nativeParams,
       signal,
-      onUpdate as any,
+      nativeOnUpdate as any,
       ctx,
     );
 
+    if (params.async === true) {
+      await rememberDetachedLaunch(
+        pi,
+        nativeResult,
+        uxTasks,
+        ctx,
+        rootCwd,
+        mode === "single" ? tasks[0]?.cwd ?? rootCwd : rootCwd,
+      );
+    }
+
     const takomi = {
       plan,
       agentScope,
@@ -390,7 +520,7 @@ export async function executeTakomiSubagentTool(
     return {
       ...nativeResult,
       details: {
-        ...(nativeResult?.details ?? {}),
+        ...withTakomiUxDetails(nativeResult?.details, uxTasks),
         takomi,
       },
     };

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

@@ -1,3 +1,282 @@
-# Takomi Model Routing Policy
-
-I want to set up a model-routing strategy for my coding agent sub-agents. Important reasoning-effort rule: Whenever I say GPT-5.4, I mean GPT-5.4 High. Whenever I say GPT-5.4 Mini, I mean GPT-5.4 Mini High. GPT-5.5 can be used at Low, Medium, or High depending on task difficulty. General rule of thumb: Use GPT-5.5 High or Medium for uncertain, expensive, risky, or high-judgment planning. Use GPT-5.5 Low when the task is already well understood but still benefits from senior-level intelligence. Use GPT-5.4 High for planning plus execution when the task is normal-to-serious but not deeply uncertain. Use GPT-5.5 Low for clean execution when the plan is already clear but correctness still matters. Use GPT-5.4 Mini High for fast execution when there is a detailed plan and the task is small, isolated, and explicit. Available models: GPT-5.5 Use this as the senior brain. Best for complex reasoning, architecture decisions, difficult debugging, regression detection, security review, large refactors, cross-file changes, unclear requirements, and tasks where missing context needs to be inferred. Use GPT-5.5 High for: - major architecture decisions - security-sensitive logic - hard debugging - regression hunting - cross-file refactors - unclear or vague tasks - final deep review Use GPT-5.5 Medium for: - serious planning - complex but bounded implementation - non-trivial debugging - design/product judgment - reviewing important code where the risk is moderate Use GPT-5.5 Low for: - execution after the plan is clear - targeted fixes - applying known patterns - straightforward implementation where the model still needs strong context awareness GPT-5.4 High Use this as the default serious workhorse. Best for normal coding, planning, UI logic, implementation, debugging, reviewing, and general execution. It is strong enough for most serious work without needing every tiny instruction spelled out. Use GPT-5.4 High when: - the task is clear enough to execute - the work needs solid reasoning but not senior-level uncertainty handling - the agent needs to plan and code in the same pass - the change is moderate in size - the codebase context is understandable - the risk of hidden regressions is not extreme GPT-5.4 Mini High Use this as the fast execution model. Best for small, clear, isolated tasks where the instructions are already detailed. Use GPT-5.4 Mini High for: - simple edits - boilerplate - formatting - small components - simple tests - docs cleanup - renaming - repetitive implementation - basic Tailwind/style changes - applying an already-written plan Do not use GPT-5.4 Mini High for: - vague tasks - deep debugging - major refactors - architecture decisions - hidden regression checks - security-sensitive changes - anything that requires strong judgment - anything where the model must infer too much missing context Role routing: Architect Use GPT-5.5 High for system design, database planning, API structure, security-sensitive decisions, major refactors, unclear project direction, or anything that could affect long-term maintainability. Use GPT-5.5 Medium for serious but bounded architecture planning. Use GPT-5.4 High for normal planning and straightforward architecture. Avoid GPT-5.4 Mini High for architecture. Coder Use GPT-5.4 High as the default coder. Use GPT-5.5 High when the code is complex, risky, deeply connected across files, or likely to cause regressions. Use GPT-5.5 Medium when the implementation is complex but the plan is mostly clear. Use GPT-5.5 Low when the plan is very clear but the task still needs strong contextual awareness. Use GPT-5.4 Mini High only for small, explicit, isolated coding tasks. Designer Use GPT-5.4 High by default for UI/UX layout, component structure, design systems, and frontend logic. Use GPT-5.5 Medium or High when the design problem needs deep product thinking, complex interaction logic, UX tradeoffs, or accessibility judgment. Use GPT-5.4 Mini High for simple style changes, spacing, copy updates, basic Tailwind edits, and clearly defined UI tweaks. Reviewer Use GPT-5.5 High for serious review: regressions, edge cases, security issues, architecture violations, broken assumptions, and deep correctness checks. Use GPT-5.5 Medium for important review where the scope is bounded. Use GPT-5.4 High for normal review. Use GPT-5.4 Mini High only for basic formatting checks, typo checks, or obvious surface-level issues. General model routing: Use GPT-5.5 when the task requires judgment. Use GPT-5.4 High when the task requires solid planning and execution. Use GPT-5.4 Mini High when the task requires speed and the instructions are precise. Escalation rule: Start with the cheapest capable model, but escalate immediately if the task becomes vague, risky, cross-file, architecture-heavy, debugging-heavy, security-sensitive, or regression-sensitive. Default setup: Architect: - GPT-5.5 High for serious planning - GPT-5.5 Medium for bounded complex planning - GPT-5.4 High for normal planning - Avoid GPT-5.4 Mini High Coder: - GPT-5.4 High by default - GPT-5.5 High for complex or risky work - GPT-5.5 Medium for complex but bounded implementation - GPT-5.5 Low for clear execution that still needs senior context - GPT-5.4 Mini High for simple explicit tasks Designer: - GPT-5.4 High by default - GPT-5.5 Medium/High for product-heavy or interaction-heavy design - GPT-5.4 Mini High for small styling tasks Reviewer: - GPT-5.5 High for final/deep review - GPT-5.5 Medium for important bounded review - GPT-5.4 High for normal review - GPT-5.4 Mini High for surface-level checks only Mental model: GPT-5.5 is the senior engineer/architect/reviewer. GPT-5.4 High is the reliable mid-to-senior workhorse. GPT-5.4 Mini High is the fast junior implementer. Treat GPT-5.4 Mini High like a fast junior implementer: excellent when the task is specific, dangerous when the task is vague. Treat GPT-5.4 High like the default serious builder. Treat GPT-5.5 like the senior brain whose reasoning effort should be adjusted based on risk: Low for clear execution, Medium for serious bounded work, High for uncertainty, architecture, debugging, and review.
+# Takomi Model Routing Policy
+
+## Goal
+
+Choose the cheapest route likely to complete the task correctly.
+
+When performance is close, prefer the stronger model at lower effort over a weaker model at extreme effort.
+
+## Core routing rule
+
+* **Sol** decides what should be done.
+* **Terra** executes a clear direction.
+* **Luna** handles bounded, repetitive, or parallel work.
+* **Gemini Flash through the Antigravity CLI** explores visual directions. Antigravity is an external CLI execution route, not a model provider.
+* **GPT-5.5** is a specialist fallback.
+
+Route by task shape, not task length. A short ambiguous task may require Sol. A long clear task may be better for Terra.
+
+## Default routes
+
+### Sol Low — Intelligent default
+
+Use for:
+
+* vague or incomplete instructions
+* normal tasks requiring judgment
+* product thinking
+* UI direction
+* codebase exploration
+* ordinary debugging
+* research and synthesis
+* reviewing plans or implementations
+
+### Sol Medium — Serious default brain
+
+Use for:
+
+* architecture
+* serious planning
+* ambiguous implementation
+* design-heavy product work
+* cross-file changes requiring judgment
+* difficult debugging
+* important knowledge work
+* final review of medium-risk work
+
+### Sol High — Senior architect and reviewer
+
+Use for:
+
+* major architecture decisions
+* hard debugging
+* security-sensitive logic
+* regression hunting
+* high-risk refactors
+* final deep review
+* expensive failure cases
+
+### Sol Max — Critical escalation
+
+Use only for:
+
+* critical security work
+* severe ambiguity
+* extremely difficult debugging
+* final review of high-risk changes
+* cases where failure costs far more than model usage
+
+### Terra High — Default serious coder
+
+Use for:
+
+* substantial but clear implementation
+* repository work across several files
+* frontend and backend implementation
+* tests and ordinary debugging
+* implementing an established product or UI direction
+* normal serious coding
+
+### Terra Max — Long-horizon implementation engine
+
+Use for:
+
+* long autonomous coding tasks
+* large clear refactors
+* complex implementations with known requirements
+* tasks where Terra High loses coherence
+* cost-sensitive alternatives to Sol High or Max
+
+### Luna Medium — Fast junior executor
+
+Use for:
+
+* small explicit edits
+* boilerplate
+* documentation
+* simple tests
+* renaming
+* formatting
+* repetitive transformations
+* tightly scoped fixes
+
+### Luna High — Parallel execution engine
+
+Use for:
+
+* bounded implementation
+* parallel sub-agents
+* executing a written plan
+* repetitive cross-file changes
+* medium tasks with clear acceptance criteria
+* high-volume work that will be reviewed
+
+### GPT-5.5 — Specialist fallback
+
+Use only for:
+
+* logic-heavy comparisons
+* regression hunting
+* prompts already tuned for GPT-5.5
+* adversarial second opinions
+
+Do not use GPT-5.5 as the default architect, coder, or designer.
+
+### Gemini 3.5 Flash through Antigravity CLI — Visual exploration specialist
+
+Invoke Gemini 3.5 Flash through the Antigravity CLI. Do not interpret Antigravity as a provider name.
+
+Use for:
+
+* rapid UI concepts
+* visual exploration
+* motion-graphics ideas
+* reference-driven design
+* multimodal analysis
+* generating several creative directions
+
+Do not use it as the default long-horizon repository agent.
+
+## Role routing
+
+### Architect
+
+* Normal planning: Sol Low
+* Serious architecture: Sol Medium
+* High-risk architecture: Sol High
+* Critical architecture or security: Sol Max
+
+### Coder
+
+* Small explicit task: Luna Medium
+* Bounded or parallel task: Luna High
+* Normal serious implementation: Terra High
+* Long clear implementation: Terra Max
+* Unclear implementation: Sol Medium
+* High-risk implementation: Sol High
+
+### Orchestrator
+
+* Product direction or UX decisions: Sol Low or Medium
+* Scaffold plus UI with ambiguity: Sol Medium
+* Production implementation after direction is clear: Terra High
+* Large build with clear requirements: Terra Max
+* Parallel components and chores: Luna High
+
+### Designer
+
+* Visual exploration: Gemini 3.5 Flash
+* Product and UI direction: Sol Low or Medium
+* Production UI implementation: Terra High
+* Premium design review: Sol High
+
+### Reviewer
+
+* Normal review: Sol Low
+* Important review: Sol Medium
+* Deep regression or security review: Sol High
+* Critical final review: Sol Max
+
+## Decision tree
+
+```text
+Small, explicit, and isolated?
+-> Luna Medium
+
+Bounded, repetitive, or parallel?
+-> Luna High
+
+Must decide what should be built?
+-> Sol Low
+-> Sol Medium when serious or ambiguous
+
+Direction clear and mainly implementation?
+-> Terra High
+-> Terra Max when large or long-running
+
+High-risk, security-sensitive, or deeply uncertain?
+-> Sol High
+-> Sol Max when critical
+```
+
+## Model-body preference
+
+When results are close:
+
+* Prefer Sol Low over Luna xHigh.
+* Prefer Sol Medium over Luna Max.
+* Prefer Terra High over pushing Luna to xHigh or Max.
+* Prefer the stronger model body unless the weaker route is materially cheaper and the task is well bounded.
+
+Avoid xHigh and Max by default. Use them only when public evidence or task risk justifies them.
+
+## Recommended handoff
+
+```text
+Sol Low or Medium
+-> interpret requirements
+-> choose architecture
+-> define acceptance criteria
+
+Terra High or Max
+-> implement
+-> test
+-> fix failures
+
+Sol Low, Medium, or High
+-> review correctness
+-> check regressions
+-> verify the right problem was solved
+```
+
+Use Luna High for parallel subtasks with clear instructions.
+
+## Escalation triggers
+
+Escalate when:
+
+* requirements become unclear
+* scope expands
+* architecture must change
+* tests repeatedly fail
+* the model loops or loses the plan
+* security or data-loss risk appears
+* hidden regressions are likely
+* UI quality falls below the reference
+
+Do not escalate mechanically. Move directly to Sol when the problem is judgment or ambiguity rather than execution capacity.
+
+## Model and execution routes
+
+```yaml
+routes:
+  luna:
+    model: oauth-router/gpt-5.6-luna
+  sol:
+    model: oauth-router/gpt-5.6-sol
+  terra:
+    model: oauth-router/gpt-5.6-terra
+  visual_exploration:
+    execution: antigravity-cli
+    model_intent: Gemini 3.5 Flash
+```
+
+Reasoning-effort labels such as Low, Medium, High, and Max are routing intent and remain part of this policy.
+
+## Mental model
+
+```text
+Sol Low      = intelligent default
+Sol Medium   = serious judgment and architecture
+Sol High     = senior reviewer and debugger
+Sol Max      = rare critical escalation
+
+Terra High   = default serious coder
+Terra Max    = long-horizon implementation engine
+
+Luna Medium  = small explicit execution
+Luna High    = parallel and bounded execution
+
+GPT-5.5      = specialist fallback
+Gemini Flash = visual and multimodal exploration through Antigravity CLI
+```