takomi 2.1.45 → 2.5.1

package/.pi/README.md

@@ -33,7 +33,7 @@ Inside Pi, use:
 - `/takomi design [prompt]` to run UI/UX design against the agreed project direction
 - `/takomi build [prompt]` to implement while cross-checking against approved UI/design artifacts
 - `/takomi plan [title]` to create a Genesis-first orchestration session that can expand through Design and Build
-- `/takomi mode direct`, `/takomi mode orchestrate`, or `/takomi mode review` to choose the session operating mode
+- `/takomi mode idle|code|review|orchestrate` to choose the main-agent mode; Genesis, Design, and Build remain separate lifecycle stages
 - `/takomi gate auto` to continue approved plans automatically and explicitly authorize project-local agents for this session
 - `/takomi gate review` (or `/takomi gate manual`) to return to the user after each task with results and verification guidance and revoke that authorization
 - `/takomi subagents on` or `/takomi subagents off` to allow or disable delegated subagents
@@ -100,12 +100,12 @@ So when working on packaging, agents should distinguish between:
 - Design stage includes a Gemini-oriented hint for model selection.
 - Build is treated as a workflow/stage, not as a separate specialist agent.
 - A fresh orchestration session starts with a Genesis foundation task, then expands Design and Build only when the scope justifies it.
-- The main execution roles remain things like `orchestrator`, `coder`, `designer`, `architect`, and `reviewer`.
+- The only public Takomi personas are `architect`, `designer`, `coder`, `worker`, `reviewer`, and `orchestrator`. Overlapping upstream built-ins remain hidden behind the execution engine.
 - Agent discovery prefers `project/.pi/agents/`, also supports legacy `project/.agents/`, and falls back to Pi's configured user agent directory so new projects can reuse the global Takomi agent pack without hard-coding `~/.pi` assumptions.
 - Orchestrator sessions run in hybrid mode:
   - human-readable docs live under `docs/tasks/orchestrator-sessions/<sessionId>/`
   - machine state lives under `.pi/takomi/orchestrator/<sessionId>.json`
-- Task packets can carry `workflow`, `skills`, `preferredModel`, `fallbackModels`, `preferredThinking`, `executionHint`, `conversationId`, and `checklist` metadata.
+- Task packets use canonical persona names and can carry `workflow`, `skills`, confirmed `preferredModel`, explicit `fallbackModels`, `requiredCapabilities`, `preferredThinking`, `executionHint`, `conversationId`, and `checklist` metadata.
 - Direct `takomi_subagent` calls build a `TakomiDelegationPlan` before launch. In auto mode the plan launches immediately; in manual mode the plan is returned for review until `confirmLaunch=true` is supplied.
 - The subagent tool supports `conversationId`, so reviewed work can be sent back to the same agent for continuation instead of restarting from scratch.
 - The subagent tool supports Pi-style single, parallel `tasks`, sequential `chain`, explicit `context=fork|fresh`, `async=true`, and native read/control actions such as `action=list`, `action=status`, `action=doctor`, `action=interrupt`, and `action=resume`.
@@ -119,9 +119,9 @@ So when working on packaging, agents should distinguish between:
 - Use Pi's native result expansion, `Alt+T`, or `/takomi subagents expand` to inspect detailed subagent output.
 - Takomi still tracks active runs internally for status and review continuity, but board synchronization is explicit: run with `takomi_subagent`, then update the board.
 - `takomi-context-manager` reduces prompt bloat by replacing the always-on skill description dump with a names-only Skill Index plus progressive `skill_manifest`/`skill_load` tools.
-- `takomi-context-manager` treats `/takomi routing` as the source of truth for model-routing policy via `.pi/settings.json -> takomi.modelRoutingPolicyFile`.
+- `model-routing.md` is advisory model-facing guidance. Executable provider allowlists and persona defaults live only under `takomi.routing` in global/project settings.
 - `takomi-context-manager` gates `takomi_subagent` when model-routing context has not been loaded, provides the routing policy, and tells the agent to retry.
