wave-agent-sdk 0.19.9 → 1.0.0

package/src/managers/mcpManager.ts

@@ -9,6 +9,7 @@ import { ChatCompletionFunctionTool } from "openai/resources.js";
 import { createMcpToolPlugin, findToolServer } from "../utils/mcpUtils.js";
 import type { ToolPlugin, ToolResult, ToolContext } from "../tools/types.js";
 import { Container } from "../utils/container.js";
+import type { ConfigurationService } from "../services/configurationService.js";
 import type {
   Logger,
   McpServerConfig,
@@ -42,7 +43,21 @@ export interface McpManagerOptions {
  */
 const WAVE_TEMPLATE_VARS = ["WAVE_PLUGIN_ROOT", "CLAUDE_PLUGIN_ROOT"];
 
-export function expandEnvVars(value: string): string {
+/**
+ * Expand environment variables in a string value.
+ * Supports ${VAR} and ${VAR:-default} patterns.
+ *
+ * @param env - Merged env to resolve against (session snapshot over OS env).
+ *              Defaults to `process.env` for backward compatibility with tests
+ *              and standalone callers.
+ */
+export function expandEnvVars(
+  value: string,
+  env: Record<string, string | undefined> = process.env as Record<
+    string,
+    string | undefined
+  >,
+): string {
   return value.replace(/\$\{([^}]+)\}/g, (_match, expr: string) => {
     const [varName, ...rest] = expr.split(":-");
     const defaultValue = rest.join(":-");
@@ -50,45 +65,53 @@ export function expandEnvVars(value: string): string {
     if (WAVE_TEMPLATE_VARS.includes(varName)) {
       return _match; // return original ${...} string untouched
     }
-    return process.env[varName] ?? defaultValue;
+    return env[varName] ?? process.env[varName] ?? defaultValue;
   });
 }
 
 /**
  * Walk an MCP config and resolve environment variables in all string fields.
- * Only expands ${VAR} from process.env (skipping WAVE_PLUGIN_ROOT which is
- * handled at spawn time).
+ * Expands ${VAR} against the session env snapshot (over OS env); falls back to
+ * process.env. WAVE_PLUGIN_ROOT is skipped — handled at spawn time.
  */
-export function resolveMcpConfig(config: McpConfig): McpConfig {
+export function resolveMcpConfig(
+  config: McpConfig,
+  env: Record<string, string | undefined> = process.env as Record<
+    string,
+    string | undefined
+  >,
+): McpConfig {
   const resolved: McpConfig = { mcpServers: {} };
 
   for (const [name, serverConfig] of Object.entries(config.mcpServers)) {
     const resolvedServer: McpServerConfig = { ...serverConfig };
 
     if (resolvedServer.command) {
-      resolvedServer.command = expandEnvVars(resolvedServer.command);
+      resolvedServer.command = expandEnvVars(resolvedServer.command, env);
     }
 
     if (resolvedServer.args) {
-      resolvedServer.args = resolvedServer.args.map(expandEnvVars);
+      resolvedServer.args = resolvedServer.args.map((a) =>
+        expandEnvVars(a, env),
+      );
     }
 
     if (resolvedServer.env) {
       const resolvedEnv: Record<string, string> = {};
       for (const [key, val] of Object.entries(resolvedServer.env)) {
-        resolvedEnv[key] = expandEnvVars(val);
+        resolvedEnv[key] = expandEnvVars(val, env);
       }
       resolvedServer.env = resolvedEnv;
     }
 
     if (resolvedServer.url) {
-      resolvedServer.url = expandEnvVars(resolvedServer.url);
+      resolvedServer.url = expandEnvVars(resolvedServer.url, env);
     }
 
     if (resolvedServer.headers) {
       const resolvedHeaders: Record<string, string> = {};
       for (const [key, val] of Object.entries(resolvedServer.headers)) {
-        resolvedHeaders[key] = expandEnvVars(val);
+        resolvedHeaders[key] = expandEnvVars(val, env);
       }
       resolvedServer.headers = resolvedHeaders;
     }
@@ -119,6 +142,19 @@ export class McpManager {
     this.mcpServers = options.mcpServers;
   }
 
+  /**
+   * Merged env for this session: OS env overlaid with the per-session settings
+   * snapshot. MCP env-var expansion (${VAR}) resolves against this so multiple
+   * sessions in one `wave --stdio` process don't read each other's settings env.
+   */
+  private get envSnapshot(): Record<string, string> {
+    return (
+      this.container
+        .get<ConfigurationService>("ConfigurationService")
+        ?.getMergedEnv?.() ?? (process.env as Record<string, string>)
+    );
+  }
+
   /**
    * Initialize MCP manager with working directory and optionally auto-connect
    */
@@ -189,7 +225,7 @@ export class McpManager {
     try {
       const configContent = await fs.readFile(this.configPath, "utf-8");
       const rawConfig: McpConfig = JSON.parse(configContent);
-      const workspaceConfig = resolveMcpConfig(rawConfig);
+      const workspaceConfig = resolveMcpConfig(rawConfig, this.envSnapshot);
 
       // Extract original (pre-resolution) URLs for safe display
       const originalUrls: Record<string, string | undefined> = {};
@@ -284,28 +320,31 @@ export class McpManager {
     // Capture original URL before any resolution for safe display
     const originalUrl = config.url;
 
-    // Expand env vars from process.env (e.g. ${TAVILY_API_KEY})
+    // Expand env vars against the session snapshot (over OS env, e.g. ${TAVILY_API_KEY})
+    const env = this.envSnapshot;
     const resolvedConfig: McpServerConfig = { ...config };
     if (resolvedConfig.command) {
-      resolvedConfig.command = expandEnvVars(resolvedConfig.command);
+      resolvedConfig.command = expandEnvVars(resolvedConfig.command, env);
     }
     if (resolvedConfig.args) {
-      resolvedConfig.args = resolvedConfig.args.map(expandEnvVars);
+      resolvedConfig.args = resolvedConfig.args.map((a) =>
+        expandEnvVars(a, env),
+      );
     }
     if (resolvedConfig.env) {
       const resolvedEnv: Record<string, string> = {};
       for (const [key, val] of Object.entries(resolvedConfig.env)) {
-        resolvedEnv[key] = expandEnvVars(val);
+        resolvedEnv[key] = expandEnvVars(val, env);
       }
       resolvedConfig.env = resolvedEnv;
     }
     if (resolvedConfig.url) {
-      resolvedConfig.url = expandEnvVars(resolvedConfig.url);
+      resolvedConfig.url = expandEnvVars(resolvedConfig.url, env);
     }
     if (resolvedConfig.headers) {
       const resolvedHeaders: Record<string, string> = {};
       for (const [key, val] of Object.entries(resolvedConfig.headers)) {
-        resolvedHeaders[key] = expandEnvVars(val);
+        resolvedHeaders[key] = expandEnvVars(val, env);
       }
       resolvedConfig.headers = resolvedHeaders;
     }
@@ -433,8 +472,11 @@ export class McpManager {
           );
         }
 
+        // Base env = OS env overlaid with this session's settings snapshot, so
+        // custom env vars from settings.json reach the MCP server subprocess
+        // without polluting other sessions sharing one `wave --stdio` process.
         const env: Record<string, string> = {
-          ...(process.env as Record<string, string>),
+          ...this.envSnapshot,
           ...(server.config.env || {}),
         };
 

package/src/managers/toolManager.ts

@@ -253,6 +253,13 @@ class ToolManager {
             "WorkflowManager",
           )
         : undefined,
+      sessionEnv: this.container.has("ConfigurationService")
+        ? this.container
+            .get<
+              import("../services/configurationService.js").ConfigurationService
+            >("ConfigurationService")
+            ?.getMergedEnv?.()
+        : undefined,
       sessionId: context.sessionId,
       toolCallId: context.toolCallId,
     };

package/src/services/configurationService.ts

@@ -61,6 +61,10 @@ export class ConfigurationService {
   private currentConfiguration: WaveConfiguration | null = null;
   private options: AgentOptions = {};
   private _configuredEnvKeys = new Set<string>();
+  // 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`.
+  private envSnapshot: Record<string, string> = {};
 
   /**
    * Set agent options for configuration resolution
@@ -69,6 +73,28 @@ export class ConfigurationService {
     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(): Record<string, string> {
+    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(): Record<string, string> {
+    return Object.fromEntries(
+      Object.entries({ ...process.env, ...this.envSnapshot }).filter(
+        ([, v]) => v !== undefined,
+      ),
+    ) as Record<string, string>;
+  }
+
   // Core loading operations
 
   /**
@@ -384,16 +410,33 @@ 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: Record<string, string>): void {
     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;
+      }
     }
   }
 
@@ -437,8 +480,11 @@ export class ConfigurationService {
     fetchOptions?: ClientOptions["fetchOptions"],
     fetch?: ClientOptions["fetch"],
   ): GatewayConfig {
-    // 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 ||
@@ -469,7 +515,8 @@ export class ConfigurationService {
     } else if (this.options.apiKey !== undefined) {
       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
@@ -480,15 +527,18 @@ export class ConfigurationService {
     } else if (this.options.baseURL !== undefined) {
       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
@@ -497,7 +547,10 @@ export class ConfigurationService {
     }
 
     // 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
@@ -539,11 +592,13 @@ export class ConfigurationService {
       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;
+      fastModel ||
+      this.options.fastModel ||
+      (this.envSnapshot.WAVE_FAST_MODEL ?? process.env.WAVE_FAST_MODEL);
 
     // Resolve max output tokens
     const resolvedMaxTokens = this.resolveMaxOutputTokens(maxTokens);
@@ -596,8 +651,10 @@ export class ConfigurationService {
       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)) {
@@ -645,9 +702,9 @@ export class ConfigurationService {
       return this.currentConfiguration.autoMemoryEnabled;
     }
 
-    // 2. WAVE_DISABLE_AUTO_MEMORY environment variable
+    // 2. WAVE_DISABLE_AUTO_MEMORY environment variable (settings snapshot > OS env)
     const disableAutoMemory =
-      process.env.WAVE_DISABLE_AUTO_MEMORY ||
+      this.envSnapshot.WAVE_DISABLE_AUTO_MEMORY ??
       process.env.WAVE_DISABLE_AUTO_MEMORY;
     if (disableAutoMemory === "1" || disableAutoMemory === "true") {
       return false;
@@ -681,9 +738,9 @@ export class ConfigurationService {
       return this.currentConfiguration.autoMemoryFrequency;
     }
 
-    // 2. WAVE_AUTO_MEMORY_FREQUENCY environment variable
+    // 2. WAVE_AUTO_MEMORY_FREQUENCY environment variable (settings snapshot > OS env)
     const envFrequency =
-      process.env.WAVE_AUTO_MEMORY_FREQUENCY ||
+      this.envSnapshot.WAVE_AUTO_MEMORY_FREQUENCY ??
       process.env.WAVE_AUTO_MEMORY_FREQUENCY;
     if (envFrequency) {
       const parsed = parseInt(envFrequency, 10);
@@ -713,8 +770,10 @@ export class ConfigurationService {
       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) {
@@ -761,8 +820,10 @@ export class ConfigurationService {
   getConfiguredModels(): string[] {
     const models = new Set<string>();
 
-    // 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/src/services/initializationService.ts

@@ -126,13 +126,17 @@ export class InitializationService {
       // 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`,
+        `Initialization Phase [Remote Settings Cache] took ${(performance.now() - phaseStart).toFixed(2)}ms`,
       );
     } catch (error) {
       logger?.error("Failed to initialize remote settings:", error);
@@ -190,6 +194,13 @@ export class InitializationService {
       // 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();
@@ -237,7 +248,9 @@ export class InitializationService {
           cwd: workdir,
           worktreeName: agentOptions.worktreeName,
           env: Object.fromEntries(
-            Object.entries(process.env).filter((e) => e[1] !== undefined),
+            Object.entries(configurationService.getMergedEnv()).filter(
+              (e) => e[1] !== undefined,
+            ),
           ) as Record<string, string>,
         });
 

package/src/services/interactionService.ts

@@ -93,7 +93,9 @@ export class InteractionService {
               cwd: workdir,
               userPrompt: content,
               env: Object.fromEntries(
-                Object.entries(process.env).filter((e) => e[1] !== undefined),
+                Object.entries(
+                  context.configurationService.getMergedEnv(),
+                ).filter((e) => e[1] !== undefined),
               ) as Record<string, string>, // Include environment variables
             },
           );
@@ -137,6 +139,7 @@ export class InteractionService {
   ): Promise<void> {
     const {
       messageManager,
+      hookManager,
       logger,
       subagentManager,
       taskManager,
@@ -157,7 +160,24 @@ export class InteractionService {
       // Continue with restoration even if save fails
     }
 
-    // 3. Load target session
+    // 3. Run SessionEnd hooks for the current session (cleanup before switching)
+    const currentSessionId = messageManager.getSessionId();
+    const currentTranscriptPath = messageManager.getTranscriptPath();
+    if (hookManager) {
+      try {
+        await hookManager.executeSessionEndHooks(
+          "resume",
+          currentSessionId,
+          currentTranscriptPath,
+        );
+      } catch (error) {
+        logger?.warn(
+          `SessionEnd hooks on restore failed: ${(error as Error).message}`,
+        );
+      }
+    }
+
+    // 4. Load target session
     const sessionData = await loadSessionFromJsonl(
       sessionId,
       messageManager.getWorkdir(),
@@ -166,20 +186,43 @@ export class InteractionService {
       throw new Error(`Session not found: ${sessionId}`);
     }
 
-    // 4. Clean current state
+    // 5. Clean current state
     abortMessage(); // Abort any running operations
     subagentManager.cleanup(); // Clean up active subagents
 
-    // 5. Rebuild usage (in correct order)
+    // 6. Rebuild usage (in correct order)
     messageManager.rebuildUsageFromMessages(sessionData.messages);
 
-    // 6. Initialize session state last
+    // 7. Initialize session state last
     messageManager.initializeFromSession(sessionData);
 
+    // 8. Run SessionStart hooks for the restored session and inject additional
+    //    context as a meta user message (matches Claude Code's resume behavior:
+    //    SessionEnd then SessionStart, hook messages appended to the conversation)
+    if (hookManager) {
+      try {
+        const sessionStartResult = await hookManager.executeSessionStartHooks(
+          "resume",
+          sessionData.id,
+          messageManager.getTranscriptPath(),
+        );
+        if (sessionStartResult.additionalContext) {
+          messageManager.addUserMessage({
+            content: `<system-reminder>\nSessionStart hook additional context: ${sessionStartResult.additionalContext}\n</system-reminder>`,
+            isMeta: true,
+          });
+        }
+      } catch (error) {
+        logger?.warn(
+          `SessionStart hooks on restore failed: ${(error as Error).message}`,
+        );
+      }
+    }
+
     // Update task manager with the root session ID to ensure continuity across compactions
     taskManager.setTaskListId(sessionData.id);
 
-    // 7. Load tasks for the restored session
+    // 9. Load tasks for the restored session
     const tasks = await taskManager.listTasks();
     options.callbacks?.onTasksChange?.(tasks);
   }

package/src/services/remoteSettingsService.ts

@@ -198,8 +198,22 @@ function startPolling(): void {
 }
 
 export function initialize(): void {
+  // Load disk cache synchronously so getRemoteSettingsSync() returns cached
+  // managed settings during loadMergedConfiguration() (must run BEFORE it).
   loadCacheFromDisk();
-  // Fire-and-forget the initial fetch, then start background polling
+}
+
+/**
+ * Start the fire-and-forget initial network fetch + background polling.
+ *
+ * Must be called AFTER loadMergedConfiguration() so disk-cached managed
+ * settings are merged before the fetch, and so settings `env` WAVE_SERVER_URL
+ * is mirrored to process.env (by setEnvironmentVars) before the fetch. The
+ * fetch uses authService.getServerUrl(), which reads process.env.WAVE_SERVER_URL
+ * — the settings value is visible there, so there is no init-ordering race
+ * that would fall back to DEFAULT_SERVER_URL (prod) and hit a test endpoint (401).
+ */
+export function startBackgroundFetch(): void {
   fetchRemoteSettings()
     .then(() => startPolling())
     .catch((err) => {
@@ -342,6 +356,7 @@ export function mergeRemoteSettings(
  */
 export const remoteSettingsService = {
   initialize,
+  startBackgroundFetch,
   getRemoteSettingsSync,
   refresh,
   clear,

package/src/services/taskManager.ts

@@ -6,6 +6,7 @@ import { Task } from "../types/tasks.js";
 import { logger } from "../utils/globalLogger.js";
 import { Container } from "../utils/container.js";
 import type { MessageManager } from "../managers/messageManager.js";
+import type { ConfigurationService } from "./configurationService.js";
 
 function byIdAsc(a: Task, b: Task) {
   const aNum = parseInt(a.id, 10);
@@ -44,7 +45,15 @@ export class TaskManager extends EventEmitter {
     if (!messageManager) return;
 
     const rootSessionId = messageManager.getRootSessionId();
-    if (this.taskListId !== rootSessionId && !process.env.WAVE_TASK_LIST_ID) {
+    // Read the per-session snapshot (not process.env) so multiple sessions in
+    // one `wave --stdio` process don't cross-pollute this flag.
+    const envSnap =
+      this.container
+        .get<ConfigurationService>("ConfigurationService")
+        ?.getEnvSnapshot() ?? {};
+    const pinnedTaskListId =
+      envSnap.WAVE_TASK_LIST_ID ?? process.env.WAVE_TASK_LIST_ID;
+    if (this.taskListId !== rootSessionId && !pinnedTaskListId) {
       this.setTaskListId(rootSessionId);
       await this.refreshTasks();
     }

package/src/tools/bashTool.ts

@@ -285,6 +285,7 @@ The working directory persists between commands. Try to maintain your current wo
         cwd: context.workdir,
         env: {
           ...process.env,
+          ...context.sessionEnv,
         },
       });
 

package/src/tools/enterWorktreeTool.ts

@@ -9,6 +9,7 @@ import {
   createWorktree,
   validateWorktreeName,
   generateWorktreeName,
+  performPostCreationSetup,
 } from "../utils/worktreeUtils.js";
 import { getGitMainRepoRoot } from "../utils/gitUtils.js";
 import { ENTER_WORKTREE_TOOL_NAME } from "../constants/tools.js";
@@ -105,6 +106,20 @@ export const enterWorktreeTool: ToolPlugin = {
     const baseRef = context.aiManager?.getWorktreeBaseRef?.();
     const worktreeInfo = createWorktree(name, mainRepoRoot, { baseRef });
 
+    // Copy local settings (.wave/settings.local.json) and gitignored project
+    // files (.worktreeinclude, e.g. .env/.mcp.json) into a new worktree —
+    // mirrors the CLI createWorktree path. Best-effort, never fails the tool.
+    if (worktreeInfo.isNew) {
+      try {
+        await performPostCreationSetup(
+          worktreeInfo.path,
+          worktreeInfo.repoRoot,
+        );
+      } catch (error) {
+        logger?.warn("Worktree post-creation setup failed:", error);
+      }
+    }
+
     // Build session state
     const session: WorktreeSession = {
       originalCwd: context.workdir,
@@ -134,11 +149,13 @@ export const enterWorktreeTool: ToolPlugin = {
             projectDir: worktreeInfo.path,
             timestamp: new Date(),
             sessionId: context.sessionId ?? "",
-            transcriptPath: context.messageManager?.getTranscriptPath() ?? "",
+            transcriptPath: context.messageManager?.getTranscriptPath?.() ?? "",
             cwd: worktreeInfo.path,
             worktreeName: worktreeInfo.name,
             env: Object.fromEntries(
-              Object.entries(process.env).filter((e) => e[1] !== undefined),
+              Object.entries(context.sessionEnv ?? process.env).filter(
+                (e) => e[1] !== undefined,
+              ),
             ) as Record<string, string>,
           },
         );