CLAUDE_CODE_BG_TASKS_REPORT_RUNNINGで非対話セッションの状態報告を切り替える

CLAUDE_CODE_BG_TASKS_REPORT_RUNNING は、非対話セッションがホストに報告する実行状態を制御する環境変数です。以前はバックグラウンドエージェントが実行中でも「waiting for your input」(入力待ち)と誤って報告されることがあり、v2.1.269でこの不具合が修正されました。0 を設定すると、修正前の挙動(ターン終了ごとにidleを報告する形)に戻せます。

CLAUDE_CODE_BG_TASKS_REPORT_RUNNINGが制御するもの

Claude Codeのリモートセッションとヘッドレスセッションは、自分の実行状態(running / idle)をホストに向けて報告しています。-p付きで起動する非対話セッションもこれに含まれます。ホストとは、リモートセッションの一覧のように状態を監視する側のツールです。

バージョンによる既定値の違い

この変数の挙動は、v2.1.269を境に前提が変わります。

v2.1.269以降では1は既定そのものなので、明示しても差は出ません。逆に、v2.1.269より前のバージョンで0を指定してもすでにidle報告が既定なので変化はありません。

バージョンをまたいで同じ監視ロジックを動かしているホストでは、アップデート後にrunning表示が急に増えたように見えることがあります。既定値が変わったためです。

バックグラウンドシェルは対象外 — -pの終了時の扱いと並べる

running状態の保持対象になるのは、バックグラウンドエージェントやワークフローの実行です。npm run devのようなバックグラウンドシェルコマンドは、動かしたままでもrunning状態を保持する理由になりません。

claude -pでは、プロセスが終わるときの扱いも同じ線で分かれます。状態報告とは別の仕組みですが、バックグラウンドシェルと、サブエージェント・ワークフローとで扱いが違う点は共通です。

Monitorの待機中も、Claudeは監視が報告する内容に応じて動き続けます。待機の上限はCLAUDE_CODE_PRINT_BG_WAIT_CEILING_MSで変えられ、0にすると上限なしで待ちます。devサーバーを立てたまま終わるような実行でも、サブエージェントやワークフローが残っていなければ、待たされるのは5秒の猶予だけです。

バックグラウンドシェルには、もう一つ別の扱いがあります。macOSとLinuxでは、OSがメモリ逼迫(critical memory pressure)を報告したときに、Claude Codeがバックグラウンドシェルを終了することがあります。条件はもう一つあり、セッションが30分間アイドルで、ターンもサブエージェントも動いていないことです。

止めたい場合はCLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP=1を使います。Windowsにはメモリ逼迫の信号がないため、この変数は効きません。長く立てっぱなしにするdevサーバーは、状態報告の面でも終了の面でも、エージェントやワークフローとは別枠で扱われます。

runningが長く続くのはどんな作業か

保持の対象になるワークフローは、複数のエージェントを一度に走らせる実行です。CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTSは、1回の実行が同時に動かすエージェント数を1〜256で決めます。既定は最大16で、CPUが少なければそれ以下です。v2.1.269のリリースノートでは、この変数がrunning保持の既定化と同じリリースで追加されています。

大きなワークフローには警告も出ます。スケジュールされたエージェントが25を超えるか、見込みのトークン総量が150万を超えると、入力欄の下のタスクパネルにLarge workflowと表示されます。ultracodeをオンにしている間は、この警告は出ません。進行中の実行は/workflowsで一覧でき、選んでxを押すと止められます。claude -pとAgent SDKではワークフローの起動時に確認プロンプトが出ず、通常の権限評価(denyルール、askルール、dontAskモード)がそのまま適用されます。

同時数を増やすほど、実行は大きく広がります。各エージェントの記録はClaude Codeのメモリに残るため、値を上げるとメモリ使用量も増えます。CLAUDE_AUTO_BACKGROUND_TASKS=1を併用すると、長く動くサブエージェントが約2分でバックグラウンドへ移ります。ホストが見るrunningの継続時間は、こうしたバックグラウンド作業の長さに連動します。

設定方法

シェルの環境変数として渡します。

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"
  }
}

注意したいのは、シェルのexportとenvの値が衝突したときの優先順位です。-pではワークスペースのtrustダイアログが出ないため、プロジェクトの.claude/settings.jsonのenvも起動時に適用されます。実行中のセッションでは、保存した変更が反映されます。

ただし変数を消しても実行中のセッションでは解除されず、次の起動から効かなくなります。

プロジェクト設定に0を書いたリポジトリで、あるジョブだけ既定に戻したいときは、コマンド前置きでは戻りません。そのジョブでは、settings.local.jsonか--settingsで渡すJSONに1を書くと、projectの0より優先されます。managed settingsが0を固定している場合は上書きできません。Claude Desktopや自己ホスト環境のランナーが起動したセッションは例外で、起動側が渡した値が優先され、設定ファイルのenvは無視されます。

どんな運用で意味を持つか

この変数を意識する必要があるかどうかは、非対話セッションの使い方によって差が大きく開きます。

自作のリモート監視ホストを持たない、あるいは単発のバッチ実行しかしていない場合は、既定値のままで足ります。複数の非対話セッションを一覧化するホストを運用しているなら、既定挙動を把握しておく価値があります。「今どれが手を離してよい状態か」の判定に効くためです。対話セッションの状態を手元の端末で見たいだけなら、別の道具が向きます。statuslineでworktreeセッションを表示する方法のほうが用途に近いでしょう。

v2.1.269で何が直ったのか

v2.1.269のリリースノートには、ある問題の修正が載っています。リモートセッションとヘッドレスセッションが、バックグラウンドエージェントの実行中に「waiting for your input」と報告していた問題です。修正前の挙動に戻すにはCLAUDE_CODE_BG_TASKS_REPORT_RUNNING=0を設定する、という注記つきです。

env-varsのページでは、この変数の説明に「Claudeがまだ作業中なのに、リモートセッション一覧のようなホストが入力待ちと表示するのを防ぐ」とあります。この変数は一覧とchangelogにも載っています。-pを使った非対話実行の基本は、Claude Code -pモードでスクリプトやパイプラインを自動化する基本にあります。

状態が想定と違うときの切り分け

ホストの表示が期待とずれたときは、症状から原因を絞れます。

バージョンと、変数が書かれている場所は次のコマンドで確かめられます。

claude --version
grep -n BG_TASKS_REPORT_RUNNING ~/.claude/settings.json \
  .claude/settings.json .claude/settings.local.json

1行目にはバージョン番号が返ります(例: 2.1.289 (Claude Code))。grepが何も返さなければ、設定ファイルには書かれていません。シェルのenvコマンドや、managed settingsの配布元も合わせて見ます。

関連する環境変数 — バックグラウンド作業のライフサイクル

状態報告は「今どう見えるか」の変数です。バックグラウンド作業を「いつまで続けるか」「終了時にどう扱うか」は、別の変数が決めます。

ホストを自作する場合は、状態報告(この記事の変数)と、待機・終了の挙動(上表)を別の軸として設計します。モデル側がテキストのみの応答で完了を誤って報告する挙動への対策は、Claude Opus 5.5のエージェントが途中で止まるのを防ぐ設定にまとめています。長いツール呼び出しが自動でバックグラウンドへ移る仕組みは、MCPの長時間ツール呼び出しが自動でバックグラウンド化する仕組みで扱っています。

まとめ

自作のホストで非対話セッションの状態を見ているなら、v2.1.269以降はrunningが長く続くのが正常な挙動です。以前の「ターンが終わればidle」を前提にした判定ロジックは見直す余地があります。