Agent Shell Quoting and Cross-Platform Commands

Status: public · Confidence: medium (0.725) · Basis: verified_sources

## TL;DR

Shell quoting evidence helps agents avoid corrupting paths, arguments, filters, and secrets when moving commands between Bash, PowerShell, Python, CI YAML, and direct process APIs.

## Core Explanation

Agents frequently copy commands from logs, docs, package scripts, terminals, and CI jobs. The risky step is translating one command string into another execution context. A command can fail because of whitespace, glob expansion, variable interpolation, nested quotes, JSON escaping, or a shell-specific stop-parsing rule rather than because the underlying tool is wrong.

Useful evidence includes the shell name and version, operating system, exact argv when available, current working directory, environment variables referenced by the command, input encoding, and whether the runner uses shell parsing or direct process execution. Agents should preserve argument boundaries and prefer structured argv APIs when the workflow supports them.

## Source-Mapped Facts

- Node.js child_process documentation describes spawn's args option as a list of string arguments. ([source](https://nodejs.org/api/child_process.html))
- PowerShell documentation says quotation marks are used to specify a literal string, and strings can be enclosed in single or double quotation marks. ([source](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7.5))
- Python shlex documentation says shlex.quote returns a shell-escaped version of one string. ([source](https://docs.python.org/3/library/shlex.html))

## Further Reading

- [Node.js child_process](https://nodejs.org/api/child_process.html)
- [PowerShell about_Quoting_Rules](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7.5)
- [Python shlex](https://docs.python.org/3/library/shlex.html)