takomi 2.1.43 → 2.1.45

package/.pi/extensions/takomi-context-manager/skill-tools.ts

@@ -1,103 +1,208 @@
-import { readFile } from "node:fs/promises";
-import path from "node:path";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
-import type { ContextManagerState } from "./state";
-import { discoverSkillsFromFilesystem, findSkill, mergeSkills, normalizeName, sortedSkills } from "./skill-registry";
-import { persistReportSnapshot, restoreReportFromSession } from "./session-state";
-
-function renderSkillIndex(state: ContextManagerState): string {
-  const skills = sortedSkills(state.skills);
-  if (skills.length === 0) return "Available skills (names only): none discovered.";
-  return ["Available skills (names only):", ...skills.map((skill) => `- ${skill.name}`)].join("\n");
-}
-
-function renderManifest(state: ContextManagerState, names: string[]): string {
-  if (names.length === 0) return "No skills requested.";
-  return names.map((name) => {
-    const skill = findSkill(state.skills, name);
-    if (!skill) {
-      const close = sortedSkills(state.skills).filter((candidate) => normalizeName(candidate.name).includes(normalizeName(name).slice(0, 4))).slice(0, 5).map((candidate) => candidate.name);
-      return [`Skill not found: ${name}`, close.length ? `Known close matches: ${close.join(", ")}` : ""].filter(Boolean).join("\n");
-    }
-    return [`Skill: ${skill.name}`, `Description: ${skill.description ?? "(no description discovered)"}`, `Location: ${skill.location ?? "(no location discovered)"}`].join("\n");
-  }).join("\n\n");
-}
-
-async function loadSkillContent(location: string): Promise<string> {
-  const fileName = path.basename(location).toLowerCase();
-  if (fileName !== "skill.md" && !location.toLowerCase().endsWith(".md")) throw new Error(`Refusing to load non-markdown skill location: ${location}`);
-  return readFile(location, "utf8");
-}
-
-async function ensureSkillsDiscovered(state: ContextManagerState, cwd: string): Promise<void> {
-  if (state.skills.size > 0) return;
-  state.skills = mergeSkills(await discoverSkillsFromFilesystem(cwd));
-  state.report.skillCount = state.skills.size;
-}
-
-export function registerSkillTools(pi: ExtensionAPI, state: ContextManagerState): void {
-  pi.registerTool({
-    name: "skill_index",
-    label: "Skill Index",
-    description: "Return the available skill names only. Use this to inspect capability names without loading descriptions or full instructions.",
-    promptSnippet: "List available skill names only for progressive skill loading",
-    parameters: Type.Object({}),
-    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
-      restoreReportFromSession(state, ctx);
-      await ensureSkillsDiscovered(state, ctx.cwd);
-      state.report.timestamp = new Date().toISOString();
-      state.report.cwd = ctx.cwd;
-      state.report.toolCalls.skillIndex += 1;
-      persistReportSnapshot(pi, state, "skill_index");
-      return { content: [{ type: "text", text: renderSkillIndex(state) }], details: { skillCount: state.skills.size } };
-    },
-  });
-
-  pi.registerTool({
-    name: "skill_manifest",
-    label: "Skill Manifest",
-    description: "Return descriptions and locations for selected skills without loading full SKILL.md instructions.",
-    promptSnippet: "Show selected skill descriptions and locations without full instructions",
-    parameters: Type.Object({ skills: Type.Array(Type.String({ description: "Skill name to inspect" })) }),
-    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      restoreReportFromSession(state, ctx);
-      await ensureSkillsDiscovered(state, ctx.cwd);
-      state.report.timestamp = new Date().toISOString();
-      state.report.cwd = ctx.cwd;
-      state.report.toolCalls.skillManifest += 1;
-      persistReportSnapshot(pi, state, "skill_manifest");
-      return { content: [{ type: "text", text: renderManifest(state, params.skills) }], details: { requested: params.skills } };
-    },
-  });
-
-  pi.registerTool({
-    name: "skill_load",
-    label: "Skill Load",
-    description: "Load the full SKILL.md content for one selected skill that will actually be used.",
-    promptSnippet: "Load full SKILL.md instructions for one selected skill",
-    parameters: Type.Object({ skill: Type.String({ description: "Exact skill name to load" }) }),
-    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      restoreReportFromSession(state, ctx);
-      await ensureSkillsDiscovered(state, ctx.cwd);
-      state.report.timestamp = new Date().toISOString();
-      state.report.cwd = ctx.cwd;
-      state.report.toolCalls.skillLoad += 1;
-      const skill = findSkill(state.skills, params.skill);
-      if (!skill?.location) {
-        persistReportSnapshot(pi, state, "skill_load_not_found");
-        return { content: [{ type: "text", text: renderManifest(state, [params.skill]) }], details: { found: false, requested: params.skill }, isError: true };
-      }
-      try {
-        const content = await loadSkillContent(skill.location);
-        state.report.loadedByTool = [...new Set([...state.report.loadedByTool, skill.name])].sort();
-        persistReportSnapshot(pi, state, "skill_load");
-        return { content: [{ type: "text", text: [`Skill: ${skill.name}`, `Location: ${skill.location}`, "", content].join("\n") }], details: { found: true, skill: skill.name, location: skill.location } };
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        persistReportSnapshot(pi, state, "skill_load_error");
-        return { content: [{ type: "text", text: message }], details: { found: true, skill: skill.name, error: message }, isError: true };
-      }
-    },
-  });
-}
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Container, Markdown, Text } from "@earendil-works/pi-tui";
+import { getMarkdownTheme, keyHint } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { ContextManagerState } from "./state";
+import { discoverSkillsFromFilesystem, findSkill, mergeSkills, normalizeName, skillIndexRenderGroups, sortedSkills, type SkillIndexRenderGroup } from "./skill-registry";
+import { persistReportSnapshot, restoreReportFromSession } from "./session-state";
+import { renderCompactCard, renderExpandedMarkdown, renderToolCall, resultText, sanitizePresentation } from "./tool-renderers";
+
+function renderSkillIndex(state: ContextManagerState): string {
+  const skills = sortedSkills(state.skills);
+  if (skills.length === 0) return "Available skills (names only): none discovered.";
+  return ["Available skills (names only):", ...skills.map((skill) => `- ${skill.name}`)].join("\n");
+}
+
+function renderManifest(state: ContextManagerState, names: string[]): string {
+  if (names.length === 0) return "No skills requested.";
+  return names.map((name) => {
+    const skill = findSkill(state.skills, name);
+    if (!skill) {
+      const close = sortedSkills(state.skills).filter((candidate) => normalizeName(candidate.name).includes(normalizeName(name).slice(0, 4))).slice(0, 5).map((candidate) => candidate.name);
+      return [`Skill not found: ${name}`, close.length ? `Known close matches: ${close.join(", ")}` : ""].filter(Boolean).join("\n");
+    }
+    return [`Skill: ${skill.name}`, `Description: ${skill.description ?? "(no description discovered)"}`, `Location: ${skill.location ?? "(no location discovered)"}`].join("\n");
+  }).join("\n\n");
+}
+
+const COMPACT_CATEGORY_LIMIT = 3;
+
+function groupSummaryItems(groups: SkillIndexRenderGroup[], maximum = groups.length): string[] {
+  const visible = groups.slice(0, maximum).map((group) => `${group.category} ${group.skills.length}`);
+  const overflow = groups.length - visible.length;
+  return [...visible, ...(overflow > 0 ? [`+${overflow} more categories`] : [])];
+}
+
+function groupSummary(groups: SkillIndexRenderGroup[], maximum = groups.length): string {
+  return groupSummaryItems(groups, maximum).join(" · ");
+}
+
+function renderGroupedSkillIndex(groups: SkillIndexRenderGroup[]): string {
+  if (groups.length === 0) return "No skills discovered.";
+  return groups.map((group) => [
+    `## ${group.category}`,
+    "",
+    ...group.skills.map((skill) => `- \`${skill.name}\`${skill.description ? ` — ${skill.description}` : ""}`),
+  ].join("\n")).join("\n\n");
+}
+
+function skillMarkdown(text: string): string {
+  const separator = text.indexOf("\n\n");
+  return separator >= 0 ? text.slice(separator + 2) : text;
+}
+
+async function loadSkillContent(location: string): Promise<string> {
+  const fileName = path.basename(location).toLowerCase();
+  if (fileName !== "skill.md" && !location.toLowerCase().endsWith(".md")) throw new Error(`Refusing to load non-markdown skill location: ${location}`);
+  return readFile(location, "utf8");
+}
+
+async function ensureSkillsDiscovered(state: ContextManagerState, cwd: string): Promise<void> {
+  if (state.skills.size > 0) return;
+  state.skills = mergeSkills(await discoverSkillsFromFilesystem(cwd));
+  state.report.skillCount = state.skills.size;
+}
+
+export function registerSkillTools(pi: ExtensionAPI, state: ContextManagerState): void {
+  pi.registerTool({
+    name: "skill_index",
+    label: "Skill Index",
+    description: "Return the available skill names only. Use this to inspect capability names without loading descriptions or full instructions.",
+    promptSnippet: "List available skill names only for progressive skill loading",
+    parameters: Type.Object({}),
+    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      restoreReportFromSession(state, ctx);
+      await ensureSkillsDiscovered(state, ctx.cwd);
+      state.report.timestamp = new Date().toISOString();
+      state.report.cwd = ctx.cwd;
+      state.report.toolCalls.skillIndex += 1;
+      persistReportSnapshot(pi, state, "skill_index");
+      const groups = skillIndexRenderGroups(state.skills.values());
+      return { content: [{ type: "text", text: renderSkillIndex(state) }], details: { skillCount: state.skills.size, groups } };
+    },
+    renderCall(_args, theme) {
+      return renderToolCall("skill_index", undefined, theme);
+    },
+    renderResult(result, { expanded }, theme) {
+      const details = result.details as { skillCount?: number; groups?: SkillIndexRenderGroup[] } | undefined;
+      const groups = details?.groups ?? [];
+      const count = details?.skillCount ?? groups.reduce((total, group) => total + group.skills.length, 0);
+      if (!expanded) {
+        return renderCompactCard({
+          status: count ? "success" : "pending",
+          title: "Skill index",
+          summary: count ? `${count} skills across ${groups.length} categories` : "no skills discovered",
+          responsiveMetadata: groups.length ? groupSummaryItems(groups, COMPACT_CATEGORY_LIMIT) : undefined,
+        }, theme);
+      }
+      return renderExpandedMarkdown({
+        status: count ? "success" : "pending",
+        title: "Skill index",
+        summary: count ? `${count} skills across ${groups.length} categories` : "no skills discovered",
+        metadata: groups.length ? [groupSummary(groups)] : undefined,
+        markdown: renderGroupedSkillIndex(groups),
+      }, theme);
+    },
+  });
+
+  pi.registerTool({
+    name: "skill_manifest",
+    label: "Skill Manifest",
+    description: "Return descriptions and locations for selected skills without loading full SKILL.md instructions.",
+    promptSnippet: "Show selected skill descriptions and locations without full instructions",
+    parameters: Type.Object({ skills: Type.Array(Type.String({ description: "Skill name to inspect" })) }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      restoreReportFromSession(state, ctx);
+      await ensureSkillsDiscovered(state, ctx.cwd);
+      state.report.timestamp = new Date().toISOString();
+      state.report.cwd = ctx.cwd;
+      state.report.toolCalls.skillManifest += 1;
+      persistReportSnapshot(pi, state, "skill_manifest");
+      const found = params.skills.filter((name) => Boolean(findSkill(state.skills, name)));
+      const missing = params.skills.filter((name) => !findSkill(state.skills, name));
+      return { content: [{ type: "text", text: renderManifest(state, params.skills) }], details: { requested: params.skills, found, missing } };
+    },
+    renderCall(args, theme) {
+      return renderToolCall("skill_manifest", `${args.skills.length} requested`, theme);
+    },
+    renderResult(result, { expanded }, theme) {
+      const details = result.details as { requested?: string[]; found?: string[]; missing?: string[] } | undefined;
+      const requested = details?.requested ?? [];
+      const found = details?.found ?? [];
+      const missing = details?.missing ?? [];
+      const status = missing.length ? "warning" : requested.length ? "success" : "pending";
+      const summary = missing.length ? `${found.length} found · ${missing.length} unavailable` : requested.length ? `${found.length} skills available` : "no skills requested";
+      const metadata = missing.length ? `Missing: ${missing.join(", ")}` : `${requested.length} requested`;
+      if (!expanded) return renderCompactCard({ status, title: "Skill manifest", summary, metadata }, theme);
+      return renderExpandedMarkdown({ status, title: "Skill manifest", summary, metadata: [metadata], markdown: resultText(result) }, theme);
+    },
+  });
+
+  pi.registerTool({
+    name: "skill_load",
+    label: "Skill Load",
+    description: "Load the full SKILL.md content for one selected skill that will actually be used.",
+    promptSnippet: "Load full SKILL.md instructions for one selected skill",
+    parameters: Type.Object({ skill: Type.String({ description: "Exact skill name to load" }) }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      restoreReportFromSession(state, ctx);
+      await ensureSkillsDiscovered(state, ctx.cwd);
+      state.report.timestamp = new Date().toISOString();
+      state.report.cwd = ctx.cwd;
+      state.report.toolCalls.skillLoad += 1;
+      const skill = findSkill(state.skills, params.skill);
+      if (!skill?.location) {
+        persistReportSnapshot(pi, state, "skill_load_not_found");
+        return { content: [{ type: "text", text: renderManifest(state, [params.skill]) }], details: { found: false, requested: params.skill }, isError: true };
+      }
+      try {
+        const content = await loadSkillContent(skill.location);
+        state.report.loadedByTool = [...new Set([...state.report.loadedByTool, skill.name])].sort();
+        persistReportSnapshot(pi, state, "skill_load");
+        return {
+          content: [{ type: "text", text: [`Skill: ${skill.name}`, `Location: ${skill.location}`, "", content].join("\n") }],
+          details: {
+            found: true,
+            skill: skill.name,
+            description: skill.description,
+            location: skill.location,
+            lineCount: content.split(/\r?\n/).length,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        persistReportSnapshot(pi, state, "skill_load_error");
+        return { content: [{ type: "text", text: message }], details: { found: true, skill: skill.name, error: message }, isError: true };
+      }
+    },
+    renderCall(args, theme) {
+      return renderToolCall("skill_load", args.skill, theme);
+    },
+    renderResult(result, { expanded }, theme) {
+      const details = result.details as { found?: boolean; skill?: string; description?: string; location?: string; lineCount?: number; error?: string } | undefined;
+      const text = resultText(result);
+      if (details?.error || details?.found === false) {
+        const summary = details?.error ?? "skill not found";
+        if (!expanded) return renderCompactCard({ status: "error", title: "Skill load", summary }, theme);
+        return renderExpandedMarkdown({ status: "error", title: "Skill load", summary, markdown: text }, theme);
+      }
+
+      const name = sanitizePresentation(details?.skill ?? "skill");
+      const description = details?.description ? sanitizePresentation(details.description) : undefined;
+      const summary = description ?? "skill instructions loaded";
+      const metadata = `${details?.lineCount ?? text.split(/\r?\n/).length} lines`;
+      if (!expanded) return renderCompactCard({ status: "success", title: name, summary, metadata }, theme);
+
+      const location = details?.location ? sanitizePresentation(details.location) : undefined;
+      const container = new Container();
+      container.addChild(new Text(`${theme.fg("success", "✓")} ${theme.fg("accent", theme.bold(name))} ${theme.fg("muted", "skill instructions")}`, 0, 0));
+      if (description) container.addChild(new Text(theme.fg("muted", description), 0, 0));
+      if (location) container.addChild(new Text(theme.fg("dim", location), 0, 0));
+      container.addChild(new Text(theme.fg("dim", keyHint("app.tools.expand", "collapse")), 0, 0));
+      container.addChild(new Markdown(sanitizePresentation(skillMarkdown(text)), 0, 1, getMarkdownTheme()));
+      return container;
+    },
+  });
+}

package/.pi/extensions/takomi-context-manager/tool-renderers.ts

@@ -0,0 +1,112 @@
+import { getMarkdownTheme, keyHint } from "@earendil-works/pi-coding-agent";
+import { Container, Markdown, Text, type Component } from "@earendil-works/pi-tui";
+
+type Theme = {
+  fg(color: string, text: string): string;
+  bold(text: string): string;
+};
+
+type ToolResult = {
+  content?: Array<{ type?: string; text?: string }>;
+};
+
+const OSC_SEQUENCE = /\x1B\][\s\S]*?(?:\x07|\x1B\\|$)/g;
+const STRING_TERMINATED_SEQUENCE = /\x1B[PX^_][\s\S]*?(?:\x1B\\|$)/g;
+const CSI_SEQUENCE = /(?:\x1B\[|\x9B)[0-?]*[ -/]*[@-~]/g;
+const ESC_SEQUENCE = /\x1B(?:[()][0-2A-Z0-9]|[=>]|[ -/]*[@-~]?)/g;
+const UNSAFE_CONTROLS = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F-\x9F]/g;
+
+/**
+ * Remove terminal controls at the TUI boundary while retaining Markdown's
+ * printable syntax and line structure. Tool result content remains unchanged.
+ */
+export function sanitizePresentation(value: string): string {
+  return value
+    .replace(OSC_SEQUENCE, "")
+    .replace(STRING_TERMINATED_SEQUENCE, "")
+    .replace(CSI_SEQUENCE, "")
+    .replace(ESC_SEQUENCE, "")
+    .replace(UNSAFE_CONTROLS, "");
+}
+
+/** Read model-facing content without modifying it, then make a presentation-safe copy. */
+export function resultText(result: ToolResult): string {
+  const text = result.content?.filter((part) => part.type === "text").map((part) => part.text ?? "").join("\n") ?? "";
+  return sanitizePresentation(text);
+}
+
+export function renderToolCall(toolName: string, target: string | undefined, theme: Theme): Text {
+  const safeToolName = sanitizePresentation(toolName);
+  const safeTarget = target ? sanitizePresentation(target) : "";
+  return new Text(
+    `${theme.fg("toolTitle", theme.bold(`${safeToolName} `))}${safeTarget ? theme.fg("accent", safeTarget) : ""}`,
+    0,
+    0,
+  );
+}
+
+export function renderCompactCard(options: {
+  status: "success" | "warning" | "error" | "pending";
+  title: string;
+  summary: string;
+  metadata?: string;
+  /** Items render inline on wide terminals and stack below 80 columns. */
+  responsiveMetadata?: string[];
+}, theme: Theme): Component {
+  const status = {
+    success: ["✓", "success"],
+    warning: ["⚠", "warning"],
+    error: ["✗", "error"],
+    pending: ["…", "muted"],
+  } as const;
+  const [icon, color] = status[options.status];
+  const title = sanitizePresentation(options.title);
+  const summary = sanitizePresentation(options.summary);
+  const metadata = options.metadata ? sanitizePresentation(options.metadata) : undefined;
+  const responsiveMetadata = options.responsiveMetadata?.map(sanitizePresentation).filter(Boolean);
+  const header = `${theme.fg(color, icon)} ${theme.fg("accent", theme.bold(title))} ${theme.fg("muted", summary)}`;
+  const hint = keyHint("app.tools.expand", "view details");
+
+  if (!responsiveMetadata?.length) {
+    const detail = metadata ? `${metadata} · ${hint}` : hint;
+    return new Text([header, theme.fg("dim", detail)].join("\n"), 0, 0);
+  }
+
+  return {
+    invalidate() {},
+    render(width: number): string[] {
+      const details = width < 80
+        ? [...responsiveMetadata.map((item) => theme.fg("dim", item)), theme.fg("dim", hint)]
+        : [theme.fg("dim", `${responsiveMetadata.join(" · ")} · ${hint}`)];
+      return new Text([header, ...details].join("\n"), 0, 0).render(width);
+    },
+  };
+}
+
+export function renderExpandedMarkdown(options: {
+  status: "success" | "warning" | "error" | "pending";
+  title: string;
+  summary: string;
+  metadata?: string[];
+  markdown: string;
+}, theme: Theme): Container {
+  const status = {
+    success: ["✓", "success"],
+    warning: ["⚠", "warning"],
+    error: ["✗", "error"],
+    pending: ["…", "muted"],
+  } as const;
+  const [icon, color] = status[options.status];
+  const title = sanitizePresentation(options.title);
+  const summary = sanitizePresentation(options.summary);
+  const container = new Container();
+  container.addChild(new Text(
+    `${theme.fg(color, icon)} ${theme.fg("accent", theme.bold(title))} ${theme.fg("muted", summary)}`,
+    0,
+    0,
+  ));
+  for (const detail of options.metadata ?? []) container.addChild(new Text(theme.fg("dim", sanitizePresentation(detail)), 0, 0));
+  container.addChild(new Text(theme.fg("dim", keyHint("app.tools.expand", "collapse")), 0, 0));
+  container.addChild(new Markdown(sanitizePresentation(options.markdown), 0, 1, getMarkdownTheme()));
+  return container;
+}

