@bubblebrain-ai/bubble 0.0.21 → 0.0.23

package/dist/agent/child-runner.js

@@ -0,0 +1,312 @@
+/**
+ * ChildRunner — executes one logical run of a subagent thread and reports the
+ * outcome to the scheduler (design doc §2, extracted in Phase 3).
+ *
+ * A logical run spans dispatch → final state; a rate-limit re-entry is the
+ * same logical run (no second SubagentStart), while a send_input restart is a
+ * new one. The runner owns: tool validation defense, instance reuse,
+ * turn-boundary budget enforcement, the handoff completeness guard, and the
+ * mapping of failures to SubagentFinalReason.
+ */
+import { AgentAbortError, EMPTY_ASSISTANT_FALLBACK, SubagentAbortError } from "./abort-errors.js";
+import { childHardCap, composeAbortSignals } from "./budget-ledger.js";
+import { isOnlyProviderProtocolArtifacts, stripProviderProtocolArtifacts } from "../provider-artifacts.js";
+import { isRateLimitError } from "../network/errors.js";
+import { mergeUsage, selectToolsForAgentProfile, validateAgentProfileTools } from "./profiles.js";
+import { estimateHandoffTokens, HANDOFF_TOKEN_FLOOR, isIntermediateHandoff, stripInternalTagFragments, } from "./subagent-summary.js";
+export class ChildRunner {
+    host;
+    constructor(host) {
+        this.host = host;
+    }
+    async run(record, input, cwd, options) {
+        const attempt = options.attempt ?? 1;
+        const emit = (status, event, message) => this.host.emit(record, options, status, event, message);
+        const allTools = this.host.allTools();
+        const diagnostics = validateAgentProfileTools(allTools, record.profile, options.approval);
+        const blockingDiagnostics = diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+        if (attempt === 1) {
+            for (const diagnostic of diagnostics.filter((item) => item.severity === "warning")) {
+                record.toolNotes.push(`profile: ${diagnostic.message}`);
+            }
+        }
+        if (blockingDiagnostics.length > 0) {
+            this.host.finalizeBlocked(record, blockingDiagnostics.map((diagnostic) => diagnostic.message).join("\n"), options);
+            this.host.onFinal(record, options);
+            return { kind: "final" };
+        }
+        const tools = selectToolsForAgentProfile(allTools, record.profile, options.approval);
+        const reuseExistingAgent = (options.reuseAgent || attempt > 1) && !!record.agent;
+        let subAgent;
+        try {
+            subAgent = reuseExistingAgent
+                ? record.agent
+                : await this.host.createInstance(record, tools, cwd, options.forkContext);
+        }
+        catch (error) {
+            // Instance creation failed before the run started: no SubagentStart
+            // fired, so no SubagentStop follows (§9 — hooks pair per started run).
+            this.host.finalizeBlocked(record, error?.message || String(error), options);
+            record.finalReason = "failed_fatal";
+            this.host.onFinal(record, options);
+            return { kind: "final" };
+        }
+        record.agent = subAgent;
+        // Write children run inside their isolated worktree (design §8).
+        const runCwd = record.worktree?.path ?? cwd;
+        record.status = "running";
+        record.updatedAt = Date.now();
+        // SubagentStart fires exactly once per logical run (design §9): a
+        // rate-limit re-entry is the same logical run and must not re-fire it.
+        if (attempt === 1) {
+            await this.host.runLifecycleHook(record, cwd, "SubagentStart", record.status, undefined, options.abortSignal);
+        }
+        emit("running", undefined, attempt > 1
+            ? `Retrying ${record.nickname} (${record.profile.name}) after a rate limit, attempt ${attempt}...`
+            : `Running ${record.nickname} (${record.profile.name})...`);
+        let turnSummaryBuffer = "";
+        let turnHadToolCall = false;
+        let executedAnyTool = false;
+        // Per-child budget enforcement happens at turn boundaries (design §6):
+        // turn_end already carries usage, and a reminder injected here is seen by
+        // the very next provider call — unlike chunk-level aborts.
+        const cap = record.tokenCap;
+        let runTokens = 0;
+        let runTurns = 0;
+        let budgetSoftWarned = false;
+        // Re-entry after a rate limit: the input was applied on attempt 1, so the
+        // child history must not gain a second copy, and any stale interruption
+        // boundary from the failed call is stripped (design §4.5).
+        const resumeWithoutInput = attempt > 1;
+        if (resumeWithoutInput) {
+            stripTrailingModelInterruptedBoundary(subAgent.messages);
+        }
+        try {
+            const childAbortSignal = composeAbortSignals([
+                options.abortSignal,
+                record.abortController.signal,
+            ]);
+            for await (const event of subAgent.run(input, runCwd, { abortSignal: childAbortSignal, resumeWithoutInput })) {
+                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);
+                    runTokens += event.usage.promptTokens + event.usage.completionTokens;
+                    runTurns += 1;
+                    if (cap) {
+                        if (!budgetSoftWarned && runTokens >= cap.soft) {
+                            budgetSoftWarned = true;
+                            // The hard cap is fixed when the warning fires: soft + ~2 of
+                            // this child's average turns (absolute floor), so the child
+                            // gets a real chance to wrap up before the kill (design §6).
+                            cap.hard = childHardCap(cap.soft, runTokens / Math.max(1, runTurns));
+                            subAgent.injectSystemReminder(buildChildBudgetWrapUpReminder(runTokens, cap.soft));
+                        }
+                        else if (budgetSoftWarned && runTokens >= cap.hard) {
+                            record.abortController.abort(new SubagentAbortError(`Subagent ${record.agentId} exceeded its hard token cap (${cap.hard}).`, "budget"));
+                        }
+                    }
+                }
+                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) {
+            if (isRateLimitError(error)
+                && !record.abortController.signal.aborted
+                && !options.abortSignal?.aborted) {
+                // Not a failure: keep the agent instance and its context, hand the
+                // backoff decision to the scheduler — the single 429 backoff layer.
+                record.status = "queued";
+                record.summary = sanitizeSubagentSummary(record.summary);
+                record.updatedAt = Date.now();
+                stripTrailingModelInterruptedBoundary(subAgent.messages);
+                emit("queued", undefined, `Rate limited; ${record.nickname} will retry with its context intact.`);
+                return { kind: "rate_limited", retryAfterMs: error.retryAfterMs };
+            }
+            const cancelled = error instanceof AgentAbortError || error?.name === "AbortError";
+            record.status = cancelled ? "cancelled" : "failed";
+            record.finalReason = cancelled
+                ? classifySubagentAbortReason(record.abortController.signal.aborted ? record.abortController.signal.reason : error, options.abortSignal, this.host.budgetLedger())
+                : "failed_transient";
+            record.summary = sanitizeSubagentSummary(record.summary);
+            record.error = error?.message || String(error);
+            record.updatedAt = Date.now();
+            await this.host.runLifecycleHook(record, cwd, "SubagentStop", record.status, record.error, options.abortSignal);
+            emit(record.status, undefined, record.error);
+            this.host.notifyWaiters(record);
+            this.host.onFinal(record, options);
+            return { kind: "final" };
+        }
+        record.summary = sanitizeSubagentSummary(record.summary);
+        if (needsExplicitFinalSummary(record, executedAnyTool)) {
+            await this.runFinalSummaryTurn(record, subAgent, runCwd, options.abortSignal, emit);
+        }
+        record.status = "completed";
+        record.finalReason = "completed";
+        record.summary = sanitizeSubagentSummary(record.summary);
+        record.updatedAt = Date.now();
+        await this.host.runLifecycleHook(record, cwd, "SubagentStop", record.status, undefined, options.abortSignal);
+        emit("completed", undefined, record.summary || `${record.nickname} completed`);
+        this.host.notifyWaiters(record);
+        this.host.onFinal(record, options);
+        return { kind: "final" };
+    }
+    async runFinalSummaryTurn(record, subAgent, cwd, abortSignal, emit) {
+        const prompt = [
+            "Produce the final subagent handoff now: what you found, your conclusions, and any unfinished items.",
+            "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.",
+            "If your previous message already was the complete handoff, restate it as-is — do not pad it.",
+            "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);
+        // The follow-up may only improve the handoff: an empty or fallback
+        // response must never replace a real (if short) summary.
+        if (!finalHadToolCall && finalSummary && finalSummary !== EMPTY_ASSISTANT_FALLBACK) {
+            record.summary = finalSummary;
+        }
+    }
+}
+export function sanitizeSubagentSummary(value) {
+    return stripInternalTagFragments(stripProviderProtocolArtifacts(value)).trim();
+}
+/**
+ * Handoff completeness guard (design §3.2): a deterministic CJK-aware token
+ * floor and a cheap intermediate-narration prefix check run in parallel.
+ * Both only apply after the child actually used tools — a short direct answer
+ * to a trivial question is a complete handoff.
+ */
+export function needsExplicitFinalSummary(record, executedAnyTool) {
+    if (!record.summary)
+        return executedAnyTool;
+    if (isOnlyProviderProtocolArtifacts(record.summary))
+        return true;
+    if (/<\/?[｜|][^<>]*>/.test(record.summary))
+        return true;
+    if (!executedAnyTool)
+        return false;
+    if (record.summary === EMPTY_ASSISTANT_FALLBACK)
+        return true;
+    if (estimateHandoffTokens(record.summary) < HANDOFF_TOKEN_FLOOR)
+        return true;
+    return isIntermediateHandoff(record.summary);
+}
+export function classifySubagentAbortReason(reason, parentSignal, ledger) {
+    if (reason instanceof SubagentAbortError) {
+        switch (reason.subagentReason) {
+            case "interrupt":
+                return "cancelled_interrupt";
+            case "user_close":
+                return "cancelled_user";
+            case "budget":
+                return "cancelled_budget";
+        }
+    }
+    if (ledger?.snapshot().exhausted)
+        return "cancelled_budget";
+    if (parentSignal?.aborted)
+        return "cancelled_parent_abort";
+    return "cancelled_user";
+}
+/**
+ * Drops trailing "[model request interrupted ...]" boundary messages so a
+ * rate-limit re-entry resumes from clean history (design §4.5).
+ */
+export function stripTrailingModelInterruptedBoundary(messages) {
+    while (messages.length > 0) {
+        const last = messages[messages.length - 1];
+        if (last.role === "assistant" && last.content.startsWith("[model request interrupted")) {
+            messages.pop();
+            continue;
+        }
+        break;
+    }
+}
+function buildChildBudgetWrapUpReminder(spentTokens, softCap) {
+    return [
+        `Token budget notice: this subagent has used ~${Math.round(spentTokens)} tokens, crossing its ${softCap}-token budget.`,
+        "Wrap up now: stop opening new lines of investigation and produce your complete final handoff",
+        "(findings, conclusions, unfinished items) in your next message.",
+    ].join(" ");
+}
+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)}...`;
+}

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

@@ -54,17 +54,37 @@ export function sanitizeAssistantProviderMetadata(metadata) {
     if (!metadata || !anthropic || !blocks?.length)
         return metadata;
     let changed = false;
-    const sanitizedBlocks = blocks.map((block) => {
-        if (block.type !== "text" || typeof block.text !== "string") {
-            return block;
+    const sanitizedBlocks = [];
+    for (const block of blocks) {
+        // Plaintext text blocks are unsigned, so rewriting them in place is safe.
+        if (block.type === "text" && typeof block.text === "string") {
+            const sanitizedText = sanitizeInternalReminderBlocks(block.text);
+            if (sanitizedText !== block.text) {
+                changed = true;
+                sanitizedBlocks.push({ ...block, text: sanitizedText });
+            }
+            else {
+                sanitizedBlocks.push(block);
+            }
+            continue;
         }
-        const sanitizedText = sanitizeInternalReminderBlocks(block.text);
-        if (sanitizedText === block.text) {
-            return block;
+        // Extended-thinking blocks carry an Anthropic signature over their exact
+        // text; rewriting the text would invalidate the signature and the API
+        // would reject the replayed block. So when a thinking block's text carries
+        // internal markup (e.g. an echoed system reminder), DROP the whole block
+        // rather than mutate it. Thinking text is never user-visible — the display
+        // path renders message.reasoning, not contentBlocks — so dropping loses
+        // nothing on screen; it only keeps the verbatim reminder out of the
+        // persisted metadata and the Anthropic replay payload. redacted_thinking
+        // holds encrypted `data` (no plaintext field) and cannot carry a reminder.
+        if (block.type === "thinking" && typeof block.thinking === "string") {
+            if (sanitizeInternalReminderBlocks(block.thinking) !== block.thinking) {
+                changed = true;
+                continue;
+            }
         }
-        changed = true;
-        return { ...block, text: sanitizedText };
-    });
+        sanitizedBlocks.push(block);
+    }
     if (!changed)
         return metadata;
     return {

package/dist/agent/profiles.d.ts

@@ -20,6 +20,8 @@ export interface AgentProfile {
     category?: string;
     tools: AgentProfileTools;
     maxTurns?: number;
+    /** Optional per-child token cap declared by the profile (may only lower the runtime default). */
+    maxTokens?: number;
     approval: AgentProfileApproval;
     nicknameCandidates?: string[];
     prompt: string;
@@ -58,6 +60,12 @@ export declare function discoverAgentProfiles(cwd: string, scope?: AgentProfileS
 export declare function builtinAgentProfiles(): AgentProfile[];
 export declare function findAgentProfile(profiles: AgentProfile[], name: string): AgentProfile | undefined;
 export declare function assignAgentNickname(profile: AgentProfile, activeNicknames?: Iterable<string>): string;
+/**
+ * Tool-effect gate as a function of the profile's mode (design §8): readonly
+ * children keep the read-only fence; write_worktree children may edit, write,
+ * and run bash — inside their isolated worktree, never the parent tree.
+ */
+export declare function allowedToolEffectsForMode(mode: AgentProfileMode): Set<string>;
 export declare function selectToolsForAgentProfile(tools: ToolRegistryEntry[], profile: AgentProfile, approval?: AgentProfileApproval): ToolRegistryEntry[];
 export declare function validateAgentProfileTools(tools: ToolRegistryEntry[], profile: AgentProfile, approval?: AgentProfileApproval): AgentProfileDiagnostic[];
 export declare function mergeUsage(current: SubagentRunResult["usage"], usage: TokenUsage): SubagentRunResult["usage"];

package/dist/agent/profiles.js

@@ -15,7 +15,16 @@ const READONLY_PRESET = [
     "skill",
     "todo_write",
 ];
-const SUBAGENT_DENY_TOOLS = new Set(["subagent", "task", "spawn_agent", "wait_agent", "send_input", "close_agent"]);
+const SUBAGENT_DENY_TOOLS = new Set([
+    "subagent",
+    "task",
+    "spawn_agent",
+    "wait_agent",
+    "send_input",
+    "close_agent",
+    "list_agents",
+    "agent_team",
+]);
 const DEFAULT_NICKNAME_CANDIDATES = [
     "Ada",
     "Alan",
@@ -146,6 +155,16 @@ export function assignAgentNickname(profile, activeNicknames = []) {
     }
     return pool[randomInt(pool.length)];
 }
+/**
+ * Tool-effect gate as a function of the profile's mode (design §8): readonly
+ * children keep the read-only fence; write_worktree children may edit, write,
+ * and run bash — inside their isolated worktree, never the parent tree.
+ */
+export function allowedToolEffectsForMode(mode) {
+    return mode === "write_worktree"
+        ? new Set(["read", "write_direct", "write_patch", "unknown"])
+        : new Set(["read"]);
+}
 export function selectToolsForAgentProfile(tools, profile, approval = profile.approval) {
     const explicitInclude = new Set(profile.tools.include ?? []);
     const selected = requestedToolNames(profile);
@@ -170,13 +189,14 @@ export function selectToolsForAgentProfile(tools, profile, approval = profile.ap
 export function validateAgentProfileTools(tools, profile, approval = profile.approval) {
     const available = new Map(tools.map((tool) => [tool.name, tool]));
     const explicitInclude = new Set(profile.tools.include ?? []);
+    const allowedEffects = allowedToolEffectsForMode(profile.mode);
     const diagnostics = [];
     for (const name of requestedToolNames(profile)) {
         if (SUBAGENT_DENY_TOOLS.has(name)) {
             diagnostics.push({
                 severity: "error",
                 toolName: name,
-                message: `Tool "${name}" is not allowed inside subagents because recursive delegation is disabled in Phase 1.`,
+                message: `Tool "${name}" is not allowed inside subagents because recursive delegation is disabled.`,
             });
             continue;
         }
@@ -192,14 +212,15 @@ export function validateAgentProfileTools(tools, profile, approval = profile.app
             continue;
         }
         const effect = tool.effect ?? "unknown";
-        if (effect !== "read") {
+        if (!allowedEffects.has(effect)) {
             diagnostics.push({
                 severity: "error",
                 toolName: name,
-                message: `Tool "${name}" has effect "${effect}" and cannot run in Phase 1 read-only subagents.`,
+                message: `Tool "${name}" has effect "${effect}" and cannot run in ${profile.mode} subagents.`,
             });
         }
-        else if (approval === "disabled" && tool.requiresApproval) {
+        else if (profile.mode === "readonly" && approval === "disabled" && tool.requiresApproval) {
+            // write_worktree children use the worktree approval policy instead.
             diagnostics.push({
                 severity: "warning",
                 toolName: name,
@@ -299,6 +320,7 @@ function parseAgentProfileFile(raw, source, filePath) {
         category: stringValue(frontmatter.category),
         tools: toolsValue(frontmatter.tools),
         maxTurns: numberValue(frontmatter.maxTurns),
+        maxTokens: numberValue(frontmatter.maxTokens),
         approval: approvalValue(frontmatter.approval),
         nicknameCandidates: stringArray(frontmatter.nicknameCandidates) ?? stringArray(frontmatter.nicknames),
         prompt: parsed.body.trim(),

package/dist/agent/result-integrator.d.ts

@@ -0,0 +1,22 @@
+/**
+ * ResultIntegrator — turns background child completions into ingestion
+ * notices injected before the parent's next inference turn (design doc §5).
+ *
+ * Injection marks the child as delivered (§3.3), so the lifecycle reminder
+ * demotes it to a one-liner and the same summary never appears twice in full
+ * form in the parent transcript.
+ */
+import type { SubagentThreadRecord } from "./subagent-control.js";
+import type { SubagentStore } from "./subagent-store.js";
+export declare class ResultIntegrator {
+    private readonly pending;
+    enqueue(agentId: string): void;
+    hasPending(): boolean;
+    /**
+     * Builds notices for children whose results have not yet reached parent
+     * context, marking them delivered. Already-delivered children (e.g. the
+     * model wait_agent-ed first) are skipped silently.
+     */
+    drainNotices(store: SubagentStore, now?: number): string[];
+}
+export declare function buildIngestionNotice(record: SubagentThreadRecord): string;

package/dist/agent/result-integrator.js

@@ -0,0 +1,50 @@
+/**
+ * ResultIntegrator — turns background child completions into ingestion
+ * notices injected before the parent's next inference turn (design doc §5).
+ *
+ * Injection marks the child as delivered (§3.3), so the lifecycle reminder
+ * demotes it to a one-liner and the same summary never appears twice in full
+ * form in the parent transcript.
+ */
+import { fenceChildOutput } from "./subagent-summary.js";
+export class ResultIntegrator {
+    pending = [];
+    enqueue(agentId) {
+        if (!this.pending.includes(agentId)) {
+            this.pending.push(agentId);
+        }
+    }
+    hasPending() {
+        return this.pending.length > 0;
+    }
+    /**
+     * Builds notices for children whose results have not yet reached parent
+     * context, marking them delivered. Already-delivered children (e.g. the
+     * model wait_agent-ed first) are skipped silently.
+     */
+    drainNotices(store, now = Date.now()) {
+        const ids = this.pending.splice(0, this.pending.length);
+        const notices = [];
+        for (const id of ids) {
+            const record = store.get(id);
+            if (!record || record.deliveredAt !== undefined)
+                continue;
+            notices.push(buildIngestionNotice(record));
+            store.markDelivered(id, now);
+        }
+        return notices;
+    }
+}
+export function buildIngestionNotice(record) {
+    const lines = [
+        `subagent ${record.nickname} (agent_id: ${record.agentId}) ${record.status}.`,
+    ];
+    if (record.error) {
+        lines.push(`error: ${record.error}`);
+    }
+    if (record.summary) {
+        lines.push(fenceChildOutput(record.summary));
+    }
+    lines.push("Full result via wait_agent. Do not redo this delegated work.");
+    return lines.join("\n");
+}

package/dist/agent/subagent-control.d.ts

@@ -1,7 +1,24 @@
 import type { AgentProfile, AgentProfileSource, SubagentRunResult } from "./profiles.js";
 import type { ResolvedSubagentRoute } from "./categories.js";
+import type { SubagentWorktree } from "./worktree.js";
 import type { AgentEvent, ContentPart, Message, ToolUpdate } from "../types.js";
 export type SubagentThreadStatus = "queued" | "running" | "completed" | "failed" | "blocked" | "cancelled" | "closed";
+/**
+ * Why a child run ended. Drives the `resumable` flag and the guidance line
+ * rendered in lifecycle tool replies (design doc §3.1) — a resume hint is
+ * emitted iff the runtime judged the run resumable, never as a blanket string.
+ */
+export type SubagentFinalReason = "completed" | "failed_transient" | "failed_fatal" | "rate_limited_exhausted" | "blocked" | "cancelled_interrupt" | "cancelled_user" | "cancelled_budget" | "cancelled_parent_abort";
+export declare function isResumableReason(reason: SubagentFinalReason): boolean;
+/** Per-child token budget, fixed at dispatch time (design doc §6). */
+export interface SubagentTokenCap {
+    /** Soft cap: crossing it injects a wrap-up reminder into the child. */
+    soft: number;
+    /** Hard cap: crossing it aborts this child only. Updated at turn checks. */
+    hard: number;
+    /** Ledger tokens already attributed to this child when the run started. */
+    baseline: number;
+}
 export interface SubagentThreadSnapshot {
     agentId: string;
     runId: string;
@@ -11,6 +28,8 @@ export interface SubagentThreadSnapshot {
     category?: string;
     route?: ResolvedSubagentRoute;
     status: SubagentThreadStatus;
+    finalReason?: SubagentFinalReason;
+    resumable?: boolean;
     task: string;
     summary: string;
     toolNotes: string[];
@@ -18,6 +37,12 @@ export interface SubagentThreadSnapshot {
     error?: string;
     createdAt: number;
     updatedAt: number;
+    deliveredAt?: number;
+    /** 1-based position in the scheduler queue while status is "queued". */
+    queuePosition?: number;
+    tokenCap?: SubagentTokenCap;
+    /** Present for write_worktree children: where the isolated checkout lives. */
+    worktree?: SubagentWorktree;
 }
 export interface SubagentThreadRecord {
     agentId: string;
@@ -29,6 +54,7 @@ export interface SubagentThreadRecord {
     parentToolCallId: string;
     parentToolName: string;
     status: SubagentThreadStatus;
+    finalReason?: SubagentFinalReason;
     task: string;
     summary: string;
     toolNotes: string[];
@@ -36,6 +62,9 @@ export interface SubagentThreadRecord {
     error?: string;
     createdAt: number;
     updatedAt: number;
+    deliveredAt?: number;
+    tokenCap?: SubagentTokenCap;
+    worktree?: SubagentWorktree;
     abortController: AbortController;
     waiters: Set<() => void>;
     agent?: {
@@ -43,6 +72,7 @@ export interface SubagentThreadRecord {
         injectSystemReminder(content: string): void;
         run(input: string | ContentPart[], cwd: string, options?: {
             abortSignal?: AbortSignal;
+            resumeWithoutInput?: boolean;
         }): AsyncIterable<AgentEvent>;
     };
     messages?: Message[];
@@ -55,3 +85,4 @@ export interface PendingSubagentToolUpdate {
 }
 export declare function snapshotSubagentThread(record: SubagentThreadRecord): SubagentThreadSnapshot;
 export declare function subagentResultFromThread(record: SubagentThreadRecord): SubagentRunResult;
+export declare function isFinalSubagentThreadStatus(status: SubagentThreadStatus): boolean;

package/dist/agent/subagent-control.js

@@ -1,3 +1,18 @@
+export function isResumableReason(reason) {
+    switch (reason) {
+        case "failed_transient":
+        case "rate_limited_exhausted":
+        case "cancelled_interrupt":
+        case "cancelled_user":
+        case "cancelled_parent_abort":
+            return true;
+        case "completed":
+        case "failed_fatal":
+        case "blocked":
+        case "cancelled_budget":
+            return false;
+    }
+}
 export function snapshotSubagentThread(record) {
     return {
         agentId: record.agentId,
@@ -8,6 +23,8 @@ export function snapshotSubagentThread(record) {
         category: record.category,
         route: record.route,
         status: record.status,
+        finalReason: record.finalReason,
+        resumable: record.finalReason !== undefined ? isResumableReason(record.finalReason) : undefined,
         task: record.task,
         summary: record.summary,
         toolNotes: [...record.toolNotes],
@@ -15,6 +32,9 @@ export function snapshotSubagentThread(record) {
         error: record.error,
         createdAt: record.createdAt,
         updatedAt: record.updatedAt,
+        deliveredAt: record.deliveredAt,
+        tokenCap: record.tokenCap ? { ...record.tokenCap } : undefined,
+        worktree: record.worktree ? { ...record.worktree } : undefined,
     };
 }
 export function subagentResultFromThread(record) {
@@ -40,3 +60,10 @@ export function subagentResultFromThread(record) {
         error: record.error,
     };
 }
+export function isFinalSubagentThreadStatus(status) {
+    return status === "completed"
+        || status === "failed"
+        || status === "blocked"
+        || status === "cancelled"
+        || status === "closed";
+}