Python: [BREAKING] Simplify ShellEnvironmentProvider configuration #9634

Maintainer-owned issue. Community contributors: please do not pick up or start implementing this issue. This is a preview-package public API design issue.

Problem

ShellEnvironmentProviderOptions is an exported frozen dataclass that groups four values but owns no validation or behavior. The common path requires importing and constructing this extra framework object.

Use Case and Evidence

The class is defined in python/packages/tools/agent_framework_tools/shell/_environment.py around lines 61-79 and exported from the shell package. agent-framework-tools is currently beta.

Desired Outcome

Allow direct keyword-only configuration on ShellEnvironmentProvider while preserving discoverability and typing. Decide whether the options class should remain as an advanced form or be deprecated before package release.

Alternatives Considered

A TypedDict is possible when options are stored or forwarded, but keyword-only parameters are likely clearer for the four direct settings. Keeping only the dataclass preserves compatibility but retains the extra import.

Proposed Direction

Add keyword-only parameters first, define conflict behavior when both forms are supplied, migrate samples, and make any class deprecation/removal explicit while the package remains preview.

Scope and Non-Goals

Do not generalize this issue to behavior-bearing configuration objects such as validated Pydantic models or classes with factories and lifecycle methods.

Language

Python

Contribution Intent

Maintainer-owned; implementation must wait for maintainer design agreement.

Acknowledgements

• I searched existing issues and did not find a duplicate.
• I will wait for explicit maintainer agreement before starting implementation of a non-trivial change.

Ownership: Core maintainers only; not available for community pickup.