Activate Python environments in Agent Host shell commands with shell init scripts

src/vs/platform/agentHost/common/agentHostSchema.ts

@@ -11,6 +11,7 @@ import type { IMcpServerConfiguration } from '../../mcp/common/mcpPlatformTypes.
 import { TelemetryConfiguration, TelemetryLevel } from '../../telemetry/common/telemetry.js';
 import { telemetryLevelToAgentHostValue } from './agentHostTelemetry.js';
 import { SessionConfigKey } from './sessionConfigKeys.js';
+import type { IShellInitScript } from './shellInitScript.js';
 import type { SessionConfigPropertySchema, SessionConfigSchema } from './state/protocol/commands.js';
 import { JsonRpcErrorCodes, ProtocolError } from './state/sessionProtocol.js';
 
@@ -299,6 +300,41 @@ const permissionsProperty = schemaProperty<IPermissionsValue>({
 	sessionMutable: true,
 });
 
+/**
+ * Scripts the client generated for this session, sourced before every built-in
+ * shell tool command (see `common/shellInitScript.ts`). Written by the
+ * workbench and consumed by the Copilot provider; `readOnly` because no user
+ * edits it directly, `sessionMutable` because the selected Python environment
+ * can change while a session is live. The value is transient and omitted from
+ * persisted session config.
+ *
+ * Deliberately has no `default`: an absent value means "nothing to apply",
+ * which must stay distinguishable from an explicit empty array (clear).
+ */
+const shellInitSnippetsProperty = schemaProperty<readonly IShellInitScript[]>({
+	type: 'array',
+	title: localize('agentHost.sessionConfig.shellInitSnippets', "Shell Init Script"),
+	description: localize('agentHost.sessionConfig.shellInitSnippetsDescription', "A script sourced before each built-in shell tool command."),
+	items: {
+		type: 'object',
+		title: localize('agentHost.sessionConfig.shellInitSnippets.item', "Shell Init Script"),
+		properties: {
+			shell: {
+				type: 'string',
+				title: localize('agentHost.sessionConfig.shellInitSnippets.shell', "Shell"),
+				enum: ['bash', 'powershell'],
+			},
+			script: {
+				type: 'string',
+				title: localize('agentHost.sessionConfig.shellInitSnippets.script', "Script"),
+			},
+		},
+		required: ['shell', 'script'],
+	},
+	readOnly: true,
+	sessionMutable: true,
+});
+
 /**
  * Session-config properties owned by the platform itself — i.e. consumed
  * by the agent host rather than by any particular agent.
@@ -345,6 +381,7 @@ export const platformSessionSchema = createSchema({
 		default: 'interactive',
 		sessionMutable: true,
 	}),
+	[SessionConfigKey.ShellInitSnippets]: shellInitSnippetsProperty,
 });
 
 /**

src/vs/platform/agentHost/common/copilotCliConfig.ts

@@ -52,6 +52,9 @@ export const CopilotCliVSCodeAssignmentContextKey = 'copilotCliVSCodeAssignmentC
 
 export const AgentHostCustomTerminalToolEnabledSettingId = 'chat.agentHost.customTerminalTool.enabled';
 
+/** Enable VS Code's generated init script for the SDK built-in shell tool. */
+export const AgentHostShellToolInitScriptEnabledSettingId = 'chat.agentHost.shellTool.initScript.enabled';
+
 export const AgentHostCopilotSdkLogLevelSettingId = 'chat.agentHost.copilotSdk.logLevel';
 
 export const AgentHostOpus48PromptEnabledSettingId = 'chat.agentHost.opus48Prompt.enabled';

src/vs/platform/agentHost/common/sessionConfigKeys.ts

