Skip to content

Python: [Bug]: LocalShellTool shell= / AGENT_FRAMEWORK_SHELL strips backslashes from Windows paths #9819

Open

Description

Observed Behavior

On Windows, a shell path passed as a string, LocalShellTool(shell=r"C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe") or AGENT_FRAMEWORK_SHELL=C:\msys64\usr\bin\bash.exe, fails on the first run() with FileNotFoundError: [WinError 2]. resolve_shell splits the string with POSIX shlex.split, which treats \ as an escape, so every backslash is dropped. A path wrapped in double quotes happens to survive.

Expected Behavior

The given shell starts. Windows paths keep their backslashes, as they do when the default shell is used.

Steps to Reproduce

  1. On Windows, create LocalShellTool(mode="stateless", shell=r"C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe") (or mode="persistent"), or set AGENT_FRAMEWORK_SHELL to an unquoted Windows path.
  2. Call run() with any command.
  3. It fails with FileNotFoundError.

Minimal Reproduction

from agent_framework_tools.shell._resolve import resolve_shell
print(resolve_shell(r"C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe", interactive=False))
# ['C:WindowsSystem32WindowsPowerShellv1.0powershell.exe', '-c']

The flag also falls back to -c instead of -Command, because the mangled name isn't recognised as PowerShell.

