Claude Code 2.1.211〜の新機能を今日から使い倒す7選

サブエージェントの“思考”や長時間実行ツールの進捗が見えず、デバッグや監視で詰まっていませんか？このままだと原因特定に時間を取られます。

Claude Code 2.1.211は、そんな「見えない」問題を解消する実用的な改善を多数含んでいます。本記事では今日から使い倒せる7つの新機能を厳選し、サブエージェントの思考ログやツール実行のストリーミング、タイムアウト管理、デバッグ用インサイトの取り出し方まで、短い手順と設定例で即効性のある使い方を具体的に紹介します。これを読めば、原因特定にかかる時間を確実に短縮できます。

そもそもどう動くのか

サブエージェントの「考え」を見落として、後で原因不明の振る舞いに悩まされていませんか？

仕組みをざっくり言うと、今回のリリース群は（1）サブエージェント出力をstream-jsonへ明示的に含めるフラグ／環境変数（2.1.211）を追加、（2）長時間ツール呼び出しに経過時間カウンターをUIに表示（2.1.210）、（3）/model 等のダイアログがバックグラウンドセッションでブロックされる不具合を修正（2.1.209）しています。つまり「イベント（stream-json）に細かい思考／開始・終了時間を載せて集め→解析して閾値監視する」流れがすぐ作れます。

7ステップで使い倒す手順

1. サブエージェント出力を有効化

• 環境変数 or フラグでオンにする（2.1.211の事実）。 例: export CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1 claude-code --forward-subagent-text > stream.json

1. stream-json内の該当行を素早く確認

• grepで「thinking」や「subagent」を検索: grep -nEi 'subagent|thinking' stream.json

1. サブエージェント思考を構造化して抽出

• jqで簡易抽出（出力の構造に合わせてフィールド名を調整してください）: jq '.events[] | select(.text != null) | {ts:.timestamp,role:.role,text:.text}' stream.json > parsed.json

1. 長時間ツール呼び出しの可視化をログで補強

• UIで経過時間が表示される（2.1.210）ことは目視確認に有用。自動化するにはstart/endイベントの差分計算を。 例（start/endにtimestampとidがある想定で計算）: jq -s 'group_by(.id) | .[] | {id:.[0].id, duration: (.[1].timestamp - .[0].timestamp)}' parsed.json

1. アラート基準に組み込む（Prometheus Pushgateway例）

• 長時間ツールが閾値を超えたらPush: curl -X POST --data-binary "agent_tool_duration_seconds{tool="ocr"} 125"http://pushgateway:9091/metrics/job/claude_agent

1. バックグラウンドセッションでのダイアログ確認

• 2.1.209で /model 等がブロックされなくなったので、バックグラウンド実行→UIで /model を開き応答を確認して下さい（問題が出る場合はログを添えて再現手順を取る）。

1. 既存ログ基盤へ取り込む（Filebeat例）

• filebeat prospectorsでstream.jsonを拾ってElasticsearchへ投げる設定抜粋: filebeat.inputs:
• type: log paths: ["/var/log/claude/stream.json"] json.keys_under_root: true

まとめ 仕組みは単純で、「サブエージェントをstream-jsonに載せる」→「思考と開始/終了で解析」→「監視に投げる」の流れを作れば、原因追跡とSLA監視が一気に楽になります。まずは1つ目の手順を真似して、CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1 を設定して stream.json を取得してみてください。

① サブエージェントの“思考”を取得する — フラグと環境変数の使い方

家のPCの前でしかサブエージェントの“思考”が追えずにイライラしていませんか？

そもそもどう動くのか --forward-subagent-text フラグ（または環境変数 CLAUDE_CODE_FORWARD_SUBAGENT_TEXT）を有効にすると、claude-code の stream-json 出力にサブエージェントのテキスト／思考が含まれるようになります。つまり標準出力をそのままパイプで繋げば、サブエージェントの発話をログ・フィルタ・監視に取り込めます。下は実務で使える具体手順の7選です。

1. 環境変数で有効化（セッション単位）

export CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1

これでそのシェルから起動する claude-code に適用されます。

1. フラグを使って起動して確認

claude-code --stream-json --forward-subagent-text | grep -n subagent

まずは grep で出力に "subagent" が含まれる行を探し、流れていることを確認します。

1. ログをファイルに残す（後で解析）

claude-code --stream-json --forward-subagent-text 2>&1 | tee claude_stream.jsonl

stream-json は行指向の JSON 出力になりがちなので、ファイル化して jq で解析できます。

1. jq でサブエージェント関連のブロックだけ抽出