@@ -39,6 +39,8 @@ export const enum SessionConfigKey {
 	AgentMerge = 'agentMerge',
 	/** `'agentMerge.controller'` — host-owned Agent Merge lifecycle state. */
 	AgentMergeController = 'agentMerge.controller',
+	/** `'shellInitSnippets'` — host-generated scripts sourced before built-in shell tool commands. */
+	ShellInitSnippets = 'shellInitSnippets',
 }
 
 /**
@@ -58,3 +60,13 @@ export const KNOWN_AUTO_APPROVE_VALUES: ReadonlySet<string> = new Set(['default'
  * property: the agent execution mode axis.
  */
 export const KNOWN_MODE_VALUES: ReadonlySet<string> = new Set(['interactive', 'plan', 'autopilot']);
+
+/**
+ * Removes session config that is derived from live client state and must not
+ * survive an Agent Host restart.
+ */
+export function omitTransientSessionConfigValues<T>(values: Record<string, T>): Record<string, T> {
+	const result = { ...values };
+	delete result[SessionConfigKey.ShellInitSnippets];
+	return result;
+}

src/vs/platform/agentHost/common/shellInitScript.ts

@@ -0,0 +1,142 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+import { encodeBase64, VSBuffer } from '../../../base/common/buffer.js';
+import { AgentHostClientType } from './agentHostClientInfo.js';
+import { SessionConfigKey } from './sessionConfigKeys.js';
+
+export type ShellInitScriptShell = 'bash' | 'powershell';
+
+/**
+ * One host-generated script sourced before every SDK built-in shell command.
+ * The array-valued session config carries either no script (`[]`) or this one
+ * script, so clearing a previously applied script is explicit.
+ */
+export interface IShellInitScript {
+	readonly shell: ShellInitScriptShell;
+	readonly script: string;
+}
+
+export const SHELL_INIT_SCRIPT_EDITOR_ONLY_ERROR = 'Shell init script config can only be set by an Editor Window client.';
+
+/**
+ * Returns an authorization error for executable shell-init config.
+ * Any client may clear the capability with `[]`; only Editor Windows may add
+ * executable text.
+ */
+export function getShellInitScriptConfigWriteError(config: Record<string, unknown>, clientType: AgentHostClientType): string | undefined {
+	if (!Object.hasOwn(config, SessionConfigKey.ShellInitSnippets)) {
+		return undefined;
+	}
+	const value = config[SessionConfigKey.ShellInitSnippets];
+	if (Array.isArray(value) && value.length === 0) {
+		return undefined;
+	}
+	return clientType === AgentHostClientType.EditorWindow ? undefined : SHELL_INIT_SCRIPT_EDITOR_ONLY_ERROR;
+}
+
+function quoteBash(value: string): string {
+	return `'${value.replaceAll(`'`, `'\\''`)}'`;
+}
+
+function encodedPowerShellExpression(value: string): string {
+	const encoded = encodeBase64(VSBuffer.fromString(value));
+	return `[System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String('${encoded}'))`;
+}
+
+function powerShellBlock(body: readonly string[], failureMessage: string): string[] {
+	return [
+		`$__vscodePreviousErrorActionPreference = $ErrorActionPreference`,
+		`try {`,
+		`\t$ErrorActionPreference = 'Stop'`,
+		...body,
+		`} catch {`,
+		`\tWrite-Output '${failureMessage.replaceAll(`'`, `''`)}'`,
+		`} finally {`,
+		`\t$ErrorActionPreference = $__vscodePreviousErrorActionPreference`,
+		`}`,
+	];
+}
+
+/**
+ * Creates the single script VS Code registers with the SDK shell tool.
+ *
+ * Profile loading comes first so activation runs against the user's shell
+ * setup. Activation is whatever command the Python Environments extension
+ * published for the folder; nothing tool-specific is added here.
+ *
+ * Every script ends successfully: the runtime reports a nonzero init-script
+ * status before every later command, and discards Bash init-script stderr.
+ */
+export function createShellInitScript(shell: ShellInitScriptShell, pythonActivation: string | undefined): IShellInitScript {
+	return shell === 'powershell'
+		? createPowerShellInitScript(pythonActivation)
+		: createBashInitScript(pythonActivation);
+}
+
+function createBashInitScript(pythonActivation: string | undefined): IShellInitScript {
+	const lines = [
+		`# Generated by VS Code for Agent Host shell commands.`,
+		`if [ -r "$HOME/.bashrc" ]; then`,
+		// An rc file's status is the status of its final command. A nonzero
+		// status therefore does not mean profile setup failed.
+		`\tbuiltin source "$HOME/.bashrc" || builtin true`,
+		`fi`,
+	];
+	if (pythonActivation?.trim()) {
+		lines.push(
+			`if ! builtin eval ${quoteBash(pythonActivation)}; then`,
+			`\tprintf '%s\\n' 'copilot shell init: Python activation failed; continuing without the selected environment.'`,
+			`fi`,
+		);
+	}
+	lines.push(`builtin true`, ``);
+	return { shell: 'bash', script: lines.join('\n') };
+}
+
+function createPowerShellInitScript(pythonActivation: string | undefined): IShellInitScript {
+	// Profiles load with their normal 'Continue' preference — the runtime
+	// sources init scripts under 'Stop', which would let one benign
+	// non-terminating profile error skip everything after it. Each profile has
+	// its own try/catch so a broken profile does not skip the next one, and a
+	// preference a profile sets deliberately carries forward, as in a real
+	// session. The activation block below manages its own preference.
+	const lines = [
+		`# Generated by VS Code for Agent Host shell commands.`,
+		`$ErrorActionPreference = 'Continue'`,
+		`foreach ($__vscodeProfile in @($PROFILE.CurrentUserAllHosts, $PROFILE.CurrentUserCurrentHost)) {`,
+		`\ttry {`,
+		`\t\tif ($__vscodeProfile -and (Test-Path -LiteralPath $__vscodeProfile)) {`,
+		`\t\t\t. $__vscodeProfile`,
+		`\t\t}`,
+		`\t} catch {`,
+		`\t\tWrite-Output 'copilot shell init: loading the PowerShell profile failed; continuing.'`,
+		`\t}`,
+		`}`,
+	];
+	if (pythonActivation?.trim()) {
+		lines.push(...powerShellBlock(
+			[`\tInvoke-Expression (${encodedPowerShellExpression(pythonActivation)})`],
+			'copilot shell init: Python activation failed; continuing without the selected environment.',
+		));
+	}
+	lines.push(`$global:LASTEXITCODE = 0`, ``);
+	return { shell: 'powershell', script: lines.join('\n') };
+}
+
+/** Validates the client-pushed list before the agent host writes it to disk. */
+export function isShellInitScriptList(value: unknown): value is readonly IShellInitScript[] {
+	return Array.isArray(value)
+		&& value.length <= 1
+		&& value.every(entry => {
+			if (!entry || typeof entry !== 'object') {
+				return false;
+			}
+			const script = entry as Partial<IShellInitScript>;
+			return (script.shell === 'bash' || script.shell === 'powershell')
+				&& typeof script.script === 'string'
+				&& script.script.length > 0;
+		});
+}

