Skip to content

Python: Resolve Windows shell tool executables from PATH only - #10229

Merged
Eduard van Valkenburg (eavanvalkenburg) merged 4 commits into
microsoft:mainfrom
eavanvalkenburg:shell-executable-lookup
Nov 10, 2026
Merged

Eduard van Valkenburg (eavanvalkenburg) merged 4 commits into
microsoft:mainfrom
eavanvalkenburg:shell-executable-lookup

Conversation

@eavanvalkenburg

Copy link
Copy Markdown
Member

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.which does the same: on Python 3.11 it always puts the current directory first, and on 3.12 and later it does so unless NoDefaultCurrentDirectoryInExePath is set. LocalShellTool and DockerShellTool hand bare names such as pwsh, powershell and docker to 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 with cmd.exe in subprocess and 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

  • What are the major changes?
    • _resolve.py gets two private helpers. find_executable walks PATH with Windows naming rules and only looks at fully qualified entries (empty, relative, drive-relative and drive-less rooted entries are skipped, and .exe is added to names without an extension). resolve_executable applies it to bare names on Windows and returns everything else unchanged; it never falls back to the bare name.
    • resolve_shell uses it for the Windows default (pwsh, then powershell) and for bare shell= and AGENT_FRAMEWORK_SHELL values.
    • DockerShellTool resolves docker_binary once per instance and uses that path for every launch (container start, the docker exec session, stateless runs, kill and rm -f cleanup, close), so the runtime that starts a container is the one that stops it. is_docker_available resolves the same way.
    • _resolve_taskkill no longer falls back to the bare taskkill name. That path is only used when psutil is missing.
    • The README and docstrings describe the lookup.
  • What is the impact of these changes?
    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 PATH entry, or a .cmd/.bat/.com shim on PATH are 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 example C:\tools\podman.exe or .\docker.exe) are used as given. A missing executable raises the same exception type as before: ShellExecutionError from the LocalShellTool constructor, and FileNotFoundError for the Docker runtime, now raised before anything is launched.
  • What do you want reviewers to focus on?
    • Whether passing explicit relative paths through unchanged is the right policy, or whether Windows should require fully qualified values the way the .NET change in .NET: Require full LocalCodeAct interpreter paths #10225 does for the LocalCodeAct interpreter path.
    • The tests. Most of them simulate a Windows host on every platform (the new fake_windows_host fixture patches sys.platform, PATH and os.path.isfile and never starts a process). test_windows_lookup_ignores_executables_in_the_current_directory uses the real file system and only runs on Windows, so the windows-latest jobs 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.
    • A path, like a PATH match, 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 for shell strings), but the two changes are independent and only need a small rebase for whichever lands second.

AI Assistance

  • No material AI assistance was used.
  • This is an AI-assisted contribution. I reviewed, understood, and verified all submitted content and accept responsibility for it.

AI assistance details: Analysis, implementation, tests, documentation and this PR description were prepared with GitHub Copilot.

Contribution Checklist

  • The code builds clean without any errors or warnings
  • All unit tests pass, and I have added new tests where possible
  • The PR follows the Contribution Guidelines
  • This PR links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change or repository-automation exception.
  • This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

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.
Copilot AI balanced review requested due to automatic review settings November 10, 2026 12:45
@agent-framework-automation agent-framework-automation Bot added documentation Usage: [Issues, PRs], Target: documentation in the code base and learn docs python Usage: [Issues, PRs], Target: Python labels Nov 10, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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 taskkill fallback.
  • 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

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Merged via the queue into microsoft:main with commit 93e14e1 Nov 10, 2026
54 checks passed
@eavanvalkenburg
Eduard van Valkenburg (eavanvalkenburg) deleted the shell-executable-lookup branch November 10, 2026 16:53

This branch was successfully deployed

1 active deployment
github-app-auth — 07c455ca Deployed Nov 10, 2026 by eavanvalkenburg via team_check #9207
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Usage: [Issues, PRs], Target: documentation in the code base and learn docs python Usage: [Issues, PRs], Target: Python

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants