wave-agent-sdk 0.15.0 → 0.15.2

package/src/tools/exitWorktreeTool.ts

@@ -0,0 +1,242 @@
+/**
+ * ExitWorktree tool - exits a worktree session and returns to the original directory.
+ * Mirrors Claude Code's ExitWorktree tool behavior and prompt.
+ */
+
+import type { ToolPlugin, ToolResult, ToolContext } from "./types.js";
+import {
+  getCurrentWorktreeSession,
+  setCurrentWorktreeSession,
+} from "../utils/worktreeSession.js";
+import {
+  removeWorktree,
+  countWorktreeChanges,
+} from "../utils/worktreeUtils.js";
+import { EXIT_WORKTREE_TOOL_NAME } from "../constants/tools.js";
+import { logger } from "../utils/globalLogger.js";
+
+export const EXIT_WORKTREE_TOOL_PROMPT = `Exit a worktree session created by EnterWorktree and return the session to the original working directory.
+
+## Scope
+
+This tool ONLY operates on worktrees created by EnterWorktree in this session. It will NOT touch:
+- Worktrees you created manually with \`git worktree add\`
+- Worktrees from a previous session (even if created by EnterWorktree then)
+- The directory you're in if EnterWorktree was never called
+
+If called outside an EnterWorktree session, the tool is a **no-op**: it reports that no worktree session is active and takes no action. Filesystem state is unchanged.
+
+## When to Use
+
+- The user explicitly asks to "exit the worktree", "leave the worktree", "go back", or otherwise end the worktree session
+- Do NOT call this proactively — only when the user asks
+
+## Parameters
+
+- \`action\` (required): \`"keep"\` or \`"remove"\`
+  - \`"keep"\` — leave the worktree directory and branch intact on disk. Use this if the user wants to come back to the work later, or if there are changes to preserve.
+  - \`"remove"\` — delete the worktree directory and its branch. Use this for a clean exit when the work is done or abandoned.
+- \`discard_changes\` (optional, default false): only meaningful with \`action: "remove"\`. If the worktree has uncommitted files or commits not on the original branch, the tool will REFUSE to remove it unless this is set to \`true\`. If the tool returns an error listing changes, confirm with the user before re-invoking with \`discard_changes: true\`.
+
+## Behavior
+
+- Restores the session's working directory to where it was before EnterWorktree
+- If action is "remove": deletes the worktree directory and branch
+- Once exited, EnterWorktree can be called again to create a fresh worktree
+`;
+
+export const exitWorktreeTool: ToolPlugin = {
+  name: EXIT_WORKTREE_TOOL_NAME,
+  shouldDefer: true,
+  config: {
+    type: "function",
+    function: {
+      name: EXIT_WORKTREE_TOOL_NAME,
+      description: EXIT_WORKTREE_TOOL_PROMPT,
+      parameters: {
+        type: "object",
+        properties: {
+          action: {
+            type: "string",
+            enum: ["keep", "remove"],
+            description:
+              '"keep" leaves the worktree and branch on disk; "remove" deletes both.',
+          },
+          discard_changes: {
+            type: "boolean",
+            description:
+              'Required true when action is "remove" and the worktree has uncommitted files or unmerged commits. The tool will refuse and list them otherwise.',
+          },
+        },
+        required: ["action"],
+      },
+    },
+  },
+  prompt: () => EXIT_WORKTREE_TOOL_PROMPT,
+
+  async execute(
+    args: Record<string, unknown>,
+    context: ToolContext,
+  ): Promise<ToolResult> {
+    const action = args.action as "keep" | "remove" | undefined;
+    const discardChanges = (args.discard_changes as boolean) ?? false;
+
+    if (!action) {
+      return {
+        success: false,
+        content:
+          'Missing required parameter: "action" must be "keep" or "remove".',
+        error: 'Missing required parameter: "action"',
+      };
+    }
+
+    // Validate: must be in an active worktree session
+    const session = getCurrentWorktreeSession();
+    if (!session) {
+      return {
+        success: false,
+        content:
+          "No-op: there is no active EnterWorktree session to exit. This tool only operates on worktrees created by EnterWorktree in the current session — it will not touch worktrees created manually or in a previous session. No filesystem changes were made.",
+        error: "No active worktree session",
+      };
+    }
+
+    // Safety check for removal with changes
+    if (action === "remove" && !discardChanges) {
+      const summary = countWorktreeChanges(
+        session.worktreePath,
+        session.originalHeadCommit,
+      );
+      if (summary === null) {
+        return {
+          success: false,
+          content: `Could not verify worktree state at ${session.worktreePath}. Refusing to remove without explicit confirmation. Re-invoke with discard_changes: true to proceed — or use action: "keep" to preserve the worktree.`,
+          error: "Could not verify worktree state",
+        };
+      }
+      const { changedFiles, commits } = summary;
+      if (changedFiles > 0 || commits > 0) {
+        const parts: string[] = [];
+        if (changedFiles > 0) {
+          parts.push(
+            `${changedFiles} uncommitted ${changedFiles === 1 ? "file" : "files"}`,
+          );
+        }
+        if (commits > 0) {
+          parts.push(
+            `${commits} ${commits === 1 ? "commit" : "commits"} on ${session.worktreeBranch ?? "the worktree branch"}`,
+          );
+        }
+        return {
+          success: false,
+          content: `Worktree has ${parts.join(" and ")}. Removing will discard this work permanently. Confirm with the user, then re-invoke with discard_changes: true — or use action: "keep" to preserve the worktree.`,
+          error: "Worktree has uncommitted changes",
+        };
+      }
+    }
+
+    // Capture info before clearing session
+    const { originalCwd, worktreePath, worktreeBranch } = session;
+
+    if (action === "keep") {
+      // Clear session state
+      setCurrentWorktreeSession(null);
+
+      // Restore CWD
+      const aiManager = context.aiManager;
+      if (aiManager) {
+        aiManager.setWorkdir(originalCwd);
+      }
+
+      return {
+        success: true,
+        content: `Exited worktree. Your work is preserved at ${worktreePath}${worktreeBranch ? ` on branch ${worktreeBranch}` : ""}. Session is now back in ${originalCwd}.`,
+      };
+    }
+
+    // action === "remove"
+    const worktreeInfo = {
+      name: session.worktreeName,
+      path: worktreePath,
+      branch: worktreeBranch,
+      repoRoot: session.repoRoot,
+      isNew: session.isNew,
+    };
+
+    // Count changes BEFORE removing the worktree (directory will be gone after)
+    const summary = countWorktreeChanges(
+      worktreePath,
+      session.originalHeadCommit,
+    ) ?? { changedFiles: 0, commits: 0 };
+
+    removeWorktree(worktreeInfo);
+
+    // Clear session state
+    setCurrentWorktreeSession(null);
+
+    // Restore CWD
+    const aiManager = context.aiManager;
+    if (aiManager) {
+      aiManager.setWorkdir(originalCwd);
+    }
+
+    // Trigger WorktreeRemove hook (non-blocking)
+    let hookTriggered = false;
+    if (context.hookManager) {
+      try {
+        const hookResults = await context.hookManager.executeHooks(
+          "WorktreeRemove",
+          {
+            event: "WorktreeRemove",
+            projectDir: originalCwd,
+            timestamp: new Date(),
+            sessionId: context.sessionId ?? "",
+            transcriptPath: context.messageManager?.getTranscriptPath() ?? "",
+            cwd: originalCwd,
+            worktreePath,
+            env: Object.fromEntries(
+              Object.entries(process.env).filter((e) => e[1] !== undefined),
+            ) as Record<string, string>,
+          },
+        );
+
+        if (context.messageManager) {
+          context.hookManager.processHookResults(
+            "WorktreeRemove",
+            hookResults,
+            context.messageManager,
+          );
+        }
+
+        hookTriggered = true;
+      } catch (error) {
+        // Non-blocking: log but don't fail the tool
+        logger?.warn("WorktreeRemove hooks execution failed:", error);
+      }
+    }
+
+    const discardParts: string[] = [];
+    if (summary.commits > 0) {
+      discardParts.push(
+        `${summary.commits} ${summary.commits === 1 ? "commit" : "commits"}`,
+      );
+    }
+    if (summary.changedFiles > 0) {
+      discardParts.push(
+        `${summary.changedFiles} uncommitted ${summary.changedFiles === 1 ? "file" : "files"}`,
+      );
+    }
+    const discardNote =
+      discardParts.length > 0
+        ? ` Discarded ${discardParts.join(" and ")}.`
+        : "";
+    const hookNote = hookTriggered
+      ? " WorktreeRemove hooks were executed."
+      : "";
+
+    return {
+      success: true,
+      content: `Exited and removed worktree at ${worktreePath}.${discardNote} Session is now back in ${originalCwd}.${hookNote}`,
+    };
+  },
+};

