Claude Code ガイド

Appearance

原文（日本語に翻訳） ​

ストリーミング途中でストールしたサブエージェントが、サイレントにハングし続ける代わりに、10分後に明確なエラーで失敗するようになりました。

原文（英語） ​

Subagents that stall mid-stream now fail with a clear error after 10 minutes instead of hanging silently

概要 ​

Claude Codeのサブエージェント（バックグラウンドで実行される補助エージェント）がストリーミング途中でストールした場合、これまでは無期限にハングし続けることがありました。今回の改善により、ストールしたサブエージェントは10分後に明確なエラーメッセージを出力して失敗するようになります。これにより、サブエージェントの状態が分からず待ち続けるという状況が解消され、問題を検出して再試行できます。

基本的な使い方 ​

特別な設定は不要です。サブエージェントが10分以上ストールすると、自動的にタイムアウトエラーが発生します。

bash
# 通常のサブエージェント実行
claude -p "バックグラウンドで大きなコードベースを分析してください"

# サブエージェントがストールした場合（10分後）：
# Error: Subagent stalled mid-stream and timed out after 10 minutes

実践例 ​

長時間タスクでのタイムアウト検知 ​

複雑なコード分析や大規模なファイル処理でサブエージェントがストールする場合があります。

bash
# バックグラウンドタスクを実行
claude --background "10,000ファイルのプロジェクト全体を分析してテスト不足箇所をリストアップ"

# 通常は完了するが、ネットワーク問題などでストールした場合
# → 10分後: "Subagent timed out" エラーが返ってくる
# → 再試行が可能

スクリプトでのエラーハンドリング ​

自動化スクリプトでサブエージェントを使用する際、タイムアウトエラーをキャッチして再試行できます。

bash
#!/bin/bash
# サブエージェントタイムアウトに対応したスクリプト例

MAX_RETRIES=3
attempt=0

while [ $attempt -lt $MAX_RETRIES ]; do
  result=$(claude -p "コードレビューを実行してください" 2>&1)
  exit_code=$?
  
  if [ $exit_code -eq 0 ]; then
    echo "成功: $result"
    break
  elif echo "$result" | grep -q "timed out"; then
    echo "タイムアウト。再試行 $((attempt+1))/$MAX_RETRIES"
    attempt=$((attempt+1))
    sleep 5
  else
    echo "エラー: $result"
    break
  fi
done

MCPツールとサブエージェントの組み合わせ ​

MCPツール呼び出し中にサブエージェントがストールするケースでも、タイムアウトにより検知できます。

# MCPツールを使ったサブエージェントタスク
/task MCP経由でデータベースを分析して最適化案を提案してください

# MCPサーバーが応答しなくなってサブエージェントがストールしても
# 10分後に明確なエラーが返るため、問題の特定が容易になる

注意点 ​

  • 10分のタイムアウト: ストリーミングが止まってから10分後にタイムアウトします。正常に実行中のサブエージェントは影響を受けません
  • 「mid-stream」のストール: この機能は応答の途中でストールした場合に対応します。開始前のタイムアウトは別のメカニズムが処理します
  • 再試行: タイムアウトエラーが発生した場合、タスクを再実行できます。ただし、ストールの原因（ネットワーク問題、MCPサーバー障害など）を特定してから再試行することを推奨します
  • 長時間の正常タスク: 10分以上かかる正常なタスクはタイムアウトしません。ストリーミング（データの継続的な送受信）が止まった場合のみタイムアウトが発生します

関連情報 ​