cat claude_stream.jsonl | jq -c 'select(tostring | test("subagent"))' > subagent_blocks.jsonl

キー名を厳密に仮定せず、JSON を文字列化して "subagent" を含むオブジェクトを拾います。

1. サブエージェントの「テキスト」だけ抜く（存在すれば）

cat subagent_blocks.jsonl | jq -r '.. | .text? // empty' > subagent_texts.txt

再帰探索で text フィールドを抽出。複数階層でも拾えます。

1. リアルタイム監視（タイムスタンプ付き）

claude-code --stream-json --forward-subagent-text | jq -c 'select(tostring|test("subagent"))' \
  | while read -r line; do echo "$(date -u +"%FT%T%z") $line"; done

監視ツールやログシッパーに流す前にタイムスタンプを付与しておくと便利です。

1. 有効化確認とトラブルシュート

• 環境変数がセットされているか：echo $CLAUDE_CODE_FORWARD_SUBAGENT_TEXT
• フラグの存在確認：claude-code --help | grep forward-subagent-text
• それでも出ない場合は、stream-json の出力全体を短時間キャプチャして（例: head -n 200）中身を確認してください。

まとめ --forward-subagent-text（または CLAUDE_CODE_FORWARD_SUBAGENT_TEXT）を有効にすると、サブエージェントの思考を標準出力経由で扱えます。まずはターミナルで次の一行を試してください：

export CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1; claude-code --stream-json --forward-subagent-text | grep -n subagent

出力が見えたら、上の jq レシピでログ化／抽出に移りましょう。

② stream-json をファイルに残して後から解析する手順

家のPCの前にいないと解析できない、という無駄な手間をなくしたい人へ。

そもそもどう動くのか：claude-code の --stream-json は1行ずつJSON（JSON Lines）を標準出力に流す。2.1.211で追加された --forward-subagent-text / CLAUDE_CODE_FORWARD_SUBAGENT_TEXT を付けると、サブエージェントのテキストや「thinking」表現もそのJSON行に含まれる（追記済み事実）。生のJSONLをそのままファイルに落とし、後からgrep/jq/スクリプトで解析するのが最も確実だ。

1. まず出力をファイルへ（エラーは別ファイルへ）

claude-code --stream-json --forward-subagent-text > out.stream.jsonl 2> err.log

1. JSONLの行毎に有効か確認（壊れた行を探す）

jq -R 'fromjson? | . // "INVALID"' out.stream.jsonl | sed -n '1,100p'

（壊れた行があると "INVALID" と出る）

1. ログローテートを設定する（破壊的編集はしない） /etc/logrotate.d/claude-code の例：

/path/to/out.stream.jsonl {
  daily
  rotate 7
  compress
  copytruncate
  missingok
}

copytruncateで既存プロセスの出力を止めずにローテーションできる。

1. まずはテキスト検索で当たりをつける

grep -n subagent out.stream.jsonl | sed -n '1,200p'

行番号付きで一覧が出るので該当箇所へジャンプしやすい。

1. 該当行を整形して中身を確認（安全にJSONとして表示）

grep subagent out.stream.jsonl | while read -r line; do echo "$line" | jq '.'; done

jqで見やすくなる。キー名を断定できない場合でも“subagent”を含む行だけを対象にする運用が有効。

1. コンテキスト（前後N行）を抽出して一塊で解析する

linenums=$(grep -n subagent out.stream.jsonl | cut -d: -f1)
for n in $linenums; do sed -n "$((n-5)),$((n+5))p" out.stream.jsonl | jq -s '.' > context_${n}.json; done

近傍をまとめてjq -sで配列化すると後処理が楽。

1. 自動抽出スクリプト（Python例：任意の値に"subagent"が含まれる行を取り出す）

import json
def has_subagent(obj):
    if isinstance(obj, dict):
        return any(has_subagent(v) for v in obj.values())
    if isinstance(obj, list):
        return any(has_subagent(v) for v in obj)
    if isinstance(obj, str):
        return "subagent" in obj
    return False

with open("out.stream.jsonl") as f:
    for line in f:
        try:
            j = json.loads(line)
        except json.JSONDecodeError:
            continue
        if has_subagent(j):
            print(json.dumps(j, ensure_ascii=False))

まとめ：生JSONLは加工せず溜めてgrep→jq→スクリプトで段階的に絞るのが再現性と安全性で最強。まずは1行目のコマンドを実行して out.stream.jsonl を吐かせ、grepで当たりを付けることを次の一歩にしてください。

③ jq／テキストツールでサブエージェント出力を抽出する実例