package/.pi/extensions/takomi-context-manager/types.ts

@@ -2,6 +2,12 @@ export type SkillRecord = {
   name: string;
   description?: string;
   location?: string;
+  /** Explicit skill metadata, preferred over all other category sources. */
+  category?: string;
+  /** Category supplied by an installer/source registry for this exact skill path. */
+  sourceCategory?: string;
+  /** Package/source identifier used only when no explicit, registry, or path category exists. */
+  packageName?: string;
   source: "systemPromptOptions" | "xml" | "filesystem" | "tool";
 };
 

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

@@ -28,6 +28,7 @@ export type TakomiRuntimeCommandState = {
 type RegisterTakomiCommandOptions = {
   getState(): TakomiRuntimeCommandState;
   updateState(ctx: ExtensionContext, mutator: () => void, message?: string | (() => string)): Promise<void>;
+  recordUserGateAutoProvenance(authorized: boolean): void;
   resetRuntime(ctx: ExtensionCommandContext): Promise<void>;
   setStageAndWorkflow(stage: VibeLifecycleStage, options?: { preserveRole?: boolean }): void;
   createPlanSession(ctx: ExtensionCommandContext, title?: string): Promise<string>;
@@ -36,6 +37,13 @@ type RegisterTakomiCommandOptions = {
 };
 
 export function registerTakomiCommands(pi: ExtensionAPI, options: RegisterTakomiCommandOptions): void {
+  // The custom runtime widget is intentionally absent in idle/direct mode, so
+  // suppress routine notifications only while the changed state remains visible.
+  function hasVisibleRuntimeWidget(): boolean {
+    const state = options.getState();
+    return state.enabled && (state.modeSource ?? "idle") !== "idle";
+  }
+
   async function handleStage(ctx: ExtensionCommandContext, stage: VibeLifecycleStage, prompt?: string): Promise<void> {
     await options.updateState(ctx, () => {
       options.getState().enabled = true;
@@ -75,26 +83,30 @@ export function registerTakomiCommands(pi: ExtensionAPI, options: RegisterTakomi
         state.autoOrch = false;
         state.planMode = true;
         state.launchMode = "manual";
+        options.recordUserGateAutoProvenance(false);
         state.role = "review";
         state.stage = undefined;
         state.workflow = undefined;
         state.modeSource = "manual";
         state.modeReason = "/takomi mode review";
       }
-    }, () => `Takomi mode set to ${mode}`);
+    }, () => hasVisibleRuntimeWidget() ? "" : `Takomi mode set to ${mode}`);
   }
 
   async function handleGate(ctx: ExtensionCommandContext, gate?: string): Promise<void> {
-    if (gate !== "auto" && gate !== "review") {
-      ctx.ui.notify("Usage: /takomi gate <auto|review>", "warning");
+    if (gate !== "auto" && gate !== "review" && gate !== "manual") {
+      ctx.ui.notify("Usage: /takomi gate <auto|review|manual>", "warning");
       return;
     }
+    const auto = gate === "auto";
     await options.updateState(ctx, () => {
       const state = options.getState();
       state.enabled = true;
-      state.launchMode = gate === "review" ? "manual" : "auto";
-      state.autoOrch = gate === "auto";
-    }, () => `Takomi execution gate set to ${gate}`);
+      state.launchMode = auto ? "auto" : "manual";
+      state.autoOrch = auto;
+      // This dedicated entry is the only user-gate authorization signal.
+      options.recordUserGateAutoProvenance(auto);
+    }, () => hasVisibleRuntimeWidget() ? "" : `Takomi execution gate set to ${auto ? "auto" : "review"}`);
   }
 
   async function handleRouting(ctx: ExtensionCommandContext, body?: string): Promise<void> {
@@ -173,20 +185,41 @@ export function registerTakomiCommands(pi: ExtensionAPI, options: RegisterTakomi
     const policyText = scopeMatch?.[2] ?? trimmed.replace(/^set\s+/i, "");
 
     try {
-      const preview = previewTakomiRoutingPolicy(ctx.cwd, policyText, { scope });
+      const availableModels = (() => {
+        try {
+          const available = (ctx as ExtensionCommandContext & { modelRegistry?: { getAvailable?: () => Array<{ provider?: string; id?: string; name?: string }> } }).modelRegistry?.getAvailable?.() ?? [];
+          return available.map((model) => `${model.provider ? `${model.provider}/` : ""}${model.id ?? model.name ?? ""}`).filter(Boolean);
+        } catch {
+          return [];
+        }
+      })();
+      const [preview, activePolicy] = await Promise.all([
+        Promise.resolve(previewTakomiRoutingPolicy(ctx.cwd, policyText, { scope, availableModels })),
+        resolveTakomiRoutingPolicy(ctx.cwd),
+      ]);
+      const replacementWarning = activePolicy.text && activePolicy.text.trim().length > preview.policy.trim().length * 2
+        ? `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.",
         "",
         "Rules:",
         "- Do not invent providers or model IDs not grounded in the policy.",
-        "- Providerless names like GPT-5.5 are routing intent unless a preferred provider/router is declared.",
-        "- Valid Takomi roles are: general, orchestrator, architect, designer, coder, reviewer.",
-        "- If the extraction is correct and safe, call takomi_apply_routing_policy with the exact policyText and scope below.",
-        "- If it is ambiguous or wrong, explain what the user should clarify and do not call the tool.",
+        "- 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.",
+        "- 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.",
         "",
         "Deterministic extraction:",
         renderRoutingPolicyPreview(preview),
         "",
+        replacementWarning,
+        "",
+        availableModels.length ? `Available Pi models:\n${availableModels.map((model) => `- ${model}`).join("\n")}` : "Available Pi models: registry unavailable; inspect it before asking the user if possible.",
+        "",
         "Original policy text:",
         "```",
         preview.policy,
@@ -217,7 +250,7 @@ export function registerTakomiCommands(pi: ExtensionAPI, options: RegisterTakomi
     if (action === "on" || action === "off") {
       await options.updateState(ctx, () => {
         options.getState().subagentsEnabled = action === "on";
-      }, `Takomi subagents ${action}`);
+      }, () => hasVisibleRuntimeWidget() ? "" : `Takomi subagents ${action}`);
       return;
     }
     if (action === "status" || !action) {

package/.pi/extensions/takomi-runtime/gate-provenance.ts

@@ -0,0 +1,24 @@
+export const USER_GATE_AUTO_PROVENANCE_ENTRY = "takomi-user-gate-auto-provenance";
+
+type SessionEntry = {
+  type?: unknown;
+  customType?: unknown;
+  data?: unknown;
+};
+
+function isAuthorizedData(value: unknown): value is { authorized: true } {
+  return typeof value === "object" && value !== null && (value as { authorized?: unknown }).authorized === true;
+}
+
+/**
+ * Reads the latest explicit user gate decision from session history.
+ * This deliberately ignores generic runtime state and profile defaults.
+ */
+export function hasUserGateAutoProvenance(entries: readonly SessionEntry[]): boolean {
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const entry = entries[index];
+    if (entry?.type !== "custom" || entry.customType !== USER_GATE_AUTO_PROVENANCE_ENTRY) continue;
+    return isAuthorizedData(entry.data);
+  }
+  return false;
+}