pi-chalin 0.1.0

package/src/model-resolution.ts

@@ -0,0 +1,106 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AgentDefinition, AgentThinkingLevel, ModelResolutionAttempt, ModelResolutionLog } from "./schemas.ts";
+
+interface ModelResolutionContext {
+  cwd?: string;
+  agents?: Map<string, AgentDefinition>;
+  modelOverrides?: Record<string, string>;
+  thinkingOverrides?: Record<string, AgentThinkingLevel>;
+  extensionContext?: ExtensionContext;
+}
+
+export function resolveAgentModel(agent: AgentDefinition | undefined, agentName: string, context: ModelResolutionContext): { model: ExtensionContext["model"]; label: string; resolution: ModelResolutionLog; warnings: string[] } {
+  const fallback = context.extensionContext?.model;
+  const tier = agentTier(agentName);
+  const candidates: Array<{ source: ModelResolutionAttempt["source"]; ref?: string }> = [
+    { source: "session-override", ref: context.modelOverrides?.[`${agent?.scope ?? "built-in"}/${agentName}`] ?? context.modelOverrides?.[agentName] },
+    { source: "agent", ref: agent?.model && agent.model !== "inherit" ? agent.model : undefined },
+    { source: "tier", ref: context.modelOverrides?.[`tier/${tier}`] ?? process.env[`PI_CHALIN_${tier.toUpperCase()}_MODEL`] },
+  ];
+  const attempts: ModelResolutionAttempt[] = [];
+
+  for (const candidate of candidates) {
+    if (!candidate.ref) continue;
+    const resolved = resolveModelRef(candidate.ref, context);
+    attempts.push({ source: candidate.source, ref: candidate.ref, status: resolved.status, model: resolved.model ? `${resolved.model.provider}/${resolved.model.id}` : undefined, reason: resolved.reason });
+    if (resolved.status === "selected" && resolved.model) {
+      const selected = `${resolved.model.provider}/${resolved.model.id}`;
+      return {
+        model: resolved.model,
+        label: selected,
+        resolution: { selected, tier, attempts },
+        warnings: fallbackWarnings(agentName, attempts, selected),
+      };
+    }
+  }
+
+  const inherited = fallback ? `${fallback.provider}/${fallback.id}` : "inherit";
+  attempts.push({ source: "inherit", status: fallback ? "selected" : "fallback", model: inherited, reason: fallback ? undefined : "no active Pi model available" });
+  return {
+    model: fallback,
+    label: fallback ? `${inherited} (${tier}:inherit)` : `inherit (${tier})`,
+    resolution: { selected: inherited, tier, attempts },
+    warnings: fallbackWarnings(agentName, attempts, inherited),
+  };
+}
+
+export function resolveAgentThinking(
+  agent: AgentDefinition | undefined,
+  agentName: string,
+  context: ModelResolutionContext,
+  modelResolution?: ModelResolutionLog,
+): { level?: Exclude<AgentThinkingLevel, "inherit">; label: AgentThinkingLevel } {
+  const explicit = context.thinkingOverrides?.[`${agent?.scope ?? "built-in"}/${agentName}`] ?? context.thinkingOverrides?.[agentName];
+  const frontmatter = agent?.thinking && agent.thinking !== "inherit" ? agent.thinking : undefined;
+  const modelSuffix = selectedThinkingSuffix(modelResolution);
+  const level = explicit && explicit !== "inherit" ? explicit : frontmatter ?? modelSuffix;
+  return level ? { level, label: level } : { label: "inherit" };
+}
+
+function selectedThinkingSuffix(modelResolution?: ModelResolutionLog): Exclude<AgentThinkingLevel, "inherit"> | undefined {
+  const selected = modelResolution?.attempts.find((attempt) => attempt.status === "selected" && attempt.ref)?.ref;
+  if (!selected) return undefined;
+  return splitThinkingSuffix(selected).thinking;
+}
+
+function resolveModelRef(ref: string, context: ModelResolutionContext): { status: ModelResolutionAttempt["status"]; model?: ExtensionContext["model"]; reason?: string } {
+  const parsed = parseModelRef(splitThinkingSuffix(ref).model);
+  if (!parsed) return { status: "invalid", reason: "expected provider/model-id" };
+  const registry = context.extensionContext?.modelRegistry;
+  const model = registry?.find(parsed.provider, parsed.modelId);
+  if (!model) return { status: "unavailable", reason: "not found in Pi model registry" };
+  if (!registry?.hasConfiguredAuth(model)) return { status: "unauthenticated", model, reason: "provider is not configured" };
+  return { status: "selected", model };
+}
+
+function splitThinkingSuffix(ref: string): { model: string; thinking?: Exclude<AgentThinkingLevel, "inherit"> } {
+  const trimmed = ref.trim();
+  const colon = trimmed.lastIndexOf(":");
+  if (colon === -1) return { model: trimmed };
+  const suffix = trimmed.slice(colon + 1);
+  if (suffix === "off" || suffix === "minimal" || suffix === "low" || suffix === "medium" || suffix === "high" || suffix === "xhigh") {
+    return { model: trimmed.slice(0, colon), thinking: suffix };
+  }
+  return { model: trimmed };
+}
+
+function parseModelRef(ref: string): { provider: string; modelId: string } | undefined {
+  const trimmed = ref.trim();
+  if (!trimmed || trimmed === "inherit") return undefined;
+  const slash = trimmed.indexOf("/");
+  if (slash <= 0 || slash === trimmed.length - 1) return undefined;
+  return { provider: trimmed.slice(0, slash), modelId: trimmed.slice(slash + 1) };
+}
+
+function agentTier(agentName: string): "fast" | "balanced" | "strong" {
+  if (["scout", "context-builder", "delegate"].includes(agentName)) return "fast";
+  if (["worker", "oracle"].includes(agentName)) return "strong";
+  return "balanced";
+}
+
+function fallbackWarnings(agentName: string, attempts: ModelResolutionAttempt[], selected: string): string[] {
+  const failed = attempts.filter((attempt) => ["invalid", "unavailable", "unauthenticated", "fallback"].includes(attempt.status) && attempt.source !== "inherit");
+  if (failed.length === 0) return [];
+  const refs = failed.map((attempt) => `${attempt.ref ?? attempt.source} ${attempt.status}`).join("; ");
+  return [`Model fallback for ${agentName}: ${refs}; selected ${selected}.`];
+}

