takomi 2.1.33 → 2.1.34

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

@@ -35,9 +35,6 @@ const SUBCOMMAND_COMPLETIONS: Record<string, TakomiCompletion[]> = {
     { value: "status", label: "status", description: "Show active subagents" },
     { value: "on", label: "on", description: "Allow subagent delegation" },
     { value: "off", label: "off", description: "Disable subagent delegation" },
-    { value: "expand", label: "expand", description: "Expand native tool results" },
-    { value: "collapse", label: "collapse", description: "Collapse native tool results" },
-    { value: "toggle", label: "toggle", description: "Toggle native tool result expansion" },
   ],
   stats: [
     { value: "overview", label: "overview", description: "Show the full profile-card dashboard" },
@@ -98,7 +95,7 @@ export function commandHelp(): string {
     "/takomi plan [title]",
     "/takomi mode <direct|orchestrate|review>",
     "/takomi gate <auto|review>",
-    "/takomi subagents <on|off|status|expand|collapse|toggle>",
+    "/takomi subagents <on|off|status>",
     "/takomi stats [overview|daily|models|projects|projects-full|sessions|sessions-full|tasks|tasks-full|tools|subagents|sources] [since 7d]",
     "/takomi routing [show|where]",
     "/takomi routing <policy text>              # updates global policy",
@@ -134,6 +131,7 @@ export function statusText(state: TakomiRuntimeCommandState, subagentController:
   return [
     `Takomi: ${state.enabled ? "on" : "off"}`,
     `Mode: ${state.role}`,
+    `Source: ${state.modeSource ?? "idle"}${state.modeReason ? ` (${state.modeReason})` : ""}`,
     `Stage: ${state.stage ?? "-"}`,
     `Workflow: ${state.workflow ?? "-"}`,
     `Plan bias: ${state.planMode ? "on" : "off"}`,

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

@@ -20,6 +20,8 @@ export type TakomiRuntimeCommandState = {
   workflow?: TakomiWorkflowId;
   activeSessionId?: string;
   subagentsEnabled: boolean;
+  modeSource?: "idle" | "manual" | "model" | "board";
+  modeReason?: string;
 };
 
 type RegisterTakomiCommandOptions = {
@@ -36,6 +38,8 @@ export function registerTakomiCommands(pi: ExtensionAPI, options: RegisterTakomi
   async function handleStage(ctx: ExtensionCommandContext, stage: VibeLifecycleStage, prompt?: string): Promise<void> {
     await options.updateState(ctx, () => {
       options.getState().enabled = true;
+      options.getState().modeSource = "manual";
+      options.getState().modeReason = `/${stage}`;
       options.setStageAndWorkflow(stage, { preserveRole: stage === "genesis" && options.getState().role === "orchestrator" });
       options.getState().planMode = stage !== "build";
     }, workflowPrompt(stage, prompt));
@@ -54,17 +58,27 @@ export function registerTakomiCommands(pi: ExtensionAPI, options: RegisterTakomi
         state.autoOrch = false;
         state.planMode = false;
         state.role = "general";
+        state.stage = undefined;
+        state.workflow = undefined;
+        state.modeSource = "idle";
+        state.modeReason = undefined;
       } 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 {
         state.autoOrch = false;
         state.planMode = true;
         state.launchMode = "manual";
         state.role = "review";
+        state.stage = undefined;
+        state.workflow = undefined;
+        state.modeSource = "manual";
+        state.modeReason = "/takomi mode review";
       }
     }, () => `Takomi mode set to ${mode}`);
   }
@@ -198,27 +212,7 @@ export function registerTakomiCommands(pi: ExtensionAPI, options: RegisterTakomi
       ctx.ui.notify(statusText(options.getState(), controller), controller.hasRuns() ? "info" : "warning");
       return;
     }
-    if (action === "expand" || action === "fullscreen") {
-      ctx.ui.setToolsExpanded(true);
-      ctx.ui.notify("Expanded native tool results for Takomi subagent output.", "info");
-      return;
-    }
-    if (action === "collapse") {
-      ctx.ui.setToolsExpanded(false);
-      ctx.ui.notify("Collapsed native tool results.", "info");
-      return;
-    }
-    if (action === "toggle") {
-      const expanded = !ctx.ui.getToolsExpanded();
-      ctx.ui.setToolsExpanded(expanded);
-      ctx.ui.notify(`${expanded ? "Expanded" : "Collapsed"} native tool results.`, "info");
-      return;
-    }
-    if (action === "next" || action === "prev") {
-      ctx.ui.notify("Takomi now uses Pi's native inline result UI. Subagent navigation is handled by the transcript/tool results.", "info");
-      return;
-    }
-    ctx.ui.notify("Usage: /takomi subagents <on|off|status|expand|collapse|toggle>", "warning");
+    ctx.ui.notify("Usage: /takomi subagents <on|off|status>", "warning");
   }
 
   pi.registerCommand("takomi", {

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

@@ -58,6 +58,8 @@ import {
 } from "./profile";
 import { installTakomiRoutingPolicy, previewTakomiRoutingPolicy, renderRoutingPolicyPreview, resolveTakomiRoutingPolicy } from "./routing-policy";
 
+type TakomiModeSource = "idle" | "manual" | "model" | "board";
+
 type TakomiState = {
   enabled: boolean;
   autoOrch: boolean;
@@ -69,15 +71,18 @@ type TakomiState = {
   activeSessionId?: string;
   subagentsEnabled: boolean;
   lastFullPromptKey?: string;
+  modeSource?: TakomiModeSource;
+  modeReason?: string;
 };
 
 const DEFAULT_STATE: TakomiState = {
   enabled: true,
-  autoOrch: true,
+  autoOrch: false,
   launchMode: "auto",
   planMode: false,
   role: "general",
   subagentsEnabled: true,
+  modeSource: "idle",
 };
 
 const STATE_ENTRY = "takomi-runtime-state";
@@ -97,6 +102,8 @@ const ThinkingSchema = Type.Union([
   Type.Literal("xhigh"),
 ]);
 
+const TakomiModeSchema = StringEnum(["idle", "code", "orchestrate", "review", "genesis", "design", "build"] as const);
+
 function cloneState(state: TakomiState): TakomiState {
   return { ...state };
 }
@@ -111,6 +118,8 @@ function formatState(state: TakomiState): string {
     `launch=${state.launchMode}`,
     `plan=${state.planMode ? "on" : "off"}`,
     `subagents=${state.subagentsEnabled ? "on" : "off"}`,
+    `source=${state.modeSource ?? "idle"}`,
+    state.modeReason ? `reason=${state.modeReason}` : "",
     state.activeSessionId ? `session=${state.activeSessionId}` : "",
   ].filter(Boolean).join(" | ");
 }
@@ -766,6 +775,8 @@ export default function takomiRuntime(pi: ExtensionAPI) {
         state.stage = "genesis";
         state.workflow = "vibe-genesis";
         state.role = "orchestrator";
+        state.modeSource = "manual";
+        state.modeReason = "/takomi plan";
       });
       return `Takomi plan created session ${session.sessionId}\nMaster plan: ${paths.masterPlan}`;
     },
@@ -783,34 +794,82 @@ export default function takomiRuntime(pi: ExtensionAPI) {
     },
   });
 
-  pi.registerShortcut("alt+t", {
-    description: "Toggle native tool result expansion",
-    handler: async (ctx) => {
-      const expanded = !ctx.ui.getToolsExpanded();
-      ctx.ui.setToolsExpanded(expanded);
-      ctx.ui.notify(`${expanded ? "Expanded" : "Collapsed"} native tool results.`, "info");
-    },
-  });
 
-  pi.registerShortcut("alt+shift+t", {
-    description: "Expand native tool results",
-    handler: async (ctx) => {
-      ctx.ui.setToolsExpanded(true);
-      ctx.ui.notify("Expanded native tool results for Takomi subagent output.", "info");
-    },
-  });
+  async function applyTakomiMode(ctx: ExtensionContext, mode: string, source: TakomiModeSource, reason?: string): Promise<string> {
+    const hasGenesis = await hasGenesisArtifacts(ctx.cwd);
+    state.enabled = true;
+    state.modeSource = source;
+    state.modeReason = reason?.trim() || undefined;
+
+    switch (mode) {
+      case "idle":
+        state.modeSource = "idle";
+        state.modeReason = undefined;
+        state.autoOrch = false;
+        state.planMode = false;
+        state.role = "general";
+        state.stage = undefined;
+        state.workflow = undefined;
+        break;
+      case "code":
+        state.autoOrch = false;
+        state.planMode = false;
+        state.role = "code";
+        state.stage = undefined;
+        state.workflow = undefined;
+        break;
+      case "review":
+        state.autoOrch = false;
+        state.planMode = true;
+        state.launchMode = "manual";
+        state.role = "review";
+        state.stage = undefined;
+        state.workflow = undefined;
+        break;
+      case "orchestrate":
+        state.autoOrch = true;
+        state.planMode = true;
+        state.role = "orchestrator";
+        state.stage = hasGenesis ? "build" : "genesis";
+        state.workflow = hasGenesis ? "vibe-build" : "vibe-genesis";
+        break;
+      case "genesis":
+      case "design":
+      case "build":
+        setStageAndWorkflow(state, mode);
+        state.autoOrch = mode === "build";
+        state.planMode = mode !== "build";
+        break;
+    }
 
-  pi.registerShortcut("alt+n", {
-    description: "Show native subagent navigation hint",
-    handler: async (ctx) => {
-      ctx.ui.notify("Native subagent results are shown inline by Pi; use the transcript/tool expansion instead of Takomi focus cycling.", "info");
-    },
-  });
+    persistState();
+    syncContextPanelState();
+    await refreshUi(ctx, state);
+    const label = state.modeSource === "idle" ? "idle" : `${state.modeSource}:${state.stage ?? state.role}`;
+    return `Takomi mode set to ${label}${state.modeReason ? ` (${state.modeReason})` : ""}.`;
+  }
 
-  pi.registerShortcut("alt+p", {
-    description: "Show native subagent navigation hint",
-    handler: async (ctx) => {
-      ctx.ui.notify("Native subagent results are shown inline by Pi; use the transcript/tool expansion instead of Takomi focus cycling.", "info");
+  pi.registerTool({
+    name: "takomi_mode",
+    label: "Takomi Mode",
+    description: "Set or clear the visible Takomi runtime mode after the active model decides a task benefits from code, review, lifecycle, or orchestration handling.",
+    promptSnippet: "Optional: call takomi_mode when you decide the current request should visibly enter Takomi code/review/orchestration/lifecycle mode. Do not call it for normal creative/general conversation. Use mode=idle to clear Takomi mode.",
+    promptGuidelines: [
+      "Let the user's request drive the choice; do not switch modes just because a vague word like code/review/build appears alone.",
+      "Prefer mode=code for direct coding in the current chat, mode=orchestrate only for broad/multi-step durable work, and mode=review for critique/audit/QA.",
+      "Use mode=idle when the user asks normal non-coding/non-Takomi questions and Takomi should get out of the way.",
+    ],
+    parameters: Type.Object({
+      mode: TakomiModeSchema,
+      reason: Type.Optional(Type.String({ description: "Short human-readable reason for the switch" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const text = await applyTakomiMode(ctx, params.mode, "model", params.reason);
+      ctx.ui.notify(text, "info");
+      return {
+        content: [{ type: "text", text }],
+        details: { mode: params.mode, source: state.modeSource, reason: state.modeReason, role: state.role, stage: state.stage, workflow: state.workflow },
+      };
     },
   });
 
@@ -1007,6 +1066,12 @@ ${stateJson}`
           }
         }
         sessionState.tasks[idx] = nextTask;
+        state.activeSessionId = params.sessionId;
+        state.modeSource = state.modeSource === "idle" ? "board" : state.modeSource;
+        state.modeReason = state.modeReason ?? "board task update";
+        persistState();
+        syncContextPanelState();
+        await refreshUi(ctx, state);
         const nextState = buildSessionState(
           sessionState.sessionId,
           sessionState.title,
@@ -1062,8 +1127,11 @@ ${stateJson}`
           }
         }
         state.activeSessionId = nextState.sessionId;
+        state.modeSource = "board";
+        state.modeReason = `expanded ${params.stage} stage`;
         persistState();
         syncContextPanelState();
+        await refreshUi(ctx, state);
 
         return {
           content: [{ type: "text", text: `Expanded ${params.stage} stage in session ${nextState.sessionId}.\n\nDocs: ${paths.root}\nState: ${paths.stateFile}\n\n${buildTaskRows(nextState.tasks)}` }],
@@ -1104,8 +1172,11 @@ ${stateJson}`
       state.role = "orchestrator";
       state.stage = nextState.lifecycle.genesis.status === "completed" ? "build" : "genesis";
       state.workflow = state.stage === "genesis" ? "vibe-genesis" : "vibe-build";
+      state.modeSource = "board";
+      state.modeReason = "orchestrator session";
       persistState();
       syncContextPanelState();
+      await refreshUi(ctx, state);
 
       return {
         content: [{ type: "text", text: `Created Takomi orchestrator session ${nextState.sessionId} in hybrid mode\n\nDocs: ${paths.root}\nState: ${paths.stateFile}\n\n${buildTaskRows(nextState.tasks) || "No tasks provided."}` }],
@@ -1152,11 +1223,15 @@ ${stateJson}`
 
     if (lowered === "use takomi") {
       state.enabled = true;
+      state.modeSource = "manual";
+      state.modeReason = "explicit user request";
       return { action: "transform", text: "Use the Takomi runtime, identify the correct lifecycle stage, and proceed accordingly." };
     }
 
     if (lowered.startsWith("use takomi ")) {
       state.enabled = true;
+      state.modeSource = "manual";
+      state.modeReason = "explicit user request";
       const route = decideRoute(text.slice("use takomi ".length));
       if (route.stage) setStageAndWorkflow(state, route.stage, { preserveRole: state.role === "orchestrator" && route.stage === "genesis" });
       else if (route.role !== "general") state.role = route.role;
@@ -1164,14 +1239,20 @@ ${stateJson}`
     }
 
     if (/\bvibe genesis\b/i.test(text)) {
+      state.modeSource = "manual";
+      state.modeReason = "vibe genesis";
       setStageAndWorkflow(state, "genesis", { preserveRole: state.role === "orchestrator" });
       return { action: "transform", text };
     }
     if (/\bvibe design\b/i.test(text)) {
+      state.modeSource = "manual";
+      state.modeReason = "vibe design";
       setStageAndWorkflow(state, "design");
       return { action: "transform", text };
     }
     if (/\bvibe build\b/i.test(text)) {
+      state.modeSource = "manual";
+      state.modeReason = "vibe build";
       setStageAndWorkflow(state, "build");
       return { action: "transform", text };
     }
@@ -1180,43 +1261,36 @@ ${stateJson}`
   });
 
   pi.on("before_agent_start", async (event, ctx) => {
-    if (!state.enabled) return;
+    if (!state.enabled || (state.modeSource ?? "idle") === "idle") return;
 
     let effectiveState = cloneState(state);
     const runtimeCwd = ctx.cwd;
     const genesisExists = await hasGenesisArtifacts(runtimeCwd);
     const route = decideRoute(event.prompt);
-    if (state.autoOrch && shouldAutoRoute(event.prompt)) {
-      effectiveState.role = "orchestrator";
-      effectiveState.stage = genesisExists ? "build" : "genesis";
-      effectiveState.workflow = genesisExists ? "vibe-build" : "vibe-genesis";
-    }
-
-    const shouldHonorRoute = route.stage || route.role !== "general" || route.sessionRecommendation !== "none";
-    if (shouldHonorRoute && route.stage) {
-      effectiveState.stage = route.stage;
-      effectiveState.workflow = route.workflow;
-      effectiveState.role = effectiveState.role === "orchestrator" && route.stage === "genesis" ? "orchestrator" : route.role;
-    } else if (shouldHonorRoute && route.role !== "general") {
-      effectiveState.role = route.role;
-    }
-
-    let routingNote = route.reason;
+    let routingNote = state.modeReason
+      ? `Takomi mode selected by ${state.modeSource}: ${state.modeReason}.`
+      : `Takomi mode selected by ${state.modeSource ?? "runtime"}.`;
     const explicitLifecycleWaiver = /skip genesis|waive genesis|genesis complete|already have (a )?(prd|requirements)|design complete|jump straight to build/i.test(event.prompt);
-    const orchestrationActive = effectiveState.role === "orchestrator" || route.executionMode === "orchestrate";
+    const orchestrationActive = effectiveState.role === "orchestrator";
     if (!genesisExists && orchestrationActive && !explicitLifecycleWaiver) {
       effectiveState.stage = "genesis";
       effectiveState.workflow = "vibe-genesis";
       routingNote = "Blank project detected; orchestrator remains in control and must honor Genesis → Design → Build.";
     }
+    if (effectiveState.stage !== state.stage || effectiveState.workflow !== state.workflow || effectiveState.role !== state.role) {
+      state.role = effectiveState.role;
+      state.stage = effectiveState.stage;
+      state.workflow = effectiveState.workflow;
+    }
 
     const promptKey = `${effectiveState.role}:${effectiveState.workflow ?? "none"}`;
     const includeFullWorkflow = Boolean(effectiveState.workflow && effectiveState.lastFullPromptKey !== promptKey);
     if (includeFullWorkflow) {
       state.lastFullPromptKey = promptKey;
-      persistState();
-      syncContextPanelState();
     }
+    persistState();
+    syncContextPanelState();
+    await refreshUi(ctx, state);
 
     const routingPolicy = await resolveTakomiRoutingPolicy(runtimeCwd);
     const optionalFeatureContext = (() => {
@@ -1263,14 +1337,14 @@ ${stateJson}`
       `Execution mode: ${route.executionMode}. Session recommendation: ${route.sessionRecommendation}.`,
       `Takomi execution gate: ${effectiveState.launchMode === "manual" ? "review" : "auto"}. In review gate mode, show the delegation plan before launching and return to the user after each task with results, verification guidance, and the recommended next step.`,
       !effectiveState.subagentsEnabled ? "Takomi subagents are disabled for this session. Do not call takomi_subagent or subagent until the user enables subagents." : "",
-      !genesisExists ? "Project foundation is missing or incomplete. Do not skip Genesis unless the user explicitly waives it." : "",
-      "Takomi is the default orchestration mindset here. Do not wait for the literal phrase 'use Takomi' before applying lifecycle judgment.",
-      "Task fan-out is flexible. Do not force exactly three tasks; decompose Genesis, Design, and Build work to fit the actual scope.",
-      "A new orchestration session should usually begin with one Genesis foundation task that creates or updates the required markdown artifacts, then expand later stages only when the scope justifies it.",
-      "If a follow-up request is small, one-shot it. If it is multi-part or large, create or expand an orchestration session instead of pretending it is a single task.",
+      orchestrationActive && !genesisExists ? "Project foundation is missing or incomplete. Do not skip Genesis unless the user explicitly waives it." : "",
+      "Do not escalate to orchestration or review just because this is coding-related; stay in the selected Takomi mode unless the user asks or a durable board/session is genuinely needed.",
+      orchestrationActive ? "Task fan-out is flexible. Do not force exactly three tasks; decompose Genesis, Design, and Build work to fit the actual scope." : "",
+      orchestrationActive ? "A new orchestration session should usually begin with one Genesis foundation task that creates or updates the required markdown artifacts, then expand later stages only when the scope justifies it." : "",
+      orchestrationActive ? "If a follow-up request is small, one-shot it. If it is multi-part or large, create or expand an orchestration session instead of pretending it is a single task." : "",
       "Before any Takomi subagent dispatch or model override, use the injected Pi model-registry context and project routing policy. Prefer provider-qualified model IDs. Do not run `pi --list-models` unless the registry context is missing or the user asks for a visible diagnostic.",
-      "When useful, state the current Takomi stage and the recommended next stage.",
-      effectiveState.stage === "build"
+      "When useful, state the current Takomi mode/stage and the recommended next step.",
+      orchestrationActive && effectiveState.stage === "build"
         ? "For build orchestration, use takomi_subagent to dispatch work to specialist subagents, then record the result on takomi_board; reuse the same conversation id when sending fixes back to the agent."
         : "",
     ].filter(Boolean);

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

@@ -27,6 +27,8 @@ export type RuntimeHudState = {
   activeSessionId?: string;
   launchMode?: string;
   subagentsEnabled?: boolean;
+  modeSource?: "idle" | "manual" | "model" | "board";
+  modeReason?: string;
 };
 
 type Tone = "accent" | "warning" | "success" | "error" | "muted" | "dim" | "thinkingMinimal";
@@ -70,24 +72,30 @@ function badge(theme: Theme, label: string, tone: Tone): string {
 }
 
 export function renderRuntimeStatus(theme: Theme, state: RuntimeHudState): string {
+  const source = state.modeSource ?? "idle";
+  if (!state.enabled) return [theme.fg("accent", "Takomi"), theme.fg("dim", "off")].join(" ");
+  if (source === "idle") return [theme.fg("accent", "Takomi"), theme.fg("dim", "idle")].join(" ");
+
   const primary = state.stage ?? state.role;
   const stageBadge = badge(theme, primary, stageTone(state.stage));
-  const auto = state.autoOrch ? theme.fg("accent", "auto") : theme.fg("dim", "manual");
-  const gate = state.launchMode === "manual" ? theme.fg("warning", "review-gate") : theme.fg("accent", "auto-gate");
+  const sourceLabel = source === "manual" ? theme.fg("warning", "manual") : theme.fg("success", source);
+  const role = state.stage && state.role !== state.stage ? theme.fg("dim", state.role) : "";
   const plan = state.planMode ? theme.fg("warning", "plan") : theme.fg("dim", "direct");
-  const subagents = state.subagentsEnabled === false ? theme.fg("error", "subagents:off") : theme.fg("dim", "subagents:on");
-  return [theme.fg("accent", "Takomi"), stageBadge, theme.fg("dim", `role:${state.role}`), auto, gate, plan, subagents].join(" ");
+  const gate = state.launchMode === "manual" ? theme.fg("warning", "review-gate") : "";
+  const subagents = state.subagentsEnabled === false ? theme.fg("error", "subagents:off") : "";
+  return [theme.fg("accent", "Takomi"), sourceLabel, stageBadge, role, gate || plan, subagents].filter(Boolean).join(" ");
 }
 
 export function renderRuntimeWidget(theme: Theme, state: RuntimeHudState): string[] {
-  if (!state.enabled) return [];
+  if (!state.enabled || (state.modeSource ?? "idle") === "idle") return [];
   const primary = state.stage ?? state.role;
+  const sourceLabel = state.modeSource === "manual" ? theme.fg("warning", "manual") : theme.fg("success", state.modeSource ?? "model");
   const parts = [
     theme.fg("accent", "Takomi"),
+    sourceLabel,
     badge(theme, primary, stageTone(state.stage)),
-    theme.fg("dim", `role:${state.role}`),
-    state.autoOrch ? theme.fg("accent", "auto") : theme.fg("dim", "manual"),
-    state.launchMode === "manual" ? theme.fg("warning", "review-gate") : theme.fg("accent", "auto-gate"),
+    state.stage && state.role !== state.stage ? theme.fg("dim", `role:${state.role}`) : "",
+    state.launchMode === "manual" ? theme.fg("warning", "review-gate") : "",
     state.planMode ? theme.fg("warning", "plan") : theme.fg("dim", "direct"),
     state.subagentsEnabled === false ? theme.fg("error", "subagents:off") : theme.fg("dim", "subagents:on"),
     state.workflow ? theme.fg("dim", `wf:${state.workflow}`) : "",
@@ -115,7 +123,7 @@ export class TakomiFooterComponent implements Component {
     this.unsubscribeBranchChange();
   }
 
-  invalidate(): void {}
+  invalidate(): void { }
 
   render(width: number): string[] {
     const state = this.getState();
@@ -141,8 +149,7 @@ export class TakomiFooterComponent implements Component {
       .filter(([key]) => key !== "takomi-runtime")
       .map(([, value]) => value)
       .filter(Boolean);
-    const runtimeStatus = renderRuntimeStatus(this.theme, state);
-    const left = [runtimeStatus, ...extensionStatuses].join(this.theme.fg("dim", "  |  "));
+    const left = extensionStatuses.join(this.theme.fg("dim", "  |  "));
     const branch = this.footerData.getGitBranch();
     const rightText = [this.ctx.model?.id || "no-model", branch ? `git:${branch}` : ""].filter(Boolean).join(" | ");
     const right = this.theme.fg("dim", rightText);

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

@@ -44,6 +44,7 @@ const SubagentParameters = Type.Object({
   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" })),
   previewOnly: Type.Optional(Type.Boolean({ description: "Return the delegation plan without launching" })),
+  clarify: Type.Optional(Type.Boolean({ description: "Show the native pi-subagents TUI to preview/edit before execution. Especially useful for chains; requires an interactive Pi TUI." })),
   chain: Type.Optional(Type.Array(TaskSchema, { description: "Sequential chain of subagent tasks" })),
   agentScope: Type.Optional(Type.Union([Type.Literal("user"), Type.Literal("project"), Type.Literal("both")])),
   confirmProjectAgents: Type.Optional(Type.Boolean({ description: "Prompt before running project-local agents. Default: true." })),
@@ -59,6 +60,7 @@ function registerSubagentTool(pi: ExtensionAPI): void {
     promptGuidelines: [
       "Use this tool during orchestration when a specialist should handle a task.",
       "Use tasks for independent parallel work and chain for dependent handoffs with {previous}.",
+      "Set clarify=true when the user asks to preview/edit a subagent run in the native Pi TUI before launch.",
       "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. Use overrideUserBlock only after explicit user approval.",

package/.pi/extensions/takomi-subagents/native-render.ts

@@ -30,15 +30,37 @@ export function renderTakomiSubagentCall(params: TakomiSubagentToolParams, theme
   );
 }
 
+function resultText(result: ToolResult): string {
+  return typeof (result as any)?.content === "string"
+    ? (result as any).content
+    : Array.isArray((result as any)?.content)
+      ? (result as any).content.map((part: any) => part?.text ?? "").filter(Boolean).join("\n")
+      : JSON.stringify((result as any)?.details ?? {}, null, 2);
+}
+
+function summarizeCollapsedResult(text: string, status: string, theme: Theme): string {
+  const policyMatch = text.match(/Required policies:\n((?:- .+\n?)+)/);
+  const policies = policyMatch?.[1]
+    ?.split("\n")
+    .map((line) => line.replace(/^[-\s]+/, "").trim())
+    .filter(Boolean) ?? [];
+  const lineCount = text ? text.split(/\r?\n/).length : 0;
+  const label = policies.length > 0
+    ? `policy context loaded: ${policies.join(", ")}`
+    : `${lineCount} result line${lineCount === 1 ? "" : "s"} hidden`;
+  const icon = status === "failed" ? "⚠" : "✓";
+  const color = status === "failed" ? "warning" : "success";
+  return `${theme.fg(color, `${icon} takomi_subagent ${status}`)}${theme.fg("dim", ` · ${label} (ctrl+o to expand)`)}`;
+}
+
 export function renderTakomiSubagentResult(result: ToolResult, options: { expanded?: boolean; isPartial?: boolean }, theme: Theme, context: any): any {
   const native = renderNativeSubagentResult(result, options, theme, context);
   if (native) return native;
 
   const status = (result as any)?.isError ? "failed" : "completed";
-  const text = typeof (result as any)?.content === "string"
-    ? (result as any).content
-    : Array.isArray((result as any)?.content)
-      ? (result as any).content.map((part: any) => part?.text ?? "").filter(Boolean).join("\n")
-      : JSON.stringify((result as any)?.details ?? {}, null, 2);
+  const text = resultText(result);
+  if (!options.expanded && !options.isPartial) {
+    return new Text(summarizeCollapsedResult(text, status, theme), 0, 0);
+  }
   return new Text(`${theme.fg("toolTitle", theme.bold(`takomi_subagent ${status}`))}\n${text || "No result content."}`, 0, 0);
 }

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

@@ -186,7 +186,7 @@ function toSubagentParams(params: TakomiSubagentToolParams, rootCwd: string, dis
     cwd: rootCwd,
     context: "fresh" as const,
     async: false,
-    clarify: false,
+    clarify: params.clarify === true,
     includeProgress: true,
     sessionDir: stableConversationSessionDir(rootCwd, tasks),
   };

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

@@ -28,6 +28,7 @@ export type TakomiSubagentToolParams = Partial<TakomiSubagentToolTask> & {
   chain?: TakomiSubagentToolTask[];
   confirmLaunch?: boolean;
   previewOnly?: boolean;
+  clarify?: boolean;
   agentScope?: TakomiAgentScope;
   confirmProjectAgents?: boolean;
   overrideUserBlock?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "takomi",
-  "version": "2.1.33",
+  "version": "2.1.34",
   "description": "🎯 Stop wrestling with AI. Start building with purpose. The artisan's toolkit for agent workflows, Codex skills, and original Takomi capabilities like 21st.dev integration.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -43,7 +43,7 @@ import {
   isStoreInitialized,
 } from './store.js';
 import { runDoctor } from './doctor.js';
-import { ensurePiInstalled, ensurePiSubagentsInstalled, launchTakomiHarness, printPiInstallResult, printPiSubagentsInstallResult, updatePiManagedPackages, printPiManagedPackageUpdateResult } from './pi-harness.js';
+import { ensurePiInstalled, ensurePiSubagentsInstalled, launchTakomiHarness, printPiInstallResult, printPiSubagentsInstallResult, updatePiCliPackage, updatePiManagedPackages, printPiManagedPackageUpdateResult } from './pi-harness.js';
 import { installPiHarnessAssets, printPiInstallSummary, syncPiHarnessAssets, validatePiHarnessInstall } from './pi-installer.js';
 import { offerPiOptionalFeatures } from './pi-optional-features.js';
 import {
@@ -459,7 +459,7 @@ async function installPiTarget(options = {}) {
       console.log(pc.cyan('\n🧩 Optional Takomi Pi feature packs...\n'));
       await offerPiOptionalFeatures({ interactive: true });
     }
-    console.log(pc.cyan('\n📦 Checking Pi-managed package updates...\n'));
+    console.log(pc.cyan('\n📦 Checking Pi-managed extension package updates...\n'));
     printPiManagedPackageUpdateResult(await updatePiManagedPackages());
     console.log(pc.dim('\nNext: cd <project> && takomi\n'));
   } catch (error) {
@@ -474,7 +474,7 @@ async function installPiOptionalFeaturesTarget() {
   printPiInstallResult(pi);
   if (!pi.ok) return;
   await offerPiOptionalFeatures({ interactive: true });
-  console.log(pc.cyan('\n📦 Checking Pi-managed package updates...\n'));
+  console.log(pc.cyan('\n📦 Checking Pi-managed extension package updates...\n'));
   printPiManagedPackageUpdateResult(await updatePiManagedPackages());
 }
 
@@ -484,7 +484,7 @@ async function syncPiTarget() {
     const result = await syncPiHarnessAssets(program.version());
     const validation = await validatePiHarnessInstall();
     printPiInstallSummary(result, validation);
-    console.log(pc.cyan('\n📦 Checking Pi-managed package updates...\n'));
+    console.log(pc.cyan('\n📦 Checking Pi-managed extension package updates...\n'));
     printPiManagedPackageUpdateResult(await updatePiManagedPackages());
   } catch (error) {
     console.log(pc.red('\nPi sync failed.'));
@@ -558,6 +558,8 @@ async function upgrade(target = 'all') {
   }
 
   if (normalizedTarget === 'pi') {
+    console.log(pc.cyan('\n📦 Updating Pi CLI...\n'));
+    printPiInstallResult(await updatePiCliPackage());
     await installPiTarget({ offerOptionalFeatures: false });
     return;
   }
@@ -567,6 +569,8 @@ async function upgrade(target = 'all') {
     return;
   }
 
+  console.log(pc.cyan('\n📦 Updating Pi CLI...\n'));
+  printPiInstallResult(await updatePiCliPackage());
   await installAllTargets({ offerOptionalFeatures: false });
   console.log(pc.magenta('\n✨ Fully upgraded. Next: run `takomi` from your project.\n'));
 }

package/src/pi-harness.js

@@ -275,9 +275,9 @@ function runCommandWithTimeout(command, args, timeoutMs) {
   });
 }
 
-export async function ensurePiInstalled() {
+async function installOrUpdatePiCli({ force = false } = {}) {
   const before = await detectPiCommand();
-  if (before.installed) {
+  if (before.installed && !force) {
     return { ok: true, changed: false, report: 'Pi already available.' };
   }
 
@@ -295,7 +295,9 @@ export async function ensurePiInstalled() {
         return {
           ok: true,
           changed: true,
-          report: (result.stdout || result.stderr || 'Installed Pi.').trim(),
+          report: (result.stdout || result.stderr || (force ? 'Updated Pi.' : 'Installed Pi.')).trim(),
+          version: after.version,
+          action: force ? 'Updated' : 'Installed',
         };
       }
       lastError = 'npm install reported success, but pi was still not detected.';
@@ -307,9 +309,17 @@ export async function ensurePiInstalled() {
   return { ok: false, changed: false, report: lastError };
 }
 
+export async function ensurePiInstalled() {
+  return installOrUpdatePiCli({ force: false });
+}
+
+export async function updatePiCliPackage() {
+  return installOrUpdatePiCli({ force: true });
+}
+
 export function printPiInstallResult(result) {
   if (result.ok) {
-    console.log(pc.green(`✔ ${result.changed ? 'Installed' : 'Validated'} Pi`));
+    console.log(pc.green(`✔ ${result.action || (result.changed ? 'Installed' : 'Validated')} Pi`));
     if (result.report) console.log(pc.dim(result.report.split(/\r?\n/).slice(-4).join('\n')));
     return;
   }
@@ -359,42 +369,54 @@ export function printPiSubagentsInstallResult(result) {
   if (result.report) console.log(pc.dim(result.report.split(/\r?\n/).slice(-8).join('\n')));
 }
 
-export async function updatePiManagedPackages({ timeoutMs = 20_000 } = {}) {
+function getPiPackageUpdateTimeoutMs(timeoutMs) {
+  if (Number.isFinite(timeoutMs) && timeoutMs > 0) return timeoutMs;
+  const envValue = Number(process.env.TAKOMI_PI_PACKAGE_UPDATE_TIMEOUT_MS || '');
+  if (Number.isFinite(envValue) && envValue > 0) return envValue;
+  return 180_000;
+}
+
+export async function updatePiManagedPackages({ timeoutMs } = {}) {
   if (process.env.TAKOMI_SKIP_PI_PACKAGE_UPDATE === '1') {
-    return { ok: true, changed: false, report: 'Skipped Pi package update because TAKOMI_SKIP_PI_PACKAGE_UPDATE=1.' };
+    return { ok: true, changed: false, report: 'Skipped Pi extension package update because TAKOMI_SKIP_PI_PACKAGE_UPDATE=1.' };
   }
 
   const pi = await detectPiCommand();
   if (!pi.installed) return { ok: false, changed: false, report: 'Pi is not installed.' };
 
-  // `pi update` reconciles packages from Pi settings, including user-installed
-  // npm/git/local packages. Treat this as a best-effort follow-up: third-party
-  // packages or manual extension entries must never hang Takomi installation.
+  // Only reconcile Pi-managed extension/package entries here. Plain `pi update`
+  // also self-updates the Pi CLI (`npm install -g @earendil-works/pi-coding-agent`).
+  // If Takomi times out and kills that process, npm can leave the global `pi`
+  // shim temporarily removed on Windows. `--extensions` avoids touching the Pi
+  // executable while still updating optional/user package packs.
+  const effectiveTimeoutMs = getPiPackageUpdateTimeoutMs(timeoutMs);
   const command = pi.path || 'pi';
-  const result = await runCommandWithTimeout(command, ['update'], timeoutMs);
+  const updateArgs = ['update', '--extensions'];
+  const updateCommandText = `pi ${updateArgs.join(' ')}`;
+  const result = await runCommandWithTimeout(command, updateArgs, effectiveTimeoutMs);
   const output = [result.stdout, result.stderr].filter(Boolean).join('\n').trim();
   if (result.timedOut) {
     return {
       ok: false,
       changed: false,
-      report: `Timed out after ${Math.round(timeoutMs / 1000)}s while running \`pi update\`. Takomi setup is complete; retry package updates later with \`pi update\` or skip this step with TAKOMI_SKIP_PI_PACKAGE_UPDATE=1. Last output:\n${output}`.trim(),
+      report: `Timed out after ${Math.round(effectiveTimeoutMs / 1000)}s while running \`${updateCommandText}\`. Takomi setup is complete; retry package updates later with \`${updateCommandText}\` or skip this step with TAKOMI_SKIP_PI_PACKAGE_UPDATE=1. Increase the timeout with TAKOMI_PI_PACKAGE_UPDATE_TIMEOUT_MS=<ms>. Last output:\n${output}`.trim(),
     };
   }
 
   return {
     ok: result.status === 0,
     changed: result.status === 0,
-    report: output || (result.status === 0 ? 'All Pi-managed packages are up to date.' : 'pi update failed.'),
+    report: output || (result.status === 0 ? 'All Pi-managed extension packages are up to date.' : `${updateCommandText} failed.`),
   };
 }
 
 export function printPiManagedPackageUpdateResult(result) {
   if (result.ok) {
-    console.log(pc.green('✔ Updated all Pi-managed packages'));
+    console.log(pc.green('✔ Updated all Pi-managed extension packages'));
     if (result.report) console.log(pc.dim(result.report.split(/\r?\n/).slice(-8).join('\n')));
     return;
   }
-  console.log(pc.yellow('⚠ Could not update Pi-managed packages'));
+  console.log(pc.yellow('⚠ Could not update Pi-managed extension packages'));
   if (result.report) console.log(pc.dim(result.report.split(/\r?\n/).slice(-8).join('\n')));
 }