takomi 2.1.36 → 2.1.38

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

@@ -6,6 +6,7 @@ import type { ContextManagerState } from "./state";
 import { recordBlocked } from "./state";
 import { resolveTakomiRoutingPolicy } from "../takomi-runtime/routing-policy";
 import { approvedModelEquivalent, isTakomiModelApproved } from "../takomi-runtime/model-routing-defaults";
+import { persistReportSnapshot } from "./session-state";
 
 type Settings = {
   takomi?: { modelRoutingPolicyFile?: string };
@@ -183,19 +184,19 @@ export function installModelPolicyGate(pi: ExtensionAPI, state: ContextManagerSt
     if (approved.length === 0) return;
 
     const refs = collectRequestedModelRefs(event.input);
-    const corrections: string[] = [];
+    const corrections: Array<{ from: string; to: string; recovery?: string }> = [];
     for (const ref of refs) {
       if (isTakomiModelApproved(ref.value, approved)) continue;
       const equivalent = approvedModelEquivalent(ref.value, approved);
       if (equivalent) {
         setModelRef(ref, equivalent);
-        corrections.push(`${ref.value} -> ${equivalent}`);
+        corrections.push({ from: ref.value, to: equivalent });
         continue;
       }
       const recovery = await askForInvalidModelRecovery(ctx, ref.value, approved);
       if (recovery.action === "retry") {
         setModelRef(ref, recovery.model);
-        corrections.push(`${ref.value} -> ${recovery.model} (user selected recovery)`);
+        corrections.push({ from: ref.value, to: recovery.model, recovery: "user selected recovery" });
         continue;
       }
       const reason = [
@@ -204,12 +205,23 @@ export function installModelPolicyGate(pi: ExtensionAPI, state: ContextManagerSt
         "Human selected stop. The agent turn has been aborted; wait for the user's next prompt.",
       ].join("\n");
       recordBlocked(state, event.toolName, reason);
+      persistReportSnapshot(pi, state, "model-policy-gate-block");
       ctx.abort?.();
       return { block: true, reason };
     }
 
     if (corrections.length > 0) {
-      ctx.ui.notify(`Takomi context manager corrected subagent model routing:\n- ${corrections.join("\n- ")}\n\nBe careful to follow /takomi routing policy next time.`, "warning");
+      const timestamp = new Date().toISOString();
+      state.report.timestamp = timestamp;
+      state.report.modelRoutingCorrections.push(...corrections.map((correction) => ({
+        toolName: event.toolName,
+        from: correction.from,
+        to: correction.to,
+        recovery: correction.recovery,
+        timestamp,
+      })));
+      persistReportSnapshot(pi, state, "model-policy-correction");
+      ctx.ui.notify(`Takomi context manager corrected subagent model routing:\n- ${corrections.map((correction) => `${correction.from} -> ${correction.to}${correction.recovery ? ` (${correction.recovery})` : ""}`).join("\n- ")}\n\nBe careful to follow /takomi routing policy next time.`, "warning");
     }
   });
 

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

@@ -3,6 +3,7 @@ import { Type } from "typebox";
 import type { ContextManagerState } from "./state";
 import { syncReportLedger } from "./state";
 import { renderPolicies, renderPolicyManifest } from "./policy-registry";
+import { persistReportSnapshot, restoreReportFromSession } from "./session-state";
 
 export function registerPolicyTools(pi: ExtensionAPI, state: ContextManagerState): void {
   pi.registerTool({
@@ -12,8 +13,11 @@ export function registerPolicyTools(pi: ExtensionAPI, state: ContextManagerState
     promptSnippet: "Show available context policy pack descriptions",
     parameters: Type.Object({ policies: Type.Optional(Type.Array(Type.String({ description: "Policy name to inspect" }))) }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      restoreReportFromSession(state, ctx);
+      state.report.timestamp = new Date().toISOString();
       state.report.cwd = ctx.cwd;
       state.report.toolCalls.policyManifest += 1;
+      persistReportSnapshot(pi, state, "policy_manifest");
       return { content: [{ type: "text", text: renderPolicyManifest(state.policies, params.policies ?? []) }], details: { requested: params.policies ?? [...state.policies.keys()] } };
     },
   });
@@ -25,10 +29,13 @@ export function registerPolicyTools(pi: ExtensionAPI, state: ContextManagerState
     promptSnippet: "Load policy packs required before sensitive tool calls",
     parameters: Type.Object({ policies: Type.Array(Type.String({ description: "Policy pack name to load" })) }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      restoreReportFromSession(state, ctx);
+      state.report.timestamp = new Date().toISOString();
       state.report.cwd = ctx.cwd;
       state.report.toolCalls.policyLoad += 1;
       const text = renderPolicies(state.policies, state.loadedPolicies, params.policies);
       syncReportLedger(state);
+      persistReportSnapshot(pi, state, "policy_load");
       return { content: [{ type: "text", text }], details: { requested: params.policies, loadedPolicies: [...state.loadedPolicies].sort() } };
     },
   });

package/.pi/extensions/takomi-context-manager/prerequisite-gates.ts

@@ -3,6 +3,7 @@ import type { ContextManagerConfig } from "./types";
 import type { ContextManagerState } from "./state";
 import { recordBlocked, syncReportLedger } from "./state";
 import { renderPolicies } from "./policy-registry";
+import { persistReportSnapshot } from "./session-state";
 
 function renderPolicyGateBlock(toolName: string, missing: string[], policyText: string): string {
   return [
@@ -33,6 +34,7 @@ export function installPrerequisiteGates(pi: ExtensionAPI, state: ContextManager
       syncReportLedger(state);
       const reason = renderPolicyGateBlock(event.toolName, missing, policyText);
       recordBlocked(state, event.toolName, reason);
+      persistReportSnapshot(pi, state, "prerequisite-gate-block");
       return { block: true, reason };
     }
   });

package/.pi/extensions/takomi-context-manager/session-state.ts

@@ -0,0 +1,160 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ContextManagerState } from "./state";
+import type { ContextReport } from "./types";
+
+const SNAPSHOT_TYPE = "takomi-context-manager-report";
+const TOOL_NAMES = ["skill_index", "skill_manifest", "skill_load", "policy_manifest", "policy_load", "context_report"] as const;
+type ToolName = typeof TOOL_NAMES[number];
+
+type RestoreStats = {
+  snapshotCount: number;
+  toolResultCount: number;
+};
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
+function uniqueSorted(values: Iterable<string>): string[] {
+  return [...new Set([...values].filter(Boolean))].sort((a, b) => a.localeCompare(b));
+}
+
+function mergeReports(base: ContextReport, restored: ContextReport | undefined): ContextReport {
+  if (!restored) return base;
+  return {
+    ...base,
+    ...restored,
+    toolCalls: { ...base.toolCalls, ...restored.toolCalls },
+    promptRewrite: { ...base.promptRewrite, ...restored.promptRewrite },
+    sessionRestore: { ...base.sessionRestore, ...restored.sessionRestore },
+  };
+}
+
+function maxToolCalls(a: ContextReport["toolCalls"], b: ContextReport["toolCalls"]): ContextReport["toolCalls"] {
+  return {
+    skillIndex: Math.max(a.skillIndex, b.skillIndex),
+    skillManifest: Math.max(a.skillManifest, b.skillManifest),
+    skillLoad: Math.max(a.skillLoad, b.skillLoad),
+    policyManifest: Math.max(a.policyManifest, b.policyManifest),
+    policyLoad: Math.max(a.policyLoad, b.policyLoad),
+    contextReport: Math.max(a.contextReport, b.contextReport),
+  };
+}
+
+function incrementTool(calls: ContextReport["toolCalls"], toolName: ToolName): void {
+  if (toolName === "skill_index") calls.skillIndex += 1;
+  if (toolName === "skill_manifest") calls.skillManifest += 1;
+  if (toolName === "skill_load") calls.skillLoad += 1;
+  if (toolName === "policy_manifest") calls.policyManifest += 1;
+  if (toolName === "policy_load") calls.policyLoad += 1;
+  if (toolName === "context_report") calls.contextReport += 1;
+}
+
+function getEntryData(entry: unknown): unknown {
+  const record = asRecord(entry);
+  if (record.type === "custom" && record.customType === SNAPSHOT_TYPE) return record.data;
+  const message = asRecord(record.message);
+  if (message.role === "custom" && message.customType === SNAPSHOT_TYPE) return message.details ?? message.content;
+  return undefined;
+}
+
+function getToolResult(entry: unknown): { toolName?: string; details?: Record<string, unknown> } | undefined {
+  const record = asRecord(entry);
+  if (record.type !== "message") return undefined;
+  const message = asRecord(record.message);
+  if (message.role !== "toolResult") return undefined;
+  return { toolName: typeof message.toolName === "string" ? message.toolName : undefined, details: asRecord(message.details) };
+}
+
+function getEntries(ctx: unknown): unknown[] {
+  const manager = asRecord(ctx).sessionManager as { getEntries?: () => unknown[]; getBranch?: () => unknown[] } | undefined;
+  try {
+    return manager?.getEntries?.() ?? manager?.getBranch?.() ?? [];
+  } catch {
+    return [];
+  }
+}
+
+function extractSnapshot(data: unknown): ContextReport | undefined {
+  const record = asRecord(data);
+  const report = asRecord(record.report);
+  if (!report || typeof report.timestamp !== "string") return undefined;
+  return report as ContextReport;
+}
+
+export function restoreReportFromSession(state: ContextManagerState, ctx: unknown): RestoreStats {
+  const entries = getEntries(ctx);
+  let latestSnapshot: ContextReport | undefined;
+  let snapshotCount = 0;
+  let toolResultCount = 0;
+  const countedToolCalls: ContextReport["toolCalls"] = { skillIndex: 0, skillManifest: 0, skillLoad: 0, policyManifest: 0, policyLoad: 0, contextReport: 0 };
+  const loadedSkills = new Set(state.report.loadedByTool);
+  const loadedPolicies = new Set(state.report.loadedPolicies);
+
+  for (const entry of entries) {
+    const snapshot = extractSnapshot(getEntryData(entry));
+    if (snapshot) {
+      snapshotCount += 1;
+      if (!latestSnapshot || snapshot.timestamp >= latestSnapshot.timestamp) latestSnapshot = snapshot;
+    }
+
+    const toolResult = getToolResult(entry);
+    if (!toolResult?.toolName || !(TOOL_NAMES as readonly string[]).includes(toolResult.toolName)) continue;
+    toolResultCount += 1;
+    incrementTool(countedToolCalls, toolResult.toolName as ToolName);
+    if (toolResult.toolName === "skill_load" && typeof toolResult.details?.skill === "string") loadedSkills.add(toolResult.details.skill);
+    if (toolResult.toolName === "policy_load" && Array.isArray(toolResult.details?.loadedPolicies)) {
+      for (const policy of toolResult.details.loadedPolicies) if (typeof policy === "string") loadedPolicies.add(policy);
+    }
+  }
+
+  state.report = mergeReports(state.report, latestSnapshot);
+  state.report.loadedByTool ??= [];
+  state.report.loadedPolicies ??= [];
+  state.report.blockedActions ??= [];
+  state.report.modelRoutingCorrections ??= [];
+  state.report.duplicateExtensionWarnings ??= [];
+  for (const skill of state.report.loadedByTool) loadedSkills.add(skill);
+  for (const policy of state.report.loadedPolicies) loadedPolicies.add(policy);
+  state.report.toolCalls = maxToolCalls(state.report.toolCalls, countedToolCalls);
+  state.report.loadedByTool = uniqueSorted(loadedSkills);
+  state.report.loadedPolicies = uniqueSorted(loadedPolicies);
+  state.loadedPolicies = new Set(state.report.loadedPolicies);
+  state.report.sessionRestore = {
+    attempted: true,
+    restored: Boolean(latestSnapshot) || toolResultCount > 0,
+    snapshotCount,
+    toolResultCount,
+    note: latestSnapshot
+      ? "Restored from Takomi context-manager snapshots and Pi tool-result history in the current session file."
+      : toolResultCount > 0
+        ? "Restored from Pi tool-result history in the current session file; no context-manager snapshot was found."
+        : "No prior context-manager snapshots or tool results were found in the current session file.",
+  };
+  return { snapshotCount, toolResultCount };
+}
+
+function compactReason(reason: string): string {
+  const firstMeaningfulLine = reason.split(/\r?\n/).map((line) => line.trim()).find(Boolean) ?? reason;
+  if (/Loaded policy context:/i.test(reason)) return `${firstMeaningfulLine}\n[policy content omitted from persisted context-manager snapshot]`;
+  return reason.length > 1200 ? `${reason.slice(0, 1200)}…\n[truncated in persisted context-manager snapshot]` : reason;
+}
+
+function snapshotReport(report: ContextReport): ContextReport {
+  return {
+    ...report,
+    blockedActions: report.blockedActions.map((action) => ({ ...action, reason: compactReason(action.reason) })),
+  };
+}
+
+export function persistReportSnapshot(pi: ExtensionAPI, state: ContextManagerState, reason: string): void {
+  try {
+    pi.appendEntry(SNAPSHOT_TYPE, {
+      version: 1,
+      reason,
+      report: snapshotReport(state.report),
+    });
+  } catch {
+    // Persistence should never break agent startup or tool execution.
+  }
+}

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

@@ -1,3 +1,6 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
 import type { SkillRecord } from "./types";
 
 export function normalizeText(value: string): string {
@@ -85,3 +88,120 @@ export function findSkill(skills: Map<string, SkillRecord>, name: string): Skill
   const matches = sortedSkills(skills).filter((skill) => normalizeName(skill.name).includes(key));
   return matches.length === 1 ? matches[0] : undefined;
 }
+
+function parseFrontmatter(text: string): Record<string, string> {
+  const match = text.match(/^---\s*\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return {};
+  const data: Record<string, string> = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const parsed = line.match(/^([a-zA-Z0-9_-]+):\s*(.*)$/);
+    if (!parsed) continue;
+    data[parsed[1]] = parsed[2].replace(/^['\"]|['\"]$/g, "").trim();
+  }
+  return data;
+}
+
+async function pathExists(filePath: string): Promise<boolean> {
+  try {
+    await stat(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readSkillFile(filePath: string): Promise<SkillRecord | undefined> {
+  try {
+    const text = await readFile(filePath, "utf8");
+    const frontmatter = parseFrontmatter(text);
+    const name = frontmatter.name?.trim() || path.basename(path.dirname(filePath));
+    const description = frontmatter.description?.trim();
+    if (!name || !description) return undefined;
+    return { name, description, location: filePath, source: "filesystem" };
+  } catch {
+    return undefined;
+  }
+}
+
+async function collectSkillFiles(root: string, directMarkdownFiles = false, depth = 0, maxDepth = 8): Promise<string[]> {
+  if (depth > maxDepth || !await pathExists(root)) return [];
+  let entries: Array<{ name: string; isDirectory(): boolean; isFile(): boolean }> = [];
+  try {
+    entries = await readdir(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const files: string[] = [];
+  if (await pathExists(path.join(root, "SKILL.md"))) files.push(path.join(root, "SKILL.md"));
+  if (directMarkdownFiles && depth === 0) {
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) files.push(path.join(root, entry.name));
+    }
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if ([".git", "node_modules"].includes(entry.name)) continue;
+    files.push(...await collectSkillFiles(path.join(root, entry.name), false, depth + 1, maxDepth));
+  }
+  return [...new Set(files)];
+}
+
+async function collectPackageSkillRoots(nodeModulesRoot: string): Promise<string[]> {
+  if (!await pathExists(nodeModulesRoot)) return [];
+  const roots: string[] = [];
+  let packages: Array<{ name: string; isDirectory(): boolean }> = [];
+  try {
+    packages = await readdir(nodeModulesRoot, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  for (const pkg of packages) {
+    if (!pkg.isDirectory()) continue;
+    if (pkg.name.startsWith("@")) {
+      const scopeRoot = path.join(nodeModulesRoot, pkg.name);
+      let scoped: Array<{ name: string; isDirectory(): boolean }> = [];
+      try {
+        scoped = await readdir(scopeRoot, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const scopedPkg of scoped) if (scopedPkg.isDirectory()) roots.push(path.join(scopeRoot, scopedPkg.name, "skills"));
+      continue;
+    }
+    roots.push(path.join(nodeModulesRoot, pkg.name, "skills"));
+  }
+  return roots;
+}
+
+function ancestorSkillRoots(cwd: string): string[] {
+  const roots: string[] = [];
+  let current = path.resolve(cwd || process.cwd());
+  const seen = new Set<string>();
+  while (!seen.has(current)) {
+    seen.add(current);
+    roots.push(path.join(current, ".agents", "skills"));
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  roots.push(path.resolve(cwd || process.cwd(), ".pi", "skills"));
+  return roots;
+}
+
+export async function discoverSkillsFromFilesystem(cwd = process.cwd()): Promise<SkillRecord[]> {
+  const home = os.homedir();
+  const roots = [
+    { root: path.join(home, ".pi", "agent", "skills"), directMarkdownFiles: true },
+    { root: path.join(home, ".agents", "skills"), directMarkdownFiles: false },
+    ...ancestorSkillRoots(cwd).map((root) => ({ root, directMarkdownFiles: root.endsWith(`${path.sep}.pi${path.sep}skills`) })),
+    ...(await collectPackageSkillRoots(path.join(home, ".pi", "agent", "npm", "node_modules"))).map((root) => ({ root, directMarkdownFiles: false })),
+  ];
+  const skillFiles = new Set<string>();
+  for (const { root, directMarkdownFiles } of roots) {
+    for (const file of await collectSkillFiles(root, directMarkdownFiles)) skillFiles.add(file);
+  }
+  const skills = await Promise.all([...skillFiles].map(readSkillFile));
+  return skills.filter((skill): skill is SkillRecord => Boolean(skill));
+}

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

@@ -3,7 +3,8 @@ import path from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import type { ContextManagerState } from "./state";
-import { findSkill, normalizeName, sortedSkills } from "./skill-registry";
+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);
@@ -29,6 +30,12 @@ async function loadSkillContent(location: string): Promise<string> {
   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",
@@ -37,8 +44,12 @@ export function registerSkillTools(pi: ExtensionAPI, state: ContextManagerState)
     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 } };
     },
   });
@@ -50,8 +61,12 @@ export function registerSkillTools(pi: ExtensionAPI, state: ContextManagerState)
     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 } };
     },
   });
