File-write directive prescribes heredocs without gating on platform, breaking on Windows

Summary

The file-writing directive injected into the system prompt prescribes a POSIX-specific shell idiom (heredocs) without being gated on platform. On Windows this conflicts with the Bash tool's own documentation, and the model is left to arbitrate between two contradictory instructions in the same context. It frequently arbitrates wrong, producing failed writes and wasted tokens.

Environment

• OS: Windows 11 Home 10.0.26220
• Platform reported in context: win32
• Shell reported in context: PowerShell (primary), Bash tool available (Git Bash)

The conflict

The session context correctly identifies the platform. It contains Platform: win32, Shell: PowerShell (primary), and the Windows version. Platform detection is not the problem.

The Bash tool's own description is also Windows-aware and explicitly says:

Do not use PowerShell here-strings (@'...'@) or backtick continuation here — for multi-line strings use a heredoc.

But a separate directive that governs how file edits should be performed instructs the model to make file changes via "sed, heredocs, or short scripts" rather than the dedicated Write/Edit tools. That directive contains no platform condition.

So two instructions coexist: one platform-aware, one not. Nothing resolves them except model judgment on each individual call.

Why it fails on Windows

• The PowerShell tool has no heredoc construct at all. The nearest equivalent, @'...'@, requires the terminator at column 0 and breaks if the command string is indented or normalized in transit.
• The Bash tool is Git Bash, a real POSIX shell, so heredocs sometimes work. But the command is marshalled as a single string across a Windows process boundary, so $, backticks, backslash paths, and CRLF can corrupt the content before sh parses it.

Intermittent success is the worst case: it works often enough that the behavior is never self-correcting.

Impact

• A failed heredoc write costs roughly 2-3x the tokens of the equivalent Write call — the content is sent, the error returns, the content is sent again in another form.
• A malformed here-string can truncate a file rather than failing cleanly, which is worse than an error.
• Neither cost buys anything. Write performs the same operation deterministically on every platform.

Suggested fix

Gate the shell-idiom guidance on platform. On win32, the directive should either omit heredocs or explicitly prefer the Write/Edit tools for file content, keeping Bash for read and search operations (cat, grep, ls, find, git) where it is genuinely the better tool.

More generally: when the harness already knows the platform, platform-specific tool guidance should not be left for the model to reconcile at inference time against a generic instruction.