wave-agent-sdk 0.15.0 → 0.15.2

package/src/managers/mcpManager.ts

@@ -24,7 +24,7 @@ interface McpConnection {
 }
 
 export interface McpManagerCallbacks {
-  onServersChange?: (servers: McpServerStatus[]) => void;
+  onMcpServersChange?: (servers: McpServerStatus[]) => void;
 }
 
 import { logger } from "../utils/globalLogger.js";
@@ -32,6 +32,8 @@ import { logger } from "../utils/globalLogger.js";
 export interface McpManagerOptions {
   callbacks?: McpManagerCallbacks;
   logger?: Logger;
+  /** Pre-configured MCP servers passed from constructor options */
+  mcpServers?: Record<string, McpServerConfig>;
 }
 
 /**
@@ -96,12 +98,14 @@ export class McpManager {
   private configPath: string = "";
   private workdir: string = "";
   private callbacks: McpManagerCallbacks;
+  private mcpServers: Record<string, McpServerConfig> | undefined;
 
   constructor(
     private container: Container,
     options: McpManagerOptions = {},
   ) {
     this.callbacks = options.callbacks || {};
+    this.mcpServers = options.mcpServers;
   }
 
   /**
@@ -114,11 +118,20 @@ export class McpManager {
     this.configPath = join(workdir, ".mcp.json");
     this.workdir = workdir;
 
+    // Register constructor-provided servers before loading .mcp.json
+    if (this.mcpServers) {
+      for (const [name, config] of Object.entries(this.mcpServers)) {
+        this.addServer(name, config);
+      }
+    }
+
     if (autoConnect) {
       logger?.debug("Initializing MCP servers...");
 
-      // Ensure MCP configuration is loaded
-      const config = await this.ensureConfigLoaded();
+      // Load workspace MCP configuration (always read, merge with any plugin servers already added)
+      await this.loadConfig();
+
+      const config = this.config;
 
       if (config && config.mcpServers) {
         // Connect to all configured servers in background to avoid blocking agent initialization
@@ -145,7 +158,7 @@ export class McpManager {
 
       logger?.debug("MCP servers initialization started in background");
       // Trigger state change callback after starting initialization
-      this.callbacks.onServersChange?.(this.getAllServers());
+      this.callbacks.onMcpServersChange?.(this.getAllServers());
     }
   }
 
@@ -164,7 +177,20 @@ export class McpManager {
 
     try {
       const configContent = await fs.readFile(this.configPath, "utf-8");
-      this.config = resolveMcpConfig(JSON.parse(configContent));
+      const workspaceConfig = resolveMcpConfig(JSON.parse(configContent));
+
+      // Merge workspace config with any existing config (e.g., from plugins or constructor)
+      // Constructor-provided servers take precedence, then workspace config, then existing config
+      const merged: McpConfig = { mcpServers: {} };
+      if (this.config) {
+        Object.assign(merged.mcpServers, this.config.mcpServers);
+      }
+      Object.assign(merged.mcpServers, workspaceConfig.mcpServers);
+      // Constructor-provided servers override both for same names
+      if (this.mcpServers) {
+        Object.assign(merged.mcpServers, this.mcpServers);
+      }
+      this.config = merged;
 
       // Initialize server statuses (preserve existing status for already known servers)
       if (this.config) {
@@ -226,7 +252,7 @@ export class McpManager {
     if (server) {
       this.servers.set(name, { ...server, ...updates });
       // Trigger state change callback
-      this.callbacks.onServersChange?.(this.getAllServers());
+      this.callbacks.onMcpServersChange?.(this.getAllServers());
     }
   }
 

package/src/managers/messageManager.ts

@@ -518,6 +518,7 @@ export class MessageManager {
           sessionId: this.sessionId,
         },
       ],
+      timestamp: new Date().toISOString(),
       ...(usage && { usage }),
     };
 
@@ -959,15 +960,13 @@ export class MessageManager {
     try {
       const { writeFile } = await import("fs/promises");
 
-      const sessionMessages: import("../types/session.js").SessionMessage[] =
-        messages.map((message) => ({
-          ...message,
-          timestamp: new Date().toISOString(),
-        }));
-
       const content =
-        sessionMessages.map((m) => JSON.stringify(m)).join("\n") +
-        (sessionMessages.length > 0 ? "\n" : "");
+        messages
+          .map((m) => {
+            const { timestamp, ...rest } = m;
+            return JSON.stringify({ timestamp, ...rest });
+          })
+          .join("\n") + (messages.length > 0 ? "\n" : "");
 
       await writeFile(this.transcriptPath, content, "utf8");
     } catch (error) {

package/src/managers/permissionManager.ts

@@ -129,8 +129,6 @@ export class PermissionManager {
   private additionalDirectories: string[] = [];
   private systemAdditionalDirectories: string[] = [];
   private planFilePath?: string;
-  private worktreeName?: string;
-  private mainRepoRoot?: string;
   private workdir?: string;
   private onConfiguredPermissionModeChange?: (mode: PermissionMode) => void;
   private _logger?: Logger;
@@ -151,8 +149,6 @@ export class PermissionManager {
       this.addSystemAdditionalDirectory(dir);
     }
 
-    this.worktreeName = this.container.get<string>("WorktreeName");
-    this.mainRepoRoot = this.container.get<string>("MainRepoRoot");
     this.workdir = this.container.get<string>("Workdir");
   }
 
@@ -438,44 +434,6 @@ export class PermissionManager {
       }
     }
 
-    // 0. Check worktree safety for Write and Edit tools
-    const currentWorkdir = this.getWorkdir();
-    if (
-      this.worktreeName &&
-      this.mainRepoRoot &&
-      currentWorkdir &&
-      (context.toolName === WRITE_TOOL_NAME ||
-        context.toolName === EDIT_TOOL_NAME)
-    ) {
-      const targetPath = context.toolInput?.file_path as string | undefined;
-      if (targetPath) {
-        const absoluteTargetPath = path.resolve(currentWorkdir, targetPath);
-        const isInsideMainRepo = isPathInside(
-          absoluteTargetPath,
-          this.mainRepoRoot,
-        );
-        const isInsideWorktree = isPathInside(
-          absoluteTargetPath,
-          currentWorkdir,
-        );
-
-        // If it's inside the main repo but NOT inside the current worktree
-        if (isInsideMainRepo && !isInsideWorktree) {
-          logger?.warn("Worktree safety violation", {
-            toolName: context.toolName,
-            targetPath,
-            worktreeName: this.worktreeName,
-            mainRepoRoot: this.mainRepoRoot,
-            workdir: currentWorkdir,
-          });
-          return {
-            behavior: "deny",
-            message: `Access denied: You are currently in a worktree session ("${this.worktreeName}"). Modifying files in the main repository (outside the worktree) is not allowed. Please only modify files within the worktree directory: ${currentWorkdir}`,
-          };
-        }
-      }
-    }
-
     // 0. Check denied rules first - Deny always takes precedence
     for (const rule of this.deniedRules) {
       if (this.matchesRule(context, rule)) {

package/src/managers/slashCommandManager.ts

@@ -23,6 +23,7 @@ import {
 import type { SkillManager } from "./skillManager.js";
 import type { SkillMetadata } from "../types/skills.js";
 import type { SubagentManager } from "./subagentManager.js";
+import type { MemoryService } from "../services/memory.js";
 
 import { logger } from "../utils/globalLogger.js";
 
@@ -81,6 +82,10 @@ export class SlashCommandManager {
     return this.container.get<SubagentManager>("SubagentManager")!;
   }
 
+  private get memoryService(): MemoryService {
+    return this.container.get<MemoryService>("MemoryService")!;
+  }
+
   private initializeBuiltinCommands(): void {
     // Register built-in clear command
     this.registerCommand({
@@ -90,6 +95,7 @@ export class SlashCommandManager {
       handler: async () => {
         this.aiManager.abortAIMessage();
         this.messageManager.clearMessages();
+        this.memoryService.clearCache();
         await this.taskManager.syncWithSession();
       },
     });
@@ -224,20 +230,39 @@ export class SlashCommandManager {
                       const messages = subagent.messages;
                       const tokens =
                         subagent.messageManager.getLatestTotalTokens();
-                      const lastTools = subagent.lastTools;
+                      const usedTools = subagent.usedTools;
 
                       const toolCount = countToolBlocks(messages);
                       const summary = formatToolTokenSummary(toolCount, tokens);
 
+                      const getDisplayParam = (t: {
+                        name: string;
+                        parameters: string;
+                        compactParams?: string;
+                        stage?: string;
+                      }) => {
+                        if (
+                          (t.stage === "end" || t.stage === "running") &&
+                          t.compactParams
+                        ) {
+                          return t.compactParams;
+                        }
+                        const flat = t.parameters.replace(/\n/g, "\\n");
+                        return flat.length > 30 ? `…${flat.slice(-30)}` : flat;
+                      };
+
                       let shortResult = "";
                       if (toolCount > 2) {
                         shortResult += "... ";
                       }
-                      if (lastTools.length > 0) {
-                        shortResult += `${lastTools.join(", ")} `;
-                      }
-
                       shortResult += summary;
+                      if (usedTools.length > 0) {
+                        shortResult +=
+                          "\n" +
+                          usedTools
+                            .map((t) => `${t.name} ${getDisplayParam(t)}`)
+                            .join("\n");
+                      }
 
                       this.messageManager.updateToolBlock({
                         id: toolBlockId,

package/src/managers/subagentManager.ts

@@ -68,7 +68,12 @@ export interface SubagentInstance {
   toolManager: ToolManager;
   status: "initializing" | "active" | "completed" | "error" | "aborted";
   messages: Message[];
-  lastTools: string[]; // Track last two tool names
+  usedTools: {
+    name: string;
+    parameters: string;
+    compactParams?: string;
+    stage?: string;
+  }[]; // Track tools with display info
   subagentType: string; // Store the subagent type for hook context
   description: string; // Store the AI-generated description
   allowedTools?: string[]; // Optional permission rules (e.g. git:*)
@@ -388,7 +393,7 @@ export class SubagentManager {
       toolManager,
       status: "initializing",
       messages: [],
-      lastTools: [], // Initialize lastTools
+      usedTools: [], // Initialize usedTools
       subagentType: parameters.subagent_type, // Store the subagent type
       description: parameters.description, // Store the AI-generated description
       allowedTools: parameters.allowedTools, // Store optional permission rules
@@ -790,27 +795,16 @@ export class SubagentManager {
       },
 
       onToolBlockUpdated: (params: AgentToolBlockUpdateParams) => {
-        // Track last two tool names when a tool starts running
-        if (params.stage === "running" && params.name) {
-          const instance = this.instances.get(subagentId);
-          if (instance) {
-            // Add to lastTools if it's different from the last one or we want to show duplicates
-            // Based on "ToolA, ToolB" requirement, we'll just keep the last two
-            instance.lastTools.push(params.name);
-            if (instance.lastTools.length > 2) {
-              instance.lastTools.shift();
-            }
-            instance.onUpdate?.();
-
-            // Log tool execution to file
-            if (instance.logStream) {
-              const displayParams =
-                params.compactParams ||
-                (params.parameters || "{}").substring(0, 100);
-              instance.logStream.write(
-                `[${new Date().toISOString()}] ${params.name}${displayParams ? ` ${displayParams}` : ""}\n`,
-              );
-            }
+        const instance = this.instances.get(subagentId);
+        if (instance) {
+          // Log tool execution to file only when finalized
+          if (instance.logStream && params.stage === "end") {
+            const displayParams =
+              params.compactParams ||
+              (params.parameters || "").substring(0, 100);
+            instance.logStream.write(
+              `[${new Date().toISOString()}] ${params.name}${displayParams ? ` ${displayParams}` : ""}\n`,
+            );
           }
         }
 
@@ -825,6 +819,17 @@ export class SubagentManager {
         const instance = this.instances.get(subagentId);
         if (instance) {
           instance.messages = messages;
+          // Compute usedTools from messages (last 2 tool blocks)
+          const toolBlocks = messages.flatMap(
+            (m) => m.blocks?.filter((b) => b.type === "tool") ?? [],
+          );
+          const last2 = toolBlocks.slice(-2);
+          instance.usedTools = last2.map((tb) => ({
+            name: tb.name ?? "",
+            parameters: tb.parameters ?? "",
+            compactParams: tb.compactParams,
+            stage: tb.stage,
+          }));
           // Trigger the onUpdate callback if provided
           instance.onUpdate?.();
           // Forward subagent message changes to parent via callbacks

package/src/managers/toolManager.ts

@@ -23,6 +23,8 @@ import {
   taskUpdateTool,
   taskListTool,
 } from "../tools/taskManagementTools.js";
+import { enterWorktreeTool } from "../tools/enterWorktreeTool.js";
+import { exitWorktreeTool } from "../tools/exitWorktreeTool.js";
 import { McpManager } from "./mcpManager.js";
 import { PermissionManager } from "./permissionManager.js";
 import { ChatCompletionFunctionTool } from "openai/resources.js";
@@ -43,6 +45,8 @@ import { logger } from "../utils/globalLogger.js";
 
 import type { SubagentConfiguration } from "../utils/subagentParser.js";
 import type { SkillMetadata } from "../types/skills.js";
+import { toolSearchTool } from "../tools/toolSearchTool.js";
+import { isDeferredTool } from "../utils/isDeferredTool.js";
 
 export interface ToolManagerOptions {
   container: Container;
@@ -123,6 +127,9 @@ class ToolManager {
       cronDeleteTool,
       cronListTool,
       webFetchTool,
+      enterWorktreeTool,
+      exitWorktreeTool,
+      toolSearchTool,
     ];
 
     for (const tool of builtInTools) {
@@ -191,6 +198,7 @@ class ToolManager {
       permissionMode: effectivePermissionMode,
       canUseToolCallback,
       permissionManager,
+      toolManager: this, // Allow ToolSearchTool to access the tool manager
       taskManager:
         this.container.get<import("../services/taskManager.js").TaskManager>(
           "TaskManager",
@@ -224,6 +232,11 @@ class ToolManager {
         this.container.get<import("./messageManager.js").MessageManager>(
           "MessageManager",
         )!,
+      hookManager: this.container.has("HookManager")
+        ? this.container.get<import("./hookManager.js").HookManager>(
+            "HookManager",
+          )
+        : undefined,
       sessionId: context.sessionId,
       toolCallId: context.toolCallId,
     };
@@ -287,10 +300,13 @@ class ToolManager {
     availableSkills?: SkillMetadata[];
     workdir?: string;
     isSubagent?: boolean;
+    /** Set of discovered deferred tool names to include in the API call */
+    discoveredTools?: Set<string>;
   }): ChatCompletionFunctionTool[] {
     const permissionManager =
       this.container.get<PermissionManager>("PermissionManager");
     const effectivePermissionMode = this.getPermissionMode();
+    const discoveredTools = options?.discoveredTools;
     const builtInToolsConfig = Array.from(this.toolsRegistry.values())
       .filter((tool) => {
         // If tool is explicitly denied by name in permission rules, filter it out
@@ -315,6 +331,10 @@ class ToolManager {
             effectivePermissionMode !== "bypassPermissions"
           );
         }
+        // Exclude deferred tools that haven't been discovered yet
+        if (isDeferredTool(tool) && !discoveredTools?.has(tool.name)) {
+          return false;
+        }
         return true;
       })
       .map((tool) => {
@@ -333,7 +353,16 @@ class ToolManager {
       });
     const mcpToolsConfig = this.mcpManager
       .getMcpToolsConfig()
-      .filter((tool) => !permissionManager?.isToolDenied(tool.function.name));
+      .filter((tool) => {
+        if (permissionManager?.isToolDenied(tool.function.name)) {
+          return false;
+        }
+        // Exclude MCP tools that haven't been discovered yet
+        if (discoveredTools && !discoveredTools.has(tool.function.name)) {
+          return false;
+        }
+        return true;
+      });
     return [...builtInToolsConfig, ...mcpToolsConfig];
   }
 
