@bubblebrain-ai/bubble 0.0.34 → 0.0.36

package/dist/agent.js

@@ -4,6 +4,9 @@
  */
 import { compactMessages } from "./context/compact.js";
 import { randomUUID } from "node:crypto";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getBubbleHome } from "./bubble-home.js";
 import { compactMessagesWithLLM } from "./context/compact-llm.js";
 import { estimateContextTokens, getContextBudget } from "./context/budget.js";
 import { buildContextUsageSnapshot } from "./context/usage.js";
@@ -17,12 +20,15 @@ import { HookBus } from "./orchestrator/hooks.js";
 import { normalizeHookInput, truncateHookText, } from "./hooks/index.js";
 import { createDefaultHooks } from "./orchestrator/default-hooks.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";
+import { getBuiltinModel } from "./model-catalog.js";
+import { getAvailableThinkingLevels, getDefaultThinkingLevel, normalizeInheritedThinkingLevel, normalizeThinkingLevel } from "./variant/variant-resolver.js";
 import { appendOutputSchemaInstructions, buildSchemaCorrectionPrompt, validateStructuredSummary } from "./agent/structured-output.js";
 import { runWorkflow, WorkflowConcurrencyGate } from "./agent/workflow/runtime.js";
-import { buildWorkflowDeliveryNotice } from "./agent/workflow/control.js";
-import { getSubtaskPolicy } from "./agent/subtask-policy.js";
-import { composeAbortSignals, computeChildTokenCap, DEFAULT_CHILD_TOKEN_CAP, PARENT_POOL_RESERVE_RATIO } from "./agent/budget-ledger.js";
-import { assignAgentNickname, builtinAgentProfiles, discoverAgentProfiles, findAgentProfile, validateAgentProfileTools } from "./agent/profiles.js";
+import { buildWorkflowDeliveryNotice, renderWorkflowResultValue } from "./agent/workflow/control.js";
+import { composeAbortSignals } from "./agent/budget-ledger.js";
+import { assignAgentNickname, discoverAgentProfiles, findAgentProfile, validateAgentProfileTools } from "./agent/profiles.js";
 import { snapshotSubagentThread, subagentResultFromThread } from "./agent/subagent-control.js";
 import { SubagentStore } from "./agent/subagent-store.js";
 import { SubagentScheduler } from "./agent/subagent-scheduler.js";
@@ -86,6 +92,10 @@ function agentEventFromHookProgress(event) {
         error: event.error ?? "Hook failed.",
     };
 }
