takomi 2.1.6 → 2.1.9

package/.pi/README.md

@@ -8,6 +8,7 @@ It is intentionally separate from the existing cross-harness assets under `asset
 
 - `extensions/takomi-runtime/` - Pi runtime glue, embedded workflow playbooks, and orchestrator board tools
 - `extensions/takomi-subagents/` - Takomi-facing subagent wrapper over Pi-style execution semantics with resumable conversation IDs
+- `extensions/takomi-context-manager/` - Progressive context loading, skill manifests, policy packs, model-routing gates, and context diagnostics
 - `prompts/` - Pi-native prompt shortcuts
 - `agents/` - Pi-native specialist agent definitions, including a design-stage agent
 
@@ -39,6 +40,7 @@ Inside Pi, use:
 - `/takomi subagents status|expand|collapse|fullscreen|next|prev|toggle` to inspect or reshape the active subagent stack
 - `/takomi-status` to show lifecycle, gate, session, and active subagent state
 - `/takomi-reset` to reset session-local Takomi runtime state
+- `/context-report` to inspect prompt compaction, skill loading, policy gates, model routing corrections, and duplicate extension diagnostics
 - `takomi_board` actions now include stage expansion, task updates, multi-task dispatch, and redispatch support for review loops
 - The old standalone commands (`/takomi-genesis`, `/takomi-design`, `/takomi-build`, `/takomi-kickoff`, `/autoorch`, `/orch`, `/architect`, `/code`, `/review`, and the `/takomi-subagent*` variants) are folded into `/takomi` subcommands so slash autocomplete stays small.
 - prompt shortcuts are suffixed with `-prompt` to avoid collisions with runtime commands, e.g. `/orch-prompt`, `/build-prompt`, `/design-prompt`, `/genesis-prompt`, `/takomi-prompt`, `/prime-prompt`
@@ -67,6 +69,7 @@ Bundled with Takomi now:
 
 - `.pi/extensions/takomi-runtime/`
 - `.pi/extensions/takomi-subagents/`
+- `.pi/extensions/takomi-context-manager/`
 - `.pi/prompts/`
 - `.pi/agents/`
 - `.pi/themes/`
@@ -112,6 +115,11 @@ So when working on packaging, agents should distinguish between:
 - Active Takomi subagent work now streams through the native Pi-style result UI instead of Takomi's older below-editor stack.
 - 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, review continuity, and board synchronization, but it no longer opens a custom subagent fullscreen overlay.
+- `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`.
+- `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` detects known duplicate global/project Takomi extension paths in `context_report` to help diagnose tool registration conflicts.
 - `takomi_board` can:
   - create a Genesis-first lifecycle session by default
   - expand a lifecycle stage into additional tasks

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

@@ -0,0 +1,42 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import type { ContextManagerConfig } from "./types";
+
+export const DEFAULT_CONFIG: ContextManagerConfig = {
+  candidateRouter: {
+    maxCandidates: 5,
+    highConfidence: 100,
+    mediumConfidence: 40,
+  },
+  policyPaths: [".pi/takomi", ".pi/takomi/policies"],
+  toolPrerequisites: {
+    takomi_subagent: [{ type: "policies", policies: ["model-routing"] }],
+  },
+  promptCompaction: {
+    compactModelRouting: true,
+    compactModelRegistry: true,
+    compactSkillDescriptions: true,
+  },
+};
+
+function mergeConfig(value: Partial<ContextManagerConfig>): ContextManagerConfig {
+  return {
+    ...DEFAULT_CONFIG,
+    ...value,
+    candidateRouter: { ...DEFAULT_CONFIG.candidateRouter, ...value.candidateRouter },
+    promptCompaction: { ...DEFAULT_CONFIG.promptCompaction, ...value.promptCompaction },
+    policyPaths: value.policyPaths ?? DEFAULT_CONFIG.policyPaths,
+    policyFiles: value.policyFiles,
+    toolPrerequisites: value.toolPrerequisites ?? DEFAULT_CONFIG.toolPrerequisites,
+  };
+}
+
+export async function loadConfig(cwd: string): Promise<ContextManagerConfig> {
+  const configPath = path.resolve(cwd, ".pi/takomi/context-manager/config.json");
+  try {
+    const raw = await readFile(configPath, "utf8");
+    return mergeConfig(JSON.parse(raw) as Partial<ContextManagerConfig>);
+  } catch {
+    return DEFAULT_CONFIG;
+  }
+}

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

@@ -0,0 +1,57 @@
+import type { CandidateContext, ContextManagerConfig, SkillRecord } from "./types";
+import { normalizeName, normalizeText, sortedSkills } from "./skill-registry";
+
+const STOPWORDS = new Set(["a", "an", "and", "are", "as", "for", "from", "in", "is", "it", "of", "on", "or", "the", "this", "to", "with", "when", "you"]);
+
+function meaningfulWords(value: string): string[] {
+  return normalizeText(value).split(" ").filter((word) => word.length >= 3 && !STOPWORDS.has(word));
+}
+
+function scoreSkill(prompt: string, skill: SkillRecord, config: ContextManagerConfig): CandidateContext | undefined {
+  const promptNorm = normalizeText(prompt);
+  if (!promptNorm) return undefined;
+  const reasons: string[] = [];
+  let score = 0;
+  const nameNorm = normalizeText(skill.name);
+  if (nameNorm && promptNorm.includes(nameNorm)) {
+    score += 100;
+    reasons.push("exact skill name match");
+  }
+  const nameWords = meaningfulWords(skill.name);
+  const matchedNameWords = nameWords.filter((word) => promptNorm.includes(word));
+  if (matchedNameWords.length > 0 && matchedNameWords.length === nameWords.length) {
+    score += 50;
+    reasons.push(`matched skill name words: ${matchedNameWords.join(", ")}`);
+  } else if (matchedNameWords.length > 0) {
+    score += 15 * matchedNameWords.length;
+    reasons.push(`partial skill name words: ${matchedNameWords.join(", ")}`);
+  }
+  const descriptionWords = meaningfulWords(skill.description ?? "").slice(0, 50);
+  const matchedDescriptionWords = [...new Set(descriptionWords.filter((word) => promptNorm.includes(word)))];
+  if (matchedDescriptionWords.length > 0) {
+    score += Math.min(50, matchedDescriptionWords.length * 10);
+    reasons.push(`description keywords: ${matchedDescriptionWords.slice(0, 5).join(", ")}`);
+  }
+  if (score < config.candidateRouter.mediumConfidence) return undefined;
+  const confidence = score >= config.candidateRouter.highConfidence ? "high" : "medium";
+  return {
+    name: skill.name,
+    score,
+    confidence,
+    suggestedAction: confidence === "high" ? "skill_load" : "skill_manifest",
+    reasons,
+  };
+}
+
+export function findCandidates(prompt: string, skills: Map<string, SkillRecord>, config: ContextManagerConfig): CandidateContext[] {
+  return sortedSkills(skills)
+    .map((skill) => scoreSkill(prompt, skill, config))
+    .filter((candidate): candidate is CandidateContext => Boolean(candidate))
+    .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name))
+    .slice(0, config.candidateRouter.maxCandidates);
+}
+
+export function renderCandidateHint(candidates: CandidateContext[]): string {
+  if (candidates.length === 0) return "";
+  return ["Potentially relevant skills:", ...candidates.map((candidate) => `- ${candidate.name} — use ${candidate.suggestedAction} if relevant`)].join("\n");
+}

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

@@ -0,0 +1,26 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "typebox";
+import type { ContextManagerState } from "./state";
+import { renderReport } from "./diagnostics";
+
+export function registerDiagnostics(pi: ExtensionAPI, state: ContextManagerState): void {
+  pi.registerTool({
+    name: "context_report",
+    label: "Context Report",
+    description: "Show takomi-context-manager diagnostics for prompt rewriting, candidates, policies, gates, and progressive skill loading.",
+    promptSnippet: "Show context manager diagnostics and prompt composition decisions",
+    parameters: Type.Object({ verbose: Type.Optional(Type.Boolean({ description: "Include skill and policy indexes in the report" })) }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      state.report.cwd = ctx.cwd;
+      state.report.toolCalls.contextReport += 1;
+      return { content: [{ type: "text", text: renderReport(state, params.verbose ?? false) }], details: state.report };
+    },
+  });
+
+  pi.registerCommand("context-report", {
+    description: "Show takomi-context-manager diagnostics",
+    handler: async (_args, ctx) => {
+      ctx.ui.notify(renderReport(state, true), "info");
+    },
+  });
+}

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

@@ -0,0 +1,53 @@
+import type { ContextManagerState } from "./state";
+import { sortedSkills } from "./skill-registry";
+import { syncReportLedger } from "./state";
+import { renderDuplicateExtensionGuidance } from "./extension-conflicts";
+
+export function renderReport(state: ContextManagerState, verbose = false): string {
+  syncReportLedger(state);
+  const report = state.report;
+  const reduction = report.promptRewrite.originalLength > 0
+    ? Math.round((1 - report.promptRewrite.rewrittenLength / report.promptRewrite.originalLength) * 1000) / 10
+    : 0;
+  const lines = [
+    "Takomi Context Manager Report",
+    `- Timestamp: ${report.timestamp}`,
+    `- CWD: ${report.cwd || "(unknown)"}`,
+    `- Skill count: ${report.skillCount}`,
+    `- Prompt rewrite attempted: ${report.promptRewrite.attempted ? "yes" : "no"}`,
+    `- Prompt changed: ${report.promptRewrite.changed ? "yes" : "no"}`,
+    `- Original prompt length: ${report.promptRewrite.originalLength} chars`,
+    `- Rewritten prompt length: ${report.promptRewrite.rewrittenLength} chars`,
+    `- Reduction: ${reduction}%`,
+    `- Removed sections: ${report.promptRewrite.removedSections.join(", ") || "none"}`,
+    `- Loaded skills: ${report.loadedByTool.join(", ") || "none"}`,
+    `- Loaded policies: ${report.loadedPolicies.join(", ") || "none"}`,
+    `- Read files: ${report.readFiles.length}`,
+    `- Edited files: ${report.editedFiles.length}`,
+    `- Written files: ${report.writtenFiles.length}`,
+    `- Blocked actions: ${report.blockedActions.length}`,
+    `- Duplicate extension warnings: ${report.duplicateExtensionWarnings.length}`,
+    `- Tool calls: skill_index=${report.toolCalls.skillIndex}, skill_manifest=${report.toolCalls.skillManifest}, skill_load=${report.toolCalls.skillLoad}, policy_manifest=${report.toolCalls.policyManifest}, policy_load=${report.toolCalls.policyLoad}, context_report=${report.toolCalls.contextReport}`,
+    `- Warnings: ${report.promptRewrite.warnings.join("; ") || "none"}`,
+  ];
+  if (report.candidates.length > 0) {
+    lines.push("- Candidates:");
+    for (const candidate of report.candidates) {
+      lines.push(`  - ${candidate.name} (${candidate.confidence}, ${candidate.score}): ${candidate.reasons.join("; ")}`);
+    }
+  } else {
+    lines.push("- Candidates: none");
+  }
+  if (report.duplicateExtensionWarnings.length > 0 || verbose) {
+    lines.push("", "Extension Conflict Diagnostics:", ...renderDuplicateExtensionGuidance(report.duplicateExtensionWarnings));
+  }
+  if (verbose) {
+    lines.push("", "Skill Index:", ...sortedSkills(state.skills).map((skill) => `- ${skill.name}`));
+    lines.push("", "Policy Packs:", ...[...state.policies.values()].map((policy) => `- ${policy.name}: ${policy.description}`));
+    if (report.blockedActions.length > 0) {
+      lines.push("", "Blocked Actions:");
+      for (const action of report.blockedActions.slice(-10)) lines.push(`- ${action.timestamp} ${action.toolName}: ${action.reason}`);
+    }
+  }
+  return lines.join("\n");
+}

package/.pi/extensions/takomi-context-manager/extension-conflicts.ts

@@ -0,0 +1,56 @@
+import { access } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type { ContextManagerState } from "./state";
+
+type KnownTakomiExtension = {
+  toolName: string;
+  relativePath: string;
+};
+
+const KNOWN_TAKOMI_EXTENSIONS: KnownTakomiExtension[] = [
+  { toolName: "takomi_workflow", relativePath: path.join("takomi-runtime", "index.ts") },
+  { toolName: "takomi_board", relativePath: path.join("takomi-runtime", "index.ts") },
+  { toolName: "takomi_subagent", relativePath: path.join("takomi-subagents", "index.ts") },
+];
+
+async function exists(filePath: string): Promise<boolean> {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function homePiExtensionsRoot(): string {
+  return path.join(os.homedir(), ".pi", "agent", "extensions");
+}
+
+export async function detectDuplicateTakomiExtensions(cwd: string): Promise<Array<{ toolName: string; paths: string[] }>> {
+  const globalRoot = homePiExtensionsRoot();
+  const projectRoot = path.resolve(cwd, ".pi", "extensions");
+  const warnings: Array<{ toolName: string; paths: string[] }> = [];
+
+  for (const known of KNOWN_TAKOMI_EXTENSIONS) {
+    const globalPath = path.join(globalRoot, known.relativePath);
+    const projectPath = path.join(projectRoot, known.relativePath);
+    if (await exists(globalPath) && await exists(projectPath)) {
+      warnings.push({ toolName: known.toolName, paths: [globalPath, projectPath] });
+    }
+  }
+
+  return warnings;
+}
+
+export function renderDuplicateExtensionGuidance(warnings: Array<{ toolName: string; paths: string[] }>): string[] {
+  if (warnings.length === 0) return ["- Duplicate Takomi extensions: none detected"];
+  const lines = ["- Duplicate Takomi extensions detected:"];
+  for (const warning of warnings) {
+    lines.push(`  - ${warning.toolName}`);
+    for (const filePath of warning.paths) lines.push(`    - ${filePath}`);
+  }
+  lines.push("- Recommended dev command: use scripts/pi-dev.ps1, which starts Pi with --no-extensions and explicit project-local Takomi extensions.");
+  lines.push("- For global Pi sessions, disable/remove one duplicate source or prefer explicit extension loading to avoid tool registration conflicts.");
+  return lines;
+}

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

@@ -0,0 +1,56 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { loadConfig, DEFAULT_CONFIG } from "./config";
+import { createState } from "./state";
+import { collectSkillsFromOptions, collectSkillsFromXml, mergeSkills } from "./skill-registry";
+import { discoverPolicies } from "./policy-registry";
+import { findCandidates } from "./context-router";
+import { rewritePrompt } from "./prompt-rewriter";
+import { registerSkillTools } from "./skill-tools";
+import { registerPolicyTools } from "./policy-tools";
+import { registerDiagnostics } from "./diagnostics-tools";
+import { installPrerequisiteGates } from "./prerequisite-gates";
+import { installModelPolicyGate } from "./model-policy-gate";
+import { detectDuplicateTakomiExtensions } from "./extension-conflicts";
+import type { ContextManagerConfig } from "./types";
+
+export default function takomiContextManager(pi: ExtensionAPI) {
+  const state = createState();
+  let config: ContextManagerConfig = DEFAULT_CONFIG;
+
+  registerSkillTools(pi, state);
+  registerPolicyTools(pi, state);
+  registerDiagnostics(pi, state);
+  installPrerequisiteGates(pi, state, () => config);
+  installModelPolicyGate(pi, state);
+
+  pi.on("before_agent_start", async (event, ctx) => {
+    config = await loadConfig(ctx.cwd);
+    state.policies = await discoverPolicies(ctx.cwd, config);
+    const duplicateExtensionWarnings = await detectDuplicateTakomiExtensions(ctx.cwd);
+    const optionSkills = collectSkillsFromOptions(event.systemPromptOptions);
+    const xmlSkills = collectSkillsFromXml(event.systemPrompt);
+    state.skills = mergeSkills([...optionSkills, ...xmlSkills]);
+
+    const candidates = findCandidates(event.prompt, state.skills, config);
+    const rewrite = rewritePrompt(event.systemPrompt, state.skills, candidates, config);
+    state.report = {
+      ...state.report,
+      timestamp: new Date().toISOString(),
+      cwd: ctx.cwd,
+      userPrompt: event.prompt,
+      skillCount: state.skills.size,
+      candidates,
+      duplicateExtensionWarnings,
+      promptRewrite: {
+        attempted: true,
+        changed: rewrite.changed,
+        originalLength: event.systemPrompt.length,
+        rewrittenLength: rewrite.prompt.length,
+        removedSections: rewrite.removedSections,
+        warnings: rewrite.warnings,
+      },
+    };
+
+    return { systemPrompt: rewrite.prompt };
+  });
+}

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

@@ -0,0 +1,213 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ContextManagerState } from "./state";
+import { recordBlocked } from "./state";
+
+type Settings = {
+  takomi?: { modelRoutingPolicyFile?: string };
+  subagents?: { agentOverrides?: Record<string, unknown> };
+};
+
+type ModelPolicySnapshot = {
+  approvedModels: string[];
+  preferredModels: string[];
+  sourceFiles: string[];
+};
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
+async function readSettings(cwd: string): Promise<Settings> {
+  try {
+    return JSON.parse(await readFile(path.resolve(cwd, ".pi/settings.json"), "utf8")) as Settings;
+  } catch {
+    return {};
+  }
+}
+
+function modelFamily(model: string): string {
+  return model.split("/").at(-1)?.toLowerCase() ?? model.toLowerCase();
+}
+
+function unique(values: string[]): string[] {
+  return [...new Set(values.filter(Boolean))];
+}
+
+function collectModelsFromSettings(settings: Settings): string[] {
+  const overrides = asRecord(settings.subagents?.agentOverrides);
+  const models: string[] = [];
+  for (const value of Object.values(overrides)) {
+    const record = asRecord(value);
+    if (typeof record.model === "string") models.push(record.model);
+    if (Array.isArray(record.fallbackModels)) {
+      for (const fallback of record.fallbackModels) if (typeof fallback === "string") models.push(fallback.split(":")[0]);
+    }
+  }
+  return models;
+}
+
+function isModelLike(value: string): boolean {
+  const lower = value.toLowerCase();
+  return /(^|\/)(gpt|claude|gemini|o[0-9]|qwen|deepseek|llama|mistral|kimi|grok|sonnet|haiku|opus|codex|mini|max)/i.test(lower)
+    || lower.includes("oauth-router/")
+    || lower.includes("openai-codex/")
+    || lower.includes("lmstudio/");
+}
+
+function collectModelsFromPolicy(text: string): string[] {
+  const explicit = (text.match(/[a-z0-9-]+\/[a-z0-9._-]+/gi) ?? []).filter(isModelLike);
+  const inferred: string[] = [];
+  if (/gpt[- ]?5\.5/i.test(text)) inferred.push("oauth-router/gpt-5.5");
+  if (/gpt[- ]?5\.4(?!\s*mini)/i.test(text)) inferred.push("oauth-router/gpt-5.4");
+  if (/gpt[- ]?5\.4\s*mini/i.test(text)) inferred.push("oauth-router/gpt-5.4-mini");
+  return unique([...explicit, ...inferred]);
+}
+
+async function loadSnapshot(cwd: string): Promise<ModelPolicySnapshot> {
+  const settings = await readSettings(cwd);
+  const settingsModels = collectModelsFromSettings(settings);
+  const sourceFiles: string[] = [];
+  let policyModels: string[] = [];
+  const configured = settings.takomi?.modelRoutingPolicyFile ?? ".pi/takomi/model-routing.md";
+  const policyPath = path.isAbsolute(configured) ? configured : path.resolve(cwd, configured);
+  try {
+    const text = await readFile(policyPath, "utf8");
+    sourceFiles.push(policyPath);
+    policyModels = collectModelsFromPolicy(text);
+  } catch {
+    // Routing policy may not exist yet.
+  }
+  const approvedModels = unique([...settingsModels, ...policyModels]);
+  return { approvedModels, preferredModels: settingsModels.length ? unique(settingsModels) : approvedModels, sourceFiles };
+}
+
+function collectRequestedModelRefs(input: unknown): Array<{ holder: Record<string, unknown>; key: string; value: string }> {
+  const refs: Array<{ holder: Record<string, unknown>; key: string; value: string }> = [];
+  function visit(value: unknown): void {
+    if (!value || typeof value !== "object") return;
+    if (Array.isArray(value)) {
+      for (const item of value) visit(item);
+      return;
+    }
+    const record = value as Record<string, unknown>;
+    for (const key of ["model", "preferredModel"]) {
+      if (typeof record[key] === "string") refs.push({ holder: record, key, value: record[key] });
+    }
+    if (Array.isArray(record.fallbackModels)) {
+      record.fallbackModels = record.fallbackModels.filter((item) => typeof item === "string");
+    }
+    for (const key of ["tasks", "chain"]) visit(record[key]);
+  }
+  visit(input);
+  return refs;
+}
+
+function approvedEquivalent(requested: string, approved: string[]): string | undefined {
+  const requestedFamily = modelFamily(requested);
+  return approved.find((candidate) => modelFamily(candidate) === requestedFamily);
+}
+
+function isModelFailure(text: string): boolean {
+  return /(unknown provider|provider.*not.*found|model.*not.*found|model.*unavailable|invalid model|unsupported model|auth|unauthorized|forbidden|rate limit|429|quota|context window|maximum context)/i.test(text);
+}
+
+function renderPolicyViolation(requested: string, approved: string[]): string {
+  return [
+    "Blocked by Takomi routing policy.",
+    "",
+    "Requested model:",
+    requested,
+    "",
+    "Allowed/preferred models include:",
+    ...(approved.length ? approved.map((model) => `- ${model}`) : ["- none discovered; run /takomi routing <policy text> first"]),
+    "",
+    "The subagent did not run. Ask the user how to proceed or retry with an approved model.",
+  ].join("\n");
+}
+
+type RecoveryChoice =
+  | { action: "retry"; model: string }
+  | { action: "stop" };
+
+async function askForInvalidModelRecovery(ctx: { ui: { select(title: string, options: string[]): Promise<string | undefined>; notify(message: string, level?: string): void }; abort?: () => void }, requested: string, approved: string[]): Promise<RecoveryChoice> {
+  if (approved.length === 0) return { action: "stop" };
+  const options = [
+    ...approved.map((model) => `Retry with ${model}`),
+    "Stop and let me send a new prompt",
+  ];
+  const choice = await ctx.ui.select(
+    `takomi_subagent requested a model outside your routing policy: ${requested}`,
+    options,
+  );
+  if (choice?.startsWith("Retry with ")) return { action: "retry", model: choice.replace("Retry with ", "") };
+  return { action: "stop" };
+}
+
+export function installModelPolicyGate(pi: ExtensionAPI, state: ContextManagerState): void {
+  pi.on("tool_call", async (event, ctx) => {
+    if (event.toolName !== "takomi_subagent") return;
+    const snapshot = await loadSnapshot(ctx.cwd);
+    const approved = snapshot.approvedModels;
+    if (approved.length === 0) return;
+
+    const refs = collectRequestedModelRefs(event.input);
+    const corrections: string[] = [];
+    for (const ref of refs) {
+      if (approved.includes(ref.value)) continue;
+      const equivalent = approvedEquivalent(ref.value, approved);
+      if (equivalent) {
+        ref.holder[ref.key] = equivalent;
+        corrections.push(`${ref.value} -> ${equivalent}`);
+        continue;
+      }
+      const recovery = await askForInvalidModelRecovery(ctx, ref.value, approved);
+      if (recovery.action === "retry") {
+        ref.holder[ref.key] = recovery.model;
+        corrections.push(`${ref.value} -> ${recovery.model} (user selected recovery)`);
+        continue;
+      }
+      const reason = [
+        renderPolicyViolation(ref.value, approved),
+        "",
+        "Human selected stop. The agent turn has been aborted; wait for the user's next prompt.",
+      ].join("\n");
+      recordBlocked(state, event.toolName, reason);
+      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");
+    }
+  });
+
+  pi.on("tool_result", async (event, ctx) => {
+    if (event.toolName !== "takomi_subagent" || !event.isError) return;
+    const content = JSON.stringify(event.content ?? "");
+    if (!isModelFailure(content)) return;
+
+    const snapshot = await loadSnapshot(ctx.cwd);
+    const options = [
+      ...snapshot.approvedModels.map((model) => `Retry with ${model}`),
+      "Stop and let me send a new prompt",
+    ];
+    const choice = await ctx.ui.select("Takomi subagent model/provider failure. How do you want to continue?", options);
+    const retryModel = choice?.startsWith("Retry with ") ? choice.replace("Retry with ", "") : undefined;
+    const stopped = !retryModel;
+    const guidance = [
+      "Takomi subagent failed with a model/provider-related error.",
+      "",
+      `Policy source: ${snapshot.sourceFiles.join(", ") || "not found"}`,
+      "Policy-approved models:",
+      ...(snapshot.approvedModels.length ? snapshot.approvedModels.map((model) => `- ${model}`) : ["- none discovered"]),
+      "",
+      stopped
+        ? "Human selected stop/no retry. The agent turn has been aborted; wait for the user's next prompt."
+        : `User selected retry with ${retryModel}. Retry takomi_subagent with model ${retryModel}.`,
+    ].join("\n");
+    if (stopped) ctx.abort?.();
+    return { content: [{ type: "text", text: guidance }], isError: true, terminate: stopped };
+  });
+}

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

@@ -0,0 +1,100 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import type { ContextManagerConfig, PolicyPack } from "./types";
+import { normalizeName } from "./skill-registry";
+
+function descriptionFromMarkdown(content: string): string {
+  const lines = content.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  const firstBody = lines.find((line) => !line.startsWith("#"));
+  return firstBody?.slice(0, 240) ?? "Policy pack";
+}
+
+async function readPolicyFile(name: string, filePath: string): Promise<PolicyPack | undefined> {
+  try {
+    const content = await readFile(filePath, "utf8");
+    return {
+      name,
+      description: descriptionFromMarkdown(content),
+      content,
+      path: filePath,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function addPolicy(policies: Map<string, PolicyPack>, policy: PolicyPack | undefined, override = false): void {
+  if (!policy) return;
+  const key = normalizeName(policy.name);
+  if (!override && policies.has(key)) return;
+  policies.set(key, policy);
+}
+
+async function discoverTakomiSettingsPolicy(cwd: string): Promise<PolicyPack | undefined> {
+  try {
+    const settingsPath = path.resolve(cwd, ".pi/settings.json");
+    const settings = JSON.parse(await readFile(settingsPath, "utf8")) as {
+      takomi?: { modelRoutingPolicyFile?: string };
+    };
+    const modelRoutingPolicyFile = settings.takomi?.modelRoutingPolicyFile;
+    if (!modelRoutingPolicyFile) return undefined;
+    return readPolicyFile("model-routing", path.resolve(cwd, modelRoutingPolicyFile));
+  } catch {
+    return undefined;
+  }
+}
+
+async function discoverExplicitPolicyFiles(cwd: string, config: ContextManagerConfig): Promise<PolicyPack[]> {
+  const entries = Object.entries(config.policyFiles ?? {});
+  const policies = await Promise.all(entries.map(([name, filePath]) => readPolicyFile(name, path.resolve(cwd, filePath))));
+  return policies.filter((policy): policy is PolicyPack => Boolean(policy));
+}
+
+export async function discoverPolicies(cwd: string, config: ContextManagerConfig): Promise<Map<string, PolicyPack>> {
+  const policies = new Map<string, PolicyPack>();
+
+  // Source-of-truth priority 1: explicit context-manager policy file mappings.
+  for (const policy of await discoverExplicitPolicyFiles(cwd, config)) {
+    addPolicy(policies, policy, true);
+  }
+
+  // Source-of-truth priority 2: Takomi's own routing artifact created by `/takomi routing`.
+  // The context manager must consume this file, not invent/own model routing policy text.
+  addPolicy(policies, await discoverTakomiSettingsPolicy(cwd), true);
+
+  // Source-of-truth priority 3: discovered markdown policy packs. These are supplemental/default packs.
+  for (const policyPath of config.policyPaths) {
+    const absolute = path.resolve(cwd, policyPath);
+    try {
+      const entries = await readdir(absolute, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+        const name = path.basename(entry.name, ".md");
+        addPolicy(policies, await readPolicyFile(name, path.join(absolute, entry.name)), false);
+      }
+    } catch {
+      // Optional policy directories may not exist.
+    }
+  }
+
+  return policies;
+}
+
+export function renderPolicyManifest(policies: Map<string, PolicyPack>, names: string[]): string {
+  const selected = names.length > 0 ? names : [...policies.keys()];
+  return selected.map((name) => {
+    const policy = policies.get(normalizeName(name));
+    if (!policy) return `Policy not found: ${name}`;
+    return [`Policy: ${policy.name}`, `Description: ${policy.description}`, `Location: ${policy.path ?? "(generated/default)"}`].join("\n");
+  }).join("\n\n");
+}
+
+export function renderPolicies(policies: Map<string, PolicyPack>, loaded: Set<string>, names: string[]): string {
+  if (names.length === 0) return "No policies requested.";
+  return names.map((name) => {
+    const policy = policies.get(normalizeName(name));
+    if (!policy) return `Policy not found: ${name}`;
+    loaded.add(policy.name);
+    return [`Policy: ${policy.name}`, `Description: ${policy.description}`, `Location: ${policy.path ?? "(generated/default)"}`, "", policy.content].join("\n");
+  }).join("\n\n---\n\n");
+}

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

@@ -0,0 +1,35 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "typebox";
+import type { ContextManagerState } from "./state";
+import { syncReportLedger } from "./state";
+import { renderPolicies, renderPolicyManifest } from "./policy-registry";
+
+export function registerPolicyTools(pi: ExtensionAPI, state: ContextManagerState): void {
+  pi.registerTool({
+    name: "policy_manifest",
+    label: "Policy Manifest",
+    description: "Return descriptions for available context policy packs without loading full policy content.",
+    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) {
+      state.report.cwd = ctx.cwd;
+      state.report.toolCalls.policyManifest += 1;
+      return { content: [{ type: "text", text: renderPolicyManifest(state.policies, params.policies ?? []) }], details: { requested: params.policies ?? [...state.policies.keys()] } };
+    },
+  });
+
+  pi.registerTool({
+    name: "policy_load",
+    label: "Policy Load",
+    description: "Load one or more context policy packs required before sensitive tools such as takomi_subagent.",
+    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) {
+      state.report.cwd = ctx.cwd;
+      state.report.toolCalls.policyLoad += 1;
+      const text = renderPolicies(state.policies, state.loadedPolicies, params.policies);
+      syncReportLedger(state);
+      return { content: [{ type: "text", text }], details: { requested: params.policies, loadedPolicies: [...state.loadedPolicies].sort() } };
+    },
+  });
+}

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

@@ -0,0 +1,39 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ContextManagerConfig } from "./types";
+import type { ContextManagerState } from "./state";
+import { recordBlocked, syncReportLedger } from "./state";
+import { renderPolicies } from "./policy-registry";
+
+function renderPolicyGateBlock(toolName: string, missing: string[], policyText: string): string {
+  return [
+    `Blocked ${toolName}: required policy context had not been loaded yet.`,
+    "",
+    "The required policy context is provided below and has now been marked as loaded for this session.",
+    "Retry the original tool call now, following the policy.",
+    "",
+    "Required policies:",
+    ...missing.map((policy) => `- ${policy}`),
+    "",
+    "Loaded policy context:",
+    policyText,
+  ].join("\n");
+}
+
+export function installPrerequisiteGates(pi: ExtensionAPI, state: ContextManagerState, getConfig: () => ContextManagerConfig): void {
+  pi.on("tool_call", async (event, ctx) => {
+    state.report.cwd = ctx.cwd;
+    const prereqs = getConfig().toolPrerequisites[event.toolName] ?? [];
+
+    for (const prereq of prereqs) {
+      if (prereq.type !== "policies") continue;
+      const missing = prereq.policies.filter((policy) => !state.loadedPolicies.has(policy));
+      if (missing.length === 0) continue;
+
+      const policyText = renderPolicies(state.policies, state.loadedPolicies, missing);
+      syncReportLedger(state);
+      const reason = renderPolicyGateBlock(event.toolName, missing, policyText);
+      recordBlocked(state, event.toolName, reason);
+      return { block: true, reason };
+    }
+  });
+}

package/.pi/extensions/takomi-context-manager/prompt-rewriter.ts

@@ -0,0 +1,81 @@
+import type { CandidateContext, ContextManagerConfig, SkillRecord } from "./types";
+import { renderCandidateHint } from "./context-router";
+import { sortedSkills } from "./skill-registry";
+
+function renderSkillIndex(skills: SkillRecord[]): string {
+  if (skills.length === 0) return "Skills: none discovered.";
+  return `Skills: ${skills.length} discovered. Use skill_index only when the task may need a skill.`;
+}
+
+function renderProgressiveRule(): string {
+  return [
+    "Skill loading:",
+    "- Skills are optional capability packs that give you special instructions/tools for specialized, repetitive tasks.",
+    "- Do not preload skill descriptions into the prompt.",
+    "- When doing specialized work, you may check whether a suited skill exists with skill_index.",
+    "- For uncertain matches, request skill_manifest for likely skills; manifests include descriptions and locations.",
+    "- If a skill is clearly relevant or the user names it directly, use skill_load without requesting a manifest first.",
+    "- Load full skill instructions only for skills you will actually use.",
+    "",
+    "Policy loading:",
+    "- Model/subagent/lifecycle policies are lazy-loaded policy packs.",
+    "- Use policy_manifest to inspect available policies.",
+    "- Use policy_load before sensitive tools such as takomi_subagent.",
+  ].join("\n");
+}
+
+function compactHeavyPolicyBlocks(prompt: string, config: ContextManagerConfig): { prompt: string; removedSections: string[] } {
+  let next = prompt;
+  const removedSections: string[] = [];
+  if (config.promptCompaction.compactModelRouting) {
+    const modelRoutingRegex = /Project Takomi model routing policy is active\. Apply it when choosing parent\/subagent models and escalation levels:\s*\n\n# Takomi Model Routing Policy[\s\S]*?(?=\nAvailable model context from Pi registry:)/;
+    if (modelRoutingRegex.test(next)) {
+      next = next.replace(modelRoutingRegex, [
+        "Project Takomi model routing policy is available as a lazy-loaded policy pack.",
+        "The subagent prerequisite gate can provide this policy automatically on first blocked takomi_subagent attempt, then the agent should retry.",
+        "",
+      ].join("\n"));
+      removedSections.push("full model routing policy");
+    }
+  }
+  if (config.promptCompaction.compactModelRegistry) {
+    const registryRegex = /Available model context from Pi registry:[^\n]*(?:\n|$)/;
+    if (registryRegex.test(next)) {
+      next = next.replace(registryRegex, "Available model registry context exists. The subagent policy gate will provide model routing context if needed.\n");
+      removedSections.push("verbose model registry list");
+    }
+  }
+  return { prompt: next, removedSections };
+}
+
+export function rewritePrompt(systemPrompt: string, skills: Map<string, SkillRecord>, candidates: CandidateContext[], config: ContextManagerConfig): {
+  prompt: string;
+  changed: boolean;
+  removedSections: string[];
+  warnings: string[];
+} {
+  const warnings: string[] = [];
+  const removedSections: string[] = [];
+  let next = systemPrompt;
+  let changed = false;
+
+  if (config.promptCompaction.compactSkillDescriptions) {
+    const replacement = [renderSkillIndex(sortedSkills(skills)), renderProgressiveRule(), renderCandidateHint(candidates)].filter(Boolean).join("\n\n");
+    const skillBlockRegex = /<available_skills>[\s\S]*?<\/available_skills>/i;
+    if (!skillBlockRegex.test(next)) {
+      warnings.push("No <available_skills> block found; appended progressive skill guidance instead.");
+      next = `${next}\n\n${replacement}`;
+      changed = true;
+    } else {
+      next = next.replace(skillBlockRegex, replacement);
+      changed = true;
+      removedSections.push("available_skills descriptions");
+    }
+  }
+
+  const compacted = compactHeavyPolicyBlocks(next, config);
+  next = compacted.prompt;
+  removedSections.push(...compacted.removedSections);
+  changed = changed || compacted.removedSections.length > 0;
+  return { prompt: next, changed, removedSections, warnings };
+}

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

@@ -0,0 +1,87 @@
+import type { SkillRecord } from "./types";
+
+export function normalizeText(value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, " ").replace(/\s+/g, " ").trim();
+}
+
+export function normalizeName(name: string): string {
+  return name.trim().toLowerCase();
+}
+
+function getString(input: unknown, keys: string[]): string | undefined {
+  if (!input || typeof input !== "object") return undefined;
+  const record = input as Record<string, unknown>;
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  return undefined;
+}
+
+export function collectSkillsFromOptions(options: unknown): SkillRecord[] {
+  if (!options || typeof options !== "object") return [];
+  const skills = (options as { skills?: unknown }).skills;
+  const rawList = Array.isArray(skills)
+    ? skills
+    : skills && typeof skills === "object"
+      ? Object.values(skills as Record<string, unknown>)
+      : [];
+  return rawList.flatMap((item): SkillRecord[] => {
+    const name = getString(item, ["name", "id", "title"]);
+    if (!name) return [];
+    return [{
+      name,
+      description: getString(item, ["description", "summary"]),
+      location: getString(item, ["location", "path", "file", "skillPath"]),
+      source: "systemPromptOptions",
+    }];
+  });
+}
+
+function decodeXmlEntities(value: string): string {
+  return value.replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
+}
+
+function extractTag(block: string, tag: string): string | undefined {
+  const match = block.match(new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`, "i"));
+  return match?.[1]?.trim() ? decodeXmlEntities(match[1].trim()) : undefined;
+}
+
+export function collectSkillsFromXml(systemPrompt: string): SkillRecord[] {
+  const root = systemPrompt.match(/<available_skills>([\s\S]*?)<\/available_skills>/i);
+  if (!root) return [];
+  const skills: SkillRecord[] = [];
+  for (const match of root[1].matchAll(/<skill>([\s\S]*?)<\/skill>/gi)) {
+    const name = extractTag(match[1], "name");
+    if (!name) continue;
+    skills.push({ name, description: extractTag(match[1], "description"), location: extractTag(match[1], "location"), source: "xml" });
+  }
+  return skills;
+}
+
+export function mergeSkills(records: SkillRecord[]): Map<string, SkillRecord> {
+  const merged = new Map<string, SkillRecord>();
+  for (const skill of records) {
+    const key = normalizeName(skill.name);
+    const existing = merged.get(key);
+    merged.set(key, existing ? {
+      name: existing.name,
+      description: existing.description ?? skill.description,
+      location: existing.location ?? skill.location,
+      source: existing.source === "systemPromptOptions" ? existing.source : skill.source,
+    } : skill);
+  }
+  return merged;
+}
+
+export function sortedSkills(skills: Map<string, SkillRecord>): SkillRecord[] {
+  return [...skills.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function findSkill(skills: Map<string, SkillRecord>, name: string): SkillRecord | undefined {
+  const key = normalizeName(name);
+  const exact = skills.get(key);
+  if (exact) return exact;
+  const matches = sortedSkills(skills).filter((skill) => normalizeName(skill.name).includes(key));
+  return matches.length === 1 ? matches[0] : undefined;
+}

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

@@ -0,0 +1,80 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "typebox";
+import type { ContextManagerState } from "./state";
+import { findSkill, normalizeName, sortedSkills } from "./skill-registry";
+
+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");
+}
+
+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) {
+      state.report.cwd = ctx.cwd;
+      state.report.toolCalls.skillIndex += 1;
+      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) {
+      state.report.cwd = ctx.cwd;
+      state.report.toolCalls.skillManifest += 1;
+      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) {
+      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 };
+      try {
+        const content = await loadSkillContent(skill.location);
+        state.report.loadedByTool.push(skill.name);
+        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);
+        return { content: [{ type: "text", text: message }], details: { found: true, skill: skill.name, error: message }, isError: true };
+      }
+    },
+  });
+}

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

