@bubblebrain-ai/bubble 0.0.34 → 0.0.36

package/dist/tools/agent-lifecycle.js

@@ -2,6 +2,9 @@ import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { discoverAgentProfiles, findAgentProfile } from "../agent/profiles.js";
 import { parseThinkingLevel } from "../agent/categories.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";
 /**
  * Session-scoped trust decisions for project profiles, keyed by file path +
@@ -102,6 +105,7 @@ export function createSpawnAgentTool(options = {}, sharedTrust) {
         "Start a child subagent in the background and return its agent_id plus random nickname.",
         "The child has an independent thread; call wait_agent later to collect its result.",
         "Proactively delegate multi-file investigations whose intermediate steps would be noise in the main conversation.",
+        "Best for helpers whose results you want to read and react to individually. For a uniform sweep over many items, or when member results should be aggregated before returning, weigh run_workflow instead. If the user asked for a workflow, an orchestration, or an agent team, that is run_workflow, not this tool.",
         "Do the work yourself when it takes only a couple of tool calls or needs conversation context — unless the user explicitly asks for a subagent, in which case spawn one.",
         "The child starts with zero context: write the task as a self-contained work order — state the goal, include known file paths or commands, and never make it rediscover knowledge you already hold.",
         "After spawning, do not duplicate the same delegated work locally; either wait for the child or do clearly non-overlapping work.",
@@ -121,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." },
@@ -288,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.",
@@ -324,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.",
@@ -377,266 +383,31 @@ export function createListAgentsTool() {
         },
     };
 }
-/** Items bound for one agent_team call (design §1.2). */
-export const AGENT_TEAM_MIN_ITEMS = 2;
-export const AGENT_TEAM_MAX_ITEMS = 32;
-export function createAgentTeamTool(options = {}, sharedTrust) {
+export function createRunWorkflowTool(options = {}, sharedTrust) {
     const trust = sharedTrust ?? new ProjectProfileTrust(options.approval);
-    return {
-        name: "agent_team",
-        readOnly: true,
-        effect: "read",
-        description: [
-            "Run the same task template over many items as parallel subagents (homogeneous map fan-out).",
-            "Proactively use this when a task naturally splits into the same read-only operation over several independent items.",
-            "Each item becomes one child with its own agent_id; the call blocks until every member reaches a final state and returns results in item order.",
-            "Failed members can be resumed individually with send_input afterwards.",
-            `Use ${AGENT_TEAM_MIN_ITEMS}-${AGENT_TEAM_MAX_ITEMS} items. agent_team must be the ONLY tool call in your response; run other tools or further teams after it returns.`,
-            "Scoping rule: split items so members never overlap or conflict with each other.",
-        ].join(" "),
-        parameters: {
-            type: "object",
-            properties: {
-                description: { type: "string", description: "Short (3-5 word) description of the team, shown in the UI." },
-                agent_type: { type: "string", description: "Subagent profile for every member. Defaults to default." },
-                category: { type: "string", description: "Optional semantic category for model/thinking routing." },
-                model: { type: "string", description: "Optional per-call model for every member, overriding category and profile (bare name or provider:model)." },
-                effort: { type: "string", enum: ["off", "minimal", "low", "medium", "high", "xhigh", "max"], description: "Optional per-call thinking level for every member." },
-                prompt_template: { type: "string", description: "Task template applied to each item. Must contain the literal placeholder {{item}}." },
-                items: {
-                    type: "array",
-                    description: `Items to fan out over (${AGENT_TEAM_MIN_ITEMS}-${AGENT_TEAM_MAX_ITEMS} unique strings); each becomes one subagent.`,
-                    items: { type: "string" },
-                },
-            },
-            required: ["description", "prompt_template", "items"],
-            additionalProperties: false,
-        },
-        async execute(args, ctx) {
-            if (!ctx.agent?.runAgentTeam) {
-                return toolRuntimeMissing("agent_team");
-            }
-            const template = stringArg(args.prompt_template);
-            if (!template) {
-                return { content: "Error: agent_team requires prompt_template.", isError: true };
-            }
-            if (!template.includes("{{item}}")) {
-                return {
-                    content: "Error: prompt_template must contain the literal placeholder {{item}} — it is replaced with each item. Example: \"Review {{item}} for risks.\"",
-                    isError: true,
-                };
-            }
-            const rawItems = Array.isArray(args.items)
-                ? args.items.filter((item) => typeof item === "string" && !!item.trim()).map((item) => item.trim())
-                : [];
-            const items = [...new Set(rawItems)];
-            if (items.length < AGENT_TEAM_MIN_ITEMS) {
-                return {
-                    content: `Error: agent_team needs at least ${AGENT_TEAM_MIN_ITEMS} unique items after deduplication (got ${items.length}). For a single task use spawn_agent instead.`,
-                    isError: true,
-                };
-            }
-            if (items.length > AGENT_TEAM_MAX_ITEMS) {
-                return {
-                    content: `Error: agent_team accepts at most ${AGENT_TEAM_MAX_ITEMS} items (got ${items.length}). Split the work into sequential teams.`,
-                    isError: true,
-                };
-            }
-            const profileName = stringArg(args.agent_type) ?? "default";
-            const resolved = resolveProfile(ctx.cwd, profileName, "both");
-            if ("error" in resolved)
-                return resolved.error;
-            const modeBlock = unsupportedProfile(resolved.profile);
-            if (modeBlock)
-                return modeBlock;
-            const trustBlock = await trust.ensureTrusted(resolved.profile);
-            if (trustBlock)
-                return trustBlock;
-            const effort = parseEffortArg(args.effort);
-            if ("error" in effort)
-                return effort.error;
-            try {
-                const snapshots = await ctx.agent.runAgentTeam(ctx.cwd, {
-                    profile: resolved.profile,
-                    category: stringArg(args.category),
-                    model: stringArg(args.model),
-                    effort: effort.value,
-                    promptTemplate: template,
-                    items,
-                    parentToolCallId: ctx.toolCall?.id ?? snapshotFallbackId(),
-                    emitUpdate: ctx.emitUpdate,
-                    abortSignal: ctx.abortSignal,
-                });
-                const counts = teamStatusCounts(snapshots);
-                const lines = [
-                    `agent_team "${stringArg(args.description) ?? "team"}": ${snapshots.length} members — ${counts}`,
-                    "Failed or cancelled members can be resumed individually with send_input (see per-member guidance below).",
-                    "",
-                    ...snapshots.flatMap((snapshot, index) => [
-                        `### item ${index + 1}: ${truncateText(items[index] ?? "", 100)}`,
-                        ...formatSnapshot(snapshot),
-                        "",
-                    ]),
-                ];
-                return {
-                    content: lines.join("\n").trim(),
-                    status: snapshots.every((snapshot) => snapshot.status === "completed")
-                        ? "success"
-                        : snapshots.some((snapshot) => snapshot.status === "completed")
-                            ? "partial"
-                            : "blocked",
-                    isError: snapshots.length > 0 && snapshots.every((snapshot) => snapshot.status !== "completed"),
-                    metadata: {
-                        kind: "subagent",
-                        mode: "team",
-                        subagents: snapshots.map(snapshotToMetadata),
-                    },
-                };
-            }
-            catch (error) {
-                return toolError("agent_team", error);
-            }
-        },
+    // Single-flight: the interactive UI holds ONE pending approval at a time,
+    // so concurrent trust prompts from a parallel() fan-out would overwrite
+    // each other's resolver and hang the workflow. Serializing here also lets
+    // the first approval satisfy the rest of the same profile via the cache.
+    let trustChain = Promise.resolve();
+    const ensureProfileTrustedSerially = (profile) => {
+        const next = trustChain.then(() => trust.ensureTrusted(profile));
+        trustChain = next.then(() => undefined, () => undefined);
+        return next;
     };
-}
-/** Specs bound for one agent_batch call (design v2 §1.3). */
-export const AGENT_BATCH_MIN_SPECS = 2;
-export const AGENT_BATCH_MAX_SPECS = 32;
-export function createAgentBatchTool(options = {}, sharedTrust) {
-    const trust = sharedTrust ?? new ProjectProfileTrust(options.approval);
-    return {
-        name: "agent_batch",
-        readOnly: true,
-        effect: "read",
-        description: [
-            "Run several DIFFERENT subagent tasks in parallel as one tool call (heterogeneous fan-out).",
-            "Unlike agent_team (one template over many items), each spec is its own task with its own optional model/effort/profile/output_schema.",
-            "Use it to run, e.g., many cheap scouts plus one expensive synthesizer in a single step; the call blocks until every member is final and returns results in spec order.",
-            `Provide ${AGENT_BATCH_MIN_SPECS}-${AGENT_BATCH_MAX_SPECS} specs. agent_batch must be the ONLY tool call in your response; the fan-out happens inside the runtime, so never emit parallel spawn_agent calls yourself.`,
-            "Scoping rule: split specs so members never overlap or conflict.",
-        ].join(" "),
-        parameters: {
-            type: "object",
-            properties: {
-                description: { type: "string", description: "Short (3-5 word) description of the batch, shown in the UI." },
-                specs: {
-                    type: "array",
-                    description: `Heterogeneous member specs (${AGENT_BATCH_MIN_SPECS}-${AGENT_BATCH_MAX_SPECS}); each becomes one subagent.`,
-                    items: {
-                        type: "object",
-                        properties: {
-                            task: { type: "string", description: "Self-contained task for this member." },
-                            agent_type: { type: "string", description: "Subagent profile for this member. Defaults to default." },
-                            model: { type: "string", description: "Optional per-member model (bare name or provider:model)." },
-                            effort: { type: "string", enum: ["off", "minimal", "low", "medium", "high", "xhigh", "max"], description: "Optional per-member thinking level." },
-                            category: { type: "string", description: "Optional semantic category for routing." },
-                            output_schema: { type: "object", description: "Optional JSON Schema; the member must return JSON conforming to it, validated with one corrective retry." },
-                        },
-                        required: ["task"],
-                        additionalProperties: false,
-                    },
-                },
-            },
-            required: ["description", "specs"],
-            additionalProperties: false,
-        },
-        async execute(args, ctx) {
-            if (!ctx.agent?.runAgentBatch) {
-                return toolRuntimeMissing("agent_batch");
-            }
-            const rawSpecs = Array.isArray(args.specs) ? args.specs : [];
-            if (rawSpecs.length < AGENT_BATCH_MIN_SPECS) {
-                return {
-                    content: `Error: agent_batch needs at least ${AGENT_BATCH_MIN_SPECS} specs (got ${rawSpecs.length}). For a single task use spawn_agent instead.`,
-                    isError: true,
-                };
-            }
-            if (rawSpecs.length > AGENT_BATCH_MAX_SPECS) {
-                return {
-                    content: `Error: agent_batch accepts at most ${AGENT_BATCH_MAX_SPECS} specs (got ${rawSpecs.length}). Split into sequential batches.`,
-                    isError: true,
-                };
-            }
-            const specs = [];
-            for (let index = 0; index < rawSpecs.length; index++) {
-                const raw = (rawSpecs[index] ?? {});
-                const task = stringArg(raw.task);
-                if (!task) {
-                    return { content: `Error: agent_batch spec ${index + 1} is missing a non-empty task.`, isError: true };
-                }
-                const profileName = stringArg(raw.agent_type) ?? stringArg(raw.agent) ?? "default";
-                const resolved = resolveProfile(ctx.cwd, profileName, "both");
-                if ("error" in resolved)
-                    return resolved.error;
-                const modeBlock = unsupportedProfile(resolved.profile);
-                if (modeBlock)
-                    return modeBlock;
-                const trustBlock = await trust.ensureTrusted(resolved.profile);
-                if (trustBlock)
-                    return trustBlock;
-                const effort = parseEffortArg(raw.effort);
-                if ("error" in effort)
-                    return effort.error;
-                const outputSchema = raw.output_schema && typeof raw.output_schema === "object" ? raw.output_schema : undefined;
-                specs.push({
-                    task,
-                    profile: resolved.profile,
-                    category: stringArg(raw.category),
-                    model: stringArg(raw.model),
-                    effort: effort.value,
-                    outputSchema,
-                });
-            }
-            try {
-                const snapshots = await ctx.agent.runAgentBatch(ctx.cwd, {
-                    specs,
-                    parentToolCallId: ctx.toolCall?.id ?? snapshotFallbackId(),
-                    emitUpdate: ctx.emitUpdate,
-                    abortSignal: ctx.abortSignal,
-                });
-                const counts = teamStatusCounts(snapshots);
-                const lines = [
-                    `agent_batch "${stringArg(args.description) ?? "batch"}": ${snapshots.length} members — ${counts}`,
-                    "Failed or cancelled members can be resumed individually with send_input (see per-member guidance below).",
-                    "",
-                    ...snapshots.flatMap((snapshot, index) => [
-                        `### member ${index + 1}: ${truncateText(specs[index]?.task ?? "", 100)}`,
-                        ...formatSnapshot(snapshot),
-                        "",
-                    ]),
-                ];
-                return {
-                    content: lines.join("\n").trim(),
-                    status: snapshots.every((snapshot) => snapshot.status === "completed")
-                        ? "success"
-                        : snapshots.some((snapshot) => snapshot.status === "completed")
-                            ? "partial"
-                            : "blocked",
-                    isError: snapshots.length > 0 && snapshots.every((snapshot) => snapshot.status !== "completed"),
-                    metadata: {
-                        kind: "subagent",
-                        mode: "batch",
-                        subagents: snapshots.map(snapshotToMetadata),
-                    },
-                };
-            }
-            catch (error) {
-                return toolError("agent_batch", error);
-            }
-        },
-    };
-}
-export function createRunWorkflowTool(options = {}) {
-    void options;
     return {
         name: "run_workflow",
         readOnly: true,
         effect: "read",
         description: [
             "Run an LLM-authored JavaScript orchestration script (dynamic workflow) that coordinates many subagents with deterministic control flow.",
-            "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}. 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.",
+            "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. 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);`",
         ].join(" "),
         parameters: {
@@ -657,6 +428,16 @@ export function createRunWorkflowTool(options = {}) {
             if (!script) {
                 return { content: "Error: run_workflow requires a non-empty script.", isError: true };
             }
+            // Submit-time syntax probe (same QuickJS engine, compile-only): a broken
+            // script fails HERE as the immediate tool result instead of one turn
+            // later through the background delivery path.
+            const precheck = await precompileWorkflowScript(script);
+            if (!precheck.ok) {
+                return {
+                    content: `run_workflow rejected before launch: ${precheck.error}. Fix the script and re-issue run_workflow.`,
+                    isError: true,
+                };
+            }
             try {
                 const { runId, title } = ctx.agent.startWorkflow(ctx.cwd, {
                     script,
@@ -664,6 +445,9 @@ export function createRunWorkflowTool(options = {}) {
                     title: stringArg(args.title),
                     parentToolCallId: ctx.toolCall?.id ?? snapshotFallbackId(),
                     abortSignal: ctx.abortSignal,
+                    // Project-local profiles named via agent(..., {agentType}) pass the
+                    // same first-use trust gate as spawn_agent (Codex review on #58).
+                    ensureProfileTrusted: ensureProfileTrustedSerially,
                 });
                 return {
                     content: [
@@ -729,17 +513,14 @@ 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: [
                     `workflow "${snapshot.title}" (${runId}) completed (${snapshot.agentCount} agents).`,
+                    ...(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) },
@@ -747,13 +528,6 @@ export function createWaitWorkflowTool() {
         },
     };
 }
-function teamStatusCounts(snapshots) {
-    const counts = new Map();
-    for (const snapshot of snapshots) {
-        counts.set(snapshot.status, (counts.get(snapshot.status) ?? 0) + 1);
-    }
-    return [...counts.entries()].map(([status, count]) => `${status} ${count}`).join(" / ");
-}
 export function createAgentLifecycleTools(options = {}) {
     const trust = new ProjectProfileTrust(options.approval);
     return [
@@ -762,9 +536,7 @@ export function createAgentLifecycleTools(options = {}) {
         createSendInputTool(),
         createCloseAgentTool(),
         createListAgentsTool(),
-        createAgentTeamTool(options, trust),
-        createAgentBatchTool(options, trust),
-        createRunWorkflowTool(options),
+        createRunWorkflowTool(options, trust),
         createWaitWorkflowTool(),
     ];
 }
@@ -907,8 +679,6 @@ function finalGuidanceLines(snapshot) {
         case "cancelled_user":
         case "cancelled_parent_abort":
             return ["", resumeLine(snapshot.agentId)];
-        case "cancelled_budget":
-            return ["", "budget exhausted — do not resume this child; integrate what it already reported and narrow the task if more is needed"];
         case "blocked":
             return ["", "blocked: re-spawn with an adjusted profile or approval setting — resuming as-is would hit the same block"];
         case "failed_fatal":
@@ -972,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;

package/dist/tools/memory.js

@@ -1,9 +1,17 @@
 import { readMemorySummary, searchMemory } from "../memory/index.js";
 const MEMORY_SCOPE_ENUM = ["project", "global", "all"];
-export function createMemorySearchTool(cwd) {
+/**
+ * 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 function createMemoryTool(cwd) {
     return {
-        name: "memory_search",
-        description: "Search persistent Bubble memory for prior project facts, user preferences, workflows, decisions, and gotchas.",
+        name: "memory",
+        description: "Read or search persistent Bubble memory (prior project facts, user preferences, workflows, decisions, gotchas). " +
+            "Without query, returns the concise memory summary (scope defaults to project). " +
+            "With query, searches memory entries (scope defaults to all, project memory first).",
         readOnly: true,
         effect: "read",
         parameters: {
@@ -11,25 +19,37 @@ export function createMemorySearchTool(cwd) {
             properties: {
                 query: {
                     type: "string",
-                    description: "Search query. Use concrete terms such as file names, feature names, commands, or error text.",
+                    description: "Search query. Use concrete terms such as file names, feature names, commands, or error text. Omit to read the memory summary instead.",
                 },
                 scope: {
                     type: "string",
                     enum: MEMORY_SCOPE_ENUM,
-                    description: "Memory scope to search. Defaults to all, with project memory first.",
+                    description: "Memory scope. Defaults to project when reading the summary, all when searching.",
                 },
                 limit: {
                     type: "number",
-                    description: "Maximum number of results to return. Defaults to 12.",
+                    description: "Maximum number of search results to return. Defaults to 12. Ignored for summary reads.",
                 },
             },
-            required: ["query"],
             additionalProperties: false,
         },
         async execute(args) {
             const query = typeof args.query === "string" ? args.query.trim() : "";
             if (!query) {
-                return { content: "query is required", isError: true, status: "no_match" };
+                const scope = parseScope(args.scope, "project");
+                const summaries = readMemorySummary(cwd, scope);
+                if (summaries.length === 0) {
+                    return { content: `No ${scope} memory summary is available.`, status: "no_match" };
+                }
+                return {
+                    content: summaries.map((summary) => [
+                        `# ${summary.scope} memory summary`,
+                        `Path: ${summary.path}`,
+                        "",
+                        summary.content,
+                    ].join("\n")).join("\n\n---\n\n"),
+                    metadata: { kind: "read", matches: summaries.length },
+                };
             }
             const scope = parseScope(args.scope);
             const limit = typeof args.limit === "number" && Number.isFinite(args.limit)
@@ -52,41 +72,6 @@ export function createMemorySearchTool(cwd) {
         },
     };
 }
-export function createMemoryReadSummaryTool(cwd) {
-    return {
-        name: "memory_read_summary",
-        description: "Read the concise persistent memory summary for the current project, global scope, or both.",
-        readOnly: true,
-        effect: "read",
-        parameters: {
-            type: "object",
-            properties: {
-                scope: {
-                    type: "string",
-                    enum: MEMORY_SCOPE_ENUM,
-                    description: "Memory scope to read. Defaults to project.",
-                },
-            },
-            additionalProperties: false,
-        },
-        async execute(args) {
-            const scope = parseScope(args.scope, "project");
-            const summaries = readMemorySummary(cwd, scope);
-            if (summaries.length === 0) {
-                return { content: `No ${scope} memory summary is available.`, status: "no_match" };
-            }
-            return {
-                content: summaries.map((summary) => [
-                    `# ${summary.scope} memory summary`,
-                    `Path: ${summary.path}`,
-                    "",
-                    summary.content,
-                ].join("\n")).join("\n\n---\n\n"),
-                metadata: { kind: "read", matches: summaries.length },
-            };
-        },
-    };
-}
 function parseScope(value, fallback = "all") {
     return value === "project" || value === "global" || value === "all" ? value : fallback;
 }