@bubblebrain-ai/bubble 0.0.34 → 0.0.36

package/dist/external-runtime/index.d.ts

@@ -0,0 +1,13 @@
+export * from "./types.js";
+export * from "./grok-errors.js";
+export * from "./grok-network.js";
+export * from "./grok-provider.js";
+export * from "./grok-input-policy.js";
+export * from "./session-policy.js";
+export * from "./grok-binary.js";
+export * from "./grok-profile.js";
+export * from "./grok-preflight.js";
+export * from "./grok-process.js";
+export * from "./grok-ndjson.js";
+export * from "./grok-acp.js";
+export * from "./grok-runtime.js";

package/dist/external-runtime/index.js

@@ -0,0 +1,13 @@
+export * from "./types.js";
+export * from "./grok-errors.js";
+export * from "./grok-network.js";
+export * from "./grok-provider.js";
+export * from "./grok-input-policy.js";
+export * from "./session-policy.js";
+export * from "./grok-binary.js";
+export * from "./grok-profile.js";
+export * from "./grok-preflight.js";
+export * from "./grok-process.js";
+export * from "./grok-ndjson.js";
+export * from "./grok-acp.js";
+export * from "./grok-runtime.js";

package/dist/external-runtime/session-policy.d.ts

@@ -0,0 +1,11 @@
+import type { ExternalRuntimeManager } from "./types.js";
+export type ExternalRuntimeBindingKind = "none" | "grok" | "unsupported";
+/**
+ * Treat every persisted external-runtime marker as non-native. Known aliases
+ * normalize to Grok; malformed or future IDs stay fail-closed instead of
+ * falling through to Bubble's native agent/tool path.
+ */
+export declare function classifyExternalRuntimeBinding(binding: unknown): ExternalRuntimeBindingKind;
+export declare function stopExternalRuntimeForSessionSwitch(runtime: ExternalRuntimeManager | undefined, sessionId?: string): Promise<void>;
+/** Never replay a Grok-owned transcript through Bubble's native print path. */
+export declare function shouldRejectGrokSessionInPrintMode(externalRuntimeBinding: unknown, printMode: boolean): boolean;

package/dist/external-runtime/session-policy.js

@@ -0,0 +1,30 @@
+import { isGrokSubscriptionProviderId } from "./grok-provider.js";
+/**
+ * Treat every persisted external-runtime marker as non-native. Known aliases
+ * normalize to Grok; malformed or future IDs stay fail-closed instead of
+ * falling through to Bubble's native agent/tool path.
+ */
+export function classifyExternalRuntimeBinding(binding) {
+    if (binding === undefined)
+        return "none";
+    const id = typeof binding === "string"
+        ? binding
+        : binding !== null && typeof binding === "object" && "id" in binding
+            ? binding.id
+            : undefined;
+    return typeof id === "string" && isGrokSubscriptionProviderId(id)
+        ? "grok"
+        : "unsupported";
+}
+export async function stopExternalRuntimeForSessionSwitch(runtime, sessionId) {
+    if (!runtime) {
+        throw new Error("The external runtime manager is unavailable; the current session was not changed.");
+    }
+    if (sessionId)
+        await runtime.cancel(sessionId);
+    await runtime.dispose();
+}
+/** Never replay a Grok-owned transcript through Bubble's native print path. */
+export function shouldRejectGrokSessionInPrintMode(externalRuntimeBinding, printMode) {
+    return printMode && classifyExternalRuntimeBinding(externalRuntimeBinding) !== "none";
+}

package/dist/external-runtime/types.d.ts