@@ -0,0 +1,68 @@
+import type { ContextReport, PolicyPack, SkillRecord } from "./types";
+
+export type ContextManagerState = {
+  skills: Map<string, SkillRecord>;
+  policies: Map<string, PolicyPack>;
+  loadedPolicies: Set<string>;
+  readFiles: Set<string>;
+  editedFiles: Set<string>;
+  writtenFiles: Set<string>;
+  report: ContextReport;
+};
+
+export function createEmptyReport(): ContextReport {
+  return {
+    timestamp: new Date().toISOString(),
+    cwd: "",
+    userPrompt: "",
+    skillCount: 0,
+    candidates: [],
+    loadedByTool: [],
+    loadedPolicies: [],
+    readFiles: [],
+    editedFiles: [],
+    writtenFiles: [],
+    blockedActions: [],
+    duplicateExtensionWarnings: [],
+    promptRewrite: {
+      attempted: false,
+      changed: false,
+      originalLength: 0,
+      rewrittenLength: 0,
+      removedSections: [],
+      warnings: [],
+    },
+    toolCalls: {
+      skillIndex: 0,
+      skillManifest: 0,
+      skillLoad: 0,
+      policyManifest: 0,
+      policyLoad: 0,
+      contextReport: 0,
+    },
+  };
+}
+
+export function createState(): ContextManagerState {
+  return {
+    skills: new Map(),
+    policies: new Map(),
+    loadedPolicies: new Set(),
+    readFiles: new Set(),
+    editedFiles: new Set(),
+    writtenFiles: new Set(),
+    report: createEmptyReport(),
+  };
+}
+
+export function syncReportLedger(state: ContextManagerState): void {
+  state.report.loadedPolicies = [...state.loadedPolicies].sort();
+  state.report.readFiles = [...state.readFiles].sort();
+  state.report.editedFiles = [...state.editedFiles].sort();
+  state.report.writtenFiles = [...state.writtenFiles].sort();
+}
+
+export function recordBlocked(state: ContextManagerState, toolName: string, reason: string): void {
+  state.report.blockedActions.push({ toolName, reason, timestamp: new Date().toISOString() });
+  syncReportLedger(state);
+}

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