@@ -375,6 +404,23 @@ class ToolManager {
     return this.container.get<PermissionManager>("PermissionManager");
   }
 
+  /**
+   * Get the names of all deferred tools (those that require ToolSearch to discover).
+   */
+  public getDeferredToolNames(): string[] {
+    const permissionManager =
+      this.container.get<PermissionManager>("PermissionManager");
+    const builtInDeferred = Array.from(this.toolsRegistry.values())
+      .filter((tool) => isDeferredTool(tool))
+      .filter((tool) => !permissionManager?.isToolDenied(tool.name))
+      .map((tool) => tool.name);
+    const mcpDeferred = this.mcpManager
+      .getMcpToolsConfig()
+      .filter((tool) => !permissionManager?.isToolDenied(tool.function.name))
+      .map((tool) => tool.function.name);
+    return [...builtInDeferred, ...mcpDeferred];
+  }
+
   /**
    * Get the task manager
    */

package/src/prompts/index.ts

@@ -1,6 +1,7 @@
 import * as os from "node:os";
 import { ToolPlugin } from "../tools/types.js";
 import { isGitRepository } from "../utils/gitUtils.js";
+import { getCurrentWorktreeSession } from "../utils/worktreeSession.js";
 import { buildAutoMemoryPrompt } from "./autoMemory.js";
 import { PermissionMode } from "../types/permissions.js";
 import {
@@ -17,9 +18,9 @@ import {
   READ_TOOL_NAME,
   GLOB_TOOL_NAME,
   GREP_TOOL_NAME,
+  TOOL_SEARCH_TOOL_NAME,
 } from "../constants/tools.js";
-
-export const MAX_PARALLEL_TOOL_CALLS = 3;
+import { isDeferredTool } from "../utils/isDeferredTool.js";
 
 export const BASE_SYSTEM_PROMPT = `You are an interactive CLI tool that helps users with software engineering tasks. Use the instructions below and the tools available to you to assist the user.`;
 
@@ -60,7 +61,6 @@ export const TOOL_POLICY = `# Using your tools
   - To search the content of files, use ${GREP_TOOL_NAME} instead of grep or rg
   - Reserve using the ${BASH_TOOL_NAME} exclusively for system commands and terminal operations that require shell execution. If you are unsure and there is a relevant dedicated tool, default to using the dedicated tool and only fallback on using the ${BASH_TOOL_NAME} tool for these if it is absolutely necessary.
 - You can call multiple tools in a single response. If you intend to call multiple tools and there are no dependencies between them, make all independent tool calls in parallel. Maximize use of parallel tool calls where possible to increase efficiency.
-- **Limit**: You MUST NOT call more than ${MAX_PARALLEL_TOOL_CALLS} tools in parallel in a single response.
 - However, if some tool calls depend on previous calls to inform dependent values, do NOT call these tools in parallel and instead call them sequentially. For instance, if one operation must complete before another starts, run these operations sequentially instead. Never use placeholders or guess missing parameters in tool calls.
 - If the user specifies that they want you to run tools "in parallel", you MUST send a single message with multiple tool use content blocks.`;
 
@@ -260,6 +260,13 @@ export function buildSystemPrompt(
     prompt += `\n\n${TOOL_POLICY}`;
   }
 
+  // List available deferred tool names so the model knows they exist
+  // Matching Claude Code: deferred tools appear by name, not loaded until fetched.
+  const deferredToolNames = tools.filter(isDeferredTool).map((t) => t.name);
+  if (deferredToolNames.length > 0) {
+    prompt += `\n\n<available-deferred-tools>${deferredToolNames.join(" ")}\nThese tools are NOT loaded yet — call ${TOOL_SEARCH_TOOL_NAME} first to discover their schemas before invoking them.</available-deferred-tools>`;
+  }
+
   prompt += `\n\n${OUTPUT_EFFICIENCY_PROMPT}`;
   prompt += `\n\n${TONE_AND_STYLE_PROMPT}`;
 
@@ -287,11 +294,13 @@ export function buildSystemPrompt(
         ? "bash"
         : shell;
 
+    const worktreeSession = getCurrentWorktreeSession();
+
     prompt += `
 
 Here is useful information about the environment you are running in:
 <env>
-Working directory: ${options.workdir}
+Working directory: ${options.workdir}${worktreeSession ? `\nThis is a git worktree — an isolated copy of the repository. Run all commands from this directory. Do NOT \`cd\` to the original repository root at ${worktreeSession.originalCwd}.` : ""}
 Is directory a git repo: ${isGitRepo}
 Platform: ${platform}
 Shell: ${shellName}
@@ -330,8 +339,10 @@ export function enhanceSystemPromptWithEnvDetails(
       ? "bash"
       : shell;
 
+  const worktreeSession = getCurrentWorktreeSession();
+
   const notes = `Notes:
-- Agent threads always have their cwd reset between bash calls, as a result please only use absolute file paths.
+- Agent threads always have their cwd reset between bash calls, as a result please only use absolute file paths.${worktreeSession ? `\n- You are in a git worktree at ${worktreeSession.worktreePath} (branch: ${worktreeSession.worktreeBranch}). Absolute paths from prior context may refer to the original repo at ${worktreeSession.originalCwd}; translate them to your worktree. Do NOT edit files outside this worktree.` : ""}
 - In your final response, share file paths (always absolute, never relative) that are relevant to the task. Include code snippets only when the exact text is load-bearing (e.g., a bug you found, a function signature the caller asked for) — do not recap code you merely read.
 - For clear communication with the user the assistant MUST avoid using emojis.
 - Do not use a colon before tool calls. Text like "Let me read the file:" followed by a read tool call should just be "Let me read the file." with a period.`;
@@ -342,7 +353,7 @@ ${notes}
 
 Here is useful information about the environment you are running in:
 <env>
-Working directory: ${workdir}
+Working directory: ${workdir}${worktreeSession ? `\nThis is a git worktree — an isolated copy of the repository. Run all commands from this directory. Do NOT \`cd\` to the original repository root at ${worktreeSession.originalCwd}.` : ""}
 Is directory a git repo: ${isGitRepo}
 Platform: ${platform}
 Shell: ${shellName}

package/src/services/initializationService.ts

@@ -22,7 +22,6 @@ import type { MemoryRuleManager } from "../managers/MemoryRuleManager.js";
 import type { LiveConfigManager } from "../managers/liveConfigManager.js";
 import type { TaskManager } from "./taskManager.js";
 import type { PermissionManager } from "../managers/permissionManager.js";
-import type { MemoryService } from "./memory.js";
 
 export interface InitializationContext {
   skillManager: SkillManager;
@@ -42,8 +41,6 @@ export interface InitializationContext {
   memoryRuleManager: MemoryRuleManager;
   liveConfigManager: LiveConfigManager;
   taskManager: TaskManager;
-  setProjectMemory: (content: string) => void;
-  setUserMemory: (content: string) => void;
   resolveAndValidateConfig: () => void;
 }
 
@@ -74,8 +71,6 @@ export class InitializationService {
       memoryRuleManager,
       liveConfigManager,
       taskManager,
-      setProjectMemory,
-      setUserMemory,
       resolveAndValidateConfig,
     } = context;
 
@@ -293,42 +288,8 @@ export class InitializationService {
       // Don't throw error to prevent app startup failure - continue without live reload
     }
 
-    // Load memory files during initialization
-    try {
-      const phaseStart = performance.now();
-      const memoryService = container.get<MemoryService>("MemoryService");
-      if (!memoryService) {
-        throw new Error("MemoryService not found in container");
-      }
-
-      // Load project memory from AGENTS.md
-      try {
-        const projectMemoryContent =
-          await memoryService.readMemoryFile(workdir);
-        setProjectMemory(projectMemoryContent);
-      } catch (error) {
-        logger?.warn("Failed to load project memory file:", error);
-        setProjectMemory("");
-      }
-
-      // Load user memory
-      try {
-        const userMemoryContent = await memoryService.getUserMemoryContent();
-        setUserMemory(userMemoryContent);
-      } catch (error) {
-        logger?.warn("Failed to load user memory file:", error);
-        setUserMemory("");
-      }
-      logger?.debug(
-        `Initialization Phase [Memory Files Loading] took ${(performance.now() - phaseStart).toFixed(2)}ms`,
-      );
-    } catch (error) {
-      // Ensure memory is always initialized even if loading fails
-      setProjectMemory("");
-      setUserMemory("");
-      logger?.error("Failed to load memory files:", error);
-      // Don't throw error to prevent app startup failure
-    }
+    // Memory is lazy-cached on first getCombinedMemoryContent call
+    // No explicit loading needed during initialization
 
     // Handle session restoration or set provided messages
     const sessionPhaseStart = performance.now();