@@ -0,0 +1,65 @@
+import type { AgentEvent } from "../types.js";
+import type { ThinkingLevel } from "../types.js";
+export type ExternalRuntimeState = "unavailable" | "signed_out" | "ready" | "running" | "failed" | "disposed";
+export interface ExternalRuntimeCapabilities {
+    chat: boolean;
+    tools: boolean;
+    memory: boolean;
+    subagents: boolean;
+    plan: boolean;
+    web: boolean;
+    sessionLoad: boolean;
+    workspace: boolean;
+    modelControl: boolean;
+    reasoningControl: boolean;
+}
+export interface ExternalRuntimeBinaryInfo {
+    path: string;
+    version: string;
+    sha256: string;
+}
+export interface ExternalRuntimeStatus {
+    provider: "grok";
+    state: ExternalRuntimeState;
+    capabilities: ExternalRuntimeCapabilities;
+    binary?: ExternalRuntimeBinaryInfo;
+    sessionId?: string;
+    /** A deliberately terse, credential-free diagnostic suitable for the TUI. */
+    message?: string;
+}
+export interface ExternalRuntimeSession {
+    id: string;
+    provider: "grok";
+    modelId?: string;
+    reasoningEffort?: ThinkingLevel;
+}
+export interface ExternalRuntimeModel {
+    id: string;
+    name: string;
+    reasoningLevels: ThinkingLevel[];
+    defaultReasoningLevel: ThinkingLevel;
+}
+export interface ExternalRuntimeModelSelection {
+    modelId?: string;
+    reasoningEffort: ThinkingLevel;
+}
+export interface ExternalRuntimeRunOptions {
+    sessionId?: string;
+    signal?: AbortSignal;
+    /** Lets callers invalidate late ACP notifications after a UI generation swap. */
+    generation?: number;
+}
+export interface ExternalRuntimeManager {
+    inspect(): Promise<ExternalRuntimeStatus>;
+    login(signal?: AbortSignal, onBrowserOpened?: () => void): Promise<void>;
+    logout(): Promise<void>;
+    newSession(): Promise<ExternalRuntimeSession>;
+    loadSession(id: string): Promise<ExternalRuntimeSession>;
+    hydrateSession(id: string, modelId?: string, reasoningEffort?: ThinkingLevel): Promise<ExternalRuntimeSession>;
+    listModels(): Promise<ExternalRuntimeModel[]>;
+    getModelSelection(): ExternalRuntimeModelSelection;
+    setModel(modelId: string, reasoningEffort?: ThinkingLevel): Promise<ExternalRuntimeModelSelection>;
+    run(prompt: string, options?: ExternalRuntimeRunOptions): AsyncIterable<AgentEvent>;
+    cancel(sessionId?: string): Promise<void>;
+    dispose(): Promise<void>;
+}

package/dist/external-runtime/types.js

@@ -0,0 +1 @@
+export {};

package/dist/feishu/agent-host/approval-card.js

@@ -55,6 +55,27 @@ export function formatApprovalRequest(req) {
                     "\n该 profile 来自仓库本地 `.bubble/agents`，其 prompt 会驱动一个子代理。仅在信任该仓库时批准。",
                 ].join("\n"),
             };
