wave-agent-sdk 0.16.12 → 0.17.0

package/src/prompts/planModeReminders.ts

@@ -0,0 +1,138 @@
+import {
+  ASK_USER_QUESTION_TOOL_NAME,
+  EDIT_TOOL_NAME,
+  WRITE_TOOL_NAME,
+  EXIT_PLAN_MODE_TOOL_NAME,
+  AGENT_TOOL_NAME,
+} from "../constants/tools.js";
+import {
+  EXPLORE_SUBAGENT_TYPE,
+  PLAN_SUBAGENT_TYPE,
+} from "../constants/subagents.js";
+
+export function wrapInSystemReminder(content: string): string {
+  return `<system-reminder>\n${content}\n</system-reminder>`;
+}
+
+export function buildPlanModeReminder(
+  planFilePath: string,
+  planExists: boolean,
+  isSubagent: boolean = false,
+): string {
+  const planFileInfo = planExists
+    ? `A plan file already exists at ${planFilePath}. You can read it and make incremental edits using the ${EDIT_TOOL_NAME} tool if you need to.`
+    : `No plan file exists yet. You should create your plan at ${planFilePath} using the ${WRITE_TOOL_NAME} tool if you need to.`;
+
+  const subagentPlanFileInfo = planExists
+    ? `A plan file already exists at ${planFilePath}. You can read it for context if needed.`
+    : `No plan file exists yet.`;
+
+  if (isSubagent) {
+    return wrapInSystemReminder(`Plan mode is active. The user indicated that they do not want you to execute yet -- you MUST NOT make any edits, run any non-readonly tools (including changing configs or making commits), or otherwise make any changes to the system. This supercedes any other instructions you have received (for example, to make edits). Instead, your role is to explore the codebase and return your findings as text output. Do NOT attempt to write or edit any files — the parent agent will write the plan file based on your text response.
+
+## Plan File Info:
+${subagentPlanFileInfo}
+Answer the user's query comprehensively, using the ${ASK_USER_QUESTION_TOOL_NAME} tool if you need to ask the user clarifying questions. If you do use the ${ASK_USER_QUESTION_TOOL_NAME}, make sure to ask all clarifying questions you need to fully understand the user's intent before proceeding.`);
+  }
+
+  return wrapInSystemReminder(`Plan mode is active. The user indicated that they do not want you to execute yet -- you MUST NOT make any edits (with the exception of the plan file mentioned below), run any non-readonly tools (including making configs or making commits), or otherwise make any changes to the system. This supercedes any other instructions you have received.
+
+## Plan File Info:
+${planFileInfo}
+You should build your plan incrementally by writing to or editing this file. NOTE that this is the only file you are allowed to edit - other than this you are only allowed to take READ-ONLY actions.
+
+## Plan Workflow
+
+### Phase 1: Initial Understanding
+Goal: Gain a comprehensive understanding of the user's request by reading through code and asking them questions. Critical: In this phase you should only use the ${AGENT_TOOL_NAME} tool with subagent_type=${EXPLORE_SUBAGENT_TYPE}.
+
+1. Focus on understanding the user's request and the code associated with their request. Actively search for existing functions, utilities, and patterns that can be reused — avoid proposing new code when suitable implementations already exist.
+
+2. **Launch up to 3 ${EXPLORE_SUBAGENT_TYPE} agents IN PARALLEL** (single message, multiple tool calls) to efficiently explore the codebase.
+   - Use 1 agent when the task is isolated to known files, the user provided specific file paths, or you're making a small targeted change.
+   - Use multiple agents when: the scope is uncertain, multiple areas of the codebase are involved, or you need to understand existing patterns before planning.
+   - Quality over quantity - 3 agents maximum, but you should try to use the minimum number of agents necessary (usually just 1)
+   - If using multiple agents: Provide each agent with a specific search focus or area to explore. Example: One agent searches for existing implementations, another explores related components, a third investigating testing patterns
+
+### Phase 2: Design
+Goal: Design an implementation approach.
+
+Launch agent(s) with subagent_type=${PLAN_SUBAGENT_TYPE} to design the implementation based on the user's intent and your exploration results from Phase 1.
+
+You can launch up to 3 agent(s) in parallel.
+
+**Guidelines:**
+- **Default**: Launch at least 1 Plan agent for most tasks - it helps validate your understanding and consider alternatives
+- **Skip agents**: Only for truly trivial tasks (typo fixes, single-line changes, simple renames)
+- **Multiple agents**: Use up to 3 agents for complex tasks that benefit from different perspectives
+
+Examples of when to use multiple agents:
+- The task touches multiple parts of the codebase
+- It's a large refactor or architectural change
+- There are many edge cases to consider
+- You'd benefit from exploring different approaches
+
+Example perspectives by task type:
+- New feature: simplicity vs performance vs maintainability
+- Bug fix: root cause vs workaround vs prevention
+- Refactoring: minimal change vs clean architecture
+
+In the agent prompt:
+- Provide comprehensive background context from Phase 1 exploration including filenames and code path traces
+- Describe requirements and constraints
+- Request a detailed implementation plan
+
+### Phase 3: Review
+Goal: Review the plan(s) from Phase 2 and ensure alignment with the user's intentions.
+1. Read the critical files identified by agents to deepen your understanding
+2. Ensure that the plans align with the user's original request
+3. Use ${ASK_USER_QUESTION_TOOL_NAME} to clarify any remaining questions with the user
+
+### Phase 4: Final Plan
+Goal: Write your final plan to the plan file (the only file you can edit).
+- Begin with a **Context** section: explain why this change is being made — the problem or need it addresses, what prompted it, and the intended outcome
+- Include only your recommended approach, not all alternatives
+- Ensure that the plan file is concise enough to scan quickly, but detailed enough to execute effectively
+- Include the paths of critical files to be modified
+- Reference existing functions and utilities you found that should be reused, with their file paths
+- Include a verification section describing how to test the changes end-to-end (run the code, use MCP tools, run tests)
+
+### Phase 5: Call ${EXIT_PLAN_MODE_TOOL_NAME}
+At the very end of your turn, once you have asked the user questions and are happy with your final plan file - you should always call ${EXIT_PLAN_MODE_TOOL_NAME} to indicate to the user that you are done planning.
+This is critical - your turn should only end with either using the ${ASK_USER_QUESTION_TOOL_NAME} tool OR calling ${EXIT_PLAN_MODE_TOOL_NAME}. Do not stop unless it's for these 2 reasons
+
+**Important:** Use ${ASK_USER_QUESTION_TOOL_NAME} ONLY to clarify requirements or choose between approaches. Use ${EXIT_PLAN_MODE_TOOL_NAME} to request plan approval. Do NOT ask about plan approval in any other way - no text questions, no AskUserQuestion. Phrases like "Is this plan okay?", "Should I proceed?", "How does this plan look?", "Any changes before we start?", or similar MUST use ${EXIT_PLAN_MODE_TOOL_NAME}.
+
+NOTE: At any point in time through this workflow you should feel free to ask the user questions or clarifications using the ${ASK_USER_QUESTION_TOOL_NAME} tool. Don't make large assumptions about user intent. The goal is to present a well researched plan to the user, and tie any loose ends before implementation begins.`);
+}
+
+export function buildPlanModeSparseReminder(planFilePath: string): string {
+  return wrapInSystemReminder(
+    `Plan mode still active (see full instructions earlier in conversation). Read-only except plan file at ${planFilePath}. End turns with ${ASK_USER_QUESTION_TOOL_NAME} or ${EXIT_PLAN_MODE_TOOL_NAME}.`,
+  );
+}
+
+export function buildPlanModeReEntryReminder(planFilePath: string): string {
+  return wrapInSystemReminder(`## Re-entering Plan Mode
+
+You are returning to plan mode after having previously exited it. A plan file exists at ${planFilePath} from your previous planning session.
+
+**Before proceeding with any new planning, you should:**
+1. Read the existing plan file to understand what was previously planned
+2. Evaluate the user's current request against that plan
+3. Decide how to proceed:
+   - **Different task**: If the user's request is for a different task—even if it's similar or related—start fresh by overwriting the existing plan
+   - **Same task, continuing**: If this is explicitly a continuation or refinement of the exact same task, modify the existing plan while cleaning up outdated or irrelevant sections
+4. Continue on with the plan process and most importantly you should always edit the plan file one way or the other before calling ${EXIT_PLAN_MODE_TOOL_NAME}
+
+Treat this as a fresh planning session. Do not assume the existing plan is relevant without evaluating it first.`);
+}
+
+export function buildExitedPlanModeReminder(
+  planFilePath?: string,
+  planExists?: boolean,
+): string {
+  return wrapInSystemReminder(`## Exited Plan Mode
+
+You have exited plan mode. You can now make edits, run tools, and take actions.${planExists ? ` The plan file is located at ${planFilePath} if you need to reference it.` : ""}`);
+}

