@bubblebrain-ai/bubble 0.0.35 → 0.0.37

package/dist/slash-commands/commands.js

@@ -11,9 +11,13 @@ import { normalizeSingleLine } from "../text-display.js";
 import { formatRelativeTime } from "../tui/recent-activity.js";
 import { HOOK_EVENT_NAMES, isHookEventName } from "../hooks/index.js";
 import { isThinkingLevel } from "../variant/thinking-level.js";
+import { normalizeInheritedThinkingLevel } from "../variant/variant-resolver.js";
 import { collectUsageStatsBundle, formatStatsText } from "../stats/usage.js";
 import { buildMemoryPrompt, getMemoryStatus, isMemoryDisabled, resetMemory, searchMemory, } from "../memory/index.js";
 import { feishuCommand } from "./feishu.js";
+import { GROK_LOCAL_COMMAND_HELP } from "../external-runtime/grok-input-policy.js";
+import { isGrokSubscriptionProviderId, } from "../external-runtime/grok-provider.js";
+import { classifyExternalRuntimeBinding } from "../external-runtime/session-policy.js";
 const VALID_SCOPES = ["user", "project", "local"];
 const VALID_LISTS = ["allow", "deny"];
 function isScope(value) {
@@ -141,13 +145,15 @@ function formatMcpContextStatus(ctx) {
     lines.push("- MCP prompts are slash commands; they do not enter context until invoked.");
     return lines.join("\n");
 }
-function switchToProviderModel(providerId, modelId, ctx, thinkingLevel) {
+function switchToProviderModel(providerId, modelId, ctx, thinkingLevel, preparedProvider) {
     const provider = ctx.registry.getConfigured().find((item) => item.id === providerId);
     if (!provider?.apiKey) {
         return false;
     }
-    ctx.agent.thinking = normalizeThinkingLevel(thinkingLevel ?? ctx.agent.thinking, getAvailableThinkingLevels(providerId, modelId));
-    ctx.agent.setProvider(ctx.createProvider(providerId, provider.apiKey, provider.baseURL));
+    ctx.agent.thinking = thinkingLevel !== undefined
+        ? normalizeThinkingLevel(thinkingLevel, getAvailableThinkingLevels(providerId, modelId))
+        : normalizeInheritedThinkingLevel(providerId, modelId, ctx.agent.thinking);
+    ctx.agent.setProvider(preparedProvider ?? ctx.createProvider(providerId, provider.apiKey, provider.baseURL));
     ctx.agent.providerId = providerId;
     ctx.agent.model = encodeModel(providerId, modelId);
     syncSystemPrompt(ctx, ctx.agent.model);
@@ -182,6 +188,122 @@ function displaySelectedModel(model, thinkingLevel) {
     const defaultLevel = providerId ? getDefaultThinkingLevel(providerId, modelId) : "off";
     return thinkingLevel === "off" || thinkingLevel === defaultLevel ? label : `${label} (${thinkingLevel})`;
 }
+function getGrokSessionId(ctx) {
+    const binding = ctx.sessionManager?.getMetadata().externalRuntime;
+    return binding && isGrokSubscriptionProviderId(binding.id) ? binding.sessionId : undefined;
+}
+function isGrokSessionActive(ctx) {
+    return classifyExternalRuntimeBinding(ctx.sessionManager?.getMetadata().externalRuntime) === "grok";
+}
+function hasExternalRuntimeSession(ctx) {
+    return classifyExternalRuntimeBinding(ctx.sessionManager?.getMetadata().externalRuntime) !== "none";
+}
+async function transitionGrokSessionToNative(ctx) {
+    if (!hasExternalRuntimeSession(ctx))
+        return;
+    if (!ctx.transitionToNative) {
+        throw new Error("Switching from Grok subscription to a native Bubble session is unavailable in this mode.");
+    }
+    const next = await ctx.transitionToNative();
+    if (!next) {
+        throw new Error("Bubble could not start a fresh native session.");
+    }
+    // Handlers below may persist provider/model metadata after the transition.
+    // Keep those writes on the new native session rather than the old Grok log.
+    ctx.sessionManager = next;
+}
+/**
+ * Sign in to the Grok subscription as a native model provider (like ChatGPT
+ * OAuth): browser PKCE against auth.x.ai, tokens in ~/.bubble/auth.json, and
+ * grok models served through Bubble's own agent loop. An existing Grok CLI
+ * login is imported so users who already ran `grok login` skip the browser.
+ */
+async function loginGrokSubscription(ctx) {
+    const providerId = "grok";
+    const { loginGrok, importGrokCliCredentials } = await import("../oauth/grok.js");
+    const storage = ctx.registry.getAuthStorage();
+    const runBrowserLogin = async () => {
+        const tokens = await loginGrok({
+            onStatus: (msg) => ctx.addMessage("assistant", msg),
+        });
+        storage.set(providerId, {
+            type: "oauth",
+            accessToken: tokens.accessToken,
+            refreshToken: tokens.refreshToken,
+            expiresAt: tokens.expiresAt,
+        });
+    };
+    let importedExisting = false;
+    if (!storage.has(providerId)) {
+        const imported = importGrokCliCredentials();
+        if (imported) {
+            storage.set(providerId, {
+                type: "oauth",
+                accessToken: imported.accessToken,
+                refreshToken: imported.refreshToken,
+                expiresAt: imported.expiresAt,
+            });
+            importedExisting = true;
+            ctx.addMessage("assistant", "Imported the existing Grok CLI sign-in.");
+        }
+    }
+    const hadStoredLogin = storage.has(providerId);
+    if (!hadStoredLogin) {
+        await runBrowserLogin();
+    }
+    try {
+        await ctx.registry.prepareProvider(providerId);
+    }
+    catch (error) {
+        // Stored/imported credentials whose refresh token was revoked get exactly
+        // one browser repair attempt; a failure right after browser login is real.
+        if (!hadStoredLogin)
+            throw error;
+        ctx.addMessage("assistant", `Stored Grok credentials could not be refreshed (${error instanceof Error ? error.message : String(error)}). Signing in again…`);
+        storage.remove(providerId);
+        await runBrowserLogin();
+        await ctx.registry.prepareProvider(providerId);
+    }
+    const provider = ctx.registry.getConfigured().find((item) => item.id === providerId);
+    const defaultModel = ctx.registry.getDefaultModel(providerId, "oauth");
+    if (!provider?.apiKey || !defaultModel) {
+        return `Grok subscription login succeeded, but the provider could not be activated. Tokens saved to ${storage.getPath()}`;
+    }
+    // Complete every fallible preparation step before leaving a legacy
+    // Grok-runtime session; commit only after the native switch succeeds.
+    const preparedProvider = ctx.createProvider(providerId, provider.apiKey, provider.baseURL);
+    await transitionGrokSessionToNative(ctx);
+    const switched = switchToProviderModel(providerId, defaultModel, ctx, undefined, preparedProvider);
+    if (!switched) {
+        return `Grok subscription login succeeded, but the provider could not be activated. Tokens saved to ${storage.getPath()}`;
+    }
+    ctx.registry.setDefault(providerId);
+    const via = importedExisting ? " (reused your Grok CLI sign-in)" : "";
+    return `Grok subscription login successful${via}. Switched to ${displayModel(ctx.agent.model)}. Tokens saved to ${storage.getPath()}`;
+}
+async function logoutGrokSubscription(ctx) {
+    const storage = ctx.registry.getAuthStorage();
+    const hadNativeLogin = storage.has("grok");
+    storage.remove("grok");
+    // Legacy cleanup: sessions bound to the old Grok ACP runtime, and the
+    // isolated CLI profile's credentials.
+    if (isGrokSessionActive(ctx) && ctx.externalRuntime && ctx.startFreshSession) {
+        await ctx.externalRuntime.cancel(getGrokSessionId(ctx)).catch(() => undefined);
+        await ctx.externalRuntime.dispose().catch(() => undefined);
+        await ctx.externalRuntime.logout().catch(() => undefined);
+        const freshSession = await ctx.startFreshSession();
+        freshSession.clearExternalRuntimeMetadata();
+        freshSession.appendMarker("runtime_switch", "native");
+        ctx.sessionManager = freshSession;
+        ctx.onExternalRuntimeChange?.(freshSession);
+        return "Grok subscription logged out. Started a fresh native Bubble session.";
+    }
+    await ctx.externalRuntime?.logout().catch(() => undefined);
+    if (!hadNativeLogin) {
+        return "No Grok subscription login was stored on this device.";
+    }
+    return "Grok subscription logged out. Only this device's local login was removed.";
+}
 function parseMemoryScopeArgs(args) {
     const tokens = args.trim().split(/\s+/).filter(Boolean);
     let scope = "project";
@@ -298,6 +420,16 @@ const builtinSlashCommandEntries = [
         name: "help",
         description: "Show available slash commands",
         async handler(args, ctx) {
+            if (hasExternalRuntimeSession(ctx)) {
+                const grok = isGrokSessionActive(ctx);
+                return [
+                    grok
+                        ? "Grok Subscription · workspace tools · Bubble approvals"
+                        : "Unsupported external runtime session · recovery-only mode",
+                    "Available commands:",
+                    ...GROK_LOCAL_COMMAND_HELP.map((command) => (`  ${command.usage} - ${command.description}`)),
+                ].join("\n");
+            }
             const { registry } = await import("./index.js");
             const lines = ["Available commands:"];
             for (const cmd of registry.list()) {
@@ -475,11 +607,12 @@ const builtinSlashCommandEntries = [
         name: "provider",
         description: "Manage providers. /provider to switch, /provider --add [id] to add, /provider --remove <id>, /provider --set <id>",
         async handler(args, ctx) {
-            if (!args) {
+            const trimmed = args.trim();
+            if (!trimmed) {
                 ctx.openPicker("provider");
                 return;
             }
-            const parts = args.trim().split(/\s+/);
+            const parts = trimmed.split(/\s+/);
             const flag = parts[0];
             const value = parts[1];
             if (flag === "--add") {
@@ -487,6 +620,9 @@ const builtinSlashCommandEntries = [
                     ctx.openPicker("provider-add");
                     return;
                 }
+                if (isGrokSubscriptionProviderId(value)) {
+                    return "Grok Subscription is built in. Use /provider --set grok or /login grok to activate it.";
+                }
                 const builtin = BUILTIN_PROVIDERS.find((p) => p.id === value && isUserVisibleProvider(p.id));
                 if (!builtin) {
                     const ids = BUILTIN_PROVIDERS.filter((p) => isUserVisibleProvider(p.id)).map((p) => p.id).join(", ");
@@ -498,17 +634,27 @@ const builtinSlashCommandEntries = [
                 return;
             }
             if (flag === "--remove" && value) {
+                if (isGrokSubscriptionProviderId(value)) {
+                    return "Grok Subscription is built in and cannot be removed. Use /logout grok to remove its local login.";
+                }
                 if (ctx.registry.getModelConfig().hasProvider(value)) {
                     return `Provider ${value} is defined in ~/.bubble/models.json. Please edit that file directly.`;
                 }
                 ctx.registry.removeProvider(value);
+                // Registry mutation without a model switch still changes the routing
+                // world (design §1.6): refresh the routing menu in the system prompt.
+                syncSystemPrompt(ctx, ctx.agent.model);
                 return `Provider ${value} removed.`;
             }
             if (flag === "--set" && value) {
+                if (isGrokSubscriptionProviderId(value)) {
+                    return loginGrokSubscription(ctx);
+                }
                 const providers = ctx.registry.getConfigured();
                 const p = providers.find((x) => x.id === value);
                 if (!p)
                     return `Provider ${value} is not configured.`;
+                await transitionGrokSessionToNative(ctx);
                 ctx.registry.setDefault(value);
                 if (ctx.registry.getModelConfig().hasProvider(value)) {
                     return `Default provider set to ${p.name}. Note: config is managed via ~/.bubble/models.json.`;
@@ -517,13 +663,17 @@ const builtinSlashCommandEntries = [
             }
             if (flag === "--list") {
                 const providers = ctx.registry.getConfigured();
-                const lines = ["Configured providers:"];
+                const grokActive = isGrokSessionActive(ctx);
+                const lines = ["Available providers:"];
                 for (const p of providers) {
-                    const marker = p.id === ctx.registry.getDefault()?.id ? "* " : "  ";
+                    const marker = !grokActive && p.id === ctx.registry.getDefault()?.id ? "* " : "  ";
                     const source = ctx.registry.getModelConfig().hasProvider(p.id) ? " [models.json]" : "";
                     const oauth = ctx.registry.getAuthStorage().has(p.id) ? " [oauth]" : "";
                     lines.push(`${marker}${p.name} (${p.id}) ${p.enabled ? "" : "[disabled]"}${oauth}${source}`);
                 }
+                if (!providers.some((provider) => provider.id === "grok")) {
+                    lines.push(`${grokActive ? "* " : "  "}Grok Subscription (grok) [not signed in — /login grok]`);
+                }
                 if (ctx.registry.getModelConfig().getLoadError()) {
                     lines.push(`Warning: failed to load models.json: ${ctx.registry.getModelConfig().getLoadError()}`);
                 }
@@ -534,15 +684,18 @@ const builtinSlashCommandEntries = [
     },
     {
         name: "login",
-        description: "OAuth login for supported providers. Usage: /login [openai]",
+        description: "Login to OpenAI OAuth or Grok Subscription. Usage: /login [openai|grok]",
         async handler(args, ctx) {
             const providerId = args?.trim() || "openai";
             if (!providerId) {
                 ctx.openPicker("login");
                 return;
             }
+            if (isGrokSubscriptionProviderId(providerId)) {
+                return loginGrokSubscription(ctx);
+            }
             if (!ctx.registry.supportsOAuth(providerId)) {
-                return `Unsupported OAuth provider: ${providerId}. Currently only 'openai' is supported.`;
+                return `Unsupported login provider: ${providerId}. Supported providers: 'openai' and 'grok'.`;
             }
             const { loginOpenAICodex } = await import("../oauth/openai-codex.js");
             const tokens = await loginOpenAICodex({
@@ -557,17 +710,25 @@ const builtinSlashCommandEntries = [
                 accountId: tokens.accountId,
             });
             await ctx.registry.prepareProvider(providerId);
-            ctx.registry.setDefault(providerId);
             const provider = ctx.registry.getConfigured().find((item) => item.id === providerId);
             const discoveredModels = provider ? await ctx.registry.listModels(provider) : [];
             const defaultModel = discoveredModels[0]?.id || ctx.registry.getDefaultModel(providerId, "oauth");
             if (!defaultModel) {
                 return `OpenAI Codex OAuth login succeeded, but no default model is configured for ${providerId}.`;
             }
-            const switched = switchToProviderModel(providerId, defaultModel, ctx);
+            if (!provider?.apiKey) {
+                return `OpenAI Codex OAuth login succeeded, but the provider could not be activated. Tokens saved to ${ctx.registry.getAuthStorage().getPath()}`;
+            }
+            // Complete every fallible OAuth/provider/model preparation step before
+            // leaving a Grok-bound session. The provider object is created once and
+            // committed only after the fresh native session switch succeeds.
+            const preparedProvider = ctx.createProvider(providerId, provider.apiKey, provider.baseURL);
+            await transitionGrokSessionToNative(ctx);
+            const switched = switchToProviderModel(providerId, defaultModel, ctx, undefined, preparedProvider);
             if (!switched) {
                 return `OpenAI Codex OAuth login succeeded, but the provider could not be activated. Tokens saved to ${ctx.registry.getAuthStorage().getPath()}`;
             }
+            ctx.registry.setDefault(providerId);
             return `OpenAI Codex OAuth login successful. Switched to ${displayModel(ctx.agent.model)}. Account: ${tokens.accountId || "unknown"}. Tokens saved to ${ctx.registry.getAuthStorage().getPath()}`;
         },
     },
@@ -576,6 +737,13 @@ const builtinSlashCommandEntries = [
         description: "Switch model. Use /model <id> [--reasoning-effort <level>] or just /model to open picker.",
         async handler(args, ctx) {
             if (!args) {
+                if (hasExternalRuntimeSession(ctx)) {
+                    if (isGrokSessionActive(ctx)) {
+                        ctx.openPicker("model");
+                        return;
+                    }
+                    return "This external runtime manages its model and reasoning settings. Bubble's model picker is unavailable until you switch to a native session.";
+                }
                 if (ctx.registry.getEnabled().length === 0) {
                     ctx.openPicker("model");
                     return;
@@ -588,30 +756,69 @@ const builtinSlashCommandEntries = [
                 return parsed.error;
             }
             if (!parsed.model) {
+                if (hasExternalRuntimeSession(ctx)) {
+                    if (isGrokSessionActive(ctx)) {
+                        ctx.openPicker("model");
+                        return;
+                    }
+                    return "This external runtime manages its model and reasoning settings. Bubble's model picker is unavailable until you switch to a native session.";
+                }
                 ctx.openPicker("model");
                 return;
             }
+            const explicitModelProvider = parsed.model.includes(":") ? parsed.model.split(":", 1)[0] : undefined;
+            if (isGrokSessionActive(ctx) && (!explicitModelProvider || isGrokSubscriptionProviderId(explicitModelProvider))) {
+                if (!ctx.externalRuntime)
+                    return "Grok Subscription runtime is unavailable.";
+                const boundSessionId = getGrokSessionId(ctx);
+                if (boundSessionId)
+                    await ctx.externalRuntime.hydrateSession(boundSessionId);
+                const requestedModel = parsed.model.includes(":")
+                    ? parsed.model.split(":").slice(1).join(":")
+                    : parsed.model;
+                const selection = await ctx.externalRuntime.setModel(requestedModel, parsed.thinkingLevel);
+                const metadata = ctx.sessionManager?.getMetadata().externalRuntime;
+                if (metadata && isGrokSubscriptionProviderId(metadata.id)) {
+                    ctx.sessionManager?.updateMetadata({
+                        externalRuntime: {
+                            ...metadata,
+                            modelId: selection.modelId,
+                            reasoningEffort: selection.reasoningEffort,
+                        },
+                    });
+                }
+                ctx.sessionManager?.appendMarker("model_switch", selection.modelId ?? requestedModel);
+                ctx.sessionManager?.appendMarker("thinking_level_switch", selection.reasoningEffort);
+                ctx.onExternalRuntimeChange?.(ctx.sessionManager);
+                return `Grok model switched to ${selection.modelId ?? requestedModel}${selection.reasoningEffort !== "off" ? ` (${selection.reasoningEffort})` : ""}.`;
+            }
             const defaultProvider = ctx.registry.getDefault()?.id || "openai";
             const next = parsed.model.includes(":") ? parsed.model : encodeModel(defaultProvider, parsed.model);
             const { providerId, modelId } = decodeModel(next);
             const targetProviderId = providerId || defaultProvider;
             await ctx.registry.prepareProvider(targetProviderId);
-            const switched = switchToProviderModel(targetProviderId, modelId, ctx, parsed.thinkingLevel);
-            if (!switched) {
+            const targetProvider = ctx.registry.getConfigured().find((item) => item.id === targetProviderId);
+            if (!targetProvider?.apiKey) {
                 return `Provider ${targetProviderId} is not configured or has no active credentials.`;
             }
+            const preparedProvider = ctx.createProvider(targetProviderId, targetProvider.apiKey, targetProvider.baseURL);
+            await transitionGrokSessionToNative(ctx);
+            switchToProviderModel(targetProviderId, modelId, ctx, parsed.thinkingLevel, preparedProvider);
             return `Model switched to ${displaySelectedModel(next, ctx.agent.thinking)}.`;
         },
     },
     {
         name: "logout",
-        description: "Remove OAuth credentials for a provider. Usage: /logout [openai]",
+        description: "Remove local login credentials. Usage: /logout [openai|grok]",
         async handler(args, ctx) {
             const providerId = args?.trim() || "openai";
             if (!providerId) {
                 ctx.openPicker("logout");
                 return;
             }
+            if (isGrokSubscriptionProviderId(providerId)) {
+                return logoutGrokSubscription(ctx);
+            }
             if (!ctx.registry.getAuthStorage().has(providerId)) {
                 return `No OAuth credentials found for ${providerId}.`;
             }
@@ -629,6 +836,9 @@ const builtinSlashCommandEntries = [
             else if (ctx.agent.providerId === providerId) {
                 ctx.agent.providerId = "";
             }
+            // No-fallback logout mutates the routing world without a model switch
+            // (design §1.6): refresh the menu so it stops advertising the provider.
+            syncSystemPrompt(ctx, ctx.agent.model);
             return `OAuth credentials for ${providerId} removed.`;
         },
     },

package/dist/slash-commands/types.d.ts

@@ -1,5 +1,5 @@
 import type { Agent } from "../agent.js";
-import type { SessionManager } from "../session.js";
+import type { SessionManager, SessionMetadata } from "../session.js";
 import type { Provider } from "../types.js";
 import type { ProviderRegistry } from "../provider-registry.js";
 import type { SkillRegistry } from "../skills/registry.js";
@@ -10,6 +10,7 @@ import type { LspService } from "../lsp/index.js";
 import type { MemoryScope } from "../memory/index.js";
 import type { ThemeMode } from "../config.js";
 import type { ExternalHookController } from "../hooks/controller.js";
+import type { ExternalRuntimeManager } from "../external-runtime/types.js";
 /**
  * Live progress for a manual `/compact` run, pushed to the TUI so it can render
  * a progress bar. `phase` advances collecting → summarizing → applying;
@@ -61,6 +62,18 @@ export interface SlashCommandContext {
      * while compacting and `null` to clear the indicator. Absent in non-TUI hosts.
      */
     compactionProgress?: (progress: CompactionProgress | null) => void;
+    /** External agent runtime used by Grok subscription chat. */
+    externalRuntime?: ExternalRuntimeManager;
+    /**
+     * Atomically create and bind a fresh Bubble session with optional metadata.
+     * External runtimes are session-affine, so crossing the native/external
+     * boundary never reuses history.
+     */
+    startFreshSession?: (metadata?: Partial<SessionMetadata>) => Promise<SessionManager>;
+    /** Stop the external runtime and atomically enter a fresh native session. */
+    transitionToNative?: () => Promise<SessionManager | undefined>;
+    /** Refresh TUI state after a command changes the external session binding. */
+    onExternalRuntimeChange?: (manager?: SessionManager) => void;
 }
 /**
  * Return types for a slash command handler:

package/dist/system-prompt.d.ts

@@ -32,5 +32,7 @@ export interface SystemPromptOptions {
     memoryPrompt?: string;
     /** Durable child-agent profile prompt used for subagents. */
     agentProfilePrompt?: string;
+    /** Rendered subagent model-routing menu (design §4); parents only. */
+    modelRoutingPrompt?: string;
 }
 export declare function buildSystemPrompt(options?: SystemPromptOptions): string;

package/dist/tools/agent-lifecycle.js

@@ -2,7 +2,8 @@ import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { discoverAgentProfiles, findAgentProfile } from "../agent/profiles.js";
 import { parseThinkingLevel } from "../agent/categories.js";
-import { workflowMemberWarning } from "../agent/workflow/control.js";
+import { THINKING_LEVELS } from "../types.js";
+import { buildWorkflowResultBlock, workflowMemberWarning } from "../agent/workflow/control.js";
 import { precompileWorkflowScript } from "../agent/workflow/runtime.js";
 import { formatSubagentRoute } from "../agent/subagent-route-format.js";
 /**
@@ -124,7 +125,7 @@ export function createSpawnAgentTool(options = {}, sharedTrust) {
                 agent: { type: "string", description: "Alias for agent_type." },
                 category: { type: "string", description: "Optional semantic category for model/thinking routing, such as quick, deep, explore, review, frontend, or writing." },
                 model: { type: "string", description: "Optional per-call model for this child, overriding category and profile. Bare name (e.g. claude-haiku-4-5) uses the parent provider; provider:model (e.g. anthropic:claude-opus-4-1) selects cross-provider." },
-                effort: { type: "string", enum: ["off", "minimal", "low", "medium", "high", "xhigh", "max"], description: "Optional per-call thinking level for this child, overriding category and profile." },
+                effort: { type: "string", enum: [...THINKING_LEVELS], description: "Optional per-call thinking level for this child, overriding category and profile." },
                 message: { type: "string", description: "Initial task for the subagent." },
                 task: { type: "string", description: "Alias for message." },
                 fork_context: { type: "boolean", description: "When true, copy recent parent conversation into the child thread." },
@@ -291,6 +292,7 @@ export function createSendInputTool() {
 export function createCloseAgentTool() {
     return {
         name: "close_agent",
+        deferred: true,
         readOnly: true,
         effect: "read",
         description: "Close a spawned subagent only when the delegated task is cancelled, stale, or no longer needed. Running children are cancelled before closing; do not close a child just because you started doing the same delegated work locally.",
@@ -327,6 +329,7 @@ export function createCloseAgentTool() {
 export function createListAgentsTool() {
     return {
         name: "list_agents",
+        deferred: true,
         readOnly: true,
         effect: "read",
         description: "List this session's subagents with their current status. Use it to recall which children exist before spawning duplicates or narrating progress.",
@@ -401,8 +404,8 @@ export function createRunWorkflowTool(options = {}, sharedTrust) {
             "This is THE tool whenever the user asks for a workflow, an orchestration, or an agent team — even a small one; do not substitute parallel spawn_agent calls for an explicit request.",
             "Also use it for tasks that need loops, conditional fan-out, or staged pipelines over dozens of subagents whose intermediate steps should stay out of this conversation — e.g. a codebase-wide audit, a migration, or cross-checked research.",
             "The script's only capability is agent(prompt, opts?) — each call spawns a sandboxed readonly subagent; opts may set {model, effort, agentType, category, schema, label}. Give each agent a short unique label. Also available: parallel(thunks), pipeline(items, ...stages), phase(title), log(msg), the global args, and budget {total, spent(), remaining()}.",
-            "End the script with `return <value>`; that value (only) comes back to you. The script has no filesystem/shell/network/clock/random access. run_workflow must be the ONLY tool call in your response; it blocks until the workflow finishes.",
-            "A failed or blocked agent() resolves to null inside parallel/pipeline (a bare await agent() throws instead): check for null slots and return which items failed alongside the results — never silently drop them.",
+            "End the script with `return <value>`; that value (only) comes back to you. Return distilled conclusions, not raw agent transcripts — reduce inside the script (plain JS filtering or a final synthesis agent); a return value past ~8000 chars reaches you truncated (full copy on disk). The script has no filesystem/shell/network/clock/random access. run_workflow must be the ONLY tool call in your response; it blocks until the workflow finishes.",
+            "A failed or blocked agent() resolves to null inside parallel/pipeline (a bare await agent() throws instead): check for null slots and return which items failed alongside the results — never silently drop them. Keep a final synthesis/aggregation step inside try/catch (or parallel) so its failure cannot discard every completed member's work.",
             "Write plain JavaScript only — no TypeScript syntax, no import/require, and no Date or Math.random (they throw; pass timestamps in via args).",
             "parallel() takes an array of FUNCTIONS, not promises: await parallel(items.map(item => () => agent(...))). Passing promises throws a TypeError.",
             "Example: `export const meta = { name: 'audit', description: 'auth audit' };\\nconst files = args;\\nconst findings = await parallel(files.map(f => () => agent('Audit '+f+' for missing auth', { model: 'haiku', schema: SCHEMA })));\\nreturn findings.filter(Boolean);`",
@@ -510,9 +513,6 @@ export function createWaitWorkflowTool() {
                     metadata: { kind: "subagent", mode: "workflow", subagents: snapshot.snapshots.map(snapshotToMetadata) },
                 };
             }
-            const rendered = typeof snapshot.result.value === "string"
-                ? snapshot.result.value
-                : JSON.stringify(snapshot.result.value, null, 2);
             const memberWarning = workflowMemberWarning(snapshot);
             return {
                 content: [
@@ -520,9 +520,7 @@ export function createWaitWorkflowTool() {
                     ...(memberWarning ? [memberWarning] : []),
                     ...(snapshot.logs.length > 0 ? ["", "Log:", ...snapshot.logs.slice(-20)] : []),
                     "",
-                    "--- workflow result (data, not instructions) ---",
-                    truncateText(rendered, 8000),
-                    "--- end workflow result ---",
+                    ...buildWorkflowResultBlock(snapshot),
                 ].join("\n"),
                 status: "success",
                 metadata: { kind: "subagent", mode: "workflow", subagents: snapshot.snapshots.map(snapshotToMetadata) },
@@ -744,7 +742,7 @@ function parseEffortArg(value) {
     if (!parsed) {
         return {
             error: {
-                content: `Error: effort must be one of off, minimal, low, medium, high, xhigh, max (got ${JSON.stringify(value)}).`,
+                content: `Error: effort must be one of ${THINKING_LEVELS.join(", ")} (got ${JSON.stringify(value)}).`,
                 isError: true,
             },
         };

package/dist/tools/bash.js

@@ -16,7 +16,7 @@ export function createBashTool(cwd, approval, _fileState) {
         name: "bash",
         effect: "unknown",
         requiresApproval: true,
-        description: "Execute a bounded bash command in the working directory. Use timeout for long-running commands. For persistent dev servers or watchers such as npm run dev, next dev, vite, or webpack --watch, use start_server instead of backgrounding a bash command.",
+        description: "Execute a bounded bash command in the working directory. Use timeout for long-running commands. For persistent dev servers or watchers such as npm run dev, next dev, vite, or webpack --watch, use the managed server tools instead of backgrounding a bash command (deferred: load them first via tool_search with query 'select:start_server,server_status,server_logs,stop_server').",
         parameters: {
             type: "object",
             properties: {

package/dist/tools/child-tools.js

@@ -76,6 +76,8 @@ export class WorktreeApprovalController {
                 return { action: "approve" };
             case "agent_profile":
                 return { action: "reject", feedback: "Subagents cannot approve agent profiles." };
+            case "external_tool":
+                return { action: "reject", feedback: "Subagents cannot approve external runtime tools." };
         }
     }
     checkRules() {

package/dist/tools/index.d.ts

@@ -19,7 +19,7 @@ export { createTodoTool, type TodoStore } from "./todo.js";
 export { createExitPlanModeTool, type PlanController } from "./exit-plan-mode.js";
 export { createToolSearchTool, type ToolSearchController } from "./tool-search.js";
 export { createQuestionTool } from "./question.js";
-export { createMemoryReadSummaryTool, createMemorySearchTool } from "./memory.js";
+export { createMemoryTool } from "./memory.js";
 import type { ToolRegistryEntry } from "../types.js";
 import type { ApprovalController } from "../approval/types.js";
 import type { SkillRegistry } from "../skills/registry.js";
@@ -45,7 +45,7 @@ export interface CreateAllToolsOptions {
      * files before mutating them so /rewind can restore.
      */
     checkpoints?: () => CheckpointStore | undefined;
-    /** Shared goal state; when present, registers the get_goal/update_goal tools. */
+    /** Shared goal state; when present, registers the update_goal tool. */
     goalStore?: GoalStore;
 }
 export declare function createAllTools(cwd: string, skillRegistry?: SkillRegistry, options?: CreateAllToolsOptions): ToolRegistryEntry[];

package/dist/tools/index.js

@@ -19,7 +19,7 @@ export { createTodoTool } from "./todo.js";
 export { createExitPlanModeTool } from "./exit-plan-mode.js";
 export { createToolSearchTool } from "./tool-search.js";
 export { createQuestionTool } from "./question.js";
-export { createMemoryReadSummaryTool, createMemorySearchTool } from "./memory.js";
+export { createMemoryTool } from "./memory.js";
 import { createBashTool } from "./bash.js";
 import { createManagedServerTools } from "./server.js";
 import { createEditTool } from "./edit.js";
@@ -38,7 +38,7 @@ import { createWebFetchTool } from "./web-fetch.js";
 import { createWebSearchTool } from "./web-search.js";
 import { createWriteTool } from "./write.js";
 import { createQuestionTool } from "./question.js";
-import { createMemoryReadSummaryTool, createMemorySearchTool } from "./memory.js";
+import { createMemoryTool } from "./memory.js";
 import { FileStateTracker } from "./file-state.js";
 import { createGoalTools } from "../goal/tools.js";
 export function createAllTools(cwd, skillRegistry, options = {}) {
@@ -56,14 +56,16 @@ export function createAllTools(cwd, skillRegistry, options = {}) {
         createLspTool(cwd, lsp, approval),
         createWebSearchTool(),
         createWebFetchTool(approval),
-        createMemorySearchTool(cwd),
-        createMemoryReadSummaryTool(cwd),
+        createMemoryTool(cwd),
         ...createAgentLifecycleTools({ cwd, approval }),
+        // Always registered: any host can carry deferred tools (MCP entries mark
+        // themselves deferred), so every host needs the unlock path. Falls back
+        // to the executing agent when no controller is wired.
+        createToolSearchTool(options.toolSearchController),
         ...(options.questionController ? [createQuestionTool(options.questionController)] : []),
         ...(skillRegistry ? [createSkillSearchTool(skillRegistry), createSkillTool(skillRegistry)] : []),
         ...(options.todoStore ? [createTodoTool(options.todoStore)] : []),
         ...(options.planController ? [createExitPlanModeTool(options.planController)] : []),
-        ...(options.toolSearchController ? [createToolSearchTool(options.toolSearchController)] : []),
         ...(options.goalStore ? createGoalTools(options.goalStore) : []),
     ];
 }

package/dist/tools/lsp.js

@@ -17,6 +17,7 @@ const OPERATIONS = [
 export function createLspTool(cwd, lsp = getLspService(cwd), approval) {
     return {
         name: "lsp",
+        deferred: true,
         readOnly: true,
         effect: "read",
         requiresApproval: true,

package/dist/tools/memory.d.ts

@@ -1,3 +1,8 @@
 import type { ToolRegistryEntry } from "../types.js";
-export declare function createMemorySearchTool(cwd: string): ToolRegistryEntry;
-export declare function createMemoryReadSummaryTool(cwd: string): ToolRegistryEntry;
+/**
+ * Single entry point to persistent memory: without a query it reads the
+ * concise memory summary, with a query it searches memory. One schema in the
+ * per-turn tool list instead of two (the read/search split cost context on
+ * every turn while both modes share this file's backing code).
+ */
+export declare function createMemoryTool(cwd: string): ToolRegistryEntry;