wave-agent-sdk 0.19.8 → 1.0.0

package/dist/prompts/index.js

@@ -149,53 +149,141 @@ This is critical - your turn should only end with either using the ${ASK_USER_QU
 NOTE: At any point in time through this workflow you should feel free to ask the user questions or clarifications using the ${ASK_USER_QUESTION_TOOL_NAME} tool. Don't make large assumptions about user intent. The goal is to present a well researched plan to the user, and tie any loose ends before implementation begins.`;
 }
 export const DEFAULT_SYSTEM_PROMPT = BASE_SYSTEM_PROMPT;
-export const COMPACT_MESSAGES_SYSTEM_PROMPT = `You are continuing work on a software engineering task. Write a detailed continuation summary that will allow you (or another instance of yourself) to resume work efficiently in a future context window where the conversation history will be replaced with this summary.
+// Aggressive no-tools preamble, aligned with Claude Code's NO_TOOLS_PREAMBLE.
+// The fork path inherits the main conversation's full tool set (required for
+// cache-key match), so the instruction must be explicit about rejection
+// consequences to prevent wasted turns.
+const COMPACT_NO_TOOLS_PREAMBLE = `CRITICAL: Respond with TEXT ONLY. Do NOT call any tools.
 
-First, write your analysis in <analysis> tags as a thinking scratchpad:
-- Chronologically review the conversation
-- Identify user intents and goals
-- Note files read/modified, approaches tried, decisions made
-- Check for accuracy and completeness — ensure nothing critical is missing
+- Do NOT use Read, Bash, Grep, Glob, Edit, Write, or ANY other tool.
+- You already have all the context you need in the conversation above.
+- Tool calls will be REJECTED and will waste your only turn — you will fail the task.
+- Your entire response must be plain text: an <analysis> block followed by a <summary> block.
 