@@ -0,0 +1,70 @@
+export type SkillRecord = {
+  name: string;
+  description?: string;
+  location?: string;
+  source: "systemPromptOptions" | "xml" | "tool";
+};
+
+export type CandidateContext = {
+  name: string;
+  score: number;
+  confidence: "high" | "medium";
+  suggestedAction: "skill_load" | "skill_manifest";
+  reasons: string[];
+};
+
+export type PolicyPack = {
+  name: string;
+  description: string;
+  content: string;
+  path?: string;
+};
+
+export type Prerequisite = { type: "policies"; policies: string[] };
+
+export type ContextManagerConfig = {
+  candidateRouter: {
+    maxCandidates: number;
+    highConfidence: number;
+    mediumConfidence: number;
+  };
+  policyPaths: string[];
+  policyFiles?: Record<string, string>;
+  toolPrerequisites: Record<string, Prerequisite[]>;
+  promptCompaction: {
+    compactModelRouting: boolean;
+    compactModelRegistry: boolean;
+    compactSkillDescriptions: boolean;
+  };
+};
+
+export type ContextReport = {
+  timestamp: string;
+  cwd: string;
+  userPrompt: string;
+  skillCount: number;
+  candidates: CandidateContext[];
+  loadedByTool: string[];
+  loadedPolicies: string[];
+  readFiles: string[];
+  editedFiles: string[];
+  writtenFiles: string[];
+  blockedActions: Array<{ toolName: string; reason: string; timestamp: string }>;
+  duplicateExtensionWarnings: Array<{ toolName: string; paths: string[] }>;
+  promptRewrite: {
+    attempted: boolean;
+    changed: boolean;
+    originalLength: number;
+    rewrittenLength: number;
+    removedSections: string[];
+    warnings: string[];
+  };
+  toolCalls: {
+    skillIndex: number;
+    skillManifest: number;
+    skillLoad: number;
+    policyManifest: number;
+    policyLoad: number;
+    contextReport: number;
+  };
+};

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