package/src/services/aiService.ts

@@ -758,6 +758,7 @@ export interface CompactMessagesOptions {
   messages: ChatCompletionMessageParam[];
   abortSignal?: AbortSignal;
   model?: string;
+  customInstructions?: string;
 }
 
 export interface CompactMessagesResult {
@@ -835,7 +836,9 @@ export async function compactMessages(
           ...cleanedMessages,
           {
             role: "user",
-            content: `Please create a detailed summary of the conversation so far.`,
+            content: options.customInstructions
+              ? `Please create a detailed summary of the conversation so far. Pay special attention to these instructions: ${options.customInstructions}`
+              : `Please create a detailed summary of the conversation so far.`,
           },
         ],
       },

package/src/services/configurationService.ts

@@ -511,12 +511,14 @@ export class ConfigurationService {
     maxTokens?: number,
     permissionMode?: PermissionMode,
   ): ModelConfig {
-    // Resolve agent model: override > options > process.env (includes settings.json env)
+    // Resolve agent model: override > options > currentConfiguration (settings.json model, possibly remote-merged) > process.env
+    // Priority: user's explicit model field > admin's env.WAVE_MODEL default.
+    // If admin wants hard enforcement, they set the `model` scalar field (overwrites local in mergeRemoteSettings).
     const resolvedAgentModel =
       model ||
       this.options.model ||
-      process.env.WAVE_MODEL ||
-      this.currentConfiguration?.model;
+      this.currentConfiguration?.model ||
+      process.env.WAVE_MODEL;
 
     // Resolve fast model: override > options > process.env (includes settings.json env)
     const resolvedFastModel =

package/src/services/initializationService.ts

@@ -77,6 +77,9 @@ export class InitializationService {
 
     const startTime = performance.now();
 
+    // Set global logger early so managers can use it during initialization
+    setGlobalLogger(logger || null);
+
     // Initialize managers first
     try {
       const phaseStart = performance.now();
@@ -123,6 +126,19 @@ export class InitializationService {
       // Don't throw error to prevent app startup failure
     }
 
+    // Initialize remote settings (load disk cache synchronously, then fetch in background)
+    // Must happen BEFORE loadMergedConfiguration so remote env vars are available
+    try {
+      const phaseStart = performance.now();
+      await remoteSettingsService.initialize();
+      logger?.debug(
+        `Initialization Phase [Remote Settings] took ${(performance.now() - phaseStart).toFixed(2)}ms`,
+      );
+    } catch (error) {
+      logger?.error("Failed to initialize remote settings:", error);
+      // Don't throw error to prevent app startup failure - continue without remote settings
+    }
+
     // Initialize hooks configuration
     try {
       const phaseStart = performance.now();
@@ -263,9 +279,6 @@ export class InitializationService {
       logger?.error("Failed to initialize auto-memory directory:", error);
     }
 
-    // Set global logger for SDK-wide access before discovering rules
-    setGlobalLogger(logger || null);
-
     // Discover modular memory rules
     try {
       const phaseStart = performance.now();
@@ -289,18 +302,6 @@ export class InitializationService {
       // Don't throw error to prevent app startup failure - continue without live reload
     }
 
-    // Initialize remote settings (fetch server-managed config)
-    try {
-      const phaseStart = performance.now();
-      await remoteSettingsService.initialize();
-      logger?.debug(
-        `Initialization Phase [Remote Settings] took ${(performance.now() - phaseStart).toFixed(2)}ms`,
-      );
-    } catch (error) {
-      logger?.error("Failed to initialize remote settings:", error);
-      // Don't throw error to prevent app startup failure - continue without remote settings
-    }
-
     // Memory is lazy-cached on first getCombinedMemoryContent call
     // No explicit loading needed during initialization
 

package/src/services/jsonlHandler.ts

@@ -229,7 +229,19 @@ export class JsonlHandler {
     // Extract filename from path
     const filename = filePath.split("/").pop() || "";
 
-    // Check if it's a subagent session
+    // New timestamp-prefixed format
+    const newSubagentMatch = filename.match(
+      /^subagent-(\d{14}-[0-9a-f]{8})\.jsonl$/,
+    );
+    if (newSubagentMatch) {
+      return { sessionId: newSubagentMatch[1], sessionType: "subagent" };
+    }
+    const newMainMatch = filename.match(/^(\d{14}-[0-9a-f]{8})\.jsonl$/);
+    if (newMainMatch) {
+      return { sessionId: newMainMatch[1], sessionType: "main" };
+    }
+
+    // Old UUID format (backward compat)
     const subagentMatch = filename.match(
       /^subagent-([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/,
     );
@@ -240,7 +252,6 @@ export class JsonlHandler {
       };
     }
 
-    // Check if it's a main session
     const mainMatch = filename.match(
       /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/,
     );
@@ -260,18 +271,26 @@ export class JsonlHandler {
    * @returns True if valid, false otherwise
    */
   isValidSessionFilename(filename: string): boolean {
-    // UUID validation patterns
+    // New timestamp-prefixed format patterns
+    const newFormatPattern = /^(\d{14}-[0-9a-f]{8})\.jsonl$/;
+    const newSubagentPattern = /^subagent-(\d{14}-[0-9a-f]{8})\.jsonl$/;
+    // Old UUID format patterns (backward compat)
     const uuidPattern =
       /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/;
     const subagentPattern =
       /^subagent-([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/;
 
-    return uuidPattern.test(filename) || subagentPattern.test(filename);
+    return (
+      newFormatPattern.test(filename) ||
+      newSubagentPattern.test(filename) ||
+      uuidPattern.test(filename) ||
+      subagentPattern.test(filename)
+    );
   }
 
   /**
    * Generate simple filename for sessions
-   * @param sessionId - UUID session identifier
+   * @param sessionId - Session identifier (timestamp-prefixed or legacy UUID format)
    * @param sessionType - Type of session ("main" or "subagent")
    * @returns Generated filename
    */
@@ -279,10 +298,11 @@ export class JsonlHandler {
     sessionId: string,
     sessionType: "main" | "subagent",
   ): string {
-    // Validate sessionId is a valid UUID
+    // Validate sessionId is either new timestamp-prefixed format or legacy UUID
+    const newFormatPattern = /^\d{14}-[0-9a-f]{8}$/;
     const uuidPattern =
       /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
-    if (!uuidPattern.test(sessionId)) {
+    if (!newFormatPattern.test(sessionId) && !uuidPattern.test(sessionId)) {
       throw new Error(`Invalid session ID format: ${sessionId}`);
     }
 

package/src/services/session.ts

@@ -59,11 +59,22 @@ export interface SessionIndex {
 }
 
 /**
- * Generate a new session ID using Node.js native crypto.randomUUID()
- * @returns UUID string for session identification
+ * Generate a new session ID with a timestamp prefix for sortability
+ * Format: {YYYYMMDDHHmmss}-{8hex} (e.g. 20260527143025-a1b2c3d4)
+ * @returns Timestamp-prefixed session ID string
  */
 export function generateSessionId(): string {
-  return randomUUID();
+  const now = new Date();
+  const ts = [
+    now.getFullYear(),
+    String(now.getMonth() + 1).padStart(2, "0"),
+    String(now.getDate()).padStart(2, "0"),
+    String(now.getHours()).padStart(2, "0"),
+    String(now.getMinutes()).padStart(2, "0"),
+    String(now.getSeconds()).padStart(2, "0"),
+  ].join("");
+  const shortId = randomUUID().slice(0, 8);
+  return `${ts}-${shortId}`;
 }
 
 /**
@@ -472,15 +483,17 @@ export async function listSessionsFromJsonl(
       try {
         const filePath = join(projectDir.encodedPath, file);
 
-        // Validate main session filename format (UUID.jsonl)
+        // Validate main session filename format (new timestamp format or legacy UUID)
+        const newFormatMatch = file.match(/^(\d{14}-[0-9a-f]{8})\.jsonl$/);
         const uuidMatch = file.match(
           /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/,
         );
-        if (!uuidMatch) {
+        const match = newFormatMatch || uuidMatch;
+        if (!match) {
           continue; // Skip invalid filenames
         }
 
-        const sessionId = uuidMatch[1];
+        const sessionId = match[1];
 
         // PERFORMANCE OPTIMIZATION: Only read the last message for timestamps and tokens
         const jsonlHandler = new JsonlHandler();
@@ -667,17 +680,24 @@ export async function cleanupExpiredSessionsFromJsonl(
             );
             const indexContent = await fs.readFile(indexPath, "utf8");
             const index = JSON.parse(indexContent) as SessionIndex;
+            // New timestamp-prefixed format patterns
+            const newMainMatch = file.match(/^(\d{14}-[0-9a-f]{8})\.jsonl$/);
+            const newSubagentMatch = file.match(
+              /^subagent-(\d{14}-[0-9a-f]{8})\.jsonl$/,
+            );
+            // Old UUID format patterns (backward compat)
             const uuidMatch = file.match(
-              /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/,
+              /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/,
             );
             const subagentMatch = file.match(
-              /^subagent-([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/,
+              /^subagent-([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/,
             );
-            const sessionId = uuidMatch
-              ? uuidMatch[1]
-              : subagentMatch
-                ? subagentMatch[1]
-                : null;
+            const sessionId =
+              newMainMatch?.[1] ??
+              newSubagentMatch?.[1] ??
+              uuidMatch?.[1] ??
+              subagentMatch?.[1] ??
+              null;
 
             if (sessionId && index.sessions[sessionId]) {
               delete index.sessions[sessionId];

package/src/tools/agentTool.ts

@@ -246,7 +246,7 @@ When using the Agent tool, you must specify a subagent_type parameter to select
               resolve({
                 success: true,
                 content: backgroundMsg,
-                shortResult: `Agent started in background: ${result}`,
+                shortResult: `Agent started in background: ${result}${outputPath ? ` → ${outputPath}` : ""}`,
               });
               return;
             }

package/src/tools/bashTool.ts

@@ -208,7 +208,7 @@ The working directory persists between commands. Try to maintain your current wo
       return {
         success: true,
         content: backgroundMsg,
-        shortResult: `Background process ${taskId} started`,
+        shortResult: `Background process ${taskId} started${outputPath ? ` → ${outputPath}` : ""}`,
       };
     }
 
@@ -226,9 +226,7 @@ The working directory persists between commands. Try to maintain your current wo
         stdio: "pipe",
         detached: true,
         cwd: context.workdir,
-        env: {
-          ...process.env,
-        },
+        env: context.env || { ...process.env },
       });
 
       let outputBuffer = "";
@@ -434,18 +432,17 @@ The working directory persists between commands. Try to maintain your current wo
           }
 
           // If CWD changed, call the onCwdChange callback and add notification
-          let cwdResetMessage: string | undefined;
+          let cwdMessage: string | undefined;
           if (newCwd && newCwd !== context.workdir && context.onCwdChange) {
             const isInSafeZone =
               context.permissionManager?.isPathInSafeZone?.(newCwd) ?? true;
 
-            if (isInSafeZone) {
-              context.onCwdChange(newCwd);
-            } else if (context.originalWorkdir) {
+            if (!isInSafeZone && context.originalWorkdir) {
               context.onCwdChange(context.originalWorkdir);
-              cwdResetMessage = `Shell cwd was reset to ${context.originalWorkdir}`;
+              cwdMessage = `Shell cwd was reset to ${context.originalWorkdir}`;
             } else {
               context.onCwdChange(newCwd);
+              cwdMessage = `Shell working directory changed to ${newCwd}`;
             }
           }
 
@@ -453,9 +450,9 @@ The working directory persists between commands. Try to maintain your current wo
           const combinedOutput =
             outputBuffer + (errorBuffer ? "\n" + errorBuffer : "");
 
-          // Prepend CWD reset message to output if present (like Claude Code's stderr approach)
+          // Prepend CWD change message to output if present
           const finalOutput =
-            (cwdResetMessage ? cwdResetMessage + "\n" : "") +
+            (cwdMessage ? cwdMessage + "\n" : "") +
             (combinedOutput || `Command executed with exit code: ${exitCode}`);
           const content = processToolResult(
             finalOutput,

package/src/tools/editTool.ts

@@ -30,6 +30,7 @@ Usage:
 - 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.
+- Use the smallest \`old_string\` that's clearly unique — usually 2-4 adjacent lines is sufficient. Avoid including 10+ lines of context when less uniquely identifies the target. Shorter matches are less likely to contain reproduction errors.
 - 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: {
@@ -109,6 +110,18 @@ Usage:
     // Touch file to track it in context
     context.messageManager?.touchFile(filePath);
 
+    // Enforce read-before-edit: the file must have been read first
+    if (
+      context.messageManager &&
+      !context.messageManager.hasFileInContext(filePath)
+    ) {
+      return {
+        success: false,
+        content: "",
+        error: `You must read the file with the ${READ_TOOL_NAME} tool before editing it. Use ${READ_TOOL_NAME} on ${filePath} first.`,
+      };
+    }
+
     try {
       const resolvedPath = resolvePath(filePath, context.workdir);
 
@@ -124,19 +137,23 @@ Usage:
         };
       }
 
+      // Normalize line endings for matching
+      const normalizedContent = originalContent.replace(/\r\n/g, "\n");
+      const normalizedOldString = oldString.replace(/\r\n/g, "\n");
+
       // Check if old_string exists
-      const index = originalContent.indexOf(oldString);
-      const matchedOldString = index !== -1 ? oldString : null;
+      const index = normalizedContent.indexOf(normalizedOldString);
+      const matchedOldString = index !== -1 ? normalizedOldString : null;
       const startLineNumber =
         index !== -1
-          ? originalContent.substring(0, index).split("\n").length
+          ? normalizedContent.substring(0, index).split("\n").length
           : undefined;
 
       if (!matchedOldString) {
         return {
           success: false,
           content: "",
-          error: analyzeEditMismatch(),
+          error: analyzeEditMismatch(normalizedOldString),
         };
       }
 
@@ -146,11 +163,11 @@ Usage:
       if (replaceAll) {
         // Replace all matches
         const regex = new RegExp(escapeRegExp(matchedOldString), "g");
-        newContent = originalContent.replace(regex, newString);
-        replacementCount = (originalContent.match(regex) || []).length;
+        newContent = normalizedContent.replace(regex, newString);
+        replacementCount = (normalizedContent.match(regex) || []).length;
       } else {
         // Replace only the first match, but first check if it's unique
-        const matches = originalContent.split(matchedOldString).length - 1;
+        const matches = normalizedContent.split(matchedOldString).length - 1;
         if (matches > 1) {
           return {
             success: false,
@@ -159,7 +176,7 @@ Usage:
           };
         }
 
-        newContent = originalContent.replace(matchedOldString, newString);
+        newContent = normalizedContent.replace(matchedOldString, newString);
         replacementCount = 1;
       }
 

package/src/tools/exitPlanMode.ts

@@ -107,6 +107,9 @@ Ensure your plan is complete and unambiguous:
         };
       }
 
+      context.permissionManager.setHasExitedPlanMode(true);
+      context.permissionManager.setNeedsPlanModeExitAttachment(true);
+
       return {
         success: true,
         content: "Plan approved. Exiting plan mode.",

package/src/tools/readTool.ts

@@ -145,7 +145,7 @@ Usage:
 - The file_path parameter must be an absolute path, not a relative path
 - By default, it reads up to 2000 lines starting from the beginning of the file
 - You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the whole file by not providing these parameters
-- Any lines longer than 2000 characters will be truncated
+- If the file content exceeds the token limit, use offset and limit parameters to read specific portions of the file, or use Bash with grep/jq to extract specific content
 - Results are returned using cat -n format, with line numbers starting at 1
 - This tool allows Agent to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually as Agent is a multimodal LLM.
 - You have the capability to call multiple tools in a single response. It is always better to speculatively read multiple files as a batch that are potentially useful.
@@ -341,13 +341,31 @@ Usage:
       const formattedContent = selectedLines
         .map((line, index) => {
           const lineNumber = startLine + index;
-          // Truncate overly long lines
-          const truncatedLine =
-            line.length > 2000 ? line.substring(0, 2000) + "..." : line;
-          return `${formatLineNumberPrefix(lineNumber)}${truncatedLine}`;
+          return `${formatLineNumberPrefix(lineNumber)}${line}`;
         })
         .join("\n");
 
+      // Token-level validation: estimate tokens and reject if over limit
+      const maxTokens = context.fileReadingLimits?.maxTokens ?? 25000; // Default 25000 tokens
+      const ext = extname(actualFilePath).toLowerCase().slice(1);
+      const bytesPerToken =
+        ext === "json" || ext === "jsonl" || ext === "jsonc" ? 2 : 4;
+      const estimatedTokens = Math.ceil(
+        formattedContent.length / bytesPerToken,
+      );
+      if (estimatedTokens > maxTokens) {
+        return {
+          success: false,
+          content: "",
+          error: `File content (~${estimatedTokens.toLocaleString()} tokens) exceeds maximum allowed tokens (${maxTokens.toLocaleString()}). Use offset and limit parameters to read specific portions of the file, or use Bash with grep/jq to search within it for specific content.`,
+          metadata: {
+            type: "error_token_limit_exceeded",
+            estimatedTokens,
+            maxTokens,
+          },
+        };
+      }
+
       // Add file information header
       let content = `File: ${filePath}\n`;
       if (startLine > 1 || endLine < totalLines) {

package/src/tools/types.ts

@@ -111,4 +111,6 @@ export interface ToolContext {
   onCwdChange?: (newCwd: string) => void;
   /** Original working directory (before any cd changes) for CWD reset */
   originalWorkdir?: string;
+  /** Merged environment variables (process.env + agent env) for child processes */
+  env?: Record<string, string>;
 }

package/src/types/agent.ts

@@ -30,6 +30,8 @@ export interface AgentOptions {
   /** Wave server URL for SSO authentication (fallback to WAVE_SERVER_URL env var) */
   serverUrl?: string;
   defaultHeaders?: Record<string, string>;
+  /** Per-subagent-type headers, merged into defaultHeaders for matching subagents */
+  subagentHeaders?: Record<string, Record<string, string>>;
   fetchOptions?: ClientOptions["fetchOptions"];
   fetch?: ClientOptions["fetch"];
   model?: string;
@@ -95,6 +97,8 @@ export interface AgentOptions {
    * File-based hooks (from config.json/.waverc.json) merge on top of these.
    */
   hooks?: PartialHookConfiguration;
+  /** Per-agent environment variables, merged on top of process.env for bash, MCP, and hooks */
+  env?: Record<string, string>;
   [key: string]: unknown;
 }
 

package/src/types/hooks.ts

@@ -24,7 +24,9 @@ export type HookEvent =
   | "WorktreeRemove"
   | "CwdChanged"
   | "SessionStart"
-  | "SessionEnd";
+  | "SessionEnd"
+  | "PreCompact"
+  | "PostCompact";
 
 // Individual hook command configuration
 export interface HookCommand {
@@ -117,6 +119,8 @@ export function isValidHookEvent(event: string): event is HookEvent {
     "CwdChanged",
     "SessionStart",
     "SessionEnd",
+    "PreCompact",
+    "PostCompact",
   ].includes(event);
 }
 
@@ -187,6 +191,8 @@ export interface HookJsonInput {
   source?: SessionStartSource; // Present for SessionStart events
   agent_type?: string; // Present for SessionStart events
   end_source?: SessionEndSource; // Present for SessionEnd events
+  compact_instructions?: string; // Present for PreCompact events
+  compact_summary?: string; // Present for PostCompact events
 }
 
 // Extended context interface for passing additional data to hook executor
@@ -205,6 +211,8 @@ export interface ExtendedHookExecutionContext extends HookExecutionContext {
   source?: SessionStartSource; // Session start source (SessionStart only)
   agentType?: string; // Agent type identifier (SessionStart only)
   endSource?: SessionEndSource; // Session end source (SessionEnd only)
+  compactInstructions?: string; // Custom instructions for PreCompact
+  compactSummary?: string; // Summary text for PostCompact
 }
 
 // Environment variables injected into hook processes

package/src/types/mcp.ts

@@ -4,6 +4,7 @@
  */
 
 export interface McpServerConfig {
+  type?: "stdio" | "sse" | "http";
   command?: string;
   args?: string[];
   env?: Record<string, string>;