wave-agent-sdk 0.16.13 → 0.17.1

package/src/managers/aiManager.ts

@@ -5,6 +5,7 @@ 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";
+import { existsSync } from "node:fs";
 import type {
   GatewayConfig,
   ModelConfig,
@@ -23,6 +24,12 @@ import type { PermissionManager } from "./permissionManager.js";
 import type { SubagentManager } from "./subagentManager.js";
 import type { SkillManager } from "./skillManager.js";
 import { buildSystemPrompt } from "../prompts/index.js";
+import {
+  buildPlanModeReminder,
+  buildPlanModeSparseReminder,
+  buildPlanModeReEntryReminder,
+  buildExitedPlanModeReminder,
+} from "../prompts/planModeReminders.js";
 import { Container } from "../utils/container.js";
 import { recoverTruncatedJson } from "../utils/stringUtils.js";
 import { ConfigurationService } from "../services/configurationService.js";
@@ -217,6 +224,119 @@ export class AIManager {
     });
   }
 
+  /**
+   * Build plan mode system-reminder messages to inject into the API message stream.
+   * These are transient messages not stored in the message history.
+   * This preserves prompt caching by keeping the system prompt constant.
+   */
+  private buildPlanModeMessages(
+    currentMode: PermissionMode | undefined,
+  ): import("openai/resources.js").ChatCompletionMessageParam[] {
+    const messages: import("openai/resources.js").ChatCompletionMessageParam[] =
+      [];
+    if (!this.permissionManager) return messages;
+
+    // Handle exit notification (one-time after leaving plan mode)
+    if (this.permissionManager.getNeedsPlanModeExitAttachment()) {
+      const planFilePath = this.permissionManager.getPlanFilePath();
+      const planExists = planFilePath ? existsSync(planFilePath) : false;
+      messages.push({
+        role: "user",
+        content: buildExitedPlanModeReminder(planFilePath, planExists),
+      });
+      this.permissionManager.setNeedsPlanModeExitAttachment(false);
+    }
+
+    // Handle plan mode reminders
+    if (currentMode !== "plan") return messages;
+
+    const planFilePath = this.permissionManager.getPlanFilePath();
+    if (!planFilePath) return messages;
+
+    const planExists = existsSync(planFilePath);
+
+    // Check for re-entry: flag is set AND plan file exists
+    if (this.permissionManager.hasExitedPlanModeInSession() && planExists) {
+      messages.push({
+        role: "user",
+        content: buildPlanModeReEntryReminder(planFilePath),
+      });
+      this.permissionManager.setHasExitedPlanMode(false); // One-time
+    }
+
+    // Count plan_mode system-reminders in existing messages to determine full vs sparse
+    // and count human turns since last reminder for throttling
+    const recentApiMessages = this.messageManager.getMessages();
+    let planModeReminderCount = 0;
+    let humanTurnsSinceLastReminder = 0;
+    let foundLastReminder = false;
+
+    for (let i = recentApiMessages.length - 1; i >= 0; i--) {
+      const msg = recentApiMessages[i];
+      if (msg.role === "user" && !msg.isMeta) {
+        // Count human turns (non-meta user messages without tool results)
+        const hasToolResult = msg.blocks?.some(
+          (b: { type: string }) => b.type === "tool",
+        );
+        if (!hasToolResult) {
+          if (!foundLastReminder) {
+            humanTurnsSinceLastReminder++;
+          }
+        }
+      }
+      // Check for existing plan mode system-reminders
+      if (msg.role === "user" && msg.isMeta) {
+        const textContent = msg.blocks
+          ?.filter((b) => b.type === "text")
+          .map((b) => ("content" in b ? b.content : ""))
+          .join("");
+        if (
+          textContent?.includes("Plan mode is active") ||
+          textContent?.includes("Plan mode still active")
+        ) {
+          planModeReminderCount++;
+          if (!foundLastReminder) {
+            foundLastReminder = true;
+          }
+        }
+      }
+    }
+
+    // Throttle: only inject every 5 human turns (but always inject on first turn)
+    const TURNS_BETWEEN_REMINDERS = 5;
+    const FULL_REMINDER_EVERY_N = 5;
+
+    if (
+      foundLastReminder &&
+      humanTurnsSinceLastReminder < TURNS_BETWEEN_REMINDERS
+    ) {
+      return messages; // Throttled — skip reminder
+    }
+
+    // Determine full vs sparse
+    // Every 5th reminder is full; rest are sparse
+    const reminderNumber = planModeReminderCount + 1;
+    const isFull = reminderNumber % FULL_REMINDER_EVERY_N === 1;
+
+    if (isFull) {
+      messages.push({
+        role: "user",
+        content: buildPlanModeReminder(
+          planFilePath,
+          planExists,
+          !!this.subagentType,
+        ),
+      });
+    } else {
+      messages.push({
+        role: "user",
+        content: buildPlanModeSparseReminder(planFilePath),
+      });
+    }
+
+    return messages;
+  }
+
   public setIsLoading(isLoading: boolean): void {
     this.isLoading = isLoading;
     this.onLoadingChange?.(isLoading);
@@ -294,272 +414,327 @@ export class AIManager {
         `Token usage exceeded ${this.getMaxInputTokens()}, compacting messages...`,
       );
 
-      // Check if messages need compaction
       const messagesToCompact = this.messageManager.getMessages();
+      if (messagesToCompact.length === 0) return;
 
-      // If there are messages to compact, perform compaction
-      if (messagesToCompact.length > 0) {
-        // Circuit breaker: skip compaction after 3 consecutive failures
-        if (this.consecutiveCompactionFailures >= 3) {
-          logger?.warn(
-            `Skipping compaction: ${this.consecutiveCompactionFailures} consecutive failures`,
-          );
-          return;
-        }
+      // Circuit breaker: skip compaction after 3 consecutive failures
+      if (this.consecutiveCompactionFailures >= 3) {
+        logger?.warn(
+          `Skipping compaction: ${this.consecutiveCompactionFailures} consecutive failures`,
+        );
+        return;
+      }
 
-        const recentChatMessages = convertMessagesForAPI(messagesToCompact);
+      await this.compactConversation({
+        abortSignal: abortController.signal,
+      });
+    }
+  }
 
