takomi 2.1.44 → 2.5.1

package/.pi/README.md

@@ -33,9 +33,9 @@ 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 gate auto` to continue approved plans automatically
-- `/takomi gate review` to return to the user after each task with results and verification guidance
+- `/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
 - `/takomi subagents list` to list available Takomi agents without exposing the raw `subagent` tool
 - `/takomi subagents status` to inspect active subagent state
@@ -100,16 +100,17 @@ 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`.
-- The subagent tool supports `agentScope` values of `user`, `project`, and `both`; project-local agents require confirmation by default.
+- The subagent tool supports `agentScope` values of `user`, `project`, and `both`; project-local agents require confirmation by default. The only session authorization bypasses are `TAKOMI_TRUST_PROJECT_AGENTS` and the explicit user `/takomi gate auto` provenance marker; model mode changes plus profile, default, or generic runtime `auto` state do not authorize project agents.
+- The explicit user gate-auto marker is stored in session history so it survives resuming that same session. `/takomi gate review`, `/takomi gate manual`, review mode, and `/takomi-reset` append a revocation; it is not a cross-session or profile setting.
 - The subagent tool also supports per-run `workflow`, `skills`, `model`, `fallbackModels`, `thinking`, `checklist`, `concurrency`, and `worktree` overrides.
 - `takomi_board` records session/state/markdown artifacts only; it does not run subagents.
 - Pi's default `subagent` tool remains owned by the user-level/default subagent extension to avoid tool-name conflicts; Takomi uses `takomi_subagent` as the preferred lifecycle-aware execution interface and renders it with the native Pi-style result surface.
@@ -118,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/oauth-router/commands.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { createAccountFromUpstream } from "./oauth-flow.ts";
+import { createRouterReportLines, createRouterReportWidget, ROUTER_REPORT_DISMISS_HINT, ROUTER_REPORT_WIDGET_KEY } from "./report-ui.ts";
 import type { RouterStatusRow, RouterUsageSummary, RouterUsageWindowSummary, RoutingPolicyName, StoredRouterAccount } from "./types.ts";
 import { RouterRuntime } from "./provider.ts";
 
@@ -273,12 +274,32 @@ export function formatUsageRawReport(runtime: RouterRuntime, accountId?: string)
   return ["# oauth-router usage raw", "", ...rows].join("\n");
 }
 
-function emitReport(ctx: ExtensionCommandContext, text: string) {
-  const lines = text.split(/\r?\n/);
-  ctx.ui.setWidget("oauth-router-report", lines, { placement: "belowEditor" });
-  ctx.ui.notify(lines[0] || "oauth-router report updated", "info");
+export function emitRouterReport(ctx: ExtensionCommandContext, text: string) {
+  // A single key gives every report predictable replacement semantics. Add the
+  // dismiss affordance at this presentation boundary, not to formatter output,
+  // so model/source report text remains unchanged. Omitting options uses Pi's
+  // default above-editor placement for both TUI and RPC widgets.
+  const reportText = `${ROUTER_REPORT_DISMISS_HINT}\n\n${text}`;
+  if (ctx.mode === "tui") {
+    ctx.ui.setWidget(ROUTER_REPORT_WIDGET_KEY, createRouterReportWidget(reportText));
+    return;
+  }
+  // RPC accepts string-array widgets only; ctx.hasUI is true there, so ctx.mode
+  // is the capability signal that prevents its visible report from being ignored.
+  ctx.ui.setWidget(ROUTER_REPORT_WIDGET_KEY, createRouterReportLines(reportText));
+}
+
+export function clearRouterReport(ctx: ExtensionCommandContext) {
+  ctx.ui.setWidget(ROUTER_REPORT_WIDGET_KEY, undefined);
 }
 
+export type RouterReportEmitter = (ctx: ExtensionCommandContext, text: string) => void;
+
+export type RouterReportControls = {
+  show: RouterReportEmitter;
+  clear: (ctx: ExtensionCommandContext) => void;
+};
+
 async function pickUpstream(runtime: RouterRuntime, ctx: ExtensionCommandContext, requestedId?: string) {
   const upstreams = runtime.listUpstreams().filter((upstream) => upstream.enabled);
   if (upstreams.length === 0) throw new Error("No enabled upstreams are configured");
@@ -385,12 +406,11 @@ function setFooterStatus(ctx: ExtensionCommandContext, runtime: RouterRuntime) {
   ctx.ui.setStatus("oauth-router", `oauth-router ${healthy}/${rows.length || 0} healthy | ${runtime.getPolicy()}`);
 }
 
-function showCommandHint(ctx: ExtensionCommandContext, title: string, lines: string[]) {
-  emitReport(ctx, [`# ${title}`, "", ...lines].join("\n"));
-  ctx.ui.notify(title, "info");
+function showCommandHint(ctx: ExtensionCommandContext, title: string, lines: string[], showReport: RouterReportEmitter = emitRouterReport) {
+  showReport(ctx, [`# ${title}`, "", ...lines].join("\n"));
 }
 