@@ -63,16 +78,24 @@ export function registerSkillTools(pi: ExtensionAPI, state: ContextManagerState)
     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) return { content: [{ type: "text", text: renderManifest(state, [params.skill]) }], details: { found: false, requested: params.skill }, isError: true };
+      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.push(skill.name);
+        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 };
       }
     },

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

@@ -23,7 +23,15 @@ export function createEmptyReport(): ContextReport {
     editedFiles: [],
     writtenFiles: [],
     blockedActions: [],
+    modelRoutingCorrections: [],
     duplicateExtensionWarnings: [],
+    sessionRestore: {
+      attempted: false,
+      restored: false,
+      snapshotCount: 0,
+      toolResultCount: 0,
+      note: "No session restore attempted yet.",
+    },
     promptRewrite: {
       attempted: false,
       changed: false,
@@ -63,6 +71,8 @@ export function syncReportLedger(state: ContextManagerState): void {
 }
 
 export function recordBlocked(state: ContextManagerState, toolName: string, reason: string): void {
-  state.report.blockedActions.push({ toolName, reason, timestamp: new Date().toISOString() });
+  const timestamp = new Date().toISOString();
+  state.report.timestamp = timestamp;
+  state.report.blockedActions.push({ toolName, reason, timestamp });
   syncReportLedger(state);
 }

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

@@ -2,7 +2,7 @@ export type SkillRecord = {
   name: string;
   description?: string;
   location?: string;
-  source: "systemPromptOptions" | "xml" | "tool";
+  source: "systemPromptOptions" | "xml" | "filesystem" | "tool";
 };
 
 export type CandidateContext = {
@@ -57,7 +57,15 @@ export type ContextReport = {
   editedFiles: string[];
   writtenFiles: string[];
   blockedActions: Array<{ toolName: string; reason: string; timestamp: string }>;
+  modelRoutingCorrections: Array<{ toolName: string; from: string; to: string; timestamp: string; recovery?: string }>;
   duplicateExtensionWarnings: Array<{ toolName: string; paths: string[] }>;
+  sessionRestore: {
+    attempted: boolean;
+    restored: boolean;
+    snapshotCount: number;
+    toolResultCount: number;
+    note: string;
+  };
   promptRewrite: {
     attempted: boolean;
     changed: boolean;

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

@@ -32,6 +32,7 @@ const SUBCOMMAND_COMPLETIONS: Record<string, TakomiCompletion[]> = {
     { value: "auto", label: "auto", description: "Continue approved plans automatically" },
   ],
   subagents: [
+    { value: "list", label: "list", description: "List available Takomi subagents" },
     { value: "status", label: "status", description: "Show active subagents" },
     { value: "on", label: "on", description: "Allow subagent delegation" },
     { value: "off", label: "off", description: "Disable subagent delegation" },
@@ -95,7 +96,7 @@ export function commandHelp(): string {
     "/takomi plan [title]",
     "/takomi mode <direct|orchestrate|review>",
     "/takomi gate <auto|review>",
-    "/takomi subagents <on|off|status>",
+    "/takomi subagents <list|on|off|status>",
     "/takomi stats [overview|daily|models|projects|projects-full|sessions|sessions-full|tasks|tasks-full|tools|subagents|sources] [since 7d]",
     "/takomi routing [show|where]",
     "/takomi routing <policy text>              # updates global policy",

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

@@ -9,6 +9,7 @@ import { commandHelp, completions, statusText, workflowPrompt } from "./command-
 import type { TakomiSubagentController } from "./subagent-types";
 import { previewTakomiRoutingPolicy, renderRoutingPolicyPreview, resolveTakomiRoutingPolicy, type RoutingPolicyInstallScope } from "./routing-policy";
 import { collectTakomiStats, renderTakomiStats } from "./takomi-stats.js";
+import { discoverTakomiAgents } from "../takomi-subagents/agents";
 
 export type TakomiRuntimeCommandState = {
   enabled: boolean;
@@ -202,6 +203,17 @@ export function registerTakomiCommands(pi: ExtensionAPI, options: RegisterTakomi
 
   async function handleSubagents(ctx: ExtensionCommandContext, action?: string): Promise<void> {
     const controller = options.subagentController;
+    if (action === "list" || action === "agents") {
+      const agents = discoverTakomiAgents(ctx.cwd, "both");
+      const lines = [
+        "Takomi subagents:",
+        ...(agents.length
+          ? agents.map((agent) => `- ${agent.name} (${agent.source}): ${agent.description}`)
+          : ["- (none discovered)"]),
+      ];
+      ctx.ui.notify(lines.join("\n"), agents.length ? "info" : "warning");
+      return;
+    }
     if (action === "on" || action === "off") {
       await options.updateState(ctx, () => {
         options.getState().subagentsEnabled = action === "on";
@@ -212,7 +224,7 @@ export function registerTakomiCommands(pi: ExtensionAPI, options: RegisterTakomi
       ctx.ui.notify(statusText(options.getState(), controller), controller.hasRuns() ? "info" : "warning");
       return;
     }
-    ctx.ui.notify("Usage: /takomi subagents <on|off|status>", "warning");
+    ctx.ui.notify("Usage: /takomi subagents <list|on|off|status>", "warning");
   }
 
   pi.registerCommand("takomi", {

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

@@ -31,8 +31,24 @@ const TaskSchema = Type.Object({
   checklist: Type.Optional(Type.Array(Type.Union([Type.String(), ChecklistItemSchema]))),
 });
 
+const ContextSchema = Type.Union([
+  Type.Literal("fresh"),
+  Type.Literal("fork"),
+]);
+
+const ActionSchema = Type.Union([
+  Type.Literal("list"),
+  Type.Literal("get"),
+  Type.Literal("models"),
+  Type.Literal("status"),
+  Type.Literal("interrupt"),
+  Type.Literal("resume"),
+  Type.Literal("doctor"),
+]);
+
 const SubagentParameters = Type.Object({
-  agent: Type.Optional(Type.String({ description: "Agent name for single execution" })),
+  action: Type.Optional(ActionSchema),
+  agent: Type.Optional(Type.String({ description: "Agent name for single execution, or target agent for get/models actions" })),
   task: Type.Optional(Type.String({ description: "Task for single execution" })),
   workflow: Type.Optional(Type.String({ description: "Workflow or playbook overlay for this task" })),
   skills: Type.Optional(Type.Array(Type.String(), { description: "Extra skills to apply during the task" })),
@@ -47,6 +63,14 @@ const SubagentParameters = Type.Object({
   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" })),
+  context: Type.Optional(ContextSchema),
+  async: Type.Optional(Type.Boolean({ description: "Run through native pi-subagents background/async mode" })),
+  concurrency: Type.Optional(Type.Number({ description: "Maximum concurrency for parallel task groups" })),
+  worktree: Type.Optional(Type.Boolean({ description: "Use native pi-subagents worktree isolation where supported" })),
+  id: Type.Optional(Type.String({ description: "Native async/control run id for status, interrupt, or resume actions" })),
+  message: Type.Optional(Type.String({ description: "Follow-up message for resume actions" })),
+  index: Type.Optional(Type.Number({ description: "Child index for resume actions when needed" })),
+  chainName: Type.Optional(Type.String({ description: "Saved chain name for get actions" })),
   agentScope: Type.Optional(Type.Union([Type.Literal("user"), Type.Literal("project"), Type.Literal("both")])),
   // Project-agent confirmation and hard-stop overrides are enforced server-side;
   // they are intentionally not model-callable parameters.
@@ -56,11 +80,14 @@ function registerSubagentTool(pi: ExtensionAPI): void {
   pi.registerTool({
     name: "takomi_subagent",
     label: "Takomi",
-    description: "Run subagents with Pi-style single, parallel, or chain modes plus Takomi lifecycle metadata.",
-    promptSnippet: "Delegate lifecycle-aware Takomi work to specialist subagents. Use single, tasks, or chain; reuse conversationId for review loops.",
+    description: "Run subagents with Pi-style single, parallel, chain, async, fork, and management/status modes plus Takomi lifecycle metadata.",
+    promptSnippet: "Delegate lifecycle-aware Takomi work to specialist subagents. Use single, tasks, chain, or action=list/status/doctor; reuse conversationId for review loops.",
     promptGuidelines: [
       "Use this tool during orchestration when a specialist should handle a task.",
+      "Use action=list to discover agents and action=status/doctor for native pi-subagents diagnostics/control instead of raw subagent.",
       "Use tasks for independent parallel work and chain for dependent handoffs with {previous}.",
+      "Set context=fork only when inherited parent-session history is needed; otherwise prefer fresh or the agent default.",
+      "Set async=true for long-running work when the parent can continue safely; keep active worktree writes single-threaded unless worktree isolation is enabled.",
       "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.",

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

@@ -171,12 +171,14 @@ export function renderTakomiSubagentResult(result: ToolResult, options: { expand
     return new Text(renderPolicyGateBlock(text, options.expanded, theme), 0, 0);
   }
 
+  const native = renderNativeSubagentResult(result, options, theme, context);
+  if (options.isPartial && native) return native;
+
   if (options.isPartial) {
     if (options.expanded) return new Text(livePartialText(result, theme), 0, 0);
     return new Text(summarizeCollapsedResult(text, status, theme), 0, 0);
   }
 
-  const native = renderNativeSubagentResult(result, options, theme, context);
   if (native) return native;
 
   if (!options.expanded) {