code executionとbashツールの混同が起きる実行環境の対処法

code executionツールとbashツールを同じリクエストに渡すと、片方で作った変数やファイルをもう片方から参照しようとする、あるいはどちらのツールを呼ぶべきか判断を誤る、という挙動が出ることがあります。Anthropicはこの構成を公式docsで「マルチコンピュータ環境」と呼んでいます。混同しやすい設計上の理由と、システムプロンプト側での防ぎ方、症状からの切り分けを順に示します。なお、code executionツール単体の挙動は$OUTPUT_DIRの罠で詳しく扱っています。

code executionとbashツールは別々のコンピューターを指す

code executionツールは、Anthropicが用意したサンドボックスコンテナの中でコマンドを実行します。ネットワークアクセスは完全に遮断され、pandas・matplotlib・numpyなどがプリインストールされています。コンテナはリクエストごとに新しく作られ、前のレスポンスのコンテナIDを渡したときだけ引き継がれます。

一方bashツールはクライアントツールで、Claude自身はコマンドを実行しません。Claudeがtool_useブロックでコマンド文字列を返し、あなたのアプリケーションが自分のbashセッションで実行して結果を返す、という往復です。

名前が似ていて紛らわしいのは、code executionの中にもbash_code_executionというサブツールがある点です。code executionを渡すと、シェル実行のbash_code_executionとファイル編集のtext_editor_code_executionがClaudeに自動で与えられます。結果の型はbash_code_execution_tool_resultで、あなたが返すtool_resultとは別物です。「bash」という語が2か所に出てくるので、ログを読むときはサーバー側で実行されたものか、自分のアプリが実行したものかをserver_tool_useの有無で見分けます。

2つの環境はファイルシステムもプロセスもネットワークも共有しません。code executionの$OUTPUT_DIRやコンテナ内の/tmpはAnthropicのインフラ上、bashツールの作業ディレクトリはあなたのサーバー上にあります。Claudeの目には、どちらも「コマンドを実行できるツール」として並びます。公式docsは、両方を同時に提供した状態をマルチコンピュータ環境と呼びます。

Claudeが混同する典型パターン

公式docsが挙げる混同は、誤ったツールを使うことと、環境間で状態が共有されていると思い込むことの2つです。具体例にすると次のようなケースが考えられます。

• code executionのサンドボックスで生成したCSVを、次のステップでbashツールのcatで読もうとする。bashツールのセッションにそのファイルはありません
• ユーザーのローカルファイルを読みたいのにcode_executionを呼ぶ。サンドボックスは外部ネットワークもローカルファイルシステムも遮断されているので、ユーザーの環境には届きません
• 「さっきインストールしたライブラリ」が、どちらの環境の話なのかを取り違える

いずれも、2つのツールを同じコンピューターの別の入り口と見なしている点が共通しています。

システムプロンプトに環境の違いを書いて混同を防ぐ

公式docsが示す対処は、システムプロンプトに両者の違いを書くことです。

When multiple code execution environments are available, be aware that:
- Variables, files, and state do NOT persist between different execution environments
- Use the code_execution tool for general-purpose computation in Anthropic's sandboxed environment
- Use client-provided execution tools (e.g., bash) when you need access to the user's local system, files, or data
- If you need to pass results between environments, explicitly include outputs in subsequent tool calls rather than assuming shared state

ポイントは最後の項目です。「状態は共有されない」と伝えるだけでなく、環境をまたいで結果を渡すなら後続のツール呼び出しに出力を明示的に含める、という代替手段まで指示しています。禁止だけを書くと、渡す手段が無いまま立ち往生する指示になります。

結果を明示的に橋渡しする実装パターン

社内DBから顧客データを取得し、集計をcode executionのpandasで行いたいケースで、最後の項目の指示を具体的に流れにするとこうなります。

「bashセッションの/tmp/data.csvをcode executionから読んで」という指示は、環境が別である以上機能しません。

