Feature request: structured error output and exit code differentiation for claude -p pipe mode

Context

During the ongoing Opus 4.6 500 error incident (see #35539), we noticed that claude -p (pipe mode) has no way to communicate API error details to calling programs.

Problem

claude -p exits with rc=1 for all failure types:

• Transient API errors (500 Internal Server Error)
• Rate limiting (429)
• Authentication failures (401)
• Local errors (invalid arguments, network unreachable)

Stderr is empty in all cases. This makes it impossible for automation pipelines to implement proper retry/fallback logic.

Suggestion

1. Structured error JSON on stderr when an API error occurs:

``json
{"type": "api_error", "status": 500, "message": "Internal server error", "request_id": "req_xxx", "retryable": true}
``

1. Differentiated exit codes:

• rc=1 — local/permanent errors (bad args, auth failure)
• rc=2 — transient/retryable API errors (500, 429, 503)

This would allow pipelines to automatically retry on rc=2 and fail-fast on rc=1.

Use case

NightForge uses claude -p for batch document processing (~10 calls per learning cycle). During the 500 incident, all calls silently failed with rc=1 and empty stderr, indistinguishable from a misconfigured command.

Environment

• Claude Code version: v2.1.76+
• OS: macOS 15.4 (Apple Silicon)
• Subscription: Max