このバグが通常のテストでは発見しにくいのはなぜか？
純粋なタイミングの競合状態の問題だからだ——バックグラウンドサブエージェントが主結果の到着と「ちょうど」同じ瞬間に完了したときにのみ発生する。通常のテストでバックグラウンドタスクが主結果よりずっと速く、あるいはずっと遅く完了する場合、この時間帯に入ることはなく、接続クローズのタイミングとバックグラウンドタスク完了のタイミングがずれるため、問題なく動作する。これがこの種のバグが「間欠的」「安定して再現できない」と表現されがちな理由でもある——テストが不十分なのではなく、問題自体の発生条件が非常に狭いタイミングウィンドウであり、バックグラウンドタスクを大量に並行実行する本番環境の方が、開発環境よりもこのウィンドウに当たりやすい。
CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS を長く設定しすぎたり短く設定しすぎたりすると、それぞれどんな結果になるか？
短く設定しすぎる（数秒など）と、待機時間を延ばしたことによる恩恵がほぼなくなる——バックグラウンドタスクが本来数分かかる場合、短すぎる上限はタスクが実際に完了する前に SDK を強制的に先へ進ませてしまい、修正前の「早期クローズ」のリスクに事実上逆戻りする。ただしトリガー条件が「競合状態の偶然の一致」から「上限設定が短すぎることの必然的な結果」に変わるだけだ。長く設定しすぎる（数時間まで延ばす）と、バックグラウンドタスクが本当に詰まって二度と idle を報告しないシナリオにおいて、接続がハングする時間がより長くなり、利用者や呼び出し側が異常に気づくまでより長く待つことになる。
より実用的なアプローチは、まず実際のバックグラウンドタスクが通常の条件下でどれくらいの時間で完了するかを観察し、その時間よりやや大きいバッファ値を選ぶことであり、デフォルトの10分や適当に大きい数値をそのまま使うことではない。
デプロイ環境の CLI バージョンが古く session_state_changed に対応していない場合、SDK をアップグレードする意味はあるか？
意味はあるが、効果は限定的になる。SDK 側は CLI が session_state_changed イベントを発行するかどうかを自動検出し、発行しない場合は旧来の「最初の結果到着でクローズ」ロジックにフォールバックする——つまり SDK 単体のアップグレードではエラーや互換性の問題は発生しないが、このバグ修正の効果は実際には機能せず、元の競合状態に依然として遭遇する可能性がある。
この修正の恩恵を実際に受けるには、SDK のアップグレードと、session_state_changed に対応したバージョンへの CLI のアップグレードの両方を行う必要があり、どちらか一方だけでは問題を完全には解決できない。
この修正は hooks、can_use_tool、SDK MCP サーバーを使用している場合にのみ関係があるのか？これらの機能を使っていないアプリケーションはこのバグを気にする必要があるか？
changelog は明確にこのバグが「query() を hooks、can_use_tool、または SDK MCP サーバーと組み合わせて使用する」文脈で発生すると記しており、これはトリガー条件がバックグラウンドサブエージェントのライフサイクル管理に関連していることを示している——これらの機能はいずれもバックグラウンドで実行される可能性のある追加の処理を伴う。アプリケーションがバックグラウンドサブエージェントの仕組みを一切使用していない場合（並行ツール呼び出しやバックグラウンド検証処理のない、純粋に同期的な質問応答フローなど）、理論上はこの特定の競合状態には遭遇しないはずだが、SDK のアップグレード自体に副作用はないため、ルーティンの更新として行うのは依然として妥当な判断だ。
Claude Agent SDK の query() を hooks、can_use_tool コールバック、または SDK 内蔵の MCP サーバーと組み合わせて使う際、特定の状況下で接続切断が安定的に発生することがあった：バックグラウンドのサブエージェントが、主な会話ターンの結果が届こうとしているまさにそのタイミングで完了すると、SDK の旧ロジックは stdin を早く閉じすぎてしまう。結果として次のターンは「Stream closed」エラーで即座に失敗し、モデル側ではこれが「このツール呼び出しが拒否された」と誤って認識される——しかし実際にはツール呼び出し自体には何の問題もなく、根本原因は下層の接続のライフサイクル管理のタイミングがずれていたことにある。
この修正以前、SDK が「このターンは stdin を閉じてよい」と判断するロジックは「最初の result メッセージを受信したこと」を基準としていた——これはほとんどの場合問題ないが、バックグラウンドのサブエージェントがちょうど主結果の到着と同じタイミングで完了すると、競合状態（レースコンディション）が発生する：SDK はこのターンが終わったと判断して接続を早期に閉じるが、CLI 側では実際にはまだバックグラウンドサブエージェントの後処理を行っており、その続行には同じ接続が必要となる。新しい修正では、CLI 自身が発行する session_state_changed メッセージをリッスンし、CLI が明示的に状態を idle（本当にアイドル状態で、バックグラウンド処理が一切実行されていない）と報告するまで stdin を閉じないようにした——「最初の結果を受信した」という間接的なシグナルから推測するのではなく。
単に「CLI が idle を報告するまで待つ」に変更するだけでは、理論上は早期クローズの問題を解決できるが、新たなリスクも生じる——何らかの理由でバックグラウンドタスクが詰まって二度と idle を報告しない場合、接続が無期限にハングし、別種の異常を引き起こすことになる。新しい修正では CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS という環境変数が追加され、デフォルト値は10分で、idle 状態を待つ上限として機能する——この時間を超えると、バックグラウンドタスクがまだ完了を報告していなくても、SDK は強制的に先へ進み、無期限のハングを回避する。バックグラウンドタスクが実際に10分を超えて実行される必要があるシナリオ（長時間のデータ処理ジョブなど）では、この環境変数を使って上限を自分で延長できる。
この修正は CLI が自発的に session_state_changed メッセージを発行することに依存しているが、すべてのバージョンの CLI がこの仕組みを実装しているわけではない。この状態イベントを持たない古い CLI では、SDK は自動的に旧来の挙動パターン——最初の結果の到着をクローズのシグナルとする方式——にフォールバックする。つまり、このバグ修正の実際の効果は、デプロイ環境の CLI バージョンに左右される：CLI が古すぎる場合、SDK を更新しても、内部では依然として競合状態のリスクを抱えた旧ロジックが動いていることになる。
アプリケーションがバックグラウンドサブエージェントを多用している場合——複数のサブクエリを並行処理したり、サブエージェントにバックグラウンドで時間のかかる検証処理を実行させたりしている場合——この種の「Stream closed」エラーと誤って認識されるツール呼び出し拒否は、これまでチームによってランダムで再現困難な不安定性の問題として扱われていたかもしれない。根本原因が分かった今、この修正を含むバージョンに SDK をアップグレードし、デプロイ環境の CLI バージョンが session_state_changed をサポートしているかを別途確認して初めて、この修正の恩恵を実際に受けられる。バックグラウンドタスクが恒常的に10分を超えて実行される場合は、CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS を忘れずに設定しておくこと。そうしないと、デフォルトの10分の上限がタスク完了前に接続を強制的に先へ進めてしまう可能性がある。