Windows agent shell — traps, and the works-here-breaks-there class

A coding agent on Windows runs its commands through Git Bash, PowerShell or cmd, and each one splits arguments, expands characters, converts paths and decodes text differently. A command that is right in one is wrong in another, and the dangerous cases don't fail: they pass with a different meaning. Most of the receipts below cost an hour or more because the failure looked like a code problem.

The rule under all of them: when something works here and breaks there, suspect the environment you did not measure. The shell, the CLI's version, the spelling of a path and a file's line endings are part of the invocation. When a config change seems to fix or break something, first check that the invocation was held constant.

Every version-specific line carries the version and date it was observed. Vendors change these monthly; § Re-verify says how to re-test.

First, know which shell runs the command

• Claude Code's Bash tool on Windows is Git Bash (MSYS2). Without Git for Windows it uses PowerShell instead (2.1.120), and with the PowerShell tool enabled PowerShell becomes the primary shell (2.1.126) (changelog, read 2026-10-24).
• Shell-form hooks run through Git Bash, or PowerShell when Git Bash is missing; Cursor runs hook commands through PowerShell; Codex takes a separate commandWindows. The guardrail-hooks skill has the hook side.
• Windows PowerShell 5.1 (powershell.exe) ships with Windows; PowerShell 7 (pwsh) is a separate install and is often absent (a dev box had only 5.1 on 2026-08-17, and still on 2026-10-24). A script or instruction that says pwsh fails there.
• Measure, don't reason: python <skill dir>/scripts/probe_argv.py <the same arguments> in the same shell prints exactly what a program receives, and which encodings its pipes use.

Paths