@leing2021/super-pi 0.23.8 → 0.23.10

package/extensions/ce-core/tools/subagent-renderer.ts

@@ -0,0 +1,453 @@
+/**
+ * TUI renderers for ce_subagent and ce_parallel_subagent.
+ *
+ * Displays real-time status in pi tool frames:
+ *   - Collapsed: status icon + agent name + recent tool calls + usage
+ *   - Expanded (Ctrl+O): full tool calls + final output + per-task usage
+ *
+ * Tool call formatting (formatToolCall) adapted directly from pi official
+ * subagent example with super-pi skill semantic adaptations.
+ */
+
+import * as os from "node:os"
+import { Container, Markdown, Spacer, Text } from "@mariozechner/pi-tui"
+import {
+  type SingleResult,
+  getFinalOutput,
+  getDisplayItems,
+  isFailedResult,
+  formatUsageStats,
+  type DisplayItem,
+} from "./subagent-events"
+import type { SubagentLiveDetails } from "./subagent"
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const COLLAPSED_ITEM_COUNT = 10
+
+// ---------------------------------------------------------------------------
+// Tool call formatting (from pi official subagent example)
+// ---------------------------------------------------------------------------
+
+export function formatToolCall(
+  toolName: string,
+  args: Record<string, unknown>,
+  themeFg: (color: any, text: string) => string,
+): string {
+  const shortenPath = (p: string) => {
+    const home = os.homedir()
+    return p.startsWith(home) ? `~${p.slice(home.length)}` : p
+  }
+
+  switch (toolName) {
+    case "bash": {
+      const command = (args.command as string) || "..."
+      const preview = command.length > 60 ? `${command.slice(0, 60)}...` : command
+      return themeFg("muted", "$ ") + themeFg("toolOutput", preview)
+    }
+    case "read": {
+      const rawPath = (args.file_path || args.path || "...") as string
+      const filePath = shortenPath(rawPath)
+      const offset = args.offset as number | undefined
+      const limit = args.limit as number | undefined
+      let text = themeFg("accent", filePath)
+      if (offset !== undefined || limit !== undefined) {
+        const startLine = offset ?? 1
+        const endLine = limit !== undefined ? startLine + limit - 1 : ""
+        text += themeFg("warning", `:${startLine}${endLine ? `-${endLine}` : ""}`)
+      }
+      return themeFg("muted", "read ") + text
+    }
+    case "write": {
+      const rawPath = (args.file_path || args.path || "...") as string
+      const filePath = shortenPath(rawPath)
+      const content = (args.content || "") as string
+      const lines = content.split("\n").length
+      let text = themeFg("muted", "write ") + themeFg("accent", filePath)
+      if (lines > 1) text += themeFg("dim", ` (${lines} lines)`)
+      return text
+    }
+    case "edit": {
+      const rawPath = (args.file_path || args.path || "...") as string
+      return themeFg("muted", "edit ") + themeFg("accent", shortenPath(rawPath))
+    }
+    case "ls": {
+      const rawPath = (args.path || ".") as string
+      return themeFg("muted", "ls ") + themeFg("accent", shortenPath(rawPath))
+    }
+    case "find": {
+      const pattern = (args.pattern || "*") as string
+      const rawPath = (args.path || ".") as string
+      return themeFg("muted", "find ") + themeFg("accent", pattern) + themeFg("dim", ` in ${shortenPath(rawPath)}`)
+    }
+    case "grep": {
+      const pattern = (args.pattern || "") as string
+      const rawPath = (args.path || ".") as string
+      return (
+        themeFg("muted", "grep ") +
+        themeFg("accent", `/${pattern}/`) +
+        themeFg("dim", ` in ${shortenPath(rawPath)}`)
+      )
+    }
+    default: {
+      const argsStr = JSON.stringify(args)
+      const preview = argsStr.length > 50 ? `${argsStr.slice(0, 50)}...` : argsStr
+      return themeFg("accent", toolName) + themeFg("dim", ` ${preview}`)
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Theme type
+// ---------------------------------------------------------------------------
+
+interface Theme {
+  fg: (color: any, text: string) => string
+  bold: (text: string) => string
+}
+
+// ---------------------------------------------------------------------------
+// renderCall
+// ---------------------------------------------------------------------------
+
+export function renderSubagentCall(
+  args: {
+    agent?: string
+    task?: string
+    chain?: Array<{ agent: string; task: string }>
+    tasks?: Array<{ agent: string; task: string }>
+  },
+  theme: Theme,
+): any {
+  if (args.chain && args.chain.length > 0) {
+    let text =
+      theme.fg("toolTitle", theme.bold("ce_subagent ")) +
+      theme.fg("accent", `chain (${args.chain.length} steps)`)
+    for (let i = 0; i < Math.min(args.chain.length, 3); i++) {
+      const step = args.chain[i]
+      const cleanTask = step.task.replace(/\{previous\}/g, "").trim()
+      const preview = cleanTask.length > 40 ? `${cleanTask.slice(0, 40)}...` : cleanTask
+      text +=
+        "\n  " +
+        theme.fg("muted", `${i + 1}.`) +
+        " " +
+        theme.fg("accent", step.agent) +
+        theme.fg("dim", ` ${preview}`)
+    }
+    if (args.chain.length > 3) text += `\n  ${theme.fg("muted", `... +${args.chain.length - 3} more`)}`
+    return new Text(text, 0, 0)
+  }
+
+  if (args.tasks && args.tasks.length > 0) {
+    let text =
+      theme.fg("toolTitle", theme.bold("ce_parallel_subagent ")) +
+      theme.fg("accent", `parallel (${args.tasks.length} tasks)`)
+    for (const t of args.tasks.slice(0, 3)) {
+      const preview = t.task.length > 40 ? `${t.task.slice(0, 40)}...` : t.task
+      text += `\n  ${theme.fg("accent", t.agent)}${theme.fg("dim", ` ${preview}`)}`
+    }
+    if (args.tasks.length > 3) text += `\n  ${theme.fg("muted", `... +${args.tasks.length - 3} more`)}`
+    return new Text(text, 0, 0)
+  }
+
+  // Single mode
+  const agentName = args.agent || "..."
+  const preview = args.task ? (args.task.length > 60 ? `${args.task.slice(0, 60)}...` : args.task) : "..."
+  let text =
+    theme.fg("toolTitle", theme.bold("ce_subagent ")) +
+    theme.fg("accent", agentName)
+  text += `\n  ${theme.fg("dim", preview)}`
+  return new Text(text, 0, 0)
+}
+
+// ---------------------------------------------------------------------------
+// renderResult
+// ---------------------------------------------------------------------------
+
+interface RenderContext {
+  expanded: boolean
+}
+
+export function renderSubagentResult(
+  details: SubagentLiveDetails,
+  context: RenderContext,
+  theme: Theme,
+): any {
+  if (!details || !details.results || details.results.length === 0) {
+    return new Text("(no output)", 0, 0)
+  }
+
+  const mdTheme = getMarkdownTheme()
+
+  const renderDisplayItems = (items: DisplayItem[], limit?: number) => {
+    const toShow = limit ? items.slice(-limit) : items
+    const skipped = limit && items.length > limit ? items.length - limit : 0
+    let text = ""
+    if (skipped > 0) text += theme.fg("muted", `... ${skipped} earlier items\n`)
+    for (const item of toShow) {
+      if (item.type === "text") {
+        const preview = context.expanded ? item.text : item.text.split("\n").slice(0, 3).join("\n")
+        text += `${theme.fg("toolOutput", preview)}\n`
+      } else {
+        text += `${theme.fg("muted", "→ ") + formatToolCall(item.name, item.args, theme.fg.bind(theme))}\n`
+      }
+    }
+    return text.trimEnd()
+  }
+
+  // --- Single mode ---
+  if (details.mode === "single" && details.results.length === 1) {
+    return renderSingleResult(details.results[0], context, theme, mdTheme, renderDisplayItems)
+  }
+
+  // --- Chain mode ---
+  if (details.mode === "chain") {
+    return renderChainResult(details.results, context, theme, mdTheme, renderDisplayItems)
+  }
+
+  // --- Parallel mode ---
+  if (details.mode === "parallel") {
+    return renderParallelResult(details.results, context, theme, mdTheme, renderDisplayItems)
+  }
+
+  return new Text("(no output)", 0, 0)
+}
+
+// ---------------------------------------------------------------------------
+// Single result renderer
+// ---------------------------------------------------------------------------
+
+function renderSingleResult(
+  r: SingleResult,
+  context: RenderContext,
+  theme: Theme,
+  mdTheme: any,
+  renderDisplayItems: (items: DisplayItem[], limit?: number) => string,
+): any {
+  const isError = isFailedResult(r)
+  const icon = isError ? theme.fg("error", "✗") : r.exitCode === -1 ? theme.fg("warning", "⏳") : theme.fg("success", "✓")
+  const displayItems = getDisplayItems(r.messages)
+  const finalOutput = getFinalOutput(r.messages)
+
+  if (context.expanded) {
+    const container = new Container()
+    let header = `${icon} ${theme.fg("toolTitle", theme.bold(r.agent))}`
+    if (isError && r.stopReason) header += ` ${theme.fg("error", `[${r.stopReason}]`)}`
+    container.addChild(new Text(header, 0, 0))
+    if (isError && r.errorMessage)
+      container.addChild(new Text(theme.fg("error", `Error: ${r.errorMessage}`), 0, 0))
+    container.addChild(new Spacer(1))
+    container.addChild(new Text(theme.fg("muted", "─── Task ───"), 0, 0))
+    container.addChild(new Text(theme.fg("dim", r.task), 0, 0))
+    container.addChild(new Spacer(1))
+    container.addChild(new Text(theme.fg("muted", "─── Output ───"), 0, 0))
+    if (displayItems.length === 0 && !finalOutput) {
+      container.addChild(new Text(theme.fg("muted", r.exitCode === -1 ? "(running...)" : "(no output)"), 0, 0))
+    } else {
+      for (const item of displayItems) {
+        if (item.type === "toolCall")
+          container.addChild(
+            new Text(theme.fg("muted", "→ ") + formatToolCall(item.name, item.args, theme.fg.bind(theme)), 0, 0),
+          )
+      }
+      if (finalOutput) {
+        container.addChild(new Spacer(1))
+        container.addChild(new Markdown(finalOutput.trim(), 0, 0, mdTheme))
+      }
+    }
+    const usageStr = formatUsageStats(r.usage, r.model)
+    if (usageStr) {
+      container.addChild(new Spacer(1))
+      container.addChild(new Text(theme.fg("dim", usageStr), 0, 0))
+    }
+    return container
+  }
+
+  // Collapsed
+  let text = `${icon} ${theme.fg("toolTitle", theme.bold(r.agent))}`
+  if (isError && r.stopReason) text += ` ${theme.fg("error", `[${r.stopReason}]`)}`
+  if (isError && r.errorMessage) text += `\n${theme.fg("error", `Error: ${r.errorMessage}`)}`
+  else if (r.exitCode === -1) text += `\n${theme.fg("muted", "(running...)")}`
+  else if (displayItems.length === 0) text += `\n${theme.fg("muted", "(no output)")}`
+  else {
+    text += `\n${renderDisplayItems(displayItems, COLLAPSED_ITEM_COUNT)}`
+    if (displayItems.length > COLLAPSED_ITEM_COUNT) text += `\n${theme.fg("muted", "(Ctrl+O to expand)")}`
+  }
+  const usageStr = formatUsageStats(r.usage, r.model)
+  if (usageStr) text += `\n${theme.fg("dim", usageStr)}`
+  return new Text(text, 0, 0)
+}
+
+// ---------------------------------------------------------------------------
+// Chain result renderer
+// ---------------------------------------------------------------------------
+
+function aggregateUsage(results: SingleResult[]) {
+  const total = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 }
+  for (const r of results) {
+    total.input += r.usage.input
+    total.output += r.usage.output
+    total.cacheRead += r.usage.cacheRead
+    total.cacheWrite += r.usage.cacheWrite
+    total.cost += r.usage.cost
+    total.contextTokens += r.usage.contextTokens
+    total.turns += r.usage.turns
+  }
+  return total
+}
+
+function renderChainResult(
+  results: SingleResult[],
+  context: RenderContext,
+  theme: Theme,
+  mdTheme: any,
+  renderDisplayItems: (items: DisplayItem[], limit?: number) => string,
+): any {
+  const successCount = results.filter(r => r.exitCode === 0).length
+  const icon = successCount === results.length ? theme.fg("success", "✓") : theme.fg("error", "✗")
+
+  if (context.expanded) {
+    const container = new Container()
+    container.addChild(
+      new Text(
+        `${icon} ${theme.fg("toolTitle", theme.bold("chain "))}${theme.fg("accent", `${successCount}/${results.length} steps`)}`,
+        0, 0,
+      ),
+    )
+    for (const r of results) {
+      const rIcon = r.exitCode === 0 ? theme.fg("success", "✓") : theme.fg("error", "✗")
+      const displayItems = getDisplayItems(r.messages)
+      const finalOutput = getFinalOutput(r.messages)
+
+      container.addChild(new Spacer(1))
+      container.addChild(new Text(`${theme.fg("muted", `─── Step ${r.step ?? "?"}: `)}${theme.fg("accent", r.agent)} ${rIcon}`, 0, 0))
+      container.addChild(new Text(theme.fg("muted", "Task: ") + theme.fg("dim", r.task), 0, 0))
+      for (const item of displayItems) {
+        if (item.type === "toolCall")
+          container.addChild(new Text(theme.fg("muted", "→ ") + formatToolCall(item.name, item.args, theme.fg.bind(theme)), 0, 0))
+      }
+      if (finalOutput) {
+        container.addChild(new Spacer(1))
+        container.addChild(new Markdown(finalOutput.trim(), 0, 0, mdTheme))
+      }
+      const stepUsage = formatUsageStats(r.usage, r.model)
+      if (stepUsage) container.addChild(new Text(theme.fg("dim", stepUsage), 0, 0))
+    }
+    const usageStr = formatUsageStats(aggregateUsage(results))
+    if (usageStr) {
+      container.addChild(new Spacer(1))
+      container.addChild(new Text(theme.fg("dim", `Total: ${usageStr}`), 0, 0))
+    }
+    return container
+  }
+
+  // Collapsed
+  let text = `${icon} ${theme.fg("toolTitle", theme.bold("chain "))}${theme.fg("accent", `${successCount}/${results.length} steps`)}`
+  for (const r of results) {
+    const rIcon = r.exitCode === 0 ? theme.fg("success", "✓") : theme.fg("error", "✗")
+    const displayItems = getDisplayItems(r.messages)
+    text += `\n\n${theme.fg("muted", `─── Step ${r.step ?? "?"}: `)}${theme.fg("accent", r.agent)} ${rIcon}`
+    if (displayItems.length === 0) text += `\n${theme.fg("muted", "(no output)")}`
+    else text += `\n${renderDisplayItems(displayItems, 5)}`
+  }
+  const usageStr = formatUsageStats(aggregateUsage(results))
+  if (usageStr) text += `\n\n${theme.fg("dim", `Total: ${usageStr}`)}`
+  text += `\n${theme.fg("muted", "(Ctrl+O to expand)")}`
+  return new Text(text, 0, 0)
+}
+
+// ---------------------------------------------------------------------------
+// Parallel result renderer
+// ---------------------------------------------------------------------------
+
+function renderParallelResult(
+  results: SingleResult[],
+  context: RenderContext,
+  theme: Theme,
+  mdTheme: any,
+  renderDisplayItems: (items: DisplayItem[], limit?: number) => string,
+): any {
+  const running = results.filter(r => r.exitCode === -1).length
+  const successCount = results.filter(r => r.exitCode !== -1 && !isFailedResult(r)).length
+  const failCount = results.filter(r => r.exitCode !== -1 && isFailedResult(r)).length
+  const isRunning = running > 0
+  const icon = isRunning
+    ? theme.fg("warning", "⏳")
+    : failCount > 0
+      ? theme.fg("warning", "◐")
+      : theme.fg("success", "✓")
+  const status = isRunning
+    ? `${successCount + failCount}/${results.length} done, ${running} running`
+    : `${successCount}/${results.length} tasks`
+
+  if (context.expanded && !isRunning) {
+    const container = new Container()
+    container.addChild(new Text(`${icon} ${theme.fg("toolTitle", theme.bold("parallel "))}${theme.fg("accent", status)}`, 0, 0))
+
+    for (const r of results) {
+      const rIcon = isFailedResult(r) ? theme.fg("error", "✗") : theme.fg("success", "✓")
+      const displayItems = getDisplayItems(r.messages)
+      const finalOutput = getFinalOutput(r.messages)
+
+      container.addChild(new Spacer(1))
+      container.addChild(new Text(`${theme.fg("muted", "─── ")}${theme.fg("accent", r.agent)} ${rIcon}`, 0, 0))
+      container.addChild(new Text(theme.fg("muted", "Task: ") + theme.fg("dim", r.task), 0, 0))
+      for (const item of displayItems) {
+        if (item.type === "toolCall")
+          container.addChild(new Text(theme.fg("muted", "→ ") + formatToolCall(item.name, item.args, theme.fg.bind(theme)), 0, 0))
+      }
+      if (finalOutput) {
+        container.addChild(new Spacer(1))
+        container.addChild(new Markdown(finalOutput.trim(), 0, 0, mdTheme))
+      }
+      const taskUsage = formatUsageStats(r.usage, r.model)
+      if (taskUsage) container.addChild(new Text(theme.fg("dim", taskUsage), 0, 0))
+    }
+
+    const usageStr = formatUsageStats(aggregateUsage(results))
+    if (usageStr) {
+      container.addChild(new Spacer(1))
+      container.addChild(new Text(theme.fg("dim", `Total: ${usageStr}`), 0, 0))
+    }
+    return container
+  }
+
+  // Collapsed (or still running)
+  let text = `${icon} ${theme.fg("toolTitle", theme.bold("parallel "))}${theme.fg("accent", status)}`
+  for (const r of results) {
+    const rIcon =
+      r.exitCode === -1
+        ? theme.fg("warning", "⏳")
+        : isFailedResult(r)
+          ? theme.fg("error", "✗")
+          : theme.fg("success", "✓")
+    const displayItems = getDisplayItems(r.messages)
+    text += `\n\n${theme.fg("muted", "─── ")}${theme.fg("accent", r.agent)} ${rIcon}`
+    if (displayItems.length === 0)
+      text += `\n${theme.fg("muted", r.exitCode === -1 ? "(running...)" : "(no output)")}`
+    else text += `\n${renderDisplayItems(displayItems, 5)}`
+  }
+  if (!isRunning) {
+    const usageStr = formatUsageStats(aggregateUsage(results))
+    if (usageStr) text += `\n\n${theme.fg("dim", `Total: ${usageStr}`)}`
+  }
+  if (!context.expanded) text += `\n${theme.fg("muted", "(Ctrl+O to expand)")}`
+  return new Text(text, 0, 0)
+}
+
+// ---------------------------------------------------------------------------
+// Markdown theme helper
+// ---------------------------------------------------------------------------
+
+function getMarkdownTheme(): any {
+  // Return a simple theme for testing / default usage
+  // In production, pi provides getMarkdownTheme()
+  try {
+    const { getMarkdownTheme: gmt } = require("@mariozechner/pi-coding-agent")
+    return gmt()
+  } catch {
+    return undefined
+  }
+}

package/extensions/ce-core/tools/subagent.ts

@@ -4,12 +4,22 @@
  * Features:
  *   - Recursion depth guard (PI_SUBAGENT_DEPTH / PI_SUBAGENT_MAX_DEPTH)
  *   - Optional context slimming via --no-skills flag
+ *   - Live TUI updates via onUpdate callback + SingleResult details
  */
 
 import {
   checkSubagentDepth,
   getChildDepthEnv,
 } from "./subagent-depth-guard"
+import {
+  type SingleResult,
+  getFinalOutput,
+  invokeRunner,
+} from "./subagent-events"
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
 
 export interface SubagentTask {
   agent: string
@@ -24,22 +34,47 @@ export interface SubagentInput {
   inheritSkills?: boolean
 }
 
-export interface SubagentResult {
+export interface SubagentLiveDetails {
   mode: "single" | "chain"
-  outputs: string[]
+  results: SingleResult[]
 }
 
+/** @deprecated Use SubagentLiveRunner instead */
+export type SubagentRunner = (
+  prompt: string,
+  options?: SubagentExecOptions,
+) => Promise<string>
+
 export interface SubagentExecOptions {
   /** Extra CLI flags to pass to the child pi process */
   extraFlags?: string[]
   /** Environment variables to inject into the child process */
   extraEnv?: Record<string, string>
+  /** Callback for live TUI partial updates */
+  onUpdate?: (partial: SingleResult) => void
 }
 
-export type SubagentRunner = (
+/**
+ * Live runner that returns a structured SingleResult and supports
+ * onUpdate for partial progress.
+ */
+export type SubagentLiveRunner = (
   prompt: string,
-  options?: SubagentExecOptions,
-) => Promise<string>
+  options?: SubagentLiveExecOptions,
+) => Promise<SingleResult>
+
+export type SubagentLiveExecOptions = SubagentExecOptions
+
+export interface SubagentLiveResult {
+  mode: "single" | "chain"
+  results: SingleResult[]
+  /** @deprecated Backward compat: final text output per step */
+  outputs?: string[]
+}
+
+// ---------------------------------------------------------------------------
+// Pipeline stage guard
+// ---------------------------------------------------------------------------
 
 const PIPELINE_STAGE_SKILLS = new Set([
   "01-brainstorm",
@@ -58,10 +93,26 @@ export function assertNonPipelineStageSkill(agent: string, toolName: string): vo
   }
 }
 
+// ---------------------------------------------------------------------------
+// Tool factory
+// ---------------------------------------------------------------------------
+
 export function createSubagentTool() {
   return {
-    name: "ce_subagent",
-    async execute(input: SubagentInput, runner: SubagentRunner): Promise<SubagentResult> {
+    name: "ce_subagent" as const,
+
+    /**
+     * Execute the subagent tool.
+     *
+     * Supports two runner signatures:
+     *   - SubagentLiveRunner (preferred): returns SingleResult, supports onUpdate
+     *   - SubagentRunner (legacy): returns string, no onUpdate
+     */
+    async execute(
+      input: SubagentInput,
+      runner: SubagentLiveRunner | SubagentRunner,
+      toolCtx?: { onUpdate?: (details: SubagentLiveDetails) => void },
+    ): Promise<SubagentLiveResult> {
       // Recursion depth guard
       const depthCheck = checkSubagentDepth()
       if (!depthCheck.allowed) {
@@ -80,46 +131,71 @@ export function createSubagentTool() {
       if (hasSingle) {
         assertNonPipelineStageSkill(input.agent!, "ce_subagent")
         const prompt = buildPrompt(input.agent!, input.task!)
-        const output = await runner(prompt, execOptions)
+
+        const liveOptions: SubagentLiveExecOptions = {
+          ...execOptions,
+          onUpdate: (partial: SingleResult) => {
+            if (toolCtx?.onUpdate) {
+              toolCtx.onUpdate({ mode: "single", results: [partial] })
+            }
+          },
+        }
+
+        const result = await invokeRunner(runner, prompt, liveOptions)
+        result.agent = input.agent!
+        result.task = input.task!
         return {
           mode: "single",
-          outputs: [output],
+          results: [result],
+          outputs: [getFinalOutput(result.messages)],
         }
       }
 
-      const outputs: string[] = []
+      // Chain mode
+      const results: SingleResult[] = []
       let previous = ""
 
       for (const task of input.chain ?? []) {
         assertNonPipelineStageSkill(task.agent, "ce_subagent")
         const prompt = buildPrompt(task.agent, task.task.replace(/\{previous\}/g, previous))
-        const output = await runner(prompt, execOptions)
-        outputs.push(output)
-        previous = output
+
+        const liveOptions: SubagentLiveExecOptions = {
+          ...execOptions,
+          onUpdate: (partial: SingleResult) => {
+            if (toolCtx?.onUpdate) {
+              toolCtx.onUpdate({ mode: "chain", results: [...results, partial] })
+            }
+          },
+        }
+
+        const result = await invokeRunner(runner, prompt, liveOptions)
+        result.agent = task.agent
+        result.task = task.task
+        results.push(result)
+        previous = getFinalOutput(result.messages)
       }
 
       return {
         mode: "chain",
-        outputs,
+        results,
+        outputs: results.map(r => getFinalOutput(r.messages)),
       }
     },
   }
 }
 
-/**
- * Build exec options based on subagent configuration.
- * Controls context inheritance and recursion depth.
- */
-function buildExecOptions(inheritSkills?: boolean): SubagentExecOptions {
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function buildExecOptions(inheritSkills?: boolean): { extraFlags?: string[]; extraEnv: Record<string, string> } {
   const flags: string[] = []
   const env: Record<string, string> = {}
 
-  // Context slimming: skip skills inheritance when explicitly disabled
   if (inheritSkills === false) {
     flags.push("--no-skills")
   }
 
-  // Recursion depth: pass incremented depth to child process
   Object.assign(env, getChildDepthEnv())
 
   return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leing2021/super-pi",
-  "version": "0.23.8",
+  "version": "0.23.10",
   "private": false,
   "type": "module",
   "description": "Pi-native Compound Engineering package for iterative development workflows",

package/skills/03-work/SKILL.md

@@ -58,6 +58,17 @@ Anti-rationalization — when a gate fails or evidence is missing:
 
 This is a hard gate — do not push past a failing test or broken build to continue implementation. Errors compound.
 
+## Error compaction after recovery
+
+After a stop-the-line failure is diagnosed, fixed, and verified:
+
+1. Replace full traces in handoff/context with `ERROR(resolved): <root cause>`
+2. Keep only the final repro, root cause, fix summary, and verification result
+3. Remove intermediate debug output and failed exploratory runs that are no longer relevant
+4. Update `session_checkpoint` with the compacted state only
+
+If the same tool, command, or implementation unit fails 3 consecutive times, stop retrying and ask the user for direction with a concise evidence summary.
+
 ## Workflow
 
 1. **Load context**: consume latest handoff before any broad file reads — `context_handoff load` or read `.context/compound-engineering/handoffs/latest.md`. If found, use `activeFiles`, `blocker`, `verification`, `activeRules` as starting point. If not found, proceed normally.

package/skills/references/pipeline-config.md

@@ -29,6 +29,15 @@ Before reading any project files or running repository-wide scans, load the most
 
 Core principle: **consume handoff before broad project file reads** — a single handoff read (~500 tokens) avoids 5-10 project file scans (~5K-10K tokens).
 
+## Context hygiene rules
+
+Applies to all Phase 1 skills when preparing context or saving handoff.
+
+1. **Compact resolved errors** — Once an error is diagnosed, fixed, and verified, do not carry the full trace forward. Replace it with `ERROR(resolved): <root cause>` and keep repro/verification only if still relevant.
+2. **Fetch obvious prerequisites** — If the next step has an obvious deterministic prerequisite, fetch it before reasoning further instead of spending an LLM round trip asking for it.
+3. **Cap repeated failures** — After 3 consecutive failures on the same tool, command, or implementation unit, stop retrying. Summarize evidence and ask the user for direction.
+4. **Prune before handoff** — Before saving handoff, keep only what the next stage needs. Move broad history to artifact paths; remove intermediate debug output that is no longer relevant.
+
 ## End of skill: save handoff + status + context
 
 Every Phase 1 skill (02-plan through 05-learn) must save context handoff at completion: