@tintinweb/pi-subagents 0.4.0 → 0.4.3

package/dist/index.js

@@ -0,0 +1,1270 @@
+/**
+ * pi-agents — A pi extension providing Claude Code-style autonomous sub-agents.
+ *
+ * Tools:
+ *   Agent             — LLM-callable: spawn a sub-agent
+ *   get_subagent_result  — LLM-callable: check background agent status/result
+ *   steer_subagent       — LLM-callable: send a steering message to a running agent
+ *
+ * Commands:
+ *   /agents                 — Interactive agent management menu
+ */
+import { existsSync, mkdirSync, unlinkSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { Text } from "@mariozechner/pi-tui";
+import { Type } from "@sinclair/typebox";
+import { AgentManager } from "./agent-manager.js";
+import { steerAgent, getAgentConversation, getDefaultMaxTurns, setDefaultMaxTurns, getGraceTurns, setGraceTurns } from "./agent-runner.js";
+import { GroupJoinManager } from "./group-join.js";
+import { getAvailableTypes, getAllTypes, getDefaultAgentNames, getUserAgentNames, getAgentConfig, resolveType, registerAgents, BUILTIN_TOOL_NAMES } from "./agent-types.js";
+import { loadCustomAgents } from "./custom-agents.js";
+import { resolveModel } from "./model-resolver.js";
+import { AgentWidget, SPINNER, formatTokens, formatMs, formatDuration, getDisplayName, getPromptModeLabel, describeActivity, } from "./ui/agent-widget.js";
+// ---- Shared helpers ----
+/** Tool execute return value for a text response. */
+function textResult(msg, details) {
+    return { content: [{ type: "text", text: msg }], details: details };
+}
+/** Safe token formatting — wraps session.getSessionStats() in try-catch. */
+function safeFormatTokens(session) {
+    if (!session)
+        return "";
+    try {
+        return formatTokens(session.getSessionStats().tokens.total);
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Create an AgentActivity state and spawn callbacks for tracking tool usage.
+ * Used by both foreground and background paths to avoid duplication.
+ */
+function createActivityTracker(onStreamUpdate) {
+    const state = { activeTools: new Map(), toolUses: 0, tokens: "", responseText: "", session: undefined };
+    const callbacks = {
+        onToolActivity: (activity) => {
+            if (activity.type === "start") {
+                state.activeTools.set(activity.toolName + "_" + Date.now(), activity.toolName);
+            }
+            else {
+                for (const [key, name] of state.activeTools) {
+                    if (name === activity.toolName) {
+                        state.activeTools.delete(key);
+                        break;
+                    }
+                }
+                state.toolUses++;
+            }
+            state.tokens = safeFormatTokens(state.session);
+            onStreamUpdate?.();
+        },
+        onTextDelta: (_delta, fullText) => {
+            state.responseText = fullText;
+            onStreamUpdate?.();
+        },
+        onSessionCreated: (session) => {
+            state.session = session;
+        },
+    };
+    return { state, callbacks };
+}
+/** Human-readable status label for agent completion. */
+function getStatusLabel(status, error) {
+    switch (status) {
+        case "error": return `Error: ${error ?? "unknown"}`;
+        case "aborted": return "Aborted (max turns exceeded)";
+        case "steered": return "Wrapped up (turn limit)";
+        case "stopped": return "Stopped";
+        default: return "Done";
+    }
+}
+/** Parenthetical status note for completed agent result text. */
+function getStatusNote(status) {
+    switch (status) {
+        case "aborted": return " (aborted — max turns exceeded, output may be incomplete)";
+        case "steered": return " (wrapped up — reached turn limit)";
+        case "stopped": return " (stopped by user)";
+        default: return "";
+    }
+}
+/** Build AgentDetails from a base + record-specific fields. */
+function buildDetails(base, record, overrides) {
+    return {
+        ...base,
+        toolUses: record.toolUses,
+        tokens: safeFormatTokens(record.session),
+        durationMs: (record.completedAt ?? Date.now()) - record.startedAt,
+        status: record.status,
+        agentId: record.id,
+        error: record.error,
+        ...overrides,
+    };
+}
+export default function (pi) {
+    /** Reload agents from .pi/agents/*.md and merge with defaults (called on init and each Agent invocation). */
+    const reloadCustomAgents = () => {
+        const userAgents = loadCustomAgents(process.cwd());
+        registerAgents(userAgents);
+    };
+    // Initial load
+    reloadCustomAgents();
+    // ---- Agent activity tracking + widget ----
+    const agentActivity = new Map();
+    // ---- Individual nudge helper (async join mode) ----
+    function sendIndividualNudge(record) {
+        const displayName = getDisplayName(record.type);
+        const duration = formatDuration(record.startedAt, record.completedAt);
+        const status = getStatusLabel(record.status, record.error);
+        const resultPreview = record.result
+            ? record.result.length > 500
+                ? record.result.slice(0, 500) + "\n...(truncated, use get_subagent_result for full output)"
+                : record.result
+            : "No output.";
+        agentActivity.delete(record.id);
+        widget.markFinished(record.id);
+        const tokens = safeFormatTokens(record.session);
+        const toolStats = tokens ? `Tool uses: ${record.toolUses} | ${tokens}` : `Tool uses: ${record.toolUses}`;
+        pi.sendUserMessage(`Background agent completed: ${displayName} (${record.description})\n` +
+            `Agent ID: ${record.id} | Status: ${status} | ${toolStats} | Duration: ${duration}\n\n` +
+            resultPreview, { deliverAs: "followUp" });
+        widget.update();
+    }
+    /** Format a single agent's summary for grouped notification. */
+    function formatAgentSummary(record) {
+        const displayName = getDisplayName(record.type);
+        const duration = formatDuration(record.startedAt, record.completedAt);
+        const status = getStatusLabel(record.status, record.error);
+        const resultPreview = record.result
+            ? record.result.length > 300
+                ? record.result.slice(0, 300) + "\n...(truncated)"
+                : record.result
+            : "No output.";
+        const tokens = safeFormatTokens(record.session);
+        const toolStats = tokens ? `Tools: ${record.toolUses} | ${tokens}` : `Tools: ${record.toolUses}`;
+        return `- ${displayName} (${record.description})\n  ID: ${record.id} | Status: ${status} | ${toolStats} | Duration: ${duration}\n  ${resultPreview}`;
+    }
+    // ---- Group join manager ----
+    const groupJoin = new GroupJoinManager((records, partial) => {
+        // Filter out agents whose results were already consumed via get_subagent_result
+        const unconsumed = records.filter(r => !r.resultConsumed);
+        for (const r of records) {
+            agentActivity.delete(r.id);
+            widget.markFinished(r.id);
+        }
+        // If all results were already consumed, skip the notification entirely
+        if (unconsumed.length === 0) {
+            widget.update();
+            return;
+        }
+        const total = unconsumed.length;
+        const label = partial ? `${total} agent(s) finished (partial — others still running)` : `${total} agent(s) finished`;
+        const summary = unconsumed.map(r => formatAgentSummary(r)).join("\n\n");
+        pi.sendUserMessage(`Background agent group completed: ${label}\n\n${summary}\n\nUse get_subagent_result for full output.`, { deliverAs: "followUp" });
+        widget.update();
+    }, 30_000);
+    // Background completion: route through group join or send individual nudge
+    const manager = new AgentManager((record) => {
+        // Skip notification if result was already consumed via get_subagent_result
+        if (record.resultConsumed) {
+            agentActivity.delete(record.id);
+            widget.markFinished(record.id);
+            widget.update();
+            return;
+        }
+        // If this agent is pending batch finalization (debounce window still open),
+        // don't send an individual nudge — finalizeBatch will pick it up retroactively.
+        if (currentBatchAgents.some(a => a.id === record.id)) {
+            widget.update();
+            return;
+        }
+        const result = groupJoin.onAgentComplete(record);
+        if (result === 'pass') {
+            sendIndividualNudge(record);
+        }
+        // 'held' → do nothing, group will fire later
+        // 'delivered' → group callback already fired
+        widget.update();
+    });
+    // Expose manager via Symbol.for() global registry for cross-package access.
+    // Standard Node.js pattern for cross-package singletons (used by OpenTelemetry, etc.).
+    const MANAGER_KEY = Symbol.for("pi-subagents:manager");
+    globalThis[MANAGER_KEY] = {
+        waitForAll: () => manager.waitForAll(),
+        hasRunning: () => manager.hasRunning(),
+    };
+    // Wait for all subagents on shutdown, then dispose the manager
+    pi.on("session_shutdown", async () => {
+        delete globalThis[MANAGER_KEY];
+        await manager.waitForAll();
+        manager.dispose();
+    });
+    // Live widget: show running agents above editor
+    const widget = new AgentWidget(manager, agentActivity);
+    // ---- Join mode configuration ----
+    let defaultJoinMode = 'smart';
+    function getDefaultJoinMode() { return defaultJoinMode; }
+    function setDefaultJoinMode(mode) { defaultJoinMode = mode; }
+    // ---- Batch tracking for smart join mode ----
+    // Collects background agent IDs spawned in the current turn for smart grouping.
+    // Uses a debounced timer: each new agent resets the 100ms window so that all
+    // parallel tool calls (which may be dispatched across multiple microtasks by the
+    // framework) are captured in the same batch.
+    let currentBatchAgents = [];
+    let batchFinalizeTimer;
+    let batchCounter = 0;
+    /** Finalize the current batch: if 2+ smart-mode agents, register as a group. */
+    function finalizeBatch() {
+        batchFinalizeTimer = undefined;
+        const batchAgents = [...currentBatchAgents];
+        currentBatchAgents = [];
+        const smartAgents = batchAgents.filter(a => a.joinMode === 'smart' || a.joinMode === 'group');
+        if (smartAgents.length >= 2) {
+            const groupId = `batch-${++batchCounter}`;
+            const ids = smartAgents.map(a => a.id);
+            groupJoin.registerGroup(groupId, ids);
+            // Retroactively process agents that already completed during the debounce window.
+            // Their onComplete fired but was deferred (agent was in currentBatchAgents),
+            // so we feed them into the group now.
+            for (const id of ids) {
+                const record = manager.getRecord(id);
+                if (!record)
+                    continue;
+                record.groupId = groupId;
+                if (record.completedAt != null && !record.resultConsumed) {
+                    groupJoin.onAgentComplete(record);
+                }
+            }
+        }
+        else {
+            // No group formed — send individual nudges for any agents that completed
+            // during the debounce window and had their notification deferred.
+            for (const { id } of batchAgents) {
+                const record = manager.getRecord(id);
+                if (record?.completedAt != null && !record.resultConsumed) {
+                    sendIndividualNudge(record);
+                }
+            }
+        }
+    }
+    // Grab UI context from first tool execution + clear lingering widget on new turn
+    pi.on("tool_execution_start", async (_event, ctx) => {
+        widget.setUICtx(ctx.ui);
+        widget.onTurnStart();
+    });
+    /** Build the full type list text dynamically from the unified registry. */
+    const buildTypeListText = () => {
+        const defaultNames = getDefaultAgentNames();
+        const userNames = getUserAgentNames();
+        const defaultDescs = defaultNames.map((name) => {
+            const cfg = getAgentConfig(name);
+            const modelSuffix = cfg?.model ? ` (${getModelLabelFromConfig(cfg.model)})` : "";
+            return `- ${name}: ${cfg?.description ?? name}${modelSuffix}`;
+        });
+        const customDescs = userNames.map((name) => {
+            const cfg = getAgentConfig(name);
+            return `- ${name}: ${cfg?.description ?? name}`;
+        });
+        return [
+            "Default agents:",
+            ...defaultDescs,
+            ...(customDescs.length > 0 ? ["", "Custom agents:", ...customDescs] : []),
+            "",
+            "Custom agents can be defined in .pi/agents/<name>.md (project) or ~/.pi/agent/agents/<name>.md (global) — they are picked up automatically. Project-level agents override global ones. Creating a .md file with the same name as a default agent overrides it.",
+        ].join("\n");
+    };
+    /** Derive a short model label from a model string. */
+    function getModelLabelFromConfig(model) {
+        // Strip provider prefix (e.g. "anthropic/claude-sonnet-4-6" → "claude-sonnet-4-6")
+        const name = model.includes("/") ? model.split("/").pop() : model;
+        // Strip trailing date suffix (e.g. "claude-haiku-4-5-20251001" → "claude-haiku-4-5")
+        return name.replace(/-\d{8}$/, "");
+    }
+    const typeListText = buildTypeListText();
+    // ---- Agent tool ----
+    pi.registerTool({
+        name: "Agent",
+        label: "Agent",
+        description: `Launch a new agent to handle complex, multi-step tasks autonomously.
+
+The Agent tool launches specialized agents that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.
+
+Available agent types:
+${typeListText}
+
+Guidelines:
+- For parallel work, use run_in_background: true on each agent. Foreground calls run sequentially — only one executes at a time.
+- Use Explore for codebase searches and code understanding.
+- Use Plan for architecture and implementation planning.
+- Use general-purpose for complex tasks that need file editing.
+- Provide clear, detailed prompts so the agent can work autonomously.
+- Agent results are returned as text — summarize them for the user.
+- Use run_in_background for work you don't need immediately. You will be notified when it completes.
+- Use resume with an agent ID to continue a previous agent's work.
+- Use steer_subagent to send mid-run messages to a running background agent.
+- Use model to specify a different model (as "provider/modelId", or fuzzy e.g. "haiku", "sonnet").
+- Use thinking to control extended thinking level.
+- Use inherit_context if the agent needs the parent conversation history.
+- Use join_mode to control how background completion notifications are delivered. By default (smart), 2+ background agents spawned in the same turn are grouped into a single notification. Use "async" for individual notifications or "group" to force grouping.`,
+        parameters: Type.Object({
+            prompt: Type.String({
+                description: "The task for the agent to perform.",
+            }),
+            description: Type.String({
+                description: "A short (3-5 word) description of the task (shown in UI).",
+            }),
+            subagent_type: Type.String({
+                description: `The type of specialized agent to use. Available types: ${getAvailableTypes().join(", ")}. Custom agents from .pi/agents/*.md (project) or ~/.pi/agent/agents/*.md (global) are also available.`,
+            }),
+            model: Type.Optional(Type.String({
+                description: 'Optional model override. Accepts "provider/modelId" or fuzzy name (e.g. "haiku", "sonnet"). Omit to use the agent type\'s default.',
+            })),
+            thinking: Type.Optional(Type.String({
+                description: "Thinking level: off, minimal, low, medium, high, xhigh. Overrides agent default.",
+            })),
+            max_turns: Type.Optional(Type.Number({
+                description: "Maximum number of agentic turns before stopping.",
+                minimum: 1,
+            })),
+            run_in_background: Type.Optional(Type.Boolean({
+                description: "Set to true to run in background. Returns agent ID immediately. You will be notified on completion.",
+            })),
+            resume: Type.Optional(Type.String({
+                description: "Optional agent ID to resume from. Continues from previous context.",
+            })),
+            isolated: Type.Optional(Type.Boolean({
+                description: "If true, agent gets no extension/MCP tools — only built-in tools.",
+            })),
+            inherit_context: Type.Optional(Type.Boolean({
+                description: "If true, fork parent conversation into the agent. Default: false (fresh context).",
+            })),
+            join_mode: Type.Optional(Type.Union([
+                Type.Literal("async"),
+                Type.Literal("group"),
+            ], { description: "Override join behavior for background agents. async: individual nudge on completion. group: hold and send one consolidated notification when all agents in the group complete. Default: smart (auto-groups 2+ background agents spawned in the same turn)." })),
+        }),
+        // ---- Custom rendering: Claude Code style ----
+        renderCall(args, theme) {
+            const displayName = args.subagent_type ? getDisplayName(args.subagent_type) : "Agent";
+            const desc = args.description ?? "";
+            return new Text("▸ " + theme.fg("toolTitle", theme.bold(displayName)) + (desc ? "  " + theme.fg("muted", desc) : ""), 0, 0);
+        },
+        renderResult(result, { expanded, isPartial }, theme) {
+            const details = result.details;
+            if (!details) {
+                const text = result.content[0]?.type === "text" ? result.content[0].text : "";
+                return new Text(text, 0, 0);
+            }
+            // Helper: build "haiku · thinking: high · 3 tool uses · 33.8k tokens" stats string
+            const stats = (d) => {
+                const parts = [];
+                if (d.modelName)
+                    parts.push(d.modelName);
+                if (d.tags)
+                    parts.push(...d.tags);
+                if (d.toolUses > 0)
+                    parts.push(`${d.toolUses} tool use${d.toolUses === 1 ? "" : "s"}`);
+                if (d.tokens)
+                    parts.push(d.tokens);
+                return parts.map(p => theme.fg("dim", p)).join(" " + theme.fg("dim", "·") + " ");
+            };
+            // ---- While running (streaming) ----
+            if (isPartial || details.status === "running") {
+                const frame = SPINNER[details.spinnerFrame ?? 0];
+                const s = stats(details);
+                let line = theme.fg("accent", frame) + (s ? " " + s : "");
+                line += "\n" + theme.fg("dim", `  ⎿  ${details.activity ?? "thinking…"}`);
+                return new Text(line, 0, 0);
+            }
+            // ---- Background agent launched ----
+            if (details.status === "background") {
+                return new Text(theme.fg("dim", `  ⎿  Running in background (ID: ${details.agentId})`), 0, 0);
+            }
+            // ---- Completed / Steered ----
+            if (details.status === "completed" || details.status === "steered") {
+                const duration = formatMs(details.durationMs);
+                const isSteered = details.status === "steered";
+                const icon = isSteered ? theme.fg("warning", "✓") : theme.fg("success", "✓");
+                const s = stats(details);
+                let line = icon + (s ? " " + s : "");
+                line += " " + theme.fg("dim", "·") + " " + theme.fg("dim", duration);
+                if (expanded) {
+                    const resultText = result.content[0]?.type === "text" ? result.content[0].text : "";
+                    if (resultText) {
+                        const lines = resultText.split("\n").slice(0, 50);
+                        for (const l of lines) {
+                            line += "\n" + theme.fg("dim", `  ${l}`);
+                        }
+                        if (resultText.split("\n").length > 50) {
+                            line += "\n" + theme.fg("muted", "  ... (use get_subagent_result with verbose for full output)");
+                        }
+                    }
+                }
+                else {
+                    const doneText = isSteered ? "Wrapped up (turn limit)" : "Done";
+                    line += "\n" + theme.fg("dim", `  ⎿  ${doneText}`);
+                }
+                return new Text(line, 0, 0);
+            }
+            // ---- Stopped (user-initiated abort) ----
+            if (details.status === "stopped") {
+                const s = stats(details);
+                let line = theme.fg("dim", "■") + (s ? " " + s : "");
+                line += "\n" + theme.fg("dim", "  ⎿  Stopped");
+                return new Text(line, 0, 0);
+            }
+            // ---- Error / Aborted (hard max_turns) ----
+            const s = stats(details);
+            let line = theme.fg("error", "✗") + (s ? " " + s : "");
+            if (details.status === "error") {
+                line += "\n" + theme.fg("error", `  ⎿  Error: ${details.error ?? "unknown"}`);
+            }
+            else {
+                line += "\n" + theme.fg("warning", "  ⎿  Aborted (max turns exceeded)");
+            }
+            return new Text(line, 0, 0);
+        },
+        // ---- Execute ----
+        execute: async (_toolCallId, params, signal, onUpdate, ctx) => {
+            // Ensure we have UI context for widget rendering
+            widget.setUICtx(ctx.ui);
+            // Reload custom agents so new .pi/agents/*.md files are picked up without restart
+            reloadCustomAgents();
+            const rawType = params.subagent_type;
+            const resolved = resolveType(rawType);
+            const subagentType = resolved ?? "general-purpose";
+            const fellBack = resolved === undefined;
+            const displayName = getDisplayName(subagentType);
+            // Get agent config (if any)
+            const customConfig = getAgentConfig(subagentType);
+            // Resolve model if specified (supports exact "provider/modelId" or fuzzy match)
+            let model = ctx.model;
+            const modelInput = params.model ?? customConfig?.model;
+            if (modelInput) {
+                const resolved = resolveModel(modelInput, ctx.modelRegistry);
+                if (typeof resolved === "string") {
+                    if (params.model)
+                        return textResult(resolved); // user-specified: error
+                    // config-specified: silent fallback to parent
+                }
+                else {
+                    model = resolved;
+                }
+            }
+            // Resolve thinking: explicit param > custom config > undefined
+            const thinking = (params.thinking ?? customConfig?.thinking);
+            // Resolve spawn-time defaults from custom config (caller overrides)
+            const inheritContext = params.inherit_context ?? customConfig?.inheritContext ?? false;
+            const runInBackground = params.run_in_background ?? customConfig?.runInBackground ?? false;
+            const isolated = params.isolated ?? customConfig?.isolated ?? false;
+            // Build display tags for non-default config
+            const parentModelId = ctx.model?.id;
+            const effectiveModelId = model?.id;
+            const agentModelName = effectiveModelId && effectiveModelId !== parentModelId
+                ? (model?.name ?? effectiveModelId).replace(/^Claude\s+/i, "").toLowerCase()
+                : undefined;
+            const agentTags = [];
+            const modeLabel = getPromptModeLabel(subagentType);
+            if (modeLabel)
+                agentTags.push(modeLabel);
+            if (thinking)
+                agentTags.push(`thinking: ${thinking}`);
+            if (isolated)
+                agentTags.push("isolated");
+            // Shared base fields for all AgentDetails in this call
+            const detailBase = {
+                displayName,
+                description: params.description,
+                subagentType,
+                modelName: agentModelName,
+                tags: agentTags.length > 0 ? agentTags : undefined,
+            };
+            // Resume existing agent
+            if (params.resume) {
+                const existing = manager.getRecord(params.resume);
+                if (!existing) {
+                    return textResult(`Agent not found: "${params.resume}". It may have been cleaned up.`);
+                }
+                if (!existing.session) {
+                    return textResult(`Agent "${params.resume}" has no active session to resume.`);
+                }
+                const record = await manager.resume(params.resume, params.prompt, signal);
+                if (!record) {
+                    return textResult(`Failed to resume agent "${params.resume}".`);
+                }
+                return textResult(record.result ?? record.error ?? "No output.", buildDetails(detailBase, record));
+            }
+            // Background execution
+            if (runInBackground) {
+                const { state: bgState, callbacks: bgCallbacks } = createActivityTracker();
+                const id = manager.spawn(pi, ctx, subagentType, params.prompt, {
+                    description: params.description,
+                    model,
+                    maxTurns: params.max_turns,
+                    isolated,
+                    inheritContext,
+                    thinkingLevel: thinking,
+                    isBackground: true,
+                    ...bgCallbacks,
+                });
+                // Determine join mode and track for batching
+                const joinMode = params.join_mode ?? defaultJoinMode;
+                const record = manager.getRecord(id);
+                if (record)
+                    record.joinMode = joinMode;
+                if (joinMode === 'async') {
+                    // Explicit async — not part of any batch
+                }
+                else {
+                    // smart or group — add to current batch
+                    currentBatchAgents.push({ id, joinMode });
+                    // Debounce: reset timer on each new agent so parallel tool calls
+                    // dispatched across multiple event loop ticks are captured together
+                    if (batchFinalizeTimer)
+                        clearTimeout(batchFinalizeTimer);
+                    batchFinalizeTimer = setTimeout(finalizeBatch, 100);
+                }
+                agentActivity.set(id, bgState);
+                widget.ensureTimer();
+                widget.update();
+                const isQueued = record?.status === "queued";
+                return textResult(`Agent ${isQueued ? "queued" : "started"} in background.\n` +
+                    `Agent ID: ${id}\n` +
+                    `Type: ${displayName}\n` +
+                    `Description: ${params.description}\n` +
+                    (isQueued ? `Position: queued (max ${manager.getMaxConcurrent()} concurrent)\n` : "") +
+                    `\nYou will be notified when this agent completes.\n` +
+                    `Use get_subagent_result to retrieve full results, or steer_subagent to send it messages.\n` +
+                    `Do not duplicate this agent's work.`, { ...detailBase, toolUses: 0, tokens: "", durationMs: 0, status: "background", agentId: id });
+            }
+            // Foreground (synchronous) execution — stream progress via onUpdate
+            let spinnerFrame = 0;
+            const startedAt = Date.now();
+            let fgId;
+            const streamUpdate = () => {
+                const details = {
+                    ...detailBase,
+                    toolUses: fgState.toolUses,
+                    tokens: fgState.tokens,
+                    durationMs: Date.now() - startedAt,
+                    status: "running",
+                    activity: describeActivity(fgState.activeTools, fgState.responseText),
+                    spinnerFrame: spinnerFrame % SPINNER.length,
+                };
+                onUpdate?.({
+                    content: [{ type: "text", text: `${fgState.toolUses} tool uses...` }],
+                    details: details,
+                });
+            };
+            const { state: fgState, callbacks: fgCallbacks } = createActivityTracker(streamUpdate);
+            // Wire session creation to register in widget
+            const origOnSession = fgCallbacks.onSessionCreated;
+            fgCallbacks.onSessionCreated = (session) => {
+                origOnSession(session);
+                for (const a of manager.listAgents()) {
+                    if (a.session === session) {
+                        fgId = a.id;
+                        agentActivity.set(a.id, fgState);
+                        widget.ensureTimer();
+                        break;
+                    }
+                }
+            };
+            // Animate spinner at ~80ms (smooth rotation through 10 braille frames)
+            const spinnerInterval = setInterval(() => {
+                spinnerFrame++;
+                streamUpdate();
+            }, 80);
+            streamUpdate();
+            const record = await manager.spawnAndWait(pi, ctx, subagentType, params.prompt, {
+                description: params.description,
+                model,
+                maxTurns: params.max_turns,
+                isolated,
+                inheritContext,
+                thinkingLevel: thinking,
+                ...fgCallbacks,
+            });
+            clearInterval(spinnerInterval);
+            // Clean up foreground agent from widget
+            if (fgId) {
+                agentActivity.delete(fgId);
+                widget.markFinished(fgId);
+            }
+            // Get final token count
+            const tokenText = safeFormatTokens(fgState.session);
+            const details = buildDetails(detailBase, record, { tokens: tokenText });
+            const fallbackNote = fellBack
+                ? `Note: Unknown agent type "${rawType}" — using general-purpose.\n\n`
+                : "";
+            if (record.status === "error") {
+                return textResult(`${fallbackNote}Agent failed: ${record.error}`, details);
+            }
+            const durationMs = (record.completedAt ?? Date.now()) - record.startedAt;
+            const statsParts = [`${record.toolUses} tool uses`];
+            if (tokenText)
+                statsParts.push(tokenText);
+            return textResult(`${fallbackNote}Agent completed in ${formatMs(durationMs)} (${statsParts.join(", ")})${getStatusNote(record.status)}.\n\n` +
+                (record.result ?? "No output."), details);
+        },
+    });
+    // ---- get_subagent_result tool ----
+    pi.registerTool({
+        name: "get_subagent_result",
+        label: "Get Agent Result",
+        description: "Check status and retrieve results from a background agent. Use the agent ID returned by Agent with run_in_background.",
+        parameters: Type.Object({
+            agent_id: Type.String({
+                description: "The agent ID to check.",
+            }),
+            wait: Type.Optional(Type.Boolean({
+                description: "If true, wait for the agent to complete before returning. Default: false.",
+            })),
+            verbose: Type.Optional(Type.Boolean({
+                description: "If true, include the agent's full conversation (messages + tool calls). Default: false.",
+            })),
+        }),
+        execute: async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+            const record = manager.getRecord(params.agent_id);
+            if (!record) {
+                return textResult(`Agent not found: "${params.agent_id}". It may have been cleaned up.`);
+            }
+            // Wait for completion if requested
+            if (params.wait && record.status === "running" && record.promise) {
+                await record.promise;
+            }
+            const displayName = getDisplayName(record.type);
+            const duration = formatDuration(record.startedAt, record.completedAt);
+            const tokens = safeFormatTokens(record.session);
+            const toolStats = tokens ? `Tool uses: ${record.toolUses} | ${tokens}` : `Tool uses: ${record.toolUses}`;
+            let output = `Agent: ${record.id}\n` +
+                `Type: ${displayName} | Status: ${record.status} | ${toolStats} | Duration: ${duration}\n` +
+                `Description: ${record.description}\n\n`;
+            if (record.status === "running") {
+                output += "Agent is still running. Use wait: true or check back later.";
+            }
+            else if (record.status === "error") {
+                output += `Error: ${record.error}`;
+            }
+            else {
+                output += record.result ?? "No output.";
+            }
+            // Mark result as consumed — suppresses the completion notification
+            if (record.status !== "running" && record.status !== "queued") {
+                record.resultConsumed = true;
+            }
+            // Verbose: include full conversation
+            if (params.verbose && record.session) {
+                const conversation = getAgentConversation(record.session);
+                if (conversation) {
+                    output += `\n\n--- Agent Conversation ---\n${conversation}`;
+                }
+            }
+            return textResult(output);
+        },
+    });
+    // ---- steer_subagent tool ----
+    pi.registerTool({
+        name: "steer_subagent",
+        label: "Steer Agent",
+        description: "Send a steering message to a running agent. The message will interrupt the agent after its current tool execution " +
+            "and be injected into its conversation, allowing you to redirect its work mid-run. Only works on running agents.",
+        parameters: Type.Object({
+            agent_id: Type.String({
+                description: "The agent ID to steer (must be currently running).",
+            }),
+            message: Type.String({
+                description: "The steering message to send. This will appear as a user message in the agent's conversation.",
+            }),
+        }),
+        execute: async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+            const record = manager.getRecord(params.agent_id);
+            if (!record) {
+                return textResult(`Agent not found: "${params.agent_id}". It may have been cleaned up.`);
+            }
+            if (record.status !== "running") {
+                return textResult(`Agent "${params.agent_id}" is not running (status: ${record.status}). Cannot steer a non-running agent.`);
+            }
+            if (!record.session) {
+                return textResult(`Agent "${params.agent_id}" has no active session yet. It may still be initializing.`);
+            }
+            try {
+                await steerAgent(record.session, params.message);
+                return textResult(`Steering message sent to agent ${record.id}. The agent will process it after its current tool execution.`);
+            }
+            catch (err) {
+                return textResult(`Failed to steer agent: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        },
+    });
+    // ---- /agents interactive menu ----
+    const projectAgentsDir = () => join(process.cwd(), ".pi", "agents");
+    const personalAgentsDir = () => join(homedir(), ".pi", "agent", "agents");
+    /** Find the file path of a custom agent by name (project first, then global). */
+    function findAgentFile(name) {
+        const projectPath = join(projectAgentsDir(), `${name}.md`);
+        if (existsSync(projectPath))
+            return { path: projectPath, location: "project" };
+        const personalPath = join(personalAgentsDir(), `${name}.md`);
+        if (existsSync(personalPath))
+            return { path: personalPath, location: "personal" };
+        return undefined;
+    }
+    function getModelLabel(type, registry) {
+        const cfg = getAgentConfig(type);
+        if (!cfg?.model)
+            return "inherit";
+        // If registry provided, check if the model actually resolves
+        if (registry) {
+            const resolved = resolveModel(cfg.model, registry);
+            if (typeof resolved === "string")
+                return "inherit"; // model not available
+        }
+        return getModelLabelFromConfig(cfg.model);
+    }
+    async function showAgentsMenu(ctx) {
+        reloadCustomAgents();
+        const allNames = getAllTypes();
+        // Build select options
+        const options = [];
+        // Running agents entry (only if there are active agents)
+        const agents = manager.listAgents();
+        if (agents.length > 0) {
+            const running = agents.filter(a => a.status === "running" || a.status === "queued").length;
+            const done = agents.filter(a => a.status === "completed" || a.status === "steered").length;
+            options.push(`Running agents (${agents.length}) — ${running} running, ${done} done`);
+        }
+        // Agent types list
+        if (allNames.length > 0) {
+            options.push(`Agent types (${allNames.length})`);
+        }
+        // Actions
+        options.push("Create new agent");
+        options.push("Settings");
+        const noAgentsMsg = allNames.length === 0 && agents.length === 0
+            ? "No agents found. Create specialized subagents that can be delegated to.\n\n" +
+                "Each subagent has its own context window, custom system prompt, and specific tools.\n\n" +
+                "Try creating: Code Reviewer, Security Auditor, Test Writer, or Documentation Writer.\n\n"
+            : "";
+        if (noAgentsMsg) {
+            ctx.ui.notify(noAgentsMsg, "info");
+        }
+        const choice = await ctx.ui.select("Agents", options);
+        if (!choice)
+            return;
+        if (choice.startsWith("Running agents (")) {
+            await showRunningAgents(ctx);
+            await showAgentsMenu(ctx);
+        }
+        else if (choice.startsWith("Agent types (")) {
+            await showAllAgentsList(ctx);
+            await showAgentsMenu(ctx);
+        }
+        else if (choice === "Create new agent") {
+            await showCreateWizard(ctx);
+        }
+        else if (choice === "Settings") {
+            await showSettings(ctx);
+            await showAgentsMenu(ctx);
+        }
+    }
+    async function showAllAgentsList(ctx) {
+        const allNames = getAllTypes();
+        if (allNames.length === 0) {
+            ctx.ui.notify("No agents.", "info");
+            return;
+        }
+        // Source indicators: defaults unmarked, custom agents get • (project) or ◦ (global)
+        // Disabled agents get ✕ prefix
+        const sourceIndicator = (cfg) => {
+            const disabled = cfg?.enabled === false;
+            if (cfg?.source === "project")
+                return disabled ? "✕• " : "•  ";
+            if (cfg?.source === "global")
+                return disabled ? "✕◦ " : "◦  ";
+            if (disabled)
+                return "✕  ";
+            return "   ";
+        };
+        const entries = allNames.map(name => {
+            const cfg = getAgentConfig(name);
+            const disabled = cfg?.enabled === false;
+            const model = getModelLabel(name, ctx.modelRegistry);
+            const indicator = sourceIndicator(cfg);
+            const prefix = `${indicator}${name} · ${model}`;
+            const desc = disabled ? "(disabled)" : (cfg?.description ?? name);
+            return { name, prefix, desc };
+        });
+        const maxPrefix = Math.max(...entries.map(e => e.prefix.length));
+        const hasCustom = allNames.some(n => { const c = getAgentConfig(n); return c && !c.isDefault && c.enabled !== false; });
+        const hasDisabled = allNames.some(n => getAgentConfig(n)?.enabled === false);
+        const legendParts = [];
+        if (hasCustom)
+            legendParts.push("• = project  ◦ = global");
+        if (hasDisabled)
+            legendParts.push("✕ = disabled");
+        const legend = legendParts.length ? "\n" + legendParts.join("  ") : "";
+        const options = entries.map(({ prefix, desc }) => `${prefix.padEnd(maxPrefix)} — ${desc}`);
+        if (legend)
+            options.push(legend);
+        const choice = await ctx.ui.select("Agent types", options);
+        if (!choice)
+            return;
+        const agentName = choice.split(" · ")[0].replace(/^[•◦✕\s]+/, "").trim();
+        if (getAgentConfig(agentName)) {
+            await showAgentDetail(ctx, agentName);
+            await showAllAgentsList(ctx);
+        }
+    }
+    async function showRunningAgents(ctx) {
+        const agents = manager.listAgents();
+        if (agents.length === 0) {
+            ctx.ui.notify("No agents.", "info");
+            return;
+        }
+        const options = agents.map(a => {
+            const dn = getDisplayName(a.type);
+            const dur = formatDuration(a.startedAt, a.completedAt);
+            return `${dn} (${a.description}) · ${a.toolUses} tools · ${a.status} · ${dur}`;
+        });
+        const choice = await ctx.ui.select("Running agents", options);
+        if (!choice)
+            return;
+        // Find the selected agent by matching the option index
+        const idx = options.indexOf(choice);
+        if (idx < 0)
+            return;
+        const record = agents[idx];
+        await viewAgentConversation(ctx, record);
+        // Back-navigation: re-show the list
+        await showRunningAgents(ctx);
+    }
+    async function viewAgentConversation(ctx, record) {
+        if (!record.session) {
+            ctx.ui.notify(`Agent is ${record.status === "queued" ? "queued" : "expired"} — no session available.`, "info");
+            return;
+        }
+        const { ConversationViewer } = await import("./ui/conversation-viewer.js");
+        const session = record.session;
+        const activity = agentActivity.get(record.id);
+        await ctx.ui.custom((tui, theme, _keybindings, done) => {
+            return new ConversationViewer(tui, session, record, activity, theme, done);
+        }, {
+            overlay: true,
+            overlayOptions: { anchor: "center", width: "90%" },
+        });
+    }
+    async function showAgentDetail(ctx, name) {
+        const cfg = getAgentConfig(name);
+        if (!cfg) {
+            ctx.ui.notify(`Agent config not found for "${name}".`, "warning");
+            return;
+        }
+        const file = findAgentFile(name);
+        const isDefault = cfg.isDefault === true;
+        const disabled = cfg.enabled === false;
+        let menuOptions;
+        if (disabled && file) {
+            // Disabled agent with a file — offer Enable
+            menuOptions = isDefault
+                ? ["Enable", "Edit", "Reset to default", "Delete", "Back"]
+                : ["Enable", "Edit", "Delete", "Back"];
+        }
+        else if (isDefault && !file) {
+            // Default agent with no .md override
+            menuOptions = ["Eject (export as .md)", "Disable", "Back"];
+        }
+        else if (isDefault && file) {
+            // Default agent with .md override (ejected)
+            menuOptions = ["Edit", "Disable", "Reset to default", "Delete", "Back"];
+        }
+        else {
+            // User-defined agent
+            menuOptions = ["Edit", "Disable", "Delete", "Back"];
+        }
+        const choice = await ctx.ui.select(name, menuOptions);
+        if (!choice || choice === "Back")
+            return;
+        if (choice === "Edit" && file) {
+            const content = readFileSync(file.path, "utf-8");
+            const edited = await ctx.ui.editor(`Edit ${name}`, content);
+            if (edited !== undefined && edited !== content) {
+                const { writeFileSync } = await import("node:fs");
+                writeFileSync(file.path, edited, "utf-8");
+                reloadCustomAgents();
+                ctx.ui.notify(`Updated ${file.path}`, "info");
+            }
+        }
+        else if (choice === "Delete") {
+            if (file) {
+                const confirmed = await ctx.ui.confirm("Delete agent", `Delete ${name} from ${file.location} (${file.path})?`);
+                if (confirmed) {
+                    unlinkSync(file.path);
+                    reloadCustomAgents();
+                    ctx.ui.notify(`Deleted ${file.path}`, "info");
+                }
+            }
+        }
+        else if (choice === "Reset to default" && file) {
+            const confirmed = await ctx.ui.confirm("Reset to default", `Delete override ${file.path} and restore embedded default?`);
+            if (confirmed) {
+                unlinkSync(file.path);
+                reloadCustomAgents();
+                ctx.ui.notify(`Restored default ${name}`, "info");
+            }
+        }
+        else if (choice.startsWith("Eject")) {
+            await ejectAgent(ctx, name, cfg);
+        }
+        else if (choice === "Disable") {
+            await disableAgent(ctx, name);
+        }
+        else if (choice === "Enable") {
+            await enableAgent(ctx, name);
+        }
+    }
+    /** Eject a default agent: write its embedded config as a .md file. */
+    async function ejectAgent(ctx, name, cfg) {
+        const location = await ctx.ui.select("Choose location", [
+            "Project (.pi/agents/)",
+            "Personal (~/.pi/agent/agents/)",
+        ]);
+        if (!location)
+            return;
+        const targetDir = location.startsWith("Project") ? projectAgentsDir() : personalAgentsDir();
+        mkdirSync(targetDir, { recursive: true });
+        const targetPath = join(targetDir, `${name}.md`);
+        if (existsSync(targetPath)) {
+            const overwrite = await ctx.ui.confirm("Overwrite", `${targetPath} already exists. Overwrite?`);
+            if (!overwrite)
+                return;
+        }
+        // Build the .md file content
+        const fmFields = [];
+        fmFields.push(`description: ${cfg.description}`);
+        if (cfg.displayName)
+            fmFields.push(`display_name: ${cfg.displayName}`);
+        fmFields.push(`tools: ${cfg.builtinToolNames?.join(", ") || "all"}`);
+        if (cfg.model)
+            fmFields.push(`model: ${cfg.model}`);
+        if (cfg.thinking)
+            fmFields.push(`thinking: ${cfg.thinking}`);
+        if (cfg.maxTurns)
+            fmFields.push(`max_turns: ${cfg.maxTurns}`);
+        fmFields.push(`prompt_mode: ${cfg.promptMode}`);
+        if (cfg.extensions === false)
+            fmFields.push("extensions: false");
+        else if (Array.isArray(cfg.extensions))
+            fmFields.push(`extensions: ${cfg.extensions.join(", ")}`);
+        if (cfg.skills === false)
+            fmFields.push("skills: false");
+        else if (Array.isArray(cfg.skills))
+            fmFields.push(`skills: ${cfg.skills.join(", ")}`);
+        if (cfg.inheritContext)
+            fmFields.push("inherit_context: true");
+        if (cfg.runInBackground)
+            fmFields.push("run_in_background: true");
+        if (cfg.isolated)
+            fmFields.push("isolated: true");
+        const content = `---\n${fmFields.join("\n")}\n---\n\n${cfg.systemPrompt}\n`;
+        const { writeFileSync } = await import("node:fs");
+        writeFileSync(targetPath, content, "utf-8");
+        reloadCustomAgents();
+        ctx.ui.notify(`Ejected ${name} to ${targetPath}`, "info");
+    }
+    /** Disable an agent: set enabled: false in its .md file, or create a stub for built-in defaults. */
+    async function disableAgent(ctx, name) {
+        const file = findAgentFile(name);
+        if (file) {
+            // Existing file — set enabled: false in frontmatter (idempotent)
+            const content = readFileSync(file.path, "utf-8");
+            if (content.includes("\nenabled: false\n")) {
+                ctx.ui.notify(`${name} is already disabled.`, "info");
+                return;
+            }
+            const updated = content.replace(/^---\n/, "---\nenabled: false\n");
+            const { writeFileSync } = await import("node:fs");
+            writeFileSync(file.path, updated, "utf-8");
+            reloadCustomAgents();
+            ctx.ui.notify(`Disabled ${name} (${file.path})`, "info");
+            return;
+        }
+        // No file (built-in default) — create a stub
+        const location = await ctx.ui.select("Choose location", [
+            "Project (.pi/agents/)",
+            "Personal (~/.pi/agent/agents/)",
+        ]);
+        if (!location)
+            return;
+        const targetDir = location.startsWith("Project") ? projectAgentsDir() : personalAgentsDir();
+        mkdirSync(targetDir, { recursive: true });
+        const targetPath = join(targetDir, `${name}.md`);
+        const { writeFileSync } = await import("node:fs");
+        writeFileSync(targetPath, "---\nenabled: false\n---\n", "utf-8");
+        reloadCustomAgents();
+        ctx.ui.notify(`Disabled ${name} (${targetPath})`, "info");
+    }
+    /** Enable a disabled agent by removing enabled: false from its frontmatter. */
+    async function enableAgent(ctx, name) {
+        const file = findAgentFile(name);
+        if (!file)
+            return;
+        const content = readFileSync(file.path, "utf-8");
+        const updated = content.replace(/^(---\n)enabled: false\n/, "$1");
+        const { writeFileSync } = await import("node:fs");
+        // If the file was just a stub ("---\n---\n"), delete it to restore the built-in default
+        if (updated.trim() === "---\n---" || updated.trim() === "---\n---\n") {
+            unlinkSync(file.path);
+            reloadCustomAgents();
+            ctx.ui.notify(`Enabled ${name} (removed ${file.path})`, "info");
+        }
+        else {
+            writeFileSync(file.path, updated, "utf-8");
+            reloadCustomAgents();
+            ctx.ui.notify(`Enabled ${name} (${file.path})`, "info");
+        }
+    }
+    async function showCreateWizard(ctx) {
+        const location = await ctx.ui.select("Choose location", [
+            "Project (.pi/agents/)",
+            "Personal (~/.pi/agent/agents/)",
+        ]);
+        if (!location)
+            return;
+        const targetDir = location.startsWith("Project") ? projectAgentsDir() : personalAgentsDir();
+        const method = await ctx.ui.select("Creation method", [
+            "Generate with Claude (recommended)",
+            "Manual configuration",
+        ]);
+        if (!method)
+            return;
+        if (method.startsWith("Generate")) {
+            await showGenerateWizard(ctx, targetDir);
+        }
+        else {
+            await showManualWizard(ctx, targetDir);
+        }
+    }
+    async function showGenerateWizard(ctx, targetDir) {
+        const description = await ctx.ui.input("Describe what this agent should do");
+        if (!description)
+            return;
+        const name = await ctx.ui.input("Agent name (filename, no spaces)");
+        if (!name)
+            return;
+        mkdirSync(targetDir, { recursive: true });
+        const targetPath = join(targetDir, `${name}.md`);
+        if (existsSync(targetPath)) {
+            const overwrite = await ctx.ui.confirm("Overwrite", `${targetPath} already exists. Overwrite?`);
+            if (!overwrite)
+                return;
+        }
+        ctx.ui.notify("Generating agent definition...", "info");
+        const generatePrompt = `Create a custom pi sub-agent definition file based on this description: "${description}"
+
+Write a markdown file to: ${targetPath}
+
+The file format is a markdown file with YAML frontmatter and a system prompt body:
+
+\`\`\`markdown
+---
+description: <one-line description shown in UI>
+tools: <comma-separated built-in tools: read, bash, edit, write, grep, find, ls. Use "none" for no tools. Omit for all tools>
+model: <optional model as "provider/modelId", e.g. "anthropic/claude-haiku-4-5-20251001". Omit to inherit parent model>
+thinking: <optional thinking level: off, minimal, low, medium, high, xhigh. Omit to inherit>
+max_turns: <optional max agentic turns, default 50. Omit for default>
+prompt_mode: <"replace" (body IS the full system prompt) or "append" (body is appended to default prompt). Default: replace>
+extensions: <true (inherit all MCP/extension tools), false (none), or comma-separated names. Default: true>
+skills: <true (inherit all), false (none). Default: true>
+inherit_context: <true to fork parent conversation into agent so it sees chat history. Default: false>
+run_in_background: <true to run in background by default. Default: false>
+isolated: <true for no extension/MCP tools, only built-in tools. Default: false>
+---
+
+<system prompt body — instructions for the agent>
+\`\`\`
+
+Guidelines for choosing settings:
+- For read-only tasks (review, analysis): tools: read, bash, grep, find, ls
+- For code modification tasks: include edit, write
+- Use prompt_mode: append if the agent should keep the default system prompt and add specialization on top
+- Use prompt_mode: replace for fully custom agents with their own personality/instructions
+- Set inherit_context: true if the agent needs to know what was discussed in the parent conversation
+- Set isolated: true if the agent should NOT have access to MCP servers or other extensions
+- Only include frontmatter fields that differ from defaults — omit fields where the default is fine
+
+Write the file using the write tool. Only write the file, nothing else.`;
+        const record = await manager.spawnAndWait(pi, ctx, "general-purpose", generatePrompt, {
+            description: `Generate ${name} agent`,
+            maxTurns: 5,
+        });
+        if (record.status === "error") {
+            ctx.ui.notify(`Generation failed: ${record.error}`, "warning");
+            return;
+        }
+        reloadCustomAgents();
+        if (existsSync(targetPath)) {
+            ctx.ui.notify(`Created ${targetPath}`, "info");
+        }
+        else {
+            ctx.ui.notify("Agent generation completed but file was not created. Check the agent output.", "warning");
+        }
+    }
+    async function showManualWizard(ctx, targetDir) {
+        // 1. Name
+        const name = await ctx.ui.input("Agent name (filename, no spaces)");
+        if (!name)
+            return;
+        // 2. Description
+        const description = await ctx.ui.input("Description (one line)");
+        if (!description)
+            return;
+        // 3. Tools
+        const toolChoice = await ctx.ui.select("Tools", ["all", "none", "read-only (read, bash, grep, find, ls)", "custom..."]);
+        if (!toolChoice)
+            return;
+        let tools;
+        if (toolChoice === "all") {
+            tools = BUILTIN_TOOL_NAMES.join(", ");
+        }
+        else if (toolChoice === "none") {
+            tools = "none";
+        }
+        else if (toolChoice.startsWith("read-only")) {
+            tools = "read, bash, grep, find, ls";
+        }
+        else {
+            const customTools = await ctx.ui.input("Tools (comma-separated)", BUILTIN_TOOL_NAMES.join(", "));
+            if (!customTools)
+                return;
+            tools = customTools;
+        }
+        // 4. Model
+        const modelChoice = await ctx.ui.select("Model", [
+            "inherit (parent model)",
+            "haiku",
+            "sonnet",
+            "opus",
+            "custom...",
+        ]);
+        if (!modelChoice)
+            return;
+        let modelLine = "";
+        if (modelChoice === "haiku")
+            modelLine = "\nmodel: anthropic/claude-haiku-4-5-20251001";
+        else if (modelChoice === "sonnet")
+            modelLine = "\nmodel: anthropic/claude-sonnet-4-6";
+        else if (modelChoice === "opus")
+            modelLine = "\nmodel: anthropic/claude-opus-4-6";
+        else if (modelChoice === "custom...") {
+            const customModel = await ctx.ui.input("Model (provider/modelId)");
+            if (customModel)
+                modelLine = `\nmodel: ${customModel}`;
+        }
+        // 5. Thinking
+        const thinkingChoice = await ctx.ui.select("Thinking level", [
+            "inherit",
+            "off",
+            "minimal",
+            "low",
+            "medium",
+            "high",
+            "xhigh",
+        ]);
+        if (!thinkingChoice)
+            return;
+        let thinkingLine = "";
+        if (thinkingChoice !== "inherit")
+            thinkingLine = `\nthinking: ${thinkingChoice}`;
+        // 6. System prompt
+        const systemPrompt = await ctx.ui.editor("System prompt", "");
+        if (systemPrompt === undefined)
+            return;
+        // Build the file
+        const content = `---
+description: ${description}
+tools: ${tools}${modelLine}${thinkingLine}
+prompt_mode: replace
+---
+
+${systemPrompt}
+`;
+        mkdirSync(targetDir, { recursive: true });
+        const targetPath = join(targetDir, `${name}.md`);
+        if (existsSync(targetPath)) {
+            const overwrite = await ctx.ui.confirm("Overwrite", `${targetPath} already exists. Overwrite?`);
+            if (!overwrite)
+                return;
+        }
+        const { writeFileSync } = await import("node:fs");
+        writeFileSync(targetPath, content, "utf-8");
+        reloadCustomAgents();
+        ctx.ui.notify(`Created ${targetPath}`, "info");
+    }
+    async function showSettings(ctx) {
+        const choice = await ctx.ui.select("Settings", [
+            `Max concurrency (current: ${manager.getMaxConcurrent()})`,
+            `Default max turns (current: ${getDefaultMaxTurns()})`,
+            `Grace turns (current: ${getGraceTurns()})`,
+            `Join mode (current: ${getDefaultJoinMode()})`,
+        ]);
+        if (!choice)
+            return;
+        if (choice.startsWith("Max concurrency")) {
+            const val = await ctx.ui.input("Max concurrent background agents", String(manager.getMaxConcurrent()));
+            if (val) {
+                const n = parseInt(val, 10);
+                if (n >= 1) {
+                    manager.setMaxConcurrent(n);
+                    ctx.ui.notify(`Max concurrency set to ${n}`, "info");
+                }
+                else {
+                    ctx.ui.notify("Must be a positive integer.", "warning");
+                }
+            }
+        }
+        else if (choice.startsWith("Default max turns")) {
+            const val = await ctx.ui.input("Default max turns before wrap-up", String(getDefaultMaxTurns()));
+            if (val) {
+                const n = parseInt(val, 10);
+                if (n >= 1) {
+                    setDefaultMaxTurns(n);
+                    ctx.ui.notify(`Default max turns set to ${n}`, "info");
+                }
+                else {
+                    ctx.ui.notify("Must be a positive integer.", "warning");
+                }
+            }
+        }
+        else if (choice.startsWith("Grace turns")) {
+            const val = await ctx.ui.input("Grace turns after wrap-up steer", String(getGraceTurns()));
+            if (val) {
+                const n = parseInt(val, 10);
+                if (n >= 1) {
+                    setGraceTurns(n);
+                    ctx.ui.notify(`Grace turns set to ${n}`, "info");
+                }
+                else {
+                    ctx.ui.notify("Must be a positive integer.", "warning");
+                }
+            }
+        }
+        else if (choice.startsWith("Join mode")) {
+            const val = await ctx.ui.select("Default join mode for background agents", [
+                "smart — auto-group 2+ agents in same turn (default)",
+                "async — always notify individually",
+                "group — always group background agents",
+            ]);
+            if (val) {
+                const mode = val.split(" ")[0];
+                setDefaultJoinMode(mode);
+                ctx.ui.notify(`Default join mode set to ${mode}`, "info");
+            }
+        }
+    }
+    pi.registerCommand("agents", {
+        description: "Manage agents",
+        handler: async (_args, ctx) => { await showAgentsMenu(ctx); },
+    });
+}