-        // Save session before compaction to preserve original messages
-        await this.messageManager.saveSession();
+  /**
+   * Manually compact the conversation history.
+   * Called by /compact slash command or auto-compaction trigger.
+   */
+  public async compactConversation(
+    options: {
+      customInstructions?: string;
+      abortSignal?: AbortSignal;
+    } = {},
+  ): Promise<void> {
+    const messagesToCompact = this.messageManager.getMessages();
+    if (messagesToCompact.length === 0) {
+      logger?.debug("No messages to compact");
+      return;
+    }
 
-        this.setIsCompacting(true);
-        try {
-          const compactResult = await aiService.compactMessages({
-            gatewayConfig: this.getGatewayConfig(),
-            modelConfig: this.getModelConfig(),
-            messages: recentChatMessages,
-            abortSignal: abortController.signal,
-            model: this.getModelConfig().fastModel,
-          });
+    // Circuit breaker: skip if already compacting
+    if (this.isCompacting) {
+      logger?.warn("Compaction already in progress");
+      return;
+    }
 
-          // Handle usage tracking for compaction operations
-          let compactUsage: Usage | undefined;
-          if (compactResult.usage) {
-            compactUsage = {
-              prompt_tokens: compactResult.usage.prompt_tokens,
-              completion_tokens: compactResult.usage.completion_tokens,
-              total_tokens: compactResult.usage.total_tokens,
-              model: this.getModelConfig().fastModel,
-              operation_type: "compact",
-            };
-          }
+    // 1. Run PreCompact hooks
+    let hookInstructions: string | undefined;
+    if (this.hookManager) {
+      try {
+        const preResult = await this.hookManager.executePreCompactHooks(
+          this.messageManager.getSessionId(),
+          this.messageManager.getTranscriptPath(),
+          options.customInstructions,
+        );
+        hookInstructions = preResult.additionalInstructions;
+      } catch (error) {
+        logger?.warn(`PreCompact hooks failed: ${(error as Error).message}`);
+      }
+    }
 
-          // 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[] = [];
+    // 2. Merge custom instructions
+    const mergedInstructions =
+      [options.customInstructions, hookInstructions]
+        .filter(Boolean)
+        .join("\n") || undefined;
 
-          // 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;
-          }
+    // 3. Save session before compaction
+    await this.messageManager.saveSession();
 
-          // 2. Working directory
-          contextParts.push(
-            `\n\n[Working Directory]\nCurrent working directory: ${this.getWorkdir()}`,
-          );
+    this.setIsCompacting(true);
+    try {
+      const recentChatMessages = convertMessagesForAPI(messagesToCompact);
 
-          // 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. Call compactMessages with optional custom instructions
+      const compactResult = await aiService.compactMessages({
+        gatewayConfig: this.getGatewayConfig(),
+        modelConfig: this.getModelConfig(),
+        messages: recentChatMessages,
+        abortSignal: options.abortSignal,
+        model: this.getModelConfig().fastModel,
+        customInstructions: mergedInstructions,
+      });
 
-          // 4. Invoked skills context (with token budget, matching Claude Code)
-          const POST_COMPACT_SKILLS_TOKEN_BUDGET = 25_000;
-          const POST_COMPACT_MAX_TOKENS_PER_SKILL = 5_000;
-          const invokedSkillNames =
-            this.messageManager.getInvokedSkillNames(10);
-          if (invokedSkillNames.length > 0 && this.skillManager) {
-            const invokedSkillParts: string[] = [];
-            let skillsUsedTokens = 0;
-            for (const skillName of invokedSkillNames) {
-              try {
-                const skill = await this.skillManager.loadSkill(skillName);
-                if (!skill) continue;
+      // 5. Handle usage tracking
+      let compactUsage: Usage | undefined;
+      if (compactResult.usage) {
+        compactUsage = {
+          prompt_tokens: compactResult.usage.prompt_tokens,
+          completion_tokens: compactResult.usage.completion_tokens,
+          total_tokens: compactResult.usage.total_tokens,
+          model: this.getModelConfig().fastModel,
+          operation_type: "compact",
+        };
+      }
 
-                // Extract content after frontmatter (matching prepareSkillContent pattern)
-                const contentMatch = skill.content.match(
-                  /^---\n[\s\S]*?\n---\n([\s\S]*)$/,
-                );
-                let skillContent = contentMatch
-                  ? contentMatch[1].trim()
-                  : skill.content;
-
-                // Per-skill token budget enforcement (~4 chars per token)
-                const maxSkillChars = POST_COMPACT_MAX_TOKENS_PER_SKILL * 4;
-                if (skillContent.length > maxSkillChars) {
-                  skillContent =
-                    skillContent.slice(0, maxSkillChars) +
-                    "\n\n...[truncated]...";
-                }
+      // 6. Build post-compact context restoration
+      const enhancedSummary = await this.buildPostCompactContext(
+        compactResult.content,
+      );
 
-                const skillTokens = Math.ceil(skillContent.length / 4);
-                if (
-                  skillsUsedTokens + skillTokens >
-                  POST_COMPACT_SKILLS_TOKEN_BUDGET
-                )
-                  break;
-                skillsUsedTokens += skillTokens;
+      // 7. Execute message reconstruction
+      this.messageManager.compactMessagesAndUpdateSession(
+        enhancedSummary,
+        compactUsage,
+      );
 
-                invokedSkillParts.push(
-                  `\n\n## ${skill.name}\n${skill.description ? `*${skill.description}*\n\n` : ""}\`\`\`\n${skillContent}\n\`\`\``,
-                );
-              } catch {
-                // Skip skills that can't be loaded
-              }
-            }
-            if (invokedSkillParts.length > 0) {
-              contextParts.push(
-                `\n\n[Invoked Skills]\n${invokedSkillParts.join("")}`,
-              );
-            }
-          }
+      // 8. Track usage
+      if (compactUsage && this.callbacks?.onUsageAdded) {
+        this.callbacks.onUsageAdded(compactUsage);
+      }
 
-          // 5. Background subagent status (shell tasks excluded, matching Claude Code's createAsyncAgentAttachmentsIfNeeded)
-          const agents =
-            this.backgroundTaskManager
-              ?.getAllTasks()
-              .filter((a) => a.type === "subagent") || [];
-          if (agents.length > 0) {
-            const agentParts: string[] = [];
-            for (const a of agents) {
-              if (a.status === "killed") {
-                agentParts.push(
-                  `Task "${a.description}" (${a.id}) was stopped by the user.`,
-                );
-              } else if (a.status === "running") {
-                const parts = [
-                  `Background agent "${a.description}" (${a.id}) is still running.`,
-                  `Do NOT spawn a duplicate. You will be notified when it completes.`,
-                ];
-                if (a.outputPath) {
-                  parts.push(`You can read partial output at ${a.outputPath}.`);
-                }
-                agentParts.push(parts.join(" "));
-              } else {
-                // completed or failed
-                const parts = [
-                  `Task ${a.id} (status: ${a.status}) (description: ${a.description}).`,
-                ];
-                const deltaText = a.status === "failed" ? a.stderr : a.stdout;
-                if (deltaText && deltaText.length > 0) {
-                  const summary =
-                    deltaText.length > 500
-                      ? deltaText.slice(0, 500) + "..."
-                      : deltaText;
-                  parts.push(`Delta: ${summary}`);
-                }
-                if (a.outputPath) {
-                  parts.push(
-                    `Read the output file to retrieve the result: ${a.outputPath}.`,
-                  );
-                }
-                agentParts.push(parts.join(" "));
-              }
-            }
-            if (agentParts.length > 0) {
-              contextParts.push(
-                `\n\n[Background Tasks]\n${agentParts.join("\n")}`,
-              );
-            }
-          }
+      this.consecutiveCompactionFailures = 0;
 
-          // Merge context restoration into summary
-          const enhancedSummary =
-            compactResult.content +
-            (contextParts.length > 0
-              ? `\n\n[Context Restoration]` + contextParts.join("")
-              : "");
-
-          // Execute message reconstruction and sessionId update after compaction
-          this.messageManager.compactMessagesAndUpdateSession(
-            enhancedSummary,
-            compactUsage,
-          );
+      // 9. Log OTEL event
+      logOTelEvent("compaction", {
+        beforeTokens: String(messagesToCompact.length),
+        afterTokens: "1",
+        model: this.getModelConfig().fastModel,
+      }).catch(() => {});
 
-          // Notify Agent to add to usage tracking
-          if (compactUsage && this.callbacks?.onUsageAdded) {
-            this.callbacks.onUsageAdded(compactUsage);
+      // 10. Run SessionStart hooks (existing behavior)
+      if (this.hookManager) {
+        try {
+          const newSessionId = this.messageManager.getSessionId();
+          const sessionStartResult =
+            await this.hookManager.executeSessionStartHooks(
+              "compact",
+              newSessionId,
+              this.messageManager.getTranscriptPath(),
+              this.subagentType,
+            );
+          if (sessionStartResult.additionalContext) {
+            this.messageManager.addUserMessage({
+              content: `<system-reminder>\nSessionStart hook additional context: ${sessionStartResult.additionalContext}\n</system-reminder>`,
+              isMeta: true,
+            });
           }
+          if (sessionStartResult.initialUserMessage) {
+            this.messageManager.addUserMessage({
+              content: sessionStartResult.initialUserMessage,
+              isMeta: true,
+            });
+          }
+        } catch (error) {
+          logger?.warn(
+            `SessionStart hooks on compact failed: ${(error as Error).message}`,
+          );
+        }
+      }
 
-          logger?.debug(
-            `Successfully compacted ${messagesToCompact.length} messages and updated session`,
+      // 11. Run PostCompact hooks
+      if (this.hookManager) {
+        try {
+          await this.hookManager.executePostCompactHooks(
+            this.messageManager.getSessionId(),
+            this.messageManager.getTranscriptPath(),
+            compactResult.content,
           );
-          this.consecutiveCompactionFailures = 0;
+        } catch (error) {
+          logger?.warn(`PostCompact hooks failed: ${(error as Error).message}`);
+        }
+      }
 
-          // Log compaction event
-          logOTelEvent("compaction", {
-            beforeTokens: String(messagesToCompact.length),
-            afterTokens: "1",
-            model: this.getModelConfig().fastModel,
-          }).catch(() => {});
+      logger?.debug(
+        `Successfully compacted ${messagesToCompact.length} messages`,
+      );
+    } catch (compactError) {
+      this.consecutiveCompactionFailures++;
+      logger?.error(
+        `Failed to compact messages (${this.consecutiveCompactionFailures} consecutive):`,
+        compactError,
+      );
+      this.messageManager.addErrorBlock(
+        `Failed to compact conversation history: ${compactError instanceof Error ? compactError.message : String(compactError)}. You may encounter context limit issues.`,
+      );
+    } finally {
+      this.setIsCompacting(false);
+    }
+  }
 
-          // Run SessionStart hooks after compaction to restore context
-          if (this.hookManager) {
-            try {
-              const newSessionId = this.messageManager.getSessionId();
-              const sessionStartResult =
-                await this.hookManager.executeSessionStartHooks(
-                  "compact",
-                  newSessionId,
-                  this.messageManager.getTranscriptPath(),
-                  this.subagentType,
-                );
+  /**
+   * Build post-compact context restoration content.
+   * Restores file reads, working directory, plan mode, skills, and background tasks.
+   */
+  private async buildPostCompactContext(summary: string): Promise<string> {
+    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;
+    }
 
-              // Inject additionalContext as a meta user message
-              if (sessionStartResult.additionalContext) {
-                this.messageManager.addUserMessage({
-                  content: `<system-reminder>\nSessionStart hook additional context: ${sessionStartResult.additionalContext}\n</system-reminder>`,
-                  isMeta: true,
-                });
-              }
+    // 2. Working directory
+    contextParts.push(
+      `\n\n[Working Directory]\nCurrent working directory: ${this.getWorkdir()}`,
+    );
 
-              // Inject initialUserMessage as a meta user message
-              if (sessionStartResult.initialUserMessage) {
-                this.messageManager.addUserMessage({
-                  content: sessionStartResult.initialUserMessage,
-                  isMeta: true,
-                });
-              }
-            } catch (error) {
-              logger?.warn(
-                `SessionStart hooks on compact failed: ${(error as Error).message}`,
-              );
-            }
+    // 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${buildPlanModeReminder(planFilePath, planExists, !!this.subagentType)}`,
+        );
+      }
+    }
+
+    // 4. Invoked skills context (with token budget, matching Claude Code)
+    const POST_COMPACT_SKILLS_TOKEN_BUDGET = 25_000;
+    const POST_COMPACT_MAX_TOKENS_PER_SKILL = 5_000;
+    const invokedSkillNames = this.messageManager.getInvokedSkillNames(10);
+    if (invokedSkillNames.length > 0 && this.skillManager) {
+      const invokedSkillParts: string[] = [];
+      let skillsUsedTokens = 0;
+      for (const skillName of invokedSkillNames) {
+        try {
+          const skill = await this.skillManager.loadSkill(skillName);
+          if (!skill) continue;
+
+          const contentMatch = skill.content.match(
+            /^---\n[\s\S]*?\n---\n([\s\S]*)$/,
+          );
+          let skillContent = contentMatch
+            ? contentMatch[1].trim()
+            : skill.content;
+
+          const maxSkillChars = POST_COMPACT_MAX_TOKENS_PER_SKILL * 4;
+          if (skillContent.length > maxSkillChars) {
+            skillContent =
+              skillContent.slice(0, maxSkillChars) + "\n\n...[truncated]...";
           }
-        } catch (compactError) {
-          this.consecutiveCompactionFailures++;
-          logger?.error(
-            `Failed to compact messages (${this.consecutiveCompactionFailures} consecutive):`,
-            compactError,
+
+          const skillTokens = Math.ceil(skillContent.length / 4);
+          if (skillsUsedTokens + skillTokens > POST_COMPACT_SKILLS_TOKEN_BUDGET)
+            break;
+          skillsUsedTokens += skillTokens;
+
+          invokedSkillParts.push(
+            `\n\n## ${skill.name}\n${skill.description ? `*${skill.description}*\n\n` : ""}\`\`\`\n${skillContent}\n\`\`\``,
           );
-          this.messageManager.addErrorBlock(
-            `Failed to compact conversation history: ${compactError instanceof Error ? compactError.message : String(compactError)}. You may encounter context limit issues.`,
+        } catch {
+          // Skip skills that can't be loaded
+        }
+      }
+      if (invokedSkillParts.length > 0) {
+        contextParts.push(
+          `\n\n[Invoked Skills]\n${invokedSkillParts.join("")}`,
+        );
+      }
+    }
+
+    // 5. Background subagent status (shell tasks excluded, matching Claude Code's createAsyncAgentAttachmentsIfNeeded)
+    const agents =
+      this.backgroundTaskManager
+        ?.getAllTasks()
+        .filter((a) => a.type === "subagent") || [];
+    if (agents.length > 0) {
+      const agentParts: string[] = [];
+      for (const a of agents) {
+        if (a.status === "killed") {
+          agentParts.push(
+            `Task "${a.description}" (${a.id}) was stopped by the user.`,
           );
-        } finally {
-          this.setIsCompacting(false);
+        } else if (a.status === "running") {
+          const parts = [
+            `Background agent "${a.description}" (${a.id}) is still running.`,
+            `Do NOT spawn a duplicate. You will be notified when it completes.`,
+          ];
+          if (a.outputPath) {
+            parts.push(`You can read partial output at ${a.outputPath}.`);
+          }
+          agentParts.push(parts.join(" "));
+        } else {
+          // completed or failed
+          const parts = [
+            `Task ${a.id} (status: ${a.status}) (description: ${a.description}).`,
+          ];
+          const deltaText = a.status === "failed" ? a.stderr : a.stdout;
+          if (deltaText && deltaText.length > 0) {
+            const summary =
+              deltaText.length > 500
+                ? deltaText.slice(0, 500) + "..."
+                : deltaText;
+            parts.push(`Delta: ${summary}`);
+          }
+          if (a.outputPath) {
+            parts.push(
+              `Read the output file to retrieve the result: ${a.outputPath}.`,
+            );
+          }
+          agentParts.push(parts.join(" "));
         }
       }
+      if (agentParts.length > 0) {
+        contextParts.push(`\n\n[Background Tasks]\n${agentParts.join("\n")}`);
+      }
     }
+
+    return (
+      summary +
+      (contextParts.length > 0
+        ? `\n\n[Context Restoration]` + contextParts.join("")
+        : "")
+    );
   }
 
   public getIsCompacting(): boolean {
@@ -685,22 +860,11 @@ export class AIManager {
         .getTools()
         .filter((t) => toolNames.has(t.name));
 
-      let planModeOptions:
-        | { planFilePath: string; planExists: boolean }
-        | undefined;
-
-      if (currentMode === "plan") {
-        const planFilePath = this.permissionManager?.getPlanFilePath();
-        if (planFilePath) {
-          let planExists = false;
-          try {
-            await fs.access(planFilePath);
-            planExists = true;
-          } catch {
-            planExists = false;
-          }
-          planModeOptions = { planFilePath, planExists };
-        }
+      // Inject plan mode system-reminder messages (not system prompt)
+      // This preserves prompt caching by keeping the system prompt constant
+      const planModeMessages = this.buildPlanModeMessages(currentMode);
+      if (planModeMessages.length > 0) {
+        recentMessages.push(...planModeMessages);
       }
 
       let autoMemoryOptions: { directory: string; content: string } | undefined;
@@ -733,7 +897,6 @@ export class AIManager {
             memory: combinedMemory,
             language: this.getLanguage(),
             isSubagent: !!this.subagentType,
-            planMode: planModeOptions,
             autoMemory: autoMemoryOptions,
             permissionMode: currentMode,
           },