Error context destroyed through exception flattening — CLI failures produce unhelpful 'Command failed with exit code 1'

[itsnotatbug]

SDK version

claude-agent-sdk==0.1.56

Description

When the Claude CLI subprocess exits with a non-zero code, the SDK destroys all error context through a 3-step chain, making failures impossible to diagnose:

1. _internal/transport/subprocess_cli.py:614 — ProcessError is created with stderr="Check stderr output for details" (hardcoded string, not actual stderr from the process)
2. _internal/query.py:250 — Caught in _read_task, flattened via str(e), sent as {"type": "error", "error": str(e)} through the message stream
3. _internal/query.py:726 — receive_messages() re-raises as bare Exception(message.get("error")), losing the ProcessError type entirely

Consumer code that catches ClaudeSDKError never fires because the exception arrives as bare Exception.

Reproduction

Any scenario where the Claude CLI process exits with code 1 (permission denied, internal error, bad config). The consumer receives:

Exception: Command failed with exit code 1 (exit code: 1)
Error output: Check stderr output for details

No actual stderr, no typed exception, no actionable detail.

Issues found (in order of severity)

File	Line	Problem
subprocess_cli.py	616	stderr="Check stderr output for details" is hardcoded — actual stderr is never captured into the error
query.py	250	str(e) flattens ProcessError (which has exit_code/stderr attrs) into a plain string
query.py	726	raise Exception(...) instead of preserving/re-raising original exception type — except ClaudeSDKError in consumer code never triggers
query.py	207-209	Control request errors also create bare Exception from dict
subprocess_cli.py	446-449	stderr reading exceptions silently swallowed (except Exception: pass)
subprocess_cli.py	608	process.wait() failure caught as returncode = -1, no logging
query.py	272, 318, 334, 346, 385, 420	Bare Exception() instead of typed ClaudeSDKError subclasses

Expected behavior

1. ProcessError.stderr should contain the actual stderr output from the CLI process, not a hardcoded string
2. query.py:726 should raise ProcessError (or at minimum ClaudeSDKError), not bare Exception — so consumer except ClaudeSDKError blocks work
3. query.py:250 should preserve the exception object (or at least its type and attributes) rather than stringifying it

Workaround

Consumer code must catch Exception (not ClaudeSDKError) and try getattr(exc, "exit_code", None) defensively. But even that doesn't help here because the attributes are stripped at step 2 before re-raising.

Environment

• Python 3.14.3
• claude-agent-sdk 0.1.56
• Windows 11
• Claude Code CLI installed via npm

[itxaiohanglover]

Hi, I've opened PR #961 to address this issue with a focused fix (+23/-4 lines).

Background — why a new PR:

I reviewed the two previous attempts:

• PR fix(errors): preserve exit_code and stderr in ProcessError chain (#800) #828 by @xodn348: fixes the query.py exception pass-through but doesn't address the hardcoded stderr placeholder in subprocess_cli.py — layer 1 of the 3-step chain remains broken.
• PR fix: preserve ProcessError context from failed CLI subprocesses #843 by @lawrence3699: fixes both files but was closed after Copilot raised 3 concerns: (1) misleading comment about stderr streaming behavior, (2) potential stderr leak into logs via logger.error, and (3) backward-incompatible change to debug_stderr forwarding.

What PR #961 does differently:

1. subprocess_cli.py — Adds a bounded deque buffer (8KB tail) that captures stderr lines in _handle_stderr() and passes the real stderr to ProcessError instead of "Check stderr output for details". Only active when stderr is already piped (user registered a callback). No change to stderr piping or forwarding behavior.

2. query.py _read_messages() — Passes the original exception object through the error message dict ("exception": e) alongside the error text, preserving type and attributes.

3. query.py receive_messages() — Re-raises the preserved exception if available, falls back to ClaudeSDKError (not bare Exception). So except ProcessError and except ClaudeSDKError handlers in consumer code now fire correctly.

How it avoids PR #843's 3 issues:

• No change to stderr=PIPE gating — only captures from already-piped stderr
• No change to logger.error — logs still use str(e) as before
• No change to debug_stderr forwarding logic — backward compatible

Before -> After example (using the trigger from #800):

# Before (SDK 0.1.81):
except Exception as e:
    print(type(e).__name__)  # Exception
    print(e)                  # Command failed with exit code 1 (exit code: 1)
                              # Error output: Check stderr output for details

# After (PR #961):
except ProcessError as e:
    print(type(e).__name__)  # ProcessError  (inherits ClaudeSDKError)
    print(e.exit_code)       # 1
    print(e.stderr)          # error: --max-budget-usd must be a positive number greater than 0

All 131 existing tests pass, including the 5 TestProcessExitAfterErrorResult tests that verify the _last_error_result_text replacement logic still works correctly.