claude-code - 💡(How to fix) Fix Bash tool on Windows hangs on npx/npm commands and ignores explicit timeout

Summary

On Windows, the Bash tool hangs indefinitely when running npx/npm commands (anything invoking a .cmd shim) even though the underlying process has already terminated cleanly. The timeout parameter passed to the tool call is not enforced.

Environment

• OS: Windows 11 Enterprise 10.0.22631
• Native shell of the Claude Code session: PowerShell 5.1
• Bash tool: Git Bash (MSYS2/MinGW) shipped with Git for Windows
• Node.js project: Vite 7.3.1 + Vitest 4.0.18 + happy-dom 20.6.1 (representative, not a Vitest-specific issue — any npx command that spawns workers reproduces it)

Reproduction

1. From within a Node.js project, call the Bash tool with:
   • command: npx vitest run tests/components/SomeFile.test.js
   • timeout: 120000 (2 minutes)
2. Test completes in ~5s (verified by running the same command directly in PowerShell — output below).
3. Bash tool stays in waiting state. The 2-minute timeout is not enforced. Manual interrupt required after 7 minutes of waiting.

Same command, PowerShell tool (works correctly)

RUN  v4.0.18 C:/Dati/selenium/test-automation/ta-frontend
 OK  tests/components/TestResult.test.js (2 tests) 85ms

 Test Files  1 passed (1)
      Tests  2 passed (2)
   Duration  6.86s
SonarQube report written to ...test-report.xml

Prompt returned immediately after the report line.

Same command, Bash tool (hangs)

Same output produced internally (verified by user running it manually), but the Bash tool never returns control to Claude. No orphan node.exe processes remained after the manual interrupt (verified with Get-Process node), so child workers exited cleanly — the hang is in the EOF/marker propagation between Git Bash and Claude Code.

Hypothesis on root cause

• npx on Windows is a .cmd shim (npx.cmd).
• Process chain when launched via Bash tool: bash.exe (MSYS2) -> cmd.exe (npx.cmd) -> node.exe -> tinypool workers.
• Vitest calls process.exit(0) after writing reporter output instead of returning naturally.
• EOF propagation from cmd.exe back to bash.exe (MSYS2) appears to not occur cleanly when node exits via process.exit(). The Bash tool waits for an end-of-command marker that never arrives.
• This is consistent with known Git Bash issues around .cmd script termination on Windows.

Two distinct bugs

1. Hang on .cmd shims: Bash tool does not detect command completion when the command chain involves a .cmd shim and process.exit().
2. timeout parameter ignored: The explicit timeout: 120000 should have killed the command at 2 minutes regardless of cause #1. It did not.

Suggested fixes

1. Make the timeout parameter actually enforce the kill (this is the most actionable — even if cause #1 is hard to fix, a respected timeout would limit the damage to 2 minutes instead of being unbounded).
2. On Windows, when the session shell is PowerShell, the Bash tool should either route .cmd-shim commands (npx, npm, yarn, pnpm, node via shims) through PowerShell, or surface a clear warning that they are unreliable.
3. Document this limitation in the Bash tool description on Windows.

Impact

User wasted 7+ minutes per occurrence waiting for a 5-second command. Multiple occurrences in a session erode trust in the tool. Workaround (use PowerShell tool instead) is now in my conversation memory so I do not repeat it — but the underlying bug is real.