Meta: Evolve Python environment tools for autonomous agent workflows

[eleanorjboyd]

Background

The Python extension currently contributes configure_python_environment as an agent-facing orchestration tool. The tool can be approved (including under Allow all) and then block on extension-owned Quick Picks or other user input. This creates two interaction layers: Chat tool approval and UI shown during tool execution.

The Python Environments extension is now rolled out broadly, but users can still disable it. Long term, Python Environments is the right owner for richer environment tooling once it is enabled by default. Until then, the Python extension needs to provide a reliable compatibility surface without advertising arguments that the active backend cannot honor.

Tool schemas are statically contributed, so the public contract should not change merely because another extension is installed. Runtime capability discovery and explicit unsupported-capability errors are safer than silently accepting hints.

Goal

Provide an environment-tool experience in which an agent can create or select the environment it needs without unexpected user interaction, while preserving a clear interactive path when explicitly requested and protecting existing users during rollout.

Current and target experience

Area	Current	Target
Interaction	Tool approval can be followed by blocking extension UI	Non-interactive calls never show input UI; interactive behavior is explicit
Inputs	The public tool primarily accepts a workspace/resource path	Contracts express only capabilities the active implementation can enforce
Failure handling	An agent can wait indefinitely for user input	Ambiguity, conflicts, and missing capabilities return structured actionable errors
Ownership	Python contributes the tool and may route internally	Python provides a temporary compatibility surface; Python Environments ultimately owns richer declarative tools
Product feedback	Success is inferred from individual reports	Release health is measured through privacy-conscious telemetry and user feedback

Proposed sequence

1. Urgent: fix the existing auto-approved call path so it cannot block on user input.
2. Map every current environment-related agent tool and user-visible flow, then document the desired end-to-end experience and ownership boundaries.
3. Experiment with the tool surface (orchestrating, granular, richer declarative, and capability-discovery variants) and compare agent outcomes.
4. Add a release-monitoring plan and evaluate telemetry after rollout before broadening or transferring the contract.
5. Move richer declarative environment tooling to Python Environments when it is the default owner; retain or retire the Python compatibility surface deliberately.

Principles

• Auto-approval must not imply hidden blocking interaction.
• Non-interactive execution must always terminate, although it may return a structured failure rather than create an environment.
• Requested properties are enforceable outcomes, not silently ignored hints.
• Disabled or unavailable Python Environments support results in reduced capabilities, not a misleading schema.
• Interactive behavior remains available only through an explicit policy.
• Rollout decisions are supported by measurable task outcomes and guardrail metrics.