wave-agent-sdk 1.0.10 → 1.1.1

package/dist/agent.d.ts

@@ -1,6 +1,6 @@
 import { type QueuedMessage } from "./managers/messageQueue.js";
 import { SlashCommand, CustomSlashCommand, AgentOptions } from "./types/index.js";
-import type { Message, McpServerStatus, GatewayConfig, ModelConfig, Usage, PermissionMode, ForegroundTask } from "./types/index.js";
+import type { Message, McpServerStatus, GatewayConfig, ModelConfig, Usage, PermissionMode, ForegroundTask, SkillMetadata } from "./types/index.js";
 import type { WorktreeSession } from "./utils/worktreeSession.js";
 export declare class Agent {
     private messageManager;
@@ -23,7 +23,9 @@ export declare class Agent {
     private messageQueue;
     private dispatchPromise;
     private isAborting;
+    private isDestroyed;
     private dispatchAborted;
+    private asyncWorkRegistry;
     private memoryRuleManager;
     private liveConfigManager;
     private taskManager;
@@ -122,6 +124,13 @@ export declare class Agent {
         }>;
         type?: "message" | "bang";
     }): boolean;
+    /**
+     * Terminal-lifecycle guard for public APIs. destroy() is terminal: after it
+     * returns, no new work may start on this agent. Silent drops hid misuse until
+     * a ghost async side effect surfaced later (issue #1808); throwing surfaces
+     * the contract violation immediately at the call site.
+     */
+    private assertNotDestroyed;
     /**
      * Unified dispatch trigger — checks state machine before processing.
      * Handles user messages, bang commands, and background task notifications
@@ -244,12 +253,6 @@ export declare class Agent {
      * Background the current foreground task
      */
     backgroundCurrentTask(): Promise<void>;
-    /**
-     * Trigger WorktreeRemove hook before agent destruction.
-     * Called from CLI exit dialog when user chooses to remove the worktree.
-     * Non-blocking: errors logged but don't prevent removal.
-     */
-    triggerWorktreeRemoveHook(worktreePath: string): Promise<void>;
     /** Destroy managers, clean up resources */
     destroy(): Promise<void>;
     /**
@@ -419,6 +422,12 @@ export declare class Agent {
      * @returns The list of subagent configurations
      */
     getSubagentConfigurations(): import("./utils/subagentParser.js").SubagentConfiguration[];
