CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MSとは — 終了待機の設定

CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MSでできること

CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MSは、Agent Teamの後片付けを非対話セッションが終了時に待つ時間を上書きする環境変数です。単位はミリ秒です。Claude Code v2.1.206(2026年7月9日公開)以降が対象で、それより前のバージョンでは設定しても効きません。

対象は非対話セッション(claude -pなど)です。

Agent Teams自体は既定で無効な実験的機能で、CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1を設定しないとチームは作られません。teammateを使わない通常のsubagent実行やworkflow実行は、この変数の対象外です。

非対話セッションでチームは本当に残るのか

env-varsのページはこの変数を「非対話セッションがチームの終了を待つ時間」と説明しています。一方でAgent Teamsのページには、-pフラグの非対話モードでClaudeがteammateを起動しないと書かれています。Agent SDKセッションも同じ扱いで、Claudeが名指ししたsubagentは通常のsubagentとして動きます。

-p実行がteammateを作らないなら、終了処理がteam側の後片付けまで進む構成でなければ、値を変えても挙動は変わらないと考えられます。

使い方

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

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
export CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS="30000"
claude --version

v2.1.289でclaude --versionを実行すると、2.1.289 (Claude Code)と表示されます。v2.1.206以降であれば、この変数が読まれる条件を満たします。

常設したい場合は、settings.jsonのenvキーに書きます。

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

シェルのexportとenvブロックの両方に同じ変数があるときは、ほとんどのセッションでenvの値が優先されます。Claude Codeがenvの各エントリをプロセス環境に書き込み、シェルから引き継いだ値を置き換えるためです。シェルのexportを残したい場合は、env側の値を""にするとexportを打ち消せます。

例外は、Claude Desktopアプリやself-hostedの環境ランナーがセッションを起動する場合です。起動側が組み立てた環境変数が優先され、設定ファイルのenvは、すでに設定済みの変数については無視されます。

この変数に対応する専用の設定キーはなく、設定できるのは環境変数(シェルのexportまたはenvブロック)だけです。

どの設定ファイルに書くか

envを書けるファイルは4種類あり、適用範囲が違います。

プロジェクト設定とローカル設定では、CLAUDE_CONFIG_DIRやOpenTelemetryのエクスポーター関連の変数はenvから設定できません。CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MSはその一覧に載っていないため、.claude/settings.jsonにも書けます。

共有ファイルには注意点が1つあります。複数のリポジトリをまとめて開くセッションは、各リポジトリの.claude/settings.jsonからenabledPluginsとextraKnownMarketplacesしか読みません。envは読まれないので、リポジトリ単体で起動したときと同じ値になるとは限りません。

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

Agent Teamsは、Claude Codeのセッションが複数のteammateを立ち上げて並列に作業させる仕組みです。セッションが終了するとき、Claude Codeはこのチームの後片付け(teardown)を行います。

リードは各teammateにshutdownリクエストを送り、teammateは承認して正常終了するか、理由を添えて拒否できます。チームの設定ディレクトリはセッション終了時に自動で削除されるので、別途のクリーンアップ手順は要りません。消えるのは設定ディレクトリだけです。タスクリストのディレクトリはローカルに残るので、再開したセッションでもタスクを引き継げます。残す期間はcleanupPeriodDaysの設定に従います。

Agent Teamsのページは制限事項として、teammateが進行中のリクエストやツール呼び出しを完了してからシャットダウンするため、終了に時間がかかる場合があると挙げています。一方、この変数が決めるのは、終了時にチームの後片付けを待つ時間の上限です。

値の設計 — 範囲外の挙動

範囲外の値は静かに既定へ戻るため、設定ミスに気づきにくくなります。"500"は下限未満、"120000"は上限超過なので、どちらも10000msとして扱われます。"60000"は上限ちょうどで、そのまま適用されます。

数値以外の文字列を入れたときの扱いは、この変数の説明に書かれていません。同じ非対話向けの待機系でも、CLAUDE_CODE_WORKER_CHECKIN_SCHEDULEは「数字のみ。それ以外の値や綴りは未設定として読まれる」と明記しています。これは別の変数の仕様なので、この変数にそのまま当てはめない方が安全です。

意図した値が効いているかを知りたいときは、範囲内の値を入れて実際にAgent Teamsを動かし、終了までの時間を見ます。

似た名前の待機系環境変数との違い

名前が似た環境変数が複数あり、待つ対象と下限バージョンが違います。

CLAUDE_CODE_WORKER_CHECKIN_SCHEDULEの値は、1〜86400の整数の秒数をカンマで区切って並べます。600,1800,3600のように書くと、各値が次のリマインダーまでの待ち時間になり、最後の値が繰り返されます。以前のCLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDSはv2.1.283で削除されており、古いスクリプトに残っていても効きません。

-pの終了時には、待ち方の違う処理がほかにもあります。バックグラウンドのBashタスク(開発サーバーやwatchビルドなど)は、最終結果の返却とstdinの終了から約5秒後に終了されます。この5秒は上の変数では変えられず、CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MSの対象でもありません。

Monitorによる監視は、タイムアウトするか10分の上限に達するまで待たれます。監視は開始から既定で5分でタイムアウトします。

同じCIジョブでAgent TeamsとMCPサーバーの両方を使うなら、終了が遅い原因を切り分けるときに、どの待機が関わるかを先に特定します。

値を変えるかどうかの切り分け

終了が長引く症状別に、疑う先を並べ替えます。

引き上げても、teardownに10秒以上かかる原因が消えるわけではありません。teardownが時間内に終わらなかったときの挙動は、環境変数の行にもAgent Teamsのページにも書かれていません。寄せすぎる前に、実際の終了までの時間を測っておくと判断を誤りにくくなります。

tmuxのペインが残るなど、終了しない症状があるなら、先にAgent Teamsのトラブルシューティングを見ます。この変数は待つ時間の上限を変えるだけで、teardownが遅い原因そのものは直しません。

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

Agent Teams自体の有効化や、使うモデルを決める変数もあります。

CLAUDE_CODE_SUBAGENT_MODELは、エージェント定義のmodelフィールドや、Claudeが起動時に渡すモデルより優先順位が低い既定値です。上書きしたいときだけ_FORCEを使います。v2.1.251より前は、この変数が定義側の指定まで上書きしていました。

サブエージェントの無応答を検知するCLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MSも、似た系統の変数です。既定は600000ms(10分)で、teardownではなく実行中のストリーミングイベントの間隔を見ます。進捗がないままこの時間が過ぎると、Claude Codeはsubagentを中断し、止まったことを親に報告します。

まとめ

この変数は、Agent Teamsを使う構成で非対話セッションが終わるときの待機に関わります。既定の10000msで困っていなければ、変える必要はありません。

値を変えるなら、.claude/settings.jsonのenvに1行足すだけで済み、戻すのもその1行です。待っているのがチームの後片付けか、バックグラウンド作業かを見分けてから、範囲内の値を選んでください。