サブエージェントの出力が大量に混ざって、欲しいメッセージだけ追えない──そんなストレスが一行で解決できる。

そもそもどう動くのか
Streaming 出力を一行ずつ JSON として扱い、行単位で「subagent」を含む行だけ取り出す。ここでの肝は jq の -R + fromjson? で「生の行」を安全に JSON に変換し、tostring を使って行全体を文字列化して検索すること。構造体の有無に依らず抽出できるため、まずは絞り込み→必要ならフィールド単位で掘る、という流れが実務では安定する。

1. ベーシックフィルタ（例で示された形）
   cat でファイルを流し、JSONL をパースして「subagent」を含む行だけ抽出する最短形。

cat out.stream.jsonl | jq -R 'fromjson? // empty' | jq -c 'select(tostring | test("subagent";"i"))'

1. ストリーミング監視（リアルタイム）
   tail -f と組み合わせて、追いかけながら抽出する。

tail -f out.stream.jsonl | jq -R 'fromjson? // empty' | jq -c 'select(tostring | test("subagent";"i"))'

1. 抽出した行からテキストだけ取り出す（text フィールドがある場合）
   フィールドがあれば .text を取り出す。存在しなくてもエラーにならない書き方。

cat out.stream.jsonl | jq -R 'fromjson? // empty' | jq -r 'select(tostring | test("subagent";"i")) | .text? // empty'

1. 行ごとの重複削除・保存
   同じ出力が重複するログを落として保存する。

cat out.stream.jsonl | jq -R 'fromjson? // empty' | jq -c 'select(tostring | test("subagent";"i"))' | awk '!seen[$0]++' > subagents.jsonl

1. 名前や役割でさらに絞る（role フィールドがあれば）
   もし JSON に role 等の属性があれば、その値でフィルタ可能。

cat out.stream.jsonl | jq -R 'fromjson? // empty' | jq -c 'select(.role == "worker" and (tostring | test("subagent";"i")))'

※フィールドが不確実なら先に tostring ベースで絞るのが安全。

1. 件数カウント（簡易サマリ）
   抽出行の総数や、role ごとの個数を把握する一行コマンド例。

cat out.stream.jsonl | jq -R 'fromjson? // empty' | jq -c 'select(tostring | test("subagent";"i"))' | wc -l

role があれば:

cat out.stream.jsonl | jq -R 'fromjson? // empty' | jq -r 'select(tostring | test("subagent";"i")) | .role // "unknown"' | sort | uniq -c

1. 出力側を有効にする（サブエージェント本文を転送）
   Claude Code 側でサブエージェント本文の転送が必要な場合、環境変数かフラグを有効化することで stream-json に含められる（仕様追加。動作確認してから使うこと）。例:

export CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1
# または実行時に --forward-subagent-text フラグを指定（ツール側の起動オプション）

これで stream の行に subagent の思考やテキストが含まれるようになるはずだ（導入済みの事実に基づく設定項目）。

まとめ
まずは出力に subagent テキストが含まれているかを環境変数で有効にし、上の jq パイプラインで必要行を抽出してみよう。まず一回、CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1 をセットして先ほどの一行コマンドを流してみることをおすすめする。

④ 経過時間カウンター(2.1.210)で長時間ツールの“止まってる感”を確認する

家のPCで「固まった？」と何度もリロードして時間を無駄にしていませんか？

そもそもどう動くのか：2.1.210で、折りたたまれたツール要約行に「経過時間（秒単位）」が表示されるようになった。長時間処理を呼び出したとき、その要約行が秒数で刻々と増えるため「処理が進んでいる／止まっている」を視覚的に判定できる仕組みである。

1. バージョン確認（まず前提）

• UIのバージョン表示で 2.1.210 以降であることを確認。CLIが使えるなら例：

claude --version

1. 長時間タスクを用意する（再現用）

• ダミーでOK。プロジェクトルートに以下を置く：

#!/bin/bash
# long_task.sh
sleep 120
echo "done"

• 実行権限を付与：chmod +x long_task.sh。エージェントにシェル実行を依頼するか、ローカルで./long_task.shを起動。

1. UIでの確認手順

• 長時間処理を走らせ、エージェントUIの「ツール要約（collapsed）」行を見る。秒数が1秒ごとに増えていれば進行中。増えていなければ停止の疑い。

1. 見逃したときのログ検索（具体例）

• UIのログパネルで Ctrl+F → "elapsed" やツール名で検索。または端末でログファイルを調べる例（パスは環境に合わせて置換）：

tail -n 200 /path/to/agent.log | grep -i elapsed

