Claude Code の Bash ツールの挙動:タイムアウトと出力上限

Claude Code エンジニアリング 7分で読めます

Claude Code がシェルコマンドを実行するときに使うのが組み込みの Bash ツールです。普段は意識しなくても使えますが、「export した変数が次のコマンドで消えている」「長いビルドが途中でバックグラウンドに回った」「テストログの後半が見えていない」といった挙動には、すべて決まったルールがあります。この記事では、公式ドキュメント「Tools reference」の Bash ツールの節をもとに、コマンド間で引き継がれるもの、タイムアウト、出力の上限、バックグラウンド実行の時間制限と、それぞれを変える環境変数・設定を整理します。

コマンド間で引き継がれるもの

Bash ツールはコマンドを1回ごとに別のプロセスで実行します。そのため、何が次のコマンドに残り、何が残らないかが決まっています。

virtualenv や conda の環境は、Claude Code を起動する前に有効化しておくのが公式の案内です。環境変数を Bash コマンドの間で持続させたい場合は、起動前に環境変数 CLAUDE_ENV_FILE にシェルスクリプトのパスを設定するか、SessionStart フックでその内容を動的に用意します。

タイムアウトの既定値と上限

各コマンドにはタイムアウトがあり、その管理は Claude 自身が行います。既定より長く待ちたいコマンドでは、Claude がその呼び出しに timeout パラメータを付けます。利用者がコマンドごとにタイムアウトを指定することはありません。

フォアグラウンドで実行するコマンドについては、次の2つの環境変数で範囲を変えられます(単位はミリ秒)。

環境変数意味既定値
BASH_DEFAULT_TIMEOUT_MSClaude が timeout を付けなかったときのタイムアウト120000(2分)
BASH_MAX_TIMEOUT_MSClaude が指定できるタイムアウトの上限600000(10分)

実際に効く上限は、BASH_MAX_TIMEOUT_MS と BASH_DEFAULT_TIMEOUT_MS の大きいほうです。PowerShell ツールも同じタイムアウトのルールに従い、同じ2つの変数を読みます。

フォアグラウンドのコマンドがタイムアウトまでに終わらなかった場合、Claude Code はそのコマンドを止めずにバックグラウンドへ移します(sleep で始まるコマンドは除く)。その場合の結果には、たとえば Command did not complete within its 120s timeout and was moved to the background のように、適用されたタイムアウトの秒数とともに移動したことが明記され、タスク ID と出力の書き込み先ファイルのパスが続きます。CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 を設定するか bare モードで動かすと、この自動移動は行われず、タイムアウトに達したコマンドはそこで止まります。

出力の上限と失敗時の扱い

コマンドの出力は実行中に作業用ファイルへ書き出され、終了後にそのファイルから読み戻されます。出力が 5 GB を超えたコマンドは強制終了されます。Claude にどれだけの出力がそのまま(インラインで)渡るかは、結果が「正常」か「失敗」かで変わります。

結果Claude が受け取るもの
正常既定でおよそ 30,000 文字まではインライン。それを超えると、セッションディレクトリに保存したファイルのパス(64 MiB を超える部分は切り捨て)と先頭最大 2,000 文字のプレビューが渡り、残りが必要なら Claude がそのファイルを読むか検索する
失敗およそ 10,000 文字まではインライン。超える場合は、読み戻した範囲から切り出した先頭と末尾の抜粋のみ(ファイルのパスは付かない)

注意したいのは終了コード 1 の扱いです。Bash ツールが終了コード 1 を「正常」とみなすのは、それが無害な結果だと Claude Code が認識しているコマンドだけで、grep・rg・egrep・fgrep・find・diff・test・[、それに git diff と git grep が該当します。それ以外は、たとえば一致なしの pgrep や jq -e、差分ありの cmp のように意味としては無害でも「失敗」扱いになり、出力は約 10,000 文字の抜粋に絞られます。

出力量の調整方法は2つあります。

バックグラウンド実行と時間制限

開発サーバーや watch ビルドのような長時間動くプロセスは、Claude が run_in_background: true を付けてバックグラウンドタスクとして起動し、その間も作業を続けられます。動いているバックグラウンドタスクの一覧表示と停止は /tasks で行います。そこやデスクトップアプリなどの接続中のクライアントから止めると、Claude は待たずに次へ進みます。

バックグラウンドのコマンドがいつ止まるかは、誰が起動したかで決まります。

時間制限がかかるのは、-p 実行、Agent SDK アプリケーション、CI ジョブ、クラウドセッションのように無人で動くセッションだけです(v2.1.285 以降。v2.1.288 より前はすべてのセッションに適用)。ターミナル・デスクトップアプリ・VS Code 拡張で自分が操作するローカルセッションには、バックグラウンドコマンドの時間制限はありません。

制限に達したコマンドは止められ、Background command "<description>" was stopped after reaching its background time limit という通知とともに理由が Claude に伝わります。作業がまだ必要なら、Claude はより長い timeout を付けて再実行できます。

この制限は、タイムアウトと同じ2つの環境変数で引き上げることができます(短くはできません。既定値より小さい値は無視され、既定値と2時間の上限がそのまま残ります)。

設定のまとめ

この記事で扱った環境変数と設定を一覧にします。環境変数はシェルで設定するか、settings.json の env ブロックに書けます。

名前種類用途
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR環境変数各コマンドの後に元の作業ディレクトリへ戻す(cd を引き継がない)
CLAUDE_ENV_FILE環境変数Bash コマンド間で持続させたい環境変数を書いたシェルスクリプトを指定
BASH_DEFAULT_TIMEOUT_MS環境変数既定のタイムアウト(既定2分)。大きくすると無人セッションのバックグラウンド既定制限も置き換わる
BASH_MAX_TIMEOUT_MS環境変数Claude が指定できるタイムアウトの上限(既定10分)。2時間超で背景実行の上限も上がる
BASH_MAX_OUTPUT_LENGTH環境変数結果へ読み戻す文字数(既定 30,000、最大 150,000)
bashOutputMaxChars設定正常な結果のインライン上限と読み戻し範囲(最大 128,000、v2.1.261 以降)。設定時は上の変数を無視
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS環境変数1 で run_in_background パラメータを外し、タイムアウト時の自動バックグラウンド移動も止める

たとえば、ビルドに15分ほどかかるプロジェクトで、Claude が待てる上限を30分に広げたい場合は次のように書きます。

{
  "env": {
    "BASH_MAX_TIMEOUT_MS": "1800000"
  }
}

どのコマンドを確認なしで実行させるかは別の仕組みで、Bash(npm run *) のような権限ルールで決めます。詳しくは権限モードの選び方を参照してください。

本記事は Claude Code 公式ドキュメント「Tools reference」の Bash ツールの節を元に、「Environment variables」で各環境変数の既定値と意味を照合した非公式の日本語解説です(確認日 2026-11-15)。仕様は更新される場合があるため、利用前に公式ドキュメントをご確認ください。