@bubblebrain-ai/bubble 0.0.4 → 0.0.6

package/dist/agent.js

@@ -3,6 +3,7 @@
  * It maintains message state, calls the LLM, executes tools, and auto-continues.
  */
 import { compactMessages } from "./context/compact.js";
+import { randomUUID } from "node:crypto";
 import { compactMessagesWithLLM } from "./context/compact-llm.js";
 import { getContextBudget } from "./context/budget.js";
 import { isContextOverflowError } from "./context/overflow.js";
@@ -11,7 +12,12 @@ import { aggressivePruneMessages } from "./context/prune.js";
 import { buildDeferredToolsReminder, buildToolFreezeReminder, isPermissionModeReminder, reminderForMode } from "./prompt/reminders.js";
 import { HookBus } from "./orchestrator/hooks.js";
 import { createDefaultHooks } from "./orchestrator/default-hooks.js";
-import { filterToolsForSubtask, getSubtaskPolicy } from "./agent/subtask-policy.js";
+import { getSubtaskPolicy } from "./agent/subtask-policy.js";
+import { composeAbortSignals } from "./agent/budget-ledger.js";
+import { assignAgentNickname, builtinAgentProfiles, mergeUsage, selectToolsForAgentProfile, validateAgentProfileTools } from "./agent/profiles.js";
+import { snapshotSubagentThread, subagentResultFromThread } from "./agent/subagent-control.js";
+import { buildSystemPrompt } from "./system-prompt.js";
+import { isOnlyProviderProtocolArtifacts, stripProviderProtocolArtifacts } from "./provider-artifacts.js";
 const MAX_CONSECUTIVE_OVERFLOW_RECOVERIES = 3;
 const RESIDENT_HISTORY_KEEP_RECENT_TURNS = 3;
 const RESIDENT_HISTORY_MESSAGE_LIMIT = 160;
