Claude Code SendMessageで複数マシンのエージェントを連携する

同じSendMessageというツールが、v2.1.77では一時停止したサブエージェントを起こし直すためだけの内線電話でした。v2.1.224では、別マシンで動く別セッションへ直接メッセージを送る手段に変わっています。同一セッション内の基本挙動から、v2.1.224で加わったクロスマシン連携の条件、そして公式ドキュメントにまだ書かれていない部分までをまとめます。

Claude CodeのSendMessageとは

SendMessageは、Claude Codeのエージェントが別のエージェントセッションへメッセージを送るビルトインツールです。呼び出すのはユーザーではなく実行中のClaude自身で、宛先にはエージェントIDか名前を指定します。用途は大きく2つ、停止・完了したサブエージェントを再開させる呼び出しと、Agent Teamsのチームメイトへ送る直接メッセージです。

SendMessage自体はAgent Teamsを有効にしなくても使えます。Agent Teamsが必要になるのは、shutdown_requestやplan_approval_responseのような構造化されたチーム間プロトコルメッセージを送るときだけです。Agent Teamsは公式が実験的機能(experimental)と位置付ける仕組みで、既定では無効です。試す場合はCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS環境変数を1に設定します。シェル環境のほか、settings.jsonのenvキーに書いても有効化できます。公式は既知の制限を複数挙げています。運用に効きやすいのは、セッションを/resumeや/rewindで再開してもインプロセスのチームメイトは復元されないこと、タスクの完了ステータスが実際の進捗より遅れて表示されることがあること、シャットダウンにはチームメイトが処理中のリクエストを終えるまでの時間がかかることです。このほか、インプロセスのチームメイトからバックグラウンドのサブエージェントを起動できない、といった制限も公式の一覧に含まれています。

安全境界も1つ組み込まれています。他のエージェントから届いたメッセージは、ユーザーの承認や同意として扱われません。保留中の権限確認をエージェント間のメッセージで通過させることはできず、CLAUDE.mdや権限設定を書き換える権限もない設計です。承認できるのは権限システムそのものと、ユーザー自身の発言だけです。

同一セッション内でSendMessageはどう機能するか

サブエージェントが完了すると、Claudeはそのエージェントの一意なIDを受け取ります。組み込みのExploreとPlanは1回限りの実行で、エージェントIDを返しません。継続作業をさせたい場合の選択肢は、general-purposeか独自定義のサブエージェントです。

再開の実体はSendMessage({to: agentId})です。完了済みのサブエージェントにメッセージが届くと、新しいAgent呼び出しなしにバックグラウンドで自動的に再開します。例外は1つだけで、ユーザー自身が/tasksのキー操作かSDKのstop_taskで止めたサブエージェントです。この場合SendMessageは拒否を返し、再開にはサブエージェントパネルでその会話に直接書き込む操作が必要です。

名前の解決にも安全策が入っています。v2.1.199以降、SendMessageは名前が会話内で以前と同じエージェントを指しているかを確認します。再起動したバックグラウンドエージェントが同じ名前を使い回していても、誤送信は起きません。Claude Codeは送信を拒否し、その名前が現在どのエージェントを指しているかをエラーで伝えます。確実に届けたいなら、名前でなくスポーン時に受け取ったエージェントIDを使うのが安全です。

サブエージェントの初期コンテキストには、v2.1.206以降「兄弟エージェント一覧」というシステムリマインダーも含まれています。mainと、セッション内で名前を持つ他の全エージェントを列挙したもので、SendMessageのtoに指定できる値の一覧として機能します。表示される条件は2つ、そのサブエージェントのtoolsにSendMessageが含まれていること、そして他に名前を持つエージェントが1つ以上いることです。起動時点のスナップショットなので、あとから名前を付けたエージェントは載りません。

v2.1.224でSendMessageの範囲はどこまで広がったか

v2.1.224でSendMessageは同一マシンの縛りを外れました。ListAgentsという発見用ツールが新設され、macOSとLinux上で動くClaude Codeセッション同士であれば、別マシンにいても互いを見つけて直接メッセージを送れます。同じリリースでcrossSessionInboundとdialogExpiryという2つの設定も加わりました。

挙動は送信先の権限モードで分かれます。許可プロンプトを一切出さないbypassPermissionsで動くセッションへの着信は、crossSessionInboundによって承認待ちで保留される仕組みです。それ以外のセッションでは自動配送になります。承認待ちのダイアログには期限があり、設定リファレンスはdialogExpiryを「Remote Controlなど接続先のクライアントへ転送するダイアログの期限」と説明しています。既定は5分、60s・5m・10m・never(無効化)のいずれかを指定可能です。期限内に応答がなければ、Claude Codeはダイアログを取り消し、何もしない側の既定動作を続けます。CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS環境変数でも同じ値を上書きでき、remote clientを介さないローカル専用のダイアログはこの期限の対象外です。

もう1つ、v2.1.222で入っていた安全策も適用されます。auto modeで動くセッションがSendMessageで他のエージェントセッションへ送るメッセージは、配送前に権限分類器の評価を受ける仕組みです。plan modeでauto分類器がコマンドを審査している間も同様で、クロスマシンの送信もこの分類器の対象になります。

SendMessageはどう進化してきたか

複数マシンでエージェントを連携させるには何を揃えればよいか

必要なのはバージョン・OS・権限モードの3点です。まずバージョン、クロスマシン連携が動くのはv2.1.224以降で、送受信の両方のマシンが同じ条件を満たしている必要があります。全マシンを更新してから確認しましょう。

