Document shell initialization for Copilot Agent Host sessions

[ntrogh]

Product change

• Source: Activate Python environments in Agent Host shell commands with shell init scripts vscode#332593
• Merged: 2026-09-02 UTC

Copilot Agent Host sessions can run a generated initialization script before each built-in shell command. The script loads the user's shell profile and can activate the Python environment selected for the workspace, so agent commands use the same environment as the developer.

Why the docs need an update

The Copilot harness documentation and AI settings reference do not mention the new initialization behavior, its opt-in setting, or the Python extension prerequisite.

Suggested documentation

• docs/agents/run/agent-harnesses.md: explain when shell initialization is useful and what is loaded on each platform.
• docs/agents/reference/ai-settings.md: add chat.agentHost.shellTool.initScript.enabled with its default, scope, and prerequisites.

Details to verify

• chat.agentHost.shellTool.initScript.enabled is application-scoped, experimental/advanced, and defaults to false.
• It applies only to local Copilot SDK Agent Host sessions that use the SDK shell tool.
• It loads ~/.bashrc on macOS and Linux and current-user PowerShell profiles on Windows.
• Python activation requires the Python Environments extension and python-envs.terminal.autoActivationType set to shellStartup.

Acceptance criteria

• Users can enable shell initialization and understand which sessions and platforms it affects.
• Python environment activation prerequisites and the default-off experimental status are explicit.
• The settings reference and Copilot harness guidance remain consistent.

[anthonykim1]

Right now this is not "customizable" in a way that we just run some script that would source user's rc file + python activation related file. I wonder if we should start documenting once its more configurable (user list the files they want sourced before each shell tool, etc)