-async function handleRouterLogin(runtime: RouterRuntime, args: string, ctx: ExtensionCommandContext) {
+async function handleRouterLogin(runtime: RouterRuntime, args: string, ctx: ExtensionCommandContext, showReport: RouterReportEmitter = emitRouterReport) {
   const [command = "help", first, ...rest] = parseArgs(args);
 
   switch (command) {
@@ -415,18 +435,17 @@ async function handleRouterLogin(runtime: RouterRuntime, args: string, ctx: Exte
         runtime.clearAccountHealth(duplicate.id);
         const usageMessage = await refreshUsageAfterCredentialChange(runtime, duplicate.id);
         setFooterStatus(ctx, runtime);
-        emitReport(ctx, `Updated existing account ${duplicate.id} (${duplicate.label}) with fresh credentials instead of adding a duplicate.${usageMessage}`);
+        showReport(ctx, `Updated existing account ${duplicate.id} (${duplicate.label}) with fresh credentials instead of adding a duplicate.${usageMessage}`);
         return;
       }
       runtime.addAccount(account);
       const usageMessage = await refreshUsageAfterCredentialChange(runtime, account.id);
       setFooterStatus(ctx, runtime);
-      emitReport(ctx, `Added account ${account.id} (${account.label}) for upstream ${upstream.id}.${usageMessage}`);
-      ctx.ui.notify(`Added ${account.id}`, "info");
+      showReport(ctx, `Added account ${account.id} (${account.label}) for upstream ${upstream.id}.${usageMessage}`);
       return;
     }
     case "list": {
-      emitReport(ctx, formatAccountsReport(runtime));
+      showReport(ctx, formatAccountsReport(runtime));
       setFooterStatus(ctx, runtime);
       return;
     }
@@ -439,7 +458,7 @@ async function handleRouterLogin(runtime: RouterRuntime, args: string, ctx: Exte
       }
       runtime.removeAccount(account.id);
       setFooterStatus(ctx, runtime);
-      emitReport(ctx, `Removed account ${account.id}.`);
+      showReport(ctx, `Removed account ${account.id}.`);
       return;
     }
     case "rename": {
@@ -447,7 +466,7 @@ async function handleRouterLogin(runtime: RouterRuntime, args: string, ctx: Exte
       const label = await getRequiredLabel(ctx, account.label, rest.join(" "));
       runtime.renameAccount(account.id, label);
       setFooterStatus(ctx, runtime);
-      emitReport(ctx, `Renamed account ${account.id} to ${label}.`);
+      showReport(ctx, `Renamed account ${account.id} to ${label}.`);
       return;
     }
     case "relogin": {
@@ -472,7 +491,7 @@ async function handleRouterLogin(runtime: RouterRuntime, args: string, ctx: Exte
       runtime.clearAccountHealth(existing.id);
       const usageMessage = await refreshUsageAfterCredentialChange(runtime, existing.id);
       setFooterStatus(ctx, runtime);
-      emitReport(ctx, `Re-logged account ${existing.id} (${existing.label}) and cleared auth state.${usageMessage}`);
+      showReport(ctx, `Re-logged account ${existing.id} (${existing.label}) and cleared auth state.${usageMessage}`);
       return;
     }
     case "refresh": {
@@ -480,12 +499,12 @@ async function handleRouterLogin(runtime: RouterRuntime, args: string, ctx: Exte
       const refreshed = await runtime.refreshAccount(account.id);
       const usageMessage = await refreshUsageAfterCredentialChange(runtime, refreshed.id);
       setFooterStatus(ctx, runtime);
-      emitReport(ctx, `Refreshed account ${refreshed.id} (${refreshed.label}).${usageMessage}`);
+      showReport(ctx, `Refreshed account ${refreshed.id} (${refreshed.label}).${usageMessage}`);
       return;
     }
     case "help":
     default: {
-      emitReport(
+      showReport(
         ctx,
         [
           "# oauth-router commands",
@@ -506,6 +525,7 @@ async function handleRouterLogin(runtime: RouterRuntime, args: string, ctx: Exte
           "- /router-disable <id>",
           "- /router-policy <round-robin|weighted-round-robin>",
           "- /router-weight <id> <n>",
+          "- /router-clear (dismiss the current report)",
         ].join("\n"),
       );
       return;
@@ -513,16 +533,27 @@ async function handleRouterLogin(runtime: RouterRuntime, args: string, ctx: Exte
   }
 }
 
-export function registerRouterCommands(pi: ExtensionAPI, runtime: RouterRuntime) {
+export function registerRouterCommands(pi: ExtensionAPI, runtime: RouterRuntime, reportControls?: RouterReportControls) {
+  const showReport = reportControls?.show ?? emitRouterReport;
+  const clearReport = reportControls?.clear ?? clearRouterReport;
+
   pi.registerCommand("router-login", {
     description: "Manage oauth-router accounts",
-    handler: async (args, ctx) => handleRouterLogin(runtime, args || "", ctx),
+    handler: async (args, ctx) => handleRouterLogin(runtime, args || "", ctx, showReport),
+  });
+
+  pi.registerCommand("router-clear", {
+    description: "Dismiss the current oauth-router report widget",
+    handler: async (_args, ctx) => {
+      clearReport(ctx);
+      setFooterStatus(ctx, runtime);
+    },
   });
 
   pi.registerCommand("router-status", {
     description: "Show oauth-router health and routing state",
     handler: async (_args, ctx) => {
-      emitReport(ctx, formatStatusReport(runtime));
+      showReport(ctx, formatStatusReport(runtime));
       setFooterStatus(ctx, runtime);
     },
   });
@@ -530,7 +561,7 @@ export function registerRouterCommands(pi: ExtensionAPI, runtime: RouterRuntime)
   pi.registerCommand("router-accounts", {
     description: "Show compact oauth-router account list",
     handler: async (_args, ctx) => {
-      emitReport(ctx, formatAccountsReport(runtime));
+      showReport(ctx, formatAccountsReport(runtime));
       setFooterStatus(ctx, runtime);
     },
   });
@@ -539,7 +570,7 @@ export function registerRouterCommands(pi: ExtensionAPI, runtime: RouterRuntime)
     description: "Show oauth-router visual provider quota and local usage",
     handler: async (args, ctx) => {
       const [id] = parseArgs(args || "");
-      emitReport(ctx, formatUsageReport(runtime, id));
+      showReport(ctx, formatUsageReport(runtime, id));
       setFooterStatus(ctx, runtime);
     },
   });
@@ -548,7 +579,7 @@ export function registerRouterCommands(pi: ExtensionAPI, runtime: RouterRuntime)
     description: "Show raw oauth-router usage/provider quota details",
     handler: async (args, ctx) => {
       const [id] = parseArgs(args || "");
-      emitReport(ctx, formatUsageRawReport(runtime, id));
+      showReport(ctx, formatUsageRawReport(runtime, id));
       setFooterStatus(ctx, runtime);
     },
   });
@@ -557,7 +588,7 @@ export function registerRouterCommands(pi: ExtensionAPI, runtime: RouterRuntime)
     description: "Alias for visual oauth-router usage/quota",
     handler: async (args, ctx) => {
       const [id] = parseArgs(args || "");
-      emitReport(ctx, formatUsageReport(runtime, id));
+      showReport(ctx, formatUsageReport(runtime, id));
       setFooterStatus(ctx, runtime);
     },
   });
@@ -580,7 +611,7 @@ export function registerRouterCommands(pi: ExtensionAPI, runtime: RouterRuntime)
       }
 
       const report = formatUsageReport(runtime, target === "all" ? undefined : target);
-      emitReport(ctx, failures.length ? [report, "", "## Refresh failures", ...failures].join("\n") : report);
+      showReport(ctx, failures.length ? [report, "", "## Refresh failures", ...failures].join("\n") : report);
       if (failures.length) ctx.ui.notify(`oauth-router usage refreshed with ${failures.length} failure(s)`, "error");
       setFooterStatus(ctx, runtime);
     },
