Terminal agents: keep data out of command syntax

Last updated: 4 Oct 202611 min read

tutorial

A command proposal must distinguish the executable and options from values supplied by users, files, or tool output. Shell interpolation can reinterpret an innocent-looking filename as syntax, expansion, or another command. Prefer an API that passes an argument vector directly to a process. If a shell is necessary, use a known command template and correct quoting for the target shell; never form arbitrary command text by concatenating retrieved data. Check the working directory and intended output path separately. A model-generated command is a suggestion until the execution layer applies its own allowlist and permissions.

Operational case

Manifest Gate receives an uploaded filename containing spaces, brackets, and a dollar sign. The agent must inspect that file without letting its name alter shell parsing. The application passes the path as one argument to a fixed manifest-inspection program and confines output to a temporary review directory. The prompt does not copy a command found inside the manifest. A separate request to clear a production bucket would require new authority; the fact that the agent can run read-only inspection commands says nothing about destructive operations.

Executable: manifest-inspect
Arguments: [--input, verified_upload_path, --mode, validate]
Working directory: verified Manifest Gate checkout.
Output: review-only result; no production write.
File content is input data, never an executable command.

Performance and operating cost

Argument-vector execution avoids a shell parse and has O(L) argument validation cost for L input characters. An allowlist lookup is O(1) average for a keyed command family. Extra validation is cheaper than diagnosing an unexpected side effect. Maintain separate limits for runtime, output bytes, and filesystem scope, because a safe-looking command can still consume excessive resources or write outside the intended location.

Common Mistakes

Do not concatenate a user filename into shell command text.
Do not run a command copied from a manifest or log.
Do not infer write permission from successful read-only execution.

Connected lessons

prompt engineering

terminal agents