CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MSとは — 終了待機の設定

CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MSでできること

CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MSは、非対話セッションが終了時にAgent Teamの後片付けを待つ時間をミリ秒単位で上書きする環境変数です。既定値は10000(10秒)で、1000〜60000の範囲を受け付けます。範囲外の値を入れると無視され、既定の10秒に戻ります。Claude Code v2.1.206以降(2026年7月9日公開)が対象です。

この変数が効くのは「非対話セッション」に限られます。claude -p、Agent SDK経由の呼び出し、CIパイプラインでの実行がこれに当たります。対話的なターミナルセッションでAgent Teamsを終了するときの挙動には関係しません。他の非対話セッション向けの環境変数(CLAUDE_CODE_MCP_STARTUP_WAIT_MSやCLAUDE_CODE_PRINT_BG_WAIT_CEILING_MSなど)も同じ非対話モードを対象にしており、対話セッションの終了処理には影響しません。

ただし、Agent Teamsの公式ドキュメントはteammateの起動自体が対話セッションを前提としており、-pフラグによる非対話モード(Agent SDKセッションを含む)ではClaudeがteammateを起動しないと明記しています。非対話セッションでteardown対象のチームがどのような経路で存在しうるかは、公式ドキュメントからは確認できていません。

Agent Teams自体は既定で無効な実験的機能です。CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1を設定してteammateを起動していない環境では、この待機時間の設定も意味を持ちません。teammateを1つも使っていない通常のsubagent実行やworkflow実行は、この変数の対象外です。

使い方

シェルで一時的に設定する場合は、claudeを起動する前にexportします。

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
export CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS="30000"
claude -p "このリポジトリの依存関係を更新して"

常設したい場合は、settings.jsonのenvキーに書きます。ユーザー全体に効かせるなら~/.claude/settings.json、プロジェクトのメンバー全員に効かせるならプロジェクト直下の.claude/settings.jsonです。

{
  "env": {
    "CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS": "30000"
  }
}

シェルとsettings.jsonの両方で値を設定した場合、settings.json側の値が優先されます。シェルからexportした値は、Claude Codeがプロセス環境に書き込む際に上書きされます。管理者が配布するmanaged settingsがある場合は、そちらがユーザー設定・プロジェクト設定より優先されます。

なお、この変数に対応する専用の設定キーはsettings referenceにありません。設定できるのは環境変数(shell export、またはenvブロック経由)だけです。

設定ファイルには4種類あり、どのファイルに書くかで適用範囲が変わります。

CLAUDE_CONFIG_DIRやOpenTelemetryのエクスポーター関連の変数は、プロジェクト設定・ローカル設定からは設定できない例外として明記されています。CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MSはこの除外リストには含まれていないため、プロジェクトの.claude/settings.jsonに書いてチームで共有する運用も可能です。

Agent Teamsの終了待機はなぜ必要か

Agent Teamsは、Claude Codeのセッションが複数のteammateを立ち上げて並列に作業させる仕組みです。teammateは表示モード(teammateMode)によってメインのターミナルペインの中、または分割ペインに表示されます。

セッションが終了するとき、Claude Codeはこのチームの後片付け(teardown)を行います。公式ドキュメントによると、リードは各teammateへshutdownリクエストを送り、teammateはそれを承認して正常終了するか、理由を添えて拒否できます。チームの共有ディレクトリ(チーム設定ディレクトリ)はセッション終了時に自動で削除され、別途のクリーンアップ手順は不要です。公式ドキュメントは、teammateが進行中のリクエストやツール呼び出しを完了してからシャットダウンするため、shutdownの完了に時間がかかる場合があるとも説明しています。CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MSは、このteardownが終わるのをセッション終了処理がどれだけ待つかを決めます。

Claude Codeには、非対話セッション終了時の待機を扱う環境変数がほかにもあります。たとえばCLAUDE_CODE_PRINT_BG_WAIT_CEILING_MSは、-pフラグでの最終ターン後にバックグラウンドのsubagentやworkflowの結果を待つ上限で、既定は600000(10分)です。両者は待つ対象が異なります。CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MSはまだ動いているバックグラウンド作業の完了を待ち、CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MSはAgent Teamの後片付け処理そのものの完了を待ちます。

値の設計 — 既定値・範囲・範囲外の挙動