-- `takomi-context-manager` can correct safe wrong-provider model requests, block or pause on policy violations, and ask the user whether to retry with an approved model or stop.
+- `takomi-context-manager` never performs provider-family substitution. It blocks unapproved exact IDs and changes models only after explicit user selection.
 - `takomi-context-manager` detects known duplicate global/project Takomi extension paths in `context_report` to help diagnose tool registration conflicts.
 - `context_report` restores context-manager snapshots and Pi tool-result history after reload/restart and explicitly labels gaps; it is not a replacement for Pi's Alt-C token/session stats.
 - `context_report` defaults to compact `mode: "summary"`; use `mode: "verbose"` for full diagnostics or `mode: "problems"` for attention-only output. `verbose: true` remains a compatibility alias. `/context-report` exposes `summary`, `verbose`, and `problems` as slash-command argument completions.

package/.pi/agents/architect.md

@@ -1,7 +1,7 @@
 ---
 name: architect
 description: Gather requirements, design architecture, and create implementation-ready plans.
-tools: read,bash,grep,find,ls
+tools: read,bash,write,grep,find,ls
 ---
 You are the Takomi Architect.
 
@@ -46,7 +46,7 @@ Produce implementation-ready structure when relevant:
 
 This is technical planning, not the Takomi Design lifecycle stage. If the work is about visual systems, mockups, interaction flows, or UI/UX polish, route it to Design.
 
-Stay at architecture level; do not write product code.
+Stay at architecture level; do not write product code. You may create or replace planning Markdown artifacts when the task requires them.
 
 ## Phase 4: Planning
 Create a practical plan with:

package/.pi/agents/designer.md

@@ -1,7 +1,7 @@
 ---
 name: designer
 description: Translate requirements into build-ready UI, UX, visual systems, and interaction direction.
-tools: read,bash,grep,find,ls
+tools: read,bash,write,grep,find,ls
 ---
 You are the Takomi Design Specialist.
 
@@ -64,7 +64,7 @@ Report:
 - pages/components ready for implementation
 - open design risks or follow-up
 
-Update builder guidance when mockups should be treated as implementation source of truth.
+Update builder guidance when mockups should be treated as implementation source of truth. You may create or replace UI/UX Markdown artifacts when the task requires them.
 
 ## Anti-Patterns
 - do not stay vague or inspirational only

package/.pi/agents/worker.md

@@ -0,0 +1,32 @@
+---
+name: worker
+description: Execute write-capable non-coding tasks and produce repository artifacts with controlled scope.
+tools: read,bash,edit,write,grep,find,ls
+---
+You are the Takomi Worker.
+
+Your mode pattern is:
+READ -> UNDERSTAND -> EXECUTE -> VERIFY -> HANDOFF.
+
+## Role Scope
+- documentation and repository artifact creation
+- configuration and content updates
+- mechanical or operational tasks that do not require the Coder persona
+- execution of an approved, well-scoped direction
+
+Use Coder for application implementation, debugging, refactoring, and tests. Use Architect for requirements, architecture, and planning decisions. Use Designer for UI/UX work. Worker executes a clear non-coding task; it does not invent product or architecture decisions.
+
+## Working Rules
+- Read the task, relevant files, and project instructions before editing.
+- Make the smallest complete change within scope.
+- Create or modify the requested artifacts directly.
+- Escalate missing product or architecture decisions instead of guessing.
+- Verify outputs with the strongest practical checks.
+- Do not expand scope or perform unrelated cleanup.
+
+## Handoff
+Report:
+- artifacts created or changed
+- validation performed
+- anything left incomplete
+- decisions still needed

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

@@ -1,115 +1,27 @@
-import { readFile } from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { ContextManagerState } from "./state";
 import { recordBlocked } from "./state";
-import { resolveTakomiRoutingPolicy } from "../takomi-runtime/routing-policy";
-import { approvedModelEquivalent, isTakomiModelApproved } from "../takomi-runtime/model-routing-defaults";
+import { isTakomiModelApproved, loadTakomiModelRoutingSnapshot } from "../takomi-runtime/model-routing-defaults";
 import { persistReportSnapshot } from "./session-state";
 import { sanitizePresentation } from "./tool-renderers";
 
