@mindfoldhq/trellis 0.6.0-beta.2 → 0.6.0-beta.20

package/dist/templates/pi/extensions/trellis/index.ts.txt

@@ -1,16 +1,15 @@
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { createHash, randomBytes } from "node:crypto";
-import { delimiter, dirname, join, resolve } from "node:path";
-import { spawn } from "node:child_process";
+import { delimiter, dirname, isAbsolute, join, resolve } from "node:path";
+import { spawn, spawnSync } from "node:child_process";
 
+// ── Types ──────────────────────────────────────────────────────────────
 type JsonObject = Record<string, unknown>;
 type TextContent = { type: "text"; text: string };
-
 interface PiToolResult {
   content: TextContent[];
-  details?: JsonObject;
+  details?: unknown;
 }
-
 interface PiExtensionContext {
   hasUI?: boolean;
   sessionManager?: {
@@ -18,892 +17,1389 @@ interface PiExtensionContext {
     getSessionFile?: () => string | undefined;
   };
   ui?: {
-    notify?: (message: string, type?: "info" | "warning" | "error") => void;
+    notify?: (msg: string, type?: "info" | "warning" | "error") => void;
   };
 }
-
-interface PiBeforeAgentStartEvent {
-  systemPrompt?: string;
-}
-
-interface PiContextEvent {
-  messages?: unknown[];
-}
-
-interface PiToolCallEvent {
-  toolName?: string;
-  input?: JsonObject;
-}
-
 interface SubagentInput {
   agent?: string;
   prompt?: string;
   mode?: "single" | "parallel" | "chain";
   prompts?: string[];
   model?: string;
-  thinking?: ThinkingLevel;
+  thinking?: string;
 }
-
-type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
-
 interface AgentConfig {
   model?: string;
-  thinking?: ThinkingLevel;
-  // Parsed for pi-subagents-compatible agent files; Pi CLI has no documented fallback-model flag to pass through here.
+  thinking?: string;
   fallbackModels: string[];
 }
-
-interface AgentDefinition {
-  content: string;
-  config: AgentConfig;
-}
-
 interface PiRunConfig {
   model?: string;
-  thinking?: ThinkingLevel;
+  thinking?: string;
+}
+
+// ── Lazy-load pi-tui (avoid failing top-level imports) ─────────────────
+let _piTui: {
+  visibleWidth?: (s: string) => number;
+  truncateToWidth?: (s: string, w: number, ellipsis?: string) => string;
+} | null = null;
+function piTui() {
+  if (!_piTui) {
+    try {
+      _piTui = require("@earendil-works/pi-tui");
+    } catch {
+      _piTui = {};
+    }
+  }
+  return _piTui;
+}
+function trunc(s: string, w: number) {
+  const t = piTui();
+  return t.truncateToWidth
+    ? t.truncateToWidth(s, w, "…")
+    : s.length <= w
+      ? s
+      : w > 1
+        ? s.slice(0, w - 1) + "…"
+        : s.slice(0, w);
 }
 
+// ── Constants ─────────────────────────────────────────────────────────
 const TRELLIS_AGENT_JSONL: Record<string, string> = {
   "trellis-implement": "implement.jsonl",
   implement: "implement.jsonl",
   "trellis-check": "check.jsonl",
   check: "check.jsonl",
 };
+const MAX_STDOUT = 8 * 1024 * 1024;
+const MAX_STDERR = 1024 * 1024;
+const MAX_TAIL = 256 * 1024;
+const MAX_LINE_BUFFER = 1024 * 1024;
+const MAX_TOOL_ARG_CHARS = 2048;
+const MAX_TOOLS = 256;
+const MAX_PARALLEL_PROMPTS = 6;
+const ABORT_KILL_GRACE_MS = 1500;
+const SESSION_OVERVIEW_TIMEOUT_MS = 1500;
+const THROTTLE_MS = 500;
+
+// ── State types ───────────────────────────────────────────────────────
+type RunStatus = "pending" | "running" | "succeeded" | "failed" | "cancelled";
+type ToolStatus = "running" | "succeeded" | "failed";
+
+interface Usage {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  cost: number;
+  ctxTokens: number;
+  turns: number;
+}
+interface ToolTrace {
+  id: string;
+  name: string;
+  args: string;
+  status: ToolStatus;
+  startedAt: number;
+  finishedAt?: number;
+}
+interface RunState {
+  id: string;
+  agent: string;
+  prompt: string;
+  step?: number;
+  status: RunStatus;
+  startedAt?: number;
+  finishedAt?: number;
+  finalText: string;
+  textTail: string;
+  thinkingTail: string;
+  stderrTail: string;
+  tools: ToolTrace[];
+  usage: Usage;
+  model?: string;
+  thinking?: string;
+  errorMessage?: string;
+}
+interface ProgressDetails {
+  kind: "trellis-subagent-progress";
+  agent: string;
+  mode: "single" | "parallel" | "chain";
+  startedAt: number;
+  updatedAt: number;
+  final: boolean;
+  runs: RunState[];
+}
 
-function findProjectRoot(startDir: string): string {
-  let current = resolve(startDir);
-  while (true) {
-    if (
-      existsSync(join(current, ".trellis")) ||
-      existsSync(join(current, ".pi"))
-    ) {
-      return current;
-    }
-    const parent = dirname(current);
-    if (parent === current) return resolve(startDir);
-    current = parent;
+// ── Native partial-update card state ──────────────────────────────────
+interface NativeCardHandle {
+  state: JsonObject;
+  invalidate: () => void;
+  updatedAt: number;
+}
+const MAX_NATIVE_CARDS = 20;
+const nativeCards = new Map<string, NativeCardHandle>();
+let activeSubagentToolCallId: string | null = null;
+function rememberNativeCard(id: string, card: NativeCardHandle) {
+  nativeCards.set(id, card);
+  const active = activeSubagentToolCallId
+    ? nativeCards.get(activeSubagentToolCallId)
+    : undefined;
+  if (!active || card.updatedAt >= active.updatedAt)
+    activeSubagentToolCallId = id;
+  for (const key of nativeCards.keys()) {
+    if (nativeCards.size <= MAX_NATIVE_CARDS) break;
+    if (key !== activeSubagentToolCallId) nativeCards.delete(key);
   }
 }
-
-function readText(path: string): string {
+function totalUsage(d: ProgressDetails): Usage {
+  const u: Usage = {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    cost: 0,
+    ctxTokens: 0,
+    turns: 0,
+  };
+  for (const r of d.runs) {
+    u.input += r.usage.input;
+    u.output += r.usage.output;
+    u.cacheRead += r.usage.cacheRead;
+    u.cacheWrite += r.usage.cacheWrite;
+    u.cost += r.usage.cost;
+    u.ctxTokens = Math.max(u.ctxTokens, r.usage.ctxTokens);
+    u.turns += r.usage.turns;
+  }
+  return u;
+}
+function activeRun(d: ProgressDetails) {
+  return d.runs.find((r) => r.status === "running") ?? d.runs.at(-1);
+}
+function toolArgs(t: ToolTrace) {
   try {
-    return readFileSync(path, "utf-8");
+    return JSON.parse(t.args) as Record<string, unknown>;
   } catch {
-    return "";
+    return {};
   }
 }
-
-function splitMarkdownFrontmatter(content: string): {
-  frontmatter: string;
-  body: string;
-} {
-  const normalized = content.replace(/^\uFEFF/, "");
-  const match = normalized.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
-  return match
-    ? { frontmatter: match[1] ?? "", body: normalized.slice(match[0].length) }
-    : { frontmatter: "", body: normalized };
+function bashCommand(t: ToolTrace) {
+  const a = toolArgs(t);
+  return String(a.command || "").toLowerCase();
 }
-
-function stripMarkdownFrontmatter(content: string): string {
-  return splitMarkdownFrontmatter(content).body.trimStart();
+function isSearchTool(t: ToolTrace) {
+  return t.name === "read" || t.name === "grep" || t.name === "find";
 }
-
-function isJsonObject(value: unknown): value is JsonObject {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
+function isMutationTool(t: ToolTrace) {
+  return t.name === "edit" || t.name === "write";
 }
-
-function stringValue(value: unknown): string | null {
-  return typeof value === "string" && value.trim() ? value.trim() : null;
+function isValidationCommand(t: ToolTrace) {
+  const c = bashCommand(t);
+  return /\b(test|typecheck|lint|build|gofmt|go test|npm run|pnpm|vitest|tsc)\b/.test(
+    c,
+  );
 }
-
-const THINKING_LEVELS = [
-  "off",
-  "minimal",
-  "low",
-  "medium",
-  "high",
-  "xhigh",
-] as const satisfies readonly ThinkingLevel[];
-const THINKING_SUFFIX_RE = /:(?:off|minimal|low|medium|high|xhigh)$/i;
-
-function normalizeThinking(value: unknown): ThinkingLevel | undefined {
-  const raw = stringValue(value)?.toLowerCase();
-  if (!raw) return undefined;
-  return THINKING_LEVELS.includes(raw as ThinkingLevel)
-    ? (raw as ThinkingLevel)
-    : undefined;
+function isInspectionCommand(t: ToolTrace) {
+  const c = bashCommand(t);
+  return /\b(rg|grep|find|git diff|git status|ls|tree)\b/.test(c);
 }
-
-function parseFrontmatterScalar(value: string): string | null {
-  const trimmed = value.trim();
-  if (
-    !trimmed ||
-    trimmed === "|" ||
-    trimmed === ">" ||
-    trimmed === "[]" ||
-    trimmed === "null" ||
-    trimmed === "~"
-  ) {
-    return null;
+function thinkingIntent(text: string) {
+  const s = text.toLowerCase();
+  if (/error|failed|failure|panic|exception|报错|失败|错误|异常/.test(s))
+    return "Analyzing failure cause";
+  if (/test|verify|check|typecheck|lint|验证|测试|检查/.test(s))
+    return "Planning verification steps";
+  if (/plan|approach|design|strategy|方案|计划|思路|设计/.test(s))
+    return "Structuring the implementation approach";
+  if (/implement|change|edit|modify|refactor|实现|修改|重构/.test(s))
+    return "Reasoning through code changes";
+  if (/inspect|search|locate|read|context|定位|搜索|阅读|上下文/.test(s))
+    return "Locating relevant context";
+  return "";
+}
+function behaviorSummary(r: RunState) {
+  if (r.status === "succeeded") return "Task completed and result returned";
+  if (r.status === "failed")
+    return "Task failed and error details were retained";
+
+  const runningTool = r.tools.findLast((t) => t.status === "running");
+  if (runningTool) {
+    if (isMutationTool(runningTool)) return "Applying the plan to code";
+    if (runningTool.name === "bash" && isValidationCommand(runningTool))
+      return "Verifying whether the implementation passes";
+    if (runningTool.name === "bash" && isInspectionCommand(runningTool))
+      return "Inspecting current code state";
+    if (isSearchTool(runningTool)) return "Locating relevant code and context";
+    if (runningTool.name === "bash")
+      return "Validating assumptions with commands";
+    return "Using tools to advance the task";
   }
+
+  const recent = r.tools.slice(-5);
+  if (recent.some((t) => t.status === "failed"))
+    return "Investigating tool or command failure";
+  if (recent.some(isMutationTool)) return "Reviewing recent changes";
+  if (recent.some((t) => t.name === "bash" && isValidationCommand(t)))
+    return "Analyzing verification results";
   if (
-    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
-    (trimmed.startsWith("'") && trimmed.endsWith("'"))
-  ) {
-    return trimmed.slice(1, -1).trim() || null;
-  }
-  return trimmed;
+    recent.length >= 2 &&
+    recent.every(
+      (t) => isSearchTool(t) || (t.name === "bash" && isInspectionCommand(t)),
+    )
+  )
+    return "Mapping code structure and impact";
+
+  const intent = thinkingIntent(`${r.thinkingTail}\n${r.textTail}`);
+  if (intent) return intent;
+  if (!r.tools.length) return "Understanding the task and planning execution";
+  return "Advancing the task and preparing next steps";
 }
-
-function parseInlineList(value: string): string[] {
-  const trimmed = value.trim();
-  if (!trimmed || trimmed === "[]") return [];
-  const body =
-    trimmed.startsWith("[") && trimmed.endsWith("]")
-      ? trimmed.slice(1, -1)
-      : trimmed;
-  return body
-    .split(",")
-    .map((item) => parseFrontmatterScalar(item))
-    .filter((item): item is string => !!item);
+function progressState(d: ProgressDetails) {
+  const running = d.runs.filter((r) => r.status === "running").length;
+  const failed = d.runs.some((r) => r.status === "failed");
+  return failed
+    ? "failed"
+    : d.final
+      ? "completed"
+      : running
+        ? `${running} running`
+        : "pending";
 }
-
-function readIndentedList(
+function progressDone(d: ProgressDetails) {
+  return d.runs.filter((r) => r.status !== "pending" && r.status !== "running")
+    .length;
+}
+function summaryText(text: string) {
+  return `${text.trim().replace(/[。.!?…]+$/u, "")}...`;
+}
+function splitModelThinking(model?: string, fallbackThinking?: string) {
+  const m = model?.match(/^(.*):(off|minimal|low|medium|high|xhigh)$/i);
+  return {
+    model: m ? m[1] : model,
+    thinking: (m?.[2] ?? fallbackThinking)?.toLowerCase(),
+  };
+}
+function modelLabel(r: RunState) {
+  const { model, thinking } = splitModelThinking(r.model, r.thinking);
+  if (!model) return undefined;
+  return thinking && thinking !== "off" ? `${model}(${thinking})` : model;
+}
+function applyRunConfig(r: RunState, cfg: PiRunConfig) {
+  const parsed = splitModelThinking(cfg.model, cfg.thinking);
+  r.model = parsed.model;
+  r.thinking = parsed.thinking;
+}
+function runElapsed(d: ProgressDetails, r: RunState) {
+  const start = r.startedAt ?? d.startedAt;
+  const end =
+    r.finishedAt ?? (r.status === "running" ? Date.now() : d.updatedAt);
+  return fmtDur(Math.max(0, end - start));
+}
+function runHeader(d: ProgressDetails, r: RunState) {
+  const usage = fmtUsage(r.usage, modelLabel(r)) || fmtUsage(totalUsage(d));
+  return `${r.agent} · ${progressDone(d)}/${d.runs.length} done · ${progressState(d)} · ${runElapsed(d, r)}${usage ? ` · ${usage}` : ""}`;
+}
+function renderRunBlock(
   lines: string[],
-  startIndex: number,
-): { values: string[]; nextIndex: number } {
-  const values: string[] = [];
-  let index = startIndex + 1;
-  while (index < lines.length) {
-    const line = lines[index] ?? "";
-    if (/^[A-Za-z][A-Za-z0-9_-]*\s*:/.test(line)) break;
-    const item = line.match(/^\s*-\s*(.*)$/);
-    if (item) {
-      const scalar = parseFrontmatterScalar(item[1] ?? "");
-      if (scalar) values.push(scalar);
-    }
-    index += 1;
+  d: ProgressDetails,
+  run: RunState,
+  expanded: boolean,
+) {
+  const step = run.step ? `step ${run.step} · ` : "";
+  lines.push(`  - ${step}${runHeader(d, run)}`);
+  const summary = behaviorSummary(run);
+  if (summary) lines.push(`    › ${summaryText(summary)}`);
+  const visibleTools = expanded ? run.tools.slice(-8) : run.tools.slice(-1);
+  for (const t of visibleTools)
+    lines.push(`    ${toolIcon(t.status)} ${toolBrief(t)}`);
+  if (expanded && run.errorMessage) {
+    lines.push(`    ✗ ${oneLine(run.errorMessage, 120)}`);
   }
-  return { values, nextIndex: index - 1 };
 }
-
-function parseAgentConfig(content: string): AgentConfig {
-  const config: AgentConfig = { fallbackModels: [] };
-  const { frontmatter } = splitMarkdownFrontmatter(content);
-  const lines = frontmatter.split(/\r?\n/);
-
-  for (let index = 0; index < lines.length; index += 1) {
-    const match = (lines[index] ?? "").match(
-      /^([A-Za-z][A-Za-z0-9_-]*)\s*:\s*(.*)$/,
-    );
-    if (!match) continue;
-
-    const key = match[1] ?? "";
-    const value = match[2] ?? "";
-    if (key === "model") {
-      config.model = parseFrontmatterScalar(value) ?? undefined;
-    } else if (key === "thinking") {
-      config.thinking = normalizeThinking(parseFrontmatterScalar(value));
-    } else if (key === "fallbackModels" || key === "fallback_models") {
-      if (value.trim()) {
-        config.fallbackModels = parseInlineList(value);
-      } else {
-        const result = readIndentedList(lines, index);
-        config.fallbackModels = result.values;
-        index = result.nextIndex;
-      }
-    }
+function renderProgressCard(
+  d: ProgressDetails,
+  expanded: boolean,
+  w: number,
+): string[] {
+  const r = activeRun(d);
+  if (!r) return [];
+  const spinner = ["◐", "◓", "◑", "◒"][Math.floor(Date.now() / 250) % 4]!;
+  const icon = d.final
+    ? d.runs.some((x) => x.status === "failed")
+      ? "✗"
+      : "✓"
+    : spinner;
+  const totalElapsed = fmtDur(
+    (d.final ? d.updatedAt : Date.now()) - d.startedAt,
+  );
+  const lines: string[] = [
+    `${icon} subagent ${d.mode} · total ${totalElapsed}`,
+  ];
+
+  if (!expanded) {
+    renderRunBlock(lines, d, r, false);
+    lines.push("  Alt+O expand latest subagent card");
+    return lines.map((l) => trunc(l, w));
   }
 
-  return config;
+  for (const run of d.runs) renderRunBlock(lines, d, run, true);
+  lines.push("  Alt+O collapse latest subagent card");
+  const max = 48;
+  const shown =
+    lines.length > max
+      ? [
+          ...lines.slice(0, max - 1),
+          `  … ${lines.length - max + 1} lines hidden`,
+        ]
+      : lines;
+  return shown.map((l) => trunc(l, w));
 }
-
-function modelHasThinkingSuffix(model: string): boolean {
-  return THINKING_SUFFIX_RE.test(model.trim());
+function progressKey(d: ProgressDetails) {
+  return d.runs
+    .map((r) => {
+      const t = r.tools.at(-1);
+      return [
+        r.id,
+        r.status,
+        r.tools.length,
+        t?.id ?? "",
+        t?.status ?? "",
+        r.usage.turns,
+        r.usage.input,
+        r.usage.output,
+        r.usage.cacheRead,
+        r.usage.cacheWrite,
+        r.usage.ctxTokens,
+        r.model ?? "",
+        r.thinking ?? "",
+        r.errorMessage ?? "",
+      ].join("~");
+    })
+    .join("|");
 }
 
-function buildPiModelArgs(config: PiRunConfig): string[] {
-  const model = stringValue(config.model);
-  const thinking = normalizeThinking(config.thinking);
-  if (model) {
-    return [
-      "--model",
-      thinking && !modelHasThinkingSuffix(model)
-        ? `${model}:${thinking}`
-        : model,
-    ];
-  }
-  return thinking ? ["--thinking", thinking] : [];
+// ── Utilities ─────────────────────────────────────────────────────────
+function isObj(v: unknown): v is JsonObject {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
 }
-
-function resolveSubagentRunConfig(
-  input: SubagentInput,
-  agentConfig: AgentConfig,
-): PiRunConfig {
-  return {
-    model: stringValue(input.model) ?? agentConfig.model,
-    thinking: normalizeThinking(input.thinking) ?? agentConfig.thinking,
-  };
+function str(v: unknown): string | null {
+  return typeof v === "string" && v.trim() ? v.trim() : null;
 }
-
-function sanitizeKey(raw: string): string {
-  return raw
-    .trim()
-    .replace(/[^A-Za-z0-9._-]+/g, "_")
-    .replace(/^[._-]+|[._-]+$/g, "")
-    .slice(0, 160);
+function num(v: unknown): number {
+  return typeof v === "number" && Number.isFinite(v) ? v : 0;
 }
-
-function hashValue(raw: string): string {
-  return createHash("sha256").update(raw).digest("hex").slice(0, 24);
+function hash(s: string) {
+  return createHash("sha256").update(s).digest("hex").slice(0, 24);
 }
-
-interface PiInvocation {
-  command: string;
-  argsPrefix: string[];
-}
-
-const PI_CLI_JS_SEGMENTS = [
-  "node_modules",
-  "@mariozechner",
-  "pi-coding-agent",
-  "dist",
-  "cli.js",
-];
-const MAX_SUBAGENT_STDOUT_BYTES = 8 * 1024 * 1024;
-const MAX_SUBAGENT_STDERR_BYTES = 1024 * 1024;
-
-// Nested agents can emit unbounded output; keep the tail so diagnostics survive without growing memory indefinitely.
-class BoundedBufferCollector {
-  private chunks: Buffer[] = [];
-  private length = 0;
-  private truncatedBytes = 0;
-
-  constructor(private readonly maxBytes: number) {}
-
-  append(chunk: Buffer): void {
-    const data = chunk;
-    if (data.length >= this.maxBytes) {
-      this.truncatedBytes += this.length + data.length - this.maxBytes;
-      this.chunks = [data.subarray(data.length - this.maxBytes)];
-      this.length = this.maxBytes;
-      return;
-    }
-
-    this.chunks.push(data);
-    this.length += data.length;
-
-    while (this.length > this.maxBytes) {
-      const first = this.chunks[0];
-      if (!first) break;
-      const overflow = this.length - this.maxBytes;
-      if (first.length <= overflow) {
-        this.chunks.shift();
-        this.length -= first.length;
-        this.truncatedBytes += first.length;
-      } else {
-        this.chunks[0] = first.subarray(overflow);
-        this.length -= overflow;
-        this.truncatedBytes += overflow;
-        break;
-      }
-    }
-  }
-
-  toString(): string {
-    const body = Buffer.concat(this.chunks, this.length).toString("utf-8");
-    return this.truncatedBytes
-      ? `[${this.truncatedBytes} bytes truncated]\n${body}`
-      : body;
+function readText(p: string) {
+  try {
+    return readFileSync(p, "utf-8");
+  } catch {
+    return "";
   }
 }
-
-function isExistingFile(path: string): boolean {
+function exists(p: string) {
   try {
-    return statSync(path).isFile();
+    return statSync(p).isFile();
   } catch {
     return false;
   }
 }
-
-function uniqueStrings(values: string[]): string[] {
-  const seen = new Set<string>();
-  const unique: string[] = [];
-  for (const value of values) {
-    if (!value || seen.has(value)) continue;
-    seen.add(value);
-    unique.push(value);
-  }
-  return unique;
-}
-
-function candidatePiCliJsPaths(): string[] {
-  const candidates: string[] = [];
-
-  for (const arg of process.argv) {
-    if (/pi-coding-agent[\\/]dist[\\/]cli\.js$/i.test(arg)) {
-      candidates.push(resolve(arg));
-    }
-  }
-
-  const npmPrefix =
-    stringValue(process.env.npm_config_prefix) ??
-    stringValue(process.env.NPM_CONFIG_PREFIX);
-  if (npmPrefix) {
-    candidates.push(join(npmPrefix, ...PI_CLI_JS_SEGMENTS));
-    candidates.push(join(npmPrefix, "lib", ...PI_CLI_JS_SEGMENTS));
-  }
-
-  const appData = stringValue(process.env.APPDATA);
-  if (appData) {
-    candidates.push(join(appData, "npm", ...PI_CLI_JS_SEGMENTS));
-  }
-
-  const pathValue = process.env.PATH ?? process.env.Path ?? "";
-  for (const pathEntry of pathValue.split(delimiter)) {
-    const entry = pathEntry.trim();
-    if (!entry) continue;
-    candidates.push(join(entry, ...PI_CLI_JS_SEGMENTS));
-    candidates.push(join(dirname(entry), ...PI_CLI_JS_SEGMENTS));
-    candidates.push(join(dirname(entry), "lib", ...PI_CLI_JS_SEGMENTS));
-  }
-
-  return uniqueStrings(candidates);
-}
-
-function resolvePiInvocation(): PiInvocation {
-  const envCli = stringValue(process.env.TRELLIS_PI_CLI_JS);
-  if (envCli) {
-    const cliJs = resolve(envCli);
-    if (!isExistingFile(cliJs)) {
-      throw new Error(`TRELLIS_PI_CLI_JS points to a missing file: ${cliJs}`);
-    }
-    return { command: process.execPath, argsPrefix: [cliJs] };
-  }
-
-  for (const cliJs of candidatePiCliJsPaths()) {
-    if (isExistingFile(cliJs)) {
-      return { command: process.execPath, argsPrefix: [cliJs] };
-    }
-  }
-
-  return { command: "pi", argsPrefix: [] };
-}
-
-function createProcessContextKey(projectRoot: string): string {
-  return `pi_process_${hashValue(
-    [projectRoot, process.pid, Date.now(), randomBytes(8).toString("hex")].join(
-      ":",
-    ),
-  )}`;
+function shellQuote(v: string) {
+  return `'${v.replace(/'/g, `'\\''`)}'`;
 }
-
-function callString(
-  callback: (() => string | undefined) | undefined,
-): string | null {
-  if (!callback) return null;
+function callStr(cb: (() => string | undefined) | undefined): string | null {
+  if (!cb) return null;
   try {
-    return stringValue(callback());
+    return str(cb());
   } catch {
     return null;
   }
 }
-
-function lookupString(data: unknown, keys: string[]): string | null {
-  if (!isJsonObject(data)) return null;
-  for (const key of keys) {
-    const value = stringValue(data[key]);
-    if (value) return value;
+function lookupStr(data: unknown, keys: string[]): string | null {
+  if (!isObj(data)) return null;
+  for (const k of keys) {
+    const v = str(data[k]);
+    if (v) return v;
   }
-  for (const nestedKey of [
+  for (const nk of [
     "input",
     "properties",
     "event",
     "hook_input",
     "hookInput",
   ]) {
-    const nested = data[nestedKey];
-    const value = lookupString(nested, keys);
-    if (value) return value;
+    const nested = data[nk];
+    const v = lookupStr(nested, keys);
+    if (v) return v;
   }
   return null;
 }
-
-function extractTextContent(content: unknown): string {
+function cmdHasTrellisCtx(cmd: string) {
+  const t = cmd.trimStart();
+  return (
+    /^export\s+TRELLIS_CONTEXT_ID=/.test(t) ||
+    /^TRELLIS_CONTEXT_ID=/.test(t) ||
+    /^env\s+.*TRELLIS_CONTEXT_ID=/.test(t)
+  );
+}
+function fmtDur(ms: number) {
+  if (ms < 1000) return `${ms}ms`;
+  const s = Math.floor(ms / 1000);
+  if (s < 60) return `${s}s`;
+  return `${Math.floor(s / 60)}m${s % 60}s`;
+}
+function fmtNum(n: number) {
+  if (!n) return "0";
+  if (Math.abs(n) < 1000) return `${n}`;
+  if (Math.abs(n) < 1000000) return `${(n / 1000).toFixed(1)}k`;
+  return `${(n / 1000000).toFixed(1)}m`;
+}
+function fmtUsage(u: Usage, m?: string) {
+  const p: string[] = [];
+  if (u.turns) p.push(`${u.turns}t`);
+  if (u.input) p.push(`↑${fmtNum(u.input)}`);
+  if (u.output) p.push(`↓${fmtNum(u.output)}`);
+  if (u.cost) p.push(`$${u.cost.toFixed(3)}`);
+  if (u.ctxTokens) p.push(`ctx:${fmtNum(u.ctxTokens)}`);
+  if (m) p.push(m);
+  return p.join(" ");
+}
+function statusIcon(s: RunStatus) {
+  return s === "pending"
+    ? "○"
+    : s === "running"
+      ? "●"
+      : s === "succeeded"
+        ? "✓"
+        : s === "failed"
+          ? "✗"
+          : "⊘";
+}
+function toolIcon(s: ToolStatus) {
+  return s === "running" ? "•" : s === "succeeded" ? "✓" : "✗";
+}
+function latest(text: string, n: number) {
+  return text
+    .split(/\r?\n/)
+    .map((l) => l.trimEnd())
+    .filter((l) => l.trim())
+    .slice(-n);
+}
+function appendTail(cur: string, next: string, max: number) {
+  if (!next) return cur;
+  const c = cur + next;
+  return c.length <= max ? c : c.slice(-max);
+}
+function extractText(content: unknown): string {
   if (typeof content === "string") return content;
   if (!Array.isArray(content)) return "";
-
   return content
-    .map((block) => {
-      if (!isJsonObject(block)) return "";
-      return block.type === "text" && typeof block.text === "string"
-        ? block.text
-        : "";
-    })
+    .map((b) =>
+      isObj(b) && b.type === "text" && typeof b.text === "string" ? b.text : "",
+    )
     .join("");
 }
+function extractThinking(content: unknown): string {
+  if (!Array.isArray(content)) return "";
+  return content
+    .map((b) =>
+      isObj(b) && b.type === "thinking" && typeof b.thinking === "string"
+        ? b.thinking
+        : "",
+    )
+    .join("\n");
+}
+function newUsage(): Usage {
+  return {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    cost: 0,
+    ctxTokens: 0,
+    turns: 0,
+  };
+}
+function newRun(
+  id: string,
+  agent: string,
+  prompt: string,
+  step?: number,
+): RunState {
+  return {
+    id,
+    agent,
+    prompt: trunc(prompt.replace(/\s+/g, " ").trim(), 120) || "(empty)",
+    step,
+    status: "pending",
+    finalText: "",
+    textTail: "",
+    thinkingTail: "",
+    stderrTail: "",
+    tools: [],
+    usage: newUsage(),
+  };
+}
+function cloneProgress(d: ProgressDetails): ProgressDetails {
+  return {
+    ...d,
+    runs: d.runs.map((r) => ({
+      ...r,
+      tools: r.tools.map((t) => ({ ...t })),
+      usage: { ...r.usage },
+    })),
+  };
+}
 
-function extractFinalAssistantText(output: string): string | null {
-  let finalText = "";
-
-  for (const line of output.split(/\r?\n/)) {
-    const trimmed = line.trim();
-    if (!trimmed) continue;
+function oneLine(v: unknown, max = 80) {
+  return String(v || "...")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, max);
+}
+function summarizeToolArgs(name: string, args: unknown): string {
+  const a = isObj(args) ? args : {};
+  const summary: JsonObject = {};
+  if ("path" in a) summary.path = oneLine(a.path, 240);
+  if ("file_path" in a) summary.file_path = oneLine(a.file_path, 240);
+  if ("command" in a) summary.command = oneLine(a.command, 240);
+  if ("pattern" in a) summary.pattern = oneLine(a.pattern, 120);
+  if ("limit" in a) summary.limit = a.limit;
+  if ("offset" in a) summary.offset = a.offset;
+  if (name === "edit" && Array.isArray(a.edits))
+    summary.edits = `${a.edits.length} edit(s)`;
+  if (name === "write" && "content" in a)
+    summary.content = `<${String(a.content ?? "").length} chars>`;
+  const json = JSON.stringify(
+    Object.keys(summary).length ? summary : { tool: name },
+  );
+  return json.length <= MAX_TOOL_ARG_CHARS
+    ? json
+    : json.slice(0, MAX_TOOL_ARG_CHARS);
+}
+function toolBrief(t: ToolTrace): string {
+  const a = toolArgs(t);
+  if (t.name === "read") return `read: ${oneLine(a.path || a.file_path, 80)}`;
+  if (t.name === "bash") return `bash: ${oneLine(a.command, 60)}`;
+  if (t.name === "write") return `write: ${oneLine(a.path || a.file_path, 80)}`;
+  if (t.name === "edit") return `edit: ${oneLine(a.path || a.file_path, 80)}`;
+  if (t.name === "grep") return `grep: ${oneLine(a.pattern, 50)}`;
+  if (t.name === "find") return `find: ${oneLine(a.pattern || "*", 50)}`;
+  return oneLine(t.name, 50);
+}
 
-    try {
-      const event = JSON.parse(trimmed) as JsonObject;
-      const message = isJsonObject(event.message) ? event.message : null;
-      if (message?.role !== "assistant") continue;
+// ── Pi CLI path resolution ────────────────────────────────────────────
+const PI_CLI_SEGMENTS = [
+  ["node_modules", "@earendil-works", "pi-coding-agent", "dist", "cli.js"],
+  ["node_modules", "@mariozechner", "pi-coding-agent", "dist", "cli.js"],
+];
 
-      const text = extractTextContent(message.content);
-      if (text) finalText = text;
-    } catch {
-      // Pi can print non-JSON diagnostics around structured output; keep scanning.
-    }
+function resolvePiCli(): { command: string; args: string[] } {
+  const envCli = str(process.env.TRELLIS_PI_CLI_JS);
+  if (envCli) {
+    const p = resolve(envCli);
+    if (!exists(p)) throw new Error(`TRELLIS_PI_CLI_JS missing: ${p}`);
+    return { command: process.execPath, args: [p] };
+  }
+  const candidates: string[] = [];
+  for (const arg of process.argv)
+    if (/pi-coding-agent[\\/]dist[\\/]cli\.js$/i.test(arg))
+      candidates.push(resolve(arg));
+  const prefix =
+    str(process.env.npm_config_prefix) ?? str(process.env.NPM_CONFIG_PREFIX);
+  const appData = str(process.env.APPDATA);
+  const pathVal = process.env.PATH ?? process.env.Path ?? "";
+  const addBase = (base: string) => {
+    for (const seg of PI_CLI_SEGMENTS) candidates.push(join(base, ...seg));
+  };
+  if (prefix) {
+    addBase(prefix);
+    addBase(join(prefix, "lib"));
+  }
+  if (appData) addBase(join(appData, "npm"));
+  for (const entry of pathVal.split(delimiter)) {
+    const e = entry.trim();
+    if (!e) continue;
+    addBase(e);
+    addBase(dirname(e));
+    addBase(join(dirname(e), "lib"));
   }
+  for (const c of [...new Set(candidates)])
+    if (exists(c)) return { command: process.execPath, args: [c] };
+  return { command: "pi", args: [] };
+}
 
-  return finalText || null;
+function resolveRunCfg(
+  input: SubagentInput,
+  agentCfg: AgentConfig,
+  inheritedThinking?: string,
+): PiRunConfig {
+  const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"];
+  const normalize = (v: unknown): string | undefined => {
+    const s = typeof v === "string" && v.trim() ? v.trim().toLowerCase() : "";
+    return THINKING_LEVELS.includes(s) ? s : undefined;
+  };
+  const suffixRe = /:(off|minimal|low|medium|high|xhigh)$/i;
+  const inputModel = str(input.model);
+  const agentModel = agentCfg.model;
+  const rawModel = inputModel ?? agentModel;
+  const inputSuffixThinking = normalize(inputModel?.match(suffixRe)?.[1]);
+  const agentSuffixThinking = normalize(agentModel?.match(suffixRe)?.[1]);
+  const baseModel = rawModel?.replace(suffixRe, "");
+  const thinking =
+    normalize(input.thinking) ??
+    inputSuffixThinking ??
+    normalize(agentCfg.thinking) ??
+    agentSuffixThinking ??
+    normalize(inheritedThinking);
+  if (baseModel && thinking && thinking !== "off")
+    return { model: `${baseModel}:${thinking}`, thinking };
+  return { model: baseModel || rawModel, thinking };
 }
 
-function formatPiOutput(stdout: string, stderr: string): string {
-  return extractFinalAssistantText(stdout) ?? (stdout || stderr);
+function buildPiArgs(cfg: PiRunConfig): string[] {
+  const args = ["--mode", "json", "-p", "--no-session"];
+  if (cfg.model)
+    args.push(
+      "--model",
+      cfg.thinking && cfg.thinking !== "off" && !cfg.model.includes(":")
+        ? `${cfg.model}:${cfg.thinking}`
+        : cfg.model,
+    );
+  else if (cfg.thinking && cfg.thinking !== "off")
+    args.push("--thinking", cfg.thinking);
+  return args;
+}
+
+// ── BoundedBufferCollector ─────────────────────────────────────────────
+class BBC {
+  private c: Buffer[] = [];
+  private len = 0;
+  private trunc = 0;
+  constructor(private max: number) {}
+  append(b: Buffer) {
+    if (b.length >= this.max) {
+      this.trunc += this.len + b.length - this.max;
+      this.c = [b.subarray(b.length - this.max)];
+      this.len = this.max;
+      return;
+    }
+    this.c.push(b);
+    this.len += b.length;
+    while (this.len > this.max) {
+      const f = this.c[0]!;
+      if (f.length <= this.len - this.max) {
+        this.c.shift();
+        this.len -= f.length;
+        this.trunc += f.length;
+      } else {
+        const ov = this.len - this.max;
+        this.c[0] = f.subarray(ov);
+        this.len -= ov;
+        this.trunc += ov;
+        break;
+      }
+    }
+  }
+  toString() {
+    const body = Buffer.concat(this.c, this.len).toString("utf-8");
+    return this.trunc ? `[${this.trunc} bytes truncated]\n${body}` : body;
+  }
 }
 
-function normalizeTaskRef(raw: string): string | null {
-  let normalized = raw.trim().replace(/\\/g, "/");
-  if (!normalized) return null;
-  while (normalized.startsWith("./")) normalized = normalized.slice(2);
-  if (normalized.startsWith("tasks/")) normalized = `.trellis/${normalized}`;
-  return normalized;
+// ── Trellis Context ────────────────────────────────────────────────────
+function findRoot(start: string): string {
+  let c = resolve(start);
+  while (true) {
+    if (existsSync(join(c, ".trellis")) || existsSync(join(c, ".pi"))) return c;
+    const p = dirname(c);
+    if (p === c) return resolve(start);
+    c = p;
+  }
+}
+function splitFM(c: string) {
+  const m = c.replace(/^\uFEFF/, "").match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  return m
+    ? { fm: m[1] ?? "", body: c.slice(m[0].length) }
+    : { fm: "", body: c };
+}
+function stripFM(c: string) {
+  return splitFM(c).body.trimStart();
+}
+function parseAgentFM(c: string): AgentConfig {
+  const cfg: AgentConfig = { fallbackModels: [] };
+  const { fm } = splitFM(c);
+  const lines = fm.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const m = (lines[i] ?? "").match(/^([A-Za-z][A-Za-z0-9_-]*)\s*:\s*(.*)$/);
+    if (!m) continue;
+    const k = m[1] ?? "",
+      v = m[2] ?? "";
+    if (k === "model")
+      cfg.model = v.trim().replace(/^["']|["']$/g, "") || undefined;
+    else if (k === "thinking")
+      cfg.thinking = (v.trim().replace(/^["']|["']$/g, "") || undefined) as
+        | string
+        | undefined;
+    else if (k === "fallbackModels" || k === "fallback_models") {
+      if (v.trim()) {
+        cfg.fallbackModels = v
+          .trim()
+          .replace(/^\[|\]$/g, "")
+          .split(",")
+          .map((s) => s.trim().replace(/^["']|["']$/g, ""))
+          .filter(Boolean);
+      } else {
+        i++;
+        while (i < lines.length && /^\s+-\s/.test(lines[i] ?? "")) {
+          const item = (lines[i] ?? "")
+            .trim()
+            .replace(/^-\s+/, "")
+            .replace(/^["']|["']$/g, "");
+          if (item) cfg.fallbackModels.push(item);
+          i++;
+        }
+        i--;
+      }
+    }
+  }
+  return cfg;
 }
 
-function taskRefToDir(projectRoot: string, taskRef: string): string {
-  if (taskRef.startsWith("/")) return taskRef;
-  if (taskRef.startsWith(".trellis/")) return join(projectRoot, taskRef);
-  return join(projectRoot, ".trellis", "tasks", taskRef);
+function contextKey(input?: unknown, ctx?: PiExtensionContext): string | null {
+  const ov = str(process.env.TRELLIS_CONTEXT_ID);
+  if (ov) return ov.replace(/[^A-Za-z0-9._-]+/g, "_").slice(0, 160) || hash(ov);
+  const sessionId =
+    callStr(ctx?.sessionManager?.getSessionId) ??
+    str(process.env.PI_SESSION_ID) ??
+    str(process.env.PI_SESSIONID) ??
+    lookupStr(input, ["session_id", "sessionId", "sessionID"]);
+  if (sessionId)
+    return `pi_${sessionId.replace(/[^A-Za-z0-9._-]+/g, "_") || hash(sessionId)}`;
+  const transcriptPath =
+    callStr(ctx?.sessionManager?.getSessionFile) ??
+    lookupStr(input, ["transcript_path", "transcriptPath", "transcript"]);
+  if (transcriptPath) return `pi_transcript_${hash(transcriptPath)}`;
+  return null;
 }
 
-function sessionFileHasCurrentTask(path: string): boolean {
+function readTaskDir(root: string, key: string | null): string | null {
+  if (!key) return null;
   try {
-    const context = JSON.parse(readText(path)) as JsonObject;
-    return !!normalizeTaskRef(stringValue(context.current_task) ?? "");
+    const ctx = JSON.parse(
+      readText(join(root, ".trellis", ".runtime", "sessions", `${key}.json`)),
+    ) as JsonObject;
+    let ref = str(ctx.current_task);
+    if (!ref) return null;
+    ref = ref;
+    ref = ref.replace(/\\/g, "/").replace(/^\.\//, "");
+    if (ref.startsWith("tasks/")) ref = `.trellis/${ref}`;
+    return ref.startsWith(".trellis/")
+      ? join(root, ref)
+      : isAbsolute(ref)
+        ? ref
+        : join(root, ".trellis", "tasks", ref);
   } catch {
-    return false;
+    return null;
   }
 }
-
-function activeRuntimeContextKeys(projectRoot: string): string[] {
-  const sessionsDir = join(projectRoot, ".trellis", ".runtime", "sessions");
+function sessionHasTask(root: string, key: string): boolean {
   try {
-    return readdirSync(sessionsDir, { withFileTypes: true })
-      .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
-      .map((entry) => entry.name.slice(0, -".json".length))
-      .filter((key) =>
-        sessionFileHasCurrentTask(join(sessionsDir, `${key}.json`)),
-      );
+    const ctx = JSON.parse(
+      readText(join(root, ".trellis", ".runtime", "sessions", `${key}.json`)),
+    ) as JsonObject;
+    return !!str(ctx.current_task);
   } catch {
-    return [];
+    return false;
   }
 }
-
-function adoptExistingContextKey(
-  projectRoot: string,
-  contextKey: string,
-): string {
-  const sessionsDir = join(projectRoot, ".trellis", ".runtime", "sessions");
-  if (sessionFileHasCurrentTask(join(sessionsDir, `${contextKey}.json`))) {
-    return contextKey;
+function adoptKey(root: string, key: string): string {
+  if (sessionHasTask(root, key)) return key;
+  try {
+    const dir = join(root, ".trellis", ".runtime", "sessions");
+    const keys = readdirSync(dir)
+      .filter(
+        (f) => f.endsWith(".json") && sessionHasTask(root, f.slice(0, -5)),
+      )
+      .map((f) => f.slice(0, -5));
+    const proc = keys.filter((k) => k.startsWith("pi_process_"));
+    const cands = proc.length ? proc : keys;
+    return cands.length === 1 ? cands[0]! : key;
+  } catch {
+    return key;
   }
-
-  const keys = activeRuntimeContextKeys(projectRoot);
-  const processKeys = keys.filter((key) => key.startsWith("pi_process_"));
-  const candidates = processKeys.length ? processKeys : keys;
-  return candidates.length === 1 ? candidates[0] : contextKey;
 }
 
-function resolveContextKey(
-  input: unknown,
-  ctx?: PiExtensionContext,
-  fallback?: string | null,
-): string | null {
-  const override = stringValue(process.env.TRELLIS_CONTEXT_ID);
-  if (override) return sanitizeKey(override) || hashValue(override);
-
-  const sessionId =
-    callString(ctx?.sessionManager?.getSessionId) ??
-    stringValue(process.env.PI_SESSION_ID) ??
-    stringValue(process.env.PI_SESSIONID) ??
-    lookupString(input, ["session_id", "sessionId", "sessionID"]);
-  if (sessionId) return `pi_${sanitizeKey(sessionId) || hashValue(sessionId)}`;
-
-  const transcriptPath =
-    callString(ctx?.sessionManager?.getSessionFile) ??
-    lookupString(input, ["transcript_path", "transcriptPath", "transcript"]);
-  if (transcriptPath) return `pi_transcript_${hashValue(transcriptPath)}`;
-
-  return fallback ?? null;
-}
-
-function readCurrentTask(
-  projectRoot: string,
-  platformInput?: unknown,
-  ctx?: PiExtensionContext,
-  contextKeyOverride?: string | null,
-): string | null {
-  const contextKey =
-    contextKeyOverride ?? resolveContextKey(platformInput, ctx);
-  if (contextKey) {
-    try {
-      const rawContext = readText(
-        join(
-          projectRoot,
-          ".trellis",
-          ".runtime",
-          "sessions",
-          `${contextKey}.json`,
-        ),
-      );
-      const context = JSON.parse(rawContext) as JsonObject;
-      const taskRef = normalizeTaskRef(stringValue(context.current_task) ?? "");
-      if (taskRef) return taskRefToDir(projectRoot, taskRef);
-    } catch {
-      // Missing or malformed session context means no active task.
-    }
+// ── Workflow State Breadcrumb ─────────────────────────────────────────
+const WF_RE =
+  /\[workflow-state:([A-Za-z0-9_-]+)\]\s*\n([\s\S]*?)\n\s*\[\/workflow-state:\1\]/g;
+function workflowBreadcrumb(root: string, key: string | null): string {
+  const wf = readText(join(root, ".trellis", "workflow.md"));
+  if (!wf) return "";
+  const templates: Record<string, string> = {};
+  for (const m of wf.matchAll(WF_RE)) {
+    const s = m[1] ?? "",
+      b = (m[2] ?? "").trim();
+    if (s && b) templates[s] = b;
   }
-
-  return null;
-}
-
-function readJsonlFiles(
-  projectRoot: string,
-  taskDir: string,
-  jsonlName: string,
-): string {
-  const jsonlPath = join(taskDir, jsonlName);
-  const lines = readText(jsonlPath).split(/\r?\n/);
-  const chunks: string[] = [];
-
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (!trimmed) continue;
+  const dir = readTaskDir(root, key);
+  let header = "Status: no_task",
+    lookup = "no_task";
+  if (dir) {
     try {
-      const row = JSON.parse(trimmed) as JsonObject;
-      const file = typeof row.file === "string" ? row.file : "";
-      if (!file) continue;
-      const content = readText(join(projectRoot, file));
-      if (content) {
-        chunks.push(`## ${file}\n\n${content}`);
+      const d = JSON.parse(readText(join(dir, "task.json"))) as JsonObject;
+      const status = str(d.status) ?? "";
+      const id = str(d.id) ?? dir.split(/[\\/]/).pop() ?? "";
+      if (status) {
+        header = `Task: ${id} (${status})`;
+        lookup = status;
       }
-    } catch {
-      // Seed rows and malformed lines must not block sub-agent startup.
-    }
+    } catch {}
   }
-
-  return chunks.join("\n\n---\n\n");
+  const body = templates[lookup] ?? "Refer to workflow.md for current step.";
+  return `<workflow-state>\n${header}\n${body}\n</workflow-state>`;
 }
 
-function buildTrellisContext(
-  projectRoot: string,
-  agent: string,
-  platformInput?: unknown,
-  ctx?: PiExtensionContext,
-  contextKey?: string | null,
-): string {
-  const taskDir = readCurrentTask(projectRoot, platformInput, ctx, contextKey);
-  if (!taskDir) {
-    return "No active Trellis task found. Read .trellis/ before proceeding.";
+// ── Session Overview ───────────────────────────────────────────────────
+function sessionOverview(root: string, key: string | null): string {
+  const script = join(root, ".trellis", "scripts", "get_context.py");
+  if (!exists(script)) return "";
+  try {
+    const py = process.platform === "win32" ? "python" : "python3";
+    const result = spawnSync(py, [script], {
+      cwd: root,
+      env: key ? { ...process.env, TRELLIS_CONTEXT_ID: key } : process.env,
+      encoding: "utf-8",
+      timeout: SESSION_OVERVIEW_TIMEOUT_MS,
+      windowsHide: true,
+    });
+    if (result.status !== 0) return "";
+    const stdout = (result.stdout ?? "").trim();
+    return stdout ? `<session-overview>\n${stdout}\n</session-overview>` : "";
+  } catch {
+    return "";
   }
+}
 
-  const prd = readText(join(taskDir, "prd.md"));
-  const info = readText(join(taskDir, "info.md"));
+function buildContext(root: string, agent: string, key: string | null): string {
+  const dir = readTaskDir(root, key);
+  if (!dir)
+    return "No active Trellis task found. Read .trellis/ before proceeding.";
+  const prd = readText(join(dir, "prd.md"));
+  const design = readText(join(dir, "design.md"));
+  const impl = readText(join(dir, "implement.md"));
   const jsonlName = TRELLIS_AGENT_JSONL[agent] ?? "";
-  const specContext = jsonlName
-    ? readJsonlFiles(projectRoot, taskDir, jsonlName)
-    : "";
-
+  let spec = "";
+  if (jsonlName) {
+    const chunks: string[] = [];
+    for (const line of readText(join(dir, jsonlName)).split(/\r?\n/)) {
+      const t = line.trim();
+      if (!t) continue;
+      try {
+        const r = JSON.parse(t) as JsonObject;
+        const f = typeof r.file === "string" ? r.file : "";
+        if (f) {
+          const c = readText(join(root, f));
+          if (c) chunks.push(`## ${f}\n\n${c}`);
+        }
+      } catch {}
+    }
+    spec = chunks.join("\n\n---\n\n");
+  }
   return [
-    "## Trellis Task Context",
-    `Task directory: ${taskDir}`,
+    `## Trellis Task Context`,
+    `Task directory: ${dir}`,
     "",
     "### prd.md",
     prd || "(missing)",
-    info ? "\n### info.md\n" + info : "",
-    specContext ? "\n### Curated Spec / Research Context\n" + specContext : "",
+    design ? "\n### design.md\n" + design : "",
+    impl ? "\n### implement.md\n" + impl : "",
+    spec ? "\n### Curated Spec / Research Context\n" + spec : "",
   ].join("\n");
 }
 
-function normalizeAgentName(agent: string): string {
-  return agent.startsWith("trellis-") ? agent : `trellis-${agent}`;
+function normalizeAgent(agent: string | undefined): string {
+  const name = agent ?? "trellis-implement";
+  return name.startsWith("trellis-") ? name : `trellis-${name}`;
 }
 
-function readAgentDefinition(
-  projectRoot: string,
-  agent: string,
-): AgentDefinition {
-  const normalized = agent.startsWith("trellis-") ? agent : `trellis-${agent}`;
-  const raw = readText(join(projectRoot, ".pi", "agents", `${normalized}.md`));
-  return {
-    content: stripMarkdownFrontmatter(raw),
-    config: parseAgentConfig(raw),
-  };
+function isTrellisAgent(root: string, agent: string): boolean {
+  return existsSync(join(root, ".pi", "agents", `${agent}.md`));
 }
 
-function commandStartsWithTrellisContext(command: string): boolean {
-  const trimmed = command.trimStart();
-  return (
-    /^export\s+TRELLIS_CONTEXT_ID=/.test(trimmed) ||
-    /^TRELLIS_CONTEXT_ID=/.test(trimmed) ||
-    /^env\s+.*\bTRELLIS_CONTEXT_ID=/.test(trimmed)
-  );
+function buildPrompt(
+  root: string,
+  input: SubagentInput,
+  key: string | null,
+): string {
+  const agent = normalizeAgent(input.agent);
+  const raw = readText(join(root, ".pi", "agents", `${agent}.md`));
+  const def = stripFM(raw);
+  const ctx = buildContext(root, agent, key);
+  return [
+    "## Trellis Agent Definition",
+    def || "(missing)",
+    "",
+    ctx,
+    "",
+    "## Delegated Task",
+    input.prompt ?? "",
+  ].join("\n");
 }
 
-function shellQuote(value: string): string {
-  return `'${value.replace(/'/g, `'\\''`)}'`;
+// ── Event parsing ─────────────────────────────────────────────────────
+function parseJsonEvent(line: string): JsonObject | null {
+  const t = line.trim();
+  if (!t) return null;
+  const i = t.indexOf("{");
+  if (i < 0) return null;
+  try {
+    const p = JSON.parse(t.slice(i));
+    return isObj(p) ? p : null;
+  } catch {
+    return null;
+  }
 }
 
-function injectTrellisContextIntoBash(
-  event: unknown,
-  contextKey: string,
-): boolean {
-  const toolCall = event as PiToolCallEvent;
-  if (toolCall.toolName !== "bash" || !isJsonObject(toolCall.input)) {
-    return false;
+function applyEvent(r: RunState, evt: JsonObject): boolean {
+  const type = typeof evt.type === "string" ? evt.type : "";
+  if (!type) return false;
+  if (type === "agent_start" || type === "turn_start") {
+    r.status = "running";
+    r.startedAt ??= Date.now();
+    return true;
   }
-
-  const rawCommand = toolCall.input.command;
-  if (typeof rawCommand !== "string" || !rawCommand.trim()) {
+  if (type === "message_update") {
+    const ae = isObj(evt.assistantMessageEvent)
+      ? evt.assistantMessageEvent
+      : null;
+    if (!ae || typeof ae.delta !== "string") return false;
+    if (ae.type === "thinking_delta") {
+      r.thinkingTail = appendTail(r.thinkingTail, ae.delta, MAX_TAIL);
+      return true;
+    }
+    if (ae.type === "text_delta") {
+      r.textTail = appendTail(r.textTail, ae.delta, MAX_TAIL);
+      return true;
+    }
     return false;
   }
-  if (commandStartsWithTrellisContext(rawCommand)) {
-    return false;
+  if (type === "message_end" && isObj(evt.message)) {
+    const msg = evt.message;
+    if (msg.role !== "assistant") return false;
+    r.usage.turns += 1;
+    const u = isObj(msg.usage) ? msg.usage : null;
+    const cost = isObj(u?.cost) ? u.cost : null;
+    r.usage.input += num(u?.input);
+    r.usage.output += num(u?.output);
+    r.usage.cacheRead += num(u?.cacheRead);
+    r.usage.cacheWrite += num(u?.cacheWrite);
+    r.usage.cost += num(cost?.total);
+    r.usage.ctxTokens = num(u?.totalTokens);
+    const thinking = extractThinking(msg.content);
+    if (thinking) r.thinkingTail = appendTail("", thinking, MAX_TAIL);
+    const text = extractText(msg.content);
+    if (text) {
+      r.finalText = text;
+      r.textTail = appendTail("", text, MAX_TAIL);
+    }
+    if (typeof msg.model === "string") {
+      const parsed = splitModelThinking(msg.model, r.thinking);
+      r.model = parsed.model;
+      r.thinking = parsed.thinking;
+    }
+    if (typeof msg.errorMessage === "string") r.errorMessage = msg.errorMessage;
+    return true;
+  }
+  if (type === "tool_execution_start") {
+    const id =
+      typeof evt.toolCallId === "string"
+        ? evt.toolCallId
+        : hash(`${Date.now()}`);
+    const name = typeof evt.toolName === "string" ? evt.toolName : "tool";
+    const args = summarizeToolArgs(name, evt.args);
+    const existing = r.tools.findIndex((t) => t.id === id);
+    if (existing >= 0)
+      r.tools[existing] = { ...r.tools[existing]!, args, status: "running" };
+    else
+      r.tools.push({
+        id,
+        name,
+        args,
+        status: "running",
+        startedAt: Date.now(),
+      });
+    if (r.tools.length > MAX_TOOLS)
+      r.tools.splice(0, r.tools.length - MAX_TOOLS);
+    return true;
+  }
+  if (type === "tool_execution_end") {
+    const id = typeof evt.toolCallId === "string" ? evt.toolCallId : "";
+    const idx = r.tools.findIndex((t) => t.id === id);
+    if (idx >= 0)
+      r.tools[idx] = {
+        ...r.tools[idx]!,
+        status: evt.isError ? "failed" : "succeeded",
+        finishedAt: Date.now(),
+      };
+    return true;
   }
+  if (type === "agent_end") {
+    r.finishedAt = Date.now();
+    if (r.status === "running" || r.status === "pending")
+      r.status = "succeeded";
+    return true;
+  }
+  return false;
+}
 
-  toolCall.input.command = `export TRELLIS_CONTEXT_ID=${shellQuote(contextKey)}; ${rawCommand}`;
-  return true;
+function finalize(r: RunState, fallback: string): string {
+  return r.finalText || fallback.trim() || r.stderrTail.trim();
+}
+function formatPiOutput(stdout: string, stderr: string): string {
+  let ft = "";
+  for (const line of stdout.split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t) continue;
+    try {
+      const evt = JSON.parse(t) as JsonObject;
+      const msg = isObj(evt.message) ? evt.message : null;
+      if (msg?.role === "assistant") {
+        const txt = extractText(msg.content);
+        if (txt) ft = txt;
+      }
+    } catch {}
+  }
+  return ft || stdout || stderr;
 }
 
+// ── runPi: subprocess execution + event processing ───────────────────
 function runPi(
-  projectRoot: string,
+  root: string,
   prompt: string,
-  runConfig: PiRunConfig,
-  contextKey?: string | null,
+  cfg: PiRunConfig,
+  state: RunState,
+  emit: () => void,
+  key?: string | null,
   signal?: AbortSignal,
-): Promise<string> {
-  return new Promise((resolvePromise, reject) => {
+): Promise<{ output: string; failed: boolean }> {
+  return new Promise((resolve) => {
     if (signal?.aborted) {
-      reject(new Error("pi subagent cancelled"));
+      state.status = "cancelled";
+      state.errorMessage = "cancelled";
+      state.finishedAt = Date.now();
+      emit();
+      resolve({ output: "cancelled", failed: true });
       return;
     }
-
-    const invocation = resolvePiInvocation();
-    const modelArgs = buildPiModelArgs(runConfig);
-    const child = spawn(
-      invocation.command,
-      [
-        ...invocation.argsPrefix,
-        "--mode",
-        "text",
-        ...modelArgs,
-        "-p",
-        "--no-session",
-      ],
-      {
-        cwd: projectRoot,
-        env: contextKey
-          ? { ...process.env, TRELLIS_CONTEXT_ID: contextKey }
-          : process.env,
-        stdio: ["pipe", "pipe", "pipe"],
-        windowsHide: true,
-      },
-    );
-
-    const stdout = new BoundedBufferCollector(MAX_SUBAGENT_STDOUT_BYTES);
-    const stderr = new BoundedBufferCollector(MAX_SUBAGENT_STDERR_BYTES);
+    const inv = resolvePiCli();
+    const childEnv = {
+      ...process.env,
+      TRELLIS_SUBAGENT_CHILD: "1",
+      ...(key ? { TRELLIS_CONTEXT_ID: key } : {}),
+    };
+    const cli = spawn(inv.command, [...inv.args, ...buildPiArgs(cfg)], {
+      cwd: root,
+      env: childEnv,
+      stdio: ["pipe", "pipe", "pipe"],
+      windowsHide: true,
+    });
+    const stdout = new BBC(MAX_STDOUT);
+    const stderr = new BBC(MAX_STDERR);
+    let buf = "";
     let settled = false;
     let aborted = false;
-
-    const abortChild = (): void => {
+    let killTimer: ReturnType<typeof setTimeout> | null = null;
+    const abort = () => {
       aborted = true;
-      child.kill();
+      cli.kill();
+      killTimer = setTimeout(() => {
+        if (!settled && cli.exitCode === null) cli.kill("SIGKILL");
+      }, ABORT_KILL_GRACE_MS);
+      killTimer?.unref?.();
     };
-
-    const cleanup = (): void => {
-      signal?.removeEventListener("abort", abortChild);
-    };
-
-    const fail = (error: Error): void => {
+    const done = (v: { output: string; failed: boolean }) => {
       if (settled) return;
       settled = true;
-      cleanup();
-      reject(error);
+      if (killTimer) clearTimeout(killTimer);
+      signal?.removeEventListener("abort", abort);
+      emit();
+      resolve(v);
     };
-
-    const succeed = (value: string): void => {
-      if (settled) return;
-      settled = true;
-      cleanup();
-      resolvePromise(value);
+    signal?.addEventListener("abort", abort, { once: true });
+    state.status = "running";
+    state.startedAt = Date.now();
+    emit();
+    const processLine = (line: string) => {
+      const evt = parseJsonEvent(line);
+      if (evt && applyEvent(state, evt)) emit();
     };
-
-    signal?.addEventListener("abort", abortChild, { once: true });
-
-    child.stdout?.on("data", (chunk: Buffer) => stdout.append(chunk));
-    child.stderr?.on("data", (chunk: Buffer) => stderr.append(chunk));
-    child.stdin?.on("error", (error: Error & { code?: string }) => {
-      if (!aborted && error.code !== "EPIPE") fail(error);
+    cli.stdout?.on("data", (d: Buffer) => {
+      stdout.append(d);
+      buf += d.toString("utf-8");
+      if (buf.length > MAX_LINE_BUFFER) buf = buf.slice(-MAX_LINE_BUFFER);
+      const lines = buf.split(/\r?\n/);
+      buf = lines.pop() ?? "";
+      for (const l of lines) processLine(l);
     });
-    child.on("error", fail);
-    child.on("close", (code) => {
+    cli.stderr?.on("data", (d: Buffer) => {
+      stderr.append(d);
+      state.stderrTail = appendTail(
+        state.stderrTail,
+        d.toString("utf-8"),
+        MAX_TAIL,
+      );
+    });
+    cli.stdin?.on("error", (e: Error & { code?: string }) => {
+      if (!aborted && e.code !== "EPIPE")
+        done({ output: e.message, failed: true });
+    });
+    cli.on("error", (e) => {
+      state.status = aborted ? "cancelled" : "failed";
+      state.errorMessage = e instanceof Error ? e.message : String(e);
+      state.finishedAt = Date.now();
+      done({ output: finalize(state, state.errorMessage), failed: true });
+    });
+    cli.on("close", (code) => {
+      if (buf.trim()) processLine(buf);
       const out = stdout.toString();
       const err = stderr.toString();
+      state.stderrTail = appendTail("", err, MAX_TAIL);
+      state.finishedAt = Date.now();
       if (aborted) {
-        fail(new Error("pi subagent cancelled"));
-      } else if (code === 0) {
-        succeed(formatPiOutput(out, err));
-      } else {
-        fail(
-          new Error(err || out || `pi exited with code ${code ?? "unknown"}`),
-        );
+        state.status = "cancelled";
+        state.errorMessage = "cancelled";
+        done({ output: finalize(state, "cancelled"), failed: true });
+        return;
+      }
+      if (code === 0) {
+        if (state.status === "pending" || state.status === "running")
+          state.status = "succeeded";
+        done({
+          output: finalize(state, formatPiOutput(out, err)),
+          failed: false,
+        });
+        return;
       }
+      state.status = "failed";
+      state.errorMessage = err || out || `exit ${code ?? "?"}`;
+      done({ output: finalize(state, state.errorMessage), failed: true });
     });
-
-    child.stdin?.end(prompt);
+    cli.stdin?.end(prompt);
   });
 }
 
-function buildSubagentPrompt(
-  projectRoot: string,
-  input: SubagentInput,
-  contextKey?: string | null,
-  agentName?: string,
-  agentDefinition?: AgentDefinition,
-): string {
-  const normalized =
-    agentName ?? normalizeAgentName(input.agent ?? "trellis-implement");
-  const definition =
-    agentDefinition ?? readAgentDefinition(projectRoot, normalized);
-  const context = buildTrellisContext(
-    projectRoot,
-    normalized,
-    input,
-    undefined,
-    contextKey,
-  );
-  const prompt = input.prompt ?? "";
-
-  return [
-    "## Trellis Agent Definition",
-    definition.content || "(missing agent definition)",
-    "",
-    context,
-    "",
-    "## Delegated Task",
-    prompt,
-  ].join("\n");
-}
-
+// ── runSubagent: orchestrate single/parallel/chain via native partial updates ──
 async function runSubagent(
-  projectRoot: string,
+  root: string,
   input: SubagentInput,
-  contextKey?: string | null,
+  key: string | null,
   signal?: AbortSignal,
-): Promise<string> {
-  const agentName = normalizeAgentName(input.agent ?? "trellis-implement");
-  const agentDefinition = readAgentDefinition(projectRoot, agentName);
-  const runConfig = resolveSubagentRunConfig(input, agentDefinition.config);
+  onUpdate?: (r: PiToolResult) => void,
+  inheritedThinking?: string,
+): Promise<{ output: string; details: ProgressDetails; failed: boolean }> {
+  const agentName = normalizeAgent(input.agent);
+  const agentRaw = readText(join(root, ".pi", "agents", `${agentName}.md`));
+  const agentCfg = parseAgentFM(agentRaw);
+  const runCfg = resolveRunCfg(input, agentCfg, inheritedThinking);
   const mode = input.mode ?? "single";
-  if (mode === "parallel") {
-    const prompts = input.prompts ?? (input.prompt ? [input.prompt] : []);
-    const outputs = await Promise.all(
-      prompts.map((prompt) =>
-        runPi(
-          projectRoot,
-          buildSubagentPrompt(
-            projectRoot,
-            { ...input, prompt },
-            contextKey,
-            agentName,
-            agentDefinition,
+  const startedAt = Date.now();
+  const details: ProgressDetails = {
+    kind: "trellis-subagent-progress",
+    agent: agentName,
+    mode,
+    startedAt,
+    updatedAt: startedAt,
+    final: false,
+    runs: [],
+  };
+  let lastEmit = 0;
+  let lastPartialKey = "";
+  let closed = false;
+  const pushPartial = (force = false) => {
+    if (closed || !onUpdate) return;
+    const key = progressKey(details);
+    if (!force && key === lastPartialKey) return;
+    lastPartialKey = key;
+    onUpdate({
+      // Keep native partial content stable; renderResult owns the visible progress UI.
+      content: [{ type: "text", text: "subagent running" }],
+      details: cloneProgress(details),
+    });
+  };
+  const emit = (force = false) => {
+    const now = Date.now();
+    if (!force && now - lastEmit < THROTTLE_MS) return;
+    lastEmit = now;
+    details.updatedAt = now;
+    pushPartial(force);
+  };
+  const finish = (output: string, failed: boolean) => {
+    closed = true;
+    details.final = true;
+    details.updatedAt = Date.now();
+    return { output, details: cloneProgress(details), failed };
+  };
+
+  try {
+    if (mode === "parallel") {
+      const prompts = input.prompts ?? (input.prompt ? [input.prompt] : []);
+      details.runs = prompts.map((p, i) => {
+        const r = newRun(`${agentName}-${i + 1}`, agentName, p);
+        applyRunConfig(r, runCfg);
+        return r;
+      });
+      emit(true);
+      const results = await Promise.all(
+        prompts.map((p, i) =>
+          runPi(
+            root,
+            buildPrompt(root, { ...input, prompt: p }, key),
+            runCfg,
+            details.runs[i]!,
+            emit,
+            key,
+            signal,
           ),
-          runConfig,
-          contextKey,
-          signal,
-        ),
-      ),
-    );
-    return outputs.join("\n\n---\n\n");
-  }
-
-  if (mode === "chain") {
-    let previous = "";
-    const prompts = input.prompts ?? (input.prompt ? [input.prompt] : []);
-    for (const prompt of prompts) {
-      previous = await runPi(
-        projectRoot,
-        buildSubagentPrompt(
-          projectRoot,
-          {
-            ...input,
-            prompt: previous
-              ? `${prompt}\n\nPrevious output:\n${previous}`
-              : prompt,
-          },
-          contextKey,
-          agentName,
-          agentDefinition,
         ),
-        runConfig,
-        contextKey,
-        signal,
+      );
+      return finish(
+        results.map((r) => r.output).join("\n\n---\n\n"),
+        results.some((r) => r.failed),
       );
     }
-    return previous;
-  }
-
-  return runPi(
-    projectRoot,
-    buildSubagentPrompt(
-      projectRoot,
-      input,
-      contextKey,
-      agentName,
-      agentDefinition,
-    ),
-    runConfig,
-    contextKey,
-    signal,
-  );
+    if (mode === "chain") {
+      let prev = "";
+      let failed = false;
+      for (let i = 0; i < (input.prompts?.length ?? 1); i++) {
+        const p = input.prompts?.[i] ?? input.prompt ?? "";
+        const rs = newRun(`${agentName}-${i + 1}`, agentName, p, i + 1);
+        applyRunConfig(rs, runCfg);
+        details.runs.push(rs);
+        emit(true);
+        const result = await runPi(
+          root,
+          buildPrompt(
+            root,
+            {
+              ...input,
+              prompt: prev ? `${p}\n\nPrevious output:\n${prev}` : p,
+            },
+            key,
+          ),
+          runCfg,
+          rs,
+          emit,
+          key,
+          signal,
+        );
+        prev = result.output;
+        failed = failed || result.failed;
+        if (result.failed) break;
+      }
+      return finish(prev, failed);
+    }
+    const rs = newRun(`${agentName}-1`, agentName, input.prompt ?? "");
+    applyRunConfig(rs, runCfg);
+    details.runs = [rs];
+    emit(true);
+    const result = await runPi(
+      root,
+      buildPrompt(root, input, key),
+      runCfg,
+      rs,
+      emit,
+      key,
+      signal,
+    );
+    return finish(result.output, result.failed);
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    const r = activeRun(details);
+    if (r) {
+      r.status = "failed";
+      r.errorMessage = message;
+      r.finishedAt = Date.now();
+    }
+    return finish(message, true);
+  }
 }
 
+// ── Extension ──────────────────────────────────────────────────────────
 export default function trellisExtension(pi: {
   registerTool?: (tool: JsonObject) => void;
+  registerShortcut?: (
+    key: string,
+    opts: {
+      description?: string;
+      handler: (ctx: PiExtensionContext) => unknown;
+    },
+  ) => void;
   on?: (
     event: string,
     handler: (event: unknown, ctx?: PiExtensionContext) => unknown,
   ) => void;
-  cwd?: string;
+  getThinkingLevel?: () => string;
 }): void {
-  const projectRoot = findProjectRoot(pi.cwd ?? process.cwd());
-  const processContextKey = createProcessContextKey(projectRoot);
-  let currentContextKey: string | null = null;
-
-  const getContextKey = (input?: unknown, ctx?: PiExtensionContext): string => {
-    const resolvedContextKey = resolveContextKey(
-      input,
-      ctx,
-      currentContextKey ?? processContextKey,
-    );
-    currentContextKey = adoptExistingContextKey(
-      projectRoot,
-      resolvedContextKey ?? processContextKey,
-    );
-    return currentContextKey;
+  if (process.env.TRELLIS_SUBAGENT_CHILD === "1") return;
+  const root = findRoot(process.cwd());
+  const procKey = `pi_process_${hash([root, process.pid, Date.now(), randomBytes(8).toString("hex")].join(":"))}`;
+  let curKey: string | null = null;
+
+  const getKey = (input?: unknown, ctx?: PiExtensionContext) => {
+    const k = adoptKey(root, contextKey(input, ctx) ?? curKey ?? procKey);
+    curKey = k;
+    return k;
   };
 
+  // Per-turn cache to avoid double-spawning python
+  let turnCache: {
+    key: string | null;
+    ts: number;
+    wf: string;
+    ov: string;
+  } | null = null;
+  const getTurnCtx = (k: string | null) => {
+    const now = Date.now();
+    if (turnCache && turnCache.key === k && now - turnCache.ts < 1500)
+      return turnCache;
+    turnCache = {
+      key: k,
+      ts: now,
+      wf: workflowBreadcrumb(root, k),
+      ov: sessionOverview(root, k),
+    };
+    return turnCache;
+  };
+
+  // Toggle only the latest subagent native card; do not use Pi global tool expansion.
+  const toggleDetail = (ctx: PiExtensionContext) => {
+    const id = activeSubagentToolCallId;
+    const card = id ? nativeCards.get(id) : undefined;
+    if (!card) {
+      ctx.ui?.notify?.("No subagent card to toggle yet.", "warning");
+      return;
+    }
+    card.state.localExpanded = card.state.localExpanded !== true;
+    card.invalidate();
+  };
+
+  pi.registerShortcut?.("alt+o", {
+    description: "Toggle latest subagent card details",
+    handler: async (ctx: PiExtensionContext) => toggleDetail(ctx),
+  });
+
+  // Tool registration
   pi.registerTool?.({
-    name: "subagent",
-    label: "Subagent",
+    name: "trellis_subagent",
+    label: "Trellis Subagent",
     description: "Run a Trellis project sub-agent with active task context.",
+    promptSnippet:
+      'Sub-agent dispatch protocol (Trellis): your dispatch prompt MUST start with one line "Active task: <task path from `task.py current`>" before any other instructions.',
+    promptGuidelines: [
+      'Use subagent for task delegation. Your dispatch prompt MUST start with "Active task: <task path from `task.py current`>".',
+    ],
     parameters: {
       type: "object",
       properties: {
@@ -916,15 +1412,11 @@ export default function trellisExtension(pi: {
           type: "string",
           description: "Task prompt for the sub-agent.",
         },
-        mode: {
-          type: "string",
-          enum: ["single", "parallel", "chain"],
-          description: "Delegation mode.",
-        },
+        mode: { type: "string", enum: ["single", "parallel", "chain"] },
         prompts: {
           type: "array",
           items: { type: "string" },
-          description: "Prompts for parallel or chain mode.",
+          maxItems: MAX_PARALLEL_PROMPTS,
         },
         model: {
           type: "string",
@@ -933,65 +1425,176 @@ export default function trellisExtension(pi: {
         },
         thinking: {
           type: "string",
-          enum: ["off", "minimal", "low", "medium", "high", "xhigh"],
           description:
             "Optional Pi thinking level override for the child sub-agent process.",
+          enum: ["off", "minimal", "low", "medium", "high", "xhigh"],
         },
       },
-      required: ["prompt"],
     },
     execute: async (
-      _toolCallId: string,
+      id: string,
       input: SubagentInput,
-      _signal?: AbortSignal,
-      _onUpdate?: (partialResult: PiToolResult) => void,
+      signal?: AbortSignal,
+      onUpdate?: (r: PiToolResult) => void,
       ctx?: PiExtensionContext,
-    ): Promise<PiToolResult> => {
-      const contextKey = getContextKey(input, ctx);
-      const output = await runSubagent(projectRoot, input, contextKey, _signal);
+    ) => {
+      activeSubagentToolCallId = id;
+      const agentName = normalizeAgent(input.agent);
+      if (!isTrellisAgent(root, agentName)) {
+        return {
+          content: [
+            {
+              type: "text",
+              text:
+                "`trellis_subagent` is only for Trellis workflow agents with a definition file in .pi/agents/.\n\n" +
+                `No definition found for: ${agentName}\n\n` +
+                "For general-purpose sub-agents, use one of these community tools:\n" +
+                "- `subagent` tool from npm:pi-subagents (nicobailon/pi-subagents)\n" +
+                "- `Agent` tool from npm:@tintinweb/pi-subagents\n\n" +
+                "If neither is installed, ask the user to either:\n" +
+                `- Create .pi/agents/${agentName}.md for your custom Trellis agent\n` +
+                "- Install a community subagent package: pi install -l npm:@tintinweb/pi-subagents",
+            },
+          ],
+          details: { agent: agentName, error: "not a trellis workflow agent" },
+        };
+      }
+      const mode = input.mode ?? "single";
+      const prompt = input.prompt?.trim();
+      const prompts = input.prompts?.map((p) => p.trim()).filter(Boolean);
+      if (mode === "single" && !prompt)
+        throw new Error("subagent prompt is required for single mode");
+      if (
+        (mode === "parallel" || mode === "chain") &&
+        !prompt &&
+        !prompts?.length
+      )
+        throw new Error(
+          "subagent prompt or prompts are required for parallel/chain mode",
+        );
+      if (
+        mode === "parallel" &&
+        prompts &&
+        prompts.length > MAX_PARALLEL_PROMPTS
+      )
+        throw new Error(
+          `subagent parallel mode supports at most ${MAX_PARALLEL_PROMPTS} prompts`,
+        );
+      const cleanInput: SubagentInput = {
+        ...input,
+        prompt,
+        prompts: prompts?.length ? prompts : undefined,
+      };
+      const key = getKey(cleanInput, ctx);
+      const inheritedThinking = pi.getThinkingLevel?.();
+      const result = await runSubagent(
+        root,
+        cleanInput,
+        key,
+        signal,
+        onUpdate,
+        inheritedThinking,
+      );
       return {
-        content: [{ type: "text", text: output }],
-        details: {
-          agent: input.agent ?? "trellis-implement",
-          mode: input.mode ?? "single",
+        content: [{ type: "text", text: result.output }],
+        details: result.details,
+      };
+    },
+    // Hide the call renderer so the native card only shows result/progress once.
+    renderCall: () => ({
+      render() {
+        return [];
+      },
+      invalidate() {},
+    }),
+    renderResult: (
+      result: PiToolResult,
+      _opts?: { expanded?: boolean; isPartial?: boolean },
+      _theme?: unknown,
+      context?: unknown,
+    ) => {
+      const ctxObj = isObj(context) ? context : null;
+      const toolCallId = str(ctxObj?.toolCallId);
+      const state = isObj(ctxObj?.state) ? (ctxObj.state as JsonObject) : null;
+      const invalidate =
+        typeof ctxObj?.invalidate === "function"
+          ? (ctxObj.invalidate as () => void)
+          : null;
+      const isProgress =
+        isObj(result.details) &&
+        result.details.kind === "trellis-subagent-progress";
+      if (toolCallId && state && invalidate) {
+        const updatedAt = isProgress
+          ? (result.details as ProgressDetails).updatedAt
+          : Date.now();
+        rememberNativeCard(toolCallId, { state, invalidate, updatedAt });
+      }
+      return {
+        render(w: number) {
+          if (isProgress) {
+            const expanded = state?.localExpanded === true;
+            return renderProgressCard(
+              result.details as ProgressDetails,
+              expanded,
+              w,
+            );
+          }
+          return [trunc(result.content?.[0]?.text ?? "(no output)", w)];
         },
+        invalidate() {},
       };
     },
   });
 
+  // Events
   pi.on?.("session_start", (event, ctx) => {
-    getContextKey(event, ctx);
+    getKey(event, ctx);
     ctx?.ui?.notify?.(
       "Trellis project context is available. Use /trellis-continue to resume the current task.",
       "info",
     );
   });
+  pi.on?.("session_shutdown", () => {
+    nativeCards.clear();
+    activeSubagentToolCallId = null;
+  });
+  pi.on?.("tool_call", (event, ctx) => {
+    const k = getKey(event, ctx);
+    const ev = event as { toolName?: string; input?: JsonObject };
+    if (
+      ev.toolName === "bash" &&
+      isObj(ev.input) &&
+      typeof ev.input.command === "string" &&
+      !cmdHasTrellisCtx(ev.input.command)
+    )
+      ev.input.command = `export TRELLIS_CONTEXT_ID=${shellQuote(k)}; ${ev.input.command}`;
+  });
+  // Preserve progress details from execute(); mark failed subagent results through
+  // the official tool_result patch hook instead of throwing away renderer details.
+  pi.on?.("tool_result", (event) => {
+    const ev = event as { toolName?: string; details?: unknown };
+    if (
+      ev.toolName === "trellis_subagent" &&
+      isObj(ev.details) &&
+      ev.details.kind === "trellis-subagent-progress" &&
+      Array.isArray(ev.details.runs) &&
+      ev.details.runs.some(
+        (r) => isObj(r) && (r.status === "failed" || r.status === "cancelled"),
+      )
+    )
+      return { isError: true };
+    return undefined;
+  });
   pi.on?.("before_agent_start", (event, ctx) => {
-    const contextKey = getContextKey(event, ctx);
-    const current = (event as PiBeforeAgentStartEvent).systemPrompt ?? "";
-    const context = buildTrellisContext(
-      projectRoot,
-      "trellis-implement",
-      event,
-      ctx,
-      contextKey,
-    );
+    const k = getKey(event, ctx);
+    const cur = (event as { systemPrompt?: string }).systemPrompt ?? "";
+    const ctxText = buildContext(root, "trellis-implement", k);
+    const { wf, ov } = getTurnCtx(k);
     return {
-      systemPrompt: [current, context].filter(Boolean).join("\n\n"),
+      systemPrompt: [cur, ctxText, wf, ov].filter(Boolean).join("\n\n"),
     };
   });
   pi.on?.("context", (event, ctx) => {
-    getContextKey(event, ctx);
-    const messages = (event as PiContextEvent).messages;
-    return Array.isArray(messages) ? { messages } : undefined;
-  });
-  pi.on?.("input", (event, ctx) => {
-    getContextKey(event, ctx);
-    return { action: "continue" };
-  });
-  pi.on?.("tool_call", (event, ctx) => {
-    const contextKey = getContextKey(event, ctx);
-    injectTrellisContextIntoBash(event, contextKey);
-    return undefined;
+    getKey(event, ctx);
   });
 }