@aexol/spectral 0.4.3 → 0.4.8

package/dist/agent/index.js

@@ -0,0 +1,951 @@
+/**
+ * Subagent Delegation Extension for Spectral
+ *
+ * Registers a `subagent` tool that allows the coding agent to delegate tasks
+ * to specialized sub-agents running in isolated `pi` / `spectral` processes.
+ *
+ * Each subagent invocation spawns a separate process with its own context
+ * window, keeping the main conversation lean and focused.
+ *
+ * Three execution modes:
+ *   - Single:   { agent: "name", task: "..." }
+ *   - Parallel: { tasks: [{ agent, task }, ...] }  (max 8, 4 concurrent)
+ *   - Chain:    { chain: [{ agent, task: "... {previous} ..." }, ...] }
+ *
+ * Agent definitions live as markdown files with YAML frontmatter:
+ *   - ~/.pi/agent/agents/*.md    (user-level, always loaded)
+ *   - .pi/agents/*.md            (project-level, opt-in via agentScope)
+ *
+ * The subagent binary is auto-detected:
+ *   - If running via `spectral`, uses the same invocation path
+ *   - Falls back to `pi` otherwise
+ */
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { StringEnum } from "@mariozechner/pi-ai";
+import { getMarkdownTheme, withFileMutationQueue, } from "@mariozechner/pi-coding-agent";
+import { Container, Markdown, Spacer, Text } from "@mariozechner/pi-tui";
+import { Type } from "typebox";
+import { discoverAgents } from "./agents.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const MAX_PARALLEL_TASKS = 8;
+const MAX_CONCURRENCY = 4;
+const COLLAPSED_ITEM_COUNT = 10;
+// ---------------------------------------------------------------------------
+// Helpers — formatting
+// ---------------------------------------------------------------------------
+function formatTokens(count) {
+    if (count < 1000)
+        return count.toString();
+    if (count < 10000)
+        return `${(count / 1000).toFixed(1)}k`;
+    if (count < 1000000)
+        return `${Math.round(count / 1000)}k`;
+    return `${(count / 1000000).toFixed(1)}M`;
+}
+function formatUsageStats(usage, model) {
+    const parts = [];
+    if (usage.turns)
+        parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
+    if (usage.input)
+        parts.push(`↑${formatTokens(usage.input)}`);
+    if (usage.output)
+        parts.push(`↓${formatTokens(usage.output)}`);
+    if (usage.cacheRead)
+        parts.push(`R${formatTokens(usage.cacheRead)}`);
+    if (usage.cacheWrite)
+        parts.push(`W${formatTokens(usage.cacheWrite)}`);
+    if (usage.cost)
+        parts.push(`$${usage.cost.toFixed(4)}`);
+    if (usage.contextTokens && usage.contextTokens > 0) {
+        parts.push(`ctx:${formatTokens(usage.contextTokens)}`);
+    }
+    if (model)
+        parts.push(model);
+    return parts.join(" ");
+}
+function formatToolCall(toolName, args, themeFg) {
+    const shortenPath = (p) => {
+        const home = os.homedir();
+        return p.startsWith(home) ? `~${p.slice(home.length)}` : p;
+    };
+    switch (toolName) {
+        case "bash": {
+            const command = args.command || "...";
+            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 || "...");
+            const filePath = shortenPath(rawPath);
+            const offset = args.offset;
+            const limit = args.limit;
+            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 || "...");
+            const filePath = shortenPath(rawPath);
+            const content = (args.content || "");
+            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 || "...");
+            return themeFg("muted", "edit ") + themeFg("accent", shortenPath(rawPath));
+        }
+        case "ls": {
+            const rawPath = (args.path || ".");
+            return themeFg("muted", "ls ") + themeFg("accent", shortenPath(rawPath));
+        }
+        case "find": {
+            const pattern = (args.pattern || "*");
+            const rawPath = (args.path || ".");
+            return (themeFg("muted", "find ") +
+                themeFg("accent", pattern) +
+                themeFg("dim", ` in ${shortenPath(rawPath)}`));
+        }
+        case "grep": {
+            const pattern = (args.pattern || "");
+            const rawPath = (args.path || ".");
+            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}`);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers — message extraction
+// ---------------------------------------------------------------------------
+function getFinalOutput(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i];
+        if (msg.role === "assistant") {
+            for (const part of msg.content) {
+                if (part.type === "text")
+                    return part.text;
+            }
+        }
+    }
+    return "";
+}
+function getDisplayItems(messages) {
+    const items = [];
+    for (const msg of messages) {
+        if (msg.role === "assistant") {
+            for (const part of msg.content) {
+                if (part.type === "text")
+                    items.push({ type: "text", text: part.text });
+                else if (part.type === "toolCall")
+                    items.push({ type: "toolCall", name: part.name, args: part.arguments });
+            }
+        }
+    }
+    return items;
+}
+// ---------------------------------------------------------------------------
+// Helpers — concurrency, temp files, binary detection
+// ---------------------------------------------------------------------------
+async function mapWithConcurrencyLimit(items, concurrency, fn) {
+    if (items.length === 0)
+        return [];
+    const limit = Math.max(1, Math.min(concurrency, items.length));
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    const workers = new Array(limit).fill(null).map(async () => {
+        while (true) {
+            const current = nextIndex++;
+            if (current >= items.length)
+                return;
+            results[current] = await fn(items[current], current);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}
+async function writePromptToTempFile(agentName, prompt) {
+    const tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "spectral-subagent-"));
+    const safeName = agentName.replace(/[^\w.-]+/g, "_");
+    const filePath = path.join(tmpDir, `prompt-${safeName}.md`);
+    await withFileMutationQueue(filePath, async () => {
+        await fs.promises.writeFile(filePath, prompt, { encoding: "utf-8", mode: 0o600 });
+    });
+    return { dir: tmpDir, filePath };
+}
+/**
+ * Detect the correct binary for spawning subagent processes.
+ *
+ * Strategy:
+ *   1. If `process.argv[1]` points to an existing script (unlikely in bundled
+ *      env but possible during dev with tsx), use that script with node.
+ *   2. If the executor is named `spectral` or `aexol`, use it directly (the
+ *      wrapper ensures MCP + memory extensions are auto-loaded).
+ *   3. Otherwise fall back to `pi`.
+ */
+function getPiInvocation(subagentArgs) {
+    const currentScript = process.argv[1];
+    // Case 1: running via tsx with an existing script file
+    if (currentScript && fs.existsSync(currentScript)) {
+        return { command: process.execPath, args: [currentScript, ...subagentArgs] };
+    }
+    // Case 2: check if this is the spectral/aexol wrapper binary
+    const execName = path.basename(process.execPath).toLowerCase();
+    if (execName === "spectral" || execName === "aexol") {
+        return { command: process.execPath, args: subagentArgs };
+    }
+    // Case 3: generic node — try spectral first, then pi
+    function hasBin(name) {
+        const PATH = process.env.PATH || "";
+        const envPathSep = process.platform === "win32" ? ";" : ":";
+        for (const dir of PATH.split(envPathSep)) {
+            const candidate = path.join(dir, name);
+            try {
+                if (fs.existsSync(candidate))
+                    return true;
+            }
+            catch {
+                /* skip */
+            }
+        }
+        return false;
+    }
+    if (hasBin("spectral")) {
+        return { command: "spectral", args: subagentArgs };
+    }
+    if (hasBin("pi")) {
+        return { command: "pi", args: subagentArgs };
+    }
+    // Last resort: use node with pi from node_modules (matches pi's own fallback)
+    return { command: "pi", args: subagentArgs };
+}
+// ---------------------------------------------------------------------------
+// Core — run a single subagent
+// ---------------------------------------------------------------------------
+async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails) {
+    const agent = agents.find((a) => a.name === agentName);
+    if (!agent) {
+        const available = agents.map((a) => `"${a.name}"`).join(", ") || "none";
+        return {
+            agent: agentName,
+            agentSource: "unknown",
+            task,
+            exitCode: 1,
+            messages: [],
+            stderr: `Unknown agent: "${agentName}". Available agents: ${available}.`,
+            usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+            step,
+        };
+    }
+    const args = ["--mode", "json", "-p", "--no-session"];
+    if (agent.model)
+        args.push("--model", agent.model);
+    if (agent.tools && agent.tools.length > 0)
+        args.push("--tools", agent.tools.join(","));
+    let tmpPromptDir = null;
+    let tmpPromptPath = null;
+    const currentResult = {
+        agent: agentName,
+        agentSource: agent.source,
+        task,
+        exitCode: 0,
+        messages: [],
+        stderr: "",
+        usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+        model: agent.model,
+        step,
+    };
+    const emitUpdate = () => {
+        if (onUpdate) {
+            onUpdate({
+                content: [{ type: "text", text: getFinalOutput(currentResult.messages) || "(running...)" }],
+                details: makeDetails([currentResult]),
+            });
+        }
+    };
+    try {
+        if (agent.systemPrompt.trim()) {
+            const tmp = await writePromptToTempFile(agent.name, agent.systemPrompt);
+            tmpPromptDir = tmp.dir;
+            tmpPromptPath = tmp.filePath;
+            args.push("--append-system-prompt", tmpPromptPath);
+        }
+        args.push(`Task: ${task}`);
+        let wasAborted = false;
+        const exitCode = await new Promise((resolve) => {
+            const invocation = getPiInvocation(args);
+            const proc = spawn(invocation.command, invocation.args, {
+                cwd: cwd ?? defaultCwd,
+                shell: false,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            let buffer = "";
+            const processLine = (line) => {
+                if (!line.trim())
+                    return;
+                let event;
+                try {
+                    event = JSON.parse(line);
+                }
+                catch {
+                    return;
+                }
+                if (event.type === "message_end" && event.message) {
+                    const msg = event.message;
+                    currentResult.messages.push(msg);
+                    if (msg.role === "assistant") {
+                        currentResult.usage.turns++;
+                        const usage = msg.usage;
+                        if (usage) {
+                            currentResult.usage.input += usage.input || 0;
+                            currentResult.usage.output += usage.output || 0;
+                            currentResult.usage.cacheRead += usage.cacheRead || 0;
+                            currentResult.usage.cacheWrite += usage.cacheWrite || 0;
+                            currentResult.usage.cost += usage.cost?.total || 0;
+                            currentResult.usage.contextTokens = usage.totalTokens || 0;
+                        }
+                        if (!currentResult.model && msg.model)
+                            currentResult.model = msg.model;
+                        if (msg.stopReason)
+                            currentResult.stopReason = msg.stopReason;
+                        if (msg.errorMessage)
+                            currentResult.errorMessage = msg.errorMessage;
+                    }
+                    emitUpdate();
+                }
+                if (event.type === "tool_result_end" && event.message) {
+                    currentResult.messages.push(event.message);
+                    emitUpdate();
+                }
+            };
+            proc.stdout.on("data", (data) => {
+                buffer += data.toString();
+                const lines = buffer.split("\n");
+                buffer = lines.pop() || "";
+                for (const line of lines)
+                    processLine(line);
+            });
+            proc.stderr.on("data", (data) => {
+                currentResult.stderr += data.toString();
+            });
+            proc.on("close", (code) => {
+                if (buffer.trim())
+                    processLine(buffer);
+                resolve(code ?? 0);
+            });
+            proc.on("error", () => {
+                resolve(1);
+            });
+            if (signal) {
+                const killProc = () => {
+                    wasAborted = true;
+                    proc.kill("SIGTERM");
+                    setTimeout(() => {
+                        if (!proc.killed)
+                            proc.kill("SIGKILL");
+                    }, 5000);
+                };
+                if (signal.aborted)
+                    killProc();
+                else
+                    signal.addEventListener("abort", killProc, { once: true });
+            }
+        });
+        currentResult.exitCode = exitCode;
+        if (wasAborted)
+            throw new Error("Subagent was aborted");
+        return currentResult;
+    }
+    finally {
+        if (tmpPromptPath)
+            try {
+                fs.unlinkSync(tmpPromptPath);
+            }
+            catch {
+                /* ignore */
+            }
+        if (tmpPromptDir)
+            try {
+                fs.rmdirSync(tmpPromptDir);
+            }
+            catch {
+                /* ignore */
+            }
+    }
+}
+// ---------------------------------------------------------------------------
+// Tool parameter schemas
+// ---------------------------------------------------------------------------
+const TaskItem = Type.Object({
+    agent: Type.String({ description: "Name of the agent to invoke" }),
+    task: Type.String({ description: "Task to delegate to the agent" }),
+    cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
+});
+const ChainItem = Type.Object({
+    agent: Type.String({ description: "Name of the agent to invoke" }),
+    task: Type.String({
+        description: "Task with optional {previous} placeholder for prior output",
+    }),
+    cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
+});
+const AgentScopeSchema = StringEnum(["user", "project", "both"], {
+    description: 'Which agent directories to use. Default: "user". Use "both" to include project-local agents.',
+    default: "user",
+});
+const SubagentParams = Type.Object({
+    agent: Type.Optional(Type.String({ description: "Name of the agent to invoke (for single mode)" })),
+    task: Type.Optional(Type.String({ description: "Task to delegate (for single mode)" })),
+    tasks: Type.Optional(Type.Array(TaskItem, {
+        description: "Array of {agent, task} for parallel execution",
+    })),
+    chain: Type.Optional(Type.Array(ChainItem, {
+        description: "Array of {agent, task} for sequential execution",
+    })),
+    agentScope: Type.Optional(AgentScopeSchema),
+    confirmProjectAgents: Type.Optional(Type.Boolean({
+        description: "Prompt before running project-local agents. Default: true.",
+        default: true,
+    })),
+    cwd: Type.Optional(Type.String({
+        description: "Working directory for the agent process (single mode)",
+    })),
+});
+// ---------------------------------------------------------------------------
+// Extension entry point
+// ---------------------------------------------------------------------------
+export default function subagentExtension(pi) {
+    pi.registerTool({
+        name: "subagent",
+        label: "Subagent",
+        description: [
+            "Delegate tasks to specialized subagents with isolated context.",
+            "Modes: single (agent + task), parallel (tasks array), chain (sequential with {previous} placeholder).",
+            'Default agent scope is "user" (from ~/.pi/agent/agents).',
+            'To enable project-local agents in .pi/agents, set agentScope: "both" (or "project").',
+        ].join(" "),
+        promptSnippet: "Run a subagent to investigate, plan, review, or implement code changes",
+        promptGuidelines: [
+            "Use the subagent tool to delegate complex investigations to specialized subagents instead of reading many files in the main conversation. Each subagent runs in an isolated context window.",
+        ],
+        parameters: SubagentParams,
+        async execute(_toolCallId, params, signal, onUpdate, ctx) {
+            const agentScope = params.agentScope ?? "user";
+            const discovery = discoverAgents(ctx.cwd, agentScope);
+            const agents = discovery.agents;
+            const confirmProjectAgents = params.confirmProjectAgents ?? true;
+            const hasChain = (params.chain?.length ?? 0) > 0;
+            const hasTasks = (params.tasks?.length ?? 0) > 0;
+            const hasSingle = Boolean(params.agent && params.task);
+            const modeCount = Number(hasChain) + Number(hasTasks) + Number(hasSingle);
+            const makeDetails = (mode) => (results) => ({
+                mode,
+                agentScope,
+                projectAgentsDir: discovery.projectAgentsDir,
+                results,
+            });
+            if (modeCount !== 1) {
+                const available = agents.map((a) => `${a.name} (${a.source})`).join(", ") || "none";
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Invalid parameters. Provide exactly one mode.\nAvailable agents: ${available}`,
+                        },
+                    ],
+                    details: makeDetails("single")([]),
+                };
+            }
+            // Security: if project-local agents are enabled, confirm with user
+            if ((agentScope === "project" || agentScope === "both") &&
+                confirmProjectAgents &&
+                ctx.hasUI) {
+                const requestedAgentNames = new Set();
+                if (params.chain)
+                    for (const step of params.chain)
+                        requestedAgentNames.add(step.agent);
+                if (params.tasks)
+                    for (const t of params.tasks)
+                        requestedAgentNames.add(t.agent);
+                if (params.agent)
+                    requestedAgentNames.add(params.agent);
+                const projectAgentsRequested = Array.from(requestedAgentNames)
+                    .map((name) => agents.find((a) => a.name === name))
+                    .filter((a) => a?.source === "project");
+                if (projectAgentsRequested.length > 0) {
+                    const names = projectAgentsRequested.map((a) => a.name).join(", ");
+                    const dir = discovery.projectAgentsDir ?? "(unknown)";
+                    const ok = await ctx.ui.confirm("Run project-local agents?", `Agents: ${names}\nSource: ${dir}\n\nProject agents are repo-controlled. Only continue for trusted repositories.`);
+                    if (!ok)
+                        return {
+                            content: [
+                                { type: "text", text: "Canceled: project-local agents not approved." },
+                            ],
+                            details: makeDetails(hasChain ? "chain" : hasTasks ? "parallel" : "single")([]),
+                        };
+                }
+            }
+            // ── Chain mode ──────────────────────────────────────────────
+            if (params.chain && params.chain.length > 0) {
+                const results = [];
+                let previousOutput = "";
+                for (let i = 0; i < params.chain.length; i++) {
+                    const step = params.chain[i];
+                    const taskWithContext = step.task.replace(/\{previous\}/g, previousOutput);
+                    const chainUpdate = onUpdate
+                        ? (partial) => {
+                            const currentResult = partial.details?.results[0];
+                            if (currentResult) {
+                                const allResults = [...results, currentResult];
+                                onUpdate({
+                                    content: partial.content,
+                                    details: makeDetails("chain")(allResults),
+                                });
+                            }
+                        }
+                        : undefined;
+                    const result = await runSingleAgent(ctx.cwd, agents, step.agent, taskWithContext, step.cwd, i + 1, signal, chainUpdate, makeDetails("chain"));
+                    results.push(result);
+                    const isError = result.exitCode !== 0 ||
+                        result.stopReason === "error" ||
+                        result.stopReason === "aborted";
+                    if (isError) {
+                        const errorMsg = result.errorMessage ||
+                            result.stderr ||
+                            getFinalOutput(result.messages) ||
+                            "(no output)";
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `Chain stopped at step ${i + 1} (${step.agent}): ${errorMsg}`,
+                                },
+                            ],
+                            details: makeDetails("chain")(results),
+                            isError: true,
+                        };
+                    }
+                    previousOutput = getFinalOutput(result.messages);
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: getFinalOutput(results[results.length - 1].messages) || "(no output)",
+                        },
+                    ],
+                    details: makeDetails("chain")(results),
+                };
+            }
+            // ── Parallel mode ───────────────────────────────────────────
+            if (params.tasks && params.tasks.length > 0) {
+                if (params.tasks.length > MAX_PARALLEL_TASKS)
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Too many parallel tasks (${params.tasks.length}). Max is ${MAX_PARALLEL_TASKS}.`,
+                            },
+                        ],
+                        details: makeDetails("parallel")([]),
+                    };
+                const allResults = new Array(params.tasks.length);
+                for (let i = 0; i < params.tasks.length; i++) {
+                    allResults[i] = {
+                        agent: params.tasks[i].agent,
+                        agentSource: "unknown",
+                        task: params.tasks[i].task,
+                        exitCode: -1,
+                        messages: [],
+                        stderr: "",
+                        usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+                    };
+                }
+                const emitParallelUpdate = () => {
+                    if (onUpdate) {
+                        const running = allResults.filter((r) => r.exitCode === -1).length;
+                        const done = allResults.filter((r) => r.exitCode !== -1).length;
+                        onUpdate({
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `Parallel: ${done}/${allResults.length} done, ${running} running...`,
+                                },
+                            ],
+                            details: makeDetails("parallel")([...allResults]),
+                        });
+                    }
+                };
+                const results = await mapWithConcurrencyLimit(params.tasks, MAX_CONCURRENCY, async (t, index) => {
+                    const result = await runSingleAgent(ctx.cwd, agents, t.agent, t.task, t.cwd, undefined, signal, (partial) => {
+                        if (partial.details?.results[0]) {
+                            allResults[index] = partial.details.results[0];
+                            emitParallelUpdate();
+                        }
+                    }, makeDetails("parallel"));
+                    allResults[index] = result;
+                    emitParallelUpdate();
+                    return result;
+                });
+                const successCount = results.filter((r) => r.exitCode === 0).length;
+                const summaries = results.map((r) => {
+                    const output = getFinalOutput(r.messages);
+                    const preview = output.slice(0, 100) + (output.length > 100 ? "..." : "");
+                    return `[${r.agent}] ${r.exitCode === 0 ? "completed" : "failed"}: ${preview || "(no output)"}`;
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Parallel: ${successCount}/${results.length} succeeded\n\n${summaries.join("\n\n")}`,
+                        },
+                    ],
+                    details: makeDetails("parallel")(results),
+                };
+            }
+            // ── Single mode ─────────────────────────────────────────────
+            if (params.agent && params.task) {
+                const result = await runSingleAgent(ctx.cwd, agents, params.agent, params.task, params.cwd, undefined, signal, onUpdate, makeDetails("single"));
+                const isError = result.exitCode !== 0 ||
+                    result.stopReason === "error" ||
+                    result.stopReason === "aborted";
+                if (isError) {
+                    const errorMsg = result.errorMessage ||
+                        result.stderr ||
+                        getFinalOutput(result.messages) ||
+                        "(no output)";
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Agent ${result.stopReason || "failed"}: ${errorMsg}`,
+                            },
+                        ],
+                        details: makeDetails("single")([result]),
+                        isError: true,
+                    };
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: getFinalOutput(result.messages) || "(no output)",
+                        },
+                    ],
+                    details: makeDetails("single")([result]),
+                };
+            }
+            const available = agents.map((a) => `${a.name} (${a.source})`).join(", ") || "none";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Invalid parameters. Available agents: ${available}`,
+                    },
+                ],
+                details: makeDetails("single")([]),
+            };
+        },
+        // ── Rendering ─────────────────────────────────────────────────
+        renderCall(args, theme, _context) {
+            const scope = args.agentScope ?? "user";
+            if (args.chain && args.chain.length > 0) {
+                let text = theme.fg("toolTitle", theme.bold("subagent ")) +
+                    theme.fg("accent", `chain (${args.chain.length} steps)`) +
+                    theme.fg("muted", ` [${scope}]`);
+                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("subagent ")) +
+                    theme.fg("accent", `parallel (${args.tasks.length} tasks)`) +
+                    theme.fg("muted", ` [${scope}]`);
+                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);
+            }
+            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("subagent ")) +
+                theme.fg("accent", agentName) +
+                theme.fg("muted", ` [${scope}]`);
+            text += `\n  ${theme.fg("dim", preview)}`;
+            return new Text(text, 0, 0);
+        },
+        renderResult(result, { expanded }, theme, _context) {
+            const details = result.details;
+            if (!details || details.results.length === 0) {
+                const text = result.content[0];
+                return new Text(text?.type === "text" ? text.text : "(no output)", 0, 0);
+            }
+            const mdTheme = getMarkdownTheme();
+            const renderDisplayItems = (items, limit) => {
+                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 = 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();
+            };
+            if (details.mode === "single" && details.results.length === 1) {
+                const r = details.results[0];
+                const isError = r.exitCode !== 0 ||
+                    r.stopReason === "error" ||
+                    r.stopReason === "aborted";
+                const icon = isError
+                    ? theme.fg("error", "✗")
+                    : theme.fg("success", "✓");
+                const displayItems = getDisplayItems(r.messages);
+                const finalOutput = getFinalOutput(r.messages);
+                if (expanded) {
+                    const container = new Container();
+                    let header = `${icon} ${theme.fg("toolTitle", theme.bold(r.agent))}${theme.fg("muted", ` (${r.agentSource})`)}`;
+                    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", "(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;
+                }
+                let text = `${icon} ${theme.fg("toolTitle", theme.bold(r.agent))}${theme.fg("muted", ` (${r.agentSource})`)}`;
+                if (isError && r.stopReason)
+                    text += ` ${theme.fg("error", `[${r.stopReason}]`)}`;
+                if (isError && r.errorMessage)
+                    text += `\n${theme.fg("error", `Error: ${r.errorMessage}`)}`;
+                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);
+            }
+            const aggregateUsage = (results) => {
+                const total = {
+                    input: 0,
+                    output: 0,
+                    cacheRead: 0,
+                    cacheWrite: 0,
+                    cost: 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.turns += r.usage.turns;
+                }
+                return total;
+            };
+            if (details.mode === "chain") {
+                const successCount = details.results.filter((r) => r.exitCode === 0).length;
+                const icon = successCount === details.results.length
+                    ? theme.fg("success", "✓")
+                    : theme.fg("error", "✗");
+                if (expanded) {
+                    const container = new Container();
+                    container.addChild(new Text(icon +
+                        " " +
+                        theme.fg("toolTitle", theme.bold("chain ")) +
+                        theme.fg("accent", `${successCount}/${details.results.length} steps`), 0, 0));
+                    for (const r of details.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(details.results));
+                    if (usageStr) {
+                        container.addChild(new Spacer(1));
+                        container.addChild(new Text(theme.fg("dim", `Total: ${usageStr}`), 0, 0));
+                    }
+                    return container;
+                }
+                let text = icon +
+                    " " +
+                    theme.fg("toolTitle", theme.bold("chain ")) +
+                    theme.fg("accent", `${successCount}/${details.results.length} steps`);
+                for (const r of details.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(details.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);
+            }
+            if (details.mode === "parallel") {
+                const running = details.results.filter((r) => r.exitCode === -1).length;
+                const successCount = details.results.filter((r) => r.exitCode === 0).length;
+                const failCount = details.results.filter((r) => r.exitCode > 0).length;
+                const isRunning = running > 0;
+                const icon = isRunning
+                    ? theme.fg("warning", "⏳")
+                    : failCount > 0
+                        ? theme.fg("warning", "◐")
+                        : theme.fg("success", "✓");
+                const status = isRunning
+                    ? `${successCount + failCount}/${details.results.length} done, ${running} running`
+                    : `${successCount}/${details.results.length} tasks`;
+                if (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 details.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", "─── ") + 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(details.results));
+                    if (usageStr) {
+                        container.addChild(new Spacer(1));
+                        container.addChild(new Text(theme.fg("dim", `Total: ${usageStr}`), 0, 0));
+                    }
+                    return container;
+                }
+                let text = `${icon} ${theme.fg("toolTitle", theme.bold("parallel "))}${theme.fg("accent", status)}`;
+                for (const r of details.results) {
+                    const rIcon = r.exitCode === -1
+                        ? theme.fg("warning", "⏳")
+                        : r.exitCode === 0
+                            ? theme.fg("success", "✓")
+                            : theme.fg("error", "✗");
+                    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(details.results));
+                    if (usageStr)
+                        text += `\n\n${theme.fg("dim", `Total: ${usageStr}`)}`;
+                }
+                if (!expanded)
+                    text += `\n${theme.fg("muted", "(Ctrl+O to expand)")}`;
+                return new Text(text, 0, 0);
+            }
+            const text = result.content[0];
+            return new Text(text?.type === "text" ? text.text : "(no output)", 0, 0);
+        },
+    });
+}