-Then produce a structured summary in <summary> tags with these sections:
-
-## Primary Request and Intent
-- The user's core request and success criteria
-- Clarifications, constraints, or scope changes
-
-## Key Technical Concepts
-- Frameworks, libraries, patterns, architectural decisions
-
-## Files and Code Sections
-- Files read, modified, created (with full paths)
-- Critical code snippets (function signatures, bug fixes, key logic)
-- Focus on recent messages — include full code for important sections
-
-## Errors and Fixes
-- Errors encountered, root causes, how they were resolved
-- Approaches tried that didn't work and why
-
-## Problem Solving
-- Approach evolution, trade-offs considered, decisions made
-
-## All User Messages
-- Complete list of all user messages (non-tool content)
-- Preserve exact wording where load-bearing
-
-## Pending Tasks
-- Outstanding work, TODOs, unresolved questions
-
-## Current Work
-- What was being worked on at the time of summarization
-- Exact state of in-progress changes
-
-## Optional Next Step
-- Immediate next action needed
-- Include verbatim quotes from recent conversation if relevant
-
-Be concise but complete — include information that prevents duplicate work or repeated mistakes.
-Respond with text only. Do NOT call any tools.
-Wrap your summary in <summary></summary> tags.`;
+`;
+// Aligned with Claude Code's DETAILED_ANALYSIS_INSTRUCTION_BASE. The
+// <analysis> block is a drafting scratchpad that formatCompactSummary()
+// strips before the summary reaches context.
+const COMPACT_DETAILED_ANALYSIS_INSTRUCTION = `Before providing your final summary, wrap your analysis in <analysis> tags to organize your thoughts and ensure you've covered all necessary points. In your analysis process:
+
+1. Chronologically analyze each message and section of the conversation. For each section thoroughly identify:
+   - The user's explicit requests and intents
+   - Your approach to addressing the user's requests
+   - Key decisions, technical concepts and code patterns
+   - Specific details like:
+     - file names
+     - full code snippets
+     - function signatures
+     - file edits
+   - Errors that you ran into and how you fixed them
+   - Pay special attention to specific user feedback that you received, especially if the user told you to do something differently.
+2. Double-check for technical accuracy and completeness, addressing each required element thoroughly.`;
+// Aligned with Claude Code's BASE_COMPACT_PROMPT (9 sections + example).
+const BASE_COMPACT_PROMPT = `Your task is to create a detailed summary of the conversation so far, paying close attention to the user's explicit requests and your previous actions.
+This summary should be thorough in capturing technical details, code patterns, and architectural decisions that would be essential for continuing development work without losing context.
+
+${COMPACT_DETAILED_ANALYSIS_INSTRUCTION}
+
+Your summary should include the following sections:
+
+1. Primary Request and Intent: Capture all of the user's explicit requests and intents in detail
+2. Key Technical Concepts: List all important technical concepts, technologies, and frameworks discussed.
+3. Files and Code Sections: Enumerate specific files and code sections examined, modified, or created. Pay special attention to the most recent messages and include full code snippets where applicable and include a summary of why this file read or edit is important.
+4. Errors and fixes: List all errors that you ran into, and how you fixed them. Pay special attention to specific user feedback that you received, especially if the user told you to do something differently.
+5. Problem Solving: Document problems solved and any ongoing troubleshooting efforts.
+6. All user messages: List ALL user messages that are not tool results. These are critical for understanding the users' feedback and changing intent.
+7. Pending Tasks: Outline any pending tasks that you have explicitly been asked to work on.
+8. Current Work: Describe in detail precisely what was being worked on immediately before this summary request, paying special attention to the most recent messages from both user and assistant. Include file names and code snippets where applicable.
+9. Optional Next Step: List the next step that you will take that is related to the most recent work you were doing. IMPORTANT: ensure that this step is DIRECTLY in line with the user's most recent explicit requests, and the task you were working on immediately before this summary request. If your last task was concluded, then only list next steps if they are explicitly in line with the users request. Do not start on tangential requests or really old requests that were already completed without confirming with the user first.
+                       If there is a next step, include direct quotes from the most recent conversation showing exactly what task you were working on and where you left off. This should be verbatim to ensure there's no drift in task interpretation.
+
+Here's an example of how your output should be structured:
+
+<example>
+<analysis>
+[Your thought process, ensuring all points are covered thoroughly and accurately]
+</analysis>
+
+<summary>
+1. Primary Request and Intent:
+   [Detailed description]
+
+2. Key Technical Concepts:
+   - [Concept 1]
+   - [Concept 2]
+   - [...]
+
+3. Files and Code Sections:
+   - [File Name 1]
+      - [Summary of why this file is important]
+      - [Summary of the changes made to this file, if any]
+      - [Important Code Snippet]
+   - [File Name 2]
+      - [Important Code Snippet]
+   - [...]
+
+4. Errors and fixes:
+    - [Detailed description of error 1]:
+      - [How you fixed the error]
+      - [User feedback on the error if any]
+    - [...]
+
+5. Problem Solving:
+   [Description of solved problems and ongoing troubleshooting]
+
+6. All user messages:
+    - [Detailed non tool use user message]
+    - [...]
+
+7. Pending Tasks:
+   - [Task 1]
+   - [Task 2]
+   - [...]
+
+8. Current Work:
+   [Precise description of current work]
+
+9. Optional Next Step:
+   [Optional Next step to take]
+
+</summary>
+</example>
+
+Please provide your summary based on the conversation so far, following this structure and ensuring precision and thoroughness in your response.
+
+There may be additional summarization instructions provided in the included context. If so, remember to follow these instructions when creating the above summary.`;
+const COMPACT_NO_TOOLS_TRAILER = "\n\nREMINDER: Do NOT call any tools. Respond with plain text only — " +
+    "an <analysis> block followed by a <summary> block. " +
+    "Tool calls will be rejected and you will fail the task.";
+/**
+ * Builds the compact instruction sent as the trailing user message on the
+ * fork path. Aligned with Claude Code's getCompactPrompt().
+ */
+export function getCompactPrompt(customInstructions) {
+    let prompt = COMPACT_NO_TOOLS_PREAMBLE + BASE_COMPACT_PROMPT;
+    if (customInstructions && customInstructions.trim() !== "") {
+        prompt += `\n\nAdditional Instructions:\n${customInstructions}`;
+    }
+    prompt += COMPACT_NO_TOOLS_TRAILER;
+    return prompt;
+}
+/**
+ * Formats the compact summary by stripping the <analysis> drafting scratchpad
+ * and extracting the <summary> section. Raw text passes through unchanged
+ * when no <summary> tag is present. Aligned with Claude Code's
+ * formatCompactSummary().
+ */
+export function formatCompactSummary(summary) {
+    let formattedSummary = summary;
+    formattedSummary = formattedSummary.replace(/<analysis>[\s\S]*?<\/analysis>/, "");
+    const summaryMatch = formattedSummary.match(/<summary>([\s\S]*?)<\/summary>/);
+    if (summaryMatch) {
+        const content = summaryMatch[1] || "";
+        formattedSummary = formattedSummary.replace(/<summary>[\s\S]*?<\/summary>/, `Summary:\n${content.trim()}`);
+    }
+    formattedSummary = formattedSummary.replace(/\n\n+/g, "\n\n");
+    return formattedSummary.trim();
+}
 export const WEB_CONTENT_SYSTEM_PROMPT = `You are a helpful assistant that extracts information from web content. The content is provided in Markdown format.`;
 export const BTW_SYSTEM_PROMPT = `You are a helpful assistant. Answer the user's side question based on the conversation history. 
 Do NOT say things like "Let me try...", "I'll now...", "Let me check...", or promise to take any action. 

package/dist/services/aiService.d.ts

@@ -24,6 +24,7 @@ export interface CallAgentOptions {
             name: string;
         };
     };
+    stream?: boolean;
     onContentUpdate?: (content: string) => void;
     onToolUpdate?: (toolCall: {
         id: string;
@@ -44,23 +45,6 @@ export interface CallAgentResult {
     additionalFields?: Record<string, unknown>;
 }
 export declare function callAgent(options: CallAgentOptions): Promise<CallAgentResult>;
-export interface CompactMessagesOptions {
-    gatewayConfig: GatewayConfig;
-    modelConfig: ModelConfig;
-    messages: ChatCompletionMessageParam[];
-    abortSignal?: AbortSignal;
-    model?: string;
-    customInstructions?: string;
-}
-export interface CompactMessagesResult {
-    content: string;
-    usage?: {
-        prompt_tokens: number;
-        completion_tokens: number;
-        total_tokens: number;
-    };
-}
-export declare function compactMessages(options: CompactMessagesOptions): Promise<CompactMessagesResult>;
 export interface ProcessWebContentOptions {
     gatewayConfig: GatewayConfig;
     modelConfig: ModelConfig;

package/dist/services/aiService.js

@@ -7,7 +7,7 @@ import { supportsPromptCaching } from "../utils/modelCapabilities.js";
 import * as os from "os";
 import * as fs from "fs";
 import * as path from "path";
-import { COMPACT_MESSAGES_SYSTEM_PROMPT, WEB_CONTENT_SYSTEM_PROMPT, BTW_SYSTEM_PROMPT, } from "../prompts/index.js";
+import { WEB_CONTENT_SYSTEM_PROMPT, BTW_SYSTEM_PROMPT, } from "../prompts/index.js";
 import { GOAL_EVALUATION_SYSTEM_PROMPT } from "../constants/goalPrompts.js";
 // Global rate limiter state for 1 QPS
 let nextAllowedTime = 0;
@@ -149,9 +149,8 @@ export async function callAgent(options) {
             ...(modelConfig.options || {}),
         });
         // Determine if streaming is needed
-        const isStreaming = !!(onContentUpdate ||
-            onToolUpdate ||
-            onReasoningUpdate);
+        const isStreaming = options.stream === true ||
+            !!(onContentUpdate || onToolUpdate || onReasoningUpdate);
         // Prepare API call parameters
         createParams = {
             ...openaiModelConfig,
@@ -488,87 +487,6 @@ async function processStreamingResponse(stream, onContentUpdate, onToolUpdate, o
     }
     return result;
 }
-export async function compactMessages(options) {
-    const { gatewayConfig, modelConfig, messages, abortSignal } = options;
-    // Validate model config at call time
-    validateModelConfig(modelConfig);
-    // Apply global 1 QPS rate limit
-    if (process.env.NODE_ENV !== "test" ||
-        modelConfig.model === "rate-limit-test") {
-        await acquireSlot(abortSignal);
-    }
-    // Strip images from messages before compact API call to reduce token usage
-    const cleanedMessages = messages.map((msg) => {
-        // Handle user/assistant messages with array content
-        if (Array.isArray(msg.content)) {
-            const textParts = msg.content.filter((part) => part.type === "text");
-            const text = textParts.map((p) => p.text).join("\n");
-            return { ...msg, content: text || "(empty message)" };
-        }
-        return msg;
-    });
-    // Create OpenAI client with injected configuration
-    const openai = new OpenAIClient({
-        apiKey: gatewayConfig.apiKey,
-        baseURL: gatewayConfig.baseURL,
-        defaultHeaders: gatewayConfig.defaultHeaders,
-        fetchOptions: gatewayConfig.fetchOptions,
-        fetch: gatewayConfig.fetch,
-    });
-    // When a fast model override is provided, use the fast model's options
-    // (if configured); otherwise fall back to the agent model's options.
-    const activeExtraParams = options.model
-        ? modelConfig.fastModelOptions || {}
-        : modelConfig.options || {};
-    const openaiModelConfig = getModelConfig(options.model || modelConfig.model, {
-        temperature: 0.1,
-        max_tokens: 8192,
-        ...activeExtraParams,
-    });
-    try {
-        const response = await openai.chat.completions.create({
-            ...openaiModelConfig,
-            messages: [
-                {
-                    role: "system",
-                    content: COMPACT_MESSAGES_SYSTEM_PROMPT,
-                },
-                ...cleanedMessages,
-                {
-                    role: "user",
-                    content: options.customInstructions
-                        ? `Please create a detailed summary of the conversation so far. Pay special attention to these instructions: ${options.customInstructions}`
-                        : `Please create a detailed summary of the conversation so far.`,
-                },
-            ],
-        }, {
-            signal: abortSignal,
-        });
-        const content = response.choices[0]?.message?.content?.trim();
-        if (!content) {
-            throw new Error("Failed to compact conversation history: Empty response from AI");
-        }
-        const usage = response.usage
-            ? {
-                prompt_tokens: response.usage.prompt_tokens,
-                completion_tokens: response.usage.completion_tokens,
-                total_tokens: response.usage.total_tokens,
-            }
-            : undefined;
-        return {
-            content,
-            usage,
-        };
-    }
-    catch (error) {
-        if (error.name === "AbortError") {
-            logger.info("Compaction request was aborted");
-            throw new Error("Compaction request was aborted");
-        }
-        logger.error("Failed to compact messages:", error);
-        throw error;
-    }
-}
 export async function processWebContent(options) {
     const { gatewayConfig, modelConfig, content, prompt, abortSignal } = options;
     // Validate model config at call time

package/dist/services/configurationService.d.ts

@@ -18,10 +18,23 @@ export declare class ConfigurationService {
     private currentConfiguration;
     private options;
     private _configuredEnvKeys;
+    private envSnapshot;
     /**
      * Set agent options for configuration resolution
      */
     setOptions(options: AgentOptions): void;
+    /**
+     * Returns a copy of the per-session environment snapshot (settings.json `env`).
+     * Priority over OS env; does NOT include OS env. For subprocess spawning use
+     * {@link getMergedEnv} instead.
+     */
+    getEnvSnapshot(): Record<string, string>;
+    /**
+     * Returns OS env merged with the session snapshot (snapshot wins). Use this
+     * when spawning user-facing subprocesses (bash, hooks, bang, background, MCP)
+     * so they inherit both OS env and the session's settings env.
+     */
+    getMergedEnv(): Record<string, string>;
     /**
      * Load and merge configuration with comprehensive validation
      */
@@ -35,8 +48,14 @@ export declare class ConfigurationService {
      */
     validateConfigurationFile(filePath: string): ValidationResult;
     /**
-     * Set environment variables from configuration
-     * This replaces direct process.env modification
+     * Store environment variables from configuration into the per-session
+     * snapshot (NOT process.env). Settings `env` shadows OS env for this session
+     * only — multiple sessions in one stdio process stay isolated.
+     *
+     * Exception: `WAVE_SERVER_URL` is also mirrored to `process.env` because the
+     * process-level singletons (AuthService, remoteSettingsService background
+     * fetch) need to read it and don't hold a per-session snapshot. Same value
+     * across sessions ⇒ no cross-pollution. See docs/specs/core/agent-config.md.
      */
     setEnvironmentVars(env: Record<string, string>): void;
     /**

package/dist/services/configurationService.js

@@ -28,6 +28,10 @@ export class ConfigurationService {
         this.currentConfiguration = null;
         this.options = {};
         this._configuredEnvKeys = new Set();
+        // Per-session environment snapshot: settings.json `env` is stored here (NOT
+        // written to process.env) so multiple sessions in one `wave --stdio` process
+        // don't cross-pollute. Resolve methods read `this.envSnapshot ?? process.env`.
+        this.envSnapshot = {};
     }
     /**
      * Set agent options for configuration resolution
@@ -35,6 +39,22 @@ export class ConfigurationService {
     setOptions(options) {
         this.options = options;
     }
+    /**
+     * Returns a copy of the per-session environment snapshot (settings.json `env`).
+     * Priority over OS env; does NOT include OS env. For subprocess spawning use
+     * {@link getMergedEnv} instead.
+     */
+    getEnvSnapshot() {
+        return { ...this.envSnapshot };
+    }
+    /**
+     * Returns OS env merged with the session snapshot (snapshot wins). Use this
+     * when spawning user-facing subprocesses (bash, hooks, bang, background, MCP)
+     * so they inherit both OS env and the session's settings env.
+     */
+    getMergedEnv() {
+        return Object.fromEntries(Object.entries({ ...process.env, ...this.envSnapshot }).filter(([, v]) => v !== undefined));
+    }
     // Core loading operations
     /**
      * Load and merge configuration with comprehensive validation
@@ -292,16 +312,31 @@ export class ConfigurationService {
     }
     // Utility operations
     /**
-     * Set environment variables from configuration
-     * This replaces direct process.env modification
+     * Store environment variables from configuration into the per-session
+     * snapshot (NOT process.env). Settings `env` shadows OS env for this session
+     * only — multiple sessions in one stdio process stay isolated.
+     *
+     * Exception: `WAVE_SERVER_URL` is also mirrored to `process.env` because the
+     * process-level singletons (AuthService, remoteSettingsService background
+     * fetch) need to read it and don't hold a per-session snapshot. Same value
+     * across sessions ⇒ no cross-pollution. See docs/specs/core/agent-config.md.
      */
     setEnvironmentVars(env) {
         for (const [key, value] of Object.entries(env)) {
-            if (process.env[key] !== undefined && !this._configuredEnvKeys.has(key)) {
+            if (process.env[key] !== undefined &&
+                !this._configuredEnvKeys.has(key) &&
+                process.env[key] !== value) {
                 logger.warn(`Overriding environment variable: ${key}`);
             }
-            process.env[key] = value;
+            this.envSnapshot[key] = value;
             this._configuredEnvKeys.add(key);
+            // WAVE_SERVER_URL is consumed by process-level singletons (AuthService,
+            // remoteSettingsService) that can't see the per-session snapshot — mirror
+            // it to process.env so they read the settings value. Same value across
+            // sessions ⇒ no last-session-wins cross-pollution.
+            if (key === "WAVE_SERVER_URL") {
+                process.env[key] = value;
+            }
         }
     }
     // =============================================================================
@@ -337,8 +372,11 @@ export class ConfigurationService {
      * @returns Resolved model configuration (model/fastModel may be undefined if not yet configured)
      */
     resolveGatewayConfig(apiKey, baseURL, defaultHeaders, fetchOptions, fetch) {
-        // Check for SSO token first - if present and server URL is available, use SSO mode
-        // Server URL resolution: options > process.env > default
+        // Check for SSO token first - if present and server URL is available, use SSO mode.
+        // Server URL resolution: options.serverUrl > process.env.WAVE_SERVER_URL > default.
+        // settings.json `env` WAVE_SERVER_URL is mirrored to process.env by
+        // setEnvironmentVars (so process-level singletons AuthService / remoteSettings
+        // can read it), then read here. See docs/specs/core/agent-config.md.
         const ssoToken = this.readSSOToken();
         const serverUrl = this.options.serverUrl ||
             process.env.WAVE_SERVER_URL ||
@@ -366,7 +404,8 @@ export class ConfigurationService {
             resolvedApiKey = this.options.apiKey;
         }
         else {
-            resolvedApiKey = process.env.WAVE_API_KEY;
+            resolvedApiKey =
+                this.envSnapshot.WAVE_API_KEY ?? process.env.WAVE_API_KEY;
         }
         // Resolve base URL: override > options > env (settings.json) > process.env
         // Note: Explicitly provided empty strings should be treated as invalid, not fall back to env
@@ -378,21 +417,26 @@ export class ConfigurationService {
             resolvedBaseURL = this.options.baseURL;
         }
         else {
-            resolvedBaseURL = process.env.WAVE_BASE_URL;
+            resolvedBaseURL =
+                this.envSnapshot.WAVE_BASE_URL ?? process.env.WAVE_BASE_URL;
         }
         // Fallback to process.env if still not resolved (for dynamic updates in tests)
         if (resolvedApiKey === undefined) {
-            resolvedApiKey = process.env.WAVE_API_KEY;
+            resolvedApiKey =
+                this.envSnapshot.WAVE_API_KEY ?? process.env.WAVE_API_KEY;
         }
         if (!resolvedBaseURL) {
-            resolvedBaseURL = process.env.WAVE_BASE_URL;
+            resolvedBaseURL =
+                this.envSnapshot.WAVE_BASE_URL ?? process.env.WAVE_BASE_URL;
         }
         // Treat empty string as not provided
         if (resolvedBaseURL?.trim() === "") {
             resolvedBaseURL = undefined;
         }
         // Resolve custom headers from environment: env (settings.json) > process.env
-        const envCustomHeaders = process.env.WAVE_CUSTOM_HEADERS || "";
+        const envCustomHeaders = this.envSnapshot.WAVE_CUSTOM_HEADERS ??
+            process.env.WAVE_CUSTOM_HEADERS ??
+            "";
         const parsedEnvHeaders = parseCustomHeaders(envCustomHeaders);
         // Merge headers: env headers < options < override
         const resolvedHeaders = {
@@ -424,9 +468,11 @@ export class ConfigurationService {
         const resolvedAgentModel = model ||
             this.options.model ||
             this.currentConfiguration?.model ||
-            process.env.WAVE_MODEL;
+            (this.envSnapshot.WAVE_MODEL ?? process.env.WAVE_MODEL);
         // Resolve fast model: override > options > process.env (includes settings.json env)
-        const resolvedFastModel = fastModel || this.options.fastModel || process.env.WAVE_FAST_MODEL;
+        const resolvedFastModel = fastModel ||
+            this.options.fastModel ||
+            (this.envSnapshot.WAVE_FAST_MODEL ?? process.env.WAVE_FAST_MODEL);
         // Resolve max output tokens
         const resolvedMaxTokens = this.resolveMaxOutputTokens(maxTokens);
         const baseConfig = {
@@ -468,8 +514,9 @@ export class ConfigurationService {
         if (this.options.maxInputTokens !== undefined) {
             return this.options.maxInputTokens;
         }
-        // Try env (settings.json) first, then process.env
-        const envMaxInputTokens = process.env.WAVE_MAX_INPUT_TOKENS;
+        // Try env (settings.json snapshot) first, then process.env
+        const envMaxInputTokens = this.envSnapshot.WAVE_MAX_INPUT_TOKENS ??
+            process.env.WAVE_MAX_INPUT_TOKENS;
         if (envMaxInputTokens) {
             const parsed = parseInt(envMaxInputTokens, 10);
             if (!isNaN(parsed)) {
@@ -510,8 +557,8 @@ export class ConfigurationService {
         if (this.currentConfiguration?.autoMemoryEnabled !== undefined) {
             return this.currentConfiguration.autoMemoryEnabled;
         }
-        // 2. WAVE_DISABLE_AUTO_MEMORY environment variable
-        const disableAutoMemory = process.env.WAVE_DISABLE_AUTO_MEMORY ||
+        // 2. WAVE_DISABLE_AUTO_MEMORY environment variable (settings snapshot > OS env)
+        const disableAutoMemory = this.envSnapshot.WAVE_DISABLE_AUTO_MEMORY ??
             process.env.WAVE_DISABLE_AUTO_MEMORY;
         if (disableAutoMemory === "1" || disableAutoMemory === "true") {
             return false;
@@ -541,8 +588,8 @@ export class ConfigurationService {
         if (this.currentConfiguration?.autoMemoryFrequency !== undefined) {
             return this.currentConfiguration.autoMemoryFrequency;
         }
-        // 2. WAVE_AUTO_MEMORY_FREQUENCY environment variable
-        const envFrequency = process.env.WAVE_AUTO_MEMORY_FREQUENCY ||
+        // 2. WAVE_AUTO_MEMORY_FREQUENCY environment variable (settings snapshot > OS env)
+        const envFrequency = this.envSnapshot.WAVE_AUTO_MEMORY_FREQUENCY ??
             process.env.WAVE_AUTO_MEMORY_FREQUENCY;
         if (envFrequency) {
             const parsed = parseInt(envFrequency, 10);
@@ -568,8 +615,9 @@ export class ConfigurationService {
         if (this.options.maxTokens !== undefined) {
             return this.options.maxTokens;
         }
-        // Try env (settings.json) first, then process.env
-        const envMaxOutputTokens = process.env.WAVE_MAX_OUTPUT_TOKENS;
+        // Try env (settings.json snapshot) first, then process.env
+        const envMaxOutputTokens = this.envSnapshot.WAVE_MAX_OUTPUT_TOKENS ??
+            process.env.WAVE_MAX_OUTPUT_TOKENS;
         if (envMaxOutputTokens) {
             const parsed = parseInt(envMaxOutputTokens, 10);
             if (!isNaN(parsed) && parsed > 0) {
@@ -610,8 +658,9 @@ export class ConfigurationService {
      */
     getConfiguredModels() {
         const models = new Set();
-        // Add current model from options or environment
-        const currentModel = this.options.model || process.env.WAVE_MODEL;
+        // Add current model from options or environment (settings snapshot > OS env)
+        const currentModel = this.options.model ||
+            (this.envSnapshot.WAVE_MODEL ?? process.env.WAVE_MODEL);
         if (currentModel) {
             models.add(currentModel);
         }

package/dist/services/initializationService.js

@@ -44,12 +44,16 @@ export class InitializationService {
             logger?.error("Failed to initialize MCP servers:", error);
             // Don't throw error to prevent app startup failure
         }
-        // Initialize remote settings (load disk cache synchronously, then fetch in background)
-        // Must happen BEFORE loadMergedConfiguration so remote env vars are available
+        // Load remote settings disk cache synchronously.
+        // Must happen BEFORE loadMergedConfiguration so cached managed settings
+        // (env, model, disallowedTools) are merged into the config. Settings `env`
+        // is stored in the per-session env snapshot (NOT process.env), except
+        // WAVE_SERVER_URL which is mirrored to process.env so the network fetch
+        // (below) can read it via authService.getServerUrl(); no race.
         try {
             const phaseStart = performance.now();
             await remoteSettingsService.initialize();
-            logger?.debug(`Initialization Phase [Remote Settings] took ${(performance.now() - phaseStart).toFixed(2)}ms`);
+            logger?.debug(`Initialization Phase [Remote Settings Cache] took ${(performance.now() - phaseStart).toFixed(2)}ms`);
         }
         catch (error) {
             logger?.error("Failed to initialize remote settings:", error);
@@ -89,6 +93,12 @@ export class InitializationService {
             logger?.error("Failed to initialize hooks system:", error);
             // Don't throw error to prevent app startup failure
         }
+        // Start remote settings network fetch + polling now that the config is
+        // merged. Settings `env` WAVE_SERVER_URL was mirrored to process.env by
+        // loadMergedConfiguration → setEnvironmentVars, so the fetch reads it via
+        // authService.getServerUrl(); fire-and-forget, failures fall back to the
+        // cached/merged settings.
+        remoteSettingsService.startBackgroundFetch();
         // Execute SessionStart hooks
         try {
             const phaseStart = performance.now();
@@ -124,7 +134,7 @@ export class InitializationService {
                     transcriptPath: messageManager.getTranscriptPath(),
                     cwd: workdir,
                     worktreeName: agentOptions.worktreeName,
-                    env: Object.fromEntries(Object.entries(process.env).filter((e) => e[1] !== undefined)),
+                    env: Object.fromEntries(Object.entries(configurationService.getMergedEnv()).filter((e) => e[1] !== undefined)),
                 });
                 // Process hook results
                 hookManager.processHookResults("WorktreeCreate", hookResults, messageManager);