@@ -37,6 +37,7 @@ import { executeTakomiSubagentTool } from "../takomi-subagents/tool-runner";
 import {
   renderRuntimeStatus,
   renderRuntimeWidget,
+  renderTakomiHeader,
   TakomiFooterComponent,
 } from "./ui";
 import { getTakomiSubagentController } from "./subagent-controller";
@@ -443,6 +444,13 @@ const footerStateRef: { current: TakomiState; installed: boolean } = { current:
 
 async function refreshUi(ctx: ExtensionContext, state: TakomiState) {
   if (!ctx.hasUI) return;
+  ctx.ui.setTitle("Takomi");
+  ctx.ui.setHeader((_tui, theme) => ({
+    invalidate() {},
+    render() {
+      return renderTakomiHeader(theme);
+    },
+  }));
   footerStateRef.current = state;
   ctx.ui.setStatus("takomi-runtime", renderRuntimeStatus(ctx.ui.theme, state));
   const widget = renderRuntimeWidget(ctx.ui.theme, state);

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

@@ -31,6 +31,27 @@ export type RuntimeHudState = {
 
 type Tone = "accent" | "warning" | "success" | "error" | "muted" | "dim" | "thinkingMinimal";
 
+export function renderTakomiHeader(theme: Theme): string[] {
+  const accent = (text: string) => theme.fg("accent", text);
+  const violet = (text: string) => theme.fg("thinkingMinimal", text);
+  const muted = (text: string) => theme.fg("muted", text);
+  const dim = (text: string) => theme.fg("dim", text);
+  const line = dim("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+
+  return [
+    "",
+    accent("████████╗ █████╗ ██╗  ██╗ ██████╗ ███╗   ███╗██╗"),
+    accent("╚══██╔══╝██╔══██╗██║ ██╔╝██╔═══██╗████╗ ████║██║"),
+    violet("   ██║   ███████║█████╔╝ ██║   ██║██╔████╔██║██║"),
+    violet("   ██║   ██╔══██║██╔═██╗ ██║   ██║██║╚██╔╝██║██║"),
+    accent("   ██║   ██║  ██║██║  ██╗╚██████╔╝██║ ╚═╝ ██║██║"),
+    accent("   ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝ ╚═╝     ╚═╝╚═╝"),
+    line,
+    `${muted("         Genesis")} ${dim("→")} ${muted("Design")} ${dim("→")} ${muted("Build")}  ${dim("| custom Pi harness runtime")}`,
+    "",
+  ];
+}
+
 function stageTone(stage?: string): Tone {
   switch (stage) {
     case "genesis":

package/.pi/themes/takomi-aurora.json

@@ -0,0 +1,88 @@
+{
+  "$schema": "https://raw.githubusercontent.com/badlogic/pi-mono/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+  "name": "takomi-aurora",
+  "vars": {
+    "void": "#070A13",
+    "obsidian": "#0B1020",
+    "deep": "#11162A",
+    "glass": "#18213A",
+    "glassHot": "#251633",
+    "glassCool": "#0D2430",
+    "line": "#2B3558",
+    "lineGlow": "#3D4B7A",
+    "snow": "#EAF2FF",
+    "mist": "#AAB8D6",
+    "haze": "#6F7EA3",
+    "neonCyan": "#2EF3FF",
+    "electricBlue": "#4D8DFF",
+    "plasmaViolet": "#B56CFF",
+    "hotMagenta": "#FF4FD8",
+    "solarGold": "#FFD166",
+    "acidGreen": "#6DFFB8",
+    "ember": "#FF6B6B"
+  },
+  "colors": {
+    "accent": "neonCyan",
+    "border": "line",
+    "borderAccent": "hotMagenta",
+    "borderMuted": "lineGlow",
+    "success": "acidGreen",
+    "error": "ember",
+    "warning": "solarGold",
+    "muted": "mist",
+    "dim": "haze",
+    "text": "snow",
+    "thinkingText": "mist",
+
+    "selectedBg": "glassHot",
+    "userMessageBg": "deep",
+    "userMessageText": "snow",
+    "customMessageBg": "glassCool",
+    "customMessageText": "snow",
+    "customMessageLabel": "hotMagenta",
+
+    "toolPendingBg": "glassCool",
+    "toolSuccessBg": "#0D2C24",
+    "toolErrorBg": "#321622",
+    "toolTitle": "neonCyan",
+    "toolOutput": "snow",
+
+    "mdHeading": "hotMagenta",
+    "mdLink": "neonCyan",
+    "mdLinkUrl": "electricBlue",
+    "mdCode": "solarGold",
+    "mdCodeBlock": "snow",
+    "mdCodeBlockBorder": "plasmaViolet",
+    "mdQuote": "mist",
+    "mdQuoteBorder": "hotMagenta",
+    "mdHr": "lineGlow",
+    "mdListBullet": "neonCyan",
+
+    "toolDiffAdded": "acidGreen",
+    "toolDiffRemoved": "ember",
+    "toolDiffContext": "mist",
+
+    "syntaxComment": "haze",
+    "syntaxKeyword": "hotMagenta",
+    "syntaxFunction": "neonCyan",
+    "syntaxVariable": "snow",
+    "syntaxString": "acidGreen",
+    "syntaxNumber": "solarGold",
+    "syntaxType": "electricBlue",
+    "syntaxOperator": "plasmaViolet",
+    "syntaxPunctuation": "mist",
+
+    "thinkingOff": "lineGlow",
+    "thinkingMinimal": "plasmaViolet",
+    "thinkingLow": "electricBlue",
+    "thinkingMedium": "neonCyan",
+    "thinkingHigh": "hotMagenta",
+    "thinkingXhigh": "ember",
+    "bashMode": "solarGold"
+  },
+  "export": {
+    "pageBg": "#060813",
+    "cardBg": "#0E1426",
+    "infoBg": "#1A1730"
+  }
+}

package/README.md

@@ -41,6 +41,20 @@ takomi install all
 takomi init
 ```
 
+### Subagent execution credit
+
+Takomi's Pi-native subagent execution and terminal UI build on **[`pi-subagents`](https://github.com/nicobailon/pi-subagents)** by **Nico Bailon**. That package provides the underlying Pi extension for delegated subagent runs, including the native subagent result renderer, live progress/status display, single/parallel/chain execution support, session/artifact handling, and related subagent tooling. Takomi adds its own lifecycle orchestration, model-routing policy, workflow metadata, board/checklist context, and agent conventions on top of that foundation.
+
+### Context Manager
+
+Takomi now ships a Pi-native `takomi-context-manager` extension. It reduces prompt bloat with progressive context loading:
+
+- skill names are always visible, while descriptions and full `SKILL.md` files load only when needed
+- `skill_manifest`, `skill_load`, `policy_manifest`, `policy_load`, and `context_report` tools expose context on demand
+- `/takomi routing` remains the source of truth for model-routing policy
+- `takomi_subagent` is guarded by routing-policy context and can recover from wrong-provider model choices
+- `/context-report` shows prompt compaction, loaded skills/policies, blocked actions, model-routing corrections, and duplicate extension diagnostics
+
 
 ### Option A: Global Install (Best for Multi-IDE Users) ⭐
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "takomi",
-  "version": "2.1.6",
+  "version": "2.1.9",
   "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": {