wave-agent-sdk 0.19.9 → 1.0.1

package/builtin/plugins/sdd/scripts/session-start.js

@@ -14,7 +14,7 @@ const guidance = [
   "Spec-First Workflow（规格优先工作流）：",
   "- 需求增加或变更时，优先更新 spec：先更新对应规格说明（新增用户故事、验收场景），待用户确认 spec 后再实现代码。spec 是功能设计的权威来源，不是 changelog。",
   "- 边界模糊时也先写 spec 草稿请用户确认，不要直接改代码。",
-  "- 使用 /sdd:specify 技能创建或更新规格文件。",
+  "- 规格编写技能（specify）由 AI 自动触发：对话中涉及新需求或需求变更时主动创建或更新规格文件，不需要用户手动调用（不出现在斜杠命令列表中）。",
   `- 新增或修改 spec 后运行校验：${specCount}（自动检测 docs/specs/，否则 specs/，否则退出）。`,
 ].join("\n");
 

package/builtin/plugins/sdd/skills/specify/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: specify
 description: 根据自然语言描述创建或更新功能规格说明，生成包含用户故事与验收场景的规格文件。
+user-invocable: false
 ---
 
 ## 用户输入
@@ -9,13 +10,11 @@ description: 根据自然语言描述创建或更新功能规格说明，生成
 $ARGUMENTS
 ```
 
-你**必须**在继续之前考虑用户输入（如果不为空）。
-
 ## 流程
 
-用户在 `/sdd:specify` 后输入的文本就是功能描述。不要让用户重复，除非他们提供了空命令。
+本技能由 AI 在会话中自动触发（不占用手动斜杠命令）。触发时机：用户提出新的需求、修改需求或涉及功能边界时，若对应规格尚未创建或已过期，则主动创建或更新规格说明。$ARGUMENTS 通常为空——需求描述直接来自对话上下文，不要让用户重复。
 
-根据功能描述，执行以下步骤：
+根据对话中的功能描述，执行以下步骤：
 
 1. **确定规格文件路径**：
    - **确定规格根目录**：优先复用项目中已有的规格目录——若 `docs/specs/` 存在则用之，否则若 `specs/` 存在则用之，否则默认 `specs/`（并在完成报告中说明所选目录，便于用户纠正）。

package/builtin/skills/settings/ENV.md

@@ -17,13 +17,13 @@ Environment variables are configured in the `env` field of `settings.json`. It i
 
 ## Supported `WAVE_*` Environment Variables
 
-Wave uses several environment variables to control its core functionality.
+Wave uses several environment variables to control its core functionality. Variables marked **OS env only** are read from the OS environment (or constructor / stdio `initialize` params) and are **NOT** read from settings.json `env` — set them in your shell, not in the `env` field.
 
 | Variable | Description | Default |
 | :--- | :--- | :--- |
 | `WAVE_API_KEY` | API key for the AI gateway. | - |
 | `WAVE_BASE_URL` | Base URL for the AI gateway. | - |
-| `WAVE_SERVER_URL` | Server URL for SSO authentication. | `https://codechat.codewave.163.com` |
+| `WAVE_SERVER_URL` | Server URL for SSO authentication. **OS env only** — set via OS env or `options.serverUrl`; not read from settings.json `env` (avoids a startup 401 race). | `https://codechat.codewave.163.com` |
 | `WAVE_CUSTOM_HEADERS` | Custom HTTP headers for the AI gateway. Newline-separated `Key: Value` pairs (e.g., `"X-Foo: bar\nAuthorization: Bearer xxx"`). | - |
 | `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` |
@@ -32,23 +32,29 @@ Wave uses several environment variables to control its core functionality.
 | `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` |
 | `WAVE_TASK_LIST_ID` | Explicitly set the task list ID for the session. | (Session ID) |