@@ -46,6 +52,12 @@ export class Agent {
     hookDefinitions;
     maxTurns;
     taskBudget;
+    budgetLedger;
+    budgetSource;
+    skillSummaries;
+    memoryPrompt;
+    subagentThreads = new Map();
+    pendingSubagentUpdates = [];
     lastInputTokens = null;
     lastAnchorMessageCount = null;
     constructor(options) {
@@ -64,6 +76,10 @@ export class Agent {
         this.hookDefinitions = options.hooks ?? [];
         this.maxTurns = options.maxTurns ?? options.steps;
         this.taskBudget = options.taskBudget;
+        this.budgetLedger = options.budgetLedger;
+        this.budgetSource = options.budgetSource ?? { runId: this.sessionID ?? "agent" };
+        this.skillSummaries = options.skills ?? [];
+        this.memoryPrompt = options.memoryPrompt;
         if (options.systemPrompt) {
             this.messages.push({ role: "system", content: options.systemPrompt });
         }
@@ -101,11 +117,11 @@ export class Agent {
         return !!tool?.deferred && !this.unlockedDeferred.has(name);
     }
     injectSystemReminder(content) {
-        this.appendMessage({ role: "user", content, isMeta: true });
+        this.appendMessage({ role: "meta", kind: "system-reminder", content });
     }
     injectModeReminder() {
-        this.messages = this.messages.filter((message) => !(message.role === "user"
-            && message.isMeta
+        this.messages = this.messages.filter((message) => !(message.role === "meta"
+            && message.kind === "system-reminder"
             && isPermissionModeReminder(message.content)));
         this.injectSystemReminder(reminderForMode(this._mode));
     }
@@ -131,7 +147,7 @@ export class Agent {
         this.provider = provider;
     }
     complete(messages, options) {
-        return this.provider.complete(messages, {
+        return this.provider.complete(projectMessages(messages), {
             model: options?.model ?? this.apiModel,
             temperature: options?.temperature ?? this.temperature,
             thinkingLevel: options?.thinkingLevel ?? this.thinkingLevel,
@@ -189,7 +205,7 @@ export class Agent {
         this.messages.unshift(systemMessage);
     }
     async *run(userInput, cwd, options = {}) {
-        const abortSignal = options.abortSignal;
+        const abortSignal = composeAbortSignals([options.abortSignal, this.budgetLedger?.signal]);
         throwIfAborted(abortSignal);
         const hookBus = new HookBus();
         for (const hooks of createDefaultHooks()) {
@@ -227,6 +243,8 @@ export class Agent {
         while (true) {
             throwIfAborted(abortSignal);
             flushGovernorReminders();
+            for (const update of this.drainSubagentToolUpdates())
+                yield update;
             yield { type: "turn_start" };
             step += 1;
             hookState.turnCount = step;
@@ -250,7 +268,7 @@ export class Agent {
                 reasoning: "",
                 toolCalls: [],
             };
-            let currentToolCall = null;
+            const streamingToolCalls = new Map();
             let turnUsage;
             let assistantAppended = false;
             let toolEntries = Array.from(this.tools.values())
@@ -307,22 +325,51 @@ export class Agent {
                             break;
                         case "tool_call":
                             if (chunk.isStart) {
-                                currentToolCall = { id: chunk.id, name: chunk.name, args: "" };
+                                streamingToolCalls.set(chunk.id, { id: chunk.id, name: chunk.name, args: "" });
+                                yield { type: "tool_call_start", id: chunk.id, name: chunk.name };
                             }
+                            if (!streamingToolCalls.has(chunk.id)) {
+                                streamingToolCalls.set(chunk.id, { id: chunk.id, name: chunk.name, args: "" });
+                            }
+                            const currentToolCall = streamingToolCalls.get(chunk.id);
                             if (currentToolCall) {
+                                currentToolCall.name = chunk.name || currentToolCall.name;
                                 currentToolCall.args += chunk.arguments;
+                                if (chunk.argumentsFull !== undefined) {
+                                    currentToolCall.args = chunk.argumentsFull;
+                                }
+                                if (chunk.argumentsCorrupt) {
+                                    currentToolCall.argsCorrupt = true;
+                                }
+                                if (chunk.arguments) {
+                                    yield {
+                                        type: "tool_call_delta",
+                                        id: currentToolCall.id,
+                                        name: currentToolCall.name,
+                                        argumentsDelta: chunk.arguments,
+                                        arguments: currentToolCall.args,
+                                    };
+                                }
                             }
                             if (chunk.isEnd && currentToolCall) {
                                 assistantMsg.toolCalls.push({
                                     id: currentToolCall.id,
                                     name: currentToolCall.name,
                                     arguments: currentToolCall.args,
+                                    ...(currentToolCall.argsCorrupt ? { argsCorrupt: true } : {}),
                                 });
-                                currentToolCall = null;
+                                yield {
+                                    type: "tool_call_end",
+                                    id: currentToolCall.id,
+                                    name: currentToolCall.name,
+                                    arguments: currentToolCall.args,
+                                };
+                                streamingToolCalls.delete(chunk.id);
                             }
                             break;
                         case "usage":
                             turnUsage = chunk.usage;
+                            this.budgetLedger?.recordUsage(chunk.usage, this.budgetSource);
                             this.lastInputTokens = chunk.usage.promptTokens;
                             this.lastAnchorMessageCount = this.messages.length;
                             if (hookState.taskBudget) {
@@ -333,7 +380,10 @@ export class Agent {
                             }
                             break;
                     }
+                    for (const update of this.drainSubagentToolUpdates())
+                        yield update;
                 }
+                throwIfAborted(abortSignal);
                 this.appendMessage(assistantMsg);
                 assistantAppended = true;
             }
@@ -359,10 +409,14 @@ export class Agent {
                 for (let index = 0; index < assistantMsg.toolCalls.length; index++) {
                     const tc = assistantMsg.toolCalls[index];
                     try {
-                        parsedCalls.push({ ...tc, parsedArgs: JSON.parse(tc.arguments) });
+                        parsedCalls.push({
+                            ...tc,
+                            parsedArgs: JSON.parse(tc.arguments),
+                            ...(tc.argsCorrupt ? { argsCorrupt: true } : {}),
+                        });
                     }
                     catch {
-                        parsedCalls.push({ ...tc, parsedArgs: {} });
+                        parsedCalls.push({ ...tc, parsedArgs: {}, argsCorrupt: true });
                     }
                 }
                 const executedResults = [];
@@ -395,7 +449,41 @@ export class Agent {
                     yield { type: "tool_start", id: tc.id, name: tc.name, args: tc.parsedArgs };
                     const todosVersionBefore = this._todosVersion;
                     const modeVersionBefore = this._modeVersion;
-                    let result = blockedResult ?? await this.executeTool(tc, cwd, abortSignal);
+                    const updateQueue = createUpdateQueue();
+                    let result;
+                    if (blockedResult) {
+                        result = blockedResult;
+                    }
+                    else {
+                        const toolExecution = this.executeTool(tc, cwd, abortSignal, (update) => updateQueue.push(update));
+                        let settled = false;
+                        let resolved;
+                        let rejected;
+                        void toolExecution
+                            .then((value) => {
+                            resolved = value;
+                        })
+                            .catch((error) => {
+                            rejected = error;
+                        })
+                            .finally(() => {
+                            settled = true;
+                            updateQueue.wake();
+                        });
+                        while (!settled || updateQueue.hasItems()) {
+                            for (const update of updateQueue.drain()) {
+                                yield { type: "tool_update", id: tc.id, name: tc.name, update };
+                            }
+                            for (const update of this.drainSubagentToolUpdates())
+                                yield update;
+                            if (!settled) {
+                                await updateQueue.wait();
+                            }
+                        }
+                        if (rejected)
+                            throw rejected;
+                        result = resolved ?? { content: `Error: Tool "${tc.name}" returned no result`, isError: true };
+                    }
                     throwIfAborted(abortSignal);
                     await hookBus.runAfterToolCall({
                         agent: this,
@@ -422,6 +510,8 @@ export class Agent {
                     this.onToolResult?.(tc.name, result);
                     executedResults.push(result);
                     yield { type: "tool_end", id: tc.id, name: tc.name, result };
+                    for (const update of this.drainSubagentToolUpdates())
+                        yield update;
                     if (this._todosVersion !== todosVersionBefore) {
                         yield { type: "todos_updated", todos: this.getTodos() };
                     }
@@ -466,6 +556,8 @@ export class Agent {
             }
             break;
         }
+        for (const update of this.drainSubagentToolUpdates())
+            yield update;
         yield { type: "agent_end" };
     }
     async recoverFromOverflow(attempt) {
@@ -507,62 +599,424 @@ export class Agent {
     }
     async runSubtask(input, cwd, options) {
         const subtaskType = options?.subtaskType;
-        const policy = getSubtaskPolicy(subtaskType);
-        const tools = filterToolsForSubtask([...this.tools.values()].filter((tool) => tool.name !== "task"), subtaskType);
+        const profile = builtinAgentProfiles().find((item) => item.subtaskType === (subtaskType ?? "general_readonly"))
+            ?? builtinAgentProfiles().find((item) => item.subtaskType === "general_readonly");
+        const run = await this.runSubAgent(input, cwd, {
+            profile,
+            runId: randomUUID(),
+            subAgentId: randomUUID(),
+            parentToolCallId: "task",
+            description: options?.description,
+        });
+        const lines = [
+            "Note: task is deprecated. Use spawn_agent with a named profile instead.",
+            `Subtask type: ${profile.subtaskType ?? "general_readonly"}`,
+        ];
+        if (options?.description) {
+            lines.push(`Subtask description: ${options.description}`);
+        }
+        if (run.summary) {
+            lines.push("", "Subtask summary:", run.summary);
+        }
+        if (run.toolNotes.length > 0) {
+            lines.push("", "Subtask tools:", ...run.toolNotes.slice(0, 8).map((note) => `- ${note}`));
+        }
+        return {
+            content: lines.join("\n"),
+            status: getSubtaskPolicy(subtaskType).resultStatus,
+            isError: run.status !== "completed",
+            metadata: {
+                kind: "subagent",
+                reason: `Subtask (${profile.subtaskType ?? "general_readonly"}) investigation completed.`,
+                subagents: [run],
+            },
+        };
+    }
+    async runSubAgent(input, cwd, options) {
+        const record = this.createSubagentThreadRecord({
+            profile: options.profile,
+            task: typeof input === "string" ? input : "(multimodal task)",
+            runId: options.runId,
+            agentId: options.subAgentId,
+            parentToolCallId: options.parentToolCallId,
+            parentToolName: "subagent",
+            nickname: options.nickname,
+        });
+        await this.runSubagentThread(record, input, cwd, {
+            approval: options.approval ?? options.profile.approval,
+            abortSignal: options.abortSignal,
+            forkContext: options.forkContext,
+            directEmit: options.emitUpdate,
+        });
+        return subagentResultFromThread(record);
+    }
+    async spawnSubAgent(input, cwd, options) {
+        const record = this.createSubagentThreadRecord({
+            profile: options.profile,
+            task: typeof input === "string" ? input : "(multimodal task)",
+            parentToolCallId: options.parentToolCallId,
+            parentToolName: "spawn_agent",
+        });
+        this.subagentThreads.set(record.agentId, record);
+        this.queueSubagentUpdate(record, "queued", undefined, `Queued ${record.nickname} (${record.profile.name})`);
+        record.promise = this.runSubagentThread(record, input, cwd, {
+            approval: options.approval ?? record.profile.approval,
+            abortSignal: options.abortSignal,
+            forkContext: options.forkContext,
+            queueUpdates: true,
+        });
+        void record.promise.finally(() => this.notifySubagentWaiters(record));
+        return snapshotSubagentThread(record);
+    }
+    async waitSubAgents(options = {}) {
+        const targets = this.resolveSubagentTargets(options.agentIds);
+        if (targets.length === 0)
+            return [];
+        const completed = targets.filter((record) => isFinalSubagentStatus(record.status));
+        if (completed.length > 0)
+            return completed.map(snapshotSubagentThread);
+        const timeoutMs = normalizeWaitTimeout(options.timeoutMs);
+        let waiter;
+        await Promise.race([
+            new Promise((resolve) => {
+                waiter = resolve;
+                for (const record of targets) {
+                    record.waiters.add(resolve);
+                }
+            }).finally(() => {
+                if (waiter) {
+                    for (const record of targets) {
+                        record.waiters.delete(waiter);
+                    }
+                }
+            }),
+            new Promise((resolve) => setTimeout(resolve, timeoutMs)),
+        ]);
+        const finished = targets.filter((record) => isFinalSubagentStatus(record.status));
+        return (finished.length > 0 ? finished : targets).map(snapshotSubagentThread);
+    }
+    async sendSubAgentInput(agentId, input, cwd, options = {}) {
+        const record = this.subagentThreads.get(agentId);
+        if (!record) {
+            throw new Error(`Unknown subagent: ${agentId}`);
+        }
+        if (record.status === "running" || record.status === "queued") {
+            if (!options.interrupt) {
+                throw new Error(`Subagent ${agentId} is still running. Call wait_agent first or pass interrupt:true.`);
+            }
+            record.abortController.abort(new AgentAbortError(`Subagent ${agentId} interrupted.`));
+            await record.promise?.catch(() => undefined);
+            record.abortController = new AbortController();
+        }
+        if (record.status === "closed") {
+            throw new Error(`Subagent ${agentId} is closed.`);
+        }
+        record.parentToolCallId = options.parentToolCallId ?? record.parentToolCallId;
+        record.parentToolName = "send_input";
+        record.task = typeof input === "string" ? input : "(multimodal task)";
+        record.summary = "";
+        record.toolNotes = [];
+        record.usage = undefined;
+        record.error = undefined;
+        record.updatedAt = Date.now();
+        record.promise = this.runSubagentThread(record, input, cwd, {
+            approval: record.profile.approval,
+            abortSignal: options.abortSignal,
+            queueUpdates: true,
+            reuseAgent: true,
+        });
+        void record.promise.finally(() => this.notifySubagentWaiters(record));
+        return snapshotSubagentThread(record);
+    }
+    async closeSubAgent(agentId) {
+        const record = this.subagentThreads.get(agentId);
+        if (!record) {
+            throw new Error(`Unknown subagent: ${agentId}`);
+        }
+        if (!isFinalSubagentStatus(record.status)) {
+            record.abortController.abort(new AgentAbortError(`Subagent ${agentId} closed.`));
+            await record.promise?.catch(() => undefined);
+        }
+        record.status = "closed";
+        record.updatedAt = Date.now();
+        this.queueSubagentUpdate(record, "cancelled", undefined, `${record.nickname} closed`);
+        this.notifySubagentWaiters(record);
+        return snapshotSubagentThread(record);
+    }
+    listSubAgents() {
+        return [...this.subagentThreads.values()].map(snapshotSubagentThread);
+    }
+    createSubagentThreadRecord(options) {
+        const now = Date.now();
+        const nickname = options.nickname ?? assignAgentNickname(options.profile, this.activeSubagentNicknames());
+        return {
+            agentId: options.agentId ?? randomUUID(),
+            runId: options.runId ?? randomUUID(),
+            nickname,
+            profile: options.profile,
+            parentToolCallId: options.parentToolCallId,
+            parentToolName: options.parentToolName,
+            status: "queued",
+            task: options.task,
+            summary: "",
+            toolNotes: [],
+            createdAt: now,
+            updatedAt: now,
+            abortController: new AbortController(),
+            waiters: new Set(),
+        };
+    }
+    async runSubagentThread(record, input, cwd, options) {
+        const emit = (status, event, message) => {
+            const update = this.buildSubagentUpdate(record, status, event, message);
+            options.directEmit?.(update);
+            if (options.queueUpdates) {
+                this.pendingSubagentUpdates.push({ id: record.parentToolCallId, name: record.parentToolName, update });
+            }
+        };
+        const allTools = [...this.tools.values()];
+        const diagnostics = validateAgentProfileTools(allTools, record.profile, options.approval);
+        const blockingDiagnostics = diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+        for (const diagnostic of diagnostics.filter((item) => item.severity === "warning")) {
+            record.toolNotes.push(`profile: ${diagnostic.message}`);
+        }
+        if (blockingDiagnostics.length > 0) {
+            record.status = "blocked";
+            record.error = blockingDiagnostics.map((diagnostic) => diagnostic.message).join("\n");
+            record.updatedAt = Date.now();
+            emit("blocked", undefined, record.error);
+            this.notifySubagentWaiters(record);
+            return;
+        }
+        const tools = selectToolsForAgentProfile(allTools, record.profile, options.approval);
+        const subAgent = options.reuseAgent && record.agent
+            ? record.agent
+            : this.createSubAgentInstance(record, tools, cwd, options.forkContext);
+        record.agent = subAgent;
+        record.status = "running";
+        record.updatedAt = Date.now();
+        emit("running", undefined, `Running ${record.nickname} (${record.profile.name})...`);
+        let turnSummaryBuffer = "";
+        let turnHadToolCall = false;
+        let executedAnyTool = false;
+        try {
+            const childAbortSignal = composeAbortSignals([
+                options.abortSignal,
+                record.abortController.signal,
+            ]);
+            for await (const event of subAgent.run(input, cwd, { abortSignal: childAbortSignal })) {
+                if (event.type === "text_delta") {
+                    turnSummaryBuffer += event.content;
+                }
+                if (event.type === "tool_call_start"
+                    || event.type === "tool_call_delta"
+                    || event.type === "tool_call_end"
+                    || event.type === "tool_start") {
+                    turnHadToolCall = true;
+                }
+                if (event.type === "tool_end") {
+                    executedAnyTool = true;
+                    record.toolNotes.push(`${event.name}: ${summarizeSubagentToolEnd(event)}`);
+                }
+                if (event.type === "turn_end" && event.usage) {
+                    record.usage = mergeUsage(record.usage, event.usage);
+                }
+                if (event.type === "turn_end") {
+                    const turnSummary = stripProviderProtocolArtifacts(turnSummaryBuffer).trim();
+                    if (!turnHadToolCall && turnSummary) {
+                        // Only the latest tool-free assistant turn is a candidate for the summary;
+                        // earlier ones are intermediate "I'll do X next" reasoning, not the final answer.
+                        record.summary = turnSummary;
+                    }
+                    turnSummaryBuffer = "";
+                    turnHadToolCall = false;
+                }
+                record.updatedAt = Date.now();
+                emit("running", event);
+            }
+        }
+        catch (error) {
+            const cancelled = error instanceof AgentAbortError || error?.name === "AbortError";
+            record.status = cancelled ? "cancelled" : "failed";
+            record.summary = sanitizeSubagentSummary(record.summary);
+            record.error = error?.message || String(error);
+            record.updatedAt = Date.now();
+            emit(record.status, undefined, record.error);
+            this.notifySubagentWaiters(record);
+            return;
+        }
+        record.summary = sanitizeSubagentSummary(record.summary);
+        if (needsExplicitFinalSummary(record, executedAnyTool)) {
+            await this.runSubagentFinalSummaryTurn(record, subAgent, cwd, options.abortSignal, emit);
+        }
+        record.status = "completed";
+        record.summary = sanitizeSubagentSummary(record.summary);
+        record.updatedAt = Date.now();
+        emit("completed", undefined, record.summary || `${record.nickname} completed`);
+        this.notifySubagentWaiters(record);
+    }
+    async runSubagentFinalSummaryTurn(record, subAgent, cwd, abortSignal, emit) {
+        const prompt = [
+            "Produce the final subagent summary now.",
+            "Do not call tools. Do not announce next steps or plans.",
+            "Use the evidence already gathered in this child thread.",
+            "Return concise findings with concrete file paths and explicit uncertainty.",
+            "Your entire response will be returned to the parent as the subagent's answer.",
+        ].join("\n");
+        subAgent.injectSystemReminder([
+            "Subagent final-summary mode is active.",
+            "Do not call tools. Do not announce next steps.",
+            "Use only the evidence already gathered in this child thread.",
+            "Return the final concise summary as your complete response.",
+        ].join("\n"));
+        let finalBuffer = "";
+        let finalHadToolCall = false;
+        const finalAbortSignal = composeAbortSignals([abortSignal, record.abortController.signal]);
+        for await (const event of subAgent.run(prompt, cwd, { abortSignal: finalAbortSignal })) {
+            if (event.type === "text_delta") {
+                finalBuffer += event.content;
+            }
+            if (event.type === "tool_call_start"
+                || event.type === "tool_call_delta"
+                || event.type === "tool_call_end"
+                || event.type === "tool_start") {
+                finalHadToolCall = true;
+            }
+            if (event.type === "turn_end" && event.usage) {
+                record.usage = mergeUsage(record.usage, event.usage);
+            }
+            emit("running", event);
+        }
+        const finalSummary = sanitizeSubagentSummary(finalBuffer);
+        if (!finalHadToolCall && finalSummary) {
+            record.summary = finalSummary;
+        }
+    }
+    createSubAgentInstance(record, tools, cwd, forkContext) {
+        const childToolNames = tools.map((tool) => tool.name);
+        const childSystemPrompt = buildSystemPrompt({
+            agentName: "Bubble",
+            configuredProvider: this.providerId || "none",
+            configuredModel: this.model || "none",
+            configuredModelId: this.model || "none",
+            thinkingLevel: this.thinkingLevel,
+            mode: "plan",
+            workingDir: cwd,
+            tools: childToolNames,
+            skills: childToolNames.includes("skill") ? this.skillSummaries : undefined,
+            memoryPrompt: childToolNames.some((name) => name === "memory_search" || name === "memory_read_summary")
+                ? this.memoryPrompt
+                : undefined,
+            agentProfilePrompt: [
+                `You are subagent ${record.nickname}. Your agent profile is ${record.profile.name}.`,
+                record.profile.prompt,
+            ].filter(Boolean).join("\n\n"),
+        });
         const subAgent = new Agent({
             provider: this.provider,
             providerId: this.providerId,
-            model: this.model,
+            model: record.profile.model && record.profile.model !== "inherit" ? record.profile.model : this.model,
             tools,
             temperature: this.temperature,
             thinkingLevel: this.thinkingLevel,
             mode: "plan",
-            maxTurns: policy.maxTurns,
-            taskBudget: policy.taskBudget,
-            systemPrompt: this.messages.find((message) => message.role === "system")?.content,
+            maxTurns: record.profile.maxTurns,
+            budgetLedger: this.budgetLedger,
+            budgetSource: { runId: record.runId, subAgentId: record.agentId },
+            systemPrompt: childSystemPrompt,
             hooks: this.hookDefinitions,
         });
-        subAgent.injectSystemReminder(`<system-reminder>\n${policy.reminder}\n</system-reminder>`);
-        let summary = "";
-        const toolNotes = [];
-        for await (const event of subAgent.run(input, cwd)) {
-            if (event.type === "text_delta") {
-                summary += event.content;
-            }
-            if (event.type === "tool_end") {
-                const detail = event.result.metadata?.reason
-                    || event.result.content.split("\n").find((line) => line.trim())?.trim()
-                    || "completed";
-                toolNotes.push(`${event.name}: ${detail}`);
-            }
-        }
-        const lines = [];
-        const trimmedSummary = summary.trim();
-        lines.push(`Subtask type: ${policy.type}`);
-        if (options?.description) {
-            lines.push(`Subtask description: ${options.description}`);
+        if (forkContext) {
+            subAgent.messages = this.forkMessagesForSubagent(childSystemPrompt);
         }
-        if (trimmedSummary) {
-            lines.push("", "Subtask summary:", trimmedSummary);
-        }
-        if (toolNotes.length > 0) {
-            lines.push("", "Subtask tools:");
-            for (const note of toolNotes.slice(0, 8)) {
-                lines.push(`- ${note}`);
+        return subAgent;
+    }
+    forkMessagesForSubagent(childSystemPrompt) {
+        const forked = this.messages
+            .filter((message) => {
+            if (message.role === "system" || message.role === "meta")
+                return false;
+            if (message.role === "assistant" && message.toolCalls?.some((call) => isSubagentLifecycleTool(call.name))) {
+                return false;
             }
-        }
-        if (lines.length === 0) {
-            lines.push("Subtask summary:", "No conclusive findings were produced.");
-        }
+            if (message.role === "tool" && message.metadata?.kind === "subagent") {
+                return false;
+            }
+            return true;
+        })
+            .slice(-20);
+        return [{ role: "system", content: childSystemPrompt }, ...forked];
+    }
+    buildSubagentUpdate(record, status, event, message) {
         return {
-            content: lines.join("\n"),
-            status: policy.resultStatus,
+            type: "subagent_update",
+            parentToolCallId: record.parentToolCallId,
+            runId: record.runId,
+            subAgentId: record.agentId,
+            agentName: record.profile.name,
+            nickname: record.nickname,
+            status,
+            childEvent: event,
+            summaryDelta: event?.type === "text_delta" ? event.content : undefined,
+            toolName: "name" in (event ?? {}) ? event.name : undefined,
+            toolCallId: "id" in (event ?? {}) ? event.id : undefined,
+            message,
             metadata: {
-                kind: "security",
-                reason: `Subtask (${policy.type}) investigation completed.`,
+                kind: "subagent",
+                runId: record.runId,
+                subagents: [{
+                        subAgentId: record.agentId,
+                        agentName: record.profile.name,
+                        nickname: record.nickname,
+                        status,
+                        profileSource: record.profile.source,
+                        task: record.task,
+                        summary: record.summary,
+                        toolNotes: record.toolNotes,
+                        usage: record.usage,
+                        error: record.error,
+                    }],
             },
         };
     }
+    queueSubagentUpdate(record, status, event, message) {
+        this.pendingSubagentUpdates.push({
+            id: record.parentToolCallId,
+            name: record.parentToolName,
+            update: this.buildSubagentUpdate(record, status, event, message),
+        });
+    }
+    drainSubagentToolUpdates() {
+        return this.pendingSubagentUpdates.splice(0, this.pendingSubagentUpdates.length)
+            .map((pending) => ({
+            type: "tool_update",
+            id: pending.id,
+            name: pending.name,
+            update: pending.update,
+        }));
+    }
+    activeSubagentNicknames() {
+        return [...this.subagentThreads.values()]
+            .filter((record) => !isFinalSubagentStatus(record.status))
+            .map((record) => record.nickname);
+    }
+    resolveSubagentTargets(agentIds) {
+        if (!agentIds || agentIds.length === 0) {
+            return [...this.subagentThreads.values()].filter((record) => record.status !== "closed");
+        }
+        return agentIds.map((id) => {
+            const record = this.subagentThreads.get(id);
+            if (!record) {
+                throw new Error(`Unknown subagent: ${id}`);
+            }
+            return record;
+        });
+    }
+    notifySubagentWaiters(record) {
+        for (const waiter of record.waiters) {
+            waiter();
+        }
+    }
     maybeCompactResidentHistory() {
         if (this.messages.length === 0) {
             return;
@@ -608,7 +1062,7 @@ export class Agent {
         this.messages.push(message);
         this.onMessageAppend?.(message);
     }
-    async executeTool(toolCall, cwd, abortSignal) {
+    async executeTool(toolCall, cwd, abortSignal, emitUpdate) {
         throwIfAborted(abortSignal);
         if (toolCall.name === "exit_plan_mode" && this._mode !== "plan") {
             return {
@@ -626,7 +1080,7 @@ export class Agent {
         if (this._mode === "plan" && !tool.readOnly) {
             return {
                 content: `Error: Tool "${toolCall.name}" is not allowed in plan mode. ` +
-                    `In plan mode you may only use read-only tools (read, glob, grep, lsp, web_search, web_fetch, task, skill, todo_write, tool_search, question, exit_plan_mode). ` +
+                    `In plan mode you may only use read-only tools (read, glob, grep, lsp, web_search, web_fetch, spawn_agent, wait_agent, send_input, close_agent, skill, todo_write, tool_search, question, exit_plan_mode). ` +
                     `To modify files or run commands, present your proposal and call exit_plan_mode so the user can review and approve it.`,
                 isError: true,
             };
@@ -638,6 +1092,25 @@ export class Agent {
                 isError: true,
             };
         }
+        if (toolCall.argsCorrupt) {
+            return {
+                content: `Error: The arguments for "${toolCall.name}" failed to parse as JSON, indicating the tool call was truncated or malformed mid-stream. ` +
+                    `Re-issue the call with valid JSON arguments; do not assume the previous attempt ran.`,
+                isError: true,
+                status: "blocked",
+                metadata: { kind: "security", reason: "args_corrupt" },
+            };
+        }
+        const missingRequired = findMissingRequiredArgs(tool.parameters, toolCall.parsedArgs);
+        if (missingRequired.length > 0) {
+            return {
+                content: `Error: Tool "${toolCall.name}" was called without required argument${missingRequired.length === 1 ? "" : "s"}: ${missingRequired.map((name) => `"${name}"`).join(", ")}. ` +
+                    `Re-issue the call with all required fields filled. Do not assume the previous attempt ran with default values.`,
+                isError: true,
+                status: "blocked",
+                metadata: { kind: "security", reason: "missing_required_args", missing: missingRequired },
+            };
+        }
         try {
             return await tool.execute(toolCall.parsedArgs, {
                 cwd,
@@ -645,6 +1118,7 @@ export class Agent {
                 abortSignal,
                 toolCall: { id: toolCall.id, name: toolCall.name },
                 agent: this,
+                emitUpdate,
             });
         }
         catch (err) {
@@ -655,11 +1129,29 @@ export class Agent {
         }
     }
 }
+function findMissingRequiredArgs(schema, args) {
+    const required = schema?.required;
+    if (!required || required.length === 0)
+        return [];
+    const missing = [];
+    for (const name of required) {
+        const value = args ? args[name] : undefined;
+        // Empty strings/arrays are intentionally allowed — writing an empty file
+        // or passing an empty list can be legitimate. Only undefined/null counts
+        // as "missing", because the observed failure mode is `finalArgs: "{}"`
+        // where the field is entirely absent.
+        if (value === undefined || value === null) {
+            missing.push(name);
+        }
+    }
+    return missing;
+}
 function estimateResidentChars(messages) {
     let total = 0;
     for (const message of messages) {
         switch (message.role) {
             case "system":
+            case "meta":
                 total += message.content.length;
                 break;
             case "tool":
@@ -694,6 +1186,34 @@ function throwIfAborted(signal) {
         throw reason;
     throw new AgentAbortError(typeof reason === "string" ? reason : undefined);
 }
+function createUpdateQueue() {
+    const items = [];
+    let waiter;
+    return {
+        push(item) {
+            items.push(item);
+            this.wake();
+        },
+        drain() {
+            return items.splice(0, items.length);
+        },
+        hasItems() {
+            return items.length > 0;
+        },
+        wait() {
+            if (items.length > 0)
+                return Promise.resolve();
+            return new Promise((resolve) => {
+                waiter = resolve;
+            });
+        },
+        wake() {
+            const resolve = waiter;
+            waiter = undefined;
+            resolve?.();
+        },
+    };
+}
 function estimateToolPayloadChars(messages) {
     return messages.reduce((sum, message) => {
         if (message.role !== "tool") {
@@ -703,7 +1223,7 @@ function estimateToolPayloadChars(messages) {
     }, 0);
 }
 function countUserTurns(messages) {
-    return messages.reduce((count, message) => count + (message.role === "user" && !message.isMeta ? 1 : 0), 0);
+    return messages.reduce((count, message) => count + (message.role === "user" ? 1 : 0), 0);
 }
 function getCurrentHeapUsed() {
     try {
@@ -713,3 +1233,76 @@ function getCurrentHeapUsed() {
         return 0;
     }
 }
+function isFinalSubagentStatus(status) {
+    return status === "completed"
+        || status === "failed"
+        || status === "blocked"
+        || status === "cancelled"
+        || status === "closed";
+}
+function normalizeWaitTimeout(value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return 30_000;
+    return Math.max(100, Math.min(3_600_000, Math.floor(value)));
+}
+function isSubagentLifecycleTool(name) {
+    return name === "subagent"
+        || name === "spawn_agent"
+        || name === "wait_agent"
+        || name === "send_input"
+        || name === "close_agent";
+}
+function sanitizeSubagentSummary(value) {
+    return stripProviderProtocolArtifacts(value).trim();
+}
+function needsExplicitFinalSummary(record, executedAnyTool) {
+    // If the subagent actually invoked any tool, always solicit an explicit final
+    // summary. We cannot tell from the stream alone whether a tool-free trailing
+    // turn was the real answer or mid-thought narration ("Let me try X next:").
+    // Asking the model to restate its findings is cheap and yields predictable,
+    // clean output. (Profile-validation notes in `toolNotes` do not count as
+    // actual tool executions.)
+    if (executedAnyTool)
+        return true;
+    if (!record.summary)
+        return false;
+    if (isOnlyProviderProtocolArtifacts(record.summary))
+        return true;
+    if (/<\/?[｜|][^<>]*>/.test(record.summary))
+        return true;
+    return false;
+}
+function summarizeSubagentToolEnd(event) {
+    const metadata = (event.result.metadata ?? {});
+    const reason = readString(metadata.reason);
+    if (reason)
+        return reason;
+    const summary = readString(metadata.summary);
+    if (summary)
+        return summary;
+    if (event.result.isError) {
+        const firstLine = event.result.content.split(/\r?\n/).map((line) => line.trim()).find(Boolean);
+        return firstLine ? truncateForNote(firstLine) : "failed";
+    }
+    const matches = readNumber(metadata.matches);
+    const pattern = readString(metadata.pattern);
+    const path = readString(metadata.path);
+    if (matches !== undefined) {
+        const target = pattern ? ` for ${pattern}` : "";
+        const within = path ? ` in ${path}` : "";
+        return `${matches} match${matches === 1 ? "" : "es"}${target}${within}`;
+    }
+    const kind = readString(metadata.kind);
+    if (path)
+        return kind ? `${kind} ${path}` : path;
+    return event.result.status ?? "completed";
+}
+function readString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function readNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function truncateForNote(value, max = 200) {
+    return value.length <= max ? value : `${value.slice(0, max - 3)}...`;
+}