wave-agent-sdk 0.15.1 → 0.15.2

package/dist/tools/cronCreateTool.js

@@ -1,25 +1,67 @@
 import { CRON_CREATE_TOOL_NAME } from "../constants/tools.js";
+import { cronToHuman } from "../utils/cronToHuman.js";
+import { parseCronExpression } from "../utils/parseCronExpression.js";
+const DEFAULT_MAX_AGE_DAYS = 7;
+const MAX_JOBS = 50;
+const CRON_CREATE_DESCRIPTION = `Schedule a prompt to run at a future time within this Wave session — either recurring on a cron schedule, or once at a specific time.`;
+const CRON_CREATE_PROMPT = `Schedule a prompt to be enqueued at a future time. Use for both recurring schedules and one-shot reminders.
+
+Uses standard 5-field cron in the user's local timezone: minute hour day-of-month month day-of-week. "0 9 * * *" means 9am local — no timezone conversion needed.
+
+## One-shot tasks (recurring: false)
+
+For "remind me at X" or "at <time>, do Y" requests — fire once then auto-delete.
+Pin minute/hour/day-of-month/month to specific values:
+  "remind me at 2:30pm today to check the deploy" → cron: "30 14 <today_dom> <today_month> *", recurring: false
+  "tomorrow morning, run the smoke test" → cron: "57 8 <tomorrow_dom> <tomorrow_month> *", recurring: false
+
+## Recurring jobs (recurring: true, the default)
+
+For "every N minutes" / "every hour" / "weekdays at 9am" requests:
+  "*/5 * * * *" (every 5 min), "0 * * * *" (hourly), "0 9 * * 1-5" (weekdays at 9am local)
+
+## Avoid the :00 and :30 minute marks when the task allows it
+
+Every user who asks for "9am" gets \`0 9\`, and every user who asks for "hourly" gets \`0 *\` — which means requests from across the planet land on the API at the same instant. When the user's request is approximate, pick a minute that is NOT 0 or 30:
+  "every morning around 9" → "57 8 * * *" or "3 9 * * *" (not "0 9 * * *")
+  "hourly" → "7 * * * *" (not "0 * * * *")
+  "in an hour or so, remind me to..." → pick whatever minute you land on, don't round
+
+Only use minute 0 or 30 when the user names that exact time and clearly means it ("at 9:00 sharp", "at half past", coordinating with a meeting). When in doubt, nudge a few minutes early or late — the user will not notice, and the fleet will.
+
+## Session-only
+
+Jobs live only in this Wave session — nothing is written to disk, and the job is gone when Wave exits.
+
+## Runtime behavior
+
+Jobs only fire while the REPL is idle (not mid-query). The scheduler adds a small deterministic jitter on top of whatever you pick: recurring tasks fire up to 10% of their period late (max 15 min); one-shot tasks landing on :00 or :30 fire up to 90s early. Picking an off-minute is still the bigger lever.
+
+Recurring tasks auto-expire after ${DEFAULT_MAX_AGE_DAYS} days — they fire one final time, then are deleted. This bounds session lifetime. Tell the user about the ${DEFAULT_MAX_AGE_DAYS}-day limit when scheduling recurring jobs.
+
+Returns a job ID you can pass to CronDelete.`;
 export const cronCreateTool = {
     name: CRON_CREATE_TOOL_NAME,
+    shouldDefer: true,
     config: {
         type: "function",
         function: {
             name: CRON_CREATE_TOOL_NAME,
-            description: "Schedule a prompt to be enqueued at a future time. Use for both recurring schedules and one-shot reminders.",
+            description: CRON_CREATE_DESCRIPTION,
             parameters: {
                 type: "object",
                 properties: {
                     cron: {
                         type: "string",
-                        description: 'Standard 5-field cron expression in local time: "M H DoM Mon DoW"',
+                        description: 'Standard 5-field cron expression in local time: "M H DoM Mon DoW" (e.g. "*/5 * * * *" = every 5 minutes, "30 14 28 2 *" = Feb 28 at 2:30pm local once).',
                     },
                     prompt: {
                         type: "string",
-                        description: "The prompt to enqueue at each fire time",
+                        description: "The prompt to enqueue at each fire time.",
                     },
                     recurring: {
                         type: "boolean",
-                        description: "Default: true. true = fire on every cron match until deleted or auto-expired after 7 days. false = fire once at the next match, then auto-delete",
+                        description: `true (default) = fire on every cron match until deleted or auto-expired after ${DEFAULT_MAX_AGE_DAYS} days. false = fire once at the next match, then auto-delete. Use false for "remind me at X" one-shot requests with pinned minute/hour/dom/month.`,
                         default: true,
                     },
                 },
@@ -27,6 +69,7 @@ export const cronCreateTool = {
             },
         },
     },
+    prompt: () => CRON_CREATE_PROMPT,
     execute: async (args, context) => {
         const { cron, prompt, recurring = true, } = args;
         if (!context.cronManager) {
@@ -36,16 +79,38 @@ export const cronCreateTool = {
                 error: "CronManager not available",
             };
         }
+        // Validate cron expression
+        if (!parseCronExpression(cron)) {
+            return {
+                success: false,
+                content: "",
+                error: `Invalid cron expression '${cron}'. Expected 5 fields: M H DoM Mon DoW.`,
+            };
+        }
+        // Check max jobs limit
+        const existingJobs = context.cronManager.listJobs();
+        if (existingJobs.length >= MAX_JOBS) {
+            return {
+                success: false,
+                content: "",
+                error: `Too many scheduled jobs (max ${MAX_JOBS}). Cancel one first.`,
+            };
+        }
         try {
             const job = context.cronManager.createJob({
                 cron,
                 prompt,
                 recurring,
             });
+            const humanSchedule = cronToHuman(cron);
+            const where = "Session-only (not written to disk, dies when Wave exits)";
+            const resultMessage = recurring
+                ? `Scheduled recurring job ${job.id} (${humanSchedule}). ${where}. Auto-expires after ${DEFAULT_MAX_AGE_DAYS} days. Use CronDelete to cancel sooner.`
+                : `Scheduled one-shot task ${job.id} (${humanSchedule}). ${where}. It will fire once then auto-delete.`;
             return {
                 success: true,
-                content: JSON.stringify({ id: job.id }, null, 2),
-                shortResult: `Scheduled job ${job.id}`,
+                content: JSON.stringify({ id: job.id, humanSchedule, recurring }, null, 2),
+                shortResult: resultMessage,
             };
         }
         catch (error) {

package/dist/tools/cronDeleteTool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cronDeleteTool.d.ts","sourceRoot":"","sources":["../../src/tools/cronDeleteTool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAA2B,MAAM,YAAY,CAAC;AAGjE,eAAO,MAAM,cAAc,EAAE,UA2C5B,CAAC"}
+{"version":3,"file":"cronDeleteTool.d.ts","sourceRoot":"","sources":["../../src/tools/cronDeleteTool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAA2B,MAAM,YAAY,CAAC;AAOjE,eAAO,MAAM,cAAc,EAAE,UA4C5B,CAAC"}

package/dist/tools/cronDeleteTool.js

@@ -1,11 +1,14 @@
 import { CRON_DELETE_TOOL_NAME } from "../constants/tools.js";
+const CRON_DELETE_DESCRIPTION = "Cancel a scheduled cron job by ID";
+const CRON_DELETE_PROMPT = `Cancel a cron job previously scheduled with CronCreate. Removes it from the in-memory session store.`;
 export const cronDeleteTool = {
     name: CRON_DELETE_TOOL_NAME,
+    shouldDefer: true,
     config: {
         type: "function",
         function: {
             name: CRON_DELETE_TOOL_NAME,
-            description: "Cancel a cron job previously scheduled with CronCreate. Removes it from the in-memory session store.",
+            description: CRON_DELETE_DESCRIPTION,
             parameters: {
                 type: "object",
                 properties: {
@@ -18,6 +21,7 @@ export const cronDeleteTool = {
             },
         },
     },
+    prompt: () => CRON_DELETE_PROMPT,
     execute: async (args, context) => {
         const { id } = args;
         if (!context.cronManager) {

package/dist/tools/cronListTool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cronListTool.d.ts","sourceRoot":"","sources":["../../src/tools/cronListTool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAA2B,MAAM,YAAY,CAAC;AAGjE,eAAO,MAAM,YAAY,EAAE,UAkC1B,CAAC"}
+{"version":3,"file":"cronListTool.d.ts","sourceRoot":"","sources":["../../src/tools/cronListTool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAA2B,MAAM,YAAY,CAAC;AAOjE,eAAO,MAAM,YAAY,EAAE,UAmC1B,CAAC"}

package/dist/tools/cronListTool.js

@@ -1,17 +1,21 @@
 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 = {
     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, context) => {
         if (!context.cronManager) {
             return {

package/dist/tools/enterWorktreeTool.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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 } from "./types.js";
+export declare 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.\n\n## When to Use\n\n- The user explicitly says \"worktree\" (e.g., \"start a worktree\", \"work in a worktree\", \"create a worktree\", \"use a worktree\")\n\n## When NOT to Use\n\n- The user asks to create a branch, switch branches, or work on a different branch \u2014 use git commands instead\n- The user asks to fix a bug or work on a feature \u2014 use normal git workflow unless they specifically mention worktrees\n- Never use this tool unless the user explicitly mentions \"worktree\"\n\n## Requirements\n\n- Must be in a git repository\n- Must not already be in a worktree\n\n## Behavior\n\n- Creates a new git worktree inside `.wave/worktrees/` with a new branch based on HEAD\n- Switches the session's working directory to the new worktree\n- 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\n\n## Parameters\n\n- `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.\n";
+export declare const enterWorktreeTool: ToolPlugin;
+//# sourceMappingURL=enterWorktreeTool.d.ts.map

package/dist/tools/enterWorktreeTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enterWorktreeTool.d.ts","sourceRoot":"","sources":["../../src/tools/enterWorktreeTool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,UAAU,EAA2B,MAAM,YAAY,CAAC;AAetE,eAAO,MAAM,0BAA0B,qxCA0BtC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,UAsI/B,CAAC"}

package/dist/tools/enterWorktreeTool.js

@@ -0,0 +1,144 @@
+/**
+ * EnterWorktree tool - creates an isolated git worktree and switches the session into it.
+ * Mirrors Claude Code's EnterWorktree tool behavior and prompt.
+ */
+import { getCurrentWorktreeSession, setCurrentWorktreeSession, } 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 = {
+    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, context) {
+        // 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 || generateWorktreeName();
+        // Validate the worktree name
+        try {
+            validateWorktreeName(name);
+        }
+        catch (e) {
+            return {
+                success: false,
+                content: `Invalid worktree name: ${e.message}`,
+                error: `Invalid worktree name: ${e.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 = {
+            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)),
+                });
+                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/dist/tools/exitWorktreeTool.d.ts

@@ -0,0 +1,8 @@
+/**
+ * ExitWorktree tool - exits a worktree session and returns to the original directory.
+ * Mirrors Claude Code's ExitWorktree tool behavior and prompt.
+ */
+import type { ToolPlugin } from "./types.js";
+export declare const EXIT_WORKTREE_TOOL_PROMPT = "Exit a worktree session created by EnterWorktree and return the session to the original working directory.\n\n## Scope\n\nThis tool ONLY operates on worktrees created by EnterWorktree in this session. It will NOT touch:\n- Worktrees you created manually with `git worktree add`\n- Worktrees from a previous session (even if created by EnterWorktree then)\n- The directory you're in if EnterWorktree was never called\n\nIf 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.\n\n## When to Use\n\n- The user explicitly asks to \"exit the worktree\", \"leave the worktree\", \"go back\", or otherwise end the worktree session\n- Do NOT call this proactively \u2014 only when the user asks\n\n## Parameters\n\n- `action` (required): `\"keep\"` or `\"remove\"`\n  - `\"keep\"` \u2014 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.\n  - `\"remove\"` \u2014 delete the worktree directory and its branch. Use this for a clean exit when the work is done or abandoned.\n- `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`.\n\n## Behavior\n\n- Restores the session's working directory to where it was before EnterWorktree\n- If action is \"remove\": deletes the worktree directory and branch\n- Once exited, EnterWorktree can be called again to create a fresh worktree\n";
+export declare const exitWorktreeTool: ToolPlugin;
+//# sourceMappingURL=exitWorktreeTool.d.ts.map

package/dist/tools/exitWorktreeTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exitWorktreeTool.d.ts","sourceRoot":"","sources":["../../src/tools/exitWorktreeTool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,UAAU,EAA2B,MAAM,YAAY,CAAC;AAYtE,eAAO,MAAM,yBAAyB,gvDA4BrC,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,UAkM9B,CAAC"}

package/dist/tools/exitWorktreeTool.js

@@ -0,0 +1,184 @@
+/**
+ * ExitWorktree tool - exits a worktree session and returns to the original directory.
+ * Mirrors Claude Code's ExitWorktree tool behavior and prompt.
+ */
+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 = {
+    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, context) {
+        const action = args.action;
+        const discardChanges = args.discard_changes ?? 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 = [];
+                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)),
+                });
+                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 = [];
+        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/dist/tools/taskManagementTools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"taskManagementTools.d.ts","sourceRoot":"","sources":["../../src/tools/taskManagementTools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAA2B,MAAM,YAAY,CAAC;AASjE,eAAO,MAAM,cAAc,EAAE,UAoI5B,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,UAyDzB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,UAgW5B,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,UAkE1B,CAAC"}
+{"version":3,"file":"taskManagementTools.d.ts","sourceRoot":"","sources":["../../src/tools/taskManagementTools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAA2B,MAAM,YAAY,CAAC;AASjE,eAAO,MAAM,cAAc,EAAE,UAqI5B,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,UA0DzB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,UAiW5B,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,UAmE1B,CAAC"}

package/dist/tools/taskManagementTools.js

@@ -1,6 +1,7 @@
 import { TASK_CREATE_TOOL_NAME, TASK_GET_TOOL_NAME, TASK_UPDATE_TOOL_NAME, TASK_LIST_TOOL_NAME, } from "../constants/tools.js";
 export const taskCreateTool = {
     name: TASK_CREATE_TOOL_NAME,
+    shouldDefer: true,
     config: {
         type: "function",
         function: {
@@ -123,6 +124,7 @@ NOTE that you should not use this tool if there is only one trivial task to do.
 };
 export const taskGetTool = {
     name: TASK_GET_TOOL_NAME,
+    shouldDefer: true,
     config: {
         type: "function",
         function: {
@@ -179,6 +181,7 @@ Returns full task details:
 };
 export const taskUpdateTool = {
     name: TASK_UPDATE_TOOL_NAME,
+    shouldDefer: true,
     config: {
         type: "function",
         function: {
@@ -478,6 +481,7 @@ Set up task dependencies:
 };
 export const taskListTool = {
     name: TASK_LIST_TOOL_NAME,
+    shouldDefer: true,
     config: {
         type: "function",
         function: {

package/dist/tools/toolSearchTool.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 } from "./types.js";
+export declare const toolSearchTool: ToolPlugin;
+//# sourceMappingURL=toolSearchTool.d.ts.map

package/dist/tools/toolSearchTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolSearchTool.d.ts","sourceRoot":"","sources":["../../src/tools/toolSearchTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAA2B,MAAM,YAAY,CAAC;AA4GjE,eAAO,MAAM,cAAc,EAAE,UAsG5B,CAAC"}