@@ -594,7 +625,7 @@ export function registerRouterCommands(pi: ExtensionAPI, runtime: RouterRuntime)
       const label = await getRequiredLabel(ctx, account.label, labelParts.join(" "));
       runtime.renameAccount(account.id, label);
       setFooterStatus(ctx, runtime);
-      emitReport(ctx, `Renamed account ${account.id} to ${label}.`);
+      showReport(ctx, `Renamed account ${account.id} to ${label}.`);
     },
   });
 
@@ -609,13 +640,13 @@ export function registerRouterCommands(pi: ExtensionAPI, runtime: RouterRuntime)
       }
       runtime.removeAccount(account.id);
       setFooterStatus(ctx, runtime);
-      emitReport(ctx, `Deleted account ${account.id}.`);
+      showReport(ctx, `Deleted account ${account.id}.`);
     },
   });
 
   pi.registerCommand("router-relogin", {
     description: "Re-login and recover an oauth-router account",
-    handler: async (args, ctx) => handleRouterLogin(runtime, `relogin ${args || ""}`, ctx),
+    handler: async (args, ctx) => handleRouterLogin(runtime, `relogin ${args || ""}`, ctx, showReport),
   });
 
   pi.registerCommand("router-enable", {
@@ -625,7 +656,7 @@ export function registerRouterCommands(pi: ExtensionAPI, runtime: RouterRuntime)
       const account = await pickAccount(runtime, ctx, id, "Choose account to enable");
       runtime.setEnabled(account.id, true);
       setFooterStatus(ctx, runtime);
-      emitReport(ctx, `Enabled account ${account.id}.`);
+      showReport(ctx, `Enabled account ${account.id}.`);
     },
   });
 