package/src/orchestration.ts

@@ -0,0 +1,99 @@
+import type { AgentDefinition } from "./schemas.ts";
+
+export function buildCompactChalinOrchestratorSystemPrompt(): string {
+  return [
+    "## pi-chalin orchestration (compact)",
+    "You are the primary Pi agent. Choose direct native execution for safe bounded implementation/scaffolding/test/refactor tasks with explicit files or acceptance criteria. Use pi-chalin only when specialist context isolation is worth the latency.",
+    "Direct bounded code work: do not narrate planning or emit visible analysis before tools; first inspect briefly, then write the requested implementation/test/docs promptly, ensure requested tests prove the behavior with non-trivial assertions rather than only starter smoke/empty coverage, run the nearest relevant verification command, fix failures, rerun verification after the final edit, and answer immediately with changed paths, verification result, and one note about the satisfied constraint. For timer behavior, prefer injected clocks/schedulers over brittle mock timer APIs; for Bun CLI subprocess tests, preserve process.env and derive paths directly from import.meta.url.",
+    "If the prompt says review-only, docs-only, no code changes, or no mutations, obey that literally: do not add tests/source files or modify code unless explicitly requested. For dependency-free TypeScript scaffolding, use exact requested paths, export the requested API, use package.json test script `bun test`, keep tests under `test/`, avoid uninstalled runners/dependencies, declare package.json `bin` when scaffolding a CLI command; `bin` values must be executable file paths, not command strings, and verify before final answer.",
+    "Call `chalin_route` for broad/deep project analysis, architecture/migration strategy, broad review, complex/risky multi-file work, risky long-file/surgical edits, parallel option comparison, or memory/continuation work. Call `chalin_interview` only when a real decision is ambiguous.",
+    "If chalin_route returns, answer from its Final answer material immediately. Do not call chalin_route for bounded direct work merely because pi-chalin is available.",
+  ].join("\n");
+}
+
+export function buildCompactChalinCriticalSystemPrompt(): string {
+  return [
+    "## pi-chalin orchestration (critical compact)",
+    "This prompt requires pi-chalin before native tools. First action should be one `chalin_route` call; do not inspect files directly before routing.",
+    "Use `chain` scout → planner → worker → reviewer for risky implementation, long-file/surgical edits, auth/security-sensitive mutations, or complex multi-file work.",
+    "Use `dag` for independent implementation slices: discovery/planning first, parallel workers with non-overlapping ownership, then reviewer synthesis.",
+    "For surgical/long-file edits: worker must use targeted edit discipline, not full rewrite; reviewer must verify scope and tests.",
+    "After `chalin_route` returns, answer from Final answer material immediately. In non-interactive runs, the chalin result itself is the handoff; do not call native tools after chalin unless the tool result explicitly says a critical blocker remains.",
+    "Available agents: scout, planner, worker, reviewer, context-builder, researcher, oracle.",
+  ].join("\n");
+}
+
+export function buildCompactChalinResumeSystemPrompt(): string {
+  return [
+    "## pi-chalin resume orchestration (compact)",
+    "The user is continuing an interrupted pi-chalin workflow. First action must be `chalin_resume`; do not answer from partial findings.",
+    "Spanish continuation prompts such as `continua`, `continúa`, `sigue`, `reanuda`, or `retoma` mean the same thing when a resumable pi-chalin run exists.",
+    "Do not call `chalin_route` for the same work. Resume the persisted run, preserve completed handoffs, and continue only pending/stale subagent steps.",
+    "After `chalin_resume` returns, answer from its Final answer material immediately.",
+  ].join("\n");
+}
+
+export function buildChalinOrchestratorSystemPrompt(agents: AgentDefinition[]): string {
+  const roster = agents.map(formatAgentForPrompt).join("\n") || "- none";
+  return [
+    "## pi-chalin orchestration",
+    "You are the primary Pi agent. Decide whether to answer directly, call `chalin_interview`, or call `chalin_route` as an agents-as-tools runtime.",
+    "pi-chalin is optional orchestration for work that benefits from specialist context isolation; the user does not need to invoke it.",
+    "",
+    "### Gate",
+    "Before read/bash/grep/find/ls, decide whether this is repository orchestration work.",
+    "MUST call `chalin_resume` first when the user asks to continue/resume/continua/continúa/sigue/reanuda/retoma and a prior pi-chalin run was paused, interrupted, or left stale by terminal shutdown. Do not answer from partial findings until resume has no resumable run.",
+    "MUST call `chalin_interview` before `chalin_route` when the request is ambiguous, uses a term you cannot resolve from memory/codebase exploration, has missing scope/constraints, or contains an uncovered decision branch that would make subagents guess.",
+    "MUST call `chalin_route` first for clear current branch/diff/PR summaries, what this project does, project structure, architecture/migration/project-wide refactor strategy, broad/project-wide review, security/correctness review over a broad surface, complex/risky multi-file implementation, risky long-file/surgical edits, or prior memory. Do NOT treat an explicit named-file refactor implementation as refactor strategy; that is bounded direct work unless the prompt says broad/risky/long-file.",
+    "Hard direct gate: if the user names one to three target file paths and asks to refactor/fix/add/update/extract tests or helpers, do NOT call `chalin_route`; use native read/edit/write/bash directly. Calling chalin_route for that bounded case wastes latency and will be redirected back to direct execution.",
+    "Hard direct gate: if the user asks for a bounded read-only mini-project review and explicitly says not to modify files, do NOT call `chalin_route`; inspect the small file set directly, answer with concrete path evidence, and perform no writes.",
+    "Single-file is NOT automatically direct: if the user says the file is long, asks for a surgical/targeted behavior/auth validation change, or warns not to rewrite the whole file, use chalin_route with worker/reviewer discipline.",
+    "You choose topology, agents, tasks, risk, memory use, interviews, and plan size. The code does not classify prompts for you.",
+    "Call `chalin_interview` in batches of 1-5 concise questions with at most 5 concise answers each; mark the best answer as recommended and allow custom answers unless safety requires constrained choices.",
+    "After `chalin_interview` returns, use its artifact answers as context. If still blocked, ask another interview batch; if ready, continue planning or call `chalin_route`.",
+    "Call `chalin_route` at most once per user prompt after the needed interview context is available. After it returns, immediately write the final answer from its `Final answer material`; do not keep thinking, do not call another tool, and do not inspect files unless the handoff names a concrete blocking gap.",
+    "For long-running/continuation work, use `chalin_resume` for interrupted runs; use `chalin_artifact_resume` when the user names an existing feature/task artifact; otherwise set `needsArtifacts: true` so pi-chalin records run summaries and handoffs.",
+    "",
+    "### Interview when",
+    "Use `chalin_interview` when proceeding would require guessing user intent, unknown terminology, risk tolerance, target scope, accepted tradeoffs, or destructive/large-change boundaries.",
+    "Do not interview for information that can be cheaply and safely discovered from the local codebase or existing pi-chalin memory; discover first, interview only for the remaining blocker.",
+    "Persisted interview answers are artifacts and should be reused by the next route/subagents instead of asking again.",
+    "",
+    "### Direct answer when",
+    "Use normal Pi for greetings, short clarifications, simple definitions without local inspection, one obvious command, one tiny isolated edit, bounded read-only mini-project reviews, explicit named-file bugfixes/refactors with tests, or bounded implementation/scaffolding with a clear file list and low risk. Direct execution still means full fidelity to every explicit acceptance criterion: if the user asks to extract helpers, add tests, preserve behavior, or avoid dependencies, do exactly that before final answer. If the user asks for tests, changing only implementation is incomplete even when existing tests pass; add or update the relevant test file before final verification. The test change must be behavior-bearing: assert requested outputs/effects and relevant edge/failure cases when applicable; merely preserving or renaming a starter smoke/empty test is incomplete. For time/window behavior, make tests deterministic with an injected or controlled clock when possible; avoid brittle mock timer APIs unless you verify the current Bun API in this project. Do not assert exact `Date.now()`-derived milliseconds against real wall time. For named-file bugfixes/refactors, inspect the target file and tests once, edit promptly, then verify. For dependency-free TypeScript scaffolding, write the exact requested files, keep requested APIs/exported helpers in the requested source file, prefer `bun test`, use `test/` unless the user explicitly asks otherwise, avoid uninstalled runners (`tsx`, `vitest`, `jest`), export requested APIs, declare requested package.json `bin` entries that point to executable file paths, never command strings, and fix verification failures and rerun verification after the final edit before final answer. For Bun CLI subprocess tests, preserve `process.env` and derive target paths directly from `import.meta.url`; do not strip PATH/NODE_OPTIONS or compute parent directories twice. After successful edits plus a passing verification command after the final edit, stop and answer immediately with changed files, verification result, and one note naming the requested behavior/constraint satisfied; do not keep exploring or run unrelated checks. Do NOT treat long-file, auth/validation mutation, broad behavior, or no-rewrite edits as tiny.",
+    "",
+    "### Default recipes",
+    "- Branch/diff/project understanding: `chain` with scout → context-builder; context-builder should synthesize scout handoff without extra file reads unless exact line-level behavior is explicitly required.",
+    "- Broad/deep project analysis MUST optimize for accuracy, not brevity. Require a Coverage Matrix and Evidence Table before synthesis; every critical surface must be marked covered with evidence, not present with evidence, or unknown/gap.",
+    "- If the user asks what a project does in depth but does not explicitly request folder-by-folder fan-out, prefer `chain` with scout → context-builder using `budget: \"deep\"`; it is usually more accurate and faster than a large DAG.",
+    "- Reserve `dag` for explicit staged fan-out/fan-in requests, e.g. the user asks to divide analysis by many folders/modules or the repo is clearly too large for one context-builder. Use scout first, parallel context-builder/reviewer/researcher tasks per independent area, then a final reviewer/context-builder synthesis stage. Give deep-analysis children `budget: \"deep\"` and ask them to preserve coverage/evidence, not just compact notes.",
+    "- For memory/agent/orchestration repos, include domain-critical surfaces in the route tasks: local/project detection, memory persistence and sync, MCP/tool surface, HTTP/API routes, conflict surfacing, external integrations, UI/dashboard/cloud, and test/eval status.",
+    "- Architecture/migration/project-wide refactor strategy: `chain` with scout → planner → reviewer. Explicit named-file refactor implementation is not this category; keep it direct when low-risk and bounded.",
+    "- Project-wide review: `chain` with scout → reviewer.",
+    "- Complex/risky multi-file implementation or requests that need broad discovery before code changes: use `chain` with scout → planner → worker → reviewer. Bounded scaffolding/greenfield/refactor/bugfix tasks with explicit files and simple acceptance criteria may stay direct to avoid orchestration overhead. In non-interactive print mode, do not convert safe bounded edits into dry-run reports; either edit directly or run a real chalin_route. When staying direct, satisfy each requested code-shape constraint, not just behavior. For TypeScript scaffolds in empty repos, use dependency-free Bun test infrastructure, exact requested paths, and exports in the requested source file instead of inventing external runners, alternate test folders, or moving the API elsewhere.",
+    "- Risky long-file or surgical behavior edits, including prompts like 'archivo largo', 'validacion puntual', 'avoid rewrite', or 'no reescribir': MUST use `chain` with scout → planner → worker → reviewer and tell worker to use targeted edit, not full rewrite.",
+    "- Alternative comparison with two approaches/options: MUST use plain `parallel` independent planners/reviewers, not `dag`, unless implementation or staged discovery is explicitly required.",
+    "- Independent implementation slices: MUST include worker agents. Prefer `dag` with discovery/planning first, a fan-out stage of parallel worker tasks with explicit non-overlapping ownership scopes, then reviewer synthesis. Use plain `parallel` only for pure worker fan-out that needs no prior discovery/review stage.",
+    "- Use `dag` when the workflow needs staged fan-out/fan-in, e.g. scout → parallel folder agents → reviewer synthesis.",
+    "- Explicit recall: `memory-only`.",
+    "- Long autonomous tasks: set `needsArtifacts: true`; subagents should leave compact handoffs, memory candidates, and validation contracts when relevant.",
+    "- Tool budgets: each step may set `budget` to `tight`, `normal`, `deep`, or `extended`. Use `deep` for project-wide/folder fan-out analysis. Use `extended` only for a bounded long-running stage with artifacts/checkpoints; otherwise split the work into a DAG instead of inflating one child.",
+    "",
+    "### Cost, risk, and latency",
+    "- Prefer 1 chalin call, 1-3 agents, and short handoffs over repeated orchestration loops.",
+    "- Use `low` risk for read-only analysis/planning. Use `medium+` only for mutation, approvals, secrets, destructive actions, or security-sensitive execution.",
+    "- Subagents should produce compact handoffs; you own the final answer.",
+    "- After a successful chalin run, answer from the handoff in the user language. If `Final answer material` is present, treat it as sufficient and respond now.",
+    "- Use `chalin_web_search` only for current external facts, docs, URLs, or explicit web research. It is available globally and to external-context agents; workers should not use it by default.",
+    "- Do not send worker agents to browse the web by default.",
+    "",
+    "### Available pi-chalin agents",
+    roster,
+  ].join("\n");
+}
+
+function formatAgentForPrompt(agent: AgentDefinition): string {
+  const tools = agent.tools.length > 0 ? agent.tools.join(", ") : "none";
+  const capabilities = agent.capabilities.length > 0 ? agent.capabilities.join(", ") : "none";
+  return `- ${agent.name}: ${agent.description} concern=${agent.concern} thinking=${agent.thinking ?? "inherit"} capabilities=${capabilities} tools=${tools}`;
+}