往復させる中身には、2つの注意があります。bashツールの出力はAPIが切り詰めず、大きすぎるリクエストは拒否されます。大きなCSVをそのまま返さず、アプリケーション側で行数を絞ってから返します。また、bashの出力に認証情報が混じると、その文字列がClaudeの文脈に入り、橋渡しでcode execution側のコードに埋め込まれる可能性があります。公式docsはクレデンシャルなどの秘密情報を、Claudeに返す前に出力から取り除くよう求めています。

中間データが大きいときは、Files APIにアップロードしてcontainer_uploadブロックでcode execution側に渡す経路もあります。逆向きでは、code executionが出力ディレクトリに保存したファイルのIDがツール結果に載り、Files APIでダウンロードできます。Files APIに置かれたファイルは、明示的に削除するまで残ります。bashツールの出力をFiles APIにアップロードする処理は、アプリケーション側の実装です。

状態が続く範囲は環境ごとに違う

「同じセッションなのだから続いているはず」という思い込みも混同の元です。状態の寿命が環境ごとに違うので、並べておきます。

• bashツール: アプリケーションが1つのbashプロセスを保てば、作業ディレクトリ・環境変数・作成したファイルが次のコマンドに残ります。APIはステートレスで、セッションをいつ始めて、いつ終えるかはアプリ側の仕事です。ツール入力のrestart: trueを処理したときは、新しいシェルを立てて、作業ディレクトリ・環境変数・実行中のプロセスをすべて失った状態から始めます
• code execution: コンテナは作成から30日で失効します。約5分間使われないとコンテナはチェックポイントされ、30日以内にIDを付けて送れば復元されます。失効したコンテナのIDを送るとエラーになるので、containerパラメータなしで再送して新しいコンテナを得ます
• Pythonの変数: code_execution_20260120以降とプログラムからのツール呼び出しを使うときに限り、コンテナを再利用するリクエストをまたいで保たれます。Claude Haiku 4.5では、この状態保持は使えません

レスポンスのcontainer.expires_atは、30日の寿命ではなく、より短い再計算される値です。この値だけ見て「あと何日使える」と判断すると、読み違えます。

web_search/web_fetchが環境をもう1つ増やす

見落とされがちなのが、web_search_20260209以降・web_fetch_20260209以降のツールです。これらは動的フィルタリングのために、code executionを自動で用意します。クライアント側のbashツールを提供済みのアプリケーションでこれらを追加すると、意図しない2つ目の実行環境が加わります。

code executionはweb searchやweb fetchと併用すると、追加の料金がかかりません。bashツールと組み合わせるアプリケーションでは、上のシステムプロンプトで2つの環境の違いを伝えておくと混同を避けやすくなります。

同時に呼んだときの結果が届く順番

Claudeがクライアントツール(bashツールなど)とcode executionを同じターンで呼んだ場合、code executionの呼び出しはレスポンスに含まれますが、実行結果はまだ入っていません。結果が届くのは、クライアントツールのtool_resultを送り返した後の、次のレスポンスです。

この返り方を知らないと、「code executionを呼んだのに結果がない」という不具合に見えます。tool_resultを返した次のレスポンスでbash_code_execution_tool_resultを探します。エラーが返ってきたときの切り分けはエラーコード一覧にまとめています。

症状から原因を切り分ける

症状が出たとき、どの環境の話かを先に決めると原因が絞れます。

使い分け早見表

判断に迷ったら、表の1行目だけを見れば足ります。ユーザー側のリソースに触るならbashツール、Anthropicのサンドボックスで完結する計算ならcode executionです。

まとめ

両方のツールを渡す構成自体は正当です。Claudeには別々のコンピューターが2つあると、システムプロンプトで伝えておくことが、混同を防ぐ最短の手段です。ツールの数自体を減らしたい場合はAdvanced Tool UseのTool Search Toolも選択肢になります。