@@ -636,7 +667,7 @@ export function registerRouterCommands(pi: ExtensionAPI, runtime: RouterRuntime)
       const account = await pickAccount(runtime, ctx, id, "Choose account to disable");
       runtime.setEnabled(account.id, false);
       setFooterStatus(ctx, runtime);
-      emitReport(ctx, `Disabled account ${account.id}.`);
+      showReport(ctx, `Disabled account ${account.id}.`);
     },
   });
 
@@ -651,7 +682,7 @@ export function registerRouterCommands(pi: ExtensionAPI, runtime: RouterRuntime)
           "",
           "Usage: /router-policy <round-robin|weighted-round-robin>",
           "Aliases: rr, wrr, weighted",
-        ]);
+        ], showReport);
         return;
       }
       if (!policy) {
@@ -660,12 +691,12 @@ export function registerRouterCommands(pi: ExtensionAPI, runtime: RouterRuntime)
           "",
           `Current policy: ${runtime.getPolicy()}`,
           "Valid values: round-robin, weighted-round-robin",
-        ]);
+        ], showReport);
         return;
       }
       runtime.setPolicy(policy);
       setFooterStatus(ctx, runtime);
-      emitReport(ctx, `Routing policy set to ${policy}.`);
+      showReport(ctx, `Routing policy set to ${policy}.`);
     },
   });
 
@@ -680,12 +711,12 @@ export function registerRouterCommands(pi: ExtensionAPI, runtime: RouterRuntime)
         weight = Number(response);
       }
       if (!Number.isFinite(weight)) {
-        showCommandHint(ctx, "router-weight", ["Usage: /router-weight <id> <n>", "Example: /router-weight acct_ab12cd34 3"]);
+        showCommandHint(ctx, "router-weight", ["Usage: /router-weight <id> <n>", "Example: /router-weight acct_ab12cd34 3"], showReport);
         return;
       }
       runtime.setWeight(account.id, weight);
       setFooterStatus(ctx, runtime);
-      emitReport(ctx, `Updated weight for ${account.id} to ${Math.max(1, Math.floor(weight))}.`);
+      showReport(ctx, `Updated weight for ${account.id} to ${Math.max(1, Math.floor(weight))}.`);
     },
   });
 }

package/.pi/extensions/oauth-router/index.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { registerRouterCommands, formatStatusReport } from "./commands.ts";
+import { emitRouterReport, formatStatusReport, registerRouterCommands, type RouterReportControls } from "./commands.ts";
+import { ROUTER_REPORT_WIDGET_KEY } from "./report-ui.ts";
 import { registerRouterProvider, RouterRuntime } from "./provider.ts";
 import type { RouterUiEvent } from "./types.ts";
 
