query() stream hangs forever (never raises) when the CLI process dies mid-run

[clriesco]

SDK version: 0.2.115 · CLI: 2.1.206 · Platform: macOS (darwin)

Bug

When the claude subprocess dies mid-run (observed repeatedly when a Pro/Max
subscription hits its rate-limit window and the CLI exits with code 1), the
SDK logs Fatal error in message reader: Command failed with exit code 1
but the query() async stream neither terminates nor raises — a consumer
awaiting the next message waits forever.

Repro sketch

import asyncio
from claude_agent_sdk import ClaudeAgentOptions, query

async def main():
    stream = query(
        prompt="Write a long essay.",
        options=ClaudeAgentOptions(model="claude-haiku-4-5", tools=[], max_turns=1),
    )
    async for msg in stream:   # kill the spawned `claude` process mid-generation:
        print(type(msg).__name__)  #   pkill -f "claude.*stream-json"
    print("stream ended")          # <- never reached; no exception either

asyncio.run(main())

Killing the subprocess externally reproduces it deterministically; the
organic trigger we hit was subscription rate-limit exhaustion.

Expected

Process death should end the stream: either raise ProcessError (ideal, with
the exit code) or terminate the iteration, so consumers can react instead of
hanging. receive_messages()'s internal reader appears to catch the fatal
error without closing the memory channel the consumer is blocked on.

Impact / workaround

Any consumer without an explicit timeout hangs indefinitely; timeouts that
cancel the iteration can additionally leak the transport if cleanup tasks are
scheduled on a loop that closes right after. We work around it in
langchain-claude-cli with a per-message inactivity watchdog plus an explicit
stream.aclose() executed inside the still-running loop.

[anishesg]

Opened #1111 with a fix for this.

[Echolonius]

I dug into this with a protocol-faithful fake CLI (completes the initialize handshake, emits messages, then dies without a result) so the scenario is deterministic, and found something surprising: the plain process-death path does not hang on current main (whose query.py/client.py/subprocess_cli.py are identical to 0.2.115). Killing the CLI mid-run — exit 1 or SIGTERM, on asyncio, trio, and uvloop — surfaces the trailing ProcessError to the async for consumer in milliseconds. The Fatal error in message reader → error-message → raise chain works.

What does reproduce your symptom exactly — stream neither terminates nor raises, forever — is the CLI dying while a child process it spawned survives holding its inherited stdout pipe (MCP servers, shell helpers…). One line in the fake CLI triggers it deterministically: spawn sleep 300, then sys.exit(1). Then:

1. The transport's read loop blocks in async for chunk in self._stdout_stream waiting for an EOF that never comes — the orphan holds the write end — so the exit-code check at the bottom of _read_messages_impl is never reached and no error is ever emitted.
2. On the asyncio backend it's worse: await process.wait() is also gated on those same pipes (asyncio's subprocess transport resolves waiters only after every pipe protocol disconnects). Probe: orphan-holding child + parent exits 7 → returncode is visible in ~0.5s, wait() still blocked 8s later. So both death signals the transport relies on are held hostage by the same pipe.

This fits both of your triggers: a rate-limit exit 1 doesn't reap the CLI's helpers, and pkill -f "claude.*stream-json" kills only the CLI (helper cmdlines don't match the pattern). It also means even a successful run hangs after its result message if a helper outlives the CLI. If you can still reproduce organically, ps / lsof on the dead CLI's pipe should show the surviving holder — would be great confirmation.

One caveat I want to flag honestly: in the orphan scenario the reader never wakes, so the Fatal error in message reader log line would not be printed by the hanging query. If you consistently see that line immediately before a hang (same session, not an earlier one that recovered), there may be a second mechanism on macOS I couldn't reproduce on Linux — the repro sketch from the report, run as-is, raises properly here.

Fix in #1112: a process-exit watcher on the transport that polls returncode (not wait(), per gotcha 2) and force-closes the stdout stream once the reader has been parked on a silent pipe for a full grace window after death — with chunk-progress and parked-on-read guards so consumer backpressure or mid-drain readers are never cut off (a 120-message burst with a slow consumer still delivers everything before the ProcessError).

[clriesco]

Thanks for your comment!. Quick answers to your points:

• Confirmed on the organic trigger: During manual testing (hitting actual Pro/Max rate limits, not a synthetic pkill), the Fatal error in message reader log hit immediately before the stream hung in that same session. This suggests that on macOS (CLI 2.1.206, SDK 0.2.115), there is indeed an execution path where the reader wakes and logs the error, but still fails to close the channel—distinct from the orphan-child-pipe scenario you reproduced on Linux.

• Process/port state: I didn't capture ps or lsof during that specific hang. At the time, we just stood up an inactivity watchdog to bypass the block rather than debugging the transport layer. I can't easily force a real rate-limit state to reproduce right now, but I'll grab ps/lsof on the stalled CLI pipe if we hit it again and drop the dump here.

Let me know when #1112 is ready; happy to run it against our workaround to verify the fix.