Function parseCommand

src/shared/parse-command.ts:471–537

(command: string)

 * should surface the error rather than proceeding with auto-approval.
 */
export function parseCommand(command: string): ParseResult {
	if (!command?.trim()) {
		return { commands: [], parseError: null }
	}

	// Run the shared state-machine scan once. It gives us both the list of
	// top-level quoted spans (used by maskTopLevelQuotes) and the parse-error
	// descriptor (used here to detect malformed input) in a single pass.
	const { unterminatedQuote } = scanTopLevelQuotes(command)

	// Reject syntactically malformed input -- an unterminated quote is a shell
	// syntax error. Return the raw input as a single opaque token so callers
	// can surface the error to the agent rather than splitting unsafe fragments
	// that might be auto-approved in isolation.
	if (unterminatedQuote !== null) {
		return { commands: [command], parseError: unterminatedQuote }
	}

	// Pre-escape any literal __ sequences present in the raw command so they
	// cannot collide with the internal placeholder tokens (e.g. __QUOTE_0__)
	// used during masking and splitting. \x00 (the null byte, U+0000) is the
	// sentinel: it encodes end-of-string at the C/OS level, so the OS terminates
	// any command string at the first \x00 -- meaning a real shell command can
	// never contain one. It therefore cannot appear in any command text the
	// parser receives and will never match a placeholder regex. The post-unescape
	// step at the return converts \x00 back to __ in every output command.
	const escapedCommand = command.replace(/__/g, "\x00")

	// Mask quoted strings before splitting on newlines so that newlines embedded
	// inside a quoted argument are not mistaken for command separators. The
	// masker delegates to scanTopLevelQuotes internally, ensuring identical
	// quoting rules with the check above.
	const { masked, quotes: topLevelQuotes } = maskTopLevelQuotes(escapedCommand)

	// Split on unquoted newlines (all line-ending formats).
	const lines = masked.split(/\r\n|\r|\n/)
	const allCommands: string[] = []

	for (const line of lines) {
		if (!line.trim()) {
			continue
		}

		// Restore top-level quote placeholders before per-line parsing so that
		// parseCommandLine sees the original quoted content and can apply its own
		// masking for operator splitting.
		const restoredLine = line.replace(/__TOPLEVEL_QUOTE_(\d+)__/g, (_, i) => topLevelQuotes[parseInt(i)])

		// If the restored line contains embedded newlines it means a top-level
		// quote (e.g. a heredoc) spanned multiple lines. The entire restored
		// string is a single atomic command -- passing it through parseCommandLine
		// would let shell-quote split on the embedded newlines and << operators.
		if (restoredLine.includes("\n")) {
			allCommands.push(restoredLine)
			continue
		}

		const lineCommands = parseCommandLine(restoredLine)