-type Settings = {
-  takomi?: { modelRoutingPolicyFile?: string };
-  subagents?: { agentOverrides?: Record<string, unknown> };
-};
-
 type ModelPolicySnapshot = {
   approvedModels: string[];
   preferredModels: string[];
   sourceFiles: string[];
+  policyConflicts?: string[];
 };
 
-function asRecord(value: unknown): Record<string, unknown> {
-  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
-}
-
-async function readSettingsFile(filePath: string): Promise<Settings> {
-  try {
-    return JSON.parse(await readFile(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);
+async function loadSnapshot(cwd: string): Promise<ModelPolicySnapshot> {
+  const snapshot = await loadTakomiModelRoutingSnapshot(cwd);
   return {
-    ...globalSettings,
-    ...projectSettings,
-    takomi: { ...(globalSettings.takomi ?? {}), ...(projectSettings.takomi ?? {}) },
-    subagents: {
-      ...(globalSettings.subagents ?? {}),
-      ...(projectSettings.subagents ?? {}),
-      agentOverrides: { ...globalOverrides, ...projectOverrides },
-    },
+    approvedModels: snapshot.approvedModels,
+    preferredModels: snapshot.preferredModels,
+    sourceFiles: snapshot.sourceFiles,
+    policyConflicts: snapshot.policyConflicts,
   };
 }
 
-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 modelFamily(model: string): string {
-  return model.split("/").at(-1)?.toLowerCase() ?? model.toLowerCase();
-}
-
-function unique(values: string[]): string[] {
-  return [...new Set(values.filter(Boolean))];
-}
-
-function collectModelsFromSettings(settings: Settings): string[] {
-  const overrides = asRecord(settings.subagents?.agentOverrides);
-  const models: string[] = [];
-  for (const value of Object.values(overrides)) {
-    const record = asRecord(value);
-    if (typeof record.model === "string") models.push(record.model);
-    if (Array.isArray(record.fallbackModels)) {
-      for (const fallback of record.fallbackModels) if (typeof fallback === "string") models.push(fallback.split(":")[0]);
-    }
-  }
-  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[] {
-  // Providerless names such as "GPT-5.5" are intent labels unless the policy
-  // declares a preferred provider/router header.
-  const explicit = (text.match(/[a-z0-9-]+\/[a-z0-9._-]+/gi) ?? []).filter(isModelLike);
-  const preferredProvider = extractPreferredProvider(text);
-  const inferred: string[] = [];
-  if (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]);
-}
-
-async function loadSnapshot(cwd: string): Promise<ModelPolicySnapshot> {
-  const settings = await readSettings(cwd);
-  const settingsModels = collectModelsFromSettings(settings);
-  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 };
-}
-
 function collectRequestedModelRefs(input: unknown): Array<{ holder: Record<string, unknown>; key: string; value: string; index?: number }> {
   const refs: Array<{ holder: Record<string, unknown>; key: string; value: string; index?: number }> = [];
   function visit(value: unknown): void {
@@ -204,18 +116,18 @@ export function installModelPolicyGate(pi: ExtensionAPI, state: ContextManagerSt
     if (event.toolName !== "takomi_subagent") return;
     const snapshot = await loadSnapshot(ctx.cwd);
     const approved = snapshot.approvedModels;
+    if (snapshot.policyConflicts?.length) {
+      const reason = ["Blocked by conflicting Takomi routing guidance and executable settings.", "", ...snapshot.policyConflicts.map((item) => `- ${item}`)].join("\n");
+      recordBlocked(state, event.toolName, reason);
+      persistReportSnapshot(pi, state, "model-policy-conflict");
+      return { block: true, reason };
+    }
     if (approved.length === 0) return;
 
     const refs = collectRequestedModelRefs(event.input);
     const corrections: Array<{ from: string; to: string; recovery?: string }> = [];
     for (const ref of refs) {
       if (isTakomiModelApproved(ref.value, approved)) continue;
-      const equivalent = approvedModelEquivalent(ref.value, approved);
-      if (equivalent) {
-        setModelRef(ref, equivalent);
-        corrections.push({ from: ref.value, to: equivalent });
-        continue;
-      }
       const recovery = await askForInvalidModelRecovery(ctx, ref.value, approved);
       if (recovery.action === "retry") {
         setModelRef(ref, recovery.model);
@@ -244,7 +156,7 @@ export function installModelPolicyGate(pi: ExtensionAPI, state: ContextManagerSt
         timestamp,
       })));
       persistReportSnapshot(pi, state, "model-policy-correction");
-      const notification = `Takomi context manager corrected subagent model routing:\n- ${corrections.map((correction) => `${sanitizePresentation(correction.from)} -> ${sanitizePresentation(correction.to)}${correction.recovery ? ` (${sanitizePresentation(correction.recovery)})` : ""}`).join("\n- ")}\n\nBe careful to follow /takomi routing policy next time.`;
+      const notification = `Takomi model routing changed only after explicit user selection:\n- ${corrections.map((correction) => `${sanitizePresentation(correction.from)} -> ${sanitizePresentation(correction.to)}${correction.recovery ? ` (${sanitizePresentation(correction.recovery)})` : ""}`).join("\n- ")}`;
       ctx.ui.notify(notification, "warning");
     }
   });

package/.pi/extensions/takomi-runtime/command-text.ts

@@ -14,7 +14,7 @@ const ROOT_COMPLETIONS: TakomiCompletion[] = [
   { value: "design", label: "design", description: "Run UI/UX design from approved scope" },
   { value: "build", label: "build", description: "Implement against the agreed UI" },
   { value: "plan", label: "plan", description: "Create or update the orchestration plan" },
-  { value: "mode", label: "mode", description: "Set direct, orchestrate, or review mode" },
+  { value: "mode", label: "mode", description: "Set idle, code, review, or orchestrate main-agent mode" },
   { value: "gate", label: "gate", description: "Set auto or review-gated execution" },
   { value: "subagents", label: "subagents", description: "Control subagent usage and view" },
   { value: "stats", label: "stats", description: "Show token, model, project, session, tool, and subagent usage stats" },
@@ -23,9 +23,10 @@ const ROOT_COMPLETIONS: TakomiCompletion[] = [
 
 const SUBCOMMAND_COMPLETIONS: Record<string, TakomiCompletion[]> = {
   mode: [
-    { value: "direct", label: "direct", description: "Handle work directly unless delegation is explicit" },
-    { value: "orchestrate", label: "orchestrate", description: "Plan and delegate broad work" },
+    { value: "idle", label: "idle", description: "Clear active Takomi main-agent behavior" },
+    { value: "code", label: "code", description: "Implement directly in the main session" },
     { value: "review", label: "review", description: "Inspect outputs and route fixes" },
+    { value: "orchestrate", label: "orchestrate", description: "Coordinate lifecycle work and specialist personas" },
   ],
   gate: [
     { value: "review", label: "review", description: "Return to the user after each task" },
@@ -94,7 +95,7 @@ export function commandHelp(): string {
     "/takomi design [prompt]",
     "/takomi build [prompt]",
     "/takomi plan [title]",
-    "/takomi mode <direct|orchestrate|review>",
+    "/takomi mode <idle|code|review|orchestrate>",
     "/takomi gate <auto|review>",
     "/takomi subagents <list|on|off|status>",
     "/takomi stats [overview|daily|models|projects|projects-full|sessions|sessions-full|tasks|tasks-full|tools|subagents|sources] [since 7d]",

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

@@ -55,28 +55,30 @@ export function registerTakomiCommands(pi: ExtensionAPI, options: RegisterTakomi
   }
 
   async function handleMode(ctx: ExtensionCommandContext, mode?: string): Promise<void> {
-    if (mode !== "direct" && mode !== "orchestrate" && mode !== "review") {
-      ctx.ui.notify("Usage: /takomi mode <direct|orchestrate|review>", "warning");
+    if (mode === "direct") mode = "code";
+    if (mode !== "idle" && mode !== "code" && mode !== "orchestrate" && mode !== "review") {
+      ctx.ui.notify("Usage: /takomi mode <idle|code|review|orchestrate>", "warning");
       return;
     }
-    const hasGenesis = await options.hasGenesisArtifacts(ctx.cwd);
     await options.updateState(ctx, () => {
       const state = options.getState();
       state.enabled = true;
-      if (mode === "direct") {
+      if (mode === "idle") {
         state.autoOrch = false;
         state.planMode = false;
         state.role = "general";
-        state.stage = undefined;
-        state.workflow = undefined;
         state.modeSource = "idle";
         state.modeReason = undefined;
+      } else if (mode === "code") {
+        state.autoOrch = false;
+        state.planMode = false;
+        state.role = "coder";
+        state.modeSource = "manual";
+        state.modeReason = "/takomi mode code";
       } else if (mode === "orchestrate") {
         state.autoOrch = true;
         state.planMode = true;
         state.role = "orchestrator";
-        state.stage = hasGenesis ? "build" : "genesis";
-        state.workflow = hasGenesis ? "vibe-build" : "vibe-genesis";
         state.modeSource = "manual";
         state.modeReason = "/takomi mode orchestrate";
       } else {
@@ -84,9 +86,7 @@ export function registerTakomiCommands(pi: ExtensionAPI, options: RegisterTakomi
         state.planMode = true;
         state.launchMode = "manual";
         options.recordUserGateAutoProvenance(false);
-        state.role = "review";
-        state.stage = undefined;
-        state.workflow = undefined;
+        state.role = "reviewer";
         state.modeSource = "manual";
         state.modeReason = "/takomi mode review";
       }
@@ -201,14 +201,14 @@ export function registerTakomiCommands(pi: ExtensionAPI, options: RegisterTakomi
         ? `WARNING: This input is much shorter than the active policy (${preview.policy.length} vs ${activePolicy.text.length} characters). It will replace the file, not merge into it. If the user referred to a full source file or prior policy, inspect and use that complete text instead.`
         : "This input replaces the selected policy file exactly; it is not merged with the active policy.";
       const reviewPrompt = [
-        "Review this Takomi routing policy extraction before it is saved.",
+        "Review this advisory Takomi model-routing guidance before it is saved.",
         "",
         "Rules:",
         "- Do not invent providers or model IDs not grounded in the policy.",
-        "- Providerless names are valid routing intent. Require a provider only when writing an executable model override.",
-        "- Check the available Pi model registry below before asking the user whether a named model exists or what its exact ID is.",
-        "- Conditional task-shape routes do not need to be forced into role-wide defaults or agentOverrides.",
-        "- Valid role-wide Takomi overrides are: general, orchestrator, architect, designer, coder, reviewer. Other headings may still be policy concepts or execution routes.",
+        "- Providerless names such as Sol, Terra, and Luna are valid advisory routing concepts.",
+        "- Do not infer executable providers, allowlists, fallbacks, or persona defaults from this prose.",
+        "- Executable changes belong in takomi.routing settings through takomi_config_routing.",
+        "- Canonical Takomi personas are: architect, designer, coder, worker, reviewer, orchestrator.",
         "- Preserve the user's full authored policy. If this looks like a summary/excerpt and a richer referenced source exists, inspect that source and apply the complete intended text instead of overwriting it with the excerpt.",
         "- If the extraction is correct and safe, call takomi_apply_routing_policy with the complete intended policyText and scope below.",
         "- Ask only for unresolved provider/account choices or genuine policy ambiguity; do not ask for facts available from the registry or files.",
@@ -227,7 +227,7 @@ export function registerTakomiCommands(pi: ExtensionAPI, options: RegisterTakomi
         "",
         `Tool call to apply if safe: takomi_apply_routing_policy({ scope: ${JSON.stringify(scope)}, policyText: <original policy text> })`,
       ].join("\n");
-      ctx.ui.notify("Takomi routing extraction prepared. Sending it to the active model for review before saving.", "info");
+      ctx.ui.notify("Takomi routing guidance prepared. Sending it to the active model for preservation review before saving.", "info");
       pi.sendUserMessage(reviewPrompt);
     } catch (error) {
       ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");