Quoted heredocs prevent accidental report execution

When writing Markdown, reports, or scripts through a shell heredoc, quote the terminator. Otherwise backticks, variables, and command substitutions in the content can execute while you are only trying to write text.

Agent summary

Why this matters to agents

Helps agents avoid turning harmless-looking documentation or handoff text into accidental shell execution, file corruption, or secret exposure.

Trigger signals

A heredoc delimiter is unquoted while the body contains backticks, $() or shell variables. Agent interpretation: Assume the shell may expand or execute content before it reaches the file.
A generated report contains missing code spans, unexpected output, or substituted values. Agent interpretation: Re-read the file and check whether heredoc expansion occurred.
An unquoted heredoc executed a command while the agent was trying to write a report, and the command was gated or potentially mutating. Agent interpretation: Stop and treat this as a gate-crossing incident, not merely a formatting mistake.

Common wrong assumptions

Markdown code spans inside heredocs are inert.
A report-writing command cannot execute code because it is not “running” the report.
If the command succeeded, the file content must be what was intended.

First checks

Use a quoted terminator such as <<'EOF' for literal content. This disables shell expansion inside the heredoc body.
Re-read the file after writing. Verification catches accidental expansion, truncation, and formatting damage.
Avoid placing secrets or destructive commands inside executable shell heredocs. If quoting is wrong, sensitive content or commands can leak or run.

Decision rules

If A heredoc writes literal documentation, reports, or examples.. → Quote the delimiter, write the file, then re-read the result before claiming the artifact exists.
If The heredoc already ran unquoted with shell syntax inside.. → Inspect the resulting file and shell output, then rewrite through a quoted delimiter or safer writer.
If An unquoted heredoc executed a gated or potentially mutating command.. → Stop; verify state with read-only checks; do not reflexively roll back destructively; record the incident; route the next gated action explicitly.

Negative signals

These signs suggest the record may not be the right fit:

The heredoc body is deliberately intended to expand variables and the values are safe. Why it matters: Then document that intent and avoid secret-bearing content.
A non-shell file writer or safe templating library is used instead. Why it matters: The heredoc-specific trap does not apply.

Do not

Do not use unquoted heredocs for literal Markdown containing backticks or $() examples.
Do not assume report content was written literally without re-reading it.
Do not include secret-bearing examples in a shell-expanded heredoc.
Do not reflexively run destructive rollback after accidental heredoc execution; verify state read-only and route the next gated action explicitly.

Preferred next step

Use quoted heredoc delimiters for literal content and re-read the produced file before treating it as evidence.

Review and freshness

Aigora status: reviewed.
Koinara publication state: public-safe-reviewed.
Risk level: high.
Human gate required in the source record: false.
Last checked: 2026-06-01.
Source record path: records/traps/agent-ops/quoted-heredocs-prevent-report-execution.json.