+        case "external_tool":
+            return {
+                title: `外部工具：${req.title}`,
+                body: [
+                    `**kind:** \`${truncate(req.kind, 80)}\``,
+                    req.locations?.length
+                        ? `**paths:** ${req.locations.map((location) => `\`${truncate(location.path, PATH_PREVIEW_MAX)}\``).join(", ")}`
+                        : "",
+                    req.rawInput === undefined
+                        ? ""
+                        : `\n**input:**\n\`\`\`json\n${truncate(safeJson(req.rawInput), CONTENT_PREVIEW_MAX)}\n\`\`\``,
+                ].filter(Boolean).join("\n"),
+            };
+    }
+}
+function safeJson(value) {
+    try {
+        return JSON.stringify(value, null, 2);
+    }
+    catch {
+        return "[unserializable input]";
     }
 }
 function truncate(s, max) {

package/dist/feishu/agent-host/run-driver.js

@@ -19,11 +19,13 @@ import { BashAllowlist } from "../../approval/session-cache.js";
 import { getLspService } from "../../lsp/index.js";
 import { ExternalHookController } from "../../hooks/index.js";
 import { buildSystemPrompt } from "../../system-prompt.js";
+import { createRoutableModelIndex, createRoutingSnapshotAccessor } from "../../agent/routing-catalog.js";
+import { buildModelRoutingPrompt } from "../../prompt/routing.js";
 import { FileStateTracker } from "../../tools/file-state.js";
 import { buildToolPromptOptions, createAllTools } from "../../tools/index.js";
 import { displayModel, encodeModel, decodeModel } from "../../provider-registry.js";
 import { buildMemoryPrompt, recordMemoryCitations } from "../../memory/index.js";
-import { getDefaultThinkingLevel } from "../../provider-transform.js";
+import { getAvailableThinkingLevels, getDefaultThinkingLevel, normalizeThinkingLevel } from "../../provider-transform.js";
 import { createSessionTitleUpdater } from "../../session-title.js";
 import { applyCardBudget } from "../card/budget.js";
 import { renderCard } from "../card/renderer.js";
@@ -87,9 +89,16 @@ export class RunDriver {
         const { provider, providerId, model } = await this.resolveProvider(session, promptCacheKey);
         const skills = this.opts.deps.skillRegistry.summaries();
         const memoryPrompt = buildMemoryPrompt(session.cwd);
-        const thinkingLevel = this.opts.deps.userConfig.getDefaultThinkingLevel()
-            ?? getDefaultThinkingLevel(providerId, decodeModel(model).modelId);
+        const modelId = decodeModel(model).modelId;
+        const configuredThinkingLevel = this.opts.deps.userConfig.getDefaultThinkingLevel();
+        const thinkingLevel = configuredThinkingLevel !== undefined
+            ? normalizeThinkingLevel(configuredThinkingLevel, getAvailableThinkingLevels(providerId, modelId))
+            : getDefaultThinkingLevel(providerId, modelId);
         const initialMode = session.permissionMode;
+        // Routing accessor built before the prompt (design §1.5): the prompt is
+        // composed before the Agent exists, same ordering constraint as main.ts.
+        const agentRouting = this.opts.deps.userConfig.getAgentRouting();
+        const routingSnapshotAccessor = createRoutingSnapshotAccessor(this.opts.deps.providerRegistry, () => this.opts.deps.userConfig.getAgentCategories(), () => agentRouting);
         const systemPrompt = buildSystemPrompt({
             agentName: "Bubble",
             configuredProvider: providerId || "none",
@@ -100,6 +109,9 @@ export class RunDriver {
             workingDir: session.cwd,
             ...buildToolPromptOptions(tools.filter((tool) => !tool.deferred)),
             memoryPrompt,
+            modelRoutingPrompt: providerId && modelId
+                ? buildModelRoutingPrompt(routingSnapshotAccessor({ providerId, model: modelId }), agentRouting)
+                : undefined,
         });
         const budgetLedger = new BudgetLedger();
         let sessionTitleUpdater;
@@ -140,6 +152,9 @@ export class RunDriver {
             memoryPrompt,
             fileStateTracker,
             agentCategories: this.opts.deps.userConfig.getAgentCategories(),
+            agentRouting,
+            routingSnapshot: routingSnapshotAccessor,
+            routableModels: createRoutableModelIndex(this.opts.deps.providerRegistry),
             subagents: this.opts.deps.userConfig.getSubagents(),
             providerFactory: (route) => this.opts.deps.createProviderForRoute(route, promptCacheKey),
             externalHooks: hookController,
@@ -175,6 +190,7 @@ export class RunDriver {
                 agent.messages = [{ role: "system", content: systemPrompt }, ...history];
                 if (agent.mode === "plan")
                     agent.injectModeReminder();
+                agent.injectDeferredToolsReminder();
             }
         }
         // 4. Build RunState + stream the card.

package/dist/feishu/serve.js

@@ -98,6 +98,7 @@ export async function serveFeishu(opts = {}) {
         promptCacheKey,
         protocol: providerRegistry.getConfigured().find((provider) => provider.id === providerId)?.protocol,
         openAICodexAuth: providerRegistry.createOpenAICodexAuthAdapter(providerId),
+        grokAuth: providerRegistry.createGrokAuthAdapter(providerId),
     });
     const createProviderForRoute = async (route, promptCacheKey) => {
         const target = providerRegistry.getConfigured().find((p) => p.id === route.providerId);

package/dist/goal/tools.d.ts

@@ -1,9 +1,12 @@
 /**
- * Model-facing goal tools: get_goal and update_goal.
+ * Model-facing goal tool: update_goal.
  *
- * Both read/write the shared GoalStore so the model's completion/blocked signal
+ * It writes the shared GoalStore so the model's completion/blocked signal
  * stops the TUI's auto-continuation loop. The user sets goals via `/goal`, so
- * there is intentionally no model-facing create_goal tool.
+ * there is intentionally no model-facing create_goal tool — and no read tool:
+ * the goal engine already injects the objective plus budget state into every
+ * goal turn's prompt, so a get_goal call could only return what the model was
+ * just told.
  */
 import type { ToolRegistryEntry } from "../types.js";
 import type { GoalStore } from "./store.js";

package/dist/goal/tools.js

@@ -1,30 +1,18 @@
 /**
- * Model-facing goal tools: get_goal and update_goal.
+ * Model-facing goal tool: update_goal.
  *
- * Both read/write the shared GoalStore so the model's completion/blocked signal
+ * It writes the shared GoalStore so the model's completion/blocked signal
  * stops the TUI's auto-continuation loop. The user sets goals via `/goal`, so
- * there is intentionally no model-facing create_goal tool.
+ * there is intentionally no model-facing create_goal tool — and no read tool:
+ * the goal engine already injects the objective plus budget state into every
+ * goal turn's prompt, so a get_goal call could only return what the model was
+ * just told.
  */
-import { goalSummaryText } from "./format.js";
 const UPDATE_GOAL_DESCRIPTION = `Update the active thread goal's status. Use this tool only to mark the goal achieved or genuinely blocked; it returns an error if there is no active goal.
 Set status to "complete" only when the objective has actually been achieved and no required work remains — never merely because the budget is nearly exhausted or you are stopping.
 Set status to "blocked" only when the same blocking condition has repeated for at least three consecutive goal turns (counting the original turn and automatic continuations) and you cannot make meaningful progress without user input or an external-state change. Do not use "blocked" because work is hard, slow, uncertain, or incomplete.
 You cannot pause, resume, or set a budget through this tool; those are controlled by the user.`;
 export function createGoalTools(store) {
-    const getGoal = {
-        name: "get_goal",
-        description: "Get the current thread goal: objective, status, turns and tokens used, and remaining token budget. Returns an error if there is no goal.",
-        parameters: { type: "object", properties: {}, required: [], additionalProperties: false },
-        readOnly: true,
-        effect: "read",
-        promptSnippet: "Inspect the active goal's status and remaining token budget.",
-        async execute() {
-            const goal = store.snapshot();
-            if (!goal)
-                return { content: "No active goal.", isError: true };
-            return { content: goalSummaryText(goal) };
-        },
-    };
     const updateGoal = {
         name: "update_goal",
         description: UPDATE_GOAL_DESCRIPTION,
@@ -66,5 +54,5 @@ export function createGoalTools(store) {
             };
         },
     };
-    return [getGoal, updateGoal];
+    return [updateGoal];
 }

package/dist/main.js

@@ -9,11 +9,13 @@ import { parseArgs, printHelp } from "./cli.js";
 import { effectiveThemeModeForTerminal, shouldProbeTerminalTheme, UserConfig } from "./config.js";
 import { createProviderInstance, createUnavailableProvider } from "./provider.js";
 import { resolveConfiguredModel } from "./model-selection.js";
-import { getDefaultThinkingLevel } from "./provider-transform.js";
+import { getAvailableThinkingLevels, getDefaultThinkingLevel, normalizeThinkingLevel } from "./provider-transform.js";
 import { ProviderRegistry, displayModel, encodeModel, decodeModel } from "./provider-registry.js";
 import { SessionManager } from "./session.js";
 import { createSessionTitleUpdater } from "./session-title.js";
 import { buildSystemPrompt } from "./system-prompt.js";
+import { createRoutableModelIndex, createRoutingSnapshotAccessor } from "./agent/routing-catalog.js";
+import { buildModelRoutingPrompt } from "./prompt/routing.js";
 import { SkillRegistry } from "./skills/registry.js";
 import { buildToolPromptOptions, createAllTools } from "./tools/index.js";
 import { FileStateTracker } from "./tools/file-state.js";
@@ -25,12 +27,14 @@ import { ExternalHookController } from "./hooks/index.js";
 import { getLspService } from "./lsp/index.js";
 import { loadMcpConfig } from "./mcp/config.js";
 import { McpManager } from "./mcp/manager.js";
+import { normalizeInheritedThinkingLevel } from "./variant/variant-resolver.js";
 import { QuestionController } from "./question/index.js";
-import { buildMemoryPrompt, formatMemoryStartupResult, recordMemoryCitations, runMemoryPhase2, runMemoryStartupPipeline, startMemoryStartupTask, } from "./memory/index.js";
+import { buildMemoryPrompt, formatMemoryStartupResult, purgeUnsafeMemorySources, recordMemoryCitations, runMemoryPhase2, runMemoryStartupPipeline, startMemoryStartupTask, } from "./memory/index.js";
 import { basename } from "node:path";
 import { normalizeSingleLine, truncateVisual } from "./text-display.js";
 import { BUBBLE_WORDMARK } from "./tui/wordmark.js";
 import { configureDebugTrace, summarizeAgentEventForTrace, summarizeTraceMessage, traceEvent, } from "./debug-trace.js";
+import { shouldRejectGrokSessionInPrintMode } from "./external-runtime/session-policy.js";
 async function main() {
     const args = parseArgs(process.argv.slice(2));
     if (process.argv.includes("-h") || process.argv.includes("--help")) {
@@ -88,6 +92,7 @@ async function main() {
             promptCacheKey: sessionPromptCacheKey,
             protocol: defaultProvider.protocol,
             openAICodexAuth: registry.createOpenAICodexAuthAdapter(defaultProvider.id),
+            grokAuth: registry.createGrokAuthAdapter(defaultProvider.id),
         })
         : createUnavailableProvider(unavailableProviderMessage);
     const createProvider = (providerId, apiKey, baseURL) => createProviderInstance({
@@ -98,6 +103,7 @@ async function main() {
         promptCacheKey: sessionPromptCacheKey,
         protocol: registry.getConfigured().find((provider) => provider.id === providerId)?.protocol,
         openAICodexAuth: registry.createOpenAICodexAuthAdapter(providerId),
+        grokAuth: registry.createGrokAuthAdapter(providerId),
     });
     const createProviderForRoute = async (route) => {
         const providerId = route.providerId;
@@ -156,7 +162,7 @@ async function main() {
     };
     const lspService = getLspService(args.cwd, settingsManager.getMerged().lsp);
     const fileStateTracker = new FileStateTracker(args.cwd);
-    // Shared between the goal tools (model-facing get_goal/update_goal) and the
+    // Shared between the goal tool (model-facing update_goal) and the
     // TUI's auto-continuation engine / status-line indicator.
     const goalStore = new GoalStore();
     const tools = createAllTools(args.cwd, skillRegistry, {
@@ -178,6 +184,7 @@ async function main() {
         console.error(chalk.yellow(`[mcp:${d.scope}] ${d.path}: ${d.message}`));
     }
     const mcpManager = new McpManager({ servers: mcpLoaded.servers });
+    let externalRuntime;
     if (mcpLoaded.servers.length > 0) {
         await mcpManager.start();
         // Only surface failures at startup. Successful connections would push the
@@ -206,8 +213,19 @@ async function main() {
             // ignore — we're exiting anyway
         }
     };
-    process.once("SIGINT", () => { void shutdownMcp().then(() => process.exit(130)); });
-    process.once("SIGTERM", () => { void shutdownMcp().then(() => process.exit(143)); });
+    const shutdownExternalRuntime = async () => {
+        try {
+            await externalRuntime?.dispose();
+        }
+        catch {
+            // ignore — we're exiting anyway
+        }
+    };
+    const shutdownSidecars = async () => {
+        await Promise.allSettled([shutdownMcp(), shutdownExternalRuntime()]);
+    };
+    process.once("SIGINT", () => { void shutdownSidecars().then(() => process.exit(130)); });
+    process.once("SIGTERM", () => { void shutdownSidecars().then(() => process.exit(143)); });
     // Session management:
     // - default: always start a fresh session
     // - --resume --session <name>: restore the named session
@@ -235,12 +253,20 @@ async function main() {
             const pickerThemeMode = effectiveThemeModeForTerminal(themeConfig, preResolvedTheme);
             const pickerResolvedTheme = pickerThemeMode === "auto" ? preResolvedTheme : pickerThemeMode;
             const { runSessionPicker } = await import("./tui-ink/run-session-picker.js");
+            const { canvasBackgroundFor } = await import("./tui-ink/theme.js");
+            // Same rule as the main TUI: a forced theme mismatching the terminal
+            // paints its canvas so its foregrounds stay readable.
+            const pickerCanvas = themeConfig.overrides?.background
+                ? undefined
+                : canvasBackgroundFor(pickerThemeMode, pickerResolvedTheme, preResolvedTheme);
             const picked = await runSessionPicker({
                 currentCwd: args.cwd,
                 currentSessions,
                 allSessions,
                 resolvedTheme: pickerResolvedTheme,
-                themeOverrides: themeConfig.overrides,
+                themeOverrides: pickerCanvas
+                    ? { ...themeConfig.overrides, background: pickerCanvas }
+                    : themeConfig.overrides,
             });
             if (picked) {
                 sessionManager = new SessionManager(picked);
@@ -288,15 +314,30 @@ async function main() {
         activeProviderId = "";
     }
     const initialThinkingLevel = activeModel
-        ? (sessionThinkingLevel
-            ?? args.thinkingLevel
-            ?? configuredThinkingLevel
-            ?? getDefaultThinkingLevel(activeProviderId, effectiveModelId))
-        : (sessionThinkingLevel ?? args.thinkingLevel ?? configuredThinkingLevel ?? "off");
+        ? args.thinkingLevel !== undefined
+            ? normalizeThinkingLevel(args.thinkingLevel, getAvailableThinkingLevels(activeProviderId, effectiveModelId))
+            : sessionThinkingLevel !== undefined
+                ? normalizeInheritedThinkingLevel(activeProviderId, effectiveModelId, sessionThinkingLevel)
+                : configuredThinkingLevel !== undefined
+                    ? normalizeThinkingLevel(configuredThinkingLevel, getAvailableThinkingLevels(activeProviderId, effectiveModelId))
+                    : getDefaultThinkingLevel(activeProviderId, effectiveModelId)
+        : (args.thinkingLevel ?? sessionThinkingLevel ?? configuredThinkingLevel ?? "off");
     const restoredTodos = sessionManager?.getTodos() ?? [];
     const initialMode = args.mode ?? "default";
     const skillSummaries = skillRegistry.summaries();
+    // This synchronous provenance gate must run before buildMemoryPrompt: the
+    // background startup pipeline is too late once text has entered the native
+    // provider's system prompt.
+    purgeUnsafeMemorySources(args.cwd);
     const memoryPrompt = buildMemoryPrompt(args.cwd);
+    // Routing snapshot accessor (model-routing design §1.5): built before the
+    // system prompt because startup composes the prompt before the Agent exists;
+    // the same accessor is then handed to the Agent constructor.
+    const agentRouting = userConfig.getAgentRouting();
+    const routingSnapshotAccessor = createRoutingSnapshotAccessor(registry, () => userConfig.getAgentCategories(), () => agentRouting);
+    const initialRoutingParent = activeProviderId && activeModel
+        ? { providerId: activeProviderId, model: decodeModel(activeModel).modelId }
+        : undefined;
     const systemPrompt = buildSystemPrompt({
         agentName: "Bubble",
         configuredProvider: activeProviderId || "none",
@@ -307,6 +348,9 @@ async function main() {
         workingDir: args.cwd,
         ...buildToolPromptOptions(tools.filter((tool) => !tool.deferred)),
         memoryPrompt,
+        modelRoutingPrompt: initialRoutingParent
+            ? buildModelRoutingPrompt(routingSnapshotAccessor(initialRoutingParent), agentRouting)
+            : undefined,
     });
     const traceInfo = configureDebugTrace({
         cwd: args.cwd,
@@ -381,6 +425,9 @@ async function main() {
         memoryPrompt,
         fileStateTracker,
         agentCategories: userConfig.getAgentCategories(),
+        agentRouting,
+        routingSnapshot: routingSnapshotAccessor,
+        routableModels: createRoutableModelIndex(registry),
         subagents: userConfig.getSubagents(),
         providerFactory: createProviderForRoute,
         externalHooks: hookController,
@@ -418,20 +465,26 @@ async function main() {
         // not perform an ad-hoc extraction of the just-finished session.
     };
     const shutdownRuntime = async () => {
-        await hookController.runEvent({
-            eventName: "SessionEnd",
-            cwd: args.cwd,
-            sessionId: sessionManager?.getSessionFile(),
-            agentRole: "driver",
-            target: "session",
-            payload: {
-                providerId: agent.providerId,
-                model: agent.apiModel,
-            },
-        });
+        try {
+            await hookController.runEvent({
+                eventName: "SessionEnd",
+                cwd: args.cwd,
+                sessionId: sessionManager?.getSessionFile(),
+                agentRole: "driver",
+                target: "session",
+                payload: {
+                    providerId: agent.providerId,
+                    model: agent.apiModel,
+                },
+            });
+        }
+        catch {
+            // Shutdown must still release child processes when a hook fails.
+        }
         const results = await Promise.allSettled([
             flushMemory(),
             shutdownMcp(),
+            shutdownExternalRuntime(),
             lspService.shutdown(),
         ]);
         for (const result of results) {
@@ -472,12 +525,18 @@ async function main() {
             if (agent.mode === "plan") {
                 agent.injectModeReminder();
             }
+            agent.injectDeferredToolsReminder();
             console.log(chalk.dim(`Resumed session: ${sessionManager.getSessionFile()}`));
         }
     }
     try {
         // Print mode: single prompt, then exit
         if (args.print || args.prompt) {
+            if (shouldRejectGrokSessionInPrintMode(sessionManager?.getMetadata().externalRuntime, true)) {
+                console.error(chalk.red("Error: Grok subscription sessions are interactive. Resume this workspace session in the TUI, or start a fresh native session for --print."));
+                process.exitCode = 1;
+                return;
+            }
             const prompt = args.prompt || (await readPipedStdin()) || "";
             if (!prompt) {
                 console.error(chalk.red("Error: No prompt provided."));
@@ -535,9 +594,8 @@ async function main() {
             try {
                 const next = new SessionManager(sessionFile);
                 const history = next.getMessages();
-                sessionManager = next;
-                sessionPromptCacheKey = next.getOrCreatePromptCacheKey();
-                sessionTitleUpdater = createSessionTitleUpdater({
+                const nextPromptCacheKey = next.getOrCreatePromptCacheKey();
+                const nextTitleUpdater = createSessionTitleUpdater({
                     sessionManager: next,
                     complete: (messages, completeOptions) => agent.complete(messages, completeOptions),
                 });
@@ -550,9 +608,26 @@ async function main() {
                 // Keep the live system/meta head (mode reminders survive the switch),
                 // mirroring the /rewind history-replacement pattern.
                 const head = agent.messages.filter((m) => m.role === "system" || m.role === "meta");
-                agent.messages = [...head, ...history];
-                agent.setTodos(next.getTodos());
-                agent.resetContextUsageAnchor();
+                const nextMessages = [...head, ...history];
+                const nextTodos = next.getTodos();
+                // Commit only after every file read/write and reconstruction step has
+                // succeeded. Callers can safely prepare candidate sessions without a
+                // failed switch rebinding persistence or replacing the live history.
+                sessionManager = next;
+                sessionPromptCacheKey = nextPromptCacheKey;
+                sessionTitleUpdater = nextTitleUpdater;
+                agent.messages = nextMessages;
+                // These update only live in-memory/UI mirrors after the persistence
+                // commit. A best-effort callback failure must not report the switch as
+                // rolled back after the outer session binding has already changed.
+                try {
+                    agent.setTodos(nextTodos);
+                }
+                catch { /* candidate already committed */ }
+                try {
+                    agent.resetContextUsageAnchor();
+                }
+                catch { /* derived counter only */ }
                 return { manager: next };
             }
             catch (error) {
@@ -579,6 +654,16 @@ async function main() {
             runMemorySummary,
             runMemoryRefresh,
         };
+        // Grok Subscription is a first-class interactive provider target. Manager
+        // construction is deliberately lazy: it does not inspect, spawn, or reach
+        // the network until the user selects Grok or runs /login grok. Print,
+        // Feishu, help, and version paths return before this import.
+        const { createGrokRuntimeManager } = await import("./external-runtime/grok-runtime.js");
+        externalRuntime = createGrokRuntimeManager({
+            workspace: args.cwd,
+            approvalController,
+            getPermissionMode: () => agentRef?.mode ?? "default",
+        });
         const { startStartupUpdateCheck } = await import("./update/index.js");
         const updateCheck = await startStartupUpdateCheck();
         const updateNotice = updateCheck.notice;
@@ -591,6 +676,7 @@ async function main() {
             onThemeModeChange: (mode) => userConfig.setThemeMode(mode),
             updateNotice: updateNotice ?? undefined,
             updateNoticeRefresh: updateCheck.refreshed,
+            externalRuntime,
         });
         const exitWallMs = summary?.wallMs;
         if (sessionManager) {

package/dist/memory/db.d.ts

@@ -40,6 +40,8 @@ export declare class MemoryDatabase {
     };
     finishPhase1Job(sessionFile: string, ok: boolean, error?: string): void;
     listStage1Outputs(limit?: number): Stage1Output[];
+    listAllStage1Outputs(): Stage1Output[];
+    deleteStage1Output(sessionFile: string): boolean;
     listPreviouslySelectedNotIn(sessionFiles: string[]): Stage1Output[];
     markSelectedForPhase2(outputs: Stage1Output[]): void;
     recordUsage(sessionFiles: string[], now?: Date): number;

package/dist/memory/db.js

@@ -95,6 +95,16 @@ export class MemoryDatabase {
       LIMIT ?
     `).all(limit).map((row) => mapStage1(row));
     }
+    listAllStage1Outputs() {
+        return this.db.prepare(`
+      SELECT * FROM memory_stage1_outputs
+      ORDER BY usage_count DESC, COALESCE(last_usage, generated_at) DESC, source_updated_at DESC
+    `).all().map((row) => mapStage1(row));
+    }
+    deleteStage1Output(sessionFile) {
+        return (this.db.prepare("DELETE FROM memory_stage1_outputs WHERE session_file = ?")
+            .run(sessionFile).changes ?? 0) > 0;
+    }
     listPreviouslySelectedNotIn(sessionFiles) {
         if (sessionFiles.length === 0) {
             return this.db.prepare("SELECT * FROM memory_stage1_outputs WHERE selected_for_phase2 = 1")

package/dist/memory/index.d.ts

@@ -7,3 +7,4 @@ export * from "./start.js";
 export * from "./storage.js";
 export * from "./reset.js";
 export * from "./usage.js";
+export * from "./session-policy.js";

package/dist/memory/index.js

@@ -7,3 +7,4 @@ export * from "./start.js";
 export * from "./storage.js";
 export * from "./reset.js";
 export * from "./usage.js";
+export * from "./session-policy.js";