wave-agent-sdk 0.13.5 → 0.14.0

package/src/managers/aiManager.ts

@@ -1,6 +1,7 @@
 import { type CallAgentOptions } from "../services/aiService.js";
 import * as aiService from "../services/aiService.js";
 import { convertMessagesForAPI } from "../utils/convertMessagesForAPI.js";
+import { microcompactMessages } from "../utils/microcompact.js";
 import { parseTaskNotificationXml } from "../utils/notificationXml.js";
 import { calculateComprehensiveTotalTokens } from "../utils/tokenCalculation.js";
 import * as fs from "node:fs/promises";
@@ -15,7 +16,6 @@ import type { ToolManager } from "./toolManager.js";
 import type { ToolContext, ToolResult } from "../tools/types.js";
 import type { MessageManager } from "./messageManager.js";
 import type { BackgroundTaskManager } from "./backgroundTaskManager.js";
-import type { NotificationQueue } from "./notificationQueue.js";
 import { ChatCompletionMessageFunctionToolCall } from "openai/resources.js";
 import type { HookManager } from "./hookManager.js";
 import type { ExtendedHookExecutionContext } from "../types/hooks.js";
@@ -25,6 +25,7 @@ import type { SkillManager } from "./skillManager.js";
 import { buildSystemPrompt } from "../prompts/index.js";
 import { Container } from "../utils/container.js";
 import { ConfigurationService } from "../services/configurationService.js";
+import type { NotificationQueue } from "./notificationQueue.js";
 
 import { logger } from "../utils/globalLogger.js";
 