package/src/paths.ts

@@ -0,0 +1,50 @@
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export interface ChalinPathsOptions {
+  cwd: string;
+  userRoot?: string;
+  packageRoot?: string;
+}
+
+export interface ChalinPaths {
+  cwd: string;
+  packageRoot: string;
+  builtInAgentsDir: string;
+  projectRoot: string;
+  projectConfigPath: string;
+  projectAgentsDir: string;
+  userRoot: string;
+  userConfigPath: string;
+  userAgentsDir: string;
+}
+
+export function packageRootFromImportMeta(importMetaUrl = import.meta.url): string {
+  return path.resolve(path.dirname(fileURLToPath(importMetaUrl)), "..");
+}
+
+export function resolveChalinPaths(options: ChalinPathsOptions): ChalinPaths {
+  const cwd = path.resolve(options.cwd);
+  const packageRoot = options.packageRoot ? path.resolve(options.packageRoot) : packageRootFromImportMeta();
+  const projectRoot = cwd;
+  const userRoot = options.userRoot ? path.resolve(options.userRoot) : path.join(os.homedir(), ".pi", "chalin");
+
+  return {
+    cwd,
+    packageRoot,
+    builtInAgentsDir: path.join(packageRoot, "agents"),
+    projectRoot,
+    projectConfigPath: path.join(projectRoot, ".pi-chalin", "config.json"),
+    projectAgentsDir: path.join(projectRoot, ".pi-chalin", "agents"),
+    userRoot,
+    userConfigPath: path.join(userRoot, "config.json"),
+    userAgentsDir: path.join(userRoot, "agents"),
+  };
+}
+
+export function expandTilde(input: string): string {
+  if (input === "~") return os.homedir();
+  if (input.startsWith("~/")) return path.join(os.homedir(), input.slice(2));
+  return input;
+}

