Repository navigation
Python: Resolve Windows shell tool executables from PATH only - #10229
Eduard van Valkenburg (eavanvalkenburg) merged 4 commits into
Conversation
On Windows, starting an executable by its bare name makes the OS look in the current directory of the host process before PATH, and shutil.which does the same. LocalShellTool and DockerShellTool could therefore start an executable from the working directory instead of the installed one. Resolve bare names (the default pwsh/powershell, bare shell overrides and docker_binary) from fully qualified PATH entries only and launch the resolved absolute path. Explicit paths are used as given, the bare taskkill fallback is removed, and POSIX behavior is unchanged.
There was a problem hiding this comment.
🟡 Changes recommended
The resolver rejects absolute UNC share roots without a trailing separator, causing existing executables on those shares to be reported as missing.
1 open issue
What changed in this PR
This PR hardens Windows executable selection in the Python shell tools by resolving bare names from fully qualified PATH entries rather than relying on current-directory search. POSIX behavior remains unchanged.
Changes:
- Adds shared executable resolution for shell defaults, overrides, and Docker runtimes.
- Reuses the resolved Docker runtime throughout each instance’s lifecycle and removes the bare-name
taskkillfallback. - Adds Windows lookup regression tests and documents the lookup policy.
| File | Description |
|---|---|
python/packages/tools/tests/test_shell_resolve.py |
Tests PATH filtering, explicit paths, and current-directory exclusion. |
python/packages/tools/tests/test_shell_killtree.py |
Tests cleanup when the system taskkill.exe is missing. |
python/packages/tools/tests/test_local_shell_tool.py |
Uses explicit fake shell paths to avoid host-dependent lookup. |
python/packages/tools/tests/test_docker_shell_tool.py |
Tests resolved runtime use across launches, cleanup, and availability checks. |
python/packages/tools/tests/conftest.py |
Adds a shared simulated-Windows lookup fixture. |
python/packages/tools/README.md |
Documents Windows lookup behavior and trust limitations. |
python/packages/tools/agent_framework_tools/shell/_tool.py |
Updates the shell parameter documentation. |
python/packages/tools/agent_framework_tools/shell/_resolve.py |
Adds PATH-only executable lookup and integrates shell resolution. |
python/packages/tools/agent_framework_tools/shell/_killtree.py |
Removes fallback to an unqualified taskkill command. |
python/packages/tools/agent_framework_tools/shell/_docker.py |
Caches runtime resolution and applies it throughout Docker operations. |
Review effort: Balanced
There was a problem hiding this comment.
MAF Automated Review — Iteration 1
Result: Findings reported
Scope: full PR (1 commit(s)): 169105c68adb
Model: gpt-5.6-sol
Overview
The PR replaces Windows bare-name process launches with explicit lookup through fully qualified PATH entries, refuses unsafe bare-name fallback, and keeps Docker lifecycle operations pinned to one resolved runtime. Its tests cover current-directory exclusion, explicit-path pass-through, and consistent Docker cleanup. One compatibility edge remains: a valid UNC share-root PATH entry without a trailing separator is rejected, so shell or Docker startup can fail for that configuration.
Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
1 verified finding remained after source verification (1 medium) across 1 file. Details are attached to the affected lines below.
Affected areas: python/packages/tools/agent_framework_tools/shell/_resolve.py
The combined test run imports conftest files in importlib mode. Two test directories that each have an __init__.py and a conftest.py resolve to the same module name, so the shared fixture file of the tools tests clashed with the one of core. Test directories must not contain an __init__.py (python/CODING_STANDARD.md).
…t of the real file system The fixture fell back to the real os.path.isfile for paths it did not know. On a Windows machine with PowerShell installed, the missing-binary check found the real pwsh.exe. The fake now answers only for the files a test names.
A UNC or device share root such as \\server\share is complete without a trailing separator and cannot depend on the current directory. ntpath.splitdrive returns the whole share as the drive with an empty remainder, so the check rejected it and executables on that share were reported as missing.
There was a problem hiding this comment.
MAF Automated Review — Iteration 2
Result: No findings
Scope: 3 net-new commit(s): 49e32c385014, a6a360100fbb, 07c455ca415b
Model: gpt-5.6-sol
Overview
This incremental update fixes the previously reported UNC share-root rejection, removes a legacy test package marker, and makes the simulated Windows filesystem deterministic. The new UNC cases cover backslash, forward-slash, and device-UNC roots, while the production lookup still requires a matching file and preserves the fail-closed bare-name behavior. No Critical, High, or Medium defect introduced in the authoritative range was established.
Reviewed the supplied incremental change set across correctness, security/reliability, architecture, and failure behavior.
No publishable findings remained after source verification for this scope.

Motivation & Context
When Windows starts an executable by its bare name, it looks in the current directory of the host process before it reads
PATH.shutil.whichdoes the same: on Python 3.11 it always puts the current directory first, and on 3.12 and later it does so unlessNoDefaultCurrentDirectoryInExePathis set.LocalShellToolandDockerShellToolhand bare names such aspwsh,powershellanddockerto process creation, so an app started from a directory that contains a file with one of those names could end up launching that file instead of the installed executable. CPython ran into the same class of problem withcmd.exeinsubprocessand fixed it by using a fully qualified path (python/cpython#101283).This change makes the shell tools resolve bare executable names themselves and never consult the current directory.
Description & Review Guide
_resolve.pygets two private helpers.find_executablewalksPATHwith Windows naming rules and only looks at fully qualified entries (empty, relative, drive-relative and drive-less rooted entries are skipped, and.exeis added to names without an extension).resolve_executableapplies it to bare names on Windows and returns everything else unchanged; it never falls back to the bare name.resolve_shelluses it for the Windows default (pwsh, thenpowershell) and for bareshell=andAGENT_FRAMEWORK_SHELLvalues.DockerShellToolresolvesdocker_binaryonce per instance and uses that path for every launch (container start, thedocker execsession, stateless runs, kill andrm -fcleanup, close), so the runtime that starts a container is the one that stops it.is_docker_availableresolves the same way._resolve_taskkillno longer falls back to the baretaskkillname. That path is only used when psutil is missing.Windows only; POSIX behavior is unchanged. Default usage is the same for normal installs. Executables that were only found through the current directory, a relative
PATHentry, or a.cmd/.bat/.comshim onPATHare no longer picked up for bare names, so pass an absolute path to select one explicitly. Values that already contain a directory or a drive (for exampleC:\tools\podman.exeor.\docker.exe) are used as given. A missing executable raises the same exception type as before:ShellExecutionErrorfrom theLocalShellToolconstructor, andFileNotFoundErrorfor the Docker runtime, now raised before anything is launched.fake_windows_hostfixture patchessys.platform,PATHandos.path.isfileand never starts a process).test_windows_lookup_ignores_executables_in_the_current_directoryuses the real file system and only runs on Windows, so thewindows-latestjobs are the real check for that part. The existing Docker tests pin the lookup to the identity function so they do not depend on which runtimes the host has installed, and two existing tests that used bare fake shell names now use path-like names.PATHmatch, only shows that a file exists, not that it can be trusted. This change removes the dependence on the current directory; it does not try to verify ownership of the resolved executable.Related Issue
N/A - team-authored change; there is no issue for it. No other open PR covers this. #10145 also edits
resolve_shell(Windows command-line parsing forshellstrings), but the two changes are independent and only need a small rebase for whichever lands second.AI Assistance
AI assistance details: Analysis, implementation, tests, documentation and this PR description were prepared with GitHub Copilot.
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.