wave-agent-sdk 0.19.9 → 1.0.0

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

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

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

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

package/builtin/skills/settings/ENV.md

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

package/builtin/skills/settings/HOOKS.md

@@ -13,7 +13,7 @@ Wave supports the following hook events:
 - `Stop`: Triggered when Wave finishes its response cycle (no more tool calls).
 - `SubagentStop`: Triggered when a subagent finishes its response cycle.
 - `WorktreeCreate`: Triggered when a new worktree is created.
-- `WorktreeRemove`: Triggered when a worktree is removed (e.g., via ExitWorktree with `action: "remove"`). Non-blocking. The hook receives `worktree_path` in the JSON input. Useful for cleanup tasks (e.g., `docker compose -p $(basename "$worktree_path") down`) after worktree deletion.
+- `WorktreeRemove`: Triggered before a worktree is removed (e.g., via ExitWorktree with `action: "remove"`). Non-blocking. Fires **before** the worktree directory is deleted so hooks can still read files inside it. The hook receives `worktree_path` in the JSON input. Useful for cleanup tasks (e.g., `docker compose -p $(basename "$worktree_path") down`).
 - `CwdChanged`: Triggered when the working directory changes (e.g., entering/exiting a worktree). Non-blocking.
 - `SessionStart`: Triggered during session initialization. Hooks can inject `additionalContext` and `initialUserMessage` via stdout.
 - `SessionEnd`: Triggered during agent destruction (fire-and-forget, non-blocking). Useful for cleanup, resource teardown, and analytics.
@@ -79,7 +79,7 @@ Wave provides detailed context to hook processes via `stdin` as a JSON object. T
 - `user_prompt`: (UserPromptSubmit) The text submitted by the user.
 - `subagent_type`: (If executed by a subagent) The type of the subagent.
 - `name`: (WorktreeCreate) The name of the new worktree.
-- `worktree_path`: (WorktreeRemove) The absolute path to the removed worktree.
+- `worktree_path`: (WorktreeRemove) The absolute path of the worktree about to be removed. Derive the worktree name with `basename "$worktree_path"`.
 - `old_cwd`: (CwdChanged) The previous working directory.
 - `new_cwd`: (CwdChanged) The new working directory.
 - `compact_instructions`: (PreCompact) Custom instructions for the compaction, if any.