package/src/route-format.ts

@@ -0,0 +1,149 @@
+import type { ChalinHandleResult } from "./kernel.ts";
+import type { ChalinRouteOutcome } from "./runtime-state.ts";
+import type { RouteDecision, RunState } from "./schemas.ts";
+
+export function formatRoute(route: RouteDecision, result: ChalinHandleResult | undefined, options: { availableAgents?: string[] } = {}): string {
+  if (!result) {
+    return [
+      `Chalin workflow: ${route.kind}`,
+      `Agents: ${route.agents.join(" → ") || "none"}`,
+      `Risk: ${route.risk}`,
+      `Reason: ${route.reason}`,
+      options.availableAgents ? `\nAvailable agents: ${options.availableAgents.join(", ") || "none"}` : undefined,
+    ].filter((line): line is string => line !== undefined).join("\n");
+  }
+
+  const finalMaterial = finalAnswerMaterial(result.run);
+  const memoryMaterial = !finalMaterial && result.memories.length > 0 ? formatMemoryMaterial(result.memories) : undefined;
+  const supportingFindings = supportingAgentFindings(result.run);
+  const lines = [
+    `pi-chalin completed: ${route.agents.join(" → ") || route.kind}`,
+    `status: ${result.run?.status ?? result.approval.action}`,
+    result.approval.action === "allow"
+      ? "Instruction for the primary Pi agent: answer the user now from the Final answer material below. Do not call more tools unless it explicitly says a critical gap remains."
+      : "Instruction for the primary Pi agent: pi-chalin did not execute because approval is required. Do not claim completion. If this is a safe explicit user-requested edit, continue directly with native tools; otherwise explain that approval is required.",
+    result.approval.action !== "allow" ? `Approval: ${result.approval.action} — ${result.approval.reason}` : undefined,
+    result.memories.length > 0 ? `Memory used: ${result.memories.length}` : undefined,
+    finalMaterial ? "\nFinal answer material:" : undefined,
+    finalMaterial,
+    memoryMaterial ? "\nMemory material:" : undefined,
+    memoryMaterial,
+    supportingFindings ? "\nSupporting findings:" : undefined,
+    supportingFindings,
+    !finalMaterial && result.run ? "\nSubagent handoff:" : undefined,
+    !finalMaterial && result.run ? result.run.steps.map(formatStep).join("\n") : undefined,
+    options.availableAgents ? `\nAvailable agents: ${options.availableAgents.join(", ") || "none"}` : undefined,
+  ];
+  return lines.filter((line): line is string => line !== undefined && line.length > 0).join("\n");
+}
+
+function formatMemoryMaterial(memories: ChalinHandleResult["memories"]): string {
+  return memories
+    .slice(0, 8)
+    .map((memory) => `- ${memory.category} · ${memory.sourceAgent} · ${memory.content}`)
+    .join("\n");
+}
+
+export function finalAnswerMaterial(run: RunState | undefined): string | undefined {
+  if (!run) return undefined;
+  const completeSteps = run.steps.filter((step) => isUsableStepStatus(step.status));
+  if (shouldAggregateFinalMaterial(run, completeSteps)) {
+    const material = completeSteps
+      .map((step) => {
+        const output = stepFullOutput(step);
+        return output ? `## ${step.agent}\n${output}` : undefined;
+      })
+      .filter((item): item is string => Boolean(item))
+      .join("\n\n");
+    return material ? truncate(material, finalAnswerMaterialBudget(run)) : undefined;
+  }
+  const primary = completeSteps.at(-1) ?? run.steps.at(-1);
+  const output = primary ? stepOutput(primary) : undefined;
+  return output ? truncate(output, finalAnswerMaterialBudget(run)) : undefined;
+}
+
+function shouldAggregateFinalMaterial(run: RunState, completeSteps: RunState["steps"]): boolean {
+  if (completeSteps.length <= 1) return false;
+  if (run.route.kind === "multi-agent-dag") return true;
+  return /\b(deep|in[- ]depth|profundidad|profundo|an[aá]lisis|project analysis|Coverage Matrix|Evidence Table)\b/i.test(run.route.reason);
+}
+
+function finalAnswerMaterialBudget(run: RunState): number {
+  const parsed = Number(process.env.PI_CHALIN_FINAL_MATERIAL_CHARS);
+  if (Number.isFinite(parsed) && parsed > 500) return Math.floor(parsed);
+  if (run.route.kind === "multi-agent-dag") return 12000;
+  if (/\b(deep|in[- ]depth|profundidad|profundo|an[aá]lisis|project analysis|Coverage Matrix|Evidence Table)\b/i.test(run.route.reason)) return 10000;
+  return 1200;
+}
+
+function supportingAgentFindings(run: RunState | undefined): string | undefined {
+  if (!run) return undefined;
+  const completeSteps = run.steps.filter((step) => isUsableStepStatus(step.status));
+  if (completeSteps.length <= 1) return undefined;
+  return completeSteps
+    .slice(0, -1)
+    .map((step) => `- ${step.agent}: ${truncate(stepOutput(step) || "no output", 260)}`)
+    .join("\n");
+}
+
+function stepOutput(step: RunState["steps"][number]): string | undefined {
+  return step.output?.handoff || step.output?.text || step.output?.raw || step.error;
+}
+
+function stepFullOutput(step: RunState["steps"][number]): string | undefined {
+  return step.output?.text || step.output?.raw || step.output?.handoff || step.error;
+}
+
+export function outcomeForResult(result: ChalinHandleResult): ChalinRouteOutcome {
+  if (result.approval.action === "ask") return "ask";
+  if (result.approval.action === "block") return "block";
+  if (result.run?.status === "failed") return "failed";
+  if (result.run?.status === "paused") return "paused";
+  return "complete";
+}
+
+export function formatDirectRecommendation(route: RouteDecision, reason: string): string {
+  return [
+    "pi-chalin direct execution recommended",
+    "status: direct-recommended",
+    reason,
+    `Original route: ${route.kind} · ${route.agents.join(" → ") || "none"}`,
+    "Instruction for the primary Pi agent: do not claim completion from this tool result. Continue now with native tools and complete the bounded edit directly.",
+  ].join("\n");
+}
+
+function formatStep(step: RunState["steps"][number]): string {
+  return `- ${step.agent}: ${truncate(stepOutput(step) || "no output", 420)}`;
+}
+
+export function compactRouteDetails(route: RouteDecision, result: ChalinHandleResult, diagnostics: unknown[]) {
+  return {
+    route,
+    approval: result.approval,
+    memoriesUsed: result.memories?.length ?? 0,
+    run: result.run ? {
+      id: result.run.id,
+      status: result.run.status,
+      logsPath: result.run.logsPath,
+      metrics: result.run.metrics,
+      steps: result.run.steps.map((step) => ({
+        agent: step.agent,
+        status: step.status,
+        model: step.model,
+        thinkingLevel: step.thinkingLevel,
+        error: step.error,
+        handoff: truncate(step.output?.handoff || step.output?.text || step.error || "", 600),
+      })),
+    } : undefined,
+    diagnostics,
+  };
+}
+
+function isUsableStepStatus(status: RunState["status"] | undefined): boolean {
+  return status === "complete" || status === "budget-capped";
+}
+
+function truncate(text: string, max: number): string {
+  const normalized = text.replace(/\s+/g, " ").trim();
+  return normalized.length <= max ? normalized : `${normalized.slice(0, max - 1)}…`;
+}

