wave-agent-sdk 0.15.1 → 0.15.2

package/src/managers/mcpManager.ts

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

package/src/managers/permissionManager.ts

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

package/src/managers/slashCommandManager.ts

@@ -23,6 +23,7 @@ import {
 import type { SkillManager } from "./skillManager.js";
 import type { SkillMetadata } from "../types/skills.js";
 import type { SubagentManager } from "./subagentManager.js";
+import type { MemoryService } from "../services/memory.js";
 
 import { logger } from "../utils/globalLogger.js";
 
@@ -81,6 +82,10 @@ export class SlashCommandManager {
     return this.container.get<SubagentManager>("SubagentManager")!;
   }
 
+  private get memoryService(): MemoryService {
+    return this.container.get<MemoryService>("MemoryService")!;
+  }
+
   private initializeBuiltinCommands(): void {
     // Register built-in clear command
     this.registerCommand({
@@ -90,6 +95,7 @@ export class SlashCommandManager {
       handler: async () => {
         this.aiManager.abortAIMessage();
         this.messageManager.clearMessages();
+        this.memoryService.clearCache();
         await this.taskManager.syncWithSession();
       },
     });

package/src/managers/toolManager.ts

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

package/src/prompts/index.ts

@@ -1,6 +1,7 @@
 import * as os from "node:os";
 import { ToolPlugin } from "../tools/types.js";
 import { isGitRepository } from "../utils/gitUtils.js";
+import { getCurrentWorktreeSession } from "../utils/worktreeSession.js";
 import { buildAutoMemoryPrompt } from "./autoMemory.js";
 import { PermissionMode } from "../types/permissions.js";
 import {
@@ -17,7 +18,9 @@ import {
   READ_TOOL_NAME,
   GLOB_TOOL_NAME,
   GREP_TOOL_NAME,
+  TOOL_SEARCH_TOOL_NAME,
 } from "../constants/tools.js";
+import { isDeferredTool } from "../utils/isDeferredTool.js";
 
 export const BASE_SYSTEM_PROMPT = `You are an interactive CLI tool that helps users with software engineering tasks. Use the instructions below and the tools available to you to assist the user.`;
 
@@ -257,6 +260,13 @@ export function buildSystemPrompt(
     prompt += `\n\n${TOOL_POLICY}`;
   }
 
+  // List available deferred tool names so the model knows they exist
+  // Matching Claude Code: deferred tools appear by name, not loaded until fetched.
+  const deferredToolNames = tools.filter(isDeferredTool).map((t) => t.name);
+  if (deferredToolNames.length > 0) {
+    prompt += `\n\n<available-deferred-tools>${deferredToolNames.join(" ")}\nThese tools are NOT loaded yet — call ${TOOL_SEARCH_TOOL_NAME} first to discover their schemas before invoking them.</available-deferred-tools>`;
+  }
+
   prompt += `\n\n${OUTPUT_EFFICIENCY_PROMPT}`;
   prompt += `\n\n${TONE_AND_STYLE_PROMPT}`;
 
@@ -284,11 +294,13 @@ export function buildSystemPrompt(
         ? "bash"
         : shell;
 
+    const worktreeSession = getCurrentWorktreeSession();
+
     prompt += `
 
 Here is useful information about the environment you are running in:
 <env>
-Working directory: ${options.workdir}
+Working directory: ${options.workdir}${worktreeSession ? `\nThis is a git worktree — an isolated copy of the repository. Run all commands from this directory. Do NOT \`cd\` to the original repository root at ${worktreeSession.originalCwd}.` : ""}
 Is directory a git repo: ${isGitRepo}
 Platform: ${platform}
 Shell: ${shellName}
@@ -327,8 +339,10 @@ export function enhanceSystemPromptWithEnvDetails(
       ? "bash"
       : shell;
 
+  const worktreeSession = getCurrentWorktreeSession();
+
   const notes = `Notes:
-- Agent threads always have their cwd reset between bash calls, as a result please only use absolute file paths.
+- Agent threads always have their cwd reset between bash calls, as a result please only use absolute file paths.${worktreeSession ? `\n- You are in a git worktree at ${worktreeSession.worktreePath} (branch: ${worktreeSession.worktreeBranch}). Absolute paths from prior context may refer to the original repo at ${worktreeSession.originalCwd}; translate them to your worktree. Do NOT edit files outside this worktree.` : ""}
 - In your final response, share file paths (always absolute, never relative) that are relevant to the task. Include code snippets only when the exact text is load-bearing (e.g., a bug you found, a function signature the caller asked for) — do not recap code you merely read.
 - For clear communication with the user the assistant MUST avoid using emojis.
 - Do not use a colon before tool calls. Text like "Let me read the file:" followed by a read tool call should just be "Let me read the file." with a period.`;
@@ -339,7 +353,7 @@ ${notes}
 
 Here is useful information about the environment you are running in:
 <env>
-Working directory: ${workdir}
+Working directory: ${workdir}${worktreeSession ? `\nThis is a git worktree — an isolated copy of the repository. Run all commands from this directory. Do NOT \`cd\` to the original repository root at ${worktreeSession.originalCwd}.` : ""}
 Is directory a git repo: ${isGitRepo}
 Platform: ${platform}
 Shell: ${shellName}

package/src/services/initializationService.ts

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

package/src/services/memory.ts

@@ -8,8 +8,26 @@ import { getGitCommonDir } from "../utils/gitUtils.js";
 import { pathEncoder } from "../utils/pathEncoder.js";
 
 export class MemoryService {
+  private _cachedProjectMemory: string = "";
+  private _cachedUserMemory: string = "";
+  private _cachedCombinedMemory: string | null = null;
+
   constructor(private container: Container) {}
 
+  public get cachedProjectMemory(): string {
+    return this._cachedProjectMemory;
+  }
+
+  public get cachedUserMemory(): string {
+    return this._cachedUserMemory;
+  }
+
+  public clearCache(): void {
+    this._cachedProjectMemory = "";
+    this._cachedUserMemory = "";
+    this._cachedCombinedMemory = null;
+  }
+
   /**
    * Get the project-specific auto-memory directory.
    * Uses the git common directory to ensure worktrees share the same memory.
@@ -143,24 +161,19 @@ export class MemoryService {
   }
 
   async getCombinedMemoryContent(workdir: string): Promise<string> {
-    // Read memory file content
-    const memoryContent = await this.readMemoryFile(workdir);
-
-    // Read user-level memory content
-    const userMemoryContent = await this.getUserMemoryContent();
-
-    // Merge project memory and user memory
-    let combinedMemory = "";
-    if (memoryContent.trim()) {
-      combinedMemory += memoryContent;
+    if (this._cachedCombinedMemory !== null) {
+      return this._cachedCombinedMemory;
     }
-    if (userMemoryContent.trim()) {
-      if (combinedMemory) {
-        combinedMemory += "\n\n";
-      }
-      combinedMemory += userMemoryContent;
+    this._cachedProjectMemory = await this.readMemoryFile(workdir);
+    this._cachedUserMemory = await this.getUserMemoryContent();
+
+    let combined = "";
+    if (this._cachedProjectMemory.trim()) combined += this._cachedProjectMemory;
+    if (this._cachedUserMemory.trim()) {
+      if (combined) combined += "\n\n";
+      combined += this._cachedUserMemory;
     }
-
-    return combinedMemory;
+    this._cachedCombinedMemory = combined;
+    return combined;
   }
 }

package/src/tools/cronCreateTool.ts

@@ -1,30 +1,73 @@
 import { ToolPlugin, ToolResult, ToolContext } from "./types.js";
 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: ToolPlugin = {
   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"',
+              '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,
           },
         },
@@ -32,6 +75,7 @@ export const cronCreateTool: ToolPlugin = {
       },
     },
   },
+  prompt: () => CRON_CREATE_PROMPT,
   execute: async (
     args: Record<string, unknown>,
     context: ToolContext,
@@ -50,6 +94,25 @@ export const cronCreateTool: ToolPlugin = {
       };
     }
 
+    // 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,
@@ -57,10 +120,20 @@ export const cronCreateTool: ToolPlugin = {
         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) {
       return {

package/src/tools/cronDeleteTool.ts

@@ -1,14 +1,18 @@
 import { ToolPlugin, ToolResult, ToolContext } from "./types.js";
 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: ToolPlugin = {
   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: {
@@ -21,6 +25,7 @@ export const cronDeleteTool: ToolPlugin = {
       },
     },
   },
+  prompt: () => CRON_DELETE_PROMPT,
   execute: async (
     args: Record<string, unknown>,
     context: ToolContext,