+/** Detector threshold N (design §6): 1–2 strong-model children are often a
+ * deliberate deep side-investigation; at 3+ uniform defaults the odds that
+ * all need frontier capability drop sharply. Revisit against live traces. */
+const ROUTING_REMINDER_THRESHOLD = 3;
 export class Agent {
     messages = [];
     provider;
@@ -116,6 +126,13 @@ export class Agent {
     memoryPrompt;
     fileStateTracker;
     agentCategories;
+    agentRouting;
+    routingSnapshotAccessor;
+    routableModelIndex;
+    /** Detector state (design §6): once per session, absolute defaulted count. */
+    routingReminderFired = false;
+    defaultedRoutingStreak = 0;
+    pendingRoutingReminder;
     providerFactory;
     subagentStore;
     subagentScheduler;
@@ -128,6 +145,14 @@ export class Agent {
     subagentsConfig;
     rateLimitPolicy;
     pendingSubagentUpdates = [];
+    /**
+     * Wakers for tool-execution update loops currently awaiting updates. A
+     * blocking lifecycle tool (wait_workflow / wait_agent) produces no updates of
+     * its own, so without this wake the background children's queued lifecycle
+     * updates sit undrained until the tool settles — the UI would only show
+     * subagent traces after the whole team finished.
+     */
+    subagentUpdateWakers = new Set();
     lastInputTokens = null;
     lastAnchorMessageCount = null;
     constructor(options) {
@@ -155,6 +180,11 @@ export class Agent {
         this.memoryPrompt = options.memoryPrompt;
         this.fileStateTracker = options.fileStateTracker;
         this.agentCategories = options.agentCategories ?? {};
+        this.agentRouting = options.agentRouting
+            ? sanitizeAgentRouting(options.agentRouting)
+            : { ...DEFAULT_AGENT_ROUTING };
+        this.routingSnapshotAccessor = options.routingSnapshot;
+        this.routableModelIndex = options.routableModels;
         this.providerFactory = options.providerFactory;
         this.subagentsConfig = options.subagents ?? {};
         this.rateLimitPolicy = options.rateLimitPolicy;
@@ -179,7 +209,6 @@ export class Agent {
         });
         this.childRunner = new ChildRunner({
             allTools: () => [...this.tools.values()],
-            budgetLedger: () => this.budgetLedger,
             emit: (record, options, status, event, message) => this.emitSubagentLifecycle(record, options, status, event, message),
             runLifecycleHook: (record, cwd, eventName, status, error, abortSignal) => this.runSubagentLifecycleHookFor(record, cwd, eventName, status, error, abortSignal),
             finalizeBlocked: (record, error, options) => this.finalizeSubagentBlocked(record, error, options),
@@ -215,6 +244,16 @@ export class Agent {
         }
         // Advertise any deferred tools so the model knows they exist and how to
         // reach them. Keeps the per-turn tool list small; schemas load on demand.
+        this.injectDeferredToolsReminder();
+    }
+    /**
+     * Re-inject the deferred-tools advertisement. Hosts that reassign
+     * agent.messages (session resume, Feishu conversation rebuild) drop the
+     * constructor-injected meta reminder — without re-injection the model has
+     * no way to discover deferred tools, since they are also filtered out of
+     * the prompt's tool list.
+     */
+    injectDeferredToolsReminder() {
         const deferredNames = [...this.tools.values()]
             .filter((t) => t.deferred)
             .map((t) => t.name);
@@ -269,7 +308,34 @@ export class Agent {
         return [...this.tools.values()].filter((t) => t.deferred);
     }
     getSystemPromptToolOptions() {
-        return buildToolPromptOptions(this.getActiveToolEntries());
+        return {
+            ...buildToolPromptOptions(this.getActiveToolEntries()),
+            // Rendered through the live accessor (design §1.5), so every host-
+            // triggered prompt rebuild picks up the current catalog.
+            modelRoutingPrompt: this.buildModelRoutingPromptSection(),
+        };
+    }
+    /** Current routing menu (design §4); undefined when no accessor is wired. */
+    buildModelRoutingPromptSection() {
+        const snapshot = this.currentRoutingSnapshot();
+        if (!snapshot)
+            return undefined;
+        return buildModelRoutingPrompt(snapshot, this.agentRouting);
+    }
+    /**
+     * Routing menu rendered for a prospective parent route — used by model-
+     * switch transactions to build the NEXT prompt before mutating the agent
+     * (design §1.5).
+     */
+    renderModelRoutingPromptFor(parent) {
+        if (!this.routingSnapshotAccessor)
+            return undefined;
+        try {
+            return buildModelRoutingPrompt(this.routingSnapshotAccessor(parent), this.agentRouting);
+        }
+        catch {
+            return undefined;
+        }
     }
     getContextUsageSnapshot() {
         return buildContextUsageSnapshot({
@@ -388,7 +454,7 @@ export class Agent {
         this.messages.unshift(systemMessage);
     }
     async *run(userInput, cwd, options = {}) {
-        const abortSignal = composeAbortSignals([options.abortSignal, this.budgetLedger?.signal]);
+        const abortSignal = options.abortSignal;
         const inputController = options.inputController;
         const traceContext = {
             cwd,
@@ -699,6 +765,18 @@ export class Agent {
                                 appendProviderContentBlock(assistantMsg, chunk.provider, chunk.block);
                                 break;
                             case "tool_call":
+                                // `toolChoice: "none"` is a governance boundary, not merely a
+                                // provider hint. Ignore any provider-side violation so a forced
+                                // text-only turn can never reach the tool execution path.
+                                if (textOnly) {
+                                    traceEvent("text_only_tool_call_ignored", {
+                                        id: chunk.id,
+                                        name: chunk.name,
+                                        isStart: chunk.isStart,
+                                        isEnd: chunk.isEnd,
+                                    }, traceContext);
+                                    break;
+                                }
                                 if (discoveryBarrier?.isEnabled()
                                     && (bufferedStreamingToolCallIds.has(chunk.id) || discoveryBarrier.shouldBufferStreamingToolCall(chunk.name))) {
                                     bufferedStreamingToolCallIds.add(chunk.id);
@@ -911,14 +989,14 @@ export class Agent {
                         }
                         let tc = parsedCalls[index];
                         let blockedResult;
-                        // agent_team must be the only tool call in its response (design
-                        // §1.2): concurrent calls race the scheduler and the aggregated
-                        // reply; the rejection teaches the model how to re-issue.
-                        if (tc.name === "agent_team" && parsedCalls.length > 1) {
+                        // run_workflow must be the only tool call in its response: it starts
+                        // a background orchestration whose result lands next turn, and
+                        // sibling calls racing it defeat the serialized fan-out contract.
+                        if (tc.name === "run_workflow" && parsedCalls.length > 1) {
                             blockedResult = {
                                 content: [
-                                    "agent_team must be the only tool call in your response.",
-                                    "Re-issue agent_team alone — one call, nothing else in the same message — and run any other tools or additional teams sequentially after it returns.",
+                                    "run_workflow must be the only tool call in your response.",
+                                    "Re-issue run_workflow alone — one call, nothing else in the same message — and run other tools after it returns.",
                                 ].join(" "),
                                 isError: true,
                                 status: "blocked",
@@ -1075,20 +1153,31 @@ export class Agent {
                                 settled = true;
                                 updateQueue.wake();
                             });
-                            while (!settled || updateQueue.hasItems()) {
-                                for (const update of updateQueue.drain()) {
-                                    yield emit({ type: "tool_update", id: tc.id, name: tc.name, update });
-                                }
-                                for (const update of this.drainSubagentToolUpdates())
-                                    yield emit(update);
-                                if (!settled) {
-                                    const waitStatus = await updateQueue.wait(abortSignal);
-                                    if (waitStatus === "aborted" && !settled) {
-                                        cancelledByAbort = true;
-                                        break;
+                            this.subagentUpdateWakers.add(updateQueue.wake);
+                            try {
+                                while (!settled || updateQueue.hasItems() || this.pendingSubagentUpdates.length > 0) {
+                                    for (const update of updateQueue.drain()) {
+                                        yield emit({ type: "tool_update", id: tc.id, name: tc.name, update });
+                                    }
+                                    for (const update of this.drainSubagentToolUpdates())
+                                        yield emit(update);
+                                    // A wake() that fires while this generator is suspended at a
+                                    // yield above finds no parked waiter and is lost (the queue has
+                                    // no wake latch), so re-check the subagent queue synchronously
+                                    // before parking — otherwise an update pushed during the yield
+                                    // stalls until the next unrelated wake or the tool settles.
+                                    if (!settled && this.pendingSubagentUpdates.length === 0) {
+                                        const waitStatus = await updateQueue.wait(abortSignal);
+                                        if (waitStatus === "aborted" && !settled) {
+                                            cancelledByAbort = true;
+                                            break;
+                                        }
                                     }
                                 }
                             }
+                            finally {
+                                this.subagentUpdateWakers.delete(updateQueue.wake);
+                            }
                             if (cancelledByAbort) {
                                 result = cancelledToolResult(tc.name);
                             }
@@ -1398,42 +1487,6 @@ export class Agent {
         // re-injected as a `Previous conversation summary` system message.
         return sanitizeInternalReminderBlocks(full).trim();
     }
-    async runSubtask(input, cwd, options) {
-        const subtaskType = options?.subtaskType;
-        const profile = builtinAgentProfiles().find((item) => item.subtaskType === (subtaskType ?? "general_readonly"))
-            ?? builtinAgentProfiles().find((item) => item.subtaskType === "general_readonly");
-        const run = await this.runSubAgent(input, cwd, {
-            profile,
-            runId: randomUUID(),
-            subAgentId: randomUUID(),
-            parentToolCallId: "task",
-            route: this.resolveRouteForSubagent(profile, undefined),
-            description: options?.description,
-        });
-        const lines = [
-            "Note: task is deprecated. Use spawn_agent with a named profile instead.",
-            `Subtask type: ${profile.subtaskType ?? "general_readonly"}`,
-        ];
-        if (options?.description) {
-            lines.push(`Subtask description: ${options.description}`);
-        }
-        if (run.summary) {
-            lines.push("", "Subtask summary:", run.summary);
-        }
-        if (run.toolNotes.length > 0) {
-            lines.push("", "Subtask tools:", ...run.toolNotes.slice(0, 8).map((note) => `- ${note}`));
-        }
-        return {
-            content: lines.join("\n"),
-            status: getSubtaskPolicy(subtaskType).resultStatus,
-            isError: run.status !== "completed",
-            metadata: {
-                kind: "subagent",
-                reason: `Subtask (${profile.subtaskType ?? "general_readonly"}) investigation completed.`,
-                subagents: [run],
-            },
-        };
-    }
     async runSubAgent(input, cwd, options) {
         const record = this.createSubagentThreadRecord({
             profile: options.profile,
@@ -1462,13 +1515,21 @@ export class Agent {
         return subagentResultFromThread(record);
     }
     async spawnSubAgent(input, cwd, options) {
+        const route = options.route
+            ?? this.resolveRouteForSubagent(options.profile, options.category, { model: options.model, effort: options.effort });
+        // Early validation (design §7): throws reach the model as a tool error it
+        // can correct this turn, instead of a late provider-factory failure.
+        const routeNote = this.validateRouteForDispatch(route);
+        this.noteRoutingDispatch(route);
         const record = this.createSubagentThreadRecord({
             profile: options.profile,
             task: typeof input === "string" ? input : "(multimodal task)",
             parentToolCallId: options.parentToolCallId,
             parentToolName: "spawn_agent",
-            route: options.route ?? this.resolveRouteForSubagent(options.profile, options.category, { model: options.model, effort: options.effort }),
+            route,
         });
+        if (routeNote)
+            record.toolNotes.push(routeNote);
         this.subagentStore.set(record);
         const approval = options.approval ?? record.profile.approval;
         // Admission validation runs before queueing (design §4.2): a request that
@@ -1580,141 +1641,6 @@ export class Agent {
             .filter((record) => !record.workflowInternal)
             .map((record) => this.snapshotSubagent(record));
     }
-    /**
-     * Homogeneous map fan-out (design §1.2): one profile, one template, N items.
-     * Every member goes through the same admission and the same scheduler
-     * dispatch as spawn_agent; the tool blocks until all members are final.
-     */
-    async runAgentTeam(cwd, options) {
-        // Team budget pre-check (§6): items × per-member cap must fit in what
-        // remains of a limited pool after the parent's reserve. On limit-free
-        // hosts the only bound is the items cap enforced by the tool.
-        const limit = this.budgetLedger?.poolLimit;
-        if (this.budgetLedger && limit !== undefined) {
-            const reserve = Math.floor(limit * PARENT_POOL_RESERVE_RATIO);
-            const available = Math.max(0, (this.budgetLedger.remaining() ?? 0) - reserve);
-            const memberCap = Math.min(this.subagentsConfig.childTokenCap ?? DEFAULT_CHILD_TOKEN_CAP, options.profile.maxTokens ?? Number.POSITIVE_INFINITY);
-            const affordable = Math.floor(available / memberCap);
-            if (options.items.length > affordable) {
-                throw new Error([
-                    `agent_team rejected: the remaining token budget affords at most ${affordable} member${affordable === 1 ? "" : "s"}`,
-                    `but ${options.items.length} were requested. Reduce items or run smaller batches sequentially.`,
-                ].join(" "));
-            }
-        }
-        const approval = options.approval ?? options.profile.approval;
-        const route = this.resolveRouteForSubagent(options.profile, options.category, { model: options.model, effort: options.effort });
-        const records = options.items.map((item) => this.createSubagentThreadRecord({
-            profile: options.profile,
-            task: options.promptTemplate.split("{{item}}").join(item),
-            parentToolCallId: options.parentToolCallId,
-            parentToolName: "agent_team",
-            route,
-        }));
-        const promises = records.map((record) => {
-            this.subagentStore.set(record);
-            const admissionError = this.admitSubagentProfile(record, approval);
-            if (admissionError) {
-                this.finalizeSubagentBlocked(record, admissionError, { directEmit: options.emitUpdate });
-                return Promise.resolve();
-            }
-            // Member events flow through the team tool's own emitUpdate
-            // (directEmit): while a foreground tool runs, the parent loop blocks in
-            // updateQueue.wait and the queued channel is not drained until the tool
-            // settles — queueUpdates would freeze the TUI for the whole team (§1.2).
-            record.promise = this.dispatchSubagentRun(record, record.task, cwd, {
-                approval,
-                abortSignal: options.abortSignal,
-                directEmit: options.emitUpdate,
-            });
-            void record.promise.finally(() => this.subagentStore.notifyWaiters(record));
-            return record.promise;
-        });
-        await Promise.all(promises);
-        // The aggregated reply carries every member's full summary.
-        for (const record of records)
-            this.subagentStore.markDelivered(record.agentId);
-        return records.map((record) => this.snapshotSubagent(record));
-    }
-    /**
-     * Heterogeneous fan-out (design v2 §1.3): N independent specs, each with its
-     * own task, profile, and per-call model/effort, dispatched concurrently as a
-     * SINGLE tool call. Unlike runAgentTeam (one template over N items), members
-     * differ. Like the team, every member goes through the same scheduler
-     * dispatch and the tool blocks until all are final, returning in spec order.
-     * Keeping fan-out inside one tool call (rather than N parallel spawn_agent
-     * tool_calls) avoids the provider parallel-tool_call bug (Kimi 400 / lost
-     * responses).
-     */
-    async runAgentBatch(cwd, options) {
-        // Budget pre-check mirrors runAgentTeam: members × per-member cap must fit
-        // in what remains of a limited pool after the parent's reserve.
-        const limit = this.budgetLedger?.poolLimit;
-        if (this.budgetLedger && limit !== undefined) {
-            const reserve = Math.floor(limit * PARENT_POOL_RESERVE_RATIO);
-            const available = Math.max(0, (this.budgetLedger.remaining() ?? 0) - reserve);
-            const memberCap = this.subagentsConfig.childTokenCap ?? DEFAULT_CHILD_TOKEN_CAP;
-            const affordable = Math.floor(available / memberCap);
-            if (options.specs.length > affordable) {
-                throw new Error([
-                    `agent_batch rejected: the remaining token budget affords at most ${affordable} member${affordable === 1 ? "" : "s"}`,
-                    `but ${options.specs.length} were requested. Reduce specs or run smaller batches sequentially.`,
-                ].join(" "));
-            }
-        }
-        const records = options.specs.map((spec) => {
-            const approval = options.approval ?? spec.profile.approval;
-            const task = spec.outputSchema !== undefined
-                ? appendOutputSchemaInstructions(spec.task, spec.outputSchema)
-                : spec.task;
-            const record = this.createSubagentThreadRecord({
-                profile: spec.profile,
-                task,
-                parentToolCallId: options.parentToolCallId,
-                parentToolName: "agent_batch",
-                route: this.resolveRouteForSubagent(spec.profile, spec.category, { model: spec.model, effort: spec.effort }),
-            });
-            return { record, approval, spec };
-        });
-        const promises = records.map(({ record, approval }) => {
-            this.subagentStore.set(record);
-            const admissionError = this.admitSubagentProfile(record, approval);
-            if (admissionError) {
-                this.finalizeSubagentBlocked(record, admissionError, { directEmit: options.emitUpdate });
-                return Promise.resolve();
-            }
-            record.promise = this.dispatchSubagentRun(record, record.task, cwd, {
-                approval,
-                abortSignal: options.abortSignal,
-                directEmit: options.emitUpdate,
-            });
-            void record.promise.finally(() => this.subagentStore.notifyWaiters(record));
-            return record.promise;
-        });
-        await Promise.all(promises);
-        // Structured-output validation + one corrective retry (design v2 §1.2):
-        // a member whose schema'd summary does not validate gets a single
-        // send_input correction, reusing the existing resume path.
-        for (const { record, spec } of records) {
-            if (spec.outputSchema === undefined)
-                continue;
-            if (record.status !== "completed")
-                continue;
-            if (validateStructuredSummary(record.summary, spec.outputSchema).ok)
-                continue;
-            const correction = buildSchemaCorrectionPrompt(spec.outputSchema, record.summary);
-            try {
-                await this.sendSubAgentInput(record.agentId, correction, cwd, { abortSignal: options.abortSignal });
-                await record.promise?.catch(() => undefined);
-            }
-            catch {
-                // resume failed; leave the original summary and surface the mismatch below
-            }
-        }
-        for (const { record } of records)
-            this.subagentStore.markDelivered(record.agentId);
-        return records.map(({ record }) => this.snapshotSubagent(record));
-    }
     /**
      * Dynamic workflow (option C): runs an LLM-authored JS orchestration script in
      * a QuickJS sandbox. Each agent() call in the script becomes a real scheduled
@@ -1732,6 +1658,7 @@ export class Agent {
             parentToolCallId: options.parentToolCallId,
             abortSignal: options.abortSignal,
             directEmit: options.emitUpdate,
+            ensureProfileTrusted: options.ensureProfileTrusted,
         });
     }
     /**
@@ -1766,12 +1693,15 @@ export class Agent {
             parentToolCallId: options.parentToolCallId,
             abortSignal: abortController.signal,
             queueUpdates: true,
+            ensureProfileTrusted: options.ensureProfileTrusted,
         }).then((out) => {
             record.agentCount = out.agentCount;
             record.snapshots = out.snapshots;
             record.logs = out.logs;
             record.result = out.result;
             record.status = out.result.ok ? "completed" : (abortController.signal.aborted ? "cancelled" : "failed");
+            if (out.result.ok)
+                record.resultPath = persistWorkflowResult(runId, out.result.value);
         }, (error) => {
             record.result = { ok: false, error: error?.message || String(error) };
             record.status = "failed";
@@ -1821,6 +1751,7 @@ export class Agent {
             status: record.status,
             agentCount: record.agentCount,
             result: record.result,
+            resultPath: record.resultPath,
             logs: record.logs,
             snapshots: record.snapshots,
         };
@@ -1842,22 +1773,13 @@ export class Agent {
         const profiles = discoverAgentProfiles(cwd, "both").profiles;
         const runRecords = [];
         const logs = [];
-        // Per-run isolation (option C review): a token ceiling that aborts only this
-        // run (never the parent) and a concurrency sub-cap below the global limit so
-        // a workflow can't starve interactive subagents.
-        const poolLimit = this.budgetLedger?.poolLimit;
-        const runTokenCeiling = poolLimit !== undefined
-            ? Math.max(1, Math.floor(poolLimit * (1 - PARENT_POOL_RESERVE_RATIO)))
-            : Number.POSITIVE_INFINITY;
-        const runSpent = () => runRecords.reduce((sum, r) => sum + (r.usage ? r.usage.promptTokens + r.usage.completionTokens : 0), 0);
+        // Per-run isolation (option C review): a concurrency sub-cap below the
+        // global limit so a workflow can't starve interactive subagents.
         const interactiveReserve = 2;
         const globalCap = Math.max(1, this.subagentsConfig.maxActiveSubagents ?? 8);
         const workflowConcurrency = Math.max(1, globalCap - interactiveReserve);
         const gate = new WorkflowConcurrencyGate(workflowConcurrency);
         const dispatchAgent = async (spec) => {
-            if (runSpent() >= runTokenCeiling) {
-                return { ok: false, error: "workflow token ceiling reached; not launching more agents" };
-            }
             const baseProfile = findAgentProfile(profiles, spec.opts.agentType ?? "default")
                 ?? findAgentProfile(profiles, "default");
             if (!baseProfile)
@@ -1875,11 +1797,16 @@ export class Agent {
                 tools: { ...baseProfile.tools, exclude: [...(baseProfile.tools.exclude ?? []), "web_fetch", "web_search"] },
             };
             let route;
+            let routeNote;
             try {
                 route = this.resolveRouteForSubagent(profile, spec.opts.category, {
                     model: spec.opts.model,
                     effort: parseThinkingLevel(spec.opts.effort),
                 });
+                // Dispatch-time validation + defaulted-fan-out accounting (§6–7):
+                // resolved routes, never script source text.
+                routeNote = this.validateRouteForDispatch(route);
+                this.noteRoutingDispatch(route);
             }
             catch (error) {
                 return { ok: false, error: error?.message || String(error) };
@@ -1895,8 +1822,27 @@ export class Agent {
                 route,
                 workflowInternal: true,
             });
+            record.expectsStructuredOutput = spec.opts.schema !== undefined;
+            if (routeNote)
+                record.toolNotes.push(routeNote);
+            const memberLabel = typeof spec.opts.label === "string" ? spec.opts.label.trim().slice(0, 40) : "";
+            if (memberLabel)
+                record.nickname = memberLabel;
             runRecords.push(record);
             this.subagentStore.set(record);
+            // Project-local profiles pass the same first-use trust gate as
+            // spawn_agent: a .bubble/agents profile must never gain a side door
+            // into execution just because a script named it (Codex review on #58).
+            // Checked AFTER the record exists so a rejected member still shows up
+            // in the run's counts/snapshots as blocked instead of vanishing.
+            if (options.ensureProfileTrusted) {
+                const blocked = await options.ensureProfileTrusted(baseProfile);
+                if (blocked) {
+                    const message = typeof blocked.content === "string" ? blocked.content : `profile "${baseProfile.name}" requires user approval`;
+                    this.finalizeSubagentBlocked(record, message, { directEmit: options.directEmit, queueUpdates: options.queueUpdates });
+                    return { ok: false, error: message };
+                }
+            }
             const admissionError = this.admitSubagentProfile(record, profile.approval);
             if (admissionError) {
                 this.finalizeSubagentBlocked(record, admissionError, { directEmit: options.directEmit, queueUpdates: options.queueUpdates });
@@ -1925,8 +1871,11 @@ export class Agent {
                 return { ok: true, value: record.summary };
             }
             // Structured output: validate, one corrective retry, then fall back to raw.
+            // The schema: log lines are the telemetry that decides whether the
+            // deferred terminate-style structured-output tool ever gets reopened.
             let validated = validateStructuredSummary(record.summary, spec.opts.schema);
             if (!validated.ok) {
+                logs.push(`schema: ${record.nickname} first output failed validation; sending one corrective retry`);
                 try {
                     await this.sendSubAgentInput(record.agentId, buildSchemaCorrectionPrompt(spec.opts.schema, record.summary), cwd, { abortSignal: options.abortSignal });
                     await record.promise?.catch(() => undefined);
@@ -1935,6 +1884,9 @@ export class Agent {
                 catch {
                     // resume failed; fall through to raw summary
                 }
+                logs.push(validated.ok
+                    ? `schema: ${record.nickname} corrective retry produced valid output`
+                    : `schema: ${record.nickname} corrective retry still invalid; returning raw summary`);
             }
             return { ok: true, value: validated.ok ? validated.value : record.summary };
         };
@@ -1945,14 +1897,11 @@ export class Agent {
             onLog: (message) => logs.push(message),
             onPhase: (title) => logs.push(`— phase: ${title} —`),
             budget: {
-                total: this.budgetLedger?.poolLimit ?? null,
+                // The ledger is pure accounting (no pool limit); scripts see an
+                // unlimited budget unless a future host contract reintroduces one.
+                total: null,
                 spent: () => runRecords.reduce((sum, r) => sum + (r.usage ? r.usage.promptTokens + r.usage.completionTokens : 0), 0),
-                remaining: () => {
-                    const limit = this.budgetLedger?.poolLimit;
-                    if (limit === undefined)
-                        return Number.POSITIVE_INFINITY;
-                    return Math.max(0, (this.budgetLedger?.remaining() ?? 0));
-                },
+                remaining: () => Number.POSITIVE_INFINITY,
             },
             signal: options.abortSignal,
         });
@@ -2013,13 +1962,6 @@ export class Agent {
     dispatchSubagentRun(record, input, cwd, options) {
         record.status = "queued";
         record.updatedAt = Date.now();
-        record.tokenCap = computeChildTokenCap({
-            ledger: this.budgetLedger,
-            subAgentId: record.agentId,
-            activeChildren: this.subagentScheduler.activeCount(),
-            configCap: this.subagentsConfig.childTokenCap,
-            profileMaxTokens: record.profile.maxTokens,
-        });
         const queueSignal = composeAbortSignals([options.abortSignal, record.abortController.signal]);
         return this.subagentScheduler.dispatch({
             agentId: record.agentId,
@@ -2028,7 +1970,7 @@ export class Agent {
             run: (ctx) => this.runSubagentThread(record, input, cwd, { ...options, attempt: ctx.attempt }),
             onCancelledWhileQueued: (reason) => {
                 record.status = "cancelled";
-                record.finalReason = classifySubagentAbortReason(reason, options.abortSignal, this.budgetLedger);
+                record.finalReason = classifySubagentAbortReason(reason, options.abortSignal);
                 record.error = reason instanceof Error ? reason.message : reason ? String(reason) : "Cancelled while queued.";
                 record.updatedAt = Date.now();
                 // The run never started, so no SubagentStart fired and no SubagentStop follows.
@@ -2068,8 +2010,14 @@ export class Agent {
         options.directEmit?.(update);
         if (options.queueUpdates) {
             this.pendingSubagentUpdates.push({ id: record.parentToolCallId, name: record.parentToolName, update });
+            this.wakeSubagentUpdateWaiters();
         }
     }
+    /** Lets a blocked tool-execution loop drain freshly queued subagent updates. */
+    wakeSubagentUpdateWaiters() {
+        for (const wake of this.subagentUpdateWakers)
+            wake();
+    }
     async runSubagentLifecycleHookFor(record, cwd, eventName, status, error, abortSignal) {
         try {
             await this.runExternalHook({
@@ -2102,30 +2050,186 @@ export class Agent {
             model: this.apiModel,
             thinkingLevel: this.thinkingLevel,
         };
-        const resolved = resolveSubagentRoute(category ?? profile.category, {
-            ...parentRoute,
-        }, this.agentCategories);
+        const snapshot = this.currentRoutingSnapshot();
+        const resolved = resolveSubagentRoute(category ?? profile.category, { ...parentRoute }, this.agentCategories, snapshot ? tierContextFromSnapshot(snapshot, this.agentRouting) : undefined);
         if ("error" in resolved) {
             throw new Error(resolved.error);
         }
         let route = resolved.route;
+        // modelSource is assigned while applying the chain (design §3.4): an
+        // explicit layer naming the parent's own model is indistinguishable from
+        // inherit by final-value comparison, yet carries different authority.
+        let modelSource = route.categoryModelSource ?? "inherit";
         if (profile.model && profile.model !== "inherit") {
             const model = resolveModelRoute(profile.model, parentRoute.providerId);
             if (model.model !== "inherit") {
                 route = { ...route, providerId: model.providerId, model: model.model, inherited: false };
+                modelSource = "profile";
             }
         }
-        // Call-site override beats profile and category.
+        // Call-site override beats profile and category. Bare names resolve
+        // against the PARENT provider per the tool contract (design §3.5) — not
+        // against a provider that category/profile may already have switched.
         if (override?.model) {
-            const model = resolveModelRoute(override.model, route.providerId);
+            const model = resolveModelRoute(override.model, parentRoute.providerId);
             if (model.model !== "inherit") {
                 route = { ...route, providerId: model.providerId, model: model.model, inherited: false };
+                modelSource = "callsite";
             }
         }
+        const supportedLevels = getAvailableThinkingLevels(route.providerId, route.model);
+        const modelMetadata = getBuiltinModel(route.providerId, route.model);
+        const hasTrustedEffortMetadata = !!modelMetadata
+            && modelMetadata.reasoningLevels.some((level) => level !== "off");
         if (override?.effort) {
-            route = { ...route, thinkingLevel: override.effort, inherited: false };
+            // A call-site effort is explicit user/model intent: preserve the existing
+            // value for legacy/unknown models, and downward-clamp only when the
+            // catalog declares real effort capabilities (for example Luna ultra -> max).
+            route = {
+                ...route,
+                thinkingLevel: hasTrustedEffortMetadata
+                    ? normalizeThinkingLevel(override.effort, supportedLevels)
+                    : override.effort,
+                inherited: false,
+            };
+        }
+        else if (hasTrustedEffortMetadata) {
+            const categoryThinkingLevel = route.category
+                ? mergeAgentCategories(this.agentCategories)[route.category]?.thinkingLevel
+                : undefined;
+            // A category's thinkingLevel is calibrated for the model the CATEGORY
+            // resolved. When a later layer (profile/call-site) replaced the model,
+            // that level is no longer explicit intent for the final model: keep it
+            // only if supported, else use the final model's own default — never
+            // downward-clamp a thinking-default model to "off" (v3.6; live case:
+            // explore's "low" + call-site glm-5.2 [high/max/off] silently landed
+            // on "off").
+            const modelReplacedAfterCategory = modelSource === "profile" || modelSource === "callsite";
+            route = {
+                ...route,
+                thinkingLevel: categoryThinkingLevel
+                    ? (modelReplacedAfterCategory && !supportedLevels.includes(route.thinkingLevel)
+                        ? getDefaultThinkingLevel(route.providerId, route.model)
+                        : normalizeThinkingLevel(route.thinkingLevel, supportedLevels))
+                    : normalizeInheritedThinkingLevel(route.providerId, route.model, route.thinkingLevel),
+            };
+        }
+        return {
+            ...route,
+            modelSource,
+            modelInherited: route.providerId === parentRoute.providerId && route.model === parentRoute.model,
+        };
+    }
+    /** Live snapshot for the CURRENT parent route; undefined when no accessor is wired. */
+    currentRoutingSnapshot() {
+        if (!this.routingSnapshotAccessor)
+            return undefined;
+        try {
+            return this.routingSnapshotAccessor({ providerId: this.providerId, model: this.apiModel });
+        }
+        catch {
+            // Catalog data is an enhancement, never a spawn blocker.
+            return undefined;
+        }
+    }
+    /**
+     * Early route validation at dispatch time (design §7). Throws with an
+     * actionable message so the model self-corrects in the same turn. The
+     * cross-provider lock (§7.2.1) is snapshot-independent; catalog checks
+     * degrade silently when no snapshot is available (§7.0).
+     */
+    validateRouteForDispatch(route) {
+        const snapshot = this.currentRoutingSnapshot();
+        const crossProvider = !!route.providerId && route.providerId !== this.providerId;
+        if (crossProvider) {
+            // §7.2.1 — the lock. Profile/user-category routes are standing user
+            // authorization and always pass; only call-site routes are lockable.
+            if (!this.agentRouting.allowCrossProvider && route.modelSource === "callsite") {
+                throw new Error("Cross-provider routing is disabled in this session's config (agentRouting.allowCrossProvider). "
+                    + "Use a model from the parent provider, or ask the user to unlock cross-provider routing.");
+            }
+            // §7.2.2 — credentials, when a snapshot is available.
+            if (snapshot && !snapshot.runnableProviderIds.includes(route.providerId)) {
+                throw new Error(`Provider "${route.providerId}" is not configured with active credentials. `
+                    + `Available: ${snapshot.runnableProviderIds.join(", ") || "(none)"}.`);
+            }
+            // §7.2.3 amended (v3.6): the provider stays the authority — no hard
+            // catalog rejection — but a near-match against the target provider's
+            // local catalog is positive evidence of a mistyped id (a Grok parent
+            // invented "openai:gpt-5.6" for gpt-5.6-sol), so soft-reject with the
+            // correction and let the model fix it this turn. Genuinely unknown ids
+            // (no near candidates) still pass through with a note.
+            const targetCatalog = this.routableModelIndex?.()
+                .filter((entry) => entry.providerId === route.providerId) ?? [];
+            if (targetCatalog.length > 0 && !targetCatalog.some((entry) => entry.id === route.model)) {
+                const near = nearModelMatches(route.model, targetCatalog, { mode: "truncation" });
+                if (near.length > 0) {
+                    throw new Error(`Unknown model "${route.model}" for provider "${route.providerId}". Did you mean: ${near.join(", ")}?`);
+                }
+                return `model ${route.providerId}:${route.model} is not in the local catalog; the provider validates it`;
+            }
+            return `model ${route.providerId}:${route.model} is not locally verifiable; the provider validates it`;
+        }
+        // §7.1 — same-provider unknown model, resolved-provider based (never
+        // input-syntax based; qualified same-provider ids land here too).
+        if (snapshot && route.modelSource === "callsite") {
+            const known = snapshot.models.some((model) => model.id === route.model);
+            if (!known) {
+                if (snapshot.authoritative) {
+                    const available = snapshot.models
+                        .map((model) => (model.tier ? `${model.id} (${model.tier})` : model.id))
+                        .join(", ");
+                    throw new Error(`Unknown model "${route.model}" for provider "${this.providerId}". Available: ${available}.`);
+                }
+                const near = nearModelMatches(route.model, snapshot.models.map((model) => ({ providerId: this.providerId, id: model.id, name: model.name })));
+                return near.length > 0
+                    ? `model id "${route.model}" is unrecognized locally (did you mean: ${near.join(", ")}?); the provider validates it`
+                    : `model id "${route.model}" is unrecognized locally; the provider validates it`;
+            }
+        }
+        return undefined;
+    }
+    /** Routable catalog across runnable providers (design v3.6); undefined when unwired. */
+    listRoutableModels() {
+        try {
+            return this.routableModelIndex?.();
+        }
+        catch {
+            return undefined;
         }
-        return route;
+    }
+    /**
+     * Decision-point detector (design §6): counts dispatches whose model was
+     * decided by NO routing layer (modelSource "inherit") under a strong-tier
+     * parent. Fires once per session at the Nth qualifying dispatch; the
+     * reminder rides the same channel as the lifecycle reminder.
+     */
+    noteRoutingDispatch(route) {
+        if (this.routingReminderFired)
+            return;
+        if (route.modelSource !== "inherit")
+            return;
+        const snapshot = this.currentRoutingSnapshot();
+        if (snapshot?.parent.tier !== "strong")
+            return;
+        this.defaultedRoutingStreak++;
+        if (this.defaultedRoutingStreak >= ROUTING_REMINDER_THRESHOLD) {
+            this.routingReminderFired = true;
+            this.pendingRoutingReminder = [
+                `Routing note: ${this.defaultedRoutingStreak} children in this fan-out defaulted to the parent's`,
+                "strong-tier model (no model/category given). If any of these tasks are mechanical",
+                "(scan / summarize / search / extract), route them with category \"quick\"/\"explore\" or a",
+                "fast-tier model next time. If they genuinely need this model, ignore this note.",
+            ].join(" ");
+        }
+    }
+    /** Consumed by the turn hooks; also closes the counting window (§6). */
+    consumePendingRoutingReminder() {
+        const reminder = this.pendingRoutingReminder;
+        this.pendingRoutingReminder = undefined;
+        if (!this.routingReminderFired)
+            this.defaultedRoutingStreak = 0;
+        return reminder;
     }
     createSubagentThreadRecord(options) {
         const now = Date.now();
@@ -2190,7 +2294,7 @@ export class Agent {
             mode: childMode,
             workingDir: childCwd,
             ...buildToolPromptOptions(tools),
-            memoryPrompt: childToolNames.some((name) => name === "memory_search" || name === "memory_read_summary")
+            memoryPrompt: childToolNames.some((name) => name === "memory")
                 ? this.memoryPrompt
                 : undefined,
             agentProfilePrompt: [
@@ -2309,6 +2413,7 @@ export class Agent {
             name: record.parentToolName,
             update: this.buildSubagentUpdate(record, status, event, message),
         });
+        this.wakeSubagentUpdateWaiters();
     }
     drainSubagentToolUpdates() {
         return this.pendingSubagentUpdates.splice(0, this.pendingSubagentUpdates.length)
@@ -2441,7 +2546,7 @@ export class Agent {
         if (this._mode === "plan" && !tool.readOnly) {
             return {
                 content: `Error: Tool "${toolCall.name}" is not allowed in plan mode. ` +
-                    `In plan mode you may only use read-only tools (read, glob, grep, lsp, web_search, web_fetch, spawn_agent, wait_agent, send_input, close_agent, skill_search, skill, todo_write, tool_search, question, exit_plan_mode). ` +
+                    `In plan mode you may only use read-only tools (read, glob, grep, web_search, web_fetch, spawn_agent, wait_agent, send_input, skill_search, skill, todo_write, tool_search, question, exit_plan_mode). ` +
                     `To modify files or run commands, present your proposal and call exit_plan_mode so the user can review and approve it.`,
                 isError: true,
             };
@@ -2768,6 +2873,23 @@ function isFinalSubagentStatus(status) {
         || status === "cancelled"
         || status === "closed";
 }
+/**
+ * Persists the full rendered workflow result so the inline preview can stay
+ * bounded without losing data (the parent reads the file selectively when the
+ * preview was cut). A write failure only costs the pointer, never the run.
+ */
+function persistWorkflowResult(runId, value) {
+    try {
+        const dir = join(getBubbleHome(), "workflows");
+        mkdirSync(dir, { recursive: true });
+        const path = join(dir, `${runId}.result.txt`);
+        writeFileSync(path, renderWorkflowResultValue(value));
+        return path;
+    }
+    catch {
+        return undefined;
+    }
+}
 function normalizeWaitTimeout(value) {
     if (typeof value !== "number" || !Number.isFinite(value))
         return 30_000;
@@ -2780,5 +2902,11 @@ function isSubagentLifecycleTool(name) {
         || name === "send_input"
         || name === "close_agent"
         || name === "list_agents"
-        || name === "agent_team";
+        || name === "run_workflow"
+        || name === "wait_workflow"
+        // Legacy names: still present in transcripts recorded before the tools
+        // were removed (2026-07-06); forked children must not inherit their
+        // dangling tool_calls either.
+        || name === "agent_team"
+        || name === "agent_batch";
 }