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

Agent Teamsのトラブルはほぼ5パターンに集約される

Agent Teamsで報告される不具合らしき挙動は、原因を辿ると5パターンにほぼ収まります。「チームメイトが見えない」「勝手にチームを組んでしまう」「権限プロンプトが多い」「途中で止まる」「tmuxが残る」の5つです。順番に切り分けていけば、原因不明のまま設定をあれこれ変えて時間を浪費せずに済みます。実装のバグではなく、設定や仕様の理解不足が原因のことがほとんどです。それぞれの切り分け方を確認していきます。

Agent Teamsは実験的機能という位置付けなので、ここで挙げる制約や挙動は今後のバージョンで変わる可能性があります。前提として、Agent Teamsは既定で無効です。settings.jsonのenvにCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: "1"を設定しない限り、Claudeはチームを組もうとしません。加えてチームメイトのスポーンには対話セッションが必要です。-pフラグを使う非対話モードやAgent SDK経由のセッションでは、この変数を有効にしていてもチームメイトは生成されず、名前を付けたサブエージェントは通常のSub-agentとして動きます。「チームが動かない」と感じたら、まずこの2点(環境変数と対話モードかどうか)を確認してください。

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

指示を出したのにチームメイトが1つも表示されない場合、確認する順番は次のとおりです。

1. 表示モードを確認する。in-processモード(既定)では、チームメイトはプロンプト入力欄の下にあるエージェントパネルに現れます。上下矢印キーで選択し、Enterで開けます。パネル自体が見当たらない場合、そもそもチームが組まれていない可能性が高いです。

2. アイドル行が隠れているだけの場合がある。パネル全体がアイドルになってから30秒経つと、アイドル中のチームメイトの行は非表示になります。停止したわけではなく、次のターンが来れば再表示される仕組みです。3人を超えてアイドルになると、超過分は「2 idle agents」のような1行にまとめられ、Enterで展開できます。名前を呼んでメッセージを送れば、隠れていた行はすぐ戻ってきます。

   この挙動はバージョンによって違います。v2.1.199以降は、パネル内の誰か1人でも稼働中ならアイドル行は隠れません。v2.1.181〜v2.1.198では、他のチームメイトが稼働中でも自分のターンが終われば30秒後に隠れていました。v2.1.181より前のバージョンではアイドル行の非表示自体がありません。手元の挙動が想定と違うと感じたら、まずclaude --versionでバージョンを確認してください。

3. タスクの複雑さを見直す。チームを組むかどうかはClaude自身が判断します。指示した作業がチームを組むほど複雑でないと判断されれば、チームメイトは生成されません。

4. split-paneモードを使っている場合はtmuxの有無を確認する。

which tmux

何も出力されなければtmuxが未インストールか、PATHが通っていません。iTerm2を使っているなら、it2 CLIのインストールと、iTerm2の環境設定でPython APIが有効になっているかも確認します。

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

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

元のサブエージェント動作に戻したい場合は、CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMSを0に設定します。

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

新しいセッションを開始する必要はありません。設定ファイルを保存すると、Claude Codeは実行中のセッションにenvの値を再適用し、次にサブエージェントへ名前を付けるタイミングで変数を読み直します。

注意点が1つあります。ユーザーのsettings.jsonで0に設定しても、より優先度の高い設定ソースで1が指定されていれば、そちらが勝つ仕様です。プロジェクト設定・ローカル設定・組織のmanaged settingsがこれに当たります。設定の優先順位を理解していないと、「offにしたのに直らない」という状況に陥ります。managed settingsで有効化されている場合は、組織の管理者への変更依頼が必要です。

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

チームメイトが求める権限確認は、すべてリードのセッションに集約されます。3〜5人のチームメイトが同時に別々のコマンドを実行すれば、リードの画面には次々と確認ダイアログが積み上がります。

対処は単純で、チームメイトをスポーンする前に、よく使う操作をpermissions設定でallowルールとして許可しておくことです。/permissionsコマンドでダイアログを開き、頻出するBashコマンドやファイル操作を事前に許可しておけば、チーム稼働中の割り込みは大きく減ります。ルールはdeny→ask→allowの順で評価されるため、広いdenyルールを先に置いていないかも合わせて確認してください。

具体的には、チームでよく走らせるコマンドをTool(specifier)の形で列挙しておきます。

allowにツール名単体(Read)を書くとそのツールの全使用が確認なしになり、Bash(npm test:*)のようにスコープを付ければ対象を絞れます。なおdenyでツール名単体を書いた場合だけは挙動が違い、そのツールがClaudeの選択肢から消えます。チームメイト全員に共通して許可したい操作は、個々のチームメイトではなくsettings.json側にまとめて書いておくと、スポーンのたびに設定し直す手間がなくなります。

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

チームメイトはエラーに遭遇すると、リカバリーせずにそのまま止まってしまうことがあります。エージェントパネルで対象のチームメイトを選びEnterを押す(split-paneモードならペインをクリックする)と、そこまでの出力を確認できます。

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

リード自身が早期に停止することもあります。まだ完了していないタスクがあるのにチーム全体が終わったと判断してしまうケースです。この場合は「まだ終わっていない、続けて」と伝えれば再開します。

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

Claude Codeのセッションが終了したあとも、split-paneモードで使ったtmuxセッションが残ることがあります。クリーンアップが完全に終わらなかった場合です。一覧を確認し、該当するセッションを手動で終了します。

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

セッション名にはチーム識別子が含まれるため、tmux lsの出力から使い終えたセッションを見分けられます。tmuxはmacOSでの動作が最も安定しており、iTerm2でsplit-paneモードを使うならtmux -CC経由での起動が公式に推奨されています。孤立が頻発するようなら、起動経路をこの形に揃えることも検討してください。

Hooksで再発を防ぐ

ここまでの対処はどれも起きてから直す方法ですが、いくつかの症状はHooksを使えば起きる前に防げます。

完了条件を満たさないタスクが完了扱いになってしまう問題は、TaskCompletedイベントで防げます。タスクが完了としてマークされようとしたタイミングで発火するイベントなので、完了条件を満たしていない完了リクエストを検知したら終了コード2でブロックし、何が足りないかをチームメイトに返す仕組みにできます。逆に、粒度の粗すぎるタスクが作られたときはTaskCreatedイベントで作成自体を差し戻す運用にできます。こうすれば、チームサイズとタスク粒度で挙げた基準を、チェックリストではなく機械的なゲートとして強制できます。チームメイトが早期に停止しがちな作業には、TeammateIdleイベントで完了品質を確認し、基準未達ならアイドル化を止めてフィードバックを返す構成が効果的です。

これらはsettings.jsonのhooksにTeammateIdle・TaskCreated・TaskCompletedを追加するだけで有効になり、チームメイト全員に同じ基準を適用できます。個々のチームメイトへの指示に品質基準を書き込むより、Hooksで一元管理するほうが、人数が増えても基準がぶれません。

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

ここまでの症状のうち、いくつかは仕様上の制約であって修正待ちのバグではありません。混同すると余計な時間を使うため、区別しておきます。

これらはCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMSの設定やtmuxの有無とは無関係です。Sub-agentsの設計とも異なる、Agent Teams固有の実験的な制約だと理解しておいてください。

まとめ

Agent Teamsの不調は、環境変数と対話モードの確認、アイドル行の非表示、設定の優先順位、権限の事前許可のいずれかで説明がつくことがほとんどです。tmuxの孤立セッションやセッション再開後の消失のように、コマンド一発で直せるものと、仕様として割り切るしかないものを区別しておくと、無駄な調査を避けられます。