@bubblebrain-ai/bubble 0.0.35 → 0.0.37

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 { buildWorkflowDeliveryNotice, renderWorkflowResultValue } from "./agent/workflow/control.js";
 import { composeAbortSignals } from "./agent/budget-ledger.js";
-import { assignAgentNickname, builtinAgentProfiles, discoverAgentProfiles, findAgentProfile, validateAgentProfileTools } from "./agent/profiles.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;
@@ -214,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);
@@ -268,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({
@@ -698,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);
@@ -1074,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);
                             }
@@ -1397,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,
@@ -1461,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
@@ -1638,6 +1700,8 @@ export class Agent {
             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";
@@ -1687,6 +1751,7 @@ export class Agent {
             status: record.status,
             agentCount: record.agentCount,
             result: record.result,
+            resultPath: record.resultPath,
             logs: record.logs,
             snapshots: record.snapshots,
         };
@@ -1732,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) };
@@ -1753,6 +1823,8 @@ export class Agent {
                 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;
@@ -1938,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({
@@ -1972,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;
         }
-        return route;
+    }
+    /**
+     * 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;
+        }
+    }
+    /**
+     * 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();
@@ -2060,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: [
@@ -2179,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)
@@ -2311,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,
             };
@@ -2638,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;

package/dist/approval/controller.js

@@ -87,6 +87,17 @@ export class PermissionAwareApprovalController {
                 return { tool: "Lsp", path: req.path, cwd: this.options.cwd };
             case "agent_profile":
                 return { tool: "AgentProfile" };
+            case "external_tool": {
+                const command = externalCommand(req.rawInput);
+                if (req.kind === "execute" && command !== undefined) {
+                    return { tool: "Bash", command };
+                }
+                const path = req.locations?.[0]?.path;
+                if ((req.kind === "edit" || req.kind === "delete" || req.kind === "move") && path) {
+                    return { tool: "Edit", path, cwd: this.options.cwd };
+                }
+                return { tool: req.title.trim() || req.kind.trim() || "ExternalTool" };
+            }
         }
     }
     checkRequestRules(req) {
@@ -176,6 +187,8 @@ function approvalTarget(req) {
             return "Lsp";
         case "agent_profile":
             return "AgentProfile";
+        case "external_tool":
+            return req.title.trim() || req.kind.trim() || "ExternalTool";
     }
 }
 function summarizeApprovalRequest(req) {
@@ -192,5 +205,20 @@ function summarizeApprovalRequest(req) {
             return { type: req.type, path: req.path, operation: req.operation };
         case "agent_profile":
             return { type: req.type, name: req.name, path: req.path, contentHash: req.contentHash };
+        case "external_tool":
+            return {
+                type: req.type,
+                toolCallId: req.toolCallId,
+                title: req.title,
+                kind: req.kind,
+                locations: req.locations,
+                rawInput: req.rawInput,
+            };
     }
 }
+function externalCommand(rawInput) {
+    if (typeof rawInput !== "object" || rawInput === null || Array.isArray(rawInput))
+        return undefined;
+    const command = rawInput.command;
+    return typeof command === "string" ? command : undefined;
+}

package/dist/approval/tool-helper.js

@@ -32,5 +32,7 @@ function approvalRequestLabel(req) {
             return `LSP ${req.operation} on ${req.path}`;
         case "agent_profile":
             return `Project agent profile "${req.name}"`;
+        case "external_tool":
+            return `External tool "${req.title}"`;
     }
 }

package/dist/approval/types.d.ts

@@ -61,7 +61,27 @@ export interface AgentProfileApprovalRequest {
     /** First lines of the profile prompt so the user can judge it. */
     promptPreview: string;
 }
-export type ApprovalRequest = EditApprovalRequest | WriteApprovalRequest | PatchApprovalRequest | BashApprovalRequest | LspApprovalRequest | AgentProfileApprovalRequest;
+/**
+ * Permission gate for a tool exposed by an external ACP runtime.
+ *
+ * Keep this structural rather than importing ACP SDK types so the approval
+ * layer remains provider-agnostic. External runtimes are responsible for
+ * copying the relevant, user-visible fields from the protocol request.
+ */
+export interface ExternalToolApprovalRequest {
+    type: "external_tool";
+    toolCallId: string;
+    /** Human-readable tool name supplied by the external runtime. */
+    title: string;
+    /** ACP tool category (for example execute, edit, read, or other). */
+    kind: string;
+    rawInput?: unknown;
+    locations?: Array<{
+        path: string;
+        line?: number | null;
+    }>;
+}
+export type ApprovalRequest = EditApprovalRequest | WriteApprovalRequest | PatchApprovalRequest | BashApprovalRequest | LspApprovalRequest | AgentProfileApprovalRequest | ExternalToolApprovalRequest;
 export type ApprovalDecision = {
     action: "approve";
     feedback?: string;

package/dist/cli.d.ts

@@ -1,7 +1,7 @@
 /**
  * CLI argument parsing.
  */
-import type { PermissionMode, ThinkingLevel } from "./types.js";
+import { type PermissionMode, type ThinkingLevel } from "./types.js";
 export type CliCommand = "default" | "serve" | "update";
 export interface CliArgs {
     command: CliCommand;