package/src/route-guards.ts

@@ -0,0 +1,92 @@
+import type { AgentStep, RouteDecision } from "./schemas.ts";
+
+export function ensureMutationRouteHasWorker(route: RouteDecision, task: string): RouteDecision {
+  if (!taskExpectsWorkspaceMutation(task) || route.kind === "memory-only" || route.kind === "ask-user" || route.agents.includes("worker")) return route;
+  if (!route.plan) return route;
+
+  const workerStep: AgentStep = {
+    id: "implementation",
+    agent: "worker",
+    task: [
+      "Implement the user's requested workspace changes.",
+      "Preserve existing behavior, satisfy every explicit acceptance criterion, and run or update relevant tests when available.",
+      `Original task: ${task}`,
+    ].join(" "),
+    budget: "normal",
+  };
+  const reason = `${route.reason} Mutation task normalized by pi-chalin: added a worker step because implementation routes must include an executor.`;
+
+  if (route.plan.kind === "dag") {
+    return {
+      ...route,
+      agents: [...route.agents, "worker"],
+      needsArtifacts: true,
+      reason,
+      plan: {
+        kind: "dag",
+        stages: [...route.plan.stages, { id: "implementation", tasks: [workerStep] }],
+      },
+    };
+  }
+
+  const existingSteps = route.plan.kind === "single"
+    ? [{ id: "existing", agent: route.plan.agent, task: route.plan.task, budget: route.plan.budget }]
+    : route.plan.kind === "chain" ? route.plan.steps : route.plan.tasks;
+  const reviewerIndex = existingSteps.findIndex((step) => step.agent === "reviewer");
+  const steps = reviewerIndex >= 0
+    ? [...existingSteps.slice(0, reviewerIndex), workerStep, ...existingSteps.slice(reviewerIndex)]
+    : [...existingSteps, workerStep];
+  return {
+    ...route,
+    kind: "multi-agent-chain",
+    agents: steps.map((step) => step.agent),
+    needsArtifacts: true,
+    reason,
+    plan: { kind: "chain", steps },
+  };
+}
+
+function taskExpectsWorkspaceMutation(task: string): boolean {
+  return /\b(refactoriza|implementa|a[nñ]ade|a[nñ]adir|actualiza|modifica|corrige|arregla|crea|extrae|implement|add|update|modify|fix|create|write|edit|extract|scaffold)\b/i.test(task)
+    || /\brefactor\b/i.test(task) && /\b(src\/|test\/|archivo|file|\.tsx?|\.jsx?|\.py|\.go|\.rs)\b/i.test(task);
+}
+
+export function directExecutionRecommendation(task: string, route: RouteDecision): string | undefined {
+  if (route.kind === "memory-only" || route.kind === "ask-user") return undefined;
+  if (route.risk === "high" || route.risk === "critical") return undefined;
+  if (isBoundedReadOnlyReview(task)) {
+    return [
+      "Direct execution recommended: this is a bounded read-only review that explicitly forbids file changes.",
+      "Use native read/grep/find/ls tools only; inspect the small relevant file set directly, perform no writes, and answer with concrete path evidence.",
+    ].join(" ");
+  }
+  if (!taskExpectsWorkspaceMutation(task)) return undefined;
+  if (!hasExplicitFileTargets(task)) return undefined;
+  if (hasBroadOrRiskyScope(task)) return undefined;
+  return [
+    "Direct execution recommended: this is a bounded explicit-file mutation.",
+    "Use native read/edit/write/bash tools instead of subagents; inspect the named target file(s), make the requested change, run the nearest relevant verification command, fix failures and rerun after the final edit, then answer with paths plus passing verification status.",
+  ].join(" ");
+}
+
+function hasExplicitFileTargets(task: string): boolean {
+  const matches = task.match(/\b[\w@.-]+(?:\/[\w@.-]+)+\.[a-zA-Z0-9]+\b/g) ?? [];
+  return matches.length > 0 && new Set(matches).size <= 3;
+}
+
+function isBoundedReadOnlyReview(task: string): boolean {
+  if (taskExpectsWorkspaceMutation(task)) return false;
+  if (!/\b(revisa|review|audit|audita|inspect|inspecciona)\b/i.test(task)) return false;
+  if (!/\b(no modifiques|no modificar|no edits?|do not modify|don't modify|read[- ]only|solo lectura|sin modificar)\b/i.test(task)) return false;
+  if (hasBroadReadOnlyScope(task)) return false;
+  return /\b(mini|small|peque[nñ]o|bounded|concret[oa]s?|specific paths?|paths concretos|file evidence|evidencia)\b/i.test(task)
+    || hasExplicitFileTargets(task);
+}
+
+function hasBroadReadOnlyScope(task: string): boolean {
+  return /\b(project[- ]wide|entire project|whole project|all files|monorepo|architecture|migration|migraci[oó]n|deep|en profundidad|broad|amplio|large|complex|risky)\b/i.test(task);
+}
+
+function hasBroadOrRiskyScope(task: string): boolean {
+  return /\b(project[- ]wide|entire project|whole project|all files|monorepo|architecture|migration|migraci[oó]n|security|seguridad|auth|authentication|authorization|permissions?|database|schema|concurrency|race condition|large|complex|risky|long file|archivo largo|surgical|quir[uú]rgic|no rewrite|sin reescribir)\b/i.test(task);
+}