Skip to content

Python: preserve Windows backslashes and quotes in LocalShellTool shell paths - #10145

Closed
Johnny Wilson Dougherty (JohnnyWilson16) wants to merge 1 commit into
microsoft:mainfrom
JohnnyWilson16:fix/9819-windows-shell-parsing
Closed

Johnny Wilson Dougherty (JohnnyWilson16) wants to merge 1 commit into
microsoft:mainfrom
JohnnyWilson16:fix/9819-windows-shell-parsing

Conversation

@JohnnyWilson16

Copy link
Copy Markdown

Motivation & Context

On Windows, configuring LocalShellTool(shell=r"C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe") or setting AGENT_FRAMEWORK_SHELL to an unquoted Windows path fails with FileNotFoundError: [WinError 2]. resolve_shell used POSIX shlex.split, which strips backslashes as escape characters and fails to identify the binary as PowerShell.

Prior PR #9858 was closed by maintainer Eduard van Valkenburg (@eavanvalkenburg) with a request for a fresh PR with a complete Windows command-line parser that preserves escaped quotes and explicitly quoted empty arguments without dropping tokens.

Description & Review Guide

  • What are the major changes?
    • Added _split_windows_command_line in agent_framework_tools/shell/_resolve.py implementing CommandLineToArgvW rules:
      • Retains literal backslashes in unquoted and quoted file paths.
      • Preserves double-quoted parameters with whitespace.
      • Preserves explicitly empty arguments ("").
      • Handles escaped quotes (\") and consecutive backslash sequences preceding quotes ($2N$ / $2N+1$ rules).
    • Added _split_shell_override to dispatch to _split_windows_command_line on sys.platform == "win32" while preserving standard shlex.split behavior on POSIX systems.
    • Updated is_powershell to normalize backslashes before os.path.basename so Windows executable paths evaluate correctly across platforms.
    • Added unit tests in test_shell_resolve.py covering unquoted Windows paths, environment variable overrides, empty arguments, and adjacent quoted/unquoted tokens under win32 platform mocks.
  • What is the impact of these changes?
    • Windows users can supply standard backslash paths to LocalShellTool and AGENT_FRAMEWORK_SHELL. POSIX behavior is unchanged.
  • What do you want reviewers to focus on?
    • Adherence of _split_windows_command_line to Windows CommandLineToArgvW argument tokenization rules.

Related Issue

Fixes #9819

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: Used an AI coding assistant to help draft the Windows tokenizer following CommandLineToArgvW rules, write the regression tests, and prepare this description.

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.

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 Windows shell parser drops literal quotes encoded as consecutive quotation marks, silently changing arguments supplied through shell= or AGENT_FRAMEWORK_SHELL.

1 open issue
What changed in this PR

This PR addresses #9819 by adding Windows-specific parsing for LocalShellTool shell overrides, preserving path backslashes while retaining POSIX parsing elsewhere.

Changes:

  • Adds Windows tokenization for explicit and environment-based overrides.
  • Updates PowerShell detection and adds regression tests for Windows paths, quoting, and empty arguments.
  • Adds implementation plans for this fix and a separate tool-approval budget cleanup.
File Description
python/​packages/​tools/​tests/​test_shell_resolve.py Adds Windows shell parsing regression tests.
python/​packages/​tools/​agent_framework_tools/​shell/​_resolve.py Adds platform-specific tokenization and normalizes paths for PowerShell detection.
docs/​superpowers/​plans/​2026-11-06-issue-9819-windows-shell-parsing.md Documents the Windows parsing implementation plan.
docs/​superpowers/​plans/​2026-11-06-issue-9677-tool-approval-budget-cleanup.md Adds an unrelated tool-approval budget cleanup plan; no runtime changes.

Review effort: Balanced

Comment on lines +54 to +55
elif c == '"':
in_quotes = not in_quotes

@BlueRaddish BlueRaddish 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.

Here is a concrete follow-up patch for the existing consecutive-quote finding, based on 8b47e6664be404472a06f28f357375653808e57b.

It preserves a doubled quote while already inside quotes, in both the ordinary quote branch and the even-backslash-before-quote branch. The eight regression cases exercise the explicit shell and AGENT_FRAMEWORK_SHELL paths; the existing 16 owning cases are unchanged. This keeps the current backslash, empty-argument, PowerShell detection and POSIX behavior.

--- a/python/packages/tools/agent_framework_tools/shell/_resolve.py
+++ b/python/packages/tools/agent_framework_tools/shell/_resolve.py
@@ -45,16 +45,24 @@
                     has_token = True
                     i += 1
                 else:
-                    in_quotes = not in_quotes
+                    if in_quotes and i + 1 < n and cmd[i + 1] == '"':
+                        buf.append('"')
+                        i += 2
+                    else:
+                        in_quotes = not in_quotes
+                        i += 1
                     has_token = True
-                    i += 1
             else:
                 buf.append("\\" * num_slashes)
                 has_token = True
         elif c == '"':
-            in_quotes = not in_quotes
+            if in_quotes and i + 1 < n and cmd[i + 1] == '"':
+                buf.append('"')
+                i += 2
+            else:
+                in_quotes = not in_quotes
+                i += 1
             has_token = True
-            i += 1
         else:
             buf.append(c)
             has_token = True
--- a/python/packages/tools/tests/test_shell_resolve.py
+++ b/python/packages/tools/tests/test_shell_resolve.py
@@ -135,3 +135,24 @@
     assert argv[0] == r"C:\Program Files\PowerShell\7\pwsh.exe"
     assert argv[1] == "-NoProfile"
     assert argv[-1] == "-Command"
+
+
+@pytest.mark.parametrize("from_env", [False, True], ids=["explicit", "env"])
+@pytest.mark.parametrize(
+    ("command_line", "expected"),
+    [
+        ('bash "a""b"', ["bash", 'a"b']),
+        ('bash "a"""', ["bash", 'a"']),
+        ('bash """a', ["bash", '"a']),
+        (r'bash "a\\""b"', ["bash", 'a\\"b']),
+    ],
+)
+def test_win32_consecutive_quotes(
+    command_line: str, expected: list[str], from_env: bool, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    import agent_framework_tools.shell._resolve as resolve_module
+
+    monkeypatch.setattr(resolve_module.sys, "platform", "win32")
+    if from_env:
+        monkeypatch.setenv("AGENT_FRAMEWORK_SHELL", command_line)
+    assert resolve_shell(None if from_env else command_line, interactive=True) == expected

Verification on Windows 11 / Python 3.11.17 / pytest 9.1.1:

  • Current complete resolver module with the final test file: 16 passed, 8 failed, 0 skipped. With this patch: 24 passed, 0 failed, 0 skipped.
  • Compared 21 argument vectors to the actual Windows CommandLineToArgvW API: current parser has 4 mismatches, patched parser has 0. Cases include empty arguments, escaped quotes, trailing backslashes, adjacent fragments and consecutive quotes. The oracle prepends a dummy executable to test ordinary argument parsing; it deliberately excludes Windows' special executable-token rule, preserving this PR's adjacent-fragment behavior.
  • The PR's declared Ruff 0.17.3 check and format check pass on the two proposed files under the exact root/package configuration.

Scope: the owning run executes the full resolver module and exact current test bodies with real pytest/MonkeyPatch and the exact ShellExecutionError class. Import-only package shims isolate unrelated SDK initialization. This does not claim full package initialization, repository-wide fixtures/suites, actual shell launch, native commit hooks or full workspace acceptance. The probes execute in their own verified, bounded processes; no model/provider calls were made.

AI assistance was used for implementation, regression tests and verification preparation. This is working implementation assistance for the already-reported gap, rather than a competing PR or a new report of that same finding.

@eavanvalkenburg

Copy link
Copy Markdown
Member

Johnny Wilson Dougherty (@JohnnyWilson16), thank you for the contribution. The linked issue (#9819) is not marked ready-for-implementation, and I cannot find an explicit maintainer comment accepting this implementation direction. Please settle the scope in the issue and wait for explicit maintainer agreement before opening a fresh implementation PR. I am closing this for now.

This branch was successfully deployed

No deployments
github-app-auth — 8b47e666 Deployed Nov 6, 2026 by JohnnyWilson16 via team_check #8871
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.

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

4 participants