1. 秒数の変化を自動で監視するワンライナー

• 1秒ごとに最新の経過表示を拾う例：

watch -n 1 "tail -n 200 /path/to/agent.log | grep -i elapsed | tail -1"

• 何秒間も表示が変わらなければ「止まった」と判断できる。

1. 一定時間で打ち切る（実務で使う）

• 外部で監視してタイムアウトさせるならtimeoutを使うのが簡単：

timeout 300 ./long_task.sh   # 300秒で強制終了

• Claude側で自動再試行や停止指示を出させたい場合は、ログの経過時間が更新されないときに停止コマンドを送る仕組みを作る。

1. CI / 通知との連携（簡易）

• 経過時間が一定秒数更新されなければ通知するスクリプト例（Webhookは適宜置換）：

ELAPSED=$(tail -n 200 /path/to/agent.log | grep -i elapsed | tail -1 | awk '{print $NF}')
# ELAPSED をパースして変化がなければ curl で通知

• 実務では「変化のない期間」を閾値にしてアラートを上げると良い。

まとめ： 経過時間カウンターは「固まったかどうか」を人手で判定する手間を大幅に減らす実装だ。まずは上のダミースクリプトを1回走らせて、折りたたまれた要約行の秒数が増えるのを確認してみてください。

⑤ backgroundセッションでの /model 等のブロック問題の確認と対処（2.1.209）

バックグラウンドで動くエージェントが /model に反応しないと、その場で確認できないままワークフローが止まる — そんなイライラ、ありませんか。

そもそもどう動くのか：claude の「background セッション」はメイン対話とは別プロセス／サブエージェントでスラッシュコマンドを受け付ける。過去はそのルーティングを守るガードが広すぎて、/model 系のダイアログが背景セッションで遮断されていた。2.1.209でその遮断が修正されている（検証済み事実）。

1. バックグラウンドセッションを起動する（UIまたはCLIで）。UIなら「Run in background」をクリック、CLI例（環境による）:

claude-code agents start --background

1. 別クライアント／別タブから /model 系コマンドを送る。チャット入力に例えば:

/model

と投げて、直ちに応答が返るかを確認する（応答はモデル一覧や ACK）。

1. 応答が来ない／ハングする場合の判別。スピナーが続く、明示的なエラーが出る、あるいはタイムアウトで応答が消える、が要注意シグナル。

2. まずバージョンを確認する（修正は 2.1.209 に入っています）。CLIでの例:

claude-code --version

表示されたバージョンが 2.1.209 以降であるかを確認してください。

1. 実行プロセスとログを取る。プロセスを探して PID を控え:

ps aux | grep -i claude

PID を使ってジャーナルを抽出:

journalctl _PID=<PID> -n 500 --no-pager > claude-agent.log

またはインストール先にログファイルがあれば直近 500 行を保存。

1. 再現手順と証拠を固める。最小手順（背景起動→/model 投入）のタイムスタンプ、セッションID（UIに表示されていれば記録）と、保存したログ（claude-agent.log）をセットにする。

2. 問題報告テンプレート（添付ファイル：claude-agent.log とバージョン出力、再現手順）。例文：

環境: <OS>, claude バージョン: <出力>
再現手順: 1) 背景セッション起動 2) 別クライアントで "/model" を送信
期待: /model に対する応答
現象: 応答が返らない（タイムスタンプ: ...）
添付: claude-agent.log

まとめ：まずは背景セッションを立ち上げて /model を投げ、応答が来るか確認してください。問題が継続する場合は上の手順でバージョンとログ（journalctl の出力）を保存して報告するのが次の一手です。

⑥ ベクトルDB呼び出しや外部ツール連携でサブエージェント痕跡をたどる

家のPCの前にいないと「どこでベクトルDBに投げたか」が追えずに夜中に詰む、そんな経験ありませんか？

そもそもどう動くのか Claude Code 2.1.211 では、サブエージェントのテキスト（思考や転送内容）を stream-json 出力に含めるオプションが追加されました。つまり「サブエージェントに渡したクエリやパラメータ」が標準出力のストリームにそのまま残る可能性が高く、ファイル化すればあとから検索・抜き出しが容易になります。仕組みが分かればログを引いて解析するだけです。

7選（手を動かせる手順）

1. サブエージェント転送を有効にする

• 起動時にフラグまたは環境変数を設定。

  export CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1
  claude agents run my-agent --forward-subagent-text --stream-json > out.stream.jsonl
  

1. まずはざっと検索（grep）

