Map current and ideal Python environment agent-tool flows

[eleanorjboyd]

Background

The urgent non-interactive bug is tracked by #25940, while #26078 tracks the broader strategy. Before changing tool ownership or expanding the public schema, we need a shared map of how every environment-related agent tool works today and what the intended end-to-end experience should be.

This should give the team a concrete artifact for discussing the user experience, backend boundaries, and the transition from Python-owned compatibility tooling to richer Python Environments-owned tooling.

Deliverable

Document every currently contributed Python environment-related agent tool, including:

• public tool name and description;
• input schema and defaults;
• extension and module that contribute and implement it;
• internal tools or commands it invokes;
• active backend when Python Environments is enabled, disabled, or unavailable;
• user-visible UI at each stage;
• success result, failure result, cancellation behavior, and known blocking paths;
• whether auto-approval changes any part of the flow.

Include current and ideal sequence diagrams covering at least:

1. reuse of an already selected environment;
2. automatic environment creation;
3. ambiguous environment selection;
4. dependency installation where applicable;
5. cancellation and failure;
6. Python Environments enabled, disabled, and unavailable.

The ideal flow should show where agent intent, capability discovery, validation, creation, selection, dependency installation, and verification belong. Clearly distinguish Chat-host approval from extension-owned interaction.

Questions to answer

• Which behaviors belong in the Python compatibility tool versus Python Environments?
• Which current tool names imply behavior that their implementations do not guarantee?
• Where can an agent currently receive success without the intended environment being created and selected?
• What capabilities can both backends honestly support during transition?
• What should happen to tool identities when Python Environments becomes the default owner?

Acceptance criteria

• The map covers all contributed environment-related agent tools and backend routes.
• Current and ideal flows are understandable without reading the implementation.
• Differences between enabled, disabled, and unavailable Python Environments are explicit.
• Gaps and ownership decisions are listed separately from proposed API design.
• The artifact is linked from Meta: Evolve Python environment tools for autonomous agent workflows #26078 and can inform the tool-surface investigation.