@@ -165,6 +165,31 @@ SessionEnd hooks receive `end_source` in the JSON input indicating how the sessi
 }
 ```
 
+## WorktreeRemove Hooks
+
+`WorktreeRemove` hooks fire **before** the worktree directory is deleted, so they can still read files inside it. They are non-blocking (Notification type): the hook never replaces `git worktree remove` itself. Useful for cleaning up external resources that were provisioned for the worktree (databases, containers, etc.).
+
+### Input
+WorktreeRemove hooks receive `worktree_path` in the JSON input (alongside the common fields `session_id`, `transcript_path`, `cwd`, `hook_event_name`). The worktree name can be derived via `basename "$worktree_path"`.
+
+### Example Configuration
+```json
+{
+  "hooks": {
+    "WorktreeRemove": [
+      {
+        "hooks": [
+          {
+            "command": "worktree_path=$(jq -r '.worktree_path') && docker compose -p \"$(basename \"$worktree_path\")\" down || true",
+            "description": "Tear down the worktree's docker compose project before removal"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
 ## Live Reload
 
 Hook configurations support **live reload**. When you modify hooks in `settings.json`, the changes take effect immediately without restarting Wave.

package/dist/agent.js

@@ -14,7 +14,10 @@ import { remoteSettingsService } from "./services/remoteSettingsService.js";
 export class Agent {
     // Dynamic configuration getter methods
     getGatewayConfig() {
-        return this.configurationService.resolveGatewayConfig();
+        return {
+            ...this.configurationService.resolveGatewayConfig(),
+            sessionId: this.messageManager.getSessionId(),
+        };
     }
     getModelConfig() {
         return this.configurationService.resolveModelConfig(undefined, undefined, undefined, this.getPermissionMode());
@@ -702,7 +705,7 @@ export class Agent {
                 transcriptPath,
                 cwd: this.workdir,
                 worktreePath,
-                env: Object.fromEntries(Object.entries(process.env).filter((e) => e[1] !== undefined)),
+                env: Object.fromEntries(Object.entries(this.configurationService.getMergedEnv()).filter((e) => e[1] !== undefined)),
             });
             // Process results via messageManager (may not be visible during shutdown)
             this.hookManager.processHookResults("WorktreeRemove", hookResults, this.messageManager);

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/managers/aiManager.d.ts

@@ -53,6 +53,14 @@ export declare class AIManager {
     private get permissionManager();
     private get planManager();
     private get configurationService();
+    /**
+     * OS env merged with the per-session env snapshot. Falls back to process.env
+     * when ConfigurationService is absent or its getMergedEnv is missing (e.g. in
+     * unit tests with partial mocks), so hook-context env construction never
+     * throws. Use this (not the non-null `configurationService` getter) when
+     * building hook context env.
+     */
+    private get mergedEnv();
     getGatewayConfig(): GatewayConfig;
     getModelConfig(): ModelConfig;
     getMaxInputTokens(): number;

package/dist/managers/aiManager.js

@@ -99,9 +99,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")
@@ -1262,7 +1277,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 +1432,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 +1499,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 +1552,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) {

package/dist/managers/mcpManager.d.ts

@@ -11,13 +11,21 @@ export interface McpManagerOptions {
     /** Pre-configured MCP servers passed from constructor options */
     mcpServers?: Record<string, McpServerConfig>;
 }
-export declare 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 declare function expandEnvVars(value: string, env?: Record<string, string | undefined>): string;
 /**
  * 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 declare function resolveMcpConfig(config: McpConfig): McpConfig;
+export declare function resolveMcpConfig(config: McpConfig, env?: Record<string, string | undefined>): McpConfig;
 export declare class McpManager {
     private container;
     private config;
@@ -30,6 +38,12 @@ export declare class McpManager {
     private reconnectTimers;
     private reconnectAttempts;
     constructor(container: Container, options?: McpManagerOptions);
+    /**
+     * 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();
     /**
      * Initialize MCP manager with working directory and optionally auto-connect
      */

package/dist/managers/mcpManager.js

@@ -11,7 +11,15 @@ import { logger } from "../utils/globalLogger.js";
  * Supports ${VAR} and ${VAR:-default} patterns.
  */
 const WAVE_TEMPLATE_VARS = ["WAVE_PLUGIN_ROOT", "CLAUDE_PLUGIN_ROOT"];
-export function expandEnvVars(value) {
+/**
+ * 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, env = process.env) {
     return value.replace(/\$\{([^}]+)\}/g, (_match, expr) => {
         const [varName, ...rest] = expr.split(":-");
         const defaultValue = rest.join(":-");
@@ -19,38 +27,38 @@ export function expandEnvVars(value) {
         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) {
+export function resolveMcpConfig(config, env = process.env) {
     const resolved = { mcpServers: {} };
     for (const [name, serverConfig] of Object.entries(config.mcpServers)) {
         const resolvedServer = { ...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 = {};
             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 = {};
             for (const [key, val] of Object.entries(resolvedServer.headers)) {
-                resolvedHeaders[key] = expandEnvVars(val);
+                resolvedHeaders[key] = expandEnvVars(val, env);
             }
             resolvedServer.headers = resolvedHeaders;
         }
@@ -71,6 +79,16 @@ export class McpManager {
         this.callbacks = options.callbacks || {};
         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.
+     */
+    get envSnapshot() {
+        return (this.container
+            .get("ConfigurationService")
+            ?.getMergedEnv?.() ?? process.env);
+    }
     /**
      * Initialize MCP manager with working directory and optionally auto-connect
      */
@@ -125,7 +143,7 @@ export class McpManager {
         try {
             const configContent = await fs.readFile(this.configPath, "utf-8");
             const rawConfig = JSON.parse(configContent);
-            const workspaceConfig = resolveMcpConfig(rawConfig);
+            const workspaceConfig = resolveMcpConfig(rawConfig, this.envSnapshot);
             // Extract original (pre-resolution) URLs for safe display
             const originalUrls = {};
             for (const [name, serverConfig] of Object.entries(rawConfig.mcpServers)) {
@@ -210,28 +228,29 @@ 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 = { ...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 = {};
             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 = {};
             for (const [key, val] of Object.entries(resolvedConfig.headers)) {
-                resolvedHeaders[key] = expandEnvVars(val);
+                resolvedHeaders[key] = expandEnvVars(val, env);
             }
             resolvedConfig.headers = resolvedHeaders;
         }
@@ -332,8 +351,11 @@ export class McpManager {
                 if (!server.config.command) {
                     throw new Error(`MCP server ${name} with type "stdio" requires a 'command'`);
                 }
+                // 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 = {
-                    ...process.env,
+                    ...this.envSnapshot,
                     ...(server.config.env || {}),
                 };
                 // For plugin servers, substitute ${WAVE_PLUGIN_ROOT} and ${CLAUDE_PLUGIN_ROOT}

package/dist/managers/toolManager.js

@@ -179,6 +179,11 @@ class ToolManager {
             workflowManager: this.container.has("WorkflowManager")
                 ? this.container.get("WorkflowManager")
                 : undefined,
+            sessionEnv: this.container.has("ConfigurationService")
+                ? this.container
+                    .get("ConfigurationService")
+                    ?.getMergedEnv?.()
+                : undefined,
             sessionId: context.sessionId,
             toolCallId: context.toolCallId,
         };