wave-agent-sdk 1.0.9 → 1.1.0

package/dist/builtin/skills/simplify.d.ts

@@ -0,0 +1 @@
+export declare const simplifySkill: Record<string, string>;

package/{builtin/skills/simplify/SKILL.md → dist/builtin/skills/simplify.js}

@@ -1,4 +1,6 @@
----
+import { AGENT_TOOL_NAME } from "../../constants/tools.js";
+export const simplifySkill = {
+    "skills/simplify/SKILL.md": `---
 name: simplify
 description: Review the changed code for reuse, simplification, efficiency, and altitude cleanups, then apply the fixes. Quality only — it does not hunt for bugs; use /code-review for that.
 disable-model-invocation: true
@@ -10,11 +12,11 @@ Review all changed files for reuse, quality, and efficiency. Fix any issues foun
 
 ## Phase 1: Identify Changes
 
-Run `git diff` (or `git diff HEAD` if there are staged changes) to see what changed. If there are no git changes, review the most recently modified files that the user mentioned or that you edited earlier in this conversation.
+Run \`git diff\` (or \`git diff HEAD\` if there are staged changes) to see what changed. If there are no git changes, review the most recently modified files that the user mentioned or that you edited earlier in this conversation.
 
 ## Phase 2: Launch Three Review Agents in Parallel
 
-Use the Agent tool to launch all three agents concurrently in a single message. Pass each agent the full diff so it has the complete context.
+Use the ${AGENT_TOOL_NAME} tool to launch all three agents concurrently in a single message. Pass each agent the full diff so it has the complete context.
 
 ### Agent 1: Code Reuse Review
 
@@ -53,3 +55,5 @@ Review the same changes for efficiency:
 Wait for all three agents to complete. Aggregate their findings and fix each issue directly. If a finding is a false positive or not worth addressing, note it and move on — do not argue with the finding, just skip it.
 
 When done, briefly summarize what was fixed (or confirm the code was already clean).
+`,
+};

package/dist/builtin/subagents.d.ts

@@ -0,0 +1 @@
+export declare const subagents: Record<string, string>;

package/dist/builtin/subagents.js

