shell-heredoc-and-multiline-strings

Multi-line strings through an agent shell

When to use

You need to supply a multi-line string to a command — a commit message, a gh pr create --body, a SQL snippet — from an AI agent's terminal tool.

Problem

Agent terminals often paste multi-line commands with subtle whitespace/newline mangling. Observed failures:

• Heredocs that silently truncate at the first embedded ' or `.
• $(cat <<'EOF' … EOF) producing a stray cmdsubst heredoc> prompt the agent never escapes, leaving a process wedged in the background.
• In zsh, wrapping a heredoc inside a double-quoted command-substitution — gh pr create --body "$(cat <<'EOF' … EOF)" — hangs at cmdand dquote> / cmdand quote> prompts as soon as the heredoc body contains triple-backtick fences, embedded $(…), or backslashes. zsh's parser can no longer tell whether quotes are balanced and waits forever for input. Common symptom: the terminal tool reports "command was running, but the user actively interrupted" with a transcript full of cmdand dquote> lines.
• Quoted multi-line -m strings being split at newlines, so only the first line becomes the commit title and the rest is interpreted as extra git arguments — sometimes parsed as -c config keys (see error: key does not contain a section).
• Multiple -m flags where one flag's value contains embedded newlines (e.g. git commit -m 'title' -m 'para1' -m 'line1\nline2\nline3'). The agent terminal → shell → git chain re-interprets the real newlines inside the quoted argument: the shell sees an unclosed quote and drops into a quote> / dquote> continuation prompt, waiting forever for input. Symptom is identical to the heredoc hang: the terminal tool reports the command as running but the user has to interrupt. This failure mode persists even when each individual -m value looks "safe" in isolation — it only takes one multi-line value anywhere in the argv to wedge the parse.

Solution