src/vs/platform/agentHost/node/agentService.ts

@@ -23,7 +23,7 @@ import { AgentChatMigrationDeferred, AgentProvider, AgentSession, AgentSignal, I
 import { type AgentHostDebugLogsArtifactKind, type IAgentHostDebugLogsArtifact, type IAgentHostDebugLogsChunk, IAgentHostManagedSettingsDiagnostics, IAgentHostNetworkDiagnosticsInfo, IAgentHostNetworkFetchResult, IAgentService } from '../common/agentService.js';
 import { ISessionDataService, SESSION_ATTACHMENTS_DIRNAME } from '../common/sessionDataService.js';
 import { IAgentEditAttributionService, ICancelEditAttributionFlushParams, ICommitEditAttributionFlushParams, IEditAttributionFlushResult, IPrepareEditAttributionFlushParams, IPreparedEditAttributionFlush, parseEditAttributionResource } from '../common/fileEditAttribution.js';
-import { SessionConfigKey } from '../common/sessionConfigKeys.js';
+import { omitTransientSessionConfigValues, SessionConfigKey } from '../common/sessionConfigKeys.js';
 import type { IAgentCustomizationSettingsRegistration } from '../common/agentCustomizationSettings.js';
 import { buildAnnotationsUri, parseAnnotationsUri } from '../common/annotationsUri.js';
 import { AGENT_HOST_AUTOMATION_MIGRATION_CONFIG_KEY, isAgentHostAutomationMigrationCompletion } from '../common/automationMigration.js';
@@ -81,6 +81,7 @@ import { ICopilotApiService } from './shared/copilotApiService.js';
 import { INetworkDiagnosticsService } from './networkDiagnosticsService.js';
 import { toAgentClientUri } from '../common/agentClientUri.js';
 import { AgentHostClientType } from '../common/agentHostClientInfo.js';
+import { getShellInitScriptConfigWriteError } from '../common/shellInitScript.js';
 import { resolveLastNonLocalTurnId } from '../common/agentHostConversationContext.js';
 import { AgentHostLaunchKind, createUnknownAgentHostClientTelemetryContext, type IAgentHostClientTelemetryContext } from '../common/agentHostTelemetry.js';
 import { IAgentHostGitHubEndpointService } from './agentHostGitHubEndpointService.js';
@@ -2973,9 +2974,12 @@ export class AgentService extends Disposable implements IAgentService {
 		this._syncAgentMergeIndex(session, undefined, sessionConfig);
 		this._serverToolHost.advertise(session.toString());
 		// Persist resolved config values for restore. Mid-session updates are
-		// persisted by `AgentSideEffects` on `SessionConfigChanged`.
+		// persisted by `SessionFlagsContribution` on `SessionConfigChanged`.
 		if (sessionConfig?.values && Object.keys(sessionConfig.values).length > 0 && !created.provisional) {
-			this._persistConfigValues(session, sessionConfig.values);
+			const persistedConfigValues = omitTransientSessionConfigValues(sessionConfig.values);
+			if (Object.keys(persistedConfigValues).length > 0) {
+				this._persistConfigValues(session, persistedConfigValues);
+			}
 		}
 
 		this._changesetCoordinator.onSessionCreated(session.toString());
@@ -3705,7 +3709,10 @@ export class AgentService extends Disposable implements IAgentService {
 		};
 		const configValues = state.config?.values;
 		if (configValues && Object.keys(configValues).length > 0) {
-			this._persistConfigValues(session, configValues);
+			const persistedConfigValues = omitTransientSessionConfigValues(configValues);
+			if (Object.keys(persistedConfigValues).length > 0) {
+				this._persistConfigValues(session, persistedConfigValues);
+			}
 		}
 		// Persist the AH-owned workspace-less marker now that the session has a
 		// real on-disk database (deferred from create for provisional sessions).
@@ -4508,6 +4515,10 @@ export class AgentService extends Disposable implements IAgentService {
 			? createUnknownAgentHostClientTelemetryContext(clientContextOrType)
 			: clientContextOrType;
 		this._logService.trace(`[AgentService] dispatchAction: type=${action.type}, clientId=${clientId}, clientSeq=${clientSeq}`, action);
+		if (action.type === ActionType.RootConfigChanged && Object.hasOwn(action.config, SessionConfigKey.ShellInitSnippets)) {
+			this._stateManager.rejectClientAction(channel, action, { clientId, clientSeq }, 'Shell init script config is session-only and cannot be set in root config.');
+			return;
+		}
 		if (action.type === ActionType.RootConfigChanged && Object.hasOwn(action.config, AGENT_HOST_AUTOMATION_MIGRATION_CONFIG_KEY)) {
 			const migration = action.config[AGENT_HOST_AUTOMATION_MIGRATION_CONFIG_KEY];
 			const origin = { clientId, clientSeq };
@@ -4757,12 +4768,29 @@ export class AgentService extends Disposable implements IAgentService {
 		// watermark, attempt budgets), so a client must never be able to write it, and
 		// a wholesale replacement must not drop it either.
 		if (action.type === ActionType.SessionConfigChanged) {
-			const configAction = action as SessionConfigChangedAction;
+			let configAction = action as SessionConfigChangedAction;
 			const forbidden = HOST_WRITTEN_SESSION_CONFIG_KEYS.filter(key => Object.hasOwn(configAction.config, key));
 			if (forbidden.length > 0) {
 				this._stateManager.rejectClientAction(channel, action, origin, `Session config keys are host-owned and cannot be set by a client: ${forbidden.join(', ')}.`);
 				return;
 			}
+			const editorClient = clientContext.clientType === AgentHostClientType.EditorWindow;
+			const writesShellInit = Object.hasOwn(configAction.config, SessionConfigKey.ShellInitSnippets);
+			const shellInitWriteError = getShellInitScriptConfigWriteError(configAction.config, clientContext.clientType);
+			if (shellInitWriteError) {
+				this._stateManager.rejectClientAction(channel, action, origin, shellInitWriteError);
+				return;
+			}
+			if (!editorClient && configAction.replace && !writesShellInit) {
+				const existingShellInit = this._stateManager.getSessionState(sessionChannel)?.config?.values[SessionConfigKey.ShellInitSnippets];
+				if (existingShellInit !== undefined) {
+					configAction = {
+						...configAction,
+						config: { ...configAction.config, [SessionConfigKey.ShellInitSnippets]: existingShellInit },
+					};
+					action = configAction;
+				}
+			}
 			if (configAction.replace) {
 				action = this._withPreservedHostWrittenSessionConfig(sessionChannel, configAction);
 			}
@@ -5562,7 +5590,7 @@ export class AgentService extends Disposable implements IAgentService {
 
 						if (m.configValues) {
 							try {
-								persistedConfigValues = JSON.parse(m.configValues);
+								persistedConfigValues = omitTransientSessionConfigValues(JSON.parse(m.configValues));
 							} catch (err) {
 								this._logService.warn(`[AgentService] Failed to parse persisted configValues for ${sessionStr}: ${toErrorMessage(err)}`);
 							}

src/vs/platform/agentHost/node/chatContributions/sessionFlags/sessionFlagsContribution.ts

@@ -9,6 +9,7 @@ import type { IAgentHostChatContribution, IAgentHostChatContributionContext, IDi
 import { ISessionDataService } from '../../../common/sessionDataService.js';
 import { ActionType } from '../../../common/state/sessionActions.js';
 import { AH_META_IS_ARCHIVED_DB_KEY, AH_META_IS_READ_DB_KEY } from '../../../common/state/sessionState.js';
+import { omitTransientSessionConfigValues } from '../../../common/sessionConfigKeys.js';
 import { AgentHostStateManager, IAgentHostStateManager } from '../../agentHostStateManager.js';
 import { persistSessionMetadata } from '../../shared/persistSessionMetadata.js';
 
@@ -35,7 +36,7 @@ export class SessionFlagsContribution extends Disposable implements IAgentHostCh
 		if (dispatched.action.type === ActionType.SessionConfigChanged) {
 			const values = this._stateManager.getSessionState(dispatched.channel)?.config?.values;
 			if (values) {
-				persistSessionMetadata(this._sessionDataService, this._logService, dispatched.channel, 'configValues', JSON.stringify(values));
+				persistSessionMetadata(this._sessionDataService, this._logService, dispatched.channel, 'configValues', JSON.stringify(omitTransientSessionConfigValues(values)));
 			}
 		}
 		// Persisting here rather than in `handleAction` covers client- and