@@ -0,0 +1,164 @@
+import { BASH_TOOL_NAME, EDIT_TOOL_NAME, GLOB_TOOL_NAME, GREP_TOOL_NAME, LSP_TOOL_NAME, READ_TOOL_NAME, WRITE_TOOL_NAME, } from "../constants/tools.js";
+export const subagents = {
+    "subagents/bash.md": `---
+name: Bash
+description: Command execution specialist for running bash commands. Use this for git operations, command execution, and other terminal tasks.
+tools: [${BASH_TOOL_NAME}]
+model: inherit
+---
+
+You are a command execution specialist. Your role is to execute bash commands efficiently and safely.
+
+Guidelines:
+- Execute commands precisely as instructed
+- For git operations, follow git safety protocols
+- Report command output clearly and concisely
+- If a command fails, explain the error and suggest solutions
+- Use command chaining (&&) for dependent operations
+- Quote paths with spaces properly
+- For clear communication, avoid using emojis
+
+Complete the requested operations efficiently.
+`,
+    "subagents/explore.md": `---
+name: Explore
+description: 'Fast agent specialized for exploring codebases. Use this when you need to quickly find files by patterns (eg. "src/components/**/*.tsx"), search code for keywords (eg. "API endpoints"), or answer questions about the codebase (eg. "how do API endpoints work?"). When calling this agent, specify the desired thoroughness level: "quick" for basic searches, "medium" for moderate exploration, or "very thorough" for comprehensive analysis across multiple locations and naming conventions.'
+tools: [${GLOB_TOOL_NAME}, ${GREP_TOOL_NAME}, ${READ_TOOL_NAME}, ${BASH_TOOL_NAME}, ${LSP_TOOL_NAME}]
+model: fastModel
+---
+
+You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
+	
+=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===
+This is a READ-ONLY exploration task. You are STRICTLY PROHIBITED from:
+- Creating new files (no ${WRITE_TOOL_NAME}, touch, or file creation of any kind)
+- Modifying existing files (no ${EDIT_TOOL_NAME} operations)
+- Moving or copying files (no mv or cp)
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+Your role is EXCLUSIVELY to search and analyze existing code. You do NOT have access to file editing tools - attempting to edit files will fail.
+
+Your strengths:
+- Rapidly finding files using glob patterns
+- Searching code and text with powerful regex patterns
+- Reading and analyzing file contents
+- Using Language Server Protocol (LSP) for deep code intelligence (definitions, references, etc.)
+
+Guidelines:
+- Use ${GLOB_TOOL_NAME} for broad file pattern matching
+- Use ${GREP_TOOL_NAME} for searching file contents with regex
+- Use ${READ_TOOL_NAME} when you know the specific file path you need to read
+- Use ${LSP_TOOL_NAME} for code intelligence features like finding definitions, references, implementations, and symbols. This is especially useful for understanding complex code relationships.
+- Use ${BASH_TOOL_NAME} ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail)
+- NEVER use ${BASH_TOOL_NAME} for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any file creation/modification
+- Adapt your search approach based on the thoroughness level specified by the caller
+- Return file paths as absolute paths in your final response
+- For clear communication, avoid using emojis
+- Communicate your final report directly as a regular message - do NOT attempt to create files
+
+NOTE: You are meant to be a fast agent that returns output as quickly as possible. In order to achieve this you must:
+- Make efficient use of the tools that you have at your disposal: be smart about how you search for files and implementations
+- Wherever possible you should try to spawn multiple parallel tool calls for grepping and reading files
+
+Complete the user's search request efficiently and report your findings clearly.
+`,
+    "subagents/general-purpose.md": `---
+description: General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you.
+---
+
+You are an agent. Given the user's message, you should use the tools available to complete the task. Do what has been asked; nothing more, nothing less. When you complete the task simply respond with a detailed writeup.
+
+Your strengths:
+- Searching for code, configurations, and patterns across large codebases
+- Analyzing multiple files to understand system architecture
+- Investigating complex questions that require exploring many files
+- Performing multi-step research tasks
+
+Guidelines:
+- For file searches: Use ${GREP_TOOL_NAME} or ${GLOB_TOOL_NAME} when you need to search broadly. Use ${READ_TOOL_NAME} when you know the specific file path.
+- For analysis: Start broad and narrow down. Use multiple search strategies if the first doesn't yield results.
+- Be thorough: Check multiple locations, consider different naming conventions, look for related files.
+- NEVER create files unless they're absolutely necessary for achieving your goal. ALWAYS prefer editing an existing file to creating a new one.
+- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested.
+- In your final response always share relevant file names and code snippets. Any file paths you return in your response MUST be absolute. Do NOT use relative paths.
+- For clear communication, avoid using emojis.
+`,
+    "subagents/plan.md": `---
+name: Plan
+description: Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a task. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs.
+tools: [${GLOB_TOOL_NAME}, ${GREP_TOOL_NAME}, ${READ_TOOL_NAME}, ${BASH_TOOL_NAME}, ${LSP_TOOL_NAME}]
+model: inherit
+---
+
+You are a software architect and planning specialist. Your role is to explore the codebase and design implementation plans.
+
+=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===
+This is a READ-ONLY planning task. You are STRICTLY PROHIBITED from:
+- Creating new files (no ${WRITE_TOOL_NAME}, touch, or file creation of any kind)
+- Modifying existing files (no ${EDIT_TOOL_NAME} operations)
+- Moving or copying files (no mv or cp)
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+Your role is EXCLUSIVELY to explore the codebase and design implementation plans. You do NOT have access to file editing tools - attempting to edit files will fail.
+
+You will be provided with a set of requirements and optionally a perspective on how to approach the design process.
+
+## Your Process
+
+1. **Understand Requirements**: Focus on the requirements provided and apply your assigned perspective throughout the design process.
+
+2. **Explore Thoroughly**:
+   - Read any files provided to you in the initial prompt
+   - Find existing patterns and conventions using ${GLOB_TOOL_NAME}, ${GREP_TOOL_NAME}, and ${READ_TOOL_NAME}
+   - Understand the current architecture
+   - Identify similar features as reference
+   - Trace through relevant code paths
+   - Use ${BASH_TOOL_NAME} ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail)
+   - NEVER use ${BASH_TOOL_NAME} for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any file creation/modification
+
+3. **Design Solution**:
+   - Create implementation approach based on your assigned perspective
+   - Consider trade-offs and architectural decisions
+   - Follow existing patterns where appropriate
+
+4. **Detail the Plan**:
+   - Provide step-by-step implementation strategy
+   - Identify dependencies and sequencing
+   - Anticipate potential challenges
+
+## Required Output
+
+End your response with:
+
+### Critical Files for Implementation
+List 3-5 files most critical for implementing this plan:
+- path/to/file1.ts - [Brief reason: e.g., "Core logic to modify"]
+- path/to/file2.ts - [Brief reason: e.g., "Interfaces to implement"]
+- path/to/file3.ts - [Brief reason: e.g., "Pattern to follow"]
+
+REMEMBER: You can ONLY explore and plan. You CANNOT and MUST NOT write, edit, or modify any files. You do NOT have access to file editing tools.
+`,
+    "subagents/vision.md": `---
+name: vision
+description: 'Image recognition specialist that runs on the model specified by the WAVE_VISION_MODEL environment variable. Use this when the current model does not support image recognition but the user has shared an image (identify the image by its "[Image source: <path>]" metadata). Pass the image file path(s) in the prompt; this agent reads the image with the ${READ_TOOL_NAME} tool and returns a detailed text description of its contents.'
+tools: [${READ_TOOL_NAME}]
+model: visionModel
+---
+
+You are an image recognition specialist. You run on a vision-capable model and your job is to look at image files and return detailed text descriptions of their contents.
+
+When given image file path(s):
+- Use the ${READ_TOOL_NAME} tool on each image path to load it. The ${READ_TOOL_NAME} tool returns the image as base64 image data that you can see directly.
+- Describe the image contents in detail: what is shown, any visible text (transcribe verbatim where relevant), layout, colors, objects, and anything else the caller asked about.
+- If an image cannot be read (file missing, not an image, or too large), report the error clearly and state which path failed.
+- Do not invent or guess content you cannot see — only describe what the image actually shows.
+- Return your description directly as a text message. Do NOT create files.
+- Avoid using emojis in your response.
+
+Complete the image recognition task and report your findings clearly.
+`,
+};

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./core/session.js";
 export * from "./services/authService.js";