package/src/tools/skillTool.ts

@@ -148,19 +148,39 @@ export const skillTool: ToolPlugin = {
             // Update shortResult
             const messages = instance.messageManager.getMessages();
             const tokens = instance.messageManager.getLatestTotalTokens();
-            const lastTools = instance.lastTools;
+            const usedTools = instance.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");
+            }
 
             context.onShortResultUpdate?.(shortResult);
           },

package/src/tools/taskManagementTools.ts

@@ -9,6 +9,7 @@ import {
 
 export const taskCreateTool: ToolPlugin = {
   name: TASK_CREATE_TOOL_NAME,
+  shouldDefer: true,
   config: {
     type: "function",
     function: {
@@ -143,6 +144,7 @@ NOTE that you should not use this tool if there is only one trivial task to do.
 
 export const taskGetTool: ToolPlugin = {
   name: TASK_GET_TOOL_NAME,
+  shouldDefer: true,
   config: {
     type: "function",
     function: {
@@ -202,6 +204,7 @@ Returns full task details:
 
 export const taskUpdateTool: ToolPlugin = {
   name: TASK_UPDATE_TOOL_NAME,
+  shouldDefer: true,
   config: {
     type: "function",
     function: {
@@ -556,6 +559,7 @@ Set up task dependencies:
 
 export const taskListTool: ToolPlugin = {
   name: TASK_LIST_TOOL_NAME,
+  shouldDefer: true,
   config: {
     type: "function",
     function: {

package/src/tools/toolSearchTool.ts

@@ -0,0 +1,228 @@
+/**
+ * ToolSearchTool - Discovers deferred tool schemas on demand.
+ *
+ * When tool deferral is enabled, deferred tools are not sent to the API.
+ * The model must call this tool to discover a deferred tool's full schema
+ * before it can invoke it.
+ *
+ * Query formats:
+ * - "select:ToolName" — direct selection by name (comma-separated for multiple)
+ * - "notebook jupyter" — keyword search, up to max_results best matches
+ * - "+slack send" — require "slack" in the name, rank by remaining terms
+ */
+
+import { ToolPlugin, ToolResult, ToolContext } from "./types.js";
+import {
+  isDeferredTool,
+  TOOL_SEARCH_TOOL_NAME,
+} from "../utils/isDeferredTool.js";
+
+function formatSchema(tool: ToolPlugin): string {
+  const desc = tool.config.function.description || "";
+  const params = JSON.stringify(tool.config.function.parameters || {}, null, 2);
+  return `${tool.name}: ${desc}\nParameters: ${params}`;
+}
+
+/**
+ * Parse tool name into searchable parts (handles CamelCase and underscores).
+ */
+function parseToolName(name: string): string[] {
+  return name
+    .replace(/([a-z])([A-Z])/g, "$1 $2") // CamelCase to spaces
+    .replace(/_/g, " ")
+    .toLowerCase()
+    .split(/\s+/)
+    .filter(Boolean);
+}
+
+/**
+ * Keyword search over deferred tools by name and description.
+ * Matches Claude Code's scoring: required terms (+prefix) must all match,
+ * optional terms contribute to ranking.
+ */
+function keywordSearch(
+  query: string,
+  deferredTools: ToolPlugin[],
+  maxResults: number,
+): ToolPlugin[] {
+  const queryLower = query.toLowerCase().trim();
+  const queryTerms = queryLower.split(/\s+/).filter(Boolean);
+
+  // Exact match fast path
+  const exact = deferredTools.find((t) => t.name.toLowerCase() === queryLower);
+  if (exact) return [exact];
+
+  // Partition into required (+prefixed) and optional terms
+  const requiredTerms: string[] = [];
+  const optionalTerms: string[] = [];
+  for (const term of queryTerms) {
+    if (term.startsWith("+") && term.length > 1) {
+      requiredTerms.push(term.slice(1));
+    } else {
+      optionalTerms.push(term);
+    }
+  }
+
+  const allScoringTerms =
+    requiredTerms.length > 0
+      ? [...requiredTerms, ...optionalTerms]
+      : queryTerms;
+
+  // Pre-filter to tools matching ALL required terms
+  let candidateTools = deferredTools;
+  if (requiredTerms.length > 0) {
+    candidateTools = deferredTools.filter((tool) => {
+      const parts = parseToolName(tool.name);
+      const desc = (tool.config.function.description || "").toLowerCase();
+      return requiredTerms.every(
+        (term) =>
+          parts.includes(term) ||
+          parts.some((p) => p.includes(term)) ||
+          desc.includes(term),
+      );
+    });
+  }
+
+  // Score each tool
+  const scored = candidateTools
+    .map((tool) => {
+      const parts = parseToolName(tool.name);
+      const desc = (tool.config.function.description || "").toLowerCase();
+      let score = 0;
+
+      for (const term of allScoringTerms) {
+        // Exact part match (high weight)
+        if (parts.includes(term)) {
+          score += tool.isMcp ? 12 : 10;
+        } else if (parts.some((p) => p.includes(term))) {
+          score += tool.isMcp ? 6 : 5;
+        }
+
+        // Full name fallback
+        if (tool.name.toLowerCase().includes(term) && score === 0) {
+          score += 3;
+        }
+
+        // Description match
+        if (desc.includes(term)) {
+          score += 2;
+        }
+      }
+
+      return { tool, score };
+    })
+    .filter((s) => s.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, maxResults)
+    .map((s) => s.tool);
+
+  return scored;
+}
+
+export const toolSearchTool: ToolPlugin = {
+  name: TOOL_SEARCH_TOOL_NAME,
+  config: {
+    type: "function",
+    function: {
+      name: TOOL_SEARCH_TOOL_NAME,
+      description: `Fetches full schema definitions for deferred tools so they can be called.
+
+Deferred tools appear by name in <available-deferred-tools> messages. Until fetched, only the name is known — there is no parameter schema, so the tool cannot be invoked. This tool takes a query, matches it against the deferred tool list, and returns the matched tools' complete JSONSchema definitions inside a <functions> block. Once a tool's schema appears in that result, it is callable exactly like any tool defined at the top of the prompt.
+
+Result format: each matched tool appears as one <function>{"description": "...", "name": "...", "parameters": {...}}`,
+    },
+  },
+  shouldDefer: false, // Always available
+  execute: async (
+    args: Record<string, unknown>,
+    context: ToolContext,
+  ): Promise<ToolResult> => {
+    const { query, max_results = 5 } = args as {
+      query?: string;
+      max_results?: number;
+    };
+
+    if (!query) {
+      return {
+        success: false,
+        content: "",
+        error: "Missing required 'query' parameter",
+      };
+    }
+
+    if (!context.toolManager) {
+      return {
+        success: false,
+        content: "",
+        error: "ToolManager not available in context",
+      };
+    }
+
+    const allTools = context.toolManager.list();
+    const deferredTools = allTools.filter(isDeferredTool);
+
+    // Handle select: prefix
+    const selectMatch = query.match(/^select:(.+)$/i);
+    if (selectMatch) {
+      const requested = selectMatch[1]!
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+
+      const found: ToolPlugin[] = [];
+      const missing: string[] = [];
+
+      for (const toolName of requested) {
+        const tool =
+          deferredTools.find((t) => t.name === toolName) ??
+          allTools.find((t) => t.name === toolName);
+        if (tool) {
+          if (!found.some((f) => f.name === tool.name)) found.push(tool);
+        } else {
+          missing.push(toolName);
+        }
+      }
+
+      if (found.length === 0) {
+        return {
+          success: false,
+          content: "",
+          error: `No matching deferred tools found for: ${missing.join(", ")}`,
+        };
+      }
+
+      const result = found.map(formatSchema).join("\n\n---\n\n");
+      const shortResult = `Discovered tools: ${found.map((t) => t.name).join(", ")}`;
+
+      return {
+        success: true,
+        content: result,
+        shortResult,
+      };
+    }
+
+    // Keyword search
+    const matches = keywordSearch(query, deferredTools, max_results);
+
+    if (matches.length === 0) {
+      return {
+        success: false,
+        content: "",
+        error: `No matching deferred tools found for query: "${query}". Available deferred tools: ${getDeferredToolNamesList(deferredTools)}`,
+      };
+    }
+
+    const result = matches.map(formatSchema).join("\n\n---\n\n");
+    const shortResult = `Found ${matches.length} tools: ${matches.map((t) => t.name).join(", ")}`;
+
+    return {
+      success: true,
+      content: result,
+      shortResult,
+    };
+  },
+};
+
+function getDeferredToolNamesList(tools: ToolPlugin[]): string {
+  return tools.map((t) => t.name).join(", ");
+}

package/src/tools/types.ts

@@ -31,6 +31,21 @@ export interface ToolPlugin {
     workdir?: string;
     isSubagent?: boolean;
   }) => string;
+  /**
+   * When true, this tool is deferred — it's not sent to the API until the model
+   * discovers it via ToolSearch. MCP tools are always deferred.
+   */
+  shouldDefer?: boolean;
+  /**
+   * When true, this tool is never deferred — its full schema always appears in
+   * the initial prompt even when tool search is enabled.
+   */
+  alwaysLoad?: boolean;
+  /**
+   * When true, this is an MCP tool (auto-set by McpManager). MCP tools are
+   * always deferred unless they have alwaysLoad: true.
+   */
+  isMcp?: boolean;
 }
 
 export interface ToolResult {
@@ -58,6 +73,8 @@ export interface ToolContext {
   abortSignal?: AbortSignal;
   backgroundTaskManager?: import("../managers/backgroundTaskManager.js").BackgroundTaskManager;
   workdir: string;
+  /** Tool manager instance for tool discovery (used by ToolSearchTool) */
+  toolManager?: import("../managers/toolManager.js").ToolManager;
   /** Permission mode for this tool execution */
   permissionMode?: PermissionMode;
   /** Custom permission callback */
@@ -103,4 +120,6 @@ export interface ToolContext {
   };
   /** State of files read in the current session for deduplication */
   readFileState?: Map<string, { mtime: number; hash: string }>;
+  /** Hook manager instance for executing hooks */
+  hookManager?: import("../managers/hookManager.js").HookManager;
 }

package/src/tools/webFetchTool.ts

@@ -103,6 +103,7 @@ const GITHUB_URL_ERROR =
 
 export const webFetchTool: ToolPlugin = {
   name: WEB_FETCH_TOOL_NAME,
+  shouldDefer: true,
   config: {
     type: "function",
     function: {

package/src/types/agent.ts

@@ -8,6 +8,7 @@ import type {
   ILspManager,
   PluginConfig,
   BackgroundTask,
+  McpServerConfig,
 } from "./index.js";
 import type { MessageManagerCallbacks } from "../managers/messageManager.js";
 import type { BackgroundTaskManagerCallbacks } from "../managers/backgroundTaskManager.js";
@@ -78,6 +79,11 @@ export interface AgentOptions {
    * These rules follow the standard permission rule syntax: `ToolName` or `ToolName(pattern)`.
    */
   disallowedTools?: string[];
+  /**
+   * Optional MCP server configs to connect at startup.
+   * Overrides .mcp.json for specified server names.
+   */
+  mcpServers?: Record<string, McpServerConfig>;
   [key: string]: unknown;
 }
 

package/src/types/hooks.ts

@@ -21,6 +21,7 @@ export type HookEvent =
   | "SubagentStop"
   | "PermissionRequest"
   | "WorktreeCreate"
+  | "WorktreeRemove"
   | "SessionStart"
   | "SessionEnd";
 
@@ -45,6 +46,8 @@ export interface HookExecutionContext {
   toolName?: string; // Present for PreToolUse/PostToolUse events
   projectDir: string; // Absolute path for $WAVE_PROJECT_DIR
   timestamp: Date;
+  worktreeName?: string; // Present for WorktreeCreate
+  worktreePath?: string; // Present for WorktreeRemove
 }
 
 // Result of hook execution
@@ -109,6 +112,7 @@ export function isValidHookEvent(event: string): event is HookEvent {
     "SubagentStop",
     "PermissionRequest",
     "WorktreeCreate",
+    "WorktreeRemove",
     "SessionStart",
     "SessionEnd",
   ].includes(event);

package/src/types/messaging.ts

@@ -14,6 +14,7 @@ export interface Message {
   id: string; // Unique identifier for the message
   role: "user" | "assistant";
   blocks: MessageBlock[];
+  timestamp: string; // ISO 8601 timestamp, assigned at creation
   usage?: Usage; // Usage data for this message's AI operation (assistant messages only)
   additionalFields?: Record<string, unknown>; // Additional metadata from AI responses
   isMeta?: boolean; // Whether the message is a meta message (hidden from UI)

package/src/types/session.ts

@@ -5,14 +5,6 @@
  * SIMPLIFIED: Removed unused interfaces to focus on core functionality
  */
 
-import type { Message } from "./messaging.js";
-
-// Enhanced message interface for JSONL storage (extends existing Message)
-export interface SessionMessage extends Message {
-  timestamp: string; // ISO 8601 - added for JSONL format
-  // Inherits: role: "user" | "assistant", blocks: MessageBlock[], usage?, additionalFields?
-}
-
 // Session filename structure for simple filename-based metadata
 export interface SessionFilename {
   sessionId: string;