wave-agent-sdk 0.6.5 → 0.7.0

package/src/managers/toolManager.ts

@@ -2,9 +2,7 @@ import type { ToolContext, ToolPlugin, ToolResult } from "../tools/types.js";
 import { bashTool } from "../tools/bashTool.js";
 import { taskOutputTool } from "../tools/taskOutputTool.js";
 import { taskStopTool } from "../tools/taskStopTool.js";
-import { deleteFileTool } from "../tools/deleteFileTool.js";
 import { editTool } from "../tools/editTool.js";
-import { multiEditTool } from "../tools/multiEditTool.js";
 import { writeTool } from "../tools/writeTool.js";
 import { exitPlanModeTool } from "../tools/exitPlanMode.js";
 import { askUserQuestionTool } from "../tools/askUserQuestion.js";
@@ -14,8 +12,8 @@ import { grepTool } from "../tools/grepTool.js";
 import { lsTool } from "../tools/lsTool.js";
 import { readTool } from "../tools/readTool.js";
 import { lspTool } from "../tools/lspTool.js";
-import { createTaskTool } from "../tools/taskTool.js";
-import { createSkillTool } from "../tools/skillTool.js";
+import { taskTool } from "../tools/taskTool.js";
+import { skillTool } from "../tools/skillTool.js";
 import {
   taskCreateTool,
   taskGetTool,
@@ -26,7 +24,6 @@ import { McpManager } from "./mcpManager.js";
 import { PermissionManager } from "./permissionManager.js";
 import { ChatCompletionFunctionTool } from "openai/resources.js";
 import type {
-  Logger,
   PermissionMode,
   PermissionCallback,
   ILspManager,
@@ -36,24 +33,14 @@ import type { SkillManager } from "./skillManager.js";
 
 import { ReversionManager } from "./reversionManager.js";
 
+import { Container } from "../utils/container.js";
+
+import { logger } from "../utils/globalLogger.js";
+
 export interface ToolManagerOptions {
-  mcpManager: McpManager;
-  lspManager?: ILspManager;
-  logger?: Logger;
-  /** Permission manager for handling tool permission checks */
-  permissionManager?: PermissionManager;
-  /** Foreground task manager for backgrounding tasks */
-  foregroundTaskManager?: import("../types/processes.js").IForegroundTaskManager;
-  /** Task manager for task management */
-  taskManager?: import("../services/taskManager.js").TaskManager;
-  /** Reversion manager for file snapshots */
-  reversionManager?: ReversionManager;
-  /** Background task manager for background execution */
-  backgroundTaskManager?: import("./backgroundTaskManager.js").BackgroundTaskManager;
-  /** Permission mode for tool execution (defaults to "default") */
-  permissionMode?: PermissionMode;
-  /** Custom permission callback for tool usage */
-  canUseToolCallback?: PermissionCallback;
+  container: Container;
+  /** Optional list of tool names to enable */
+  tools?: string[];
 }
 
 /**
@@ -63,44 +50,31 @@ export interface ToolManagerOptions {
  * Supports both built-in tools and MCP (Model Context Protocol) tools.
  */
 class ToolManager {
-  private tools = new Map<string, ToolPlugin>();
-  private mcpManager: McpManager;
-  private lspManager?: ILspManager;
-  private logger?: Logger;
-  private permissionManager?: PermissionManager;
-  private foregroundTaskManager?: import("../types/processes.js").IForegroundTaskManager;
-  private reversionManager?: ReversionManager;
-  private taskManager?: import("../services/taskManager.js").TaskManager;
-  private backgroundTaskManager?: import("./backgroundTaskManager.js").BackgroundTaskManager;
-  private permissionMode?: PermissionMode;
-  private canUseToolCallback?: PermissionCallback;
+  private toolsRegistry = new Map<string, ToolPlugin>();
+  private tools?: string[];
+  private container: Container;
 
   constructor(options: ToolManagerOptions) {
-    this.mcpManager = options.mcpManager;
-    this.lspManager = options.lspManager;
-    this.logger = options.logger;
-    this.permissionManager = options.permissionManager;
-    this.taskManager = options.taskManager;
-    this.foregroundTaskManager = options.foregroundTaskManager;
-    this.reversionManager = options.reversionManager;
-    this.backgroundTaskManager = options.backgroundTaskManager;
-    // Store CLI permission mode, let PermissionManager resolve effective mode
-    this.permissionMode = options.permissionMode;
-    this.canUseToolCallback = options.canUseToolCallback;
+    this.container = options.container;
+    this.tools = options.tools;
+  }
+
+  private get mcpManager(): McpManager {
+    return this.container.get<McpManager>("McpManager")!;
   }
 
   /**
    * Register a new tool
    */
   public register(tool: ToolPlugin): void {
-    this.tools.set(tool.name, tool);
+    this.toolsRegistry.set(tool.name, tool);
   }
 
   /**
    * Initialize built-in tools. Can be called with dependencies for tools that require them.
    *
    * This method can be called multiple times safely. When called without dependencies,
-   * it registers basic tools (Bash, Read, Write, TodoWrite, etc.). When called with
+   * it registers basic tools (Bash, Read, Write, TaskCreate, etc.). When called with
    * dependencies, it also registers tools that require managers (Task, Skill).
    *
    * @param deps Optional dependencies for advanced tools
@@ -119,17 +93,12 @@ class ToolManager {
    * });
    * ```
    */
-  public initializeBuiltInTools(deps?: {
-    subagentManager?: SubagentManager;
-    skillManager?: SkillManager;
-  }): void {
+  public initializeBuiltInTools(): void {
     const builtInTools = [
       bashTool,
       taskOutputTool,
       taskStopTool,
-      deleteFileTool,
       editTool,
-      multiEditTool,
       writeTool,
       exitPlanModeTool,
       askUserQuestionTool,
@@ -138,6 +107,8 @@ class ToolManager {
       lsTool,
       readTool,
       lspTool,
+      taskTool,
+      skillTool,
       taskCreateTool,
       taskGetTool,
       taskUpdateTool,
@@ -145,19 +116,22 @@ class ToolManager {
     ];
 
     for (const tool of builtInTools) {
-      this.tools.set(tool.name, tool);
-    }
-
-    // Register tools that require dependencies
-    if (deps?.subagentManager) {
-      const taskTool = createTaskTool(deps.subagentManager);
-      this.tools.set(taskTool.name, taskTool);
+      if (this.shouldEnableTool(tool.name)) {
+        this.toolsRegistry.set(tool.name, tool);
+      }
     }
+  }
 
-    if (deps?.skillManager) {
-      const skillTool = createSkillTool(deps.skillManager);
-      this.tools.set(skillTool.name, skillTool);
+  /**
+   * Check if a tool should be enabled based on tools configuration
+   */
+  private shouldEnableTool(name: string): boolean {
+    if (!this.tools) {
+      return true;
     }
+    return this.tools.some(
+      (toolName) => toolName.toLowerCase() === name.toLowerCase(),
+    );
   }
 
   /**
@@ -178,32 +152,53 @@ class ToolManager {
     args: Record<string, unknown>,
     context: ToolContext,
   ): Promise<ToolResult> {
+    const permissionManager =
+      this.container.get<PermissionManager>("PermissionManager");
+    const permissionMode = this.container.has("PermissionMode")
+      ? this.container.get<PermissionMode>("PermissionMode")
+      : undefined;
+
     // Resolve effective permission mode (CLI override > configuration > default)
-    const effectivePermissionMode = this.permissionManager
-      ? this.permissionManager.getCurrentEffectiveMode(this.permissionMode)
-      : this.permissionMode || "default";
+    const effectivePermissionMode = permissionManager
+      ? permissionManager.getCurrentEffectiveMode(permissionMode)
+      : permissionMode || "default";
 
     // Enhance context with permission-related fields
     const enhancedContext: ToolContext = {
       ...context,
       permissionMode: effectivePermissionMode,
-      canUseToolCallback: this.canUseToolCallback,
-      permissionManager: this.permissionManager,
-      taskManager: this.taskManager!,
-      reversionManager: this.reversionManager,
-      backgroundTaskManager: this.backgroundTaskManager,
-      foregroundTaskManager: this.foregroundTaskManager,
+      canUseToolCallback: this.container.has("CanUseToolCallback")
+        ? this.container.get<PermissionCallback>("CanUseToolCallback")
+        : undefined,
+      permissionManager,
+      taskManager:
+        this.container.get<import("../services/taskManager.js").TaskManager>(
+          "TaskManager",
+        )!,
+      reversionManager:
+        this.container.get<ReversionManager>("ReversionManager")!,
+      backgroundTaskManager: this.container.get<
+        import("./backgroundTaskManager.js").BackgroundTaskManager
+      >("BackgroundTaskManager")!,
+      foregroundTaskManager: this.container.get<
+        import("../types/processes.js").IForegroundTaskManager
+      >("ForegroundTaskManager")!,
       mcpManager: this.mcpManager,
-      lspManager: this.lspManager,
+      lspManager: this.container.get<ILspManager>("LspManager")!,
+      subagentManager: this.container.has("SubagentManager")
+        ? this.container.get<SubagentManager>("SubagentManager")
+        : undefined,
+      skillManager: this.container.has("SkillManager")
+        ? this.container.get<SkillManager>("SkillManager")
+        : undefined,
       sessionId: context.sessionId,
     };
 
-    this.logger?.debug("Executing tool with enhanced context", {
+    logger?.debug("Executing tool with enhanced context", {
       toolName: name,
-      cliPermissionMode: this.permissionMode,
+      permissionMode,
       effectivePermissionMode,
-      hasPermissionManager: !!this.permissionManager,
-      hasPermissionCallback: !!this.canUseToolCallback,
+      hasPermissionManager: !!permissionManager,
     });
 
     // Check if it's an MCP tool first
@@ -216,12 +211,12 @@ class ToolManager {
     }
 
     // Check built-in tools
-    const plugin = this.tools.get(name);
+    const plugin = this.toolsRegistry.get(name);
     if (plugin) {
       try {
         return await plugin.execute(args, enhancedContext);
       } catch (error) {
-        this.logger?.error("Tool execution failed", {
+        logger?.error("Tool execution failed", {
           toolName: name,
           error: error instanceof Error ? error.message : String(error),
         });
@@ -233,7 +228,7 @@ class ToolManager {
       }
     }
 
-    this.logger?.warn("Tool not found", { toolName: name });
+    logger?.warn("Tool not found", { toolName: name });
     return {
       success: false,
       content: "",
@@ -242,14 +237,14 @@ class ToolManager {
   }
 
   list(): ToolPlugin[] {
-    const builtInTools = Array.from(this.tools.values());
+    const builtInTools = Array.from(this.toolsRegistry.values());
     const mcpTools = this.mcpManager.getMcpToolPlugins();
     return [...builtInTools, ...mcpTools];
   }
 
   getToolsConfig(): ChatCompletionFunctionTool[] {
     const effectivePermissionMode = this.getPermissionMode();
-    const builtInToolsConfig = Array.from(this.tools.values())
+    const builtInToolsConfig = Array.from(this.toolsRegistry.values())
       .filter((tool) => {
         if (effectivePermissionMode === "bypassPermissions") {
           if (tool.name === "ExitPlanMode" || tool.name === "AskUserQuestion") {
@@ -270,19 +265,23 @@ class ToolManager {
    * Get the list of registered tool plugins
    */
   public getTools(): ToolPlugin[] {
-    return Array.from(this.tools.values());
+    return Array.from(this.toolsRegistry.values());
   }
 
   /**
    * Get the current permission mode
    */
   public getPermissionMode(): PermissionMode {
-    if (this.permissionManager) {
-      return this.permissionManager.getCurrentEffectiveMode(
-        this.permissionMode,
-      );
+    const permissionManager =
+      this.container.get<PermissionManager>("PermissionManager");
+    const permissionMode = this.container.has("PermissionMode")
+      ? this.container.get<PermissionMode>("PermissionMode")
+      : undefined;
+
+    if (permissionManager) {
+      return permissionManager.getCurrentEffectiveMode(permissionMode);
     }
-    return this.permissionMode || "default";
+    return permissionMode || "default";
   }
 
   /**
@@ -290,14 +289,14 @@ class ToolManager {
    * @param mode - The new permission mode
    */
   public setPermissionMode(mode: PermissionMode): void {
-    this.permissionMode = mode;
+    this.container.register("PermissionMode", mode);
   }
 
   /**
    * Get the permission manager
    */
   public getPermissionManager(): PermissionManager | undefined {
-    return this.permissionManager;
+    return this.container.get<PermissionManager>("PermissionManager");
   }
 
   /**
@@ -306,7 +305,9 @@ class ToolManager {
   public getTaskManager():
     | import("../services/taskManager.js").TaskManager
     | undefined {
-    return this.taskManager;
+    return this.container.get<import("../services/taskManager.js").TaskManager>(
+      "TaskManager",
+    );
   }
 }
 

package/src/prompts/index.ts

@@ -161,7 +161,6 @@ export const EXPLORE_SUBAGENT_SYSTEM_PROMPT = `You are a file search specialist.
 	This is a READ-ONLY exploration task. You are STRICTLY PROHIBITED from:
 	- Creating new files (no Write, touch, or file creation of any kind)
 	- Modifying existing files (no Edit operations)
-	- Deleting files (no rm or deletion)
 	- Moving or copying files (no mv or cp)
 	- Creating temporary files anywhere, including /tmp
 	- Using redirect operators (>, >>, |) or heredocs to write to files
@@ -199,7 +198,6 @@ export const PLAN_SUBAGENT_SYSTEM_PROMPT = `You are a software architect and pla
 This is a READ-ONLY planning task. You are STRICTLY PROHIBITED from:
 - Creating new files (no Write, touch, or file creation of any kind)
 - Modifying existing files (no Edit operations)
-- Deleting files (no rm or deletion)
 - Moving or copying files (no mv or cp)
 - Creating temporary files anywhere, including /tmp
 - Using redirect operators (>, >>, |) or heredocs to write to files
@@ -290,6 +288,9 @@ 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.
 Wrap your summary in <summary></summary> tags.`;
 
+import type { SubagentConfiguration } from "../utils/subagentParser.js";
+import type { SkillMetadata } from "../types/skills.js";
+
 export function buildSystemPrompt(
   basePrompt: string | undefined,
   tools: ToolPlugin[],
@@ -302,15 +303,22 @@ export function buildSystemPrompt(
       planFilePath: string;
       planExists: boolean;
     };
+    availableSubagents?: SubagentConfiguration[];
+    availableSkills?: SkillMetadata[];
   } = {},
 ): string {
   let prompt = basePrompt || DEFAULT_SYSTEM_PROMPT;
-
-  prompt += `\n\n${TOOL_POLICY}`;
+  if (tools.length > 0) {
+    prompt += `\n\n${TOOL_POLICY}`;
+  }
 
   for (const tool of tools) {
     if (tool.prompt) {
-      prompt += tool.prompt();
+      prompt += tool.prompt({
+        availableSubagents: options.availableSubagents,
+        availableSkills: options.availableSkills,
+        workdir: options.workdir,
+      });
     }
   }
 

package/src/services/MarketplaceService.ts

@@ -80,6 +80,16 @@ export class MarketplaceService {
     }
     try {
       const content = await fs.readFile(this.knownMarketplacesPath, "utf-8");
+      if (!content.trim()) {
+        return {
+          marketplaces: [
+            {
+              ...MarketplaceService.BUILTIN_MARKETPLACE,
+              isBuiltin: true,
+            },
+          ],
+        };
+      }
       return JSON.parse(content);
     } catch (error) {
       console.error("Failed to load known marketplaces:", error);
@@ -96,6 +106,9 @@ export class MarketplaceService {
     }
     try {
       const content = await fs.readFile(this.installedPluginsPath, "utf-8");
+      if (!content.trim()) {
+        return { plugins: [] };
+      }
       return JSON.parse(content);
     } catch (error) {
       console.error("Failed to load installed plugins:", error);

package/src/services/aiService.ts

@@ -8,6 +8,7 @@ import {
 } from "openai/resources.js";
 import { OpenAIClient } from "../utils/openaiClient.js";
 import { logger } from "../utils/globalLogger.js";
+import { addOnceAbortListener } from "../utils/abortUtils.js";
 import type { GatewayConfig, ModelConfig } from "../types/index.js";
 import {
   transformMessagesForClaudeCache,
@@ -69,13 +70,50 @@ interface ErrorData {
 type OpenAIModelConfig = Omit<
   ChatCompletionCreateParamsNonStreaming,
   "messages"
-> & {
-  vertexai?: {
-    thinking_config: {
-      thinking_level: string;
-    };
-  };
-};
+>;
+
+// Global rate limiter state for 1 QPS
+let nextAllowedTime = 0;
+const MIN_INTERVAL = 1000; // 1 second for 1 QPS
+
+/**
+ * Resets the rate limiter state. Primarily used for testing.
+ */
+export function resetRateLimiter(): void {
+  nextAllowedTime = 0;
+}
+
+/**
+ * Acquires a slot for an AI request, ensuring 1 QPS limit.
+ * @param abortSignal Optional abort signal to cancel waiting
+ */
+async function acquireSlot(abortSignal?: AbortSignal): Promise<void> {
+  if (abortSignal?.aborted) {
+    throw new Error("Request was aborted");
+  }
+
+  const now = Date.now();
+  const waitTime = Math.max(0, nextAllowedTime - now);
+
+  // Reserve the slot synchronously to ensure global ordering
+  nextAllowedTime = Math.max(now, nextAllowedTime) + MIN_INTERVAL;
+
+  if (waitTime > 0) {
+    await new Promise<void>((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        cleanup();
+        resolve();
+      }, waitTime);
+
+      const cleanup = abortSignal
+        ? addOnceAbortListener(abortSignal, () => {
+            clearTimeout(timeout);
+            reject(new Error("Request was aborted"));
+          })
+        : () => {};
+    });
+  }
+}
 
 /**
  * Get specific configuration parameters based on model name
@@ -99,14 +137,6 @@ function getModelConfig(
     config.temperature = undefined;
   }
 
-  if (modelName.startsWith("gemini-3-flash")) {
-    config.vertexai = {
-      thinking_config: {
-        thinking_level: "minimal",
-      },
-    };
-  }
-
   return config;
 }
 
@@ -170,6 +200,14 @@ export async function callAgent(
     onReasoningUpdate,
   } = options;
 
+  // Apply global 1 QPS rate limit
+  if (
+    process.env.NODE_ENV !== "test" ||
+    modelConfig.agentModel === "rate-limit-test"
+  ) {
+    await acquireSlot(abortSignal);
+  }
+
   // Declare variables outside try block for error handling access
   let openaiMessages: ChatCompletionMessageParam[] | undefined;
   let createParams:
@@ -719,6 +757,14 @@ export async function compressMessages(
 ): Promise<CompressMessagesResult> {
   const { gatewayConfig, modelConfig, messages, abortSignal } = options;
 
+  // Apply global 1 QPS rate limit
+  if (
+    process.env.NODE_ENV !== "test" ||
+    modelConfig.agentModel === "rate-limit-test"
+  ) {
+    await acquireSlot(abortSignal);
+  }
+
   // Create OpenAI client with injected configuration
   const openai = new OpenAIClient({
     apiKey: gatewayConfig.apiKey,

package/src/services/configurationService.ts

@@ -374,7 +374,7 @@ export class ConfigurationService {
     if (apiKey !== undefined) {
       resolvedApiKey = apiKey;
     } else {
-      resolvedApiKey = this.env.WAVE_API_KEY || process.env.WAVE_API_KEY;
+      resolvedApiKey = this.env.WAVE_API_KEY;
     }
 
     // Resolve base URL: constructor > env (settings.json) > process.env
@@ -383,8 +383,25 @@ export class ConfigurationService {
     if (baseURL !== undefined) {
       resolvedBaseURL = baseURL;
     } else {
-      resolvedBaseURL =
-        this.env.WAVE_BASE_URL || process.env.WAVE_BASE_URL || "";
+      resolvedBaseURL = this.env.WAVE_BASE_URL || "";
+    }
+
+    // If we have a parent configuration, use it as a fallback for API key and base URL
+    if (this.currentConfiguration?.env) {
+      if (resolvedApiKey === undefined) {
+        resolvedApiKey = this.currentConfiguration.env.WAVE_API_KEY;
+      }
+      if (!resolvedBaseURL) {
+        resolvedBaseURL = this.currentConfiguration.env.WAVE_BASE_URL || "";
+      }
+    }
+
+    // Fallback to process.env if still not resolved (for dynamic updates in tests)
+    if (resolvedApiKey === undefined) {
+      resolvedApiKey = process.env.WAVE_API_KEY;
+    }
+    if (!resolvedBaseURL) {
+      resolvedBaseURL = process.env.WAVE_BASE_URL || "";
     }
 
     if (!resolvedBaseURL && baseURL === undefined) {
@@ -443,18 +460,22 @@ export class ConfigurationService {
     const DEFAULT_FAST_MODEL = "gemini-2.5-flash";
 
     // Resolve agent model: constructor > env (settings.json) > process.env > default
-    const resolvedAgentModel =
-      agentModel ||
-      this.env.WAVE_MODEL ||
-      process.env.WAVE_MODEL ||
-      DEFAULT_AGENT_MODEL;
+    let resolvedAgentModel = agentModel || this.env.WAVE_MODEL;
+
+    if (!resolvedAgentModel && this.currentConfiguration?.env?.WAVE_MODEL) {
+      resolvedAgentModel = this.currentConfiguration.env.WAVE_MODEL;
+    }
+    resolvedAgentModel =
+      resolvedAgentModel || process.env.WAVE_MODEL || DEFAULT_AGENT_MODEL;
 
     // Resolve fast model: constructor > env (settings.json) > process.env > default
-    const resolvedFastModel =
-      fastModel ||
-      this.env.WAVE_FAST_MODEL ||
-      process.env.WAVE_FAST_MODEL ||
-      DEFAULT_FAST_MODEL;
+    let resolvedFastModel = fastModel || this.env.WAVE_FAST_MODEL;
+
+    if (!resolvedFastModel && this.currentConfiguration?.env?.WAVE_FAST_MODEL) {
+      resolvedFastModel = this.currentConfiguration.env.WAVE_FAST_MODEL;
+    }
+    resolvedFastModel =
+      resolvedFastModel || process.env.WAVE_FAST_MODEL || DEFAULT_FAST_MODEL;
 
     // Resolve max output tokens
     const resolvedMaxTokens = this.resolveMaxOutputTokens(maxTokens);

package/src/services/taskManager.ts

@@ -4,12 +4,16 @@ import { homedir } from "os";
 import { EventEmitter } from "events";
 import { Task } from "../types/tasks.js";
 import { logger } from "../utils/globalLogger.js";
+import { Container } from "../utils/container.js";
 
 export class TaskManager extends EventEmitter {
   private readonly baseDir: string;
   private taskListId: string;
 
-  constructor(taskListId: string) {
+  constructor(
+    private container: Container,
+    taskListId: string,
+  ) {
     super();
     this.taskListId = taskListId;
     this.baseDir = join(homedir(), ".wave", "tasks");

package/src/tools/bashTool.ts

@@ -306,7 +306,7 @@ Usage notes:
       }
 
       child.stdout?.on("data", (data) => {
-        if (!isAborted && !isBackgrounded) {
+        if (!isAborted && !isBackgrounded && !runInBackground) {
           const chunk = stripAnsiColors(data.toString());
           outputBuffer += chunk;
           context.onShortResultUpdate?.(chunk.trim().split("\n").pop() || "");
@@ -314,7 +314,7 @@ Usage notes:
       });
 
       child.stderr?.on("data", (data) => {
-        if (!isAborted && !isBackgrounded) {
+        if (!isAborted && !isBackgrounded && !runInBackground) {
           const chunk = stripAnsiColors(data.toString());
           errorBuffer += chunk;
           context.onShortResultUpdate?.(chunk.trim().split("\n").pop() || "");

package/src/tools/editTool.ts

@@ -23,7 +23,15 @@ export const editTool: ToolPlugin = {
   name: EDIT_TOOL_NAME,
   formatCompactParams,
   prompt: () =>
-    `Performs exact string replacements in files. \n\nUsage:\n- You must use your \`${READ_TOOL_NAME}\` tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file. \n- When editing text from read_file tool output, ensure you preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is: spaces + line number + tab. Everything after that tab is the actual file content to match. Never include any part of the line number prefix in the old_string or new_string.\n- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.\n- Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.\n- The edit will FAIL if \`old_string\` is not unique in the file. Either provide a larger string with more surrounding context to make it unique or use \`replace_all\` to change every instance of \`old_string\`. \n- Use \`replace_all\` for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.`,
+    `Performs exact string replacements in files.
+
+Usage:
+- You must use your \`${READ_TOOL_NAME}\` tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file. 
+- When editing text from ${READ_TOOL_NAME} tool output, ensure you preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is: spaces + line number + tab. Everything after that tab is the actual file content to match. Never include any part of the line number prefix in the old_string or new_string.
+- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
+- Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.
+- The edit will FAIL if \`old_string\` is not unique in the file. Either provide a larger string with more surrounding context to make it unique or use \`replace_all\` to change every instance of \`old_string\`. 
+- Use \`replace_all\` for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.`,
   config: {
     type: "function",
     function: {