+    /**
+     * Get all skill metadata visible in this session (builtin, personal,
+     * project, and plugin skills).
+     * @returns The list of skill metadata
+     */
+    getSkillMetadata(): SkillMetadata[];
     /**
      * Get currently active subagent instances (status active/initializing).
      * @returns The list of active subagent instances

package/dist/agent.js

@@ -18,7 +18,7 @@ export class Agent {
         };
     }
     getModelConfig() {
-        return this.configurationService.resolveModelConfig(undefined, undefined, undefined, this.getPermissionMode());
+        return this.configurationService.resolveModelConfig(undefined, undefined, this.getPermissionMode());
     }
     getMaxInputTokens() {
         return this.configurationService.resolveMaxInputTokens();
@@ -53,7 +53,8 @@ export class Agent {
     constructor(options) {
         this.bangManager = null;
         this.dispatchPromise = null; // Track current dispatch for teardown
-        this.isAborting = false; // Guard: prevents tryDispatch from firing during abortMessage
+        this.isAborting = false; // Transient guard: prevents tryDispatch from firing during abortMessage (reset when the abort completes)
+        this.isDestroyed = false; // Terminal guard: set in destroy(), never reset — no dispatch may ever start after destroy
         this.dispatchAborted = false; // Set on abort while a dispatch is running: suppress the .finally re-check so preserved notifications don't get dispatched after abort
         this.sessionStartTime = Date.now();
         const { logger, workdir, systemPrompt, stream = true } = options;
@@ -113,6 +114,7 @@ export class Agent {
         this.bangManager = this.container.get("BangManager");
         this.cronManager = this.container.get("CronManager");
         this.messageQueue = this.container.get("MessageQueue");
+        this.asyncWorkRegistry = this.container.get("AsyncWorkRegistry");
         // Wire up CWD change callback from AIManager to sync Agent's workdir
         this.aiManager.setOnCwdChange((newCwd) => {
             this.workdir = newCwd;
@@ -256,6 +258,17 @@ export class Agent {
         }
         return updated;
     }
+    /**
+     * Terminal-lifecycle guard for public APIs. destroy() is terminal: after it
+     * returns, no new work may start on this agent. Silent drops hid misuse until
+     * a ghost async side effect surfaced later (issue #1808); throwing surfaces
+     * the contract violation immediately at the call site.
+     */
+    assertNotDestroyed() {
+        if (this.isDestroyed) {
+            throw new Error("Agent destroyed");
+        }
+    }
     /**
      * Unified dispatch trigger — checks state machine before processing.
      * Handles user messages, bang commands, and background task notifications
@@ -263,6 +276,8 @@ export class Agent {
      * onLoadingChange(false), and onCommandRunningChange(false).
      */
     tryDispatch() {
+        if (this.isDestroyed)
+            return; // Terminal: agent destroyed, never dispatch again
         if (this.isAborting)
             return; // Suppress dispatch during abort to prevent queued notifications from being dispatched as a side-effect
         if (this.dispatchAborted)
@@ -274,7 +289,7 @@ export class Agent {
         if (this.aiManager.isLoading || this.isCommandRunning)
             return;
         this.messageQueue.transitionTo("dispatching");
-        this.dispatchPromise = this.processQueuedMessage()
+        this.dispatchPromise = this.asyncWorkRegistry.track(this.processQueuedMessage()
             .catch((error) => {
             this.logger?.error("Failed to process queued message:", error);
         })
@@ -285,7 +300,7 @@ export class Agent {
                 this.tryDispatch(); // Re-check after processing
             }
             this.dispatchAborted = false;
-        });
+        }));
     }
     /**
      * Process the next queued item when the agent becomes idle.
@@ -499,6 +514,7 @@ export class Agent {
     }
     /** Execute bash command (bang command) */
     async bang(command) {
+        this.assertNotDestroyed();
         // If the agent is busy, enqueue the bang command
         if (this.aiManager.isLoading || this.isCommandRunning) {
             this.messageQueue.enqueue({ type: "bang", content: command });
@@ -625,37 +641,14 @@ export class Agent {
         await this.foregroundTaskManager.backgroundCurrentTask();
         this.options.callbacks?.onBackgroundCurrentTask?.();
     }
-    /**
-     * Trigger WorktreeRemove hook before agent destruction.
-     * Called from CLI exit dialog when user chooses to remove the worktree.
-     * Non-blocking: errors logged but don't prevent removal.
-     */
-    async triggerWorktreeRemoveHook(worktreePath) {
-        if (!this.hookManager.hasHooks("WorktreeRemove")) {
-            return;
-        }
-        try {
-            const sessionId = this.messageManager.getSessionId();
-            const transcriptPath = this.messageManager.getTranscriptPath();
-            const hookResults = await this.hookManager.executeHooks("WorktreeRemove", {
-                event: "WorktreeRemove",
-                projectDir: this.workdir,
-                timestamp: new Date(),
-                sessionId,
-                transcriptPath,
-                cwd: this.workdir,
-                worktreePath,
-                env: Object.fromEntries(Object.entries(this.configurationService.getMergedEnv()).filter((e) => e[1] !== undefined)),
-            });
-            // Process results via messageManager (may not be visible during shutdown)
-            this.hookManager.processHookResults("WorktreeRemove", hookResults, this.messageManager);
-        }
-        catch (error) {
-            this.logger?.warn("WorktreeRemove hooks execution failed:", error);
-        }
-    }
     /** Destroy managers, clean up resources */
     async destroy() {
+        // Terminal guard: suppress any dispatch triggered during teardown (e.g. the
+        // onLoadingChange(false) fired by abortAIMessage() below, or the dispatch
+        // .finally re-check). Without this, leftover queued messages would be
+        // dispatched fire-and-forget and outlive the agent. Never reset: destroy()
+        // is terminal, no dispatch should ever start afterwards.
+        this.isDestroyed = true;
         // Log session_end event and shutdown telemetry
         await logOTelEvent("session_end", {
             duration: String(Math.round((Date.now() - this.sessionStartTime) / 1000)),
@@ -717,7 +710,13 @@ export class Agent {
         }
         // Cleanup remote settings polling
         remoteSettingsService.shutdown();
-        // Cleanup memory store
+        // Drain live async work (dispatch, background subagents, fork subagents):
+        // abort steps above make them settle; wait for them so no async side
+        // effect outlives the agent. Timeout fallback keeps destroy bounded.
+        const drained = await this.asyncWorkRegistry.drain();
+        if (!drained) {
+            this.logger?.error(`Async work did not drain: ${this.asyncWorkRegistry.size} live work item(s) remain after destroy`);
+        }
     }
     /**
      * Trigger the rewind UI callback
@@ -738,6 +737,7 @@ export class Agent {
      * @returns Promise that resolves to the AI's answer
      */
     async askBtw(question, abortSignal, onContent, onReasoning) {
+        this.assertNotDestroyed();
         const result = await this.aiManager.runBtwFork(question, abortSignal, onContent, onReasoning);
         return result.content ?? result.error ?? "No response received";
     }
@@ -760,6 +760,7 @@ export class Agent {
      * @returns Promise that resolves to the background task ID
      */
     async forkSubagent(prompt, options, abortSignal) {
+        this.assertNotDestroyed();
         return this.aiManager.runForkSubagent(prompt, options, abortSignal);
     }
     /**
@@ -789,6 +790,7 @@ export class Agent {
      * ```
      */
     async sendMessage(content, images) {
+        this.assertNotDestroyed();
         // If the agent is busy, enqueue the message — unless it's an immediate
         // slash command (e.g., /clear, /compact) that should execute
         // right away even while AI is processing
@@ -981,6 +983,14 @@ export class Agent {
     getSubagentConfigurations() {
         return this.subagentManager.getConfigurations();
     }
+    /**
+     * Get all skill metadata visible in this session (builtin, personal,
+     * project, and plugin skills).
+     * @returns The list of skill metadata
+     */
+    getSkillMetadata() {
+        return this.skillManager.getAvailableSkills();
+    }
     /**
      * Get currently active subagent instances (status active/initializing).
      * @returns The list of active subagent instances

package/dist/builtin/skills/settings.js

@@ -29,7 +29,7 @@ Wave uses several environment variables to control its core functionality. Varia
 | \`WAVE_MODEL\` | The primary AI model to use for the agent. | \`gemini-3-flash\` |
 | \`WAVE_FAST_MODEL\` | The fast AI model to use for quick tasks. | \`gemini-2.5-flash\` |
 | \`WAVE_VISION_MODEL\` | Vision-capable model used by the built-in \`vision\` subagent for image recognition. When set, the built-in \`vision\` subagent is registered (its frontmatter \`model: visionModel\` resolves to this value); when unset, the subagent is not loaded. Useful when the main model is fast but non-vision (e.g. DeepSeek). | - (not registered) |
-| \`WAVE_MAX_INPUT_TOKENS\` | Maximum number of input tokens allowed. | \`200000\` |
+| \`WAVE_MAX_INPUT_TOKENS\` | Maximum number of input tokens allowed. Overridden per-model by \`models[<model>].maxInputTokens\`. | \`200000\` |
 | \`WAVE_MAX_OUTPUT_TOKENS\` | Maximum number of output tokens allowed. | \`32000\` |
 | \`WAVE_DISABLE_AUTO_MEMORY\` | Set to \`1\` or \`true\` to disable the auto-memory feature. | \`false\` |
 | \`WAVE_AUTO_MEMORY_FREQUENCY\` | Auto memory update frequency. \`1\` = every turn, \`2\` = every 2 turns, etc. | \`1\` |
@@ -92,8 +92,8 @@ Wave supports the following hook events:
 - \`PermissionRequest\`: Triggered when Wave requests permission to use a tool.
 - \`Stop\`: Triggered when Wave finishes its response cycle (no more tool calls).
 - \`SubagentStop\`: Triggered when a subagent finishes its response cycle.
-- \`WorktreeCreate\`: Triggered when a new worktree is created.
-- \`WorktreeRemove\`: Triggered before a worktree is removed (e.g., via ExitWorktree with \`action: "remove"\`). Non-blocking. Fires **before** the worktree directory is deleted so hooks can still read files inside it. The hook receives \`worktree_path\` in the JSON input. Useful for cleanup tasks (e.g., \`docker compose -p $(basename "$worktree_path") down\`).
+- \`WorktreeCreate\`: Triggered to create a new worktree, replacing \`git worktree add\`. The hook performs the creation itself (e.g., \`git worktree add\`, or any other VCS/external provisioning) and must output the worktree's absolute path on stdout (path return). Creation is blocked if all hooks fail or produce no output. Receives \`name\` in the JSON input. The resulting session is marked "hook-based".
+- \`WorktreeRemove\`: Triggered when a hook-based worktree (created by a \`WorktreeCreate\` hook) is removed (e.g., via ExitWorktree with \`action: "remove"\`), replacing \`git worktree remove\` for that worktree: the hook performs the removal itself (e.g., \`git worktree remove --force\` plus external resource cleanup). Fires **before** the worktree directory is deleted so hooks can still read files inside it. Receives \`worktree_path\` in the JSON input. Failures are logged but non-blocking. Git-created worktrees are removed by git directly and do not trigger this hook.
 - \`CwdChanged\`: Triggered when the working directory changes (e.g., entering/exiting a worktree). Non-blocking.
 - \`SessionStart\`: Triggered during session initialization. Hooks can inject \`additionalContext\` and \`initialUserMessage\` via stdout.
 - \`SessionEnd\`: Triggered during agent destruction (fire-and-forget, non-blocking). Useful for cleanup, resource teardown, and analytics.
@@ -245,9 +245,34 @@ SessionEnd hooks receive \`end_source\` in the JSON input indicating how the ses
 }
 \`\`\`
 
+## WorktreeCreate Hooks
+
+\`WorktreeCreate\` hooks replace \`git worktree add\`: when configured, Wave does not create the worktree itself — the hook does. The hook must output the worktree's absolute path on **stdout** (the first successful hook's trimmed stdout is used as the path). All hooks failing or producing no output blocks the creation with \`WorktreeCreate hook failed: ...\`. The resulting session is marked "hook-based" and skips Wave's post-creation setup (\`settings.local.json\` / \`.worktreeinclude\` propagation) — the hook is responsible for any initialization.
+
+### Input
+WorktreeCreate hooks receive \`name\` (the worktree name) in the JSON input, alongside the common fields \`session_id\`, \`transcript_path\`, \`cwd\`, \`hook_event_name\`.
+
+### Example Configuration
+\`\`\`json
+{
+  "hooks": {
+    "WorktreeCreate": [
+      {
+        "hooks": [
+          {
+            "command": "worktree_path=\\"$WAVE_PROJECT_DIR/.wave/worktrees/$(jq -r '.name')\\" && mkdir -p \\"$worktree_path\\" && git worktree add \\"$worktree_path\\" 2>/dev/null; echo \\"$worktree_path\\"",
+            "description": "Create the worktree and print its path"
+          }
+        ]
+      }
+    ]
+  }
+}
+\`\`\`
+
 ## WorktreeRemove Hooks
 
-\`WorktreeRemove\` hooks fire **before** the worktree directory is deleted, so they can still read files inside it. They are non-blocking (Notification type): the hook never replaces \`git worktree remove\` itself. Useful for cleaning up external resources that were provisioned for the worktree (databases, containers, etc.).
+\`WorktreeRemove\` hooks replace \`git worktree remove\` for **hook-based** worktrees (those created by a \`WorktreeCreate\` hook). When a hook-based worktree is removed from any entry point (CLI exit, ExitWorktree tool, \`wave -p\`, stdio RPC), Wave calls the hook instead of running \`git worktree remove\` — the hook performs the actual removal, so it can clean up external resources it provisioned (databases, containers, etc.) at the same time. Hooks fire **before** the worktree directory is deleted, so they can still read files inside it. Failures are logged but non-blocking. If no \`WorktreeRemove\` hook is configured for a hook-based worktree, Wave logs a warning and leaves the worktree in place. Git-created worktrees (no \`WorktreeCreate\` hook) are removed by git directly and do **not** trigger this hook.
 
 ### Input
 WorktreeRemove hooks receive \`worktree_path\` in the JSON input (alongside the common fields \`session_id\`, \`transcript_path\`, \`cwd\`, \`hook_event_name\`). The worktree name can be derived via \`basename "$worktree_path"\`.
@@ -260,8 +285,8 @@ WorktreeRemove hooks receive \`worktree_path\` in the JSON input (alongside the
       {
         "hooks": [
           {
-            "command": "worktree_path=$(jq -r '.worktree_path') && docker compose -p \\"$(basename \\"$worktree_path\\")\\" down || true",
-            "description": "Tear down the worktree's docker compose project before removal"
+            "command": "worktree_path=$(jq -r '.worktree_path') && git worktree remove --force \\"$worktree_path\\" && docker compose -p \\"$(basename \\"$worktree_path\\")\\" down",
+            "description": "Remove the worktree and tear down its docker compose project"
           }
         ]
       }
@@ -297,7 +322,7 @@ When hooks are registered via a **plugin**, Wave automatically:
 }
 \`\`\`
 
-The shell also receives \`WAVE_PLUGIN_ROOT\` as an env var, so \`$WAVE_PLUGIN_ROOT\` works in the hook script itself.
+The shell also receives \`WAVE_PLUGIN_ROOT\` as an env var, so \`$WAVE_PLUGIN_ROOT\` works in the hook script itself. For \`WorktreeCreate\`, the script must print the created worktree's absolute path to stdout.
 
 ## Best Practices
 
@@ -560,12 +585,27 @@ You can define overrides for specific models in the \`models\` field. The key sh
 Generation parameters are nested under the \`options\` field within each model's configuration. Wave supports passing arbitrary parameters to the underlying AI provider. Common parameters include:
 
 - \`temperature\`: Controls randomness (0.0 to 2.0).
-- \`maxTokens\`: Maximum number of tokens to generate in the response.
+- \`max_tokens\`: Maximum number of tokens to generate in the response.
 - \`reasoning_effort\`: (OpenAI specific) Controls the reasoning effort for models like \`o1\` and \`o3-mini\`. Values: \`low\`, \`medium\`, \`high\`.
 - \`thinking\`: (Claude specific) Configures the thinking/reasoning capabilities for Claude 3.7+ models.
   - \`type\`: \`"enabled"\` or \`"disabled"\`.
   - \`budget_tokens\`: Maximum tokens to use for thinking.
 
+## Per-Model Input Context Window
+
+Set \`maxInputTokens\` at the top level of a model entry (not inside \`options\`) to define that model's input context window. It overrides the global \`WAVE_MAX_INPUT_TOKENS\`, so compaction thresholds and usage display follow each model's own value:
+
+\`\`\`json
+{
+  "models": {
+    "deepseek-v4-flash": { "maxInputTokens": 200000 },
+    "kimi-k3": { "maxInputTokens": 131072 }
+  }
+}
+\`\`\`
+
+Resolution priority: constructor > \`options\` > \`models[<model>].maxInputTokens\` > \`WAVE_MAX_INPUT_TOKENS\` > default. Subagents (\`fastModel\`/\`visionModel\`) resolve against the model they actually use.
+
 ## Model Capabilities
 
 Wave needs to know whether a model supports certain features. Instead of guessing from the model name, you declare these explicitly via the \`capabilities\` field. Note that \`capabilities\` is set at the top level of the model configuration, **not** inside the \`options\` field — \`options\` is reserved for generation parameters only.

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();
@@ -123,7 +133,19 @@ export declare class AIManager {
     setIsLoading(isLoading: boolean): void;
     abortAIMessage(): void;
     private generateCompactParams;
-    private handleTokenUsageAndCompaction;
+    private updateLatestTotalTokens;
+    /**
+     * Pre-request auto-compaction check (aligned with Claude Code's
+     * autoCompactIfNeeded). Runs before every API request is issued: estimates
+     * the context that is about to be sent (last response's total_tokens plus
+     * character estimates for newer messages) and compacts first when it
+     * exceeds maxInputTokens, so over-limit requests are never sent. Only
+     * total_tokens is used — under OpenAI-compatible usage it already includes
+     * cache hits; adding cache fields would double-count and fire early.
+     * Fork paths (compaction / auto-memory) never reach here: they run in
+     * runForkLoop, not sendAIMessage.
+     */
+    private maybeAutoCompactBeforeRequest;
     /**
      * Manually compact the conversation history.
      * Called by /compact slash command or auto-compaction trigger.

package/dist/managers/aiManager.js

@@ -3,7 +3,7 @@ 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 { calculateComprehensiveTotalTokens, estimateContextTokens, } from "../utils/tokenCalculation.js";
 import { estimateTokens } from "../utils/tokenEstimate.js";
 import { getTaskReminderTurnCounts, maybeInjectTaskReminder, TASK_REMINDER_CONFIG, } from "../utils/taskReminder.js";
 import { createWriteStream, existsSync } from "node:fs";
@@ -103,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");
     }
@@ -141,7 +144,7 @@ export class AIManager {
         const permissionMode = this.container.has("PermissionMode")
             ? this.container.get("PermissionMode")
             : undefined;
-        const parentModelConfig = this.configurationService.resolveModelConfig(undefined, undefined, undefined, permissionMode);
+        const parentModelConfig = this.configurationService.resolveModelConfig(undefined, undefined, permissionMode);
         let modelToUse;
         if (this.modelOverride) {
             if (this.modelOverride === "fastModel") {
@@ -154,10 +157,13 @@ export class AIManager {
                 modelToUse = this.modelOverride;
             }
         }
-        return this.configurationService.resolveModelConfig(modelToUse, undefined, undefined, permissionMode);
+        return this.configurationService.resolveModelConfig(modelToUse, undefined, permissionMode);
     }
     getMaxInputTokens() {
-        return this.configurationService.resolveMaxInputTokens();
+        // Pass the resolved model (including fastModel/visionModel/override
+        // resolution) so subagents using a different model get that model's
+        // per-model maxInputTokens instead of the main model's value.
+        return this.configurationService.resolveMaxInputTokens(undefined, this.getModelConfig().model);
     }
     getLanguage() {
         return this.configurationService.resolveLanguage();
@@ -363,30 +369,43 @@ export class AIManager {
         }
         return "";
     }
-    // Private method to handle token statistics and message compaction
-    async handleTokenUsageAndCompaction(usage, abortController) {
+    // Private method to update the displayed token statistics from a response.
+    // The comprehensive value (including cache tokens) is intentionally kept:
+    // it drives cost/usage display. Auto-compaction is NOT decided here — it
+    // happens pre-request via maybeAutoCompactBeforeRequest so that over-limit
+    // requests never go out (aligned with Claude Code's proactive autocompact).
+    updateLatestTotalTokens(usage) {
         if (!usage)
             return;
         // Update token statistics - display comprehensive token usage including cache tokens
         const comprehensiveTotalTokens = calculateComprehensiveTotalTokens(usage);
         this.messageManager.setlatestTotalTokens(comprehensiveTotalTokens);
-        // Check if token limit exceeded - use injected configuration
-        if (usage.total_tokens +
-            (usage.cache_read_input_tokens || 0) +
-            (usage.cache_creation_input_tokens || 0) >
-            this.getMaxInputTokens()) {
-            logger?.debug(`Token usage exceeded ${this.getMaxInputTokens()}, compacting messages...`);
-            const messagesToCompact = this.messageManager.getMessages();
-            if (messagesToCompact.length === 0)
-                return;
-            // Circuit breaker: skip compaction after 3 consecutive failures
-            if (this.consecutiveCompactionFailures >= 3) {
-                logger?.warn(`Skipping compaction: ${this.consecutiveCompactionFailures} consecutive failures`);
-                return;
-            }
-            await this.compactConversation({
-                abortSignal: abortController.signal,
-            });
+    }
+    /**
+     * Pre-request auto-compaction check (aligned with Claude Code's
+     * autoCompactIfNeeded). Runs before every API request is issued: estimates
+     * the context that is about to be sent (last response's total_tokens plus
+     * character estimates for newer messages) and compacts first when it
+     * exceeds maxInputTokens, so over-limit requests are never sent. Only
+     * total_tokens is used — under OpenAI-compatible usage it already includes
+     * cache hits; adding cache fields would double-count and fire early.
+     * Fork paths (compaction / auto-memory) never reach here: they run in
+     * runForkLoop, not sendAIMessage.
+     */
+    async maybeAutoCompactBeforeRequest(abortController) {
+        // Circuit breaker: skip compaction after 3 consecutive failures
+        if (this.consecutiveCompactionFailures >= 3) {
+            logger?.warn(`Skipping compaction: ${this.consecutiveCompactionFailures} consecutive failures`);
+            return;
+        }
+        const messages = this.messageManager.getMessages();
+        if (messages.length === 0)
+            return;
+        const maxTokens = this.getMaxInputTokens();
+        const estimatedTokens = estimateContextTokens(messages);
+        if (estimatedTokens > maxTokens) {
+            logger?.debug(`Estimated context tokens ${estimatedTokens} exceeded ${maxTokens}, compacting before request...`);
+            await this.compactConversation({ abortSignal: abortController.signal });
         }
     }
     /**
@@ -431,7 +450,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) {
@@ -595,11 +614,31 @@ export class AIManager {
                 workdir,
                 tools: toolsConfig,
                 systemPrompt,
+                maxTokens: this.configurationService.resolveMaxOutputTokens(),
                 toolChoice: this.toolChoiceOverride,
                 // Stream so a slow reasoning model emits first bytes before the
                 // 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 = {
@@ -652,10 +691,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);
     }
     /**
@@ -811,8 +852,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
@@ -859,6 +902,7 @@ export class AIManager {
                 abortCleanup?.();
             }
         })();
+        this.asyncWorkRegistry?.track(forkPromise);
         return taskId;
     }
     /**
@@ -1002,6 +1046,7 @@ ${question}`;
                 workdir,
                 tools: toolsConfig,
                 systemPrompt,
+                maxTokens: this.configurationService.resolveMaxOutputTokens(),
                 toolChoice: this.toolChoiceOverride,
                 // Stream so a slow reasoning model emits first bytes before the
                 // gateway's idle timeout fires (same rationale as runCompactFork).
@@ -1254,6 +1299,10 @@ ${question}`;
                             isMeta: true,
                         });
                     }
+                    // Pre-request auto-compaction: estimate the context about to be sent
+                    // and compact BEFORE issuing the request, so an over-limit request
+                    // never goes out. Skipped on fork paths (they use runForkLoop).
+                    await this.maybeAutoCompactBeforeRequest(abortController);
                     // Get recent message history
                     const rawMessages = this.messageManager.getMessages();
                     const currentModelConfig = this.getModelConfig();
@@ -1278,7 +1327,7 @@ ${question}`;
                         tools: toolsConfig, // Pass filtered tool configuration
                         model: model, // Use passed model
                         systemPrompt: mainSystemPrompt, // Pass custom system prompt
-                        maxTokens: maxTokens, // Pass max tokens override
+                        maxTokens: maxTokens ?? this.configurationService.resolveMaxOutputTokens(), // Pass max tokens override, falling back to the resolved global value
                         toolChoice: this.toolChoiceOverride, // Pass tool_choice override
                         // Fast-model subagents send disable-thinking params only when
                         // explicitly configured (never in the agent loop).
@@ -1462,8 +1511,9 @@ ${question}`;
                             }
                         }
                     }
-                    // Handle token statistics and message compaction
-                    await this.handleTokenUsageAndCompaction(result.usage, abortController);
+                    // Update token statistics for display (compaction decision is
+                    // pre-request, see maybeAutoCompactBeforeRequest)
+                    this.updateLatestTotalTokens(result.usage);
                     // Finalize text/reasoning blocks for the final response (no tools)
                     this.messageManager.finalizeStreamingBlocks();
                     // Check if there are tool operations or response was truncated, if so automatically initiate next AI service call