wave-agent-sdk 0.15.0 → 0.15.2

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/skillTool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skillTool.d.ts","sourceRoot":"","sources":["../../src/tools/skillTool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAA2B,MAAM,YAAY,CAAC;AAgBtE,eAAO,MAAM,SAAS,EAAE,UAmNvB,CAAC"}
+{"version":3,"file":"skillTool.d.ts","sourceRoot":"","sources":["../../src/tools/skillTool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAA2B,MAAM,YAAY,CAAC;AAgBtE,eAAO,MAAM,SAAS,EAAE,UAuOvB,CAAC"}

package/dist/tools/skillTool.js

@@ -109,17 +109,29 @@ export const skillTool = {
                     // 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) => {
+                        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);
                 });
                 try {

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"}

package/dist/tools/toolSearchTool.js

@@ -0,0 +1,185 @@
+/**
+ * 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 { isDeferredTool, TOOL_SEARCH_TOOL_NAME, } from "../utils/isDeferredTool.js";
+function formatSchema(tool) {
+    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) {
+    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, deferredTools, maxResults) {
+    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 = [];
+    const optionalTerms = [];
+    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 = {
+    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, context) => {
+        const { query, max_results = 5 } = args;
+        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 = [];
+            const missing = [];
+            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) {
+    return tools.map((t) => t.name).join(", ");
+}

package/dist/tools/types.d.ts

@@ -19,6 +19,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 {
     success: boolean;
@@ -38,6 +53,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 */
@@ -86,5 +103,7 @@ export interface ToolContext {
         mtime: number;
         hash: string;
     }>;
+    /** Hook manager instance for executing hooks */
+    hookManager?: import("../managers/hookManager.js").HookManager;
 }
 //# sourceMappingURL=types.d.ts.map