@@ -51,11 +52,13 @@ export class AIManager {
   onLoadingChange?: (loading: boolean) => void;
   private toolAbortController: AbortController | null = null;
   private workdir: string;
+  private originalWorkdir: string;
   private systemPrompt?: string;
   private subagentType?: string; // Store subagent type for hook context
   private stream: boolean; // Streaming mode flag
   private modelOverride?: string;
   private _onCwdChange?: (newCwd: string) => void; // Store callback for CWD changes
+  private consecutiveCompressionFailures: number = 0;
 
   // Service overrides
   constructor(
@@ -63,6 +66,7 @@ export class AIManager {
     options: AIManagerOptions,
   ) {
     this.workdir = options.workdir;
+    this.originalWorkdir = options.workdir;
     this.systemPrompt = options.systemPrompt;
     this.subagentType = options.subagentType; // Store subagent type
     this.stream = options.stream ?? true; // Default to true if not specified
@@ -165,6 +169,10 @@ export class AIManager {
     return this.workdir;
   }
 
+  public getOriginalWorkdir(): string {
+    return this.originalWorkdir;
+  }
+
   public setOnCwdChange(callback: (newCwd: string) => void): void {
     this._onCwdChange = callback;
   }
@@ -234,6 +242,7 @@ export class AIManager {
       if (toolPlugin?.formatCompactParams) {
         const context: ToolContext = {
           workdir: this.workdir,
+          originalWorkdir: this.originalWorkdir,
           taskManager: this.taskManager,
         };
         return toolPlugin.formatCompactParams(toolArgs, context);
@@ -248,7 +257,6 @@ export class AIManager {
   private async handleTokenUsageAndCompression(
     usage: Usage | undefined,
     abortController: AbortController,
-    model?: string,
   ): Promise<void> {
     if (!usage) return;
 
@@ -272,6 +280,14 @@ export class AIManager {
 
       // If there are messages to compress, perform compression
       if (messagesToCompress.length > 0) {
+        // Circuit breaker: skip compression after 3 consecutive failures
+        if (this.consecutiveCompressionFailures >= 3) {
+          logger?.warn(
+            `Skipping compression: ${this.consecutiveCompressionFailures} consecutive failures`,
+          );
+          return;
+        }
+
         const recentChatMessages = convertMessagesForAPI(messagesToCompress);
 
         // Save session before compression to preserve original messages
@@ -284,7 +300,7 @@ export class AIManager {
             modelConfig: this.getModelConfig(),
             messages: recentChatMessages,
             abortSignal: abortController.signal,
-            model: model,
+            model: this.getModelConfig().fastModel,
           });
 
           // Handle usage tracking for compression operations
@@ -294,14 +310,91 @@ export class AIManager {
               prompt_tokens: compressionResult.usage.prompt_tokens,
               completion_tokens: compressionResult.usage.completion_tokens,
               total_tokens: compressionResult.usage.total_tokens,
-              model: model || this.getModelConfig().model,
+              model: this.getModelConfig().fastModel,
               operation_type: "compress",
             };
           }
 
+          // Build post-compact context restoration
+          const POST_COMPACT_TOKEN_BUDGET = 50_000;
+          const POST_COMPACT_MAX_TOKENS_PER_FILE = 5_000;
+          const POST_COMPACT_MAX_FILES_TO_RESTORE = 5;
+          const contextParts: string[] = [];
+
+          // 1. File context restoration
+          const recentFiles = this.messageManager.getRecentFileReads(
+            POST_COMPACT_MAX_FILES_TO_RESTORE,
+            POST_COMPACT_MAX_TOKENS_PER_FILE,
+          );
+          let usedTokens = 0;
+          for (const file of recentFiles) {
+            const fileTokens = Math.ceil(file.content.length / 4);
+            if (usedTokens + fileTokens > POST_COMPACT_MAX_TOKENS_PER_FILE)
+              continue;
+            if (fileTokens > 0) usedTokens += fileTokens;
+            contextParts.push(
+              `\n\n## ${file.path}\n\`\`\`\n${file.content}\n\`\`\``,
+            );
+            if (contextParts.length >= POST_COMPACT_MAX_FILES_TO_RESTORE) break;
+            if (usedTokens >= POST_COMPACT_TOKEN_BUDGET) break;
+          }
+
+          // 2. Working directory
+          contextParts.push(
+            `\n\n[Working Directory]\nCurrent working directory: ${this.workdir}`,
+          );
+
+          // 3. Plan mode context
+          const currentMode = this.permissionManager?.getCurrentEffectiveMode(
+            this.getModelConfig().permissionMode,
+          );
+          if (currentMode === "plan") {
+            const planFilePath = this.permissionManager?.getPlanFilePath();
+            if (planFilePath) {
+              let planExists = false;
+              try {
+                await fs.access(planFilePath);
+                planExists = true;
+              } catch {
+                // Plan file doesn't exist yet
+              }
+              contextParts.push(
+                `\n\n[Plan Mode]\nYou are in plan mode. Plan file: ${planFilePath} (exists: ${planExists})`,
+              );
+            }
+          }
+
+          // 4. Skills context
+          const skills =
+            this.skillManager
+              ?.getAvailableSkills()
+              .filter((s) => !s.disableModelInvocation) || [];
+          if (skills.length > 0) {
+            const skillList = skills
+              .map((s) => `- ${s.name}: ${s.description || ""}`)
+              .join("\n");
+            contextParts.push(`\n\n[Available Skills]\n${skillList}`);
+          }
+
+          // 5. Background agents status
+          const agents = this.backgroundTaskManager?.getAllTasks() || [];
+          if (agents.length > 0) {
+            const agentList = agents
+              .map((a) => `- Agent "${a.description}": ${a.status}`)
+              .join("\n");
+            contextParts.push(`\n\n[Background Tasks]\n${agentList}`);
+          }
+
+          // Merge context restoration into summary
+          const enhancedSummary =
+            compressionResult.content +
+            (contextParts.length > 0
+              ? `\n\n[Context Restoration]` + contextParts.join("")
+              : "");
+
           // Execute message reconstruction and sessionId update after compression
           this.messageManager.compressMessagesAndUpdateSession(
-            compressionResult.content,
+            enhancedSummary,
             compressionUsage,
           );
 
@@ -313,8 +406,13 @@ export class AIManager {
           logger?.debug(
             `Successfully compressed ${messagesToCompress.length} messages and updated session`,
           );
+          this.consecutiveCompressionFailures = 0;
         } catch (compressError) {
-          logger?.error("Failed to compress messages:", compressError);
+          this.consecutiveCompressionFailures++;
+          logger?.error(
+            `Failed to compress messages (${this.consecutiveCompressionFailures} consecutive):`,
+            compressError,
+          );
           this.messageManager.addErrorBlock(
             `Failed to compress conversation history: ${compressError instanceof Error ? compressError.message : String(compressError)}. You may encounter context limit issues.`,
           );
@@ -403,10 +501,13 @@ export class AIManager {
       toolAbortController = this.toolAbortController!;
     }
 
-    // Get recent message history
-    const recentMessages = convertMessagesForAPI(
-      this.messageManager.getMessages(),
-    );
+    // Get recent message history with microcompact applied
+    const rawMessages = this.messageManager.getMessages();
+    const microcompactedMessages = microcompactMessages(rawMessages, {
+      timeThresholdMS: 30 * 60 * 1000, // 30 minutes
+      recentResultsToKeep: 3,
+    });
+    const recentMessages = convertMessagesForAPI(microcompactedMessages);
 
     try {
       // Get combined memory content
@@ -472,6 +573,7 @@ export class AIManager {
           filteredToolPlugins,
           {
             workdir: this.workdir,
+            originalWorkdir: this.originalWorkdir,
             memory: combinedMemory,
             language: this.getLanguage(),
             isSubagent: !!this.subagentType,
@@ -658,6 +760,7 @@ export class AIManager {
                   stage: "end",
                   name: toolName,
                   compactParams: "",
+                  timestamp: Date.now(),
                 });
                 return;
               }
@@ -710,6 +813,7 @@ export class AIManager {
                 abortSignal: toolAbortController.signal,
                 backgroundTaskManager: this.backgroundTaskManager,
                 workdir: this.workdir,
+                originalWorkdir: this.originalWorkdir,
                 messageId: this.messageManager.getMessages().slice(-1)[0]?.id,
                 sessionId: this.messageManager.getSessionId(),
                 toolCallId: toolId,
@@ -774,6 +878,7 @@ export class AIManager {
                 shortResult: toolResult.shortResult,
                 isManuallyBackgrounded: toolResult.isManuallyBackgrounded,
                 startLineNumber: toolResult.startLineNumber,
+                timestamp: Date.now(),
               });
 
               // Execute PostToolUse hooks after successful tool completion
@@ -799,6 +904,7 @@ export class AIManager {
                 name: toolName,
                 compactParams,
                 isManuallyBackgrounded: false,
+                timestamp: Date.now(),
               });
             }
           },
@@ -809,11 +915,7 @@ export class AIManager {
       }
 
       // Handle token statistics and message compression
-      await this.handleTokenUsageAndCompression(
-        result.usage,
-        abortController,
-        model,
-      );
+      await this.handleTokenUsageAndCompression(result.usage, abortController);
 
       // Finalize text/reasoning blocks for the final response (no tools)
       this.messageManager.finalizeStreamingBlocks();

package/src/managers/messageManager.ts

@@ -16,6 +16,7 @@ import {
   generateMessageId,
 } from "../utils/messageOperations.js";
 import type { Message, Usage } from "../types/index.js";
+import { getLastApiRounds } from "../utils/groupMessagesByApiRound.js";
 import { join, isAbsolute, relative } from "path";
 import {
   appendMessages,
@@ -89,6 +90,8 @@ export class MessageManager {
   private transcriptPath: string; // Cached transcript path
   private savedMessageCount: number; // Track how many messages have been saved to prevent duplication
   private filesInContext: Set<string> = new Set(); // Track files mentioned in the conversation
+  private recentFileReads: Map<string, { content: string; timestamp: number }> =
+    new Map(); // Track file read contents
   private sessionType: "main" | "subagent";
   private subagentType?: string;
   private _usages: Usage[] = [];
@@ -266,11 +269,13 @@ export class MessageManager {
     const newMessages = messages.slice(oldLength);
     for (const message of newMessages) {
       this.addPathsFromMessage(message);
+      this.extractFileReadsFromMessage(message);
     }
 
     // Also check if the last message was updated (common for tool blocks)
     if (messages.length > 0 && messages.length === oldLength) {
       this.addPathsFromMessage(messages[messages.length - 1]);
+      this.extractFileReadsFromMessage(messages[messages.length - 1]);
     }
 
     this.callbacks.onMessagesChange?.([...messages]);
@@ -495,8 +500,8 @@ export class MessageManager {
     compressedContent: string,
     usage?: Usage,
   ): void {
-    // Get last 3 messages to preserve
-    const lastThreeMessages = this.messages.slice(-3);
+    // Get last 2 API rounds to preserve (structurally safe boundary)
+    const lastThreeMessages = getLastApiRounds(this.messages, 2);
 
     // Create compressed message
     const compressMessage: Message = {
@@ -994,4 +999,61 @@ export class MessageManager {
 
     return paths;
   }
+
+  /**
+   * Extract file read contents from tool result blocks in a message.
+   */
+  private extractFileReadsFromMessage(message: Message): void {
+    for (const block of message.blocks) {
+      if (
+        block.type === "tool" &&
+        block.name === "read" &&
+        block.stage === "end" &&
+        block.result &&
+        block.parameters
+      ) {
+        let filePath: string | undefined;
+        try {
+          const params = JSON.parse(block.parameters) as Record<
+            string,
+            unknown
+          >;
+          filePath = params.file_path as string | undefined;
+        } catch {
+          // Ignore parse errors
+        }
+        if (filePath) {
+          this.recentFileReads.set(filePath, {
+            content: block.result,
+            timestamp: Date.now(),
+          });
+        }
+      }
+    }
+  }
+
+  /**
+   * Get recent file read contents, sorted by timestamp (newest first).
+   * @param maxFiles - Maximum number of files to return
+   * @param maxTokensPerFile - Maximum tokens per file (~4 chars/token)
+   * @returns Array of { path, content } sorted by recency
+   */
+  public getRecentFileReads(
+    maxFiles = 5,
+    maxTokensPerFile = 5000,
+  ): Array<{ path: string; content: string }> {
+    const sorted = Array.from(this.recentFileReads.entries())
+      .sort(([, a], [, b]) => b.timestamp - a.timestamp)
+      .slice(0, maxFiles);
+
+    const result: Array<{ path: string; content: string }> = [];
+    for (const [path, { content }] of sorted) {
+      const truncated =
+        content.length > maxTokensPerFile * 4
+          ? content.slice(0, maxTokensPerFile * 4)
+          : content;
+      result.push({ path, content: truncated });
+    }
+    return result;
+  }
 }

package/src/managers/messageQueue.ts

@@ -29,4 +29,13 @@ export class MessageQueue {
   getQueue(): QueuedMessage[] {
     return [...this.queue];
   }
+
+  removeAt(index: number): boolean {
+    if (index < 0 || index >= this.queue.length) {
+      return false;
+    }
+    this.queue.splice(index, 1);
+    this.onMessageEnqueued?.();
+    return true;
+  }
 }

package/src/managers/permissionManager.ts

@@ -315,6 +315,13 @@ export class PermissionManager {
     return this.planFilePath;
   }
 
+  /**
+   * Public wrapper for isInsideSafeZone to check if a path is in the safe zone
+   */
+  public isPathInSafeZone(targetPath: string): boolean {
+    return this.isInsideSafeZone(targetPath).isInside;
+  }
+
   /**
    * Check if a path is inside the Safe Zone (workdir + additionalDirectories)
    */

package/src/managers/subagentManager.ts

@@ -567,23 +567,25 @@ export class SubagentManager {
         instance.logStream?.end();
         const task = backgroundTaskManager.getTask(instance.backgroundTaskId);
         if (task) {
+          const wasAlreadyKilled = task.status === "killed";
           task.status = "completed";
           task.stdout = response || "Agent completed with no text response";
           task.endTime = Date.now();
           if (task.startTime) {
             task.runtime = task.endTime - task.startTime;
           }
-        }
-
-        // Enqueue completion notification
-        const notificationQueue = this.container.has("NotificationQueue")
-          ? this.container.get<NotificationQueue>("NotificationQueue")
-          : undefined;
-        if (notificationQueue) {
-          const summary = `Agent task "${instance.description}" completed`;
-          notificationQueue.enqueue(
-            `<task-notification>\n<task-id>${instance.backgroundTaskId}</task-id>\n<task-type>agent</task-type>\n<status>completed</status>\n<summary>${summary}</summary>\n</task-notification>`,
-          );
+          // Skip notification if task was already stopped (e.g. by main agent shutdown)
+          if (!wasAlreadyKilled) {
+            const notificationQueue = this.container.has("NotificationQueue")
+              ? this.container.get<NotificationQueue>("NotificationQueue")
+              : undefined;
+            if (notificationQueue) {
+              const summary = `Agent task "${instance.description}" completed`;
+              notificationQueue.enqueue(
+                `<task-notification>\n<task-id>${instance.backgroundTaskId}</task-id>\n<task-type>agent</task-type>\n<status>completed</status>\n<summary>${summary}</summary>\n</task-notification>`,
+              );
+            }
+          }
         }
       }
 
@@ -602,25 +604,27 @@ export class SubagentManager {
         instance.logStream?.end();
         const task = backgroundTaskManager.getTask(instance.backgroundTaskId);
         if (task) {
+          const wasAlreadyKilled = task.status === "killed";
           task.status = "failed";
           task.stderr = error instanceof Error ? error.message : String(error);
           task.endTime = Date.now();
           if (task.startTime) {
             task.runtime = task.endTime - task.startTime;
           }
-        }
-
-        // Enqueue error notification
-        const notificationQueue = this.container.has("NotificationQueue")
-          ? this.container.get<NotificationQueue>("NotificationQueue")
-          : undefined;
-        if (notificationQueue) {
-          const errorMsg =
-            error instanceof Error ? error.message : String(error);
-          const summary = `Agent task "${instance.description}" failed: ${errorMsg}`;
-          notificationQueue.enqueue(
-            `<task-notification>\n<task-id>${instance.backgroundTaskId}</task-id>\n<task-type>agent</task-type>\n<status>failed</status>\n<summary>${summary}</summary>\n</task-notification>`,
-          );
+          // Skip notification if task was already stopped (e.g. by main agent shutdown)
+          if (!wasAlreadyKilled) {
+            const notificationQueue = this.container.has("NotificationQueue")
+              ? this.container.get<NotificationQueue>("NotificationQueue")
+              : undefined;
+            if (notificationQueue) {
+              const errorMsg =
+                error instanceof Error ? error.message : String(error);
+              const summary = `Agent task "${instance.description}" failed: ${errorMsg}`;
+              notificationQueue.enqueue(
+                `<task-notification>\n<task-id>${instance.backgroundTaskId}</task-id>\n<task-type>agent</task-type>\n<status>failed</status>\n<summary>${summary}</summary>\n</task-notification>`,
+              );
+            }
+          }
         }
       }
       throw error;

package/src/prompts/index.ts

@@ -179,28 +179,52 @@ NOTE: At any point in time through this workflow you should feel free to ask the
 
 export const DEFAULT_SYSTEM_PROMPT = BASE_SYSTEM_PROMPT;
 
-export const COMPRESS_MESSAGES_SYSTEM_PROMPT = `You have been working on the task described above but have not yet completed it. Write a continuation summary that will allow you (or another instance of yourself) to resume work efficiently in a future context window where the conversation history will be replaced with this summary. Your summary should be structured, concise, and actionable. Include:
-1. Task Overview
-The user's core request and success criteria
-Any clarifications or constraints they specified
-2. Current State
-What has been completed so far
-Files created, modified, or analyzed (with paths if relevant)
-Key outputs or artifacts produced
-3. Important Discoveries
-Technical constraints or requirements uncovered
-Decisions made and their rationale
-Errors encountered and how they were resolved
-What approaches were tried that didn't work (and why)
-4. Next Steps
-Specific actions needed to complete the task
-Any blockers or open questions to resolve
-Priority order if multiple steps remain
-5. Context to Preserve
-User preferences or style requirements
-Domain-specific details that aren't obvious
-Any promises made to the user
-Be concise but complete—err on the side of including information that would prevent duplicate work or repeated mistakes. Write in a way that enables immediate resumption of the task.
+export const COMPRESS_MESSAGES_SYSTEM_PROMPT = `You are continuing work on a software engineering task. Write a detailed continuation summary that will allow you (or another instance of yourself) to resume work efficiently in a future context window where the conversation history will be replaced with this summary.
+
+First, write your analysis in <analysis> tags as a thinking scratchpad:
+- Chronologically review the conversation
+- Identify user intents and goals
+- Note files read/modified, approaches tried, decisions made
+- Check for accuracy and completeness — ensure nothing critical is missing
+
+Then produce a structured summary in <summary> tags with these sections:
+
+## Primary Request and Intent
+- The user's core request and success criteria
+- Clarifications, constraints, or scope changes
+
+## Key Technical Concepts
+- Frameworks, libraries, patterns, architectural decisions
+
+## Files and Code Sections
+- Files read, modified, created (with full paths)
+- Critical code snippets (function signatures, bug fixes, key logic)
+- Focus on recent messages — include full code for important sections
+
+## Errors and Fixes
+- Errors encountered, root causes, how they were resolved
+- Approaches tried that didn't work and why
+
+## Problem Solving
+- Approach evolution, trade-offs considered, decisions made
+
+## All User Messages
+- Complete list of all user messages (non-tool content)
+- Preserve exact wording where load-bearing
+
+## Pending Tasks
+- Outstanding work, TODOs, unresolved questions
+
+## Current Work
+- What was being worked on at the time of summarization
+- Exact state of in-progress changes
+
+## Optional Next Step
+- Immediate next action needed
+- Include verbatim quotes from recent conversation if relevant
+
+Be concise but complete — include information that prevents duplicate work or repeated mistakes.
+Respond with text only. Do NOT call any tools.
 Wrap your summary in <summary></summary> tags.`;
 
 export const WEB_CONTENT_SYSTEM_PROMPT = `You are a helpful assistant that extracts information from web content. The content is provided in Markdown format.`;
@@ -214,6 +238,7 @@ export function buildSystemPrompt(
   tools: ToolPlugin[],
   options: {
     workdir?: string;
+    originalWorkdir?: string;
     memory?: string;
     language?: string;
     isSubagent?: boolean;
@@ -251,8 +276,9 @@ export function buildSystemPrompt(
     prompt += `\n\n${buildPlanModePrompt(options.planMode.planFilePath, options.planMode.planExists, options.isSubagent)}`;
   }
 
-  if (options.workdir) {
-    const isGitRepo = isGitRepository(options.workdir);
+  const workdirForPrompt = options.originalWorkdir || options.workdir;
+  if (workdirForPrompt) {
+    const isGitRepo = isGitRepository(workdirForPrompt);
     const platform = os.platform();
     const osVersion = `${os.type()} ${os.release()}`;
     const today = new Date().toISOString().split("T")[0];
@@ -267,7 +293,7 @@ export function buildSystemPrompt(
 
 Here is useful information about the environment you are running in:
 <env>
-Working directory: ${options.workdir}
+Working directory: ${workdirForPrompt}
 Is directory a git repo: ${isGitRepo}
 Platform: ${platform}
 Shell: ${shellName}

package/src/services/aiService.ts

@@ -784,6 +784,19 @@ export async function compressMessages(
     await acquireSlot(abortSignal);
   }
 
+  // Strip images from messages before compact API call to reduce token usage
+  const cleanedMessages = messages.map((msg) => {
+    // Handle user/assistant messages with array content
+    if (Array.isArray(msg.content)) {
+      const textParts = msg.content.filter(
+        (part) => part.type === "text",
+      ) as import("openai/resources.js").ChatCompletionContentPartText[];
+      const text = textParts.map((p) => p.text).join("\n");
+      return { ...msg, content: text || "(empty message)" };
+    }
+    return msg;
+  });
+
   // Create OpenAI client with injected configuration
   const openai = new OpenAIClient({
     apiKey: gatewayConfig.apiKey,
@@ -821,7 +834,7 @@ export async function compressMessages(
             role: "system",
             content: COMPRESS_MESSAGES_SYSTEM_PROMPT,
           },
-          ...messages,
+          ...cleanedMessages,
           {
             role: "user",
             content: `Please create a detailed summary of the conversation so far.`,

package/src/tools/agentTool.ts

@@ -71,7 +71,11 @@ When using the Agent tool, you must specify a subagent_type parameter to select
 
 - When doing file search, prefer to use the ${AGENT_TOOL_NAME} tool in order to reduce context usage.
 - You should proactively use the ${AGENT_TOOL_NAME} tool with specialized agents when the task at hand matches the agent's description.
-- VERY IMPORTANT: When exploring the codebase to gather context or to answer a question that is not a needle query for a specific file/class/function, it is CRITICAL that you use the ${AGENT_TOOL_NAME} tool with subagent_type=${EXPLORE_SUBAGENT_TYPE} instead of running search commands directly.`;
+- VERY IMPORTANT: When exploring the codebase to gather context or to answer a question that is not a needle query for a specific file/class/function, it is CRITICAL that you use the ${AGENT_TOOL_NAME} tool with subagent_type=${EXPLORE_SUBAGENT_TYPE} instead of running search commands directly.
+- You can optionally run agents in the background using the run_in_background parameter. When an agent runs in the background, you will be automatically notified when it completes — do NOT sleep, poll, or proactively check on its progress. Continue with other work or respond to the user instead.
+- **Foreground vs background**: Use foreground (default) when you need the agent's results before you can proceed — e.g., research agents whose findings inform your next steps. Use background when you have genuinely independent work to do in parallel.
+- **Don't peek.** The tool result includes an output file path — do not Read or tail it unless the user explicitly asks for a progress check. You get a completion notification; trust it. Reading the transcript mid-flight pulls the agent's tool noise into your context, which defeats the point of backgrounding.
+- **Don't race.** After launching, you know nothing about what the agent found. Never fabricate or predict agent results in any format — not as prose, summary, or structured output. The notification arrives as a user-role message in a later turn; it is never something you write yourself. If the user asks a follow-up before the notification lands, tell them the agent is still running — give status, not a guess.`;
   },
 
   execute: async (
@@ -212,9 +216,17 @@ When using the Agent tool, you must specify a subagent_type parameter to select
             if (run_in_background) {
               const task = context.backgroundTaskManager?.getTask(result);
               const outputPath = task?.outputPath;
+              const backgroundMsg = [
+                `Agent started in background with ID: ${result}.`,
+                `The agent is working in the background. You will be notified automatically when it completes.`,
+                `Do not duplicate this agent's work — avoid working with the same files or topics it is using.`,
+                outputPath
+                  ? `output_file: ${outputPath}`
+                  : `Briefly tell the user what you launched and end your response.`,
+              ].join("\n");
               resolve({
                 success: true,
-                content: `Agent started in background with ID: ${result}.${outputPath ? ` Real-time output: ${outputPath}` : ""}`,
+                content: backgroundMsg,
                 shortResult: `Agent started in background: ${result}`,
               });
               return;