-| `WAVE_PLUGIN_GIT_TIMEOUT_MS` | Timeout in milliseconds for git operations when installing plugins. | `300000` |
+| `WAVE_PLUGIN_GIT_TIMEOUT_MS` | Timeout in milliseconds for git operations when installing plugins. **OS env only** (infrastructure). | `300000` |
 
 ## Configuration Scopes
 
-Environment variables can be set in different scopes, with the following precedence (highest to lowest):
+Environment variables can be set in different scopes. Wave merges scopes from lowest to highest priority and stores the result in the agent's **per-session environment snapshot**. The snapshot takes priority over OS environment variables but is **NOT written to `process.env`** — this keeps multiple sessions in one `wave --stdio` process from polluting each other.
+
+Precedence (highest to lowest):
 
 1.  **Local Scope**: `.wave/settings.local.json` (Local overrides, ignored by git)
 2.  **Project Scope**: `.wave/settings.json` (Project-specific settings, shared via git)
 3.  **User Scope**: `~/.wave/settings.json` (Global settings for all projects)
-4.  **System Environment**: Variables set in your shell (e.g., `export WAVE_API_KEY=...`)
+4.  **System Environment**: Variables set in your shell (e.g., `export WAVE_API_KEY=...`). Used as a fallback when a key is absent from the settings snapshot.
+
+> Settings `env` shadows (does not mutate) OS env: a key set in both settings.json `env` and the OS environment resolves to the settings value for that session, while the OS value remains untouched and visible to unrelated processes.
 
 ## Custom Environment Variables
 
-You can also define custom environment variables in the `env` field. These variables will be available to:
+You can also define custom environment variables in the `env` field. These variables are stored in the session's environment snapshot and will be available to:
+
+- **Hooks**: Any shell command executed as a hook will have these variables in its environment (merged on top of OS env).
+- **Tools**: Tools like `Bash` will have access to these variables (merged on top of OS env).
 
-- **Hooks**: Any shell command executed as a hook will have these variables in its environment.
-- **Tools**: Tools like `Bash` will have access to these variables.
+In `wave --stdio` mode one process hosts multiple sessions; each session keeps its own snapshot, so sessions with different `env` do not pollute each other (no "last session wins").
 
 Example:
 ```json
@@ -62,7 +68,7 @@ Example:
 
 ## Live Reload
 
-Environment variables configured in `settings.json` support **live reload**. When you modify the `env` field in any `settings.json` file (user, project, or local scope), the changes take effect immediately without requiring a Wave session restart.
+Environment variables configured in `settings.json` support **live reload**. When you modify the `env` field in any `settings.json` file (user, project, or local scope), the changes take effect immediately without requiring a Wave session restart — the session's environment snapshot is refreshed and subsequent resolve calls / subprocess spawns use the new values.
 
 ## Best Practices
 

package/builtin/skills/settings/HOOKS.md

@@ -13,7 +13,7 @@ Wave supports the following hook events:
 - `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 when a worktree is removed (e.g., via ExitWorktree with `action: "remove"`). Non-blocking. The hook receives `worktree_path` in the JSON input. Useful for cleanup tasks (e.g., `docker compose -p $(basename "$worktree_path") down`) after worktree deletion.
+- `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`).
 - `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.
@@ -79,7 +79,7 @@ Wave provides detailed context to hook processes via `stdin` as a JSON object. T
 - `user_prompt`: (UserPromptSubmit) The text submitted by the user.
 - `subagent_type`: (If executed by a subagent) The type of the subagent.
 - `name`: (WorktreeCreate) The name of the new worktree.
-- `worktree_path`: (WorktreeRemove) The absolute path to the removed worktree.
+- `worktree_path`: (WorktreeRemove) The absolute path of the worktree about to be removed. Derive the worktree name with `basename "$worktree_path"`.
 - `old_cwd`: (CwdChanged) The previous working directory.
 - `new_cwd`: (CwdChanged) The new working directory.
 - `compact_instructions`: (PreCompact) Custom instructions for the compaction, if any.
@@ -165,6 +165,31 @@ SessionEnd hooks receive `end_source` in the JSON input indicating how the sessi
 }
 ```
 
+## 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.).
+
+### 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"`.
+
+### Example Configuration
+```json
+{
+  "hooks": {
+    "WorktreeRemove": [
+      {
+        "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"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
 ## Live Reload
 
 Hook configurations support **live reload**. When you modify hooks in `settings.json`, the changes take effect immediately without restarting Wave.

package/dist/agent.d.ts

@@ -19,7 +19,6 @@ export declare class Agent {
     private pluginManager;
     private skillManager;
     private cronManager;
-    private goalManager;
     private hookManager;
     private reversionManager;
     private messageQueue;
@@ -92,10 +91,6 @@ export declare class Agent {
     get isCommandRunning(): boolean;
     /** Get queued user-facing messages (excludes background notifications) */
     get queuedMessages(): QueuedMessage[];
-    /** Get goal status string */
-    get goalStatus(): string;
-    /** Check if a goal is active */
-    get isGoalActive(): boolean;
     /**
      * Remove a queued message by index
      * @param index - The index of the message to remove
@@ -231,19 +226,6 @@ export declare class Agent {
      * @param customInstructions - Optional custom instructions for compaction
      */
     compact(customInstructions?: string): Promise<void>;
-    /**
-     * Set an autonomous goal for the session
-     * @param condition - The goal condition to achieve
-     */
-    setGoal(condition: string): Promise<void>;
-    /**
-     * Clear the current autonomous goal
-     */
-    clearGoal(): Promise<void>;
-    /**
-     * Show the current goal status
-     */
-    showGoalStatus(): Promise<void>;
     /** Unified interrupt method, interrupts both AI messages and command execution */
     abortMessage(): void;
     /** Interrupt bash command execution */
@@ -275,11 +257,18 @@ export declare class Agent {
      */
     triggerShowRewind(): void;
     /**
-     * Ask a side question without tool use
+     * Ask a side question without interrupting the main agent.
+     *
+     * Runs a single-turn fork of the conversation that reuses the main loop's
+     * system prompt, tools, and memory injection (prompt-cache friendly) and
+     * never executes tools. The abort signal lets the UI cancel a pending
+     * question (loading dismiss); aborts propagate as thrown errors.
+     *
      * @param question - The side question to ask
+     * @param abortSignal - Optional signal to abort the pending request
      * @returns Promise that resolves to the AI's answer
      */
-    askBtw(question: string): Promise<string>;
+    askBtw(question: string, abortSignal?: AbortSignal, onContent?: (content: string) => void, onReasoning?: (content: string) => void): Promise<string>;
     /**
      * Send a message to the AI agent with optional images
      *

package/dist/agent.js

@@ -1,8 +1,5 @@
 import { LspManager } from "./managers/lspManager.js";
 import { configValidator } from "./utils/configValidator.js";
-import { btw } from "./services/aiService.js";
-import { convertMessagesForAPI } from "./utils/convertMessagesForAPI.js";
-import { supportsVision } from "./utils/modelCapabilities.js";
 import { parseTaskNotificationXml } from "./utils/notificationXml.js";
 import { InitializationService } from "./services/initializationService.js";
 import { InteractionService } from "./services/interactionService.js";
@@ -14,7 +11,10 @@ import { remoteSettingsService } from "./services/remoteSettingsService.js";
 export class Agent {
     // Dynamic configuration getter methods
     getGatewayConfig() {
-        return this.configurationService.resolveGatewayConfig();
+        return {
+            ...this.configurationService.resolveGatewayConfig(),
+            sessionId: this.messageManager.getSessionId(),
+        };
     }
     getModelConfig() {
         return this.configurationService.resolveModelConfig(undefined, undefined, undefined, this.getPermissionMode());
@@ -111,7 +111,6 @@ export class Agent {
         this.pluginManager = this.container.get("PluginManager");
         this.bangManager = this.container.get("BangManager");
         this.cronManager = this.container.get("CronManager");
-        this.goalManager = this.container.get("GoalManager");
         this.messageQueue = this.container.get("MessageQueue");
         // Wire up CWD change callback from AIManager to sync Agent's workdir
         this.aiManager.setOnCwdChange((newCwd) => {
@@ -138,14 +137,6 @@ export class Agent {
         if (options.permissionMode) {
             this.setPermissionMode(options.permissionMode);
         }
-        // Wire up goal state change callback
-        this.goalManager.setOnGoalStateChange((active, condition, elapsed) => {
-            this.options.callbacks?.onGoalStateChange?.(active, condition, elapsed);
-        });
-        // Wire up goal evaluating callback
-        this.goalManager.setOnGoalEvaluating((evaluating) => {
-            this.options.callbacks?.onGoalEvaluating?.(evaluating);
-        });
     }
     // Public getter methods
     get sessionId() {
@@ -216,14 +207,6 @@ export class Agent {
             .getQueue()
             .filter((m) => m.type !== "notification");
     }
-    /** Get goal status string */
-    get goalStatus() {
-        return this.goalManager.getStatusString();
-    }
-    /** Check if a goal is active */
-    get isGoalActive() {
-        return this.goalManager.isGoalActive();
-    }
     /**
      * Remove a queued message by index
      * @param index - The index of the message to remove
@@ -521,8 +504,6 @@ export class Agent {
     }
     async clearMessages() {
         this.aiManager.abortAIMessage();
-        // Clear any active goal
-        this.goalManager.clearGoal();
         // Capture old session info before clearing
         const oldSessionId = this.messageManager.getSessionId();
         const transcriptPath = this.messageManager.getTranscriptPath();
@@ -571,68 +552,6 @@ export class Agent {
         });
         await this.messageManager.saveSession();
     }
-    /**
-     * Set an autonomous goal for the session
-     * @param condition - The goal condition to achieve
-     */
-    async setGoal(condition) {
-        // Check plan mode
-        if (this.getPermissionMode() === "plan") {
-            this.messageManager.addUserMessage({
-                content: "<system-reminder>Cannot set a goal in plan mode. Exit plan mode first.</system-reminder>",
-                isMeta: true,
-            });
-            return;
-        }
-        this.goalManager.setGoal(condition);
-        this.messageManager.addUserMessage({
-            content: `<system-reminder>Goal set: ${condition}. The agent will work autonomously until this goal is achieved.</system-reminder>`,
-            isMeta: true,
-        });
-        // Add the goal as a user directive to start working
-        this.messageManager.addUserMessage({
-            content: condition,
-        });
-        this.aiManager.sendAIMessage();
-        await this.messageManager.saveSession();
-    }
-    /**
-     * Clear the current autonomous goal
-     */
-    async clearGoal() {
-        if (this.goalManager.isGoalActive()) {
-            this.goalManager.clearGoal();
-            this.messageManager.addUserMessage({
-                content: "<system-reminder>Goal cleared.</system-reminder>",
-                isMeta: true,
-            });
-        }
-        else {
-            this.messageManager.addUserMessage({
-                content: "<system-reminder>No active goal to clear.</system-reminder>",
-                isMeta: true,
-            });
-        }
-        await this.messageManager.saveSession();
-    }
-    /**
-     * Show the current goal status
-     */
-    async showGoalStatus() {
-        if (this.goalManager.isGoalActive()) {
-            this.messageManager.addUserMessage({
-                content: `<system-reminder>${this.goalManager.getStatusString()}</system-reminder>`,
-                isMeta: true,
-            });
-        }
-        else {
-            this.messageManager.addUserMessage({
-                content: "<system-reminder>No active goal. Use /goal <condition> to set one.</system-reminder>",
-                isMeta: true,
-            });
-        }
-        await this.messageManager.saveSession();
-    }
     /** Unified interrupt method, interrupts both AI messages and command execution */
     abortMessage() {
         // Guard: prevent tryDispatch (triggered by abortAIMessage → setIsLoading(false))
@@ -702,7 +621,7 @@ export class Agent {
                 transcriptPath,
                 cwd: this.workdir,
                 worktreePath,
-                env: Object.fromEntries(Object.entries(process.env).filter((e) => e[1] !== undefined)),
+                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);
@@ -754,6 +673,17 @@ export class Agent {
         this.subagentManager.cleanup();
         // Cleanup forked agent manager
         await this.forkedAgentManager.cleanup();
+        // Drain an in-flight auto-memory extraction fork so the process doesn't
+        // exit mid-extraction
+        try {
+            const autoMemoryService = this.container.get("AutoMemoryService");
+            if (autoMemoryService) {
+                await autoMemoryService.drain();
+            }
+        }
+        catch (error) {
+            this.logger?.warn(`Auto-memory extraction drain failed: ${error.message}`);
+        }
         // Cleanup skill manager
         await this.skillManager.destroy();
         // Cleanup live configuration reload
@@ -774,21 +704,20 @@ export class Agent {
         this.messageManager.triggerShowRewind();
     }
     /**
-     * Ask a side question without tool use
+     * Ask a side question without interrupting the main agent.
+     *
+     * Runs a single-turn fork of the conversation that reuses the main loop's
+     * system prompt, tools, and memory injection (prompt-cache friendly) and
+     * never executes tools. The abort signal lets the UI cancel a pending
+     * question (loading dismiss); aborts propagate as thrown errors.
+     *
      * @param question - The side question to ask
+     * @param abortSignal - Optional signal to abort the pending request
      * @returns Promise that resolves to the AI's answer
      */
-    async askBtw(question) {
-        const messages = convertMessagesForAPI(this.messageManager.getMessages(), {
-            supportsVision: supportsVision(this.getModelConfig().capabilities),
-        });
-        const result = await btw({
-            gatewayConfig: this.getGatewayConfig(),
-            modelConfig: this.getModelConfig(),
-            messages,
-            question,
-        });
-        return result.content;
+    async askBtw(question, abortSignal, onContent, onReasoning) {
+        const result = await this.aiManager.runBtwFork(question, abortSignal, onContent, onReasoning);
+        return result.content ?? result.error ?? "No response received";
     }
     /**
      * Send a message to the AI agent with optional images
@@ -818,7 +747,7 @@ export class Agent {
      */
     async sendMessage(content, images) {
         // If the agent is busy, enqueue the message — unless it's an immediate
-        // slash command (e.g., /goal clear, /clear, /compact) that should execute
+        // slash command (e.g., /clear, /compact) that should execute
         // right away even while AI is processing
         if (this.aiManager.isLoading || this.isCommandRunning) {
             const trimmed = content.trim();

package/dist/index.d.ts

@@ -22,6 +22,7 @@ export * from "./utils/tokenCalculation.js";
 export * from "./utils/gitUtils.js";
 export * from "./utils/nameGenerator.js";
 export * from "./utils/worktreeSession.js";
+export * from "./utils/worktreeUtils.js";
 export { loadMergedWaveConfig } from "./services/configurationService.js";
 export * from "./types/index.js";
 export * from "./tools/buildTool.js";

package/dist/index.js

@@ -26,6 +26,7 @@ export * from "./utils/tokenCalculation.js";
 export * from "./utils/gitUtils.js";
 export * from "./utils/nameGenerator.js";
 export * from "./utils/worktreeSession.js";
+export * from "./utils/worktreeUtils.js";
 export { loadMergedWaveConfig } from "./services/configurationService.js";
 export * from "./types/index.js";
 // Export tool building utilities

package/dist/managers/aiManager.d.ts

@@ -1,6 +1,15 @@
-import type { GatewayConfig, ModelConfig, Usage } from "../types/index.js";
+import type { GatewayConfig, ModelConfig, Usage, Message } from "../types/index.js";
 import { Container } from "../utils/container.js";
 import type { WorktreeSession } from "../utils/worktreeSession.js";
+/** Result of a fork-path agent loop (compaction or auto-memory extraction). */
+interface ForkLoopResult {
+    content?: string;
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+}
 export interface AIManagerCallbacks {
     onCompactionStateChange?: (isCompacting: boolean) => void;
     onUsageAdded?: (usage: Usage) => void;
@@ -53,6 +62,14 @@ export declare class AIManager {
     private get permissionManager();
     private get planManager();
     private get configurationService();
+    /**
+     * OS env merged with the per-session env snapshot. Falls back to process.env
+     * when ConfigurationService is absent or its getMergedEnv is missing (e.g. in
+     * unit tests with partial mocks), so hook-context env construction never
+     * throws. Use this (not the non-null `configurationService` getter) when
+     * building hook context env.
+     */
+    private get mergedEnv();
     getGatewayConfig(): GatewayConfig;
     getModelConfig(): ModelConfig;
     getMaxInputTokens(): number;
@@ -111,15 +128,60 @@ export declare class AIManager {
     private buildMainSystemPrompt;
     private resolveFilteredTools;
     /**
-     * Fork-path compaction: run a bounded agent loop over a copy of the
-     * conversation using 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. Tool calls are denied locally (the model
-     * is told to summarize, not act) and their rejections are fed back for
-     * another turn. Returns undefined content when the model never produces
-     * text; the caller treats that as a compaction failure.
+     * Fork-path loop: run a bounded agent loop over a copy of the conversation
+     * using 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. A `canUseTool` gate decides whether each tool call
+     * executes locally (with a stripped context) or is denied and fed back to
+     * the model for another turn. Returns undefined content when the model never
+     * produces text; the caller treats that as a failure.
+     */
+    private runForkLoop;
+    /**
+     * Fork-path compaction: deny all tool calls locally (the model is told to
+     * summarize, not act) and feed the rejections back for another turn.
      */
     private runCompactFork;
+    /**
+     * Auto-memory extraction via the perfect fork: the extraction prompt is run
+     * against the same request prefix as the main conversation (same system
+     * prompt, tools, model, and message history) so the prompt cache is reused.
+     * Gate-approved tools execute locally in a stripped context; everything else
+     * is denied. Usage is reported with operation_type "agent" so extraction
+     * token costs stay visible in session accounting.
+     */
+    runAutoMemoryFork(messages: Message[], prompt: string, options: {
+        canUseTool: (name: string, args: Record<string, unknown>) => boolean;
+        deniedToolMessage?: string;
+        maxTurns?: number;
+    }, abortSignal?: AbortSignal): Promise<ForkLoopResult>;
+    /**
+     * Parse a fork tool call's JSON arguments, recovering truncated JSON the
+     * same way the main loop does. Unparseable arguments fall back to `{}` and
+     * are rejected by the gate or the tool's own parameter validation.
+     */
+    private parseForkToolArgs;
+    /**
+     * Execute a single tool call inside a fork with a stripped context: no
+     * permission manager (never prompts the user), no message manager (no
+     * conditional-rule triggering), no messageId (no file-history snapshots),
+     * and no background task manager (commands run in the foreground). Only
+     * gate-approved tool names reach this path.
+     */
+    private executeForkTool;
+    /**
+     * Fork-path side question ("/btw"): run a single-turn fork of the
+     * conversation using 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. The in-progress assistant message (if any) is
+     * stripped so the fork starts from the last completed request prefix. Tools
+     * are never executed — the wrapped question instructs the model to answer
+     * directly; an attempted tool call is surfaced as an error string.
+     */
+    runBtwFork(question: string, abortSignal?: AbortSignal, onContent?: (content: string) => void, onReasoning?: (content: string) => void): Promise<{
+        content?: string;
+        error?: string;
+    }>;
     /**
      * Build post-compact context restoration content.
      * Restores file reads, working directory, plan mode, skills, and background tasks.
@@ -158,3 +220,4 @@ export declare class AIManager {
      */
     private executePostToolUseHooks;
 }
+export {};