Exit codes as a contract between scripts and the agent that calls them

What it is

The GNU Bash manual states that a command killed by fatal signal N gets exit status 128+N — the widely used convention that codes above 128 mean "killed by signal N" (143 for SIGTERM, 137 for SIGKILL). POSIX itself only requires a value above 128; bash, dash and zsh use 128+N, while ksh93 reports 256+N. POSIX does mandate 126 for "found but not executable" and 127 for "command not found". 0 means success everywhere; 1–125 is free for the script to define. Exit codes are 8-bit: exit 256 arrives as 0 and exit 300 as 44.

Why it matters

An agent that only checks "zero or not" loses information a well-behaved script already computed for it; an agent that assumes a specific non-zero number means one particular thing across all tools will eventually be wrong, because 1–125 is not standardized beyond "not success". Two further traps hide the real exit code from the caller:

• Pipelines: cmd1 | cmd2 in bash normally reports cmd2's exit status only. set -o pipefail (bash, zsh, ksh; not in dash 0.5.12) changes that so the pipeline's status is the rightmost non-zero status of any stage — without it, a failing first stage feeding a successful grep looks like total success. Bash's PIPESTATUS array, documented in the manual's Bash Variables section, holds every stage's individual exit status right after the pipeline runs (${PIPESTATUS[0]} for the first command), the way to know which stage failed (zsh: lowercase pipestatus).
• PowerShell's two different signals: exit <n>, documented in about_Language_Keywords, sets $LASTEXITCODE and ends the script. throw, documented in about_Throw, raises a terminating error; if nothing catches it, pwsh -File and -Command both exit with 1 (about_Pwsh). The traps: a script whose catch swallows the error, or that only emits non-terminating errors, exits 0 under -File; and under -Command any specific code other than 0/1 is collapsed to 1 unless the command string ends with exit $LASTEXITCODE.

How to apply

• Reserve 0 strictly for success in every script an agent generates, and document the meaning of any other codes the script defines in a comment near the top.
• Always add set -o pipefail to bash scripts whose result depends on an earlier stage of a pipeline, and read PIPESTATUS when the caller needs to know which stage failed.
• End every PowerShell script's top-level error handling with an explicit exit 1 (or a more specific code) in the catch block, not just a throw, whenever the script must communicate failure to a non-PowerShell caller.
• When wrapping a native tool, check $LASTEXITCODE (PowerShell) or $? (POSIX shell) immediately after the call, before any other command overwrites it.

Pitfalls

• Treating exit code 1 from an unfamiliar tool as always meaning the same thing as exit code 1 from another tool.
• Reading $? after any intervening command (even echo), or $LASTEXITCODE after another native program ran.
• Expecting a native exit code inside a Start-Job or thread job to reach the caller's $LASTEXITCODE; return it as job output and check the job's State.