@bubblebrain-ai/bubble 0.0.38 → 0.0.40

package/dist/agent/internal-reminder-sanitizer.js

@@ -169,6 +169,8 @@ const INTERNAL_REASONING_REFERENCE_PATTERNS = [
     /Do not describe a subagent as running or still working/i,
     /Background task truth/i,
     /Never re-run work a finished task already did/i,
+    /Large-change checkpoint/i,
+    /delegation only adds merge risk/i,
 ];
 function consumeInternalBlockAtStart(text, final) {
     if (text.startsWith(INTERNAL_TAG_PREFIX)) {

package/dist/agent/profiles.d.ts

@@ -56,6 +56,12 @@ export interface AgentProfileDiagnostic {
 export type AgentProfileScope = "user" | "project" | "both";
 export declare function discoverAgentProfiles(cwd: string, scope?: AgentProfileScope): DiscoverAgentProfilesResult;
 export declare function builtinAgentProfiles(): AgentProfile[];
+/**
+ * The delegation nudge only fires when a write-capable spawn surface exists
+ * (large-task-delegation design §3): defense in depth for hosts that strip
+ * or override the builtin profiles.
+ */
+export declare function hasWriteWorktreeProfile(profiles: AgentProfile[]): boolean;
 export declare function findAgentProfile(profiles: AgentProfile[], name: string): AgentProfile | undefined;
 export declare function assignAgentNickname(profile: AgentProfile, activeNicknames?: Iterable<string>): string;
 /**

package/dist/agent/profiles.js

@@ -134,8 +134,40 @@ export function builtinAgentProfiles() {
         toProfile("security_investigation"),
         toProfile("evidence_correlation"),
         toProfile("general_readonly"),
+        // The write-capable builtin (large-task-delegation design §3): before
+        // this, write_worktree was reachable only via user-authored profile
+        // frontmatter, so the delegation nudge would have recommended a surface
+        // that does not exist in a stock session.
+        {
+            name: "implementer",
+            description: "Write-capable implementation subagent (isolated git worktree)",
+            source: "builtin",
+            mode: "write_worktree",
+            model: "inherit",
+            tools: {
+                preset: "explicit",
+                include: ["read", "glob", "grep", "edit", "write", "bash", "lsp", "todo_write"],
+                exclude: [],
+            },
+            approval: "fail",
+            nicknameCandidates: DEFAULT_NICKNAME_CANDIDATES,
+            prompt: [
+                "You are an implementer subagent working in your own isolated git worktree — the parent tree is never touched.",
+                "Your worktree forks from the last commit; changes the parent made after that commit are NOT present unless included in your briefing.",
+                "Make the smallest coherent edits that complete your assigned group. Stay strictly inside the file set you were given; if a needed change falls outside it, report that instead of editing.",
+                "Verify your changes narrowly (targeted tests or typecheck) when possible, and end with a concise summary of files changed and verification results — the parent reviews and applies your worktree.",
+            ].join("\n"),
+        },
     ];
 }
+/**
+ * The delegation nudge only fires when a write-capable spawn surface exists
+ * (large-task-delegation design §3): defense in depth for hosts that strip
+ * or override the builtin profiles.
+ */
+export function hasWriteWorktreeProfile(profiles) {
+    return profiles.some((profile) => profile.mode === "write_worktree");
+}
 export function findAgentProfile(profiles, name) {
     return profiles.find((profile) => profile.name === name)
         ?? profiles.find((profile) => profile.name === `builtin:${name}`);

package/dist/agent.d.ts

@@ -112,6 +112,14 @@ export declare class Agent {
         outputTail: (id: string) => string | undefined;
     };
     private lastTaskReminderVersion;
+    /**
+     * Once-per-session latch for the large-task delegation nudge
+     * (large-task-delegation design §2): goal-loop continuations rebuild
+     * TurnHookState every run, so a per-turn latch would nag on every turn.
+     * If the model read the nudge once and chose not to delegate, repeating
+     * it is noise.
+     */
+    largeTaskNudgeConsumed: boolean;
     private _providerId;
     private _model;
     private tools;
@@ -295,6 +303,15 @@ export declare class Agent {
         abortSignal?: AbortSignal;
     }): Promise<SubagentThreadSnapshot>;
     closeSubAgent(agentId: string): Promise<SubagentThreadSnapshot>;
+    /**
+     * Live (non-final) children only — the delegation-nudge gate
+     * (large-task-delegation design §2). listSubAgents() is a grows-only
+     * session history (finished + resumed children stay forever), so it must
+     * never be used to answer "am I currently delegating?".
+     */
+    activeSubAgentCount(): number;
+    /** run_workflow children are workflowInternal and invisible to listSubAgents. */
+    hasRunningWorkflow(): boolean;
     listSubAgents(): SubagentThreadSnapshot[];
     /**
      * Dynamic workflow (option C): runs an LLM-authored JS orchestration script in

package/dist/agent.js

@@ -20,6 +20,7 @@ import { HookBus } from "./orchestrator/hooks.js";
 import { normalizeHookInput, truncateHookText, } from "./hooks/index.js";
 import { createDefaultHooks } from "./orchestrator/default-hooks.js";
 import { buildTaskLifecycleReminder } from "./agent/task-lifecycle-reminder.js";
+import { classifyTask } from "./agent/task-classifier.js";
 import { mergeAgentCategories, parseThinkingLevel, resolveModelRoute, resolveSubagentRoute } from "./agent/categories.js";
 import { DEFAULT_AGENT_ROUTING, nearModelMatches, sanitizeAgentRouting, tierContextFromSnapshot } from "./agent/routing-catalog.js";
 import { buildModelRoutingPrompt } from "./prompt/routing.js";
@@ -108,6 +109,14 @@ export class Agent {
      */
     backgroundTasks;
     lastTaskReminderVersion = -1;
+    /**
+     * Once-per-session latch for the large-task delegation nudge
+     * (large-task-delegation design §2): goal-loop continuations rebuild
+     * TurnHookState every run, so a per-turn latch would nag on every turn.
+     * If the model read the nudge once and chose not to delegate, repeating
+     * it is noise.
+     */
+    largeTaskNudgeConsumed = false;
     _providerId;
     _model;
     tools = new Map();
@@ -548,6 +557,15 @@ export class Agent {
                 events.push(...hook.events);
                 this.injectHookModelContext(hook.result);
                 this.appendMessage({ role: "user", content: input.content });
+                // Large-task detector (large-task-delegation design §1): a steer
+                // redirects the task — stale breadth evidence must not fire a nudge
+                // about the pre-steer task, and the classifier should reason about
+                // the redirected one.
+                hookState.exploredFiles?.clear();
+                hookState.largeTaskCheckpointDone = false;
+                if (typeof input.content === "string" && input.content.trim()) {
+                    hookState.taskType = classifyTask(input.content);
+                }
                 events.push({
                     type: "input_applied",
                     id: input.id,
@@ -1675,6 +1693,19 @@ export class Agent {
         this.subagentStore.notifyWaiters(record);
         return this.snapshotSubagent(record);
     }
+    /**
+     * Live (non-final) children only — the delegation-nudge gate
+     * (large-task-delegation design §2). listSubAgents() is a grows-only
+     * session history (finished + resumed children stay forever), so it must
+     * never be used to answer "am I currently delegating?".
+     */
+    activeSubAgentCount() {
+        return this.subagentStore.activeCount();
+    }
+    /** run_workflow children are workflowInternal and invisible to listSubAgents. */
+    hasRunningWorkflow() {
+        return [...this.workflowRuns.values()].some((record) => record.status === "running");
+    }
     listSubAgents() {
         return this.subagentStore.values()
             .filter((record) => !record.workflowInternal)

package/dist/cli.d.ts

@@ -11,6 +11,8 @@ export interface CliArgs {
     resume?: boolean;
     sessionName?: string;
     print?: boolean;
+    /** Print-mode output: plain (default) or a single JSON object on stdout. */
+    outputFormat?: "plain" | "json";
     prompt?: string;
     thinkingLevel?: ThinkingLevel;
     mode?: PermissionMode;

package/dist/cli.js

@@ -55,6 +55,15 @@ export function parseArgs(argv) {
             case "-p":
                 args.print = true;
                 break;
+            case "--output-format": {
+                const value = argv[++i];
+                if (value !== "plain" && value !== "json") {
+                    console.error(`Invalid --output-format: ${value ?? "(missing)"}. Expected plain or json.`);
+                    process.exit(1);
+                }
+                args.outputFormat = value;
+                break;
+            }
             case "--plan":
                 args.mode = "plan";
                 break;
@@ -108,6 +117,8 @@ Options (default):
   --dangerously-skip-permissions
                            Enable bypass mode (auto-approve EVERY tool; disables all safety prompts)
   -p, --print              Non-interactive mode (single prompt)
+  --output-format <fmt>    Print-mode output: plain (default) or json
+                           (one JSON object on stdout: text, usage, num_turns)
   -v, --version            Print the installed version and exit
   -h, --help               Show this help
 

package/dist/main.js

@@ -20,6 +20,7 @@ import { SkillRegistry } from "./skills/registry.js";
 import { buildToolPromptOptions, createAllTools } from "./tools/index.js";
 import { getProcessManager } from "./tasks/manager.js";
 import { PromotionChannel } from "./tasks/promotion.js";
+import { PrintRunCollector, formatPrintJson, formatPrintJsonError } from "./print-output.js";
 import { FileStateTracker } from "./tools/file-state.js";
 import { GoalStore } from "./goal/store.js";
 import { PermissionAwareApprovalController } from "./approval/controller.js";
@@ -552,7 +553,8 @@ async function main() {
                 agent.injectModeReminder();
             }
             agent.injectDeferredToolsReminder();
-            console.log(chalk.dim(`Resumed session: ${sessionManager.getSessionFile()}`));
+            // JSON print mode reserves stdout for the single result object.
+            (args.outputFormat === "json" ? console.error : console.log)(chalk.dim(`Resumed session: ${sessionManager.getSessionFile()}`));
         }
     }
     try {
@@ -568,33 +570,70 @@ async function main() {
                 console.error(chalk.red("Error: No prompt provided."));
                 process.exit(1);
             }
-            let printedTurnText = false;
-            for await (const event of agent.run(prompt, args.cwd)) {
-                traceEvent("print_agent_event", summarizeAgentEventForTrace(event));
-                if (event.type === "turn_start") {
-                    printedTurnText = false;
-                }
-                else if (event.type === "provider_retry") {
-                    // The stream died mid-response and the agent re-issues the whole
-                    // request. Text already on stdout cannot be un-printed, so at least
-                    // separate the retried response and say what happened.
-                    if (printedTurnText)
-                        process.stdout.write("\n");
-                    console.error(chalk.yellow(`[Stream interrupted; retrying (${event.attempt}/${event.maxAttempts}) — the partial text above is superseded by the retried response]`));
-                }
-                else if (event.type === "text_delta") {
-                    printedTurnText = true;
-                    process.stdout.write(event.content);
+            // JSON mode (benchmark/CI adapters): stdout carries exactly ONE JSON
+            // object; streaming text and tool logs move to stderr-silence. Plain
+            // mode is byte-for-byte the previous behavior.
+            const jsonOutput = args.outputFormat === "json";
+            const collector = new PrintRunCollector();
+            const printSessionId = sessionManager
+                ? basename(sessionManager.getSessionFile())
+                : undefined;
+            try {
+                let printedTurnText = false;
+                for await (const event of agent.run(prompt, args.cwd)) {
+                    traceEvent("print_agent_event", summarizeAgentEventForTrace(event));
+                    collector.onEvent(event);
+                    if (jsonOutput) {
+                        if (event.type === "provider_retry") {
+                            console.error(chalk.yellow(`[Stream interrupted; retrying (${event.attempt}/${event.maxAttempts})]`));
+                        }
+                        continue;
+                    }
+                    if (event.type === "turn_start") {
+                        printedTurnText = false;
+                    }
+                    else if (event.type === "provider_retry") {
+                        // The stream died mid-response and the agent re-issues the whole
+                        // request. Text already on stdout cannot be un-printed, so at least
+                        // separate the retried response and say what happened.
+                        if (printedTurnText)
+                            process.stdout.write("\n");
+                        console.error(chalk.yellow(`[Stream interrupted; retrying (${event.attempt}/${event.maxAttempts}) — the partial text above is superseded by the retried response]`));
+                    }
+                    else if (event.type === "text_delta") {
+                        printedTurnText = true;
+                        process.stdout.write(event.content);
+                    }
+                    else if (event.type === "tool_start") {
+                        console.log(chalk.cyan(`\n[Tool: ${event.name}]`));
+                    }
+                    else if (event.type === "tool_end") {
+                        const color = event.result.isError ? chalk.red : chalk.dim;
+                        console.log(color(`[Result: ${event.result.content.slice(0, 200)}${event.result.content.length > 200 ? "..." : ""}]`));
+                    }
                 }
-                else if (event.type === "tool_start") {
-                    console.log(chalk.cyan(`\n[Tool: ${event.name}]`));
+                if (jsonOutput) {
+                    process.stdout.write(formatPrintJson({
+                        summary: collector.summary(),
+                        sessionId: printSessionId,
+                    }) + "\n");
                 }
-                else if (event.type === "tool_end") {
-                    const color = event.result.isError ? chalk.red : chalk.dim;
-                    console.log(color(`[Result: ${event.result.content.slice(0, 200)}${event.result.content.length > 200 ? "..." : ""}]`));
+                else {
+                    console.log();
                 }
             }
-            console.log();
+            catch (error) {
+                if (!jsonOutput)
+                    throw error;
+                // Structured failure: adapters distinguish agent errors from crashes
+                // by the JSON error object + non-zero exit.
+                process.stdout.write(formatPrintJsonError({
+                    message: error instanceof Error ? error.message : String(error),
+                    summary: collector.summary(),
+                    sessionId: printSessionId,
+                }) + "\n");
+                process.exitCode = 1;
+            }
             return;
         }
         const themeConfig = userConfig.getTheme();
@@ -795,7 +834,10 @@ async function readPipedStdin() {
 }
 main()
     .then(() => {
-    void exitAfterFlush(0);
+    // Preserve an exit code set by a handled failure path (e.g. print-mode
+    // agent errors set exitCode = 1 and return normally) — exit(0) here
+    // would silently override it.
+    void exitAfterFlush(typeof process.exitCode === "number" ? process.exitCode : 0);
 })
     .catch((err) => {
     console.error(chalk.red(`Fatal error: ${err.message}`));

package/dist/orchestrator/default-hooks.js

@@ -5,8 +5,11 @@ import { ExecutionGovernor } from "../agent/execution-governor.js";
 import { DiscoveryBarrier } from "../agent/discovery-barrier.js";
 import { arbitrateToolCall } from "../agent/tool-arbiter.js";
 import { buildEditRetryEscalationReminder, buildSmallTaskHint, buildWorkflowPhaseReminder, } from "../prompt/reminders.js";
-import { orchestrationRequestReminder, reminderForTaskType, userNamedModelReminder } from "../prompt/task-reminders.js";
+import { largeImplementationTaskReminder, orchestrationRequestReminder, reminderForTaskType, userNamedModelReminder } from "../prompt/task-reminders.js";
 import { formatCoverageSummary, resolveWorkflowPhase } from "./workflow.js";
+import { resolve as resolvePath } from "node:path";
+import { traceEvent } from "../debug-trace.js";
+import { builtinAgentProfiles, discoverAgentProfiles, hasWriteWorktreeProfile } from "../agent/profiles.js";
 import { buildSubagentLifecycleReminder } from "../agent/subagent-lifecycle-reminder.js";
 export function createDefaultHooks() {
     return [
@@ -33,6 +36,9 @@ export function createDefaultHooks() {
                 const orchestrationReminder = orchestrationRequestReminder(ctx.input, ctx.agent.hasToolAvailable("run_workflow"));
                 if (orchestrationReminder) {
                     ctx.queueReminder(orchestrationReminder);
+                    // The large-change checkpoint must not re-offer spawn_agent in a
+                    // turn where this reminder just forbade it (design §3).
+                    ctx.state.orchestrationReminderSent = true;
                 }
                 // User named a configured model ("gpt 5.6 sol"): resolve it against
                 // the routable catalog and hand over the exact id at the decision
@@ -97,6 +103,12 @@ export function createDefaultHooks() {
                 const toolCall = { ...arbitration.toolCall, ...(arbitration.note ? { arbiterNote: arbitration.note } : {}) };
                 ctx.replaceToolCall(toolCall);
                 ctx.state.governor?.beforeToolCall(toolCall);
+                // Large-change checkpoint (large-task-delegation design §1): the
+                // first mutation of the turn is the decision point — exploration is
+                // over, nothing has been edited yet.
+                if (isMutationTool(toolCall.name)) {
+                    maybeQueueLargeTaskNudge(ctx);
+                }
                 const blockedResult = ctx.state.discoveryBarrier?.beforeToolCall(toolCall);
                 if (blockedResult)
                     ctx.blockToolCall(blockedResult);
@@ -153,6 +165,18 @@ export function createDefaultHooks() {
                 // dedup do the work.
                 if (isCodeWriteResult(ctx.toolCall, ctx.result)) {
                     markCodeChanged(ctx.state);
+                    ctx.state.appliedEditCount = (ctx.state.appliedEditCount ?? 0) + 1;
+                }
+                // Large-task breadth evidence (design §1): only files actually READ.
+                // Search results contribute nothing — one glob returns up to 100
+                // match paths and would saturate any threshold instantly (review
+                // blocker). Bash-parsed reads (cat/head/sed -n) carry relative
+                // paths, so resolve against cwd before dedup.
+                if (!ctx.result.isError && ctx.result.metadata?.kind === "read") {
+                    const path = typeof ctx.result.metadata.path === "string" ? ctx.result.metadata.path : undefined;
+                    if (path) {
+                        (ctx.state.exploredFiles ??= new Set()).add(resolvePath(ctx.cwd, path));
+                    }
                 }
                 // Removed: active verification tracking. The previous design nagged the
                 // model every turn until it ran a recognised verification command, and
@@ -206,6 +230,59 @@ export function createDefaultHooks() {
 function markCodeChanged(state) {
     state.codeChanged = true;
 }
+// Large-task delegation checkpoint (large-task-delegation design §1-3).
+const BREADTH_FILES = 8;
+const BREADTH_FILES_WITH_PLAN = 5;
+const BREADTH_TODOS = 6;
+function maybeQueueLargeTaskNudge(ctx) {
+    // Evaluated exactly once per turn, at the first mutation — fired or not
+    // (mid-implementation re-detection is out of scope by design §4).
+    if (ctx.state.largeTaskCheckpointDone)
+        return;
+    ctx.state.largeTaskCheckpointDone = true;
+    const agent = ctx.agent;
+    const taskType = ctx.state.taskType;
+    const exploredFiles = ctx.state.exploredFiles?.size ?? 0;
+    const pendingTodos = agent.getTodos?.()
+        ?.filter((todo) => todo.status === "pending" || todo.status === "in_progress").length ?? 0;
+    const threshold = pendingTodos >= BREADTH_TODOS ? BREADTH_FILES_WITH_PLAN : BREADTH_FILES;
+    // Gate order: cheap checks first; the profile discovery (filesystem) runs
+    // only when everything else already passed.
+    const suppressedBy = agent.largeTaskNudgeConsumed ? "session_latch"
+        : (taskType === "code_review" || taskType === "security_investigation") ? "task_type"
+            : !agent.hasToolAvailable("spawn_agent") ? "no_spawn_tool"
+                : (agent.activeSubAgentCount?.() ?? 0) > 0 ? "active_children"
+                    : agent.hasRunningWorkflow?.() ? "running_workflow"
+                        : exploredFiles < threshold ? "below_threshold"
+                            : !writeWorktreeSurfaceAvailable(ctx.cwd) ? "no_write_profile"
+                                : undefined;
+    traceEvent("delegation_detector", {
+        fired: suppressedBy === undefined,
+        exploredFiles,
+        pendingTodos,
+        threshold,
+        taskType: taskType ?? "unknown",
+        ...(suppressedBy ? { suppressedBy } : {}),
+    });
+    if (suppressedBy !== undefined)
+        return;
+    agent.largeTaskNudgeConsumed = true;
+    ctx.queueReminder(largeImplementationTaskReminder({
+        exploredFiles,
+        pendingTodos,
+        appliedEdits: ctx.state.appliedEditCount ?? 0,
+        orchestrationRequested: ctx.state.orchestrationReminderSent === true,
+    }));
+}
+function writeWorktreeSurfaceAvailable(cwd) {
+    try {
+        const discovered = discoverAgentProfiles(cwd, "both").profiles;
+        return hasWriteWorktreeProfile([...builtinAgentProfiles(), ...discovered]);
+    }
+    catch {
+        return hasWriteWorktreeProfile(builtinAgentProfiles());
+    }
+}
 function isCodeWriteResult(_toolCall, result) {
     if (result.isError || result.status === "blocked" || result.status === "cancelled" || result.status === "command_error") {
         return false;

package/dist/orchestrator/hooks.d.ts

@@ -26,6 +26,13 @@ export interface TurnHookState {
         total: number;
         spent: number;
     };
+    exploredFiles?: Set<string>;
+    /** Checkpoint evaluated at the first mutation — once per turn, fired or not. */
+    largeTaskCheckpointDone?: boolean;
+    /** Successful mutations this turn; rendered as K in the nudge wording. */
+    appliedEditCount?: number;
+    /** orchestrationRequestReminder fired: the nudge offers only run_workflow. */
+    orchestrationReminderSent?: boolean;
 }
 export interface TurnHookContext {
     agent: Agent;

package/dist/print-output.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Structured output for print mode (`-p --output-format json`).
+ *
+ * Built for benchmark/CI adapters (Pier, terminal-bench): stdout carries
+ * exactly one JSON object; all human-facing noise goes to stderr. Field
+ * names follow the grok-build/Claude Code convention (text, stopReason,
+ * sessionId, usage.{input_tokens,...}, num_turns) so existing harness
+ * adapters port with minimal changes.
+ */
+import type { AgentEvent } from "./types.js";
+export type PrintOutputFormat = "plain" | "json";
+export declare function parseOutputFormat(raw: string | undefined): PrintOutputFormat | undefined;
+export interface PrintUsageSummary {
+    input_tokens: number;
+    cache_read_input_tokens: number;
+    output_tokens: number;
+    reasoning_tokens: number;
+    total_tokens: number;
+}
+export interface PrintRunSummary {
+    /** Final answer: the last turn's streamed text. */
+    text: string;
+    num_turns: number;
+    num_tool_calls: number;
+    usage: PrintUsageSummary;
+    /**
+     * False when no turn carried provider usage (some endpoints — notably the
+     * Grok subscription proxy — omit it): zeros then mean "not reported",
+     * not "free". Mirrors the goal engine's markTokenUsageUnavailable and
+     * grok-build's usage_is_incomplete convention.
+     */
+    usage_reported: boolean;
+}
+export declare class PrintRunCollector {
+    private turnText;
+    private lastTurnText;
+    private turns;
+    private toolCalls;
+    private usageReported;
+    private readonly usage;
+    onEvent(event: AgentEvent): void;
+    private addUsage;
+    summary(): PrintRunSummary;
+}
+export declare function formatPrintJson(input: {
+    summary: PrintRunSummary;
+    sessionId?: string;
+    stopReason?: "end_turn" | "error" | "cancelled";
+}): string;
+export declare function formatPrintJsonError(input: {
+    message: string;
+    summary?: PrintRunSummary;
+    sessionId?: string;
+}): string;

package/dist/print-output.js

@@ -0,0 +1,103 @@
+/**
+ * Structured output for print mode (`-p --output-format json`).
+ *
+ * Built for benchmark/CI adapters (Pier, terminal-bench): stdout carries
+ * exactly one JSON object; all human-facing noise goes to stderr. Field
+ * names follow the grok-build/Claude Code convention (text, stopReason,
+ * sessionId, usage.{input_tokens,...}, num_turns) so existing harness
+ * adapters port with minimal changes.
+ */
+export function parseOutputFormat(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (raw === "plain" || raw === "json")
+        return raw;
+    return undefined;
+}
+export class PrintRunCollector {
+    turnText = "";
+    lastTurnText = "";
+    turns = 0;
+    toolCalls = 0;
+    usageReported = false;
+    usage = {
+        input_tokens: 0,
+        cache_read_input_tokens: 0,
+        output_tokens: 0,
+        reasoning_tokens: 0,
+        total_tokens: 0,
+    };
+    onEvent(event) {
+        switch (event.type) {
+            case "turn_start":
+                this.turns += 1;
+                this.turnText = "";
+                break;
+            case "text_delta":
+                this.turnText += event.content;
+                break;
+            case "provider_retry":
+                // The retried response supersedes the partial text.
+                this.turnText = "";
+                break;
+            case "tool_start":
+                this.toolCalls += 1;
+                break;
+            case "turn_end":
+                // Usage reaches AgentEvent only on turn_end (the stream-level
+                // "usage" chunk is aggregated into it by the agent loop).
+                if (this.turnText.trim())
+                    this.lastTurnText = this.turnText;
+                if (event.usage)
+                    this.addUsage(event.usage);
+                break;
+            default:
+                break;
+        }
+    }
+    addUsage(usage) {
+        this.usageReported = true;
+        this.usage.input_tokens += usage.promptTokens ?? 0;
+        this.usage.cache_read_input_tokens += usage.promptCacheHitTokens ?? 0;
+        this.usage.output_tokens += usage.completionTokens ?? 0;
+        this.usage.reasoning_tokens += usage.reasoningTokens ?? 0;
+        this.usage.total_tokens += usage.totalTokens
+            ?? ((usage.promptTokens ?? 0) + (usage.completionTokens ?? 0));
+    }
+    summary() {
+        return {
+            text: (this.lastTurnText || this.turnText).trim(),
+            num_turns: this.turns,
+            num_tool_calls: this.toolCalls,
+            usage: { ...this.usage },
+            usage_reported: this.usageReported,
+        };
+    }
+}
+export function formatPrintJson(input) {
+    return JSON.stringify({
+        text: input.summary.text,
+        stopReason: input.stopReason ?? "end_turn",
+        ...(input.sessionId ? { sessionId: input.sessionId } : {}),
+        num_turns: input.summary.num_turns,
+        num_tool_calls: input.summary.num_tool_calls,
+        usage: input.summary.usage,
+        usage_reported: input.summary.usage_reported,
+    });
+}
+export function formatPrintJsonError(input) {
+    return JSON.stringify({
+        type: "error",
+        message: input.message,
+        stopReason: "error",
+        ...(input.sessionId ? { sessionId: input.sessionId } : {}),
+        ...(input.summary
+            ? {
+                text: input.summary.text,
+                num_turns: input.summary.num_turns,
+                num_tool_calls: input.summary.num_tool_calls,
+                usage: input.summary.usage,
+            }
+            : {}),
+    });
+}

package/dist/prompt/delegation.js

@@ -51,9 +51,12 @@ earlier work lives in an existing subagent, prefer send_input to resume it
 over spawning a fresh one.
 
 Do NOT delegate when:
-- The task requires editing files or running state-changing commands.
-  Built-in subagents are read-only; do edits and writes yourself unless a
-  write-capable (write_worktree) profile is explicitly available.
+- The edits are ENTANGLED — shared state, one file feeding the next, order
+  matters. Write delegation exists (the builtin "implementer" profile runs
+  in an isolated git worktree), but it only pays off for INDEPENDENT edit
+  groups with disjoint file sets. Worktree children fork from the last
+  commit and the parent reviews/applies their changes afterward; entangled
+  work through that contract only adds merge risk — do it yourself.
 - The task takes one or two tool calls (reading a single file, looking up one
   definition). The handoff overhead costs more than the task.
 - Doing it well depends on conversation context (preferences the user stated

package/dist/prompt/task-reminders.d.ts

@@ -23,4 +23,21 @@ export declare function reminderForTaskType(taskType: TaskType, options?: TaskRe
  * this, 2026-07-12 live case). Silent on no match: zero standing noise.
  */
 export declare function userNamedModelReminder(input: string | import("../types.js").ContentPart[], routableModels: RoutableModelEntry[] | undefined, canSpawn: boolean): string | undefined;
+/**
+ * Large-change checkpoint (large-task-delegation design §3): injected once
+ * per session at the first mutation of a broad turn. Carries the routing
+ * decision criteria (independent vs entangled) and the real worktree
+ * mechanics (children fork from the last commit; disjoint file sets) —
+ * never a command. The "smallest coherent edit" clause is lifted verbatim
+ * from the implementation-workflow reminder so the two compose.
+ */
+export interface LargeTaskReminderInput {
+    exploredFiles: number;
+    pendingTodos: number;
+    /** Mutations already applied this turn (the current batch lands regardless). */
+    appliedEdits: number;
+    /** orchestrationRequestReminder fired this turn: only offer run_workflow. */
+    orchestrationRequested: boolean;
+}
+export declare function largeImplementationTaskReminder(input: LargeTaskReminderInput): string;
 export declare function orchestrationRequestReminder(input: string | import("../types.js").ContentPart[], canRunWorkflow: boolean): string | undefined;

package/dist/prompt/task-reminders.js

@@ -119,6 +119,21 @@ export function userNamedModelReminder(input, routableModels, canSpawn) {
         "Use these exact ids in spawn_agent / run_workflow `model` params; do not retype model ids from memory.",
     ].join("\n");
 }
+export function largeImplementationTaskReminder(input) {
+    const plan = input.pendingTodos > 0 ? ` (plan: ${input.pendingTodos} open todo items)` : "";
+    const applied = input.appliedEdits > 0
+        ? ` ${input.appliedEdits} edit${input.appliedEdits === 1 ? "" : "s"} from your current batch will land regardless.`
+        : "";
+    const mechanism = input.orchestrationRequested
+        ? "one run_workflow script (the user asked for a coordinated workflow — keep everything in it)"
+        : "write_worktree subagents (spawn_agent with the implementer profile) or one run_workflow script";
+    return wrapInSystemReminder(`
+Large-change checkpoint: you have read ${input.exploredFiles} files this turn${plan} and are starting to edit.${applied}
+- If the REMAINING edits form INDEPENDENT groups (per-module, per-file, same shape repeated), split them across ${mechanism}. Assign each child a DISJOINT file set; keep shared files (types, registries, exports) for yourself. Children fork from the last COMMIT — commit your applied edits first, or fold them into the child briefings. Each child still makes the smallest coherent edit for its group.
+- If the edits are ENTANGLED (shared state, one file feeding the next, order matters), delegation only adds merge risk — proceed yourself.
+- Work already small enough to finish directly: just finish it.
+`);
+}
 const ORCHESTRATION_REQUEST = /\b(?:workflows?|orchestrat\w*|agent[ -]?teams?|fan[ -]?out)\b|工作流|编排|(?:智能体|代理|agent)\s*(?:团队|小队)/i;
 export function orchestrationRequestReminder(input, canRunWorkflow) {
     if (!canRunWorkflow)

package/dist/provider.js

@@ -15,6 +15,7 @@ import { createProviderProtocolArtifactFilter } from "./provider-artifacts.js";
 import { resolveProviderRequestConfig } from "./provider-transform.js";
 import { debugReasoningStream, summarizeDebugText } from "./reasoning-debug.js";
 import { RateLimitError } from "./network/errors.js";
+import { ProviderStreamInterruptedError } from "./network/retry.js";
 // Diagnostic logger for tool-args byte-loss investigation. Activate with
 //   BUBBLE_DEBUG_TOOL_ARGS=/path/to/log.jsonl   (any writable path)
 // Each line is a JSON record describing a transition. When debugging is off,
@@ -188,13 +189,24 @@ export function createProviderInstance(options) {
         // surfaces a final 429 as a typed RateLimitError instead of a string.
         let stream;
         stream = (await createCompletion(body));
-        yield* translateOpenAIStream(stream, {
-            toolArgsMergeMode: resolveToolArgsMergeMode(options.providerId || "", options.baseURL),
-            reasoningMergeMode: resolveReasoningMergeMode(options.providerId || "", options.baseURL),
-            textMergeMode: resolveTextMergeMode(options.providerId || "", options.baseURL),
-            debugProviderId: options.providerId || "",
-            debugModelId: chatOptions.model,
-        });
+        // A socket drop while iterating the SSE stream must surface as
+        // ProviderStreamInterruptedError so the agent loop re-issues the request;
+        // a raw network error here aborts the whole run (anthropic/codex/ai-sdk
+        // paths already wrap — this generic chat-completions path did not).
+        try {
+            yield* translateOpenAIStream(stream, {
+                toolArgsMergeMode: resolveToolArgsMergeMode(options.providerId || "", options.baseURL),
+                reasoningMergeMode: resolveReasoningMergeMode(options.providerId || "", options.baseURL),
+                textMergeMode: resolveTextMergeMode(options.providerId || "", options.baseURL),
+                debugProviderId: options.providerId || "",
+                debugModelId: chatOptions.model,
+            });
+        }
+        catch (error) {
+            if (chatOptions.abortSignal?.aborted)
+                throw error;
+            throw new ProviderStreamInterruptedError(`Provider stream interrupted: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
         yield { type: "done" };
     }
     async function complete(messages, chatOptions) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bubblebrain-ai/bubble",
-  "version": "0.0.38",
+  "version": "0.0.40",
   "description": "A terminal coding agent",
   "type": "module",
   "engines": {