Graceful Refusals as Unsignalled Failures: Characterising claude -p Exit-Code Semantics on Agent Declines
Shell pipelines and agent harnesses route control flow on the exit code of LLM command-line runners, a channel POSIX defines as zero for successful completion. Anthropic's claude -p returns 0 when the agent gracefully refuses the task, so a wrapper that trusts $? reads the refusal as success. We argue that the defect is the width of the channel: an agent runner has at least four task outcomes and the exit code two values for them. On N=50 refusal-provoking prompts (Claude Code 2.1.200, July 2026, run inside the author's own configuration), 24 trials exit 0, all with stop_reason: end_turn, and 12 to 20 of them are graceful declines: 24% to 40% of the suite depending on how a decline is counted (40% under the author's label, 95% Wilson CI 28-54%), with an 18% floor from an English-only phrase detector. Among the 24 exit-0 trials no status field separates a decline from a delivery; for the question a wrapper asks (was the task delivered?) the exit code carries 0.09 of 0.40 bits (22.4%). We steel-man exit 0 as a process status, name the trade-off between in-band and out-of-band signalling, and propose an opt-in typed termination contract, with a content check tested in-sample as the stopgap. Technical note, version 2.3, in English, Portuguese, Spanish and Italian. Every number is re-derived from committed data in the companion software and replication package, release 2.0.0: https://doi.org/10.5281/zenodo.20276631
Authors
- Carlos Ulisses Flores (ORCID: https://orcid.org/0000-0002-6034-7765)
Publication Details
- Journal
- Zenodo (CERN European Organization for Nuclear Research)
- Published
- 2026-11-09
- DOI
- https://doi.org/10.5281/zenodo.24065934
- Primary Topic
- Software Engineering Research
- Type
- article
- Field-Weighted Citation Impact
- 0.00