@@ -64,8 +65,33 @@ function notifyActivity(ctx: ExtensionContext, event: RouterUiEvent) {
   ctx.ui.notify(message, level);
 }
 
-function installRouterUiBridge(pi: ExtensionAPI, runtime: RouterRuntime, notifyOnLoad = false) {
+function installRouterUiBridge(pi: ExtensionAPI, runtime: RouterRuntime, notifyOnLoad = false): RouterReportControls {
   let activeCtx: ExtensionContext | undefined;
+  let reportGeneration = 0;
+  let activeReport: { generation: number; ctx: ExtensionContext } | undefined;
+
+  const clearReport = (fallbackCtx?: ExtensionContext, clearFallback = false) => {
+    const report = activeReport;
+    const ctx = report?.ctx ?? (clearFallback ? fallbackCtx : undefined);
+    if (!ctx) return;
+
+    try {
+      ctx.ui.setWidget(ROUTER_REPORT_WIDGET_KEY, undefined);
+    } catch {
+      // Widget lifecycle is best-effort and must not interrupt agent activity.
+    } finally {
+      // A re-entrant command can replace the report while the old widget clears.
+      // Its newer generation remains active instead of being erased by this clear.
+      if (report && activeReport?.generation === report.generation) activeReport = undefined;
+    }
+  };
+
+  const showReport: RouterReportControls["show"] = (ctx, text) => {
+    const report = { generation: ++reportGeneration, ctx };
+    activeCtx = ctx;
+    activeReport = report;
+    emitRouterReport(ctx, text);
+  };
 
   const setBaseStatus = (ctx: ExtensionContext) => {
     activeCtx = ctx;
@@ -84,14 +110,29 @@ function installRouterUiBridge(pi: ExtensionAPI, runtime: RouterRuntime, notifyO
   });
 
   pi.on("session_start", async (_event, ctx) => {
+    // A session replacement owns a fresh transport, so clear the old transport
+    // before accepting reports for the new one.
+    clearReport(activeCtx, true);
     setBaseStatus(ctx);
     if (notifyOnLoad) ctx.ui.notify("oauth-router loaded", "info");
   });
 
+  pi.on("input", async (event, ctx) => {
+    // Registered slash commands run before Pi emits input and return without an
+    // input event. Ordinary text/image input reaches this handler before its
+    // agent starts, which is the intended transient-dismissal boundary.
+    if (event.text.trim() || event.images?.length) clearReport(ctx);
+  });
+
   pi.on("agent_start", async (_event, ctx) => {
+    clearReport(ctx);
     setBaseStatus(ctx);
   });
 
+  pi.on("tool_execution_start", async (_event, ctx) => {
+    clearReport(ctx);
+  });
+
   pi.on("turn_start", async (_event, ctx) => {
     setBaseStatus(ctx);
   });
@@ -105,23 +146,26 @@ function installRouterUiBridge(pi: ExtensionAPI, runtime: RouterRuntime, notifyO
   });
 
   pi.on("session_shutdown", async () => {
+    // The old context owns the RPC transport. Clear its report before releasing
+    // it so clients do not retain a widget across a session replacement.
+    clearReport(activeCtx, true);
     activeCtx = undefined;
   });
+
+  return { show: showReport, clear: (ctx) => clearReport(ctx, true) };
 }
 
 export default function (pi: ExtensionAPI) {
   const runtime = new RouterRuntime();
 
   registerRouterProvider(pi, runtime);
-  registerRouterCommands(pi, runtime);
-  installRouterUiBridge(pi, runtime, false);
+  const reportControls = installRouterUiBridge(pi, runtime, false);
+  registerRouterCommands(pi, runtime, reportControls);
 
   pi.registerCommand("router-debug-report", {
     description: "Show a detailed oauth-router report in the UI only",
     handler: async (_args, ctx) => {
-      const report = formatStatusReport(runtime);
-      ctx.ui.setWidget("oauth-router-report", report.split(/\r?\n/), { placement: "belowEditor" });
-      ctx.ui.notify("oauth-router debug report updated", "info");
+      reportControls.show(ctx, formatStatusReport(runtime));
     },
   });
 }