microsoft
diff --git a/‎src/vs/platform/agentHost/common/agentHostSchema.ts‎
Lines changed: 37 additions & 0 deletions b/‎src/vs/platform/agentHost/common/agentHostSchema.ts‎
Lines changed: 37 additions & 0 deletions
diff --git a/‎src/vs/platform/agentHost/common/copilotCliConfig.ts‎
Lines changed: 11 additions & 0 deletions b/‎src/vs/platform/agentHost/common/copilotCliConfig.ts‎
Lines changed: 11 additions & 0 deletions
diff --git a/‎src/vs/platform/agentHost/common/sessionConfigKeys.ts‎
Lines changed: 12 additions & 0 deletions b/‎src/vs/platform/agentHost/common/sessionConfigKeys.ts‎
Lines changed: 12 additions & 0 deletions
diff --git a/‎src/vs/platform/agentHost/common/shellInitScript.ts‎
Lines changed: 127 additions & 0 deletions b/‎src/vs/platform/agentHost/common/shellInitScript.ts‎
Lines changed: 127 additions & 0 deletions
diff --git a/‎src/vs/platform/agentHost/node/agentService.ts‎
Lines changed: 11 additions & 5 deletions b/‎src/vs/platform/agentHost/node/agentService.ts‎
Lines changed: 11 additions & 5 deletions
diff --git a/‎src/vs/platform/agentHost/node/chatContributions/sessionFlags/sessionFlagsContribution.ts‎
Lines changed: 2 additions & 1 deletion b/‎src/vs/platform/agentHost/node/chatContributions/sessionFlags/sessionFlagsContribution.ts‎
Lines changed: 2 additions & 1 deletion
@@ -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 shellInitScriptsProperty = schemaProperty<readonly IShellInitScript[]>({
+	type: 'array',
+	title: localize('agentHost.sessionConfig.shellInitScripts', "Shell Init Script"),
+	description: localize('agentHost.sessionConfig.shellInitScriptsDescription', "A script sourced before each built-in shell tool command."),
+	items: {
+		type: 'object',
+		title: localize('agentHost.sessionConfig.shellInitScripts.item', "Shell Init Script"),
+		properties: {
+			shell: {
+				type: 'string',
+				title: localize('agentHost.sessionConfig.shellInitScripts.shell', "Shell"),
+				enum: ['bash', 'powershell'],
+			},
+			script: {
+				type: 'string',
+				title: localize('agentHost.sessionConfig.shellInitScripts.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.ShellInitScripts]: shellInitScriptsProperty,
 });
 
 /**
 
@@ -16,6 +16,8 @@ import { reasoningEffortLevels } from './reasoningEffort.js';
 export const enum CopilotCliConfigKey {
 	/** Use Agent Host's custom terminal tool instead of the SDK's default. Off by default. */
 	EnableCustomTerminalTool = 'enableCustomTerminalTool',
+	/** Apply the shell init script a client published for a session to SDK shell commands. Off by default. */
+	EnableShellInitScript = 'enableShellInitScript',
 	/** Log level passed to the Copilot SDK client. */
 	CopilotSdkLogLevel = 'copilotSdkLogLevel',
 	/** Enable the rubber duck critic subagent. */
@@ -52,6 +54,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';
@@ -148,6 +153,12 @@ export const copilotCliConfigSchema = createSchema({
 		description: localize('agentHost.config.enableCustomTerminalTool.description', "When enabled, Copilot SDK sessions use Agent Host's terminal tool override instead of the SDK's default terminal behavior."),
 		default: false,
 	}),
+	[CopilotCliConfigKey.EnableShellInitScript]: schemaProperty<boolean>({
+		type: 'boolean',
+		title: localize('agentHost.config.enableShellInitScript.title', "Shell Init Script"),
+		description: localize('agentHost.config.enableShellInitScript.description', "When enabled, Copilot SDK sessions apply the shell init script published by the client before each shell command."),
+		default: false,
+	}),
 	[CopilotCliConfigKey.CopilotSdkLogLevel]: schemaProperty<CopilotSdkLogLevelSetting>({
 		type: 'string',
 		title: localize('agentHost.config.copilotSdkLogLevel.title', "Copilot SDK Log Level"),
 
@@ -39,6 +39,8 @@ export const enum SessionConfigKey {
 	AgentMerge = 'agentMerge',
 	/** `'agentMerge.controller'` — host-owned Agent Merge lifecycle state. */
 	AgentMergeController = 'agentMerge.controller',
+	/** `'shellInitScripts'` — scripts a client generated for the session, sourced before built-in shell tool commands. */
+	ShellInitScripts = 'shellInitScripts',
 }
 
 /**
@@ -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.ShellInitScripts];
+	return result;
+}
@@ -0,0 +1,127 @@
+/*---------------------------------------------------------------------------------------------
+ *  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';
+
+export type ShellInitScriptShell = 'bash' | 'powershell';
+
+/**
+ * One client-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;
+}
+
+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 unless sourced profile code itself
+ * terminates the shell: 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. A
+	// preference changed by a profile affects later init work; the runtime may
+	// restore its outer preference after this script completes.
+	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') };
+}
+
+/** Generated scripts are a few hundred bytes; anything near this is not one. */
+const MAX_SHELL_INIT_SCRIPT_LENGTH = 64 * 1024;
+
+/** 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
+				&& script.script.length <= MAX_SHELL_INIT_SCRIPT_LENGTH;
+		});
+}
@@ -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';
@@ -3022,9 +3022,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());
@@ -3754,7 +3757,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).
@@ -5611,7 +5617,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)}`);
 							}
 
@@ -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