+export * from "./services/worktreeHooks.js";
 export * from "./constants/tools.js";
 export * from "./agent.js";
 export * from "./core/plugin.js";
@@ -21,6 +22,7 @@ export * from "./utils/hookMatcher.js";
 export * from "./utils/tokenCalculation.js";
 export * from "./utils/gitUtils.js";
 export * from "./utils/nameGenerator.js";
+export * from "./utils/pathEncoder.js";
 export * from "./utils/worktreeSession.js";
 export * from "./utils/worktreeUtils.js";
 export { loadMergedWaveConfig, loadUserConfigEnv, } from "./services/configurationService.js";

package/dist/index.js

@@ -1,6 +1,7 @@
 // Export all services
 export * from "./core/session.js";
 export * from "./services/authService.js";
+export * from "./services/worktreeHooks.js";
 // Export constants
 export * from "./constants/tools.js";
 // Export main agent
@@ -25,6 +26,7 @@ export * from "./utils/hookMatcher.js";
 export * from "./utils/tokenCalculation.js";
 export * from "./utils/gitUtils.js";
 export * from "./utils/nameGenerator.js";
+export * from "./utils/pathEncoder.js";
 export * from "./utils/worktreeSession.js";
 export * from "./utils/worktreeUtils.js";
 export { loadMergedWaveConfig, loadUserConfigEnv, } from "./services/configurationService.js";

package/dist/managers/aiManager.d.ts

