CLAUDE_CODE_BG_TASKS_REPORT_RUNNINGで非対話セッションの状態報告を切り替える
リモート・ヘッドレスセッションが実行中でも入力待ちと誤報告されていた不具合がv2.1.269で修正されました。この環境変数で挙動を切り替えられます。
CLAUDE_CODE_BG_TASKS_REPORT_RUNNING は、非対話セッションがホストに報告する実行状態を制御する環境変数です。以前はバックグラウンドエージェントが実行中でも「waiting for your input」(入力待ち)と誤って報告されることがあり、v2.1.269でこの不具合が修正されました。0 を設定すると、修正前の挙動(ターン終了ごとにidleを報告する形)に戻せます。
CLAUDE_CODE_BG_TASKS_REPORT_RUNNINGが制御するもの
Claude Codeのリモートセッションやヘッドレスセッション(-pフラグ付きで起動する非対話セッションを含む)は、自分の実行状態(running / idle)をホストに向けて報告しています。ホストとは、リモートセッションの一覧を表示して監視する側のツールを指します。
既定の挙動では、あるターンの応答とツール呼び出しが終わっても、バックグラウンドエージェントやワークフローの実行がまだ続いていれば、セッションはrunning状態を報告し続けます。ホスト側が「Claudeがまだユーザーの入力を待っていない」と正しく認識できるようにするための挙動です。この既定値は、v2.1.269以降のバージョンで導入されました。
CLAUDE_CODE_BG_TASKS_REPORT_RUNNINGを0に設定すると、この既定の挙動をオフにできます。オフにすると、ターンが終わった時点でバックグラウンド作業が動いていてもidle状態を報告します。ターン単位で状態を区切りたい場合や、旧来の単純な報告方式に合わせたい場合に使う設定です。
バージョンによる既定値の違い
この変数の挙動は、v2.1.269を境に前提が変わります。
| バージョン | 既定の挙動 | running状態を保ちたい場合 |
|---|---|---|
| v2.1.269以降 | 既定の挙動ターン終了後もバックグラウンド作業中はrunningを保持 | running状態を保ちたい場合何もしなくてよい(既定のまま) |
| v2.1.269より前 | 既定の挙動ターン終了と同時にidleを報告(runningを保持しない) | running状態を保ちたい場合CLAUDE_CODE_BG_TASKS_REPORT_RUNNINGに1を設定 |
v2.1.269より前のバージョンを使い続けている場合、この変数に0を指定してもとくに意味はありません。古いバージョンではすでにidleを報告する挙動が既定だからです。逆に、古いバージョンで「作業中はrunningを保ちたい」場合は1を明示的に指定します。
バージョンをまたいで同じ監視ロジックを動かしているホストがある場合、この前後関係を把握しておかないと「アップデートしたらrunning表示が急に増えた」という体感になりえます。v2.1.269で、バックグラウンドエージェントの実行中に「waiting for your input」と報告されていた不具合が修正され、既定値が変わったことが理由です。
対象になるバックグラウンド作業と対象外の作業
running状態の保持対象になるのは、バックグラウンドエージェントやワークフローの実行です。一方で、開発サーバーのようなバックグラウンドシェルコマンドは対象に含まれません。
この線引きは、報告の粒度を「Claude自身が能動的に動いているか」で決めていることを意味します。ユーザーが立ち上げっぱなしにしているシェルプロセスの有無まで状態報告に含めると、常時起動のdevサーバーを持つ環境ではrunning状態が実質的に張り付いたままになり、ホスト側の監視が意味を持たなくなるためです。
たとえば、非対話セッションがdevサーバーをバックグラウンドで立ち上げたあと、テストの実行をワークフローとしてサブエージェントに任せている場面を考えます。この場合、running状態を保持するかどうかを左右するのはワークフローの実行状況で、devサーバー自体が動き続けていることは判定に影響しません。ワークフローが完了してターンも終われば、devサーバーがまだ生きていてもセッションはidleを報告します。
設定方法
シェルの環境変数として渡します。
export CLAUDE_CODE_BG_TASKS_REPORT_RUNNING=0
claude -p "バックグラウンドでテストスイートを回しつつ、次のタスクに進んで"1回の実行だけに適用したい場合は、コマンドの前に置く形でも渡せます。
CLAUDE_CODE_BG_TASKS_REPORT_RUNNING=0 claude -p "ワークフローを起動して結果を教えて"チームやCI環境をまたいで固定したい場合は、settings.jsonのenvキーに書く方法もあります。
{
"env": {
"CLAUDE_CODE_BG_TASKS_REPORT_RUNNING": "0"
}
}プロジェクト直下の.claude/settings.jsonに書けば、そのリポジトリで起動する非対話セッションすべてに同じ設定が配られます。個人ごとに挙動を変えたい場合は、プロジェクト設定ではなくユーザー単位の設定ファイルに書きます。
CI専用のジョブにだけexportで渡す構成にすると、同じリポジトリをローカルで手動実行したときに設定が抜け落ち、CIとローカルで状態報告のタイミングが食い違う原因になります。監視ホストの判定ロジックを1つに保ちたいなら、プロジェクト設定にまとめて書き、必要なジョブだけコマンド前置きで一時的に上書きする構成のほうが管理しやすくなります。管理設定(managed settings)に書けば、個人設定や実行時の環境変数でも上書きできない強制値にできます。
どんな運用で意味を持つか
この変数を意識する必要があるかどうかは、非対話セッションの使い方によって差が大きく開きます。
| 使い方 | この変数の重要度 | 理由 |
|---|---|---|
| リモートセッション一覧を自作ホストで監視する | この変数の重要度高い | 理由running/idleの誤報告がそのまま監視画面の誤表示になる |
| 自作のスクリプトでセッション状態をポーリングして判定する | この変数の重要度中程度 | 理由状態文字列を判定条件に使っている場合だけ影響する |
claude -pをワンショットのバッチ処理として使う | この変数の重要度低い | 理由セッションが1ターンで終わるなら報告のタイミング差が表に出にくい |
通常の対話セッション(-pなし)を使う | この変数の重要度対象外 | 理由この変数は非対話セッションの報告にのみ関わる |
自作のリモート監視ホストを持たない、あるいは単発のバッチ実行しかしていない場合は、既定値のままで困る場面はほとんどありません。逆に、複数の非対話セッションを一覧化して「今どれが手を離してよい状態か」を判定するホストを運用しているなら、この変数の既定挙動を把握しておく価値があります。対話セッションの状態を手元の端末で確認したいだけなら、statuslineでworktreeセッションを表示する方法のほうが用途に近いこともあります。
なぜこの既定値が必要になったか
非対話セッションがバックグラウンドエージェントやワークフローを起動したまま次のターンの入力待ちに戻ると、ホスト側からは「Claudeが止まっている」ように見えかねません。ターン終了だけを状態の切れ目にすると、実際にはバックグラウンドで処理が進んでいるのに、監視画面上はユーザーの入力待ちとして表示されてしまいます。
v2.1.269でrunning保持がデフォルト化されたのは、この見え方のずれを塞ぐ変更です。リモートセッション一覧のようなホストは、running表示をユーザーの入力待ちかどうかの判定に使うことがあり、状態報告が早すぎるとその判定を誤らせます。CLAUDE_CODE_BG_TASKS_REPORT_RUNNING=0は、そのデフォルト化された挙動をあえて外し、修正前の報告方式に戻すための脱出口として用意された形です。-pフラグを使った非対話実行の基本はClaude Code -pモードでスクリプトやパイプラインを自動化する基本にまとめています。
関連する環境変数 — バックグラウンド作業のライフサイクル
非対話セッションのバックグラウンド作業まわりには、状態報告以外にもいくつかの環境変数があります。合わせて把握しておくと、非対話実行の挙動を制御する全体像がつかみやすくなります。
| 環境変数 | 役割 |
|---|---|
CLAUDE_AUTO_BACKGROUND_TASKS | 役割長時間実行のサブエージェントを約2分後に自動でバックグラウンドへ移す |
CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS | 役割-p実行の最終ターン後、バックグラウンドのサブエージェントとワークフローを待つ上限時間(既定10分) |
CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF | 役割プロセスの再起動時にバックグラウンドの実行を次のプロセスへ引き継がせない |
CLAUDE_CODE_EXIT_AFTER_STOP_DELAY | 役割クエリループがアイドルになってから自動終了するまでの待機時間 |
CLAUDE_CODE_BG_TASKS_REPORT_RUNNINGが制御するのは「今どう見えるか」の報告であるのに対し、上表の変数群は「バックグラウンド作業をいつまで続けるか」「終了時にどう扱うか」を制御します。役割は分かれていますが、どちらも非対話セッションがターン終了後も裏で動き続けることを前提にした変数群です。ホストを自作する場合は、状態報告(本記事の変数)と待機・終了の挙動(上表の変数)を別軸として設計するとつじつまが合いやすくなります。
よくある質問
対話セッション(-pを付けない起動)でも意味がありますか
この変数の説明は非対話セッションに限定されています。対話的にclaudeと打って開く通常のセッションの状態報告には関わりません。
0にすると処理速度が変わりますか
変わりません。変わるのはホストに送る状態文字列だけで、バックグラウンドエージェントやワークフローの実行速度・完了タイミングには影響しません。
値を1にすると何が起きますか
v2.1.269以降では1が既定の挙動そのものなので、明示しても差は出ません。意味を持つのはv2.1.269より前のバージョンで、その場合は既定のidle即時報告をやめてrunningを保持する側に切り替わります。
まとめ
CLAUDE_CODE_BG_TASKS_REPORT_RUNNINGは、非対話セッションがバックグラウンドエージェントやワークフローの実行中にrunning状態を保つかどうかを決める環境変数です。v2.1.269で、実行中にもかかわらず入力待ちと誤って報告される不具合が修正され、既定(v2.1.269以降)ではrunningを保持するようになりました。0を指定すると、修正前の挙動(ターン終了ごとにidleを報告する形)に戻せます。バックグラウンドシェルコマンドは対象外で、影響が出るのはバックグラウンドエージェントとワークフローの実行に限られます。リモートセッション一覧のようなホストを自作・運用している場合は、この既定値の意味を押さえておくと状態表示の誤解を避けられます。バックグラウンド作業が自動でオフロードされる仕組みはMCPの長時間ツール呼び出しが自動でバックグラウンド化する仕組みで扱っています。