wave-agent-sdk 0.15.1 → 0.15.2

package/src/tools/cronListTool.ts

@@ -1,20 +1,25 @@
 import { ToolPlugin, ToolResult, ToolContext } from "./types.js";
 import { CRON_LIST_TOOL_NAME } from "../constants/tools.js";
 
+const CRON_LIST_DESCRIPTION = "List scheduled cron jobs";
+
+const CRON_LIST_PROMPT = `List all cron jobs scheduled via CronCreate in this session.`;
+
 export const cronListTool: ToolPlugin = {
   name: CRON_LIST_TOOL_NAME,
+  shouldDefer: true,
   config: {
     type: "function",
     function: {
       name: CRON_LIST_TOOL_NAME,
-      description:
-        "List all cron jobs scheduled via CronCreate in this session.",
+      description: CRON_LIST_DESCRIPTION,
       parameters: {
         type: "object",
         properties: {},
       },
     },
   },
+  prompt: () => CRON_LIST_PROMPT,
   execute: async (
     _args: Record<string, unknown>,
     context: ToolContext,

package/src/tools/enterWorktreeTool.ts

@@ -0,0 +1,183 @@
+/**
+ * EnterWorktree tool - creates an isolated git worktree and switches the session into it.
+ * Mirrors Claude Code's EnterWorktree tool behavior and prompt.
+ */
+
+import type { ToolPlugin, ToolResult, ToolContext } from "./types.js";
+import {
+  getCurrentWorktreeSession,
+  setCurrentWorktreeSession,
+  type WorktreeSession,
+} from "../utils/worktreeSession.js";
+import {
+  createWorktree,
+  validateWorktreeName,
+  generateWorktreeName,
+} from "../utils/worktreeUtils.js";
+import { getGitMainRepoRoot } from "../utils/gitUtils.js";
+import { ENTER_WORKTREE_TOOL_NAME } from "../constants/tools.js";
+import { logger } from "../utils/globalLogger.js";
+
+export const ENTER_WORKTREE_TOOL_PROMPT = `Use this tool ONLY when the user explicitly asks to work in a worktree. This tool creates an isolated git worktree and switches the current session into it.
+
+## When to Use
+
+- The user explicitly says "worktree" (e.g., "start a worktree", "work in a worktree", "create a worktree", "use a worktree")
+
+## When NOT to Use
+
+- The user asks to create a branch, switch branches, or work on a different branch — use git commands instead
+- The user asks to fix a bug or work on a feature — use normal git workflow unless they specifically mention worktrees
+- Never use this tool unless the user explicitly mentions "worktree"
+
+## Requirements
+
+- Must be in a git repository
+- Must not already be in a worktree
+
+## Behavior
+
+- Creates a new git worktree inside \`.wave/worktrees/\` with a new branch based on HEAD
+- Switches the session's working directory to the new worktree
+- Use ExitWorktree to leave the worktree mid-session (keep or remove). On session exit, if still in the worktree, the user will be prompted to keep or remove it
+
+## Parameters
+
+- \`name\` (optional): A name for the worktree. Each "/"-separated segment may contain only letters, digits, dots, underscores, and dashes; max 64 chars total. A random name is generated if not provided.
+`;
+
+export const enterWorktreeTool: ToolPlugin = {
+  name: ENTER_WORKTREE_TOOL_NAME,
+  shouldDefer: true,
+  config: {
+    type: "function",
+    function: {
+      name: ENTER_WORKTREE_TOOL_NAME,
+      description: ENTER_WORKTREE_TOOL_PROMPT,
+      parameters: {
+        type: "object",
+        properties: {
+          name: {
+            type: "string",
+            description:
+              'Optional name for the worktree. Each "/"-separated segment may contain only letters, digits, dots, underscores, and dashes; max 64 chars total. A random name is generated if not provided.',
+          },
+        },
+      },
+    },
+  },
+  prompt: () => ENTER_WORKTREE_TOOL_PROMPT,
+
+  async execute(
+    args: Record<string, unknown>,
+    context: ToolContext,
+  ): Promise<ToolResult> {
+    // Validate not already in a worktree created by this session
+    if (getCurrentWorktreeSession()) {
+      return {
+        success: false,
+        content:
+          "Already in a worktree session. Use ExitWorktree to leave before creating a new one.",
+        error: "Already in a worktree session",
+      };
+    }
+
+    const name = (args.name as string) || generateWorktreeName();
+
+    // Validate the worktree name
+    try {
+      validateWorktreeName(name);
+    } catch (e) {
+      return {
+        success: false,
+        content: `Invalid worktree name: ${(e as Error).message}`,
+        error: `Invalid worktree name: ${(e as Error).message}`,
+      };
+    }
+
+    // Resolve to main repo root so worktree creation works from within a subdirectory
+    const mainRepoRoot = getGitMainRepoRoot(context.workdir);
+    if (!mainRepoRoot) {
+      return {
+        success: false,
+        content:
+          "Cannot create a worktree: not in a git repository. Configure WorktreeCreate and WorktreeRemove hooks in settings.json to use worktree isolation with other VCS systems.",
+        error: "Not in a git repository",
+      };
+    }
+
+    // Create the worktree (captures originalHeadCommit internally)
+    const worktreeInfo = createWorktree(name, mainRepoRoot);
+
+    // Build session state
+    const session: WorktreeSession = {
+      originalCwd: context.workdir,
+      worktreePath: worktreeInfo.path,
+      worktreeBranch: worktreeInfo.branch,
+      worktreeName: worktreeInfo.name,
+      isNew: worktreeInfo.isNew,
+      repoRoot: worktreeInfo.repoRoot,
+      originalHeadCommit: worktreeInfo.originalHeadCommit,
+    };
+
+    // Set module-level session state
+    setCurrentWorktreeSession(session);
+
+    // Update CWD via AIManager
+    const aiManager = context.aiManager;
+    if (aiManager) {
+      aiManager.setWorkdir(worktreeInfo.path);
+    }
+
+    // Also update the container's Workdir entry
+    // (Container is not directly accessible from ToolContext, but AIManager.setWorkdir
+    // handles both its internal field and process.chdir)
+
+    // Trigger WorktreeCreate hook if worktree is new
+    let hookTriggered = false;
+    if (session.isNew && context.hookManager) {
+      try {
+        const hookResults = await context.hookManager.executeHooks(
+          "WorktreeCreate",
+          {
+            event: "WorktreeCreate",
+            projectDir: worktreeInfo.path,
+            timestamp: new Date(),
+            sessionId: context.sessionId ?? "",
+            transcriptPath: context.messageManager?.getTranscriptPath() ?? "",
+            cwd: worktreeInfo.path,
+            worktreeName: worktreeInfo.name,
+            env: Object.fromEntries(
+              Object.entries(process.env).filter((e) => e[1] !== undefined),
+            ) as Record<string, string>,
+          },
+        );
+
+        if (context.messageManager) {
+          context.hookManager.processHookResults(
+            "WorktreeCreate",
+            hookResults,
+            context.messageManager,
+          );
+        }
+
+        hookTriggered = true;
+      } catch (error) {
+        // Non-blocking: log but don't fail the tool
+        logger?.warn("WorktreeCreate hooks execution failed:", error);
+      }
+    }
+
+    const branchInfo = worktreeInfo.branch
+      ? ` on branch ${worktreeInfo.branch}`
+      : "";
+    const hookInfo = hookTriggered
+      ? " WorktreeCreate hooks were executed."
+      : "";
+
+    return {
+      success: true,
+      content: `Created worktree at ${worktreeInfo.path}${branchInfo}. The session is now working in the worktree. Use ExitWorktree to leave mid-session, or exit the session to be prompted.${hookInfo}`,
+    };
+  },
+};

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/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: {