• ベクトルに関する痕跡をざっくり抽出。

  grep -nEi 'vector|vec|ベクトル|ベクトルデータベース|ベクトルdb' out.stream.jsonl
  

1. 該当チャンクだけ抜き出す

• 見つかった行番号から該当行を別ファイルへ。

  grep -nEi 'vector|vec|ベクトル' out.stream.jsonl | cut -d: -f1 | xargs -I{} sed -n '{}p' out.stream.jsonl > vectors.excerpts.jsonl
  

1. JSON を整形して中身を読む（可読化）

• JSONL の各行を jq で整形。

  sed -n '1,200p' vectors.excerpts.jsonl | jq .
  

1. 外部ツール呼び出しの痕跡を掘る

• 「ベクトルDB」以外に endpoint URL や embed などのキーワードも同様に grep。見つけた行を追って tool 呼び出し前後を確認。

  grep -nEi 'endpoint|embed|ベクトル' out.stream.jsonl
  

1. バイナリやエンコードされたペイロードを復号する

• base64 らしき文字列があればデコードして内容を確認。

  echo 'BASE64STRING' | base64 -d | jq .
  

1. 抜粋を共有／隔離する（機密対策）

• 問題のあるチャンクだけをチームに渡す。全文共有が不要なら抜粋ファイルを渡す。

  mv vectors.excerpts.jsonl /secure/team-shared/
  

まとめ サブエージェント転送を有効にすると stream-json に痕跡が残りやすく、grep→抜出→整形の流れで短時間に追跡できます。まずは自分の最新 out.stream.jsonl に対して上の grep コマンドを一度走らせてみてください。これが次の一歩です。

⑦ 障害時の最小限の証跡収集と開発運用フロー

本番でサービスが止まったとき、最初に聞かれるのは「どう再現したんですか？」であり、それに答えられないと話が進まない。

そもそもどう動くのか：Claude Code は --stream-json で実行過程を逐次 JSON に吐ける。2.1.211 で追加された --forward-subagent-text（環境変数 CLAUDE_CODE_FORWARD_SUBAGENT_TEXT でも可）を付けると、サブエージェントのテキストや“thinking”も stream-json に含まれるため、外から見えない内部経路の証跡が取れる。標準出力／標準エラーをファイルにリダイレクトしておけば、調査用の最小限セットが得られる。

7ステップ（最小限の証跡テンプレ）

1. 実行コマンドを固定する（再現コマンドを明記）
   例: 実行するワークフロー／スクリプトをそのまま書く。CLI なら次をそのまま伝える。

   CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1 claude-code --stream-json --forward-subagent-text \
     --config ./my-config.yaml --input input.yaml > out.stream.jsonl 2> err.log
   

2. stdout と stderr を分けて保存する（必須）
   上のリダイレクトで out.stream.jsonl と err.log を得る。err.log はクラッシュ時のトレースや権限エラーを拾う。
3. 実行環境を明記する（OS・shell・CLI バージョン）
   例: uname -a; bash --version; claude-code --version を実行して出力を添付する。
4. 問題箇所を grep でざっくり拾う（高速に絞る）
   例:

   grep -n "subagent" out.stream.jsonl | head
   grep -n -E "ERROR|Exception" err.log
   

5. jq で該当 JSON を抽出する（詳細）
   JSON 構造が不明でも文字列検索で十分。例:

   jq -c 'select(tostring|contains("subagent") or tostring|contains("thinking"))' out.stream.jsonl > suspects.jsonl
   

6. 秘密情報をマスクして共有する
   API キーやパスは sed で伏せる。例:

   sed -E 's/(sk-[A-Za-z0-9]{20,})/REDACTED_KEY/g' err.log > err.redacted.log
   

7. バグ報告テンプレに貼ってチケット作成、再現手順を再実行して確認する
   添付するのは：再現コマンド、out.stream.jsonl（または suspects.jsonl）、err.redacted.log、環境出力のスクショまたはテキスト。

まとめ：まずは上のコマンドで1回丸ごと取り、grep→jq で問題箇所を切り出してチケットに貼ると調査が早く始まる。まずは上記の1回分を収集して共有してみてください。

まとめ

Claude Code 2.1.211のサブエージェント転送、2.1.210の経過時間表示、2.1.209の /model 修正は、ログ取得→解析→運用組み込みの流れで最短の改善をもたらします。特にサブエージェント転送はフロー追跡の精度を上げ、経過時間表示はボトルネック特定を高速化します。これにより短期間で観測性と対処速度が向上します。まずは環境変数を一つ設定して出力を取り、サブエージェントの痕跡を一度確認してみましょう。