Agent Teamsでinboxへの書き込みに失敗する原因と対処
Agent Teamsで「Failed to write to a teammate's inbox」が出て、teammateにメッセージが届かないときの原因と切り分け。ディスク容量、書き込み権限、ロック競合の順に確かめます。
Agent Teamsで Failed to write to researcher's inbox — nothing was sent というエラーが出たら、受信側のteammateには何も届いていません。送信先のメールボックスファイルに書き込めなかったことが原因で、疑う場所はディスク容量、ディレクトリの書き込み権限、ロックの競合の3つです。
このエラーは、端末のバナーには出ません。メッセージを送ったエージェントのツール結果に載るだけなので、画面を眺めているだけでは見落とします。
このエラーが示すこと
Agent Teamsでは、リードとteammateのやり取りがメールボックスを介して行われます。メールボックスの実体は、~/.claude/teams/{team-name}/inboxes/{agent-name}.json というJSONファイルです。エージェントがメッセージを送るとは、相手のファイルに1件追記することを指します。
その追記に失敗すると、Claude Codeは「送信済み」とは扱わず、送信側にエラーを返します。エラー文は、再試行するかリードに連絡するよう促す内容です。
Failed to write to researcher's inbox — nothing was sent. Try again, or message the lead.挙動は版によって違います。v2.1.224より前は、書き込みに失敗しても送信済みとして報告されていました。送った側は届いたつもりで待ち続け、受け取る側は何も知らない状態になります。古い版でteammateが返事をしない事象に当たったら、まず更新を疑う価値があります。
書き込みが失敗する3つの原因
Claude Codeがファイルを作成または更新できないと、書き込みは失敗します。例として挙げられているのは次の3つです。
inboxの書き込みが失敗する原因
ディスクが満杯
ホームディレクトリのあるボリュームに空きがなく、ファイルを作れない、または更新できない状態です。
ディレクトリに書き込めない
~/.claude/teamsかその配下のファイルが、実行ユーザーで書き込めない状態です。ロックを長く握られている
別のエージェントがinboxのロックを長く保持していて、待ちきれずに失敗する状態です。
3つのうち、ロックの競合は一時的です。再送すれば通ります。ディスクと権限は環境の問題なので、再送しても同じエラーが繰り返されます。したがって、1回目の再送で通ったかどうかが、そのまま原因の切り分けになります。
切り分けの手順
最初にやるのは、送信側のエージェントにもう一度送らせることです。再送が通れば、ロックの競合だったと言えます。同じエラーが続くなら、環境側を確かめます。
# ホームのあるボリュームの空き容量
df -h ~
# teamsディレクトリの権限と所有者
ls -ld ~/.claude/teams
ls -l ~/.claude/teams/*/inboxes/見るポイントは2つです。df の出力で使用率が100%に近いなら、ディスクが原因です。ls -l で所有者が自分のユーザーと違っていたり、書き込み権限が無かったりすれば、権限が原因です。sudo で起動したセッションの残骸などで所有者が食い違うことがありますが、これはあくまで一般的なUnix環境の話で、Claude Codeの仕様として書かれているわけではありません。
直したあとは、同じメッセージをもう一度送らせます。エラー文もリカバリ手順も再送を前提に書かれているので、セッションを作り直す前にまず再送だけ試します。
メッセージの種類ごとのエラー文
メールボックスには、通常のテキストだけでなく、プロトコル用の構造化メッセージも流れます。計画の承認、計画の却下、シャットダウン要求、シャットダウンの拒否が該当し、書き込みに失敗するとエラーが送ろうとした種類を名指しします。
Failed to write the <message> to <name>'s inbox — nothing was sentややこしいのは「plan approval」と「plan approval request」の区別です。前者はリードがteammateの計画を承認する決定で、後者はteammateがリードへ計画を提出するメッセージです。後者と他の2種類は、専用の文言で出ます。
| エラー文 | 何が起きたか |
|---|---|
Failed to write the plan approval request to the lead's inbox — plan not submitted; try again | 何が起きたかteammateの計画がリードに届いていない。再提出が成功するまで、teammateはplanモードのまま |
The permission request could not be delivered to the team lead (mailbox write failed) | 何が起きたかteammateの権限リクエストがリードに届いていない。誰もそのツール呼び出しを承認していない |
The confirmation could not be written to team-lead's inbox. | 何が起きたかシャットダウンの承認自体は有効で、teammateは終了する。リードへの確認だけが届いていない |
3行目だけは性質が違います。teammateは実際に終了しているので、リードが「まだ生きている」と思い込んでいる可能性があります。1行目と2行目は逆で、受信側が動けないまま待つ状態になります。
権限リクエストの失敗は、特に静かに詰まります。teammateの権限プロンプトはリードのセッションに出る仕組みなので、その経路が書き込み失敗で切れると、teammateは承認待ちのまま止まります。権限まわりの仕組みはAgent Teamsの権限モデルにまとめています。
自分で@メンションしたときの見え方
リードのセッションで @name に続けてメッセージを打つと、自分からteammateに直接送れます。この経路で書き込みに失敗した場合は、ツール結果ではなく通知として表示されます。
Couldn't write to @name's inbox — message not sent. Try again.このとき入力したテキストはプロンプト欄に残ります。打ち直す必要はなく、原因を直してからそのまま送信し直せます。エージェント同士のやり取りでは見落としやすい一方で、人間が打った場合は画面に出るため、気づくのは早くなります。
別の理由で届かないケースとの見分け方
受信側に何も届かない理由は、書き込み失敗だけではありません。エラー文があるかどうかで、ある程度まで絞れます。
- auto modeの分類器がブロックした: auto modeでは、分類器がエージェント間のメッセージを配信前に確認します。ブロックされたメッセージは受信側に届きません。これは書き込み失敗ではなく、意図した遮断です
- メールボックスのJSONに不正な行がある: Claude Codeはメールボックスを読むたびに各エントリを検証し、形式に合わないものはエラーとして報告したうえで削除します。有効なメッセージは配信されます。v2.1.207より前は、不正なエントリが1件あるだけで毎秒エラーが出続け、そのメールボックスへの配信が止まっていました。ファイルを手で消すまで直らない型です
- セッション間メッセージの失敗: 同じマシン上の別セッションに送る機能は、Agent Teamsのメールボックスとは別の仕組みです。メッセージが大きすぎる、短時間に送りすぎた、受信側のキューが満杯、といった別のエラー文で報告されます
最後のものは inboxes/ 配下のファイルとは無関係なので、ディスクや権限を調べても何も出ません。エラー文に「cross-session」とあれば、こちらの系統です。
「agent definition was not restored」が出たとき
もう1つ、書き込み失敗と並んで紹介されている通知があります。停止中のteammateにメッセージを送ると、Claude Codeは同じセッション内でそのteammateを復帰させ、保存されていた会話を戻して、メッセージを次のプロンプトとして渡します。このとき、元のサブエージェント定義が再適用されないことがあります。
Its agent definition was not restored: the folder its definition file came from is not trusted (source: projectSettings), so the teammate is running with the team-essential tools and no custom instructions. ...通知は、送信側エージェントのツール結果にある復帰報告の後ろに付きます。inboxの書き込み失敗とは違い、メッセージ自体は届いています。届いた先のteammateが、定義の tools や本文を持たない素の状態で動いているのが問題です。
原因は、定義ファイルのあるフォルダが信頼されていないことです。対象は、プロジェクトまたは --add-dir で追加したディレクトリの .claude/agents/ にある定義です。親フォルダを信頼していても条件を満たしません。
直し方は2通りあります。
- 通知が示すフォルダで
claudeを起動し、信頼ダイアログを承認する。フォルダは--debugのログに出る。定義は、次にteammateが復帰したときに再適用され、リードのセッションを再起動する必要はない ~/.claude.jsonの該当エントリで、hasTrustDialogAcceptedをtrueにする。キーはデバッグログが出力するprojects["<path>"]の形そのまま使う
通知の文面には「ユーザーの代わりに信頼設定を変更しないこと」という指示も含まれています。エージェントに任せず、人間が自分で承認する前提の作りです。定義をteammateに流用する仕組みの全体は、サブエージェント定義をteammateに流用する記事で扱っています。
症状別の早見表
| 見えている症状 | 疑う原因 | 最初の一手 |
|---|---|---|
Failed to write to <name>'s inbox が出る | 疑う原因ディスク、権限、ロック | 最初の一手再送し、通らなければ df と ls -ld |
| 古い版でteammateが返事をしない | 疑う原因v2.1.224より前の、失敗の握りつぶし | 最初の一手Claude Codeを更新する |
| エラーは無いが届かない(auto mode) | 疑う原因分類器によるブロック | 最初の一手遮断された理由をログで見る |
| 不正エントリのエラーが毎秒出る | 疑う原因v2.1.207より前の検証 | 最初の一手更新する。直らなければファイルを確認 |
| teammateが定義の指示を無視する | 疑う原因信頼されていないフォルダ | 最初の一手該当フォルダで claude を起動して承認 |
teammateがそもそも起動しない、途中で止まる、tmuxセッションが残る、といった症状は別の話です。そちらはAgent Teamsが動かないときの対処法で扱っています。全体像から確認したいときは、Agent Teamsとはが入口になります。
再発しにくくする運用
書き込み失敗の原因は、ディスク、権限、ロックのどれかです。前の2つは事前に確かめられます。
ディスクは、チームを回す前に df -h ~ で見る習慣をつけるだけで防げます。長時間のセッションでは、ログや生成物がホームのボリュームを圧迫していないかも見ておくと安心です。
ロック競合は一時的で再送で通るため、本来は人間が介入する場面ではありません。ただ、エージェントが「エラーが出た、諦める」と判断してしまうと、タスクが止まります。指示文に「メッセージの送信に失敗したら、一度再送し、それでも失敗するならリードに知らせる」と書いておけば、エラー文の「Try again, or message the lead」と同じ動きを促せます。これは公式の推奨ではなく、エラー文の内容を指示に落とした一例です。
もう1つの注意点は、チーム構成ファイルの扱いです。~/.claude/teams/{team-name}/config.json にはセッションIDやtmuxのペインIDなど実行時の状態が入っていて、手で編集しても次の更新で上書きされます。inboxの書き込みが通らないからといって、このディレクトリの中身を作り直そうとするのは筋が悪い手です。チームのディレクトリはセッション終了時に自動で削除される一方、タスクリストは別の場所に残ります。
まとめ
inboxの書き込み失敗は「届いていない」ことを正直に報告する仕組みで、v2.1.224以降は握りつぶされなくなりました。再送が通ればロック競合、通らなければディスクと権限を見る。この順番で、ほとんどの場合は原因に届きます。復帰したteammateの定義が効いていないときは、書き込みではなくフォルダの信頼設定が原因です。