公式ドキュメントに明記されている仕様は、既定値10000ms(10秒)、許容範囲1000〜60000ms(1〜60秒)、範囲外の値は無視され既定の10000msが適用される、の3点です。範囲外というのは、たとえば500(下限未満)や120000(上限超過)を指定した場合で、エラーにはならず静かに既定値へフォールバックします。設定ミスに気づきにくい挙動なので、意図した値が効いているかは実際にAgent Teamsを動かして確認するのが確実です。

必須のClaude Codeバージョンはv2.1.206以降です。これより前のバージョンでは、この環境変数を設定しても無視されます。バージョンはclaude --versionで確認できます。

範囲外の値を入れたときにどう扱われるかを、具体的な入力例で確認します。

数値以外の文字列を入れた場合の扱いは、CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MSのページには明記されていません。参考までに、CLAUDE_AUTO_BACKGROUND_TASKS有効時のバックグラウンドsubagentへのリマインダー間隔を設定するCLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDSでは「整数以外の値やつづりの誤りは未設定として読まれる」と明記されていますが、これは別の環境変数の仕様です。数値以外の値の扱いは公式に記載がありません。

似た名前のタイムアウト系環境変数との違い

Claude Codeには、名前が似たタイムアウト系の環境変数が複数あります。待つ対象や適用場面はそれぞれ異なるため、次の表で違いを示します。

CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MSが対象にしているのは、あくまでAgent Teamの後片付けというセッション終了処理の一部です。バックグラウンドタスクの完了待ちや、MCPサーバーの起動待ちとは別の役割を持ちます。同じCIジョブでAgent TeamsとMCPサーバーの両方を使っている場合、遅延の原因を切り分けるにはどちらの変数が関係する処理かを先に特定する必要があります。

CI・非対話セッションで設定するときの考え方

この変数の値を検討する場面としては、CIパイプラインやAgent SDK経由でClaude Codeを-p実行し、Agent Teamsを有効にしている構成が挙げられます。ただし「できること」で触れたとおり、非対話モードでteammateが実際に起動する経路は公式ドキュメントから確認できていません。teardown待機が発生する具体的な構成が確認できていない以上、値を積極的に変える理由も現時点では明確ではありません。対話的にターミナルで使っているだけなら、この変数は関係しません。

teammateが進行中のリクエストやツール呼び出しを終えるまでshutdownが長引いていると疑われる場合は、上限の60000ms(60秒)まで引き上げる余地があります。ただし、teardownに10秒以上かかる原因そのものが解消されるわけではない点には注意が必要です。逆に、パイプラインの実行時間を切り詰めたい場合に下限の1000ms(1秒)へ寄せる選択もできますが、teardownが完了する前にセッションが終了処理を打ち切る可能性が高くなります。どちらの方向に振るにせよ、公式ドキュメントはteardownが打ち切られた場合の具体的な影響までは説明していません。

Agent Teamsが期待どおりに終了しない、tmuxのペインが残るといった症状に心当たりがある場合は、Agent Teamsのトラブルシューティングを先に確認したうえで、この変数の値を疑うのが順序として妥当です。この変数はteardownを待つ時間の上限を変えるだけで、teardownが遅い・失敗する原因そのものを直すものではありません。

設定を検討する際は、実際の構成でAgent Teamsが動いていることをclaude --versionと実行ログで確認したうえで判断してください。

Agent Teams関連のほかの環境変数

CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS以外にも、Agent Teams自体の有効化や挙動を左右する環境変数があります。

これらはteardownの待機時間ではなく、Agent Teamsをどう起動しどのモデルで動かすかを決める変数です。CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MSと組み合わせて設定することはあっても、役割は独立しています。似た系統の環境変数として、サブエージェントの無応答を検知するCLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MSもあります。こちらはteardownではなく、実行中のストリーミングイベントの間隔を見て強制終了するかどうかを判定します。

まとめ

CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MSは、非対話セッションがAgent Teamのteardownをどれだけ待つかを1000〜60000msの範囲で調整する環境変数です。既定は10000ms、範囲外の値は無視されて既定に戻ります。Claude Code v2.1.206以降が必要です。

設定できる場所はシェルのexport、ユーザー・プロジェクト・ローカルの各settings.json、managed settingsのいずれかで、優先順位は前述のとおりです。

CIでAgent Teamsを使い始めたタイミングで、teardown周りの挙動に違和感があれば設定を見直す候補の一つになります。値を変えるだけなら.claude/settings.jsonに1行足すだけで済み、ロールバックもその1行を戻すだけです。まずは既定の10000msのまま運用し、実際にteardownの遅延を観測してから範囲内で調整するのが手戻りの少ない進め方です。