Python: Added ShellTool and LocalShellExecutor

[dmytrostruk]

Motivation and Context

This PR adds shell command execution capabilities to the Agent Framework through a new ShellTool abstraction and LocalShellExecutor implementation.

• Added ShellTool abstraction for shell command execution with configurable security policies
• Added LocalShellExecutor in new agent-framework-shell-local package using asyncio subprocess
• Security controls: privilege escalation blocking, dangerous pattern detection, path validation
• Support for allowlist/denylist patterns
• Configurable timeouts, output truncation, and working directory
• as_ai_function() conversion for use with existing AI agents

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework
_shell_tool.py	187	17	90%	58, 99–100, 102, 113, 328, 356, 362, 369–371, 376–377, 437–438, 514–515
_types.py	957	128	86%	72, 95–96, 150, 155, 174, 176, 180, 184, 186, 188, 190, 207–208, 210–212, 214–215, 217–218, 220–221, 236–238, 240–243, 260, 265, 270, 274, 304, 659–660, 996, 1079, 1145, 1162, 1180, 1185, 1203, 1211–1213, 1230–1231, 1233, 1251–1252, 1254, 1261–1262, 1264, 1299, 1310–1311, 1313, 1332–1333, 1336–1345, 1348–1351, 1353, 1357, 1391, 1424, 1596, 1601, 1605, 1609, 1801, 1811, 1856, 1901–1906, 1928, 1933, 2292, 2301, 2437, 2525–2527, 2566, 2622, 2643, 2652, 2881–2883, 2886–2888, 2892, 2897, 2901, 3013–3015, 3043, 3079, 3097, 3101–3103, 3105, 3116–3117, 3122, 3130
packages/shell-local/agent_framework_shell_local
_executor.py	63	13	79%	50, 54–57, 68, 75–77, 107–108, 130–131
TOTAL	17733	2733	84%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
3227	213 💤	0 ❌	0 🔥	1m 3s ⏱️

[Copilot]

Pull request overview

This PR adds shell command execution capabilities to the Agent Framework through a new ShellTool abstraction and LocalShellExecutor implementation.

Changes:

• Introduces ShellTool with comprehensive security validation (privilege escalation blocking, dangerous pattern detection, path restrictions)
• Adds LocalShellExecutor in new agent-framework-shell-local package using asyncio subprocess
• Includes allowlist/denylist patterns, configurable timeouts, output truncation, and AI function conversion support

Reviewed changes

Copilot reviewed 12 out of 13 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
python/uv.lock	Added agent-framework-shell-local package dependency
python/pyproject.toml	Registered new shell-local workspace package
python/packages/shell-local/pyproject.toml	Package configuration for shell-local with pytest, mypy, and bandit setup
python/packages/shell-local/agent_framework_shell_local/_executor.py	LocalShellExecutor implementation with async subprocess, timeout handling, and output truncation
python/packages/shell-local/agent_framework_shell_local/init.py	Package exports for LocalShellExecutor
python/packages/shell-local/README.md	Documentation covering installation, usage, security considerations, and configuration options
python/packages/shell-local/LICENSE	MIT license for the package
python/packages/shell-local/tests/test_executor.py	Comprehensive tests for LocalShellExecutor covering basic execution, timeouts, truncation, working directories, and stderr capture
python/packages/core/tests/core/test_shell_tool.py	Extensive tests for ShellTool validation, security patterns, path restrictions, and AI function conversion
python/packages/core/agent_framework/shell_local/init.pyi	Type stubs for lazy-loaded shell_local module
python/packages/core/agent_framework/shell_local/init.py	Lazy loading implementation for shell-local package
python/packages/core/agent_framework/_shell_tool.py	Core ShellTool implementation with security validation, pattern matching, and command execution
python/packages/core/agent_framework/init.py	Added shell_tool module to core exports

[moonbox3]

Will we include any sample code on how to use this?

[eavanvalkenburg]

I think this one still makes sense, just needs some work to move it to the new model with get_..._tool methods. @dmytrostruk