hermes - 💡(How to fix) Fix [Bug]: Browser tool commands fail on Windows when arguments contain shell characters (&, |, <, >) due to .cmd wrapper evaluation [1 pull requests]

Bug Description

When running Hermes on Windows, using browser_tool to navigate to URLs containing query parameters (like &) or executing JavaScript containing shell characters (<, >, |) causes the command to fail or truncate.

This occurs because Hermes invokes agent-browser via its npm-generated .cmd wrapper (agent-browser.cmd). On Windows, cmd.exe evaluates arguments twice (once when python invokes the subprocess, and again inside the .cmd wrapper when %* is expanded). As a result, standard argument quoting is stripped on the second pass, causing cmd.exe to interpret & as a command separator, which breaks the URL and throws a system error. Environment OS: Windows Component: tools/browser_tool.py (_run_browser_command function)

Steps to Reproduce

Run Hermes on a Windows environment. Ask the agent to navigate to a URL with multiple query parameters. Example: https://example.com/search?q=test&page=2 Observe that the command fails or truncates at the &, attempting to run page=2 as a separate Windows command.

Expected Behavior

The entire URL or expression should be passed safely to the underlying Node.js process without being intercepted and split by Windows cmd.exe.

Actual Behavior

When os.name == "nt" and the target executable is a .cmd or .bat file, we need to inject triple carets (^^^&, ^^^|, ^^^<, ^^^>) to survive the double-evaluation pass of the Windows shell.

Here is the diff that resolves the issue inside tools/browser_tool.py > _run_browser_command:

 else:
     cmd_prefix = [browser_cmd]

• original_args = list(args)
• if os.name == "nt" and args:

•    # Prevent Windows CMD from splitting URLs on '&' when calling .cmd wrappers.

•    # list2cmdline automatically wraps strings with spaces in double-quotes (which protects '&' natively).

•    # We inject caret (^) escapes for strings WITHOUT spaces.

•    # Note: .cmd wrappers evaluate arguments twice (once by cmd.exe, once inside the .cmd via %*),

•    # so a single caret ^& is consumed on the first pass and fails on the second. We need triple carets ^^^&.

•    is_cmd = cmd_prefix[0].lower().endswith(".cmd") or cmd_prefix[0].lower().endswith(".bat")

•    args = [

•        a.replace("&", "^^^&").replace("|", "^^^|").replace("<", "^^^<").replace(">", "^^^>")

•        if is_cmd and isinstance(a, str) and " " not in a else

•        (a.replace("&", "^&").replace("|", "^|").replace("<", "^<").replace(">", "^>") if isinstance(a, str) and " " not in a else a)

•        for a in args

•    ]

• else:

•    is_cmd = False

• cmd_parts = cmd_prefix + backend_args + [ "--json", command ] + args

Affected Component

Tools (terminal, file ops, web, code execution, etc.)

Messaging Platform (if gateway-related)

N/A (CLI only)

Debug Report

✓ Stopped gateway for this profile
PS C:\Users\mukul\AppData\Local\hermes\hermes-agent> hermes debug share
⚠️  This will upload the following to a public paste service:
  • System info (OS, Python version, Hermes version, provider, which API keys
    are configured — NOT the actual keys)
  • Recent log lines (agent.log, errors.log, gateway.log — may contain
    conversation fragments and file paths)
  • Full agent.log and gateway.log (up to 512 KB each — likely contains
    conversation content, tool outputs, and file paths)

Pastes auto-delete after 6 hours.

Collecting debug report...

Operating System

Windows

Python Version

3.11

Hermes Version

0.14

Additional Logs / Traceback (optional)

Root Cause Analysis (optional)

No response

Proposed Fix (optional)

No response

Are you willing to submit a PR for this?

• I'd like to fix this myself and submit a PR