wave-agent-sdk 0.19.9 → 1.0.1

package/dist/managers/aiManager.js

@@ -12,6 +12,10 @@ import { recoverTruncatedJson } from "../utils/stringUtils.js";
 import { logger } from "../utils/globalLogger.js";
 import { startInteractionSpan, endInteractionSpan, startLLMRequestSpan, endLLMRequestSpan, resetTracingState, } from "../telemetry/sessionTracing.js";
 import { logOTelEvent } from "../telemetry/events.js";
+/** Max turns for the compaction fork: the model should summarize, not act. */
+const MAX_FORK_TURNS = 3;
+/** Max turns for the auto-memory extraction fork. */
+const MAX_AUTO_MEMORY_FORK_TURNS = 5;
 // Truncate text to `max` chars and append a "… [+N chars]" marker when exceeded.
 // Used for background_tasks description/command fields (≤1000 chars per spec FR-063).
 function truncateWithMarker(text, max) {
@@ -99,9 +103,24 @@ export class AIManager {
     get configurationService() {
         return this.container.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.
+     */
+    get mergedEnv() {
+        return (this.container
+            .get("ConfigurationService")
+            ?.getMergedEnv?.() ?? process.env);
+    }
     // Getter methods for accessing dynamic configuration
     getGatewayConfig() {
-        return this.configurationService.resolveGatewayConfig();
+        return {
+            ...this.configurationService.resolveGatewayConfig(),
+            sessionId: this.messageManager.getSessionId(),
+        };
     }
     getModelConfig() {
         const permissionMode = this.container.has("PermissionMode")
@@ -438,7 +457,7 @@ export class AIManager {
         }
         catch (compactError) {
             this.consecutiveCompactionFailures++;
-            logger?.error(`Failed to compact messages (${this.consecutiveCompactionFailures} consecutive):`, compactError);
+            logger?.error(`Failed to compact messages (${this.consecutiveCompactionFailures} consecutive): ${compactError instanceof Error ? compactError.message : String(compactError)}`);
             this.messageManager.addErrorBlock(`Failed to compact conversation history: ${compactError instanceof Error ? compactError.message : String(compactError)}. You may encounter context limit issues.`);
         }
         finally {
@@ -475,16 +494,15 @@ export class AIManager {
         return { toolsConfig, toolNames, filteredToolPlugins };
     }
     /**
-     * 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.
      */
-    async runCompactFork(historyMessages, compactPrompt, abortSignal) {
-        const MAX_FORK_TURNS = 3;
+    async runForkLoop(historyMessages, prompt, options, abortSignal) {
         const modelConfig = this.getModelConfig();
         const gatewayConfig = this.getGatewayConfig();
         const sessionId = this.messageManager.getSessionId();
@@ -498,12 +516,15 @@ export class AIManager {
                 content: wrapInSystemReminder(prependContent),
             });
         }
-        forkMessages.push({ role: "user", content: compactPrompt });
+        forkMessages.push({ role: "user", content: prompt });
         const { toolsConfig, filteredToolPlugins } = this.resolveFilteredTools();
         const systemPrompt = await this.buildMainSystemPrompt(filteredToolPlugins);
+        // Fresh read-state map so Read/Edit state built up inside the fork never
+        // leaks into the main session's dedup and staleness tracking.
+        const forkReadFileState = new Map();
         let totalUsage;
         let content;
-        for (let turn = 0; turn < MAX_FORK_TURNS; turn++) {
+        for (let turn = 0; turn < options.maxTurns; turn++) {
             const result = await aiService.callAgent({
                 gatewayConfig,
                 modelConfig,
@@ -516,7 +537,7 @@ export class AIManager {
                 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
-                // summary, which exceeds the timeout on large contexts).
+                // response, which exceeds the timeout on large contexts).
                 stream: true,
             });
             if (result.usage) {
@@ -532,28 +553,259 @@ export class AIManager {
                 break;
             }
             if (result.tool_calls && result.tool_calls.length > 0) {
-                // Deny all tool calls locally and feed the rejections back so the
-                // model gets another turn to produce the summary text.
+                const functionCalls = result.tool_calls.filter((tc) => tc.type === "function");
+                if (functionCalls.length === 0)
+                    break;
                 forkMessages.push({
                     role: "assistant",
                     content: result.content ?? null,
-                    tool_calls: result.tool_calls,
+                    tool_calls: functionCalls,
                 });
-                for (const toolCall of result.tool_calls) {
+                for (const toolCall of functionCalls) {
+                    const name = toolCall.function?.name || "";
+                    const args = this.parseForkToolArgs(toolCall.function?.arguments);
+                    let toolContent;
+                    if (options.canUseTool && options.canUseTool(name, args)) {
+                        toolContent = await this.executeForkTool(name, args, workdir, sessionId, abortSignal, forkReadFileState);
+                    }
+                    else {
+                        toolContent =
+                            options.deniedToolMessage ??
+                                "Tool use is not allowed in this context";
+                    }
                     forkMessages.push({
                         role: "tool",
                         tool_call_id: toolCall.id,
-                        content: "Tool use is not allowed during compaction",
+                        content: toolContent,
                     });
                 }
                 continue;
             }
             // Neither text nor tool calls: retrying the identical request is
-            // pointless, bail out and let the caller fail the compaction.
+            // pointless, bail out and let the caller fail.
             break;
         }
         return { content, usage: totalUsage };
     }
+    /**
+     * 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) {
+        return this.runForkLoop(historyMessages, compactPrompt, {
+            maxTurns: MAX_FORK_TURNS,
+            deniedToolMessage: "Tool use is not allowed during compaction",
+        }, abortSignal);
+    }
+    /**
+     * 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.
+     */
+    async runAutoMemoryFork(messages, prompt, options, abortSignal) {
+        const modelConfig = this.getModelConfig();
+        const historyMessages = convertMessagesForAPI(messages, {
+            supportsVision: supportsVision(modelConfig.capabilities),
+        });
+        // Give the fork a real signal even when the caller has none, so tools
+        // (e.g. Bash's foreground path) always receive a well-formed context.
+        const signal = abortSignal ?? new AbortController().signal;
+        const result = await this.runForkLoop(historyMessages, prompt, {
+            maxTurns: options.maxTurns ?? MAX_AUTO_MEMORY_FORK_TURNS,
+            canUseTool: options.canUseTool,
+            deniedToolMessage: options.deniedToolMessage,
+        }, signal);
+        if (result.usage && this.callbacks?.onUsageAdded) {
+            this.callbacks.onUsageAdded({
+                ...result.usage,
+                model: modelConfig.model,
+                operation_type: "agent",
+            });
+        }
+        return result;
+    }
+    /**
+     * 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.
+     */
+    parseForkToolArgs(argsString) {
+        if (!argsString?.trim())
+            return {};
+        try {
+            return JSON.parse(argsString);
+        }
+        catch {
+            try {
+                return JSON.parse(recoverTruncatedJson(argsString));
+            }
+            catch {
+                return {};
+            }
+        }
+    }
+    /**
+     * 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.
+     */
+    async executeForkTool(name, args, workdir, sessionId, abortSignal, readFileState) {
+        const plugin = this.toolManager.getTools().find((t) => t.name === name);
+        if (!plugin) {
+            return `Tool '${name}' not found`;
+        }
+        const context = {
+            abortSignal,
+            workdir,
+            originalWorkdir: this.originalWorkdir,
+            sessionId,
+            taskManager: this.taskManager,
+            readFileState,
+            onShortResultUpdate: () => { },
+            onResultUpdate: () => { },
+            onCwdChange: () => { },
+        };
+        try {
+            const result = await plugin.execute(args, context);
+            if (result.content)
+                return result.content;
+            if (result.error)
+                return `Error: ${result.error}`;
+            return "";
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger?.error(`Fork tool execution failed for ${name}:`, error);
+            return `Tool execution failed: ${message}`;
+        }
+    }
+    /**
+     * 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.
+     */
+    async runBtwFork(question, abortSignal, onContent, onReasoning) {
+        const modelConfig = this.getModelConfig();
+        const gatewayConfig = this.getGatewayConfig();
+        const sessionId = this.messageManager.getSessionId();
+        const workdir = this.getWorkdir();
+        const rawMessages = this.messageManager.getMessages();
+        // Strip the in-progress assistant message (a block still in "streaming"
+        // stage) so the fork's request prefix matches the last completed
+        // main-loop request and the prompt cache is reused.
+        const lastMessage = rawMessages[rawMessages.length - 1];
+        const hasInProgressMessage = lastMessage?.role === "assistant" &&
+            lastMessage.blocks.some((b) => "stage" in b && b.stage === "streaming");
+        const forkMessages = convertMessagesForAPI(hasInProgressMessage ? rawMessages.slice(0, -1) : rawMessages, { supportsVision: supportsVision(modelConfig.capabilities) });
+        // Mirror the main loop's memory injection so the request prefix matches.
+        const { prependContent } = await this.messageManager.getMemoryForInjection();
+        if (prependContent.trim()) {
+            forkMessages.unshift({
+                role: "user",
+                content: wrapInSystemReminder(prependContent),
+            });
+        }
+        // Wrap the question with the side-question instructions (verbatim
+        // Claude Code sideQuestion.ts) so the model answers directly.
+        const wrappedQuestion = `<system-reminder>This is a side question from the user. You must answer this question directly in a single response.
+
+IMPORTANT CONTEXT:
+- You are a separate, lightweight agent spawned to answer this one question
+- The main agent is NOT interrupted - it continues working independently in the background
+- You share the conversation context but are a completely separate instance
+- Do NOT reference being interrupted or what you were "previously doing" - that framing is incorrect
+
+CRITICAL CONSTRAINTS:
+- You have NO tools available - you cannot read files, run commands, search, or take any actions
+- This is a one-off response - there will be no follow-up turns
+- You can ONLY provide information based on what you already know from the conversation context
+- NEVER say things like "Let me try...", "I'll now...", "Let me check...", or promise to take any action
+- If you don't know the answer, say so - do not offer to look it up or investigate
+
+Simply answer the question with the information you have.</system-reminder>
+
+${question}`;
+        forkMessages.push({ role: "user", content: wrappedQuestion });
+        const { toolsConfig, filteredToolPlugins } = this.resolveFilteredTools();
+        const systemPrompt = await this.buildMainSystemPrompt(filteredToolPlugins);
+        try {
+            // Surface partial output to the caller (e.g. the /btw overlay's
+            // streaming display) as it arrives. Reasoning chunks from thinking
+            // models stream through a separate channel when the caller supplies
+            // one (webview hosts distinguish thinking from content so the panel
+            // can drop thinking text once content starts); otherwise they fall
+            // back to the content channel (CLI overlay mixes both).
+            const streamToOverlay = (text) => {
+                if (text.trim()) {
+                    onContent?.(text);
+                }
+            };
+            const streamReasoning = (text) => {
+                if (text.trim()) {
+                    if (onReasoning) {
+                        onReasoning(text);
+                    }
+                    else {
+                        onContent?.(text);
+                    }
+                }
+            };
+            const result = await aiService.callAgent({
+                gatewayConfig,
+                modelConfig,
+                messages: forkMessages,
+                sessionId,
+                abortSignal,
+                workdir,
+                tools: toolsConfig,
+                systemPrompt,
+                toolChoice: this.toolChoiceOverride,
+                // Stream so a slow reasoning model emits first bytes before the
+                // gateway's idle timeout fires (same rationale as runCompactFork).
+                stream: true,
+                onContentUpdate: streamToOverlay,
+                onReasoningUpdate: streamReasoning,
+            });
+            if (result.content?.trim()) {
+                return { content: result.content };
+            }
+            // A thinking model may emit only reasoning content (e.g. the stream
+            // is truncated before the final answer); surface that instead of
+            // falling through to "No response received".
+            if (result.reasoning_content?.trim()) {
+                return { content: result.reasoning_content };
+            }
+            if (result.tool_calls && result.tool_calls.length > 0) {
+                const firstFunctionCall = result.tool_calls.find((call) => call.type === "function");
+                const toolName = firstFunctionCall?.function?.name ?? "a tool";
+                return {
+                    error: `(The model tried to call ${toolName} instead of answering directly. Try rephrasing or ask in the main conversation.)`,
+                };
+            }
+            // Neither text nor tool calls.
+            return { error: "No response received" };
+        }
+        catch (error) {
+            // aiService.callAgent converts AbortError into a plain Error, so the
+            // abort is detected via the signal itself; rethrow so the UI can
+            // silently dismiss instead of showing an error.
+            if (abortSignal?.aborted) {
+                throw error;
+            }
+            return {
+                error: `(API error: ${error instanceof Error ? error.message : String(error)})`,
+            };
+        }
+    }
     /**
      * Build post-compact context restoration content.
      * Restores file reads, working directory, plan mode, skills, and background tasks.
@@ -790,6 +1042,11 @@ export class AIManager {
                         systemPrompt: mainSystemPrompt, // Pass custom system prompt
                         maxTokens: maxTokens, // Pass max tokens override
                         toolChoice: this.toolChoiceOverride, // Pass tool_choice override
+                        // Fast-model subagents send disable-thinking params only when
+                        // explicitly configured (never in the agent loop).
+                        disableThinkingOptions: this.modelOverride === "fastModel"
+                            ? this.getModelConfig().disableThinkingOptions
+                            : undefined,
                     };
                     // Prepend: AGENTS.md + user memory + unconditional rules as system-reminder
                     if (prependContent.trim()) {
@@ -1103,67 +1360,15 @@ export class AIManager {
                             this.messageManager.addFileHistoryBlock(snapshots);
                         }
                     }
-                    // Goal evaluation — supersedes Stop hooks when active
-                    const goalManager = this.container.has("GoalManager")
-                        ? this.container.get("GoalManager")
-                        : undefined;
-                    let goalContinuing = false;
-                    if (goalManager?.isGoalActive() && !this.subagentType) {
-                        // 1. Increment turn count and check circuit breakers
-                        goalManager.incrementTurnCount();
-                        const circuitBreaker = goalManager.checkCircuitBreakers();
-                        if (circuitBreaker) {
-                            goalManager.clearGoal();
-                            logger?.info(`[Goal] ${circuitBreaker}`);
-                            this.messageManager.addUserMessage({
-                                content: `<system-reminder>${circuitBreaker}</system-reminder>`,
-                                isMeta: true,
-                            });
-                            // Fall through to normal Stop hooks on the final turn
-                        }
-                        else {
-                            // 2. Evaluate goal
-                            const evaluation = await goalManager.evaluateGoal(abortController.signal);
-                            if (evaluation.isMet) {
-                                goalManager.clearGoal();
-                                logger?.info(`[Goal] Goal achieved: ${evaluation.reason}`);
-                                this.messageManager.addUserMessage({
-                                    content: `<system-reminder>Goal achieved: ${evaluation.reason}</system-reminder>`,
-                                    isMeta: true,
-                                });
-                                // Fall through to normal Stop hooks on the final turn
-                            }
-                            else {
-                                const goal = goalManager.getGoal();
-                                goal.lastReason = evaluation.reason;
-                                logger?.info(`[Goal] Not yet met: ${evaluation.reason}`);
-                                this.messageManager.addUserMessage({
-                                    content: `<system-reminder>Goal not yet met: ${evaluation.reason}. Continue working toward: ${goal.condition}</system-reminder>`,
-                                    isMeta: true,
-                                });
-                                // Keep loading state active to prevent UI flicker
-                                this.setIsLoading(true);
-                                goalContinuing = true;
-                                // Restart outer loop to continue goal pursuit
-                                shouldRestart = true;
-                                turnOffset = 0;
-                            }
-                        }
-                    }
-                    // Skip Stop hooks when goal evaluator is continuing the conversation
-                    if (goalContinuing) {
-                        // Goal evaluator supersedes Stop hooks
-                    }
-                    else {
-                        const shouldContinue = await this.executeStopHooks();
-                        // If Stop/SubagentStop hooks indicate we should continue (due to blocking errors),
-                        // restart the AI conversation cycle
-                        if (shouldContinue) {
-                            logger?.info(`${this.subagentType ? "SubagentStop" : "Stop"} hooks indicate issues need fixing, continuing conversation...`);
-                            // Restart the conversation to let AI fix the issues
-                            shouldRestart = true;
-                            turnOffset = 0;
-                        }
+                    // Execute Stop hooks
+                    const shouldContinue = await this.executeStopHooks();
+                    // If Stop/SubagentStop hooks indicate we should continue (due to blocking errors),
+                    // restart the AI conversation cycle
+                    if (shouldContinue) {
+                        logger?.info(`${this.subagentType ? "SubagentStop" : "Stop"} hooks indicate issues need fixing, continuing conversation...`);
+                        // Restart the conversation to let AI fix the issues
+                        shouldRestart = true;
+                        turnOffset = 0;
                     }
                 }
                 // Inject pending notifications from background tasks (after Stop hooks,
@@ -1262,7 +1467,7 @@ export class AIManager {
                 sessionCrons, // Stop-only: session cron jobs snapshot
                 lastAssistantMessage: lastAssistantText, // Stop/SubagentStop: last assistant message text
                 // Stop hooks don't need toolName, toolInput, toolResponse, or userPrompt
-                env: Object.fromEntries(Object.entries(process.env).filter((e) => e[1] !== undefined)), // Include environment variables
+                env: Object.fromEntries(Object.entries(this.mergedEnv).filter((e) => e[1] !== undefined)), // Include environment variables
             };
             const results = await this.hookManager.executeHooks(hookName, context);
             // Process hook results to handle exit codes and appropriate responses
@@ -1417,7 +1622,7 @@ export class AIManager {
                     if (this.hookManager) {
                         const sessionId = this.messageManager.getSessionId();
                         const transcriptPath = this.messageManager.getTranscriptPath();
-                        const env = Object.fromEntries(Object.entries(process.env).filter((e) => e[1] !== undefined));
+                        const env = Object.fromEntries(Object.entries(this.mergedEnv).filter((e) => e[1] !== undefined));
                         await this.hookManager.executeCwdChangedHooks(oldCwd, newCwd, sessionId, transcriptPath, env);
                     }
                 },
@@ -1484,7 +1689,7 @@ export class AIManager {
                 cwd: this.getWorkdir(),
                 toolInput,
                 subagentType: this.subagentType, // Include subagent type in hook context
-                env: Object.fromEntries(Object.entries(process.env).filter((e) => e[1] !== undefined)), // Include environment variables
+                env: Object.fromEntries(Object.entries(this.mergedEnv).filter((e) => e[1] !== undefined)), // Include environment variables
             };
             const results = await this.hookManager.executeHooks("PreToolUse", context);
             // Process hook results to handle exit codes and determine if tool should be blocked
@@ -1537,7 +1742,7 @@ export class AIManager {
                 toolResponse,
                 subagentType: this.subagentType, // Include subagent type in hook context
                 planFilePath: this.permissionManager?.getPlanFilePath(),
-                env: Object.fromEntries(Object.entries(process.env).filter((e) => e[1] !== undefined)), // Include environment variables
+                env: Object.fromEntries(Object.entries(this.mergedEnv).filter((e) => e[1] !== undefined)), // Include environment variables
             };
             const results = await this.hookManager.executeHooks("PostToolUse", context);
             // Process hook results to handle exit codes and update tool results

package/dist/managers/backgroundTaskManager.d.ts

@@ -15,6 +15,12 @@ export declare class BackgroundTaskManager {
     private callbacks;
     private workdir;
     constructor(container: Container, options: BackgroundTaskManagerOptions);
+    /**
+     * Merged env (OS env overlaid with this session's settings snapshot) for
+     * background-task subprocesses, so settings `env` vars reach them without
+     * polluting other sessions in one `wave --stdio` process.
+     */
+    private get sessionEnv();
     /**
      * Fire the onBackgroundTasksChange callback so UI consumers refresh.
      * Public so other managers (e.g. WorkflowManager) can trigger a refresh

package/dist/managers/backgroundTaskManager.js

@@ -13,6 +13,16 @@ export class BackgroundTaskManager {
         this.callbacks = options.callbacks || {};
         this.workdir = options.workdir;
     }
+    /**
+     * Merged env (OS env overlaid with this session's settings snapshot) for
+     * background-task subprocesses, so settings `env` vars reach them without
+     * polluting other sessions in one `wave --stdio` process.
+     */
+    get sessionEnv() {
+        return (this.container
+            .get("ConfigurationService")
+            ?.getMergedEnv?.() ?? process.env);
+    }
     /**
      * Fire the onBackgroundTasksChange callback so UI consumers refresh.
      * Public so other managers (e.g. WorkflowManager) can trigger a refresh
@@ -44,6 +54,7 @@ export class BackgroundTaskManager {
             cwd: cwd ?? this.workdir,
             env: {
                 ...process.env,
+                ...this.sessionEnv,
             },
         });
         // Create log file

package/dist/managers/bangManager.d.ts

@@ -14,6 +14,12 @@ export declare class BangManager {
     onCommandRunningChange?: (running: boolean) => void;
     constructor(container: Container, options: BangManagerOptions);
     private get messageManager();
+    /**
+     * Merged env (OS env overlaid with this session's settings snapshot) for
+     * bang-command subprocesses, so settings `env` vars reach them without
+     * polluting other sessions in one `wave --stdio` process.
+     */
+    private get sessionEnv();
     private setCommandRunning;
     executeCommand(command: string): Promise<number>;
     abortCommand(): void;

package/dist/managers/bangManager.js

@@ -10,6 +10,16 @@ export class BangManager {
     get messageManager() {
         return this.container.get("MessageManager");
     }
+    /**
+     * Merged env (OS env overlaid with this session's settings snapshot) for
+     * bang-command subprocesses, so settings `env` vars reach them without
+     * polluting other sessions in one `wave --stdio` process.
+     */
+    get sessionEnv() {
+        return (this.container
+            .get("ConfigurationService")
+            ?.getMergedEnv?.() ?? process.env);
+    }
     setCommandRunning(isRunning) {
         this.isCommandRunning = isRunning;
         this.onCommandRunningChange?.(isRunning);
@@ -28,6 +38,7 @@ export class BangManager {
                 cwd: this.workdir,
                 env: {
                     ...process.env,
+                    ...this.sessionEnv,
                 },
             });
             this.currentProcess = child;

package/dist/managers/hookManager.d.ts

@@ -4,7 +4,7 @@
  * Central orchestrator for the hooks system. Handles configuration loading,
  * validation, and hook execution across all supported events.
  */
-import { type HookEvent, type HookExecutionContext, type ExtendedHookExecutionContext, type HookExecutionResult, type HookValidationResult, type SessionEndSource } from "../types/hooks.js";
+import { type HookEvent, type HookExecutionContext, type ExtendedHookExecutionContext, type HookExecutionResult, type HookValidationResult, type SessionEndSource, type SessionStartSource } from "../types/hooks.js";
 import type { WaveConfiguration, PartialHookConfiguration } from "../types/configuration.js";
 import { HookMatcher } from "../utils/hookMatcher.js";
 import type { MessageManager } from "./messageManager.js";
@@ -18,6 +18,12 @@ export declare class HookManager {
     private readonly matcher;
     private readonly workdir;
     constructor(container: Container, workdir: string, matcher?: HookMatcher);
+    /**
+     * Merged env for this session (OS env overlaid with the per-session settings
+     * snapshot). Hook subprocesses spawn with this env so settings.json `env`
+     * vars reach hooks without polluting other sessions in one stdio process.
+     */
+    private get sessionEnv();
     /**
      * Load hook configuration from programmatic source (AgentOptions.hooks)
      */
@@ -118,7 +124,7 @@ export declare class HookManager {
      * Execute SessionStart hooks during initialization.
      * Collects additionalContext and initialUserMessage from hook stdout.
      */
-    executeSessionStartHooks(source: "startup" | "compact" | "clear", sessionId: string, transcriptPath: string, agentType?: string): Promise<{
+    executeSessionStartHooks(source: SessionStartSource, sessionId: string, transcriptPath: string, agentType?: string): Promise<{
         results: HookExecutionResult[];
         additionalContext?: string;
         initialUserMessage?: string;

package/dist/managers/hookManager.js

@@ -18,6 +18,16 @@ export class HookManager {
         this.workdir = workdir;
         this.matcher = matcher;
     }
+    /**
+     * Merged env for this session (OS env overlaid with the per-session settings
+     * snapshot). Hook subprocesses spawn with this env so settings.json `env`
+     * vars reach hooks without polluting other sessions in one stdio process.
+     */
+    get sessionEnv() {
+        return (this.container
+            .get("ConfigurationService")
+            ?.getMergedEnv?.() ?? process.env);
+    }
     /**
      * Load hook configuration from programmatic source (AgentOptions.hooks)
      */
@@ -674,7 +684,7 @@ export class HookManager {
             cwd: this.workdir,
             source,
             agentType,
-            env: Object.fromEntries(Object.entries(process.env).filter((e) => e[1] !== undefined)),
+            env: Object.fromEntries(Object.entries(this.sessionEnv).filter((e) => e[1] !== undefined)),
         };
         const results = await this.executeHooks("SessionStart", context);
         let additionalContext;
@@ -718,7 +728,7 @@ export class HookManager {
             transcriptPath,
             cwd: this.workdir,
             endSource: source,
-            env: Object.fromEntries(Object.entries(process.env).filter((e) => e[1] !== undefined)),
+            env: Object.fromEntries(Object.entries(this.sessionEnv).filter((e) => e[1] !== undefined)),
         };
         const results = await this.executeHooks("SessionEnd", context);
         // Process results but never block shutdown
@@ -740,7 +750,7 @@ export class HookManager {
             transcriptPath,
             cwd: this.workdir,
             compactInstructions: customInstructions,
-            env: Object.fromEntries(Object.entries(process.env).filter((e) => e[1] !== undefined)),
+            env: Object.fromEntries(Object.entries(this.sessionEnv).filter((e) => e[1] !== undefined)),
         };
         const results = await this.executeHooks("PreCompact", context);
         let additionalInstructions;
@@ -767,7 +777,7 @@ export class HookManager {
             transcriptPath,
             cwd: this.workdir,
             compactSummary,
-            env: Object.fromEntries(Object.entries(process.env).filter((e) => e[1] !== undefined)),
+            env: Object.fromEntries(Object.entries(this.sessionEnv).filter((e) => e[1] !== undefined)),
         };
         const results = await this.executeHooks("PostCompact", context);
         if (results.length > 0) {