Root cause: the shlex.split(shell) and shlex.split(env_override) calls in resolve_shell, python/packages/tools/agent_framework_tools/shell/_resolve.py. A fix that should work: on win32, split without escape processing (shlex.shlex(value, posix=False) with " as the only quote character, then strip the quotes), and keep shlex.split elsewhere. Checked against CommandLineToArgvW on 14 typical override strings. I have this fix with tests ready if it's wanted.

Error Messages and Stack Traces

FileNotFoundError: [WinError 2] The system cannot find the file specified

Package Versions

agent-framework-tools from main (fc3c3c0)

Python Version

3.13

Operating System

Windows

Activity

  1. added
    pythonUsage: [Issues, PRs], Target: Python
    triageUsage: [Issues], Target: All issues that still need to be triaged
    on Oct 29, 2026
  2. added
    reproducedUsage: [Issues], Target: all issues that can be reproduced by the triage workflow
    on Oct 29, 2026
  3. github-actions commented on Oct 29, 2026

    @github-actions
    Contributor

    🤖 Automated triage reproduction notes (agent-authored — trust but verify)

    Agent analysis

    python/packages/tools/agent_framework_tools/shell/_resolve.py::resolve_shell strips backslashes when a Windows path is supplied as a string through shell= or AGENT_FRAMEWORK_SHELL; stateless PowerShell paths are then misclassified and receive -c. Minimal repro: monkeypatch sys.platform to win32, resolve r"C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe" with interactive=False, and observe the mangled path and flag.

    • Failing test: python/packages/tools/tests/test_shell_resolve.py
    • Files examined: python/packages/tools/agent_framework_tools/shell/_resolve.py, python/packages/tools/agent_framework_tools/shell/_tool.py, python/packages/tools/tests/test_shell_resolve.py, python/packages/tools/pyproject.toml
    • Tests run: tests/test_shell_resolve.py, test_resolve_shell_preserves_windows_path_override, test_resolve_shell_preserves_windows_path_environment_override
    • Current version: 1.0.0b261022
  4. added
    skillsUsage: [Issues, PRs], Target: skills related features
    and removed
    triageUsage: [Issues], Target: All issues that still need to be triaged
    on Oct 29, 2026
  5. eavanvalkenburg commented on Nov 2, 2026

    @eavanvalkenburg
    Member

    /plan Plan the supported Windows LocalShellTool shell-string parsing correction using existing #9858 and the current maintainer review as input, not a competing implementation. POSIX shlex.split currently removes backslashes from both explicit string and AGENT_FRAMEWORK_SHELL overrides. Select a compatible, maintainable Windows argv parsing approach; preserve literal paths, quoted spaces, odd/even backslashes before quotes, embedded escaped quotes and explicitly empty arguments. Existing review already identifies escaped-quote and empty-argument gaps: do not treat the current scanner as complete. Cover explicit/environment/sequence overrides, persistent/stateless modes, Windows PowerShell executable recognition and -Command/-c selection, with native Windows process-launch evidence and unchanged POSIX quoting. Keep this platform-parser change out of minor-ready until compatibility cases are established; preserve assignments and coordinate existing contributor work.

  6. eavanvalkenburg commented on Nov 10, 2026

    @eavanvalkenburg
    Member

    /plan I'm sure there are ways we can leverage other libraries, preferably from the standard library to handle this

  7. github-actions commented on Nov 10, 2026

    @github-actions
    Contributor

    Summary

    On Windows, resolve_shell in _resolve.py parses string overrides (shell= and AGENT_FRAMEWORK_SHELL) with POSIX shlex.split. That treats \ as an escape, so C:\Windows\...\powershell.exe loses its backslashes. The mangled name is then not recognised by is_powershell, so stateless mode appends -c instead of -Command. I read the code and it matches the report. I did not run anything. Sequence overrides (shell=[...]) are used as-is and are not affected.

    Recommendation

    Yes, a small code change is warranted. It is a real bug on a supported platform, with a clear Windows-only scope. Use the standard library where possible, but the standard library has no pure-Python parser for Windows command lines. Options I checked:

    • shlex with posix=False. It keeps backslashes, but it keeps the quotes in the tokens. It also has no model of Windows quote rules (backslashes before quotes, "" inside quotes, empty arguments). Several of those cases were already flagged as gaps in review. It would still need post-processing, which becomes a hand-written parser.
    • ctypes.windll.shell32.CommandLineToArgvW (standard library ctypes). This is the Windows function that real programs use to split their command line. It gives exactly the native behaviour for every case on the list: literal paths, quoted spaces, odd and even backslashes before quotes, escaped quotes, and empty arguments. It only exists on Windows, which is the only place we need it. Caveat: it treats the first token specially (no escape processing, quotes only), and an empty string returns the current executable path. The fix is to prefix a dummy token, for example "x " + value, and drop the first result, so every real token gets the same rules. Parse an empty or whitespace-only string as "empty override" before calling it. The returned memory must be freed with LocalFree.
    • A small pure-Python port of the Windows rules. This is the fallback if we do not want ctypes. It adds maintenance cost and a risk of drifting from the native behaviour, and it is the area where the current scanner has gaps.

    I recommend CommandLineToArgvW via ctypes on win32, and unchanged shlex.split everywhere else. This is the most compatible choice and the least code to maintain.

    Proposed plan (a proposal; nothing has been changed)

    1. In _resolve.py, add one helper, for example _split_shell_string(value). It uses ctypes + CommandLineToArgvW on sys.platform == "win32" (with the dummy-first-token trick, LocalFree in finally) and shlex.split otherwise. Use it for both the shell= string and the AGENT_FRAMEWORK_SHELL value, so the two paths cannot diverge.

    2. Keep the existing empty-override handling and error message. Sequence overrides stay verbatim.

    3. Check is_powershell. With correct paths, os.path.basename on Windows already recognises powershell.exe/pwsh.exe, so stateless mode should pick -Command and -c stays for bash.exe. Confirm this in tests rather than changing the function.

    4. Tests in python/packages/tools/tests/test_shell_resolve.py:

      • Parser cases (Windows-only, skipped elsewhere): unquoted path, quoted path with spaces, path plus arguments, odd/even backslashes before a quote, an escaped quote, "" as an explicit empty argument, and an empty string.
      • resolve_shell cases: explicit string, environment variable, and sequence override, each in interactive=True and False. Check PowerShell gets -Command and others get -c.
      • POSIX regression: existing shlex behaviour is unchanged, including quoting.
      • Monkeypatching sys.platform cannot exercise ctypes.windll, so the native checks need a real Windows run (CI Windows job or manual).
    5. Evidence of success: a Windows run where LocalShellTool(shell=r"C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe") actually starts and runs a command in both stateless and persistent modes. The same applies to an unquoted AGENT_FRAMEWORK_SHELL.

    6. Per the earlier maintainer note, keep this out of minor-ready until the compatibility cases above pass, and coordinate with the existing contributor work on the issue (assignments unchanged). If preferred, the pure-Python port is the fallback to avoid ctypes.

    Trade-off to confirm: one behaviour change is possible. Strings that previously used POSIX-style escapes on Windows (for example \ for a space) will now follow Windows rules. That seems right for Windows paths, but it is worth a line in the docstring and release notes.

    Generated by Issue Planning for #9819 · copilot · auto · ~18 AIC · ⌖ ~1 AIC · ⊞ 4.8K · ◷

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

pythonUsage: [Issues, PRs], Target: PythonreproducedUsage: [Issues], Target: all issues that can be reproduced by the triage workflowskillsUsage: [Issues, PRs], Target: skills related features

Type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions