@bubblebrain-ai/bubble 0.0.21 → 0.0.22

package/dist/agent/abort-errors.d.ts

@@ -0,0 +1,14 @@
+export declare class AgentAbortError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Abort tagged with why the runtime stopped a child, so finalization can map
+ * it to a SubagentFinalReason (design doc §3.1) instead of guessing from
+ * message strings.
+ */
+export declare class SubagentAbortError extends AgentAbortError {
+    readonly subagentReason: "interrupt" | "user_close" | "budget";
+    constructor(message: string, subagentReason: "interrupt" | "user_close" | "budget");
+}
+/** Shown when the model produced no user-visible content despite recovery attempts. */
+export declare const EMPTY_ASSISTANT_FALLBACK = "The model returned no user-visible response. Please retry, or switch models if this keeps happening.";

package/dist/agent/abort-errors.js

@@ -0,0 +1,21 @@
+export class AgentAbortError extends Error {
+    constructor(message = "Agent run cancelled.") {
+        super(message);
+        this.name = "AgentAbortError";
+    }
+}
+/**
+ * Abort tagged with why the runtime stopped a child, so finalization can map
+ * it to a SubagentFinalReason (design doc §3.1) instead of guessing from
+ * message strings.
+ */
+export class SubagentAbortError extends AgentAbortError {
+    subagentReason;
+    constructor(message, subagentReason) {
+        super(message);
+        this.subagentReason = subagentReason;
+        this.name = "SubagentAbortError";
+    }
+}
+/** Shown when the model produced no user-visible content despite recovery attempts. */
+export const EMPTY_ASSISTANT_FALLBACK = "The model returned no user-visible response. Please retry, or switch models if this keeps happening.";

package/dist/agent/budget-ledger.d.ts

@@ -1,4 +1,5 @@
 import type { TokenUsage } from "../types.js";
+import type { SubagentTokenCap } from "./subagent-control.js";
 export interface BudgetUsageSource {
     runId: string;
     subAgentId?: string;
@@ -8,13 +9,53 @@ export interface BudgetSnapshot {
     limit?: number;
     exhausted: boolean;
 }
+/**
+ * Shared token ledger for a parent and all of its children, with per-source
+ * accounting so the runtime can enforce per-child caps (design doc §6).
+ * The shared pool limit is optional — both production hosts construct the
+ * ledger without one — so per-child caps must never be derived solely from
+ * "pool remaining"; see computeChildTokenCap.
+ */
 export declare class BudgetLedger {
     private readonly limit?;
     private spent;
+    private readonly spentBySource;
     private readonly controller;
     constructor(limit?: number | undefined);
     get signal(): AbortSignal;
     recordUsage(usage: TokenUsage, source: BudgetUsageSource): void;
+    /** Tokens attributed to one child (or the parent when subAgentId is omitted). */
+    spentBy(subAgentId?: string): number;
+    /** Pool tokens remaining, or undefined when the pool has no limit. */
+    remaining(): number | undefined;
+    get poolLimit(): number | undefined;
     snapshot(): BudgetSnapshot;
 }
+/** Default absolute per-child soft cap; applies even on limit-free hosts. */
+export declare const DEFAULT_CHILD_TOKEN_CAP = 200000;
+/** Share of a limited pool reserved for the parent's own turns. */
+export declare const PARENT_POOL_RESERVE_RATIO = 0.2;
+/** Hard cap sits at least this many tokens above the soft cap (≈ 2 turns). */
+export declare const CHILD_HARD_CAP_FLOOR = 20000;
+/**
+ * Per-child token cap, fixed at dispatch (design doc §6). The soft cap is an
+ * absolute number (config default 200k) so it is effective on limit-free
+ * hosts; when the pool *is* limited, the fair share of what remains after the
+ * parent's reserve further bounds it. The cap never shrinks mid-run because
+ * siblings spawned later.
+ */
+export declare function computeChildTokenCap(options: {
+    ledger?: BudgetLedger;
+    subAgentId: string;
+    activeChildren: number;
+    configCap?: number;
+    profileMaxTokens?: number;
+}): SubagentTokenCap;
+/**
+ * Hard cap recomputed at each turn-boundary check: at least ~2 of this
+ * child's average turns above the soft cap, never below the absolute floor
+ * (design doc §6 — replaces the fixed 25% ratio that could be smaller than a
+ * single turn).
+ */
+export declare function childHardCap(soft: number, avgTurnTokens: number): number;
 export declare function composeAbortSignals(signals: Array<AbortSignal | undefined>): AbortSignal | undefined;

package/dist/agent/budget-ledger.js

@@ -1,6 +1,15 @@
+const PARENT_SOURCE_KEY = "__parent__";
+/**
+ * Shared token ledger for a parent and all of its children, with per-source
+ * accounting so the runtime can enforce per-child caps (design doc §6).
+ * The shared pool limit is optional — both production hosts construct the
+ * ledger without one — so per-child caps must never be derived solely from
+ * "pool remaining"; see computeChildTokenCap.
+ */
 export class BudgetLedger {
     limit;
     spent = 0;
+    spentBySource = new Map();
     controller = new AbortController();
     constructor(limit) {
         this.limit = limit;
@@ -11,10 +20,25 @@ export class BudgetLedger {
     recordUsage(usage, source) {
         const delta = usage.promptTokens + usage.completionTokens;
         this.spent += delta;
+        const key = source.subAgentId ?? PARENT_SOURCE_KEY;
+        this.spentBySource.set(key, (this.spentBySource.get(key) ?? 0) + delta);
         if (this.limit !== undefined && this.spent >= this.limit && !this.controller.signal.aborted) {
             this.controller.abort(budgetAbortError("Budget exhausted"));
         }
     }
+    /** Tokens attributed to one child (or the parent when subAgentId is omitted). */
+    spentBy(subAgentId) {
+        return this.spentBySource.get(subAgentId ?? PARENT_SOURCE_KEY) ?? 0;
+    }
+    /** Pool tokens remaining, or undefined when the pool has no limit. */
+    remaining() {
+        if (this.limit === undefined)
+            return undefined;
+        return Math.max(0, this.limit - this.spent);
+    }
+    get poolLimit() {
+        return this.limit;
+    }
     snapshot() {
         return {
             spent: this.spent,
@@ -23,6 +47,46 @@ export class BudgetLedger {
         };
     }
 }
+/** Default absolute per-child soft cap; applies even on limit-free hosts. */
+export const DEFAULT_CHILD_TOKEN_CAP = 200_000;
+/** Share of a limited pool reserved for the parent's own turns. */
+export const PARENT_POOL_RESERVE_RATIO = 0.2;
+/** Hard cap sits at least this many tokens above the soft cap (≈ 2 turns). */
+export const CHILD_HARD_CAP_FLOOR = 20_000;
+/**
+ * Per-child token cap, fixed at dispatch (design doc §6). The soft cap is an
+ * absolute number (config default 200k) so it is effective on limit-free
+ * hosts; when the pool *is* limited, the fair share of what remains after the
+ * parent's reserve further bounds it. The cap never shrinks mid-run because
+ * siblings spawned later.
+ */
+export function computeChildTokenCap(options) {
+    let soft = options.configCap ?? DEFAULT_CHILD_TOKEN_CAP;
+    if (options.profileMaxTokens !== undefined && options.profileMaxTokens > 0) {
+        soft = Math.min(soft, options.profileMaxTokens);
+    }
+    const limit = options.ledger?.poolLimit;
+    if (options.ledger && limit !== undefined) {
+        const reserve = Math.floor(limit * PARENT_POOL_RESERVE_RATIO);
+        const available = Math.max(0, (options.ledger.remaining() ?? 0) - reserve);
+        const share = Math.floor(available / (options.activeChildren + 1));
+        soft = Math.max(1, Math.min(soft, share));
+    }
+    return {
+        soft,
+        hard: soft + CHILD_HARD_CAP_FLOOR,
+        baseline: options.ledger?.spentBy(options.subAgentId) ?? 0,
+    };
+}
+/**
+ * Hard cap recomputed at each turn-boundary check: at least ~2 of this
+ * child's average turns above the soft cap, never below the absolute floor
+ * (design doc §6 — replaces the fixed 25% ratio that could be smaller than a
+ * single turn).
+ */
+export function childHardCap(soft, avgTurnTokens) {
+    return soft + Math.max(CHILD_HARD_CAP_FLOOR, Math.ceil(avgTurnTokens * 2));
+}
 function budgetAbortError(message) {
     const error = new Error(message);
     error.name = "AbortError";

package/dist/agent/child-runner.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 { BudgetLedger } from "./budget-ledger.js";
+import type { SubagentRunOutcome } from "./subagent-scheduler.js";
+import type { SubagentFinalReason, SubagentThreadRecord } from "./subagent-control.js";
+import type { AgentEvent, Message, ToolRegistryEntry, ToolUpdate } from "../types.js";
+export interface ChildRunOptions {
+    approval: "fail" | "disabled";
+    abortSignal?: AbortSignal;
+    forkContext?: boolean;
+    directEmit?: (update: ToolUpdate) => void;
+    queueUpdates?: boolean;
+    reuseAgent?: boolean;
+    /** 1-based scheduler attempt; >1 means rate-limit re-entry of the same logical run. */
+    attempt?: number;
+}
+export interface ChildRunnerHost {
+    allTools(): ToolRegistryEntry[];
+    budgetLedger(): BudgetLedger | undefined;
+    emit(record: SubagentThreadRecord, options: ChildRunOptions, status: ToolUpdate["status"], event?: AgentEvent, message?: string): void;
+    runLifecycleHook(record: SubagentThreadRecord, cwd: string, eventName: "SubagentStart" | "SubagentStop", status?: string, error?: string, abortSignal?: AbortSignal): Promise<void>;
+    finalizeBlocked(record: SubagentThreadRecord, error: string, options: ChildRunOptions): void;
+    createInstance(record: SubagentThreadRecord, tools: ToolRegistryEntry[], cwd: string, forkContext?: boolean): Promise<NonNullable<SubagentThreadRecord["agent"]>>;
+    notifyWaiters(record: SubagentThreadRecord): void;
+    /** Called on every final state so background results can be ingested (§5). */
+    onFinal(record: SubagentThreadRecord, options: ChildRunOptions): void;
+}
+export declare class ChildRunner {
+    private readonly host;
+    constructor(host: ChildRunnerHost);
+    run(record: SubagentThreadRecord, input: string | import("../types.js").ContentPart[], cwd: string, options: ChildRunOptions): Promise<SubagentRunOutcome>;
+    private runFinalSummaryTurn;
+}
+export declare function sanitizeSubagentSummary(value: string): string;
+/**
+ * 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 declare function needsExplicitFinalSummary(record: SubagentThreadRecord, executedAnyTool: boolean): boolean;
+export declare function classifySubagentAbortReason(reason: unknown, parentSignal: AbortSignal | undefined, ledger: BudgetLedger | undefined): SubagentFinalReason;
+/**
+ * Drops trailing "[model request interrupted ...]" boundary messages so a
+ * rate-limit re-entry resumes from clean history (design §4.5).
+ */
+export declare function stripTrailingModelInterruptedBoundary(messages: Message[]): void;

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/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(),