Repository navigation
Python: [BREAKING] Improve shell path validation - #10318
Conversation
There was a problem hiding this comment.
🟡 Changes recommended
The Windows test passes a shell path through POSIX-style parsing, causing construction to raise ShellExecutionError before the re-anchoring assertion; passing a one-element argv list would preserve the path.
1 open issue
What changed in this PR
This PR hardens Python shell executable lookup to align with the .NET path-validation changes, reducing dependence on the application's working directory.
Changes:
- Requires full paths for local shell overrides and an explicit
docker_binaryruntime path. - Removes empty and relative entries from local shell
PATH, rejecting unusable POSIX configurations. - Updates documentation and tests for validation, runtime launches, and restricted command lookup.
| File | Description |
|---|---|
python/packages/tools/tests/test_shell_resolve.py |
Tests full-path validation and restricted executable lookup. |
python/packages/tools/tests/test_local_shell_tool.py |
Tests environment restrictions in both execution modes. |
python/packages/tools/tests/test_docker_shell_tool.py |
Updates runtime arguments and tests path validation. |
python/packages/tools/README.md |
Documents breaking changes and migration examples. |
python/packages/tools/agent_framework_tools/shell/_tool.py |
Restricts the local shell environment before execution. |
python/packages/tools/agent_framework_tools/shell/_resolve.py |
Implements full-path checks and PATH filtering. |
python/packages/tools/agent_framework_tools/shell/_docker.py |
Requires and consistently uses the configured runtime path. |
Review effort: Balanced
There was a problem hiding this comment.
MAF Automated Review — Iteration 1
Result: Findings reported
Scope: full PR (2 commit(s)): 574c89cd3fca, 19c39d96613d
Model: gpt-5.6-sol
Overview
The change consistently validates explicit executable paths, filters ordinary relative PATH entries, and adds focused unit and end-to-end coverage across local and Docker-backed shells. Three residual gaps remain: native Windows environment overrides are corrupted before validation, inherited environments are unexpectedly frozen at construction, and Linux cwd aliases bypass the lexical absolute-path filter. Each can break or undermine the newly documented path contract.
Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
3 verified findings remained after source verification (3 medium) across 2 files. Details are attached to the affected lines below.
Affected areas: python/packages/tools/agent_framework_tools/shell/_resolve.py, python/packages/tools/agent_framework_tools/shell/_tool.py

Motivation & Context
LocalShellToolandDockerShellToolaccepted program names such asbash,pwsh.exeordockerfor theshell, the
AGENT_FRAMEWORK_SHELLenvironment variable and the container runtime, and looked them up usingevery
PATHentry, including relative ones like.orbin. The shell's ownPATHkept those entries too.This means the program that runs, and the tools the shell then starts, can depend on the folder the app is
started from, which makes the behavior hard to predict.
This change brings the Python shell tools in line with the .NET change in #10310: programs are given or found
by full path, and the shell's
PATHonly contains full directory paths, so results no longer depend on thecurrent folder.
Description & Review Guide
shell/_resolve.py:find_executable(name)searches only fully qualifiedPATHentries. On Windows it only finds.exefiles; on Linux/macOS the file must be executable.
require_full_path(value, *, source): rejects values that are not full paths (on Windows, alsovalues without an extension).
resolve_shellrequires a full path for an explicitshelland forAGENT_FRAMEWORK_SHELL. Thedefault lookup (
pwsh/powershellon Windows,bash/shelsewhere) usesfind_executable.restrict_executable_search(env): removes empty and relativePATHentries. On Windows it alsosets
NoDefaultCurrentDirectoryInExePath=1. On Linux/macOS it raisesValueErrorwhen no fulldirectory path is left in
PATH(orPATHis missing), because the shell would otherwise fall backto searching the current folder.
LocalShellTool: the shell environment (bothclean_envmodes, stateless and persistent) goes throughrestrict_executable_search.DockerShellTool:docker_binaryis now a required keyword argument and must be a full path.is_docker_available(binary)now takes the runtime path.find_executable,restrict_executable_search, and anend-to-end check that commands run in the shell don't use relative
PATHentries (stateless andpersistent).
shell=andAGENT_FRAMEWORK_SHELLmust be full paths, e.g.shell="/bin/zsh"orshell=r"C:\Program Files\PowerShell\7\pwsh.exe".DockerShellToolneedsdocker_binary:On Linux/macOS,
LocalShellTool(clean_env=True, ...)needs anenvwith aPATHthat contains atleast one full directory path, e.g.
env={"PATH": "/usr/bin:/bin"}.PATHentries. Use./tool(or
.\tool) to run a program from the working folder._resolve.py, especially the Linux/macOS error whenPATHhas no fulldirectory path.
docker_binaryrequired instead of looking it up.Related Issue
Fixes #
AI Assistance
AI assistance details: implementation, tests, documentation, and this PR description.
Contribution Checklist
breaking changelabel (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.