@@ -12,6 +12,15 @@ interface ForkLoopResult {
 }
 export interface AIManagerCallbacks {
     onCompactionStateChange?: (isCompacting: boolean) => void;
+    /**
+     * Streaming content from the compaction fork (accumulated, same semantics
+     * as `onContentUpdate` in CallAgentOptions). Reasoning chunks fall back to
+     * this channel when no reasoning callback is provided. Consumed by the CLI
+     * to show the compaction loading tail.
+     */
+    onCompactionContentUpdate?: (content: string) => void;
+    /** Streaming reasoning from the compaction fork (accumulated). */
+    onCompactionReasoningUpdate?: (content: string) => void;
     onUsageAdded?: (usage: Usage) => void;
     onCwdChange?: (newCwd: string) => void;
 }
@@ -59,6 +68,7 @@ export declare class AIManager {
     private get memoryService();
     private get taskManager();
     private get backgroundTaskManager();
+    private get asyncWorkRegistry();
     private get hookManager();
     private get reversionManager();
     private get permissionManager();

package/dist/managers/aiManager.js

@@ -1,6 +1,7 @@
 import * as aiService from "../services/aiService.js";
 import { convertMessagesForAPI } from "../utils/convertMessagesForAPI.js";
 import { supportsVision } from "../utils/modelCapabilities.js";
+import { persistToolImages } from "../utils/toolImagePersistence.js";
 import { parseTaskNotificationXml, taskNotificationToXml, } from "../utils/notificationXml.js";
 import { calculateComprehensiveTotalTokens } from "../utils/tokenCalculation.js";
 import { estimateTokens } from "../utils/tokenEstimate.js";
@@ -102,6 +103,9 @@ export class AIManager {
     get backgroundTaskManager() {
         return this.container.get("BackgroundTaskManager");
     }
+    get asyncWorkRegistry() {
+        return this.container.get("AsyncWorkRegistry");
+    }
     get hookManager() {
         return this.container.get("HookManager");
     }
@@ -430,7 +434,7 @@ export class AIManager {
             // 4. Fork path: fork the conversation with the same system prompt,
             // tools, model, and generation params as the main loop so the forked
             // request prefix matches exactly and the prompt cache is reused.
-            const forkResult = await this.runCompactFork(recentChatMessages, compactPrompt, options.abortSignal);
+            const forkResult = await this.runCompactFork(recentChatMessages, compactPrompt, options.abortSignal, this.callbacks?.onCompactionContentUpdate, this.callbacks?.onCompactionReasoningUpdate);
             const summaryContent = forkResult.content;
             const compactTokens = forkResult.usage;
             if (!summaryContent) {
@@ -452,6 +456,10 @@ export class AIManager {
             const enhancedSummary = await this.buildPostCompactContext(formattedSummary);
             // 8. Execute message reconstruction
             await this.messageManager.compactMessagesAndUpdateSession(enhancedSummary, compactUsage);
+            // Clear readFileState after compaction (aligned with Claude Code's
+            // compact flow): a file_unchanged stub would otherwise reference Read
+            // results that were just folded away. Clearing forces a real re-read.
+            this.readFileState.clear();
             // Re-add plan mode reminder as persistent meta message after compaction
             const postCompactMode = this.permissionManager?.getCurrentEffectiveMode(this.getModelConfig().permissionMode);
             if (postCompactMode === "plan") {
@@ -595,6 +603,25 @@ export class AIManager {
                 // gateway's idle timeout fires (non-streaming waits for the full
                 // response, which exceeds the timeout on large contexts).
                 stream: true,
+                // Surface partial output to the caller (e.g. the compaction loading
+                // tail) as it arrives. Reasoning chunks from thinking models go to
+                // the reasoning channel when the caller supplies one; otherwise they
+                // fall back to the content channel (CLI mixes both).
+                onContentUpdate: (content) => {
+                    if (content.trim()) {
+                        options.onContentUpdate?.(content);
+                    }
+                },
+                onReasoningUpdate: (reasoning) => {
+                    if (reasoning.trim()) {
+                        if (options.onReasoningUpdate) {
+                            options.onReasoningUpdate(reasoning);
+                        }
+                        else {
+                            options.onContentUpdate?.(reasoning);
+                        }
+                    }
+                },
             });
             if (result.usage) {
                 totalUsage = {
@@ -647,10 +674,12 @@ export class AIManager {
      * Fork-path compaction: deny all tool calls locally (the model is told to
      * summarize, not act) and feed the rejections back for another turn.
      */
-    async runCompactFork(historyMessages, compactPrompt, abortSignal) {
+    async runCompactFork(historyMessages, compactPrompt, abortSignal, onContentUpdate, onReasoningUpdate) {
         return this.runForkLoop(historyMessages, compactPrompt, {
             maxTurns: MAX_FORK_TURNS,
             deniedToolMessage: "Tool use is not allowed during compaction",
+            onContentUpdate,
+            onReasoningUpdate,
         }, abortSignal);
     }
     /**
@@ -806,8 +835,10 @@ export class AIManager {
             }
         };
         // Fire-and-forget: the fork runs to completion in the background; the
-        // caller gets the task ID immediately.
-        (async () => {
+        // caller gets the task ID immediately. Tracked in the async work registry
+        // so destroy() drains it before returning (abort via the task's onStop
+        // makes the loop settle).
+        const forkPromise = (async () => {
             try {
                 const result = await this.runForkLoop(historyMessages, prompt, {
                     // /subtask aligns with Claude Code's fork subagent
@@ -854,6 +885,7 @@ export class AIManager {
                 abortCleanup?.();
             }
         })();
+        this.asyncWorkRegistry?.track(forkPromise);
         return taskId;
     }
     /**
@@ -1904,6 +1936,18 @@ ${question}`;
             };
             // Execute tool
             const toolResult = await this.toolManager.execute(functionToolCall.function?.name || "", toolArgs, context);
+            // MCP tools can return images (e.g. Figma screenshots) as in-memory
+            // base64. When this agent's model cannot see them, persist each image to
+            // a temp file so the non-vision path in convertMessagesForAPI can attach
+            // `[Image source: <path>]` metadata and the main model can delegate
+            // recognition to the vision subagent. Vision-capable models keep the
+            // inline base64 — no disk writes.
+            let toolImages = toolResult.images;
+            if (toolImages &&
+                toolImages.length > 0 &&
+                !supportsVision(this.getModelConfig().capabilities)) {
+                toolImages = persistToolImages(toolImages);
+            }
             // Build result content, adding truncation warning if JSON was recovered
             let toolResultContent = toolResult.content ||
                 (toolResult.error ? `Error: ${toolResult.error}` : "");
@@ -1926,7 +1970,7 @@ ${question}`;
                 backgroundedByUser: toolResult.backgroundedByUser,
                 assistantAutoBackgrounded: toolResult.assistantAutoBackgrounded,
                 startLineNumber: toolResult.startLineNumber,
-                images: toolResult.images,
+                images: toolImages,
                 timestamp: Date.now(),
             });
             // Execute PostToolUse hooks after successful tool completion

package/dist/managers/mcpManager.js

@@ -656,7 +656,7 @@ export class McpManager {
                     else if (c.type === "image" && c.data) {
                         images.push({
                             data: c.data,
-                            mediaType: "image/png", // Default to PNG
+                            mediaType: c.mimeType || "image/png", // MCP standard mimeType, PNG fallback
                         });
                     }
                     else if (c.type === "resource") {

package/dist/managers/messageManager.d.ts

@@ -222,6 +222,12 @@ export declare class MessageManager {
      * Extract file read contents from tool result blocks in a message.
      */
     private extractFileReadsFromMessage;
+    /**
+     * Bound recentFileReads growth: evict oldest entries beyond the cache limit
+     * and drop content from all but the most recent entries (paths are kept for
+     * hasFileBeenRead). Prevents unbounded memory growth in long sessions.
+     */
+    private trimRecentFileReads;
     /**
      * Get recent file read contents, sorted by timestamp (newest first).
      * @param maxFiles - Maximum number of files to return

package/dist/managers/messageManager.js

@@ -5,6 +5,13 @@ import { appendMessages, createSession, generateSessionId, SESSION_DIR, } from "
 import { pathEncoder } from "../utils/pathEncoder.js";
 import { estimateTokens } from "../utils/tokenEstimate.js";
 import { READ_TOOL_NAME } from "../constants/tools.js";
+// Cap for recentFileReads: content is only consumed by getRecentFileReads
+// (top 5 for post-compact restoration), so bound both the entry count and the
+// number of entries that keep full content (aligned with Claude Code's
+// FileStateCache 100-entry limit). Paths beyond the content cap are kept so
+// hasFileBeenRead still works for read-before-edit enforcement.
+const RECENT_FILE_READS_CACHE_LIMIT = 100;
+const RECENT_FILE_READS_CONTENT_LIMIT = 10;
 import { logger } from "../utils/globalLogger.js";
 export class MessageManager {
     constructor(container, options) {
@@ -397,6 +404,8 @@ export class MessageManager {
         // Update in-memory state
         this.setMessages(newMessages);
         this.savedMessageCount = newMessages.length;
+        // Trim recent file read cache so contents compacted away are released
+        this.trimRecentFileReads();
         // Clear and rebuild loaded rule IDs from remaining meta messages
         this.clearLoadedRuleIds();
         this.rebuildLoadedRuleIds();
@@ -779,10 +788,34 @@ export class MessageManager {
                         content: block.result,
                         timestamp: Date.now(),
                     });
+                    this.trimRecentFileReads();
                 }
             }
         }
     }
+    /**
+     * Bound recentFileReads growth: evict oldest entries beyond the cache limit
+     * and drop content from all but the most recent entries (paths are kept for
+     * hasFileBeenRead). Prevents unbounded memory growth in long sessions.
+     */
+    trimRecentFileReads() {
+        if (this.recentFileReads.size > RECENT_FILE_READS_CACHE_LIMIT) {
+            const sortedAsc = Array.from(this.recentFileReads.entries()).sort(([, a], [, b]) => a.timestamp - b.timestamp);
+            const excess = this.recentFileReads.size - RECENT_FILE_READS_CACHE_LIMIT;
+            for (const [path] of sortedAsc.slice(0, excess)) {
+                this.recentFileReads.delete(path);
+            }
+        }
+        if (this.recentFileReads.size > RECENT_FILE_READS_CONTENT_LIMIT) {
+            const sortedDesc = Array.from(this.recentFileReads.entries()).sort(([, a], [, b]) => b.timestamp - a.timestamp);
+            for (const [path, entry] of sortedDesc.slice(RECENT_FILE_READS_CONTENT_LIMIT)) {
+                this.recentFileReads.set(path, {
+                    content: "",
+                    timestamp: entry.timestamp,
+                });
+            }
+        }
+    }
     /**
      * Get recent file read contents, sorted by timestamp (newest first).
      * @param maxFiles - Maximum number of files to return

package/dist/managers/subagentManager.d.ts

@@ -75,6 +75,7 @@ export declare class SubagentManager {
     private stream;
     constructor(container: Container, options: SubagentManagerOptions);
     private get configurationService();
+    private get asyncWorkRegistry();
     /**
      * Initialize the SubagentManager by loading and caching configurations
      */
@@ -150,6 +151,14 @@ export declare class SubagentManager {
      * Clean up completed, errored, or aborted instances
      */
     cleanupInstance(subagentId: string): void;
+    /**
+     * Release a subagent instance so its graph (message history, file-read
+     * caches, log stream) can be garbage-collected. Besides removing the
+     * instance from the map, this drops the background task's onStop closure,
+     * which captures the instance and would otherwise keep the whole graph
+     * alive for the rest of the session.
+     */
+    private releaseInstance;
     /**
      * Get all active instances
      */

package/dist/managers/subagentManager.js

@@ -23,6 +23,9 @@ export class SubagentManager {
     get configurationService() {
         return this.container.get("ConfigurationService");
     }
+    get asyncWorkRegistry() {
+        return this.container.get("AsyncWorkRegistry");
+    }
     /**
      * Initialize the SubagentManager by loading and caching configurations
      */
@@ -171,6 +174,16 @@ export class SubagentManager {
         // Without this, concurrent background subagents steal sibling completion
         // notifications from the parent queue, causing the main agent to exit early.
         subagentContainer.register("MessageQueue", new MessageQueue());
+        // Deliberately shadow the parent ReversionManager with `undefined` so the
+        // subagent resolves no reversion manager instead of falling back to the
+        // parent's. Subagent Write/Edit must not be recorded into the main agent's
+        // file_history buffer — this mirrors Claude Code's explicit isolation for
+        // forked agents (`updateFileHistoryState: () => {}` in forkedAgent.ts).
+        // Without this, the subagent drains the SHARED parent buffer into its own
+        // transient messages (discarded on cleanup), leaving orphaned snapshot
+        // files on disk and racing the main agent's own drain. All ReversionManager
+        // consumers are truthiness-guarded, so resolving to `undefined` is safe.
+        subagentContainer.register("ReversionManager", undefined);
         // Register a modified AgentOptions without onLoadingChange to prevent subagent loading
         // from affecting the parent agent's loading state
         const parentOptions = this.container.get("AgentOptions");
@@ -321,7 +334,7 @@ export class SubagentManager {
                 instance.backgroundTaskId = taskId;
                 // Execute in background
                 // Note: notification enqueueing is handled by internalExecute when instance.backgroundTaskId is set
-                (async () => {
+                const backgroundPromise = (async () => {
                     try {
                         const result = await this.internalExecute(instance, prompt, abortSignal);
                         const task = backgroundTaskManager?.getTask(taskId);
@@ -342,13 +355,30 @@ export class SubagentManager {
                             task.runtime = task.endTime - startTime;
                         }
                     }
+                    finally {
+                        // Free the instance once the background task finishes: without
+                        // this the instance (message history, caches) would linger in the
+                        // map for the whole session, and the task's onStop closure would
+                        // keep it alive even after that.
+                        this.releaseInstance(instance.subagentId);
+                    }
                 })();
+                this.asyncWorkRegistry?.track(backgroundPromise);
                 return taskId;
             }
-            return await this.internalExecute(instance, prompt, abortSignal);
+            const result = await this.internalExecute(instance, prompt, abortSignal);
+            // Free the instance once the subagent finishes. Callers that still hold
+            // the reference can read its messageManager, but the map entry and the
+            // background task's onStop closure are released so the message history
+            // and caches can be garbage-collected.
+            this.releaseInstance(instance.subagentId);
+            return result;
         }
         catch (error) {
             this.updateInstanceStatus(instance.subagentId, "error");
+            // Release on failure too so errored instances don't linger for the
+            // session (the abort listener already releases on abort).
+            this.releaseInstance(instance.subagentId);
             throw error;
         }
     }
@@ -543,8 +573,37 @@ export class SubagentManager {
             (instance.status === "completed" ||
                 instance.status === "error" ||
                 instance.status === "aborted")) {
-            this.instances.delete(subagentId);
+            this.releaseInstance(subagentId);
+        }
+    }
+    /**
+     * Release a subagent instance so its graph (message history, file-read
+     * caches, log stream) can be garbage-collected. Besides removing the
+     * instance from the map, this drops the background task's onStop closure,
+     * which captures the instance and would otherwise keep the whole graph
+     * alive for the rest of the session.
+     */
+    releaseInstance(subagentId) {
+        const instance = this.instances.get(subagentId);
+        if (!instance) {
+            return;
+        }
+        if (instance.backgroundTaskId) {
+            const backgroundTaskManager = this.container.has("BackgroundTaskManager")
+                ? this.container.get("BackgroundTaskManager")
+                : undefined;
+            const task = backgroundTaskManager?.getTask(instance.backgroundTaskId);
+            if (task) {
+                task.onStop = undefined;
+            }
+        }
+        if (instance.logStream && !instance.logStream.writableEnded) {
+            // Only force-close a stream that hasn't been ended yet (the completion
+            // and error paths already call end(); destroy would drop buffered data).
+            instance.logStream.destroy();
         }
+        instance.logStream = undefined;
+        this.instances.delete(subagentId);
     }
     /**
      * Get all active instances