プロンプトキャッシュのミス原因の表示
CHANGELOG 原文（英語）
Added a likely cause for prompt-cache misses (e.g. tool definitions or system prompt changed, idle past the TTL) to /cost and the status line's prompt_cache field 公式の変更履歴を開く ↗ 日本語での補足
/cost とステータスラインの prompt_cache フィールドに、ツール定義やシステムプロンプトの変更、TTL経過によるアイドルなど、prompt-cacheミスの推定原因を追加
関連ドキュメント
機能の基本的な使い方を確認できます。今回の変更は上の原文をご覧ください。
ドキュメントの抜粋（参考訳）
プロンプトキャッシュのフィールド
prompt_cache オブジェクトは、セッションのメイン会話がプロンプトキャッシュをどのように利用しているかをまとめたものです。Claude Code は API レスポンスに含まれるキャッシュのトークン数から算出するため、どのプロバイダーでも利用できます。
このオブジェクトは、メイン会話で最初の API レスポンスを受け取った後に現れます。サブエージェントのリクエストは、この統計に含まれません。Claude Code v2.1.251 以降が必要です。
各フィールドの意味は次のとおりです。タイムスタンプは rate_limits.*.resets_at と同じく、Unix エポックからの経過秒数です。短いステータスラインでは、通常、このうち 1〜2 項目を表示します。キャッシュの状態を最も直接的に把握できるのは warm と hit_ratio です。
| フィールド | 説明 |
|---|---|
warm |
キャッシュされたプレフィックスが有効期間（TTL）内にあるかどうか。直近のレスポンスでキャッシュのトークン数が報告されなかった場合は、caching_observed が true でも false になります。 |
caching_observed |
このセッションで、キャッシュのトークン数を報告したレスポンスが一度でもあったかどうか。false は、プロンプトキャッシュが無効か、プロバイダーまたはゲートウェイがその情報を報告していないことを意味します。 |
ttl |
現在キャッシュされているプレフィックスの有効期間。"5m" または "1h" です。 |
expires_at |
キャッシュされたプレフィックスの TTL が切れて利用できなくなる時刻。Unix エポックからの経過秒数です。直近のレスポンスでキャッシュのトークン数が報告されなかった場合は null になります。 |
requests |
このセッションのメイン会話で記録された API リクエスト数。 |
misses |
キャッシュにすでにあった内容を再処理したリクエスト数。キャッシュから読み取れたはずの内容のうち、5% を超え、かつ 2,000 トークン以上を再処理しており、その読み取り不足をコンパクションやツール結果の削除では説明できない場合に数えられます。 |
expected_rebuilds |
コンパクションや古いツール結果の削除に伴って行われたキャッシュの再構築回数。 |
hit_ratio |
このセッションのすべての入力トークンに占める、キャッシュから読み取ったトークンの割合。0〜1 の値です。分母には、キャッシュからの読み取り、キャッシュへの書き込み、キャッシュされていない入力を含みます。これらの数がすべてゼロの間は null になります。 |
cache_write_tokens |
このセッションでキャッシュに書き込まれたトークンの総数。最初のリクエストによる初回の書き込みも含みます。 |
miss_recache_tokens |
キャッシュミスとして数えられたリクエストが、キャッシュに書き込んだトークン数。 |
last_miss_at |
直近のキャッシュミスが発生した時刻。Unix エポックからの経過秒数です。このセッションでミスが発生していない間は null になります。 |
last_miss_cause |
直近のミスについて、Claude Code が推定した原因。直近のミスの原因で説明する内容です。Claude Code v2.1.260 以降が必要です。 |
miss_causes |
このセッションで原因を特定できたミスのうち、それぞれの原因に該当した件数。キー名は last_miss_cause と同じ原因名を使います。Claude Code v2.1.260 以降が必要です。 |
recache_tokens_if_cold |
次のリクエストまでにキャッシュの有効期限が切れた場合、そのリクエストが再キャッシュするトークン数。コンパクションや古いツール結果の削除の直後は null となり、次のリクエストで再構成後の会話のサイズが記録されるまでそのままです。 |
同じ統計は、ターミナルの /usage コマンドの Prompt cache (main) 行でも確認できます。
直近のミスの原因
last_miss_cause オブジェクトは、直近のミスについて Claude Code が推定した原因を報告します。その causes 配列には、tools_changed、system_prompt_changed、ttl_expired_5m、likely_server_side などの原因名が 1 つ以上含まれます。このオブジェクトは、セッションで最初のミスが発生するまでは null であり、直近のミスの原因を Claude Code が特定できなかった場合にも null に戻ります。Claude Code v2.1.260 以降が必要です。
2 つの原因では、オブジェクトに件数も追加されます。
tools_addedとtools_removed:tools_changedの場合、リクエストに追加または削除されたツールの数system_char_delta:system_prompt_changedの場合、システムプロンプトの文字数の変化量
取得日 · 2026-09-23