Agent Teamsが動かないときの対処法 — 出てこない・早期に止まる・tmuxが残る

Agent Teamsのトラブルは5つの症状に分かれる

「チームメイトが見えない」「勝手にチームが組まれる」「権限プロンプトが多い」「途中で止まる」「tmuxが残る」。Agent Teamsで困る場面は、この5つの症状で切り分けられます。設定で直るものと、設定では直らない制約があります。

前提として、Agent Teamsは実験的機能で、既定では無効です。settings.jsonのenvにCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: "1"を設定しない限り、Claudeはチームを組みません。チームメイトのスポーンには対話セッションも要ります。-pフラグの非対話モードやAgent SDK経由では、この変数を有効にしていてもチームメイトは生成されません。名前を付けたサブエージェントは通常のSub-agentとして動きます。

「チームが動かない」と感じたら、まず環境変数と対話モードかどうかを見てください。

チームメイトが出てこない

指示を出してもチームメイトが1人も表示されないときは、次の順で確かめます。

tmuxの有無は次のコマンドで分かります。何も出力されなければ、未インストールかPATH未設定です。

which tmux

iTerm2のPython APIは、iTerm2 → Settings → General → Magic → Enable Python APIでオンにします。

表示モードで原因が変わる

teammateModeはsettings.jsonに書く設定で、既定は"in-process"です。split-paneを使いたいときだけ値を変えます。

claude --teammate-mode autoのように起動時のフラグでも指定できますが、このフラグはclaude --helpに出ません。v2.1.287のclaude --helpにはteammateを含む行がありません。ヘルプに無いからといって、フラグが無効なわけではありません。

アイドル行の非表示はバージョンで違う

3人を超えてアイドルのときは、超過分が「2 idle agents」のような1行にまとまります。Enterで展開し、Escで畳みます。

手元の挙動が想定と違うときは、claude --versionでバージョンを確認してください。

Claudeがサブエージェントのつもりで勝手にチームを組む

Agent Teamsを有効にすると、通常のサブエージェント委任にも影響が出ます。Claudeは委任先のサブエージェントに自分で名前を付けることがあり、Agent Teamsが有効な間は、名前を付けられたサブエージェントがチームメイトとして起動します。頼んだ覚えのないチームが組まれる原因は、これです。

元の動作に戻すには、CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMSを0にします。

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "0"
  }
}

新しいセッションは要りません。設定ファイルを保存すると、Claude Codeは実行中のセッションにenvの値を再適用し、サブエージェントに名前を付けるたびに変数を読み直します。ユーザーのsettings.jsonの0は、シェルでexportした値より優先されます。

0にしても直らないときは、より優先度の高い設定ソースが1を指定しています。プロジェクト設定、ローカル設定、--settingsで渡した設定は、ユーザー設定の後に適用されます。managed settingsは最後に適用されるので、組織が有効にしている場合は管理者に変更を頼むことになります。

0にしても、Claudeがサブエージェントに名前を付けること自体は続きます。名前はSendMessageの宛先として使えます。

権限プロンプトが多すぎる

チームメイトの権限確認は、すべてリードのセッションに集まります。同時に動く人数が多いほど、リードへの確認が増えます。

チームメイトは、スポーン時点のリードの権限モードで始まります。引き継がれないのはdontAskモードだけです。リードを--dangerously-skip-permissionsで起動していれば、チームメイトも同じになります。スポーン時にチームメイトごとの権限モードは指定できません。スポーン後なら、個別に変更できます。

対処は、チームメイトをスポーンする前に、よく使う操作をpermissions設定のallowルールにしておくことです。/permissionsでダイアログを開き、頻出するBashコマンドやファイル操作を許可します。

末尾のワイルドカードは、Bash(npm test:*)とBash(npm test *)のどちらでも同じ意味です。権限ダイアログで「Yes, and don't ask again」を選ぶと、スペース区切りの形で保存されます。コロン付きの形が認識されるのはパターンの末尾だけで、Bash(git:* push)のように途中に置くとコロンは文字として扱われます。

評価順はdeny、ask、allowで、最初に当たったものが結果を決めます。広いdenyを置くと、より細かいallowを足しても通りません。同じ理由で、askルールに当たる操作は、細かいallowがあってもプロンプトが出ます。denyにツール名だけを書くと、そのツールはClaudeの選択肢から消えます。Bash(rm *)のようにパターンを付けた場合は、ツール自体は残って該当の呼び出しだけが止まります。

チーム全員に共通する許可は、個別の指示ではなくsettings.jsonにまとめます。

チームメイトが早期に停止する

チームメイトは、エラーに遭遇するとリカバリーせずに止まることがあります。エージェントパネルで該当のチームメイトを選んでEnterを押すと、そこまでの出力を読めます。split-paneならペインをクリックします。

対処は2つあります。追加の指示を直接送るか、代わりのチームメイトをスポーンして引き継がせます。API呼び出しの失敗でリトライ待ちのin-processチームメイトは、リードか他のチームメイトからメッセージが届くと、リトライ遅延を待たずに再試行します。

リード自身が早く止まることもあります。未完了のタスクが残っているのにチーム全体が終わったと判断するケースです。続けるよう伝えれば再開します。

tmuxセッションが孤立して残る

Claude Codeのセッションが終わった後に、split-paneで使ったtmuxセッションが残ることがあります。クリーンアップが最後まで終わらなかった場合です。一覧を見て、チームが作ったものを手動で終了します。

tmux ls
tmux kill-session -t <session-name>

非対話セッションが終了時にチームの後片付けを待つ時間は、CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MSで変えられます。範囲は1000〜60000ミリ秒で、範囲外の値は無視されて既定の10000が使われます。v2.1.206以降の変数です。

tmuxにはOSによって制約があり、macOSでの動作が最も安定しています。iTerm2でsplit-paneを使うなら、tmux -CCで起動するのが推奨の入口です。

なお、チームの設定ディレクトリはセッション終了時に削除されますが、タスクリストのディレクトリはローカルに残ります。再開したセッションがタスクを引き継げるようにするためで、保持期間はcleanupPeriodDaysで決まります。tmuxの孤立とは別の話で、ディスクに残るファイルを見ても故障とは限りません。

Hooksで再発を防ぐ

ここまでは起きてから直す方法でした。Hooksを使うと、一部の症状は起きる前に止められます。

粒度の粗いタスクはTaskCreatedで差し戻せます。チームサイズとタスク粒度の基準を、チェックリストではなくゲートとして強制できます。完了条件を満たさない完了はTaskCompletedで止められます。

注意点が2つあります。3つのイベントはどれもmatcherに対応せず、毎回発火します。TaskCreatedはTaskCreateツールを持たないセッションでは発火しません。もう1つは、JSONで{"continue": false}を返す場合の違いです。TeammateIdleとTaskCompletedではチームメイトを完全に止める指定になりますが、TaskCompletedはTaskUpdateツールが引き金のときこれを無視します。TaskCreatedではcontinue: falseは無視され、decision: "block"か終了コード2で取り消します。

設定はsettings.jsonのhooksに書きます。チームメイト全員に同じ基準が適用されます。

不具合ではなく仕様の制約であるケース

次の症状は、設定や再起動では解消しない既知の制約です。

同じセッションの中で、止まっているin-processチームメイトにメッセージを送ると、Claude Codeは会話を復元して再開させます。

これらはCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMSやtmuxの有無とは無関係です。Sub-agentsの設計とも異なる、Agent Teams固有の制約です。

まとめ

設定で直るのは表示モード・環境変数・権限の3系統です。最後の表に当たる症状は設定では解消しないので、チームを作り直す前提で運用を組みます。