whale-code 6.4.0

package/dist/cli/services/subagent.js

@@ -0,0 +1,647 @@
+/**
+ * Subagent System — Claude Code-style Task tool for spawning specialized agents
+ *
+ * Subagents run in isolated context, enabling:
+ * - Parallel exploration without polluting main context
+ * - Specialized prompts per agent type
+ * - Cost optimization (Haiku for simple tasks)
+ * - Resume capability for long-running tasks
+ */
+import { readFileSync, existsSync, writeFileSync, mkdirSync, appendFileSync } from "fs";
+import { join } from "path";
+import { homedir, tmpdir } from "os";
+import { LOCAL_TOOL_DEFINITIONS, } from "./local-tools.js";
+import { LoopDetector, estimateCostUsd } from "../../shared/agent-core.js";
+import { MODEL_MAP } from "../../shared/constants.js";
+import { loadServerToolDefinitions, } from "./server-tools.js";
+import { logSpan, generateSpanId, generateTraceId } from "./telemetry.js";
+import { loadClaudeMd, getModel } from "./agent-loop.js";
+import { getGlobalEmitter } from "./agent-events.js";
+import { getAgentDefinition } from "./agent-definitions.js";
+import { callAgentAPI, executeToolBlocks, extractTextBlocks, extractToolUseBlocks, getResponseText, yieldToEventLoop, yieldForRender, } from "./agent-worker-base.js";
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+const AGENTS_DIR = join(homedir(), ".swagmanager", "agents");
+// Claude Code pattern: subagents should be discrete tasks, not open-ended
+// Low turn limit prevents infinite loops and forces focused execution
+const MAX_TURNS = 8;
+const SUBAGENT_MAX_OUTPUT_TOKENS = 32_000; // Claude Code parity — subagents get 32K output
+// ============================================================================
+// AGENT PROMPTS — specialized per type
+// ============================================================================
+// Build agent prompt with working directory context
+function buildAgentPrompt(type, cwd) {
+    const cwdContext = `
+## Working Directory
+You are working in: ${cwd}
+All file paths should be relative to or absolute from this directory.
+IMPORTANT: Focus ONLY on files within this directory. Do not get confused by other projects.
+`;
+    // Check for custom agent definition first
+    const custom = getAgentDefinition(type);
+    if (custom)
+        return custom.prompt + cwdContext;
+    const prompts = {
+        explore: `You are an exploration agent. Your ONLY job is to quickly find specific information in the codebase, then STOP.
+
+Tools available:
+- glob: Find files by pattern (e.g., "**/*.ts")
+- grep: Search file contents with regex
+- read_file: Read file contents
+- list_directory: List directory contents
+${cwdContext}
+## STOP CONDITIONS — You MUST stop when ANY of these are met:
+1. You found the specific information requested
+2. You've searched 3+ patterns without finding anything new
+3. You've read the key files that answer the question
+4. You've exhausted reasonable search patterns
+
+## Guidelines:
+- Call multiple tools per turn — batch glob + grep + read_file in a single response
+- Read only the necessary files to answer the question
+- DO NOT continue exploring after you have the answer
+- DO NOT read files that aren't directly relevant
+
+## Output Format:
+Return a concise summary with:
+- File paths and line numbers for relevant code
+- Key code snippets (brief)
+- Direct answer to the question asked
+
+IMPORTANT: Complete in 2-4 turns. If you haven't found it by turn 4, summarize what you found and STOP.`,
+        plan: `You are a planning agent. Your ONLY job is to analyze the codebase and create an implementation plan, then STOP.
+
+Tools available:
+- glob: Find files by pattern
+- grep: Search file contents
+- read_file: Read file contents
+- list_directory: List directory contents
+${cwdContext}
+## STOP CONDITIONS — You MUST stop when:
+1. You've identified the files that need changes
+2. You've understood the existing patterns/architecture
+3. You've created a concrete plan with specific steps
+
+## Guidelines:
+- FIRST: Quick search to find relevant files
+- Read only files needed to understand the architecture
+- DO NOT read every file — focus on entry points and key modules
+- Create the plan as soon as you understand the structure
+
+## Output Format — Return EXACTLY this structure:
+### Summary
+[1-2 sentences on the approach]
+
+### Files to Modify
+- path/to/file.ts: [what changes]
+
+### Implementation Steps
+1. [Specific step]
+2. [Specific step]
+
+### Risks
+- [Any considerations]
+
+IMPORTANT: Complete in 3-5 turns. If you haven't finished by turn 5, output your best plan and STOP.`,
+        "general-purpose": `You are an autonomous agent for discrete tasks. Complete the task, then STOP.
+
+Tools available:
+- File operations: read_file, write_file, edit_file, glob, grep
+- Shell: run_command
+- Search: search_files, search_content
+- Web: web_fetch
+${cwdContext}
+## STOP CONDITIONS — You MUST stop when:
+1. The specific task is complete
+2. You've verified the changes work (if applicable)
+3. You encounter a blocker you cannot resolve
+
+## Guidelines:
+- Understand what exists before making changes
+- Make targeted changes — don't over-engineer
+- Verify your changes if possible (run tests, check syntax)
+- If blocked, explain the blocker and STOP
+
+## Output Format:
+### What I Did
+[Brief summary of actions taken]
+
+### Files Modified
+- path/to/file.ts: [change description]
+
+### Verification
+[How you verified it works, or N/A]
+
+### Issues (if any)
+[Any problems encountered]
+
+IMPORTANT: This is a discrete task. Complete it in 4-6 turns maximum. Do not loop.`,
+        research: `You are a research agent. Find the specific information requested, then STOP.
+
+Tools available:
+- web_fetch: Fetch and parse web content
+- web_search: Search the web
+- read_file: Read local files
+- grep: Search local file contents
+${cwdContext}
+## STOP CONDITIONS — You MUST stop when:
+1. You found the answer to the question
+2. You've checked 2-3 authoritative sources
+3. You've gathered enough information to answer
+
+## Guidelines:
+- Search for official documentation first
+- Check 2-3 sources, not 10
+- DO NOT keep searching after you have the answer
+- Summarize findings immediately when you have enough
+
+## Output Format:
+### Answer
+[Direct answer to the question]
+
+### Key Points
+- [Important detail 1]
+- [Important detail 2]
+
+### Sources
+- [URL 1]: [what it says]
+- [URL 2]: [what it says]
+
+### Caveats
+[Any version requirements or limitations]
+
+IMPORTANT: Complete in 2-4 turns. Stop as soon as you have a good answer.`,
+    };
+    return prompts[type] || prompts["general-purpose"];
+}
+// ============================================================================
+// AGENT STATE PERSISTENCE
+// ============================================================================
+function ensureAgentsDir() {
+    if (!existsSync(AGENTS_DIR))
+        mkdirSync(AGENTS_DIR, { recursive: true });
+}
+function saveAgentState(state) {
+    ensureAgentsDir();
+    const path = join(AGENTS_DIR, `${state.id}.json`);
+    writeFileSync(path, JSON.stringify(state, null, 2), "utf-8");
+}
+function loadAgentState(agentId) {
+    const path = join(AGENTS_DIR, `${agentId}.json`);
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+function generateAgentId() {
+    return `agent-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+// ============================================================================
+// TOOL FILTERING — restrict tools per agent type
+// ============================================================================
+function getToolsForAgent(type) {
+    // Check for custom agent definition with explicit tools
+    const custom = getAgentDefinition(type);
+    if (custom?.tools && custom.tools.length > 0)
+        return custom.tools;
+    switch (type) {
+        case "explore":
+            return ["glob", "grep", "read_file", "list_directory", "search_files", "search_content"];
+        case "plan":
+            return ["glob", "grep", "read_file", "list_directory", "search_files", "search_content"];
+        case "research":
+            return ["web_fetch", "web_search", "read_file", "grep", "glob"];
+        case "general-purpose":
+            // All tools
+            return [
+                "read_file", "write_file", "edit_file", "list_directory",
+                "search_files", "search_content", "run_command",
+                "glob", "grep", "notebook_edit", "web_fetch", "tasks",
+            ];
+        default:
+            return ["read_file", "glob", "grep"];
+    }
+}
+async function getFilteredTools(type) {
+    const allowedNames = new Set(getToolsForAgent(type));
+    // Local tools
+    const localTools = LOCAL_TOOL_DEFINITIONS
+        .filter((t) => allowedNames.has(t.name))
+        .map((t) => ({
+        name: t.name,
+        description: t.description,
+        input_schema: t.input_schema,
+    }));
+    // Add web_search from server tools if allowed
+    if (allowedNames.has("web_search")) {
+        try {
+            const serverTools = await loadServerToolDefinitions();
+            const webSearch = serverTools.find((t) => t.name === "web_search");
+            if (webSearch)
+                localTools.push(webSearch);
+        }
+        catch { /* server tools unavailable */ }
+    }
+    return localTools;
+}
+// ============================================================================
+// DISPLAY HELPERS — icons and colors for trace visualization
+// ============================================================================
+function getAgentIcon(type) {
+    const icons = {
+        explore: "🔍", // Magnifying glass for exploration
+        plan: "📋", // Clipboard for planning
+        "general-purpose": "🤖", // Robot for autonomous work
+        research: "📚", // Books for research
+    };
+    return icons[type] || "⚙️";
+}
+function getAgentColor(type) {
+    const colors = {
+        explore: "#3B82F6", // Blue for exploration
+        plan: "#8B5CF6", // Purple for planning
+        "general-purpose": "#10B981", // Green for general work
+        research: "#F59E0B", // Amber for research
+    };
+    return colors[type] || "#6B7280";
+}
+// ============================================================================
+// SUBAGENT EXECUTION
+// ============================================================================
+// Progress emitter — uses event system instead of stderr to avoid UI conflicts
+// The global emitter batches and routes these to ChatApp without causing re-renders
+// NOTE: No module-level mutable state — agentId/turn passed through function params for parallel safety
+function emitSubagentProgress(agentType, agentId, message, turn, toolName) {
+    const emitter = getGlobalEmitter();
+    emitter.emitSubagentProgress(agentId, agentType, message, turn, toolName);
+}
+export async function runSubagent(options) {
+    const { prompt, subagent_type, model, resume, max_turns, name, parentContext, parentTraceContext } = options;
+    const agentId = resume || generateAgentId();
+    // Inherit parent model when not specified (Anthropic pattern)
+    const modelId = model ? MODEL_MAP[model] : getModel();
+    const cwd = process.cwd();
+    const systemPrompt = buildAgentPrompt(subagent_type, cwd);
+    const startTime = Date.now();
+    const effectiveMaxTurns = max_turns ? Math.max(1, Math.min(50, max_turns)) : MAX_TURNS;
+    // Extract short description from prompt (first sentence or 60 chars)
+    const descMatch = prompt.match(/^[^.!?\n]+/);
+    const shortDescription = name || (descMatch
+        ? descMatch[0].slice(0, 60) + (descMatch[0].length > 60 ? "…" : "")
+        : prompt.slice(0, 60) + (prompt.length > 60 ? "…" : ""));
+    // Emit subagent start event
+    const emitter = getGlobalEmitter();
+    emitter.emitSubagentStart(agentId, subagent_type, model || "inherited", shortDescription);
+    // Load or create agent state
+    let state = resume ? loadAgentState(resume) : null;
+    if (!state) {
+        state = {
+            id: agentId,
+            type: subagent_type,
+            model: modelId,
+            messages: [],
+            toolsUsed: [],
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+        };
+    }
+    const loopDetector = new LoopDetector();
+    // Get filtered tools for this agent type
+    const tools = await getFilteredTools(subagent_type);
+    // Build full system prompt with optional parent context
+    let fullSystemPrompt = systemPrompt;
+    if (parentContext) {
+        fullSystemPrompt += `\n\n## Parent Conversation Context\n${parentContext}`;
+    }
+    // Add CLAUDE.md if available
+    const claudeMd = loadClaudeMd();
+    if (claudeMd) {
+        fullSystemPrompt += `\n\n## Project Instructions\n${claudeMd.content}`;
+    }
+    // Add user prompt to messages
+    state.messages.push({ role: "user", content: prompt });
+    let totalIn = 0;
+    let totalOut = 0;
+    let finalText = "";
+    // Create subagent span context — inherit parent's trace context for hierarchy
+    // IMPORTANT: Don't increment global turn number — subagent is part of parent turn
+    const subagentSpanId = generateSpanId();
+    const turnCtx = {
+        source: "claude_code",
+        serviceName: "whale-cli",
+        serviceVersion: "2.1.0",
+        model: modelId,
+        agentId,
+        agentName: name || `subagent-${subagent_type}`,
+        // Inherit parent's trace to keep hierarchy intact
+        traceId: parentTraceContext?.traceId || generateTraceId(),
+        spanId: subagentSpanId,
+        parentSpanId: parentTraceContext?.spanId, // Parent's spanId becomes our parentSpanId
+        conversationId: parentTraceContext?.conversationId,
+        turnNumber: parentTraceContext?.turnNumber, // Inherit parent turn, don't increment
+        userId: parentTraceContext?.userId,
+        userEmail: parentTraceContext?.userEmail,
+        traceFlags: 1,
+    };
+    try {
+        for (let turn = 0; turn < effectiveMaxTurns; turn++) {
+            // Emit progress and yield before API call to keep UI responsive
+            emitSubagentProgress(subagent_type, agentId, `turn ${turn + 1}: calling API...`, turn + 1);
+            await yieldForRender(); // Give Ink time to render the progress update
+            // Claude Code parity: thinking is DISABLED for all subagents.
+            // Subagents don't get extended thinking — all output tokens go to actual content.
+            // max_tokens = 32K matching Claude Code's hardcoded subagent default.
+            const apiStart = Date.now();
+            let response;
+            let lastError = null;
+            for (let attempt = 0; attempt < 3; attempt++) {
+                try {
+                    response = await callAgentAPI({
+                        modelId,
+                        contextProfile: "subagent",
+                        systemPrompt: fullSystemPrompt,
+                        messages: state.messages,
+                        tools,
+                        thinkingEnabled: false,
+                        maxOutputTokens: SUBAGENT_MAX_OUTPUT_TOKENS,
+                        cacheLastTool: true,
+                    });
+                    lastError = null;
+                    break;
+                }
+                catch (err) {
+                    lastError = err;
+                    if (attempt < 2 && (err.status === 429 || err.status === 500 || err.status === 529)) {
+                        await new Promise(r => setTimeout(r, 1000 * Math.pow(2, attempt)));
+                        continue;
+                    }
+                    throw err;
+                }
+            }
+            if (lastError)
+                throw lastError;
+            const apiDuration = Date.now() - apiStart;
+            // Yield after API call
+            await yieldToEventLoop();
+            totalIn += response.usage.input_tokens;
+            totalOut += response.usage.output_tokens;
+            // Log API call as child span
+            const apiCostUsd = estimateCostUsd(response.usage.input_tokens, response.usage.output_tokens, modelId);
+            logSpan({
+                action: "claude_api_request",
+                durationMs: apiDuration,
+                context: {
+                    ...turnCtx,
+                    spanId: generateSpanId(), // New span for this API call
+                    parentSpanId: turnCtx.spanId, // Parent is the subagent
+                    inputTokens: response.usage.input_tokens,
+                    outputTokens: response.usage.output_tokens,
+                    totalCost: apiCostUsd,
+                    model: modelId,
+                },
+                details: {
+                    "gen_ai.request.model": modelId,
+                    "gen_ai.usage.input_tokens": response.usage.input_tokens,
+                    "gen_ai.usage.output_tokens": response.usage.output_tokens,
+                    "gen_ai.usage.cost": apiCostUsd,
+                    agent_id: agentId,
+                    agent_type: subagent_type,
+                    turn: turn + 1,
+                    stop_reason: response.stop_reason,
+                    is_subagent_api: true,
+                },
+            });
+            // Yield to event loop to keep UI responsive
+            await yieldToEventLoop();
+            // Extract text and tool use using shared helpers
+            const textBlocks = extractTextBlocks(response.content);
+            const toolBlocks = extractToolUseBlocks(response.content);
+            if (textBlocks.length) {
+                finalText = getResponseText(response.content);
+            }
+            // No tool calls — we're done
+            if (toolBlocks.length === 0 || response.stop_reason === "end_turn") {
+                emitSubagentProgress(subagent_type, agentId, `done (${turn + 1} turn${turn > 0 ? "s" : ""})`, turn + 1);
+                break;
+            }
+            // Emit tool usage progress
+            const toolNames = toolBlocks.map(b => b.name).join(", ");
+            emitSubagentProgress(subagent_type, agentId, `using: ${toolNames}`, turn + 1);
+            // Execute tools using shared executeToolBlocks
+            const { toolResults, toolsUsed: turnToolsUsed } = await executeToolBlocks({
+                toolBlocks,
+                loopDetector,
+                callbacks: {
+                    onToolStart: (toolName, input) => {
+                        emitSubagentProgress(subagent_type, agentId, `running ${toolName}`, turn + 1, toolName);
+                        emitter.emitSubagentToolStart(agentId, toolName, input);
+                    },
+                    onToolEnd: (toolName, success, durationMs) => {
+                        emitter.emitSubagentToolEnd(agentId, toolName, success, durationMs);
+                        // Log tool call as child span of the subagent
+                        const tu = toolBlocks.find(b => b.name === toolName);
+                        logSpan({
+                            action: `tool.${toolName}`,
+                            durationMs,
+                            context: {
+                                ...turnCtx,
+                                spanId: generateSpanId(),
+                                parentSpanId: turnCtx.spanId,
+                            },
+                            error: success ? undefined : "(see tool result)",
+                            details: {
+                                tool_type: "subagent_tool",
+                                tool_input: tu?.input,
+                                agent_id: agentId,
+                                agent_type: subagent_type,
+                                is_subagent_tool: true,
+                                iteration: turn,
+                            },
+                        });
+                    },
+                },
+            });
+            // Track tool usage
+            for (const tn of turnToolsUsed) {
+                if (!state.toolsUsed.includes(tn)) {
+                    state.toolsUsed.push(tn);
+                }
+            }
+            // Append assistant response + tool results
+            state.messages.push({
+                role: "assistant",
+                content: response.content,
+            });
+            state.messages.push({
+                role: "user",
+                content: toolResults,
+            });
+            // Yield to event loop after tool execution
+            await yieldToEventLoop();
+        }
+        // Save state for potential resume
+        state.updatedAt = new Date().toISOString();
+        saveAgentState(state);
+        // Log the subagent's final response as a chat.assistant_response span
+        // This ensures the full output is visible in the telemetry waterfall
+        const subFinalCost = estimateCostUsd(totalIn, totalOut, modelId);
+        if (finalText) {
+            logSpan({
+                action: "chat.assistant_response",
+                durationMs: Date.now() - startTime,
+                context: {
+                    ...turnCtx,
+                    spanId: generateSpanId(),
+                    parentSpanId: turnCtx.spanId,
+                    inputTokens: totalIn,
+                    outputTokens: totalOut,
+                    totalCost: subFinalCost,
+                    model: modelId,
+                },
+                details: {
+                    response: finalText,
+                    agent_id: agentId,
+                    agent_name: name || `subagent-${subagent_type}`,
+                    agent_type: subagent_type,
+                    is_subagent: true,
+                    "gen_ai.request.model": modelId,
+                    "gen_ai.usage.input_tokens": totalIn,
+                    "gen_ai.usage.output_tokens": totalOut,
+                    "gen_ai.usage.cost": subFinalCost,
+                    model: modelId,
+                    input_tokens: totalIn,
+                    output_tokens: totalOut,
+                    turn_count: Math.floor(state.messages.length / 2),
+                    tool_calls: state.toolsUsed.length,
+                    tool_names: state.toolsUsed,
+                },
+            });
+        }
+        // Log telemetry with rich metadata for trace visualization
+        const subagentTotalCost = estimateCostUsd(totalIn, totalOut, modelId);
+        logSpan({
+            action: `subagent.${subagent_type}`,
+            durationMs: Date.now() - new Date(state.createdAt).getTime(),
+            context: {
+                ...turnCtx,
+                inputTokens: totalIn,
+                outputTokens: totalOut,
+                totalCost: subagentTotalCost,
+            },
+            details: {
+                // Core identification
+                agent_id: agentId,
+                agent_type: subagent_type,
+                model: modelId,
+                // Cost for SwiftUI display
+                "gen_ai.request.model": modelId,
+                "gen_ai.usage.input_tokens": totalIn,
+                "gen_ai.usage.output_tokens": totalOut,
+                "gen_ai.usage.cost": subagentTotalCost,
+                // Execution metrics
+                turns: state.messages.length / 2,
+                tools_used: state.toolsUsed,
+                tool_count: state.toolsUsed.length,
+                // Hierarchy info for visualization
+                is_subagent: true,
+                parent_trace_id: parentTraceContext?.traceId,
+                parent_span_id: parentTraceContext?.spanId,
+                // Rich display metadata
+                display_name: `${subagent_type.charAt(0).toUpperCase() + subagent_type.slice(1)} Agent`,
+                display_icon: getAgentIcon(subagent_type),
+                display_color: getAgentColor(subagent_type),
+                // Summary for trace feed (2000 chars for meaningful preview)
+                summary: finalText.slice(0, 2000) + (finalText.length > 2000 ? "..." : ""),
+                prompt_preview: prompt.slice(0, 200) + (prompt.length > 200 ? "..." : ""),
+            },
+        });
+        // Emit subagent done event
+        emitter.emitSubagentDone(agentId, subagent_type, true, finalText || "(No output from agent)", { input: totalIn, output: totalOut }, state.toolsUsed, Date.now() - startTime);
+        return {
+            success: true,
+            output: finalText || "(No output from agent)",
+            agentId,
+            tokensUsed: { input: totalIn, output: totalOut },
+            toolsUsed: state.toolsUsed,
+        };
+    }
+    catch (err) {
+        // Emit subagent error event
+        emitter.emitSubagentDone(agentId, subagent_type, false, `Agent error: ${err.message || err}`, { input: totalIn, output: totalOut }, state.toolsUsed, Date.now() - startTime);
+        return {
+            success: false,
+            output: `Agent error: ${err.message || err}`,
+            agentId,
+            tokensUsed: { input: totalIn, output: totalOut },
+            toolsUsed: state.toolsUsed,
+        };
+    }
+}
+// ============================================================================
+// BACKGROUND AGENT EXECUTION
+// ============================================================================
+export async function runSubagentBackground(options) {
+    const agentId = options.resume || generateAgentId();
+    const outputFile = join(tmpdir(), `whale-agent-${agentId}.output`);
+    // Write initial status
+    writeFileSync(outputFile, `Agent ${agentId} started (${options.subagent_type})\n`, "utf-8");
+    // Import background process tracker (dynamic to avoid circular deps)
+    const bgModule = await import("./background-processes.js");
+    bgModule.registerBackgroundAgent(agentId, options.subagent_type, outputFile);
+    // Start agent in detached async — don't await
+    runSubagent({ ...options, resume: undefined }).then(result => {
+        appendFileSync(outputFile, `\n---DONE---\n${JSON.stringify({ success: result.success, agentId: result.agentId, output: result.output })}\n`, "utf-8");
+        import("./background-processes.js").then(m => m.markAgentDone(agentId, result.success));
+    }).catch(err => {
+        appendFileSync(outputFile, `\n---ERROR---\n${err.message}\n`, "utf-8");
+        import("./background-processes.js").then(m => m.markAgentDone(agentId, false));
+    });
+    return { agentId, outputFile };
+}
+// ============================================================================
+// TOOL DEFINITION — for integration with main agent loop
+// ============================================================================
+// Following Claude Code pattern: discrete, focused tasks with clear completion criteria
+export const TASK_TOOL_DEFINITION = {
+    name: "task",
+    description: `Launch a subagent in isolated context. Subagents have full tool access and batch multiple tool calls per turn (glob + grep + read_file in parallel). Launch multiple task calls in one response for parallel execution.
+
+Use for any work requiring 3+ tool calls or touching multiple parts of the codebase.
+
+Agent types:
+- explore: Find specific files/code (2-4 turns, uses batch glob+grep)
+- plan: Create implementation plan (3-5 turns)
+- general-purpose: Complete a specific task (4-8 turns, full tool access)
+- research: Look up specific info (2-4 turns)
+
+Each agent completes autonomously and returns results.`,
+    input_schema: {
+        type: "object",
+        properties: {
+            prompt: {
+                type: "string",
+                description: "Specific task with clear completion criteria. Include: what to find/do, where to look, what to return.",
+            },
+            subagent_type: {
+                type: "string",
+                enum: ["explore", "plan", "general-purpose", "research"],
+                description: "Agent type: explore=find, plan=design, general-purpose=do, research=lookup.",
+            },
+            model: {
+                type: "string",
+                enum: ["sonnet", "opus", "haiku"],
+                description: "Optional model override. If not specified, inherits from parent. Prefer haiku for quick, straightforward tasks to minimize cost and latency.",
+            },
+            resume: {
+                type: "string",
+                description: "Agent ID to resume (rarely needed).",
+            },
+        },
+        required: ["prompt", "subagent_type"],
+    },
+};

package/dist/cli/services/system-prompt.d.ts

@@ -0,0 +1,7 @@
+/**
+ * System Prompt Builder — assembles the full system prompt for the agent loop
+ *
+ * Extracted from agent-loop.ts for single-responsibility.
+ * All consumers should import from agent-loop.ts (re-export facade).
+ */
+export declare function buildSystemPrompt(hasServerTools: boolean, effort?: "low" | "medium" | "high"): Promise<string>;