wave-agent-sdk 0.19.9 → 1.0.0

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);

package/dist/services/interactionService.js

@@ -48,7 +48,7 @@ export class InteractionService {
                         transcriptPath: messageManager.getTranscriptPath(),
                         cwd: workdir,
                         userPrompt: content,
-                        env: Object.fromEntries(Object.entries(process.env).filter((e) => e[1] !== undefined)), // Include environment variables
+                        env: Object.fromEntries(Object.entries(context.configurationService.getMergedEnv()).filter((e) => e[1] !== undefined)), // Include environment variables
                     });
                     // Process hook results and determine if we should continue
                     const processResult = hookManager.processHookResults("UserPromptSubmit", hookResults, messageManager);
@@ -76,7 +76,7 @@ export class InteractionService {
         }
     }
     static async restoreSession(context, sessionId) {
-        const { messageManager, logger, subagentManager, taskManager, options, abortMessage, } = context;
+        const { messageManager, hookManager, logger, subagentManager, taskManager, options, abortMessage, } = context;
         // 1. Validation
         if (!sessionId || sessionId === messageManager.getSessionId()) {
             return; // No-op if session ID is invalid or already current
@@ -89,21 +89,49 @@ export class InteractionService {
             logger?.warn("Failed to save current session before restore:", error);
             // 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.message}`);
+            }
+        }
+        // 4. Load target session
         const sessionData = await loadSessionFromJsonl(sessionId, messageManager.getWorkdir());
         if (!sessionData) {
             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.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/dist/services/remoteSettingsService.d.ts

@@ -6,6 +6,17 @@ import type { WaveConfiguration } from "../types/configuration.js";
  */
 export declare function onSettingsUpdate(callback: () => void | Promise<void>): () => void;
 export declare function initialize(): void;
+/**
+ * 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 declare function startBackgroundFetch(): void;
 export declare function getRemoteSettingsSync(): WaveConfiguration | null;
 export declare function refresh(): Promise<RemoteSettingsFetchResult>;
 export declare function clear(): void;
@@ -17,6 +28,7 @@ export declare function mergeRemoteSettings(localMerged: WaveConfiguration, remo
  */
 export declare const remoteSettingsService: {
     readonly initialize: typeof initialize;
+    readonly startBackgroundFetch: typeof startBackgroundFetch;
     readonly getRemoteSettingsSync: typeof getRemoteSettingsSync;
     readonly refresh: typeof refresh;
     readonly clear: typeof clear;

package/dist/services/remoteSettingsService.js

@@ -174,8 +174,21 @@ function startPolling() {
     _pollingTimer.unref();
 }
 export function initialize() {
+    // 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() {
     fetchRemoteSettings()
         .then(() => startPolling())
         .catch((err) => {
@@ -302,6 +315,7 @@ export function mergeRemoteSettings(localMerged, remote) {
  */
 export const remoteSettingsService = {
     initialize,
+    startBackgroundFetch,
     getRemoteSettingsSync,
     refresh,
     clear,

package/dist/services/taskManager.js

@@ -32,7 +32,13 @@ 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")
+            ?.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/dist/tools/bashTool.js

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

package/dist/tools/enterWorktreeTool.js

@@ -2,7 +2,7 @@
  * EnterWorktree tool - creates an isolated git worktree and switches the session into it.
  * Mirrors Claude Code's EnterWorktree tool behavior and prompt.
  */
-import { createWorktree, validateWorktreeName, generateWorktreeName, } from "../utils/worktreeUtils.js";
+import { createWorktree, validateWorktreeName, generateWorktreeName, performPostCreationSetup, } from "../utils/worktreeUtils.js";
 import { getGitMainRepoRoot } from "../utils/gitUtils.js";
 import { ENTER_WORKTREE_TOOL_NAME } from "../constants/tools.js";
 import { logger } from "../utils/globalLogger.js";
@@ -85,6 +85,17 @@ export const enterWorktreeTool = {
         // Create the worktree (captures originalHeadCommit internally)
         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 = {
             originalCwd: context.workdir,
@@ -110,10 +121,10 @@ export const enterWorktreeTool = {
                     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)),
+                    env: Object.fromEntries(Object.entries(context.sessionEnv ?? process.env).filter((e) => e[1] !== undefined)),
                 });
                 if (context.messageManager) {
                     context.hookManager.processHookResults("WorktreeCreate", hookResults, context.messageManager);

package/dist/tools/exitWorktreeTool.js

@@ -128,14 +128,8 @@ export const exitWorktreeTool = {
         };
         // Count changes BEFORE removing the worktree (directory will be gone after)
         const summary = countWorktreeChanges(worktreePath, session.originalHeadCommit) ?? { changedFiles: 0, commits: 0 };
-        removeWorktree(worktreeInfo);
-        // Clear session state and restore CWD
-        const aiManager = context.aiManager;
-        if (aiManager) {
-            aiManager.setWorktreeSession(null);
-            aiManager.setWorkdir(originalCwd);
-        }
-        // Trigger WorktreeRemove hook (non-blocking)
+        // Trigger WorktreeRemove hook (non-blocking) BEFORE git removal so hooks
+        // can still read files inside the worktree to clean up external resources.
         let hookTriggered = false;
         if (context.hookManager) {
             try {
@@ -144,10 +138,10 @@ export const exitWorktreeTool = {
                     projectDir: originalCwd,
                     timestamp: new Date(),
                     sessionId: context.sessionId ?? "",
-                    transcriptPath: context.messageManager?.getTranscriptPath() ?? "",
+                    transcriptPath: context.messageManager?.getTranscriptPath?.() ?? "",
                     cwd: originalCwd,
                     worktreePath,
-                    env: Object.fromEntries(Object.entries(process.env).filter((e) => e[1] !== undefined)),
+                    env: Object.fromEntries(Object.entries(context.sessionEnv ?? process.env).filter((e) => e[1] !== undefined)),
                 });
                 if (context.messageManager) {
                     context.hookManager.processHookResults("WorktreeRemove", hookResults, context.messageManager);
@@ -159,6 +153,13 @@ export const exitWorktreeTool = {
                 logger?.warn("WorktreeRemove hooks execution failed:", error);
             }
         }
+        removeWorktree(worktreeInfo);
+        // Clear session state and restore CWD
+        const aiManager = context.aiManager;
+        if (aiManager) {
+            aiManager.setWorktreeSession(null);
+            aiManager.setWorkdir(originalCwd);
+        }
         const discardParts = [];
         if (summary.commits > 0) {
             discardParts.push(`${summary.commits} ${summary.commits === 1 ? "commit" : "commits"}`);

package/dist/tools/types.d.ts

@@ -104,4 +104,11 @@ export interface ToolContext {
     originalWorkdir?: string;
     /** Workflow manager instance for workflow orchestration */
     workflowManager?: import("../managers/workflowManager.js").WorkflowManager;
+    /**
+     * Per-session merged environment (OS env overlaid with the settings env
+     * snapshot) for this session. Tools that spawn subprocesses (Bash, hooks)
+     * should merge this on top of `process.env` so settings `env` vars reach
+     * the subprocess without polluting other sessions in one stdio process.
+     */
+    sessionEnv?: Record<string, string>;
 }

package/dist/types/config.d.ts

@@ -10,6 +10,8 @@ export interface GatewayConfig {
     defaultHeaders?: Record<string, string>;
     fetchOptions?: OpenAI["fetchOptions"];
     fetch?: OpenAI["fetch"];
+    /** Session identifier, sent as the `x-session-id` request header for backend correlation. */
+    sessionId?: string;
 }
 export interface ModelCapabilities {
     /** Whether the model supports image/vision input. Default: true. */

package/dist/types/hooks.d.ts

@@ -54,8 +54,8 @@ export declare class HookConfigurationError extends Error {
     readonly validationErrors: string[];
     constructor(configPath: string, validationErrors: string[]);
 }
-export type SessionStartSource = "startup" | "compact" | "clear";
-export type SessionEndSource = "exit" | "stop" | "compact" | "clear";
+export type SessionStartSource = "startup" | "resume" | "compact" | "clear";
+export type SessionEndSource = "exit" | "resume" | "stop" | "compact" | "clear";
 export declare function isValidHookEvent(event: string): event is HookEvent;
 export declare function isValidHookCommand(cmd: unknown): cmd is HookCommand;
 export declare function isValidHookEventConfig(config: unknown): config is HookEventConfig;

package/dist/utils/containerSetup.js

@@ -159,7 +159,7 @@ export function setupAgentContainer(setupOptions) {
                     toolName: context.toolName,
                     toolInput: context.toolInput,
                     planFilePath: permissionManager.getPlanFilePath(),
-                    env: Object.fromEntries(Object.entries(process.env).filter((e) => e[1] !== undefined)),
+                    env: Object.fromEntries(Object.entries(configurationService.getMergedEnv()).filter((e) => e[1] !== undefined)),
                 });
                 if (results.length > 0) {
                     const processResult = hookManager.processHookResults("PermissionRequest", results, messageManager);

package/dist/utils/openaiClient.js

@@ -36,11 +36,12 @@ export class OpenAIClient {
         };
     }
     async _create(params, options) {
-        const { baseURL, apiKey, defaultHeaders, fetchOptions, fetch: customFetch, } = this.config;
+        const { baseURL, apiKey, sessionId, defaultHeaders, fetchOptions, fetch: customFetch, } = this.config;
         const url = `${baseURL}/chat/completions`;
         const headers = {
             "Content-Type": "application/json",
             ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+            ...(sessionId ? { "x-session-id": sessionId } : {}),
             ...defaultHeaders,
         };
         const fetchFn = customFetch || fetch;

package/dist/utils/pathEncoder.js

@@ -127,8 +127,13 @@ export class PathEncoder {
             // If realpath fails, use the absolute path
             resolvedPath = absolutePath;
         }
-        // Encode the resolved path
-        const encodedName = await this.encode(resolvedPath);
+        // Encode the resolved path. Use encodeSync (pure string transform) rather
+        // than encode(): realpath was already attempted above with its own fallback,
+        // so re-resolving via encode()->resolvePath() would throw ENOENT again when
+        // the workdir no longer exists (e.g. a deleted worktree during agent
+        // shutdown). Session files live under <baseSessionDir>/<encoded>/ regardless
+        // of the workdir's existence, so encoding must not require it to exist.
+        const encodedName = this.encodeSync(resolvedPath);
         const encodedPath = join(baseSessionDir, encodedName);
         // Generate hash if encoding resulted in truncation
         let pathHash;

package/dist/utils/worktreeUtils.d.ts

@@ -33,10 +33,27 @@ export declare function getHeadCommit(cwd: string): string;
 export declare function createWorktree(name: string, cwd: string, options?: {
     baseRef?: "fresh" | "head";
 }): WorktreeInfo;
+/**
+ * Set up a freshly created worktree: copy local settings and gitignored
+ * project files (via .worktreeinclude) from the main repo. Best-effort — any
+ * failure only logs a warning and never fails worktree creation.
+ */
+export declare function performPostCreationSetup(worktreePath: string, repoRoot: string): Promise<void>;
 /**
  * Remove a git worktree and its branch.
  */
 export declare function removeWorktree(info: WorktreeInfo): void;
+/**
+ * Validate that a worktree path is safe to remove before running git removal.
+ * Aligns with Claude Code v2.1.216+ background-session checks:
+ * - rejects a path whose final component is a symlink;
+ * - rejects a path that resolves outside the repo root.
+ *
+ * A path that no longer exists (worktree already removed) is allowed so that
+ * removal stays best-effort/idempotent; its nearest existing ancestor is used
+ * for the containment check. Throws an Error on invalid paths.
+ */
+export declare function validateWorktreeRemovalPath(worktreePath: string, repoRoot: string): void;
 /**
  * Count uncommitted files and new commits in a worktree.
  * Returns null if git commands fail (fail-closed).