claude update
claude --version

対応OSはmacOSとLinuxです。Windowsでの対応は変更履歴に記載がなく、確認できていません。

次に権限モードです。相手のセッションがbypassPermissionsで動いているかどうかで挙動が変わります。動いている場合はcrossSessionInboundの承認待ちを挟み、そうでなければ自動配送されるという分岐です。auto modeのセッションへ送る場合は、権限分類器のレビューが挟まることも踏まえておきましょう。

タイムアウトを調整したいときはdialogExpiry設定の出番です。既定の5分では短いと感じる運用なら10m、逆に速く諦めさせたい運用なら60sに変更できます。

どんな場面で効果が出るか

効き方は運用形態で分かれます。複数マシンでエージェントを並行運用している場合と、1台のローカルCLIで完結している場合とでは、恩恵の大きさがまるで違います。

SendMessageと紛らわしい機能の違い

似た響きの機能がいくつかあり、つなぐ対象が違います。混同すると、設定を探す場所を間違えてしまいます。

サブエージェントは結果をメインエージェントへ返すだけの一方通行です。一方、Agent TeamsのチームメイトはSendMessageで互いに直接連絡を取り合い、共有のタスク一覧を見ながら自分で作業を拾います。トークン消費はサブエージェントより高くつく代わりに、調査結果を持ち寄って議論させたいときに向く構成といえます。

Agent Teamsとagent viewは、どちらも同一マシンの中で完結する機能です。人間がスマホから覗きに行きたいならRemote Control、エージェント同士が勝手に連絡を取り合ってほしいならSendMessageのクロスセッションという切り分けになります。Claude Codeのサブエージェントを土台にした設計なら、まず同一セッション内の再開から使い始めるのが分かりやすい入り口です。

よくあるつまずき

Windows環境での対応は確認できていません。対応が明記されているのはmacOSとLinuxだけで、変更履歴の記述からはWindowsでの動作可否を判断できないので注意が必要です。

名前を使い回すと誤送信になりかけていた時期もありました。v2.1.199より前は、再起動したエージェントが同じ名前を使い回すと別のエージェントに送ってしまう恐れがありました。いまは検出して拒否される仕組みですが、確実に狙った相手に届けたいなら名前ではなくエージェントIDを使うほうが確実です。

bypassPermissionsのセッションへの送信は、承認待ちのまま気づかれないことがあります。設定リファレンスがdialogExpiryの対象とするのはRemote Controlなど接続先クライアントへ転送するダイアログで、crossSessionInboundの保留メッセージに同じ期限が適用されるかどうかは確認できていません。承認が長く放置されれば、送信側は結局届かなかったことに気づけないままになります。

チームメイトからのメッセージを、うっかり承認だと誤解しないよう注意が必要です。エージェント間のメッセージは保留中の権限確認を素通りさせず、承認できるのはあくまでユーザー自身の発言だけです。

長時間セッションでエージェント間のやり取りが増えると、トークン消費も無視できません。v2.1.212では、メッセージ本文が再生された履歴とツール結果へ二重に展開されない変更が入り、エージェント間メッセージング自体のトークン消費は抑えられています。クロスマシンでのやり取りが増える運用ほど、この最適化の恩恵は大きくなるでしょう。

よくある質問

dialogExpiryはSendMessage以外にも影響しますか

影響します。設定リファレンスはdialogExpiryを、Remote ControlやSDKホストなど接続先のクライアントへ転送するダイアログ全般の期限だと説明しています。例に挙がっているのは、安全性の理由で拒否したあとのモデル選択プロンプトで、crossSessionInboundの承認待ちに限った設定ではありません。なお通常の権限プロンプトとAskUserQuestionは別の仕組みで動くため、この期限の対象外です。

別マシンのサブエージェントを直接再開できますか

確認できていません。変更履歴が書いているのは「セッション同士がListAgentsで互いを見つけてメッセージを送れる」という粒度です。セッション配下のサブエージェントを別マシンから直接指定して再開できるかどうかには、まだ触れられていません。

別々のclaude.aiアカウントのマシン間でも使えますか

公式ドキュメントに明記がなく、断定はできません。同じく複数デバイスをまたぐRemote Controlは、同一アカウント・同一組織へのログインが前提と明記されています。SendMessageのクロスセッション機能については、同様の記述が見当たらないのが実情です。

料金プランによる制限はありますか

明記されていません。Remote Controlや自社マシンでのセルフホスト環境にはプラン別の可否が書かれているのに対し、SendMessageのクロスセッション機能にはプラン条件の記載自体が見当たりません。

まとめ

SendMessageは、同一セッション内で止まったサブエージェントを起こす内線電話として始まりました。Agent Teamsのチームメイト間連絡を経て、v2.1.224では別マシンのセッション同士をつなぐ手段になっています。使うための条件は、全マシンをv2.1.224以降にすること、macOSかLinuxであること、そして送信先の権限モードに応じた承認待ちの仕組みを理解しておくことです。

複数マシンでエージェントを並行運用しているチームには明確な恩恵があります。一方でListAgentsの発見方法やアカウントの前提条件など、ドキュメントにまだ書かれていない部分も残ったままです。Claude Code v2.1.224ではこの機能とあわせてサブエージェントの総発行数上限も撤廃されており、オーケストレーター設計のような多エージェント運用を前提にした変更が続けて入った回でした。