Issue Station
Sign In
Tools hereToolbox

claude-code - ✅(Solved) Fix [DOCS] Prompt caching TTL env var docs omit generic 1-hour and forced 5-minute controls [1 pull requests, 1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#48082•Fetched 2026-04-15 06:33:44
View on GitHub
Comments
0
Participants
1
Timeline
3
Reactions
0
Author
coygeekcoygeek
Participants
coygeekcoygeek
Timeline (top)
labeled ×3

PR fix notes

PR #142: feat(v8.2): Opus 4.7 最適化 + Anthropic 公式ベストプラクティス全反映

Description (problem / solution / changelog)

Summary

Anthropic 公式 4 ドキュメントの精査結果に基づき、ClaudeOS v8 を v8.2 へ更新。 Opus 4.7 移行と長時間自律運用 (5h) の最適化を全 11 項目で実施。

出典

  • claude.com/blog/using-claude-code-session-management-and-1m-context
  • claude.com/blog/best-practices-for-using-claude-opus-4-7-with-claude-code
  • platform.claude.com/docs/en/about-claude/models/migration-guide#migrating-to-claude-opus-4-7
  • code.claude.com/docs/en/changelog (v2.1.90 – v2.1.111)

変更内容（マトリクス対応）

P0 必須

#項目反映先
1Token 配分 1.35x 再キャリブレーションCLAUDE.md §13 + state.json
2Agent Teams 並列 spawn 明示プリアンブルCLAUDE.md §6
3/compact 事前発動規約 (Token 70% / Verify 失敗 3 回 / フェーズ切替)CLAUDE.md §12

P1 推奨

#項目反映先
4task_budget (beta) を 5h 運用に導入CLAUDE.md §13.5 + state.json
5ENABLE_PROMPT_CACHING_1H 適用settings.json + CLAUDE.md §13.6
6/ultrareview を Verify 必須に統合CLAUDE.md §8.6
7PreCompact hook で state.json/Memory 自動退避settings.json + pre-compact.js

P2 任意

#項目反映先
8/recap をセッション開始時に必須化CLAUDE.md §0 ステップ 4.5
9Push Notification を STABLE/Blocked/5h/Critical Review に接続notify-stable.js
10Effort 動的切替 (xhigh ⇄ high ⇄ medium)CLAUDE.md §10.5 + state.json

F (文体改修)

#項目反映先
11比喩・冗長記述削減、強制ルールとリファレンスの境界明示CLAUDE.md §22, §24

Hook 実装一覧

ファイル役割
claudeos/scripts/hooks/pre-compact.jssnapshot 退避 + 失敗時 exitCode 2 ブロック
claudeos/scripts/hooks/session-start.js前回コンテキスト読み出し + /recap 代替
claudeos/scripts/hooks/session-end.jslast_stop_at 記録
claudeos/scripts/hooks/suggest-compact.js§12 規約のプログラム化
claudeos/scripts/hooks/notify-stable.jsSTABLE / Blocked / 5h / Critical Review 通知

影響範囲

  • CLAUDE.md (v8 → v8.2) — 大幅改修 (+437 行 / -123 行)
  • .claude/settings.json — env に ENABLE_PROMPT_CACHING_1H、hooks に PreCompact/SessionStart/Stop 追加
  • .claude/claudeos/scripts/hooks/ — 4 ファイル実装 + 1 ファイル新規作成
  • .claude/claudeos/system/token-budget.md — Opus 4.7 補正・task_budget 連携・Effort 連動を明記
  • .claude/claudeos/snapshots/ — PreCompact 退避先 (新規ディレクトリ + 専用 .gitignore)

state.json は .gitignore 対象のため diff には含まれないが、 CLAUDE.md §4 にサンプル構造を v8.2 で更新。

Test Plan

  • Node 構文チェック: 全 5 hook で node --check パス
  • JSON parse: state.json / settings.json で JSON.parse パス (BOM 除去済)
  • session-start.js 実機実行: 前回コンテキスト出力確認
  • suggest-compact.js 実機実行: Token 0% で「不要」判定確認
  • pre-compact.js 実機実行: snapshot ファイル生成確認 (4359 bytes)
  • notify-stable.js 実機実行: STABLE 通知発火 (CLI 不在時 console fallback)
  • CI で全テスト通過 (本 PR で検証)
  • 次セッションで /recap 実行 → §0 ステップ 4.5 が機能するか確認
  • 次セッションで Token 70% 到達時に suggest-compact.js が推奨を出すか確認

残課題（本 PR スコープ外）

  • state.json テンプレートを claudeos/examples/ 配下に配置（新規セットアップ補助）
  • Cyber Verification Program 申請（Security Agent 業務影響時）
  • High-resolution image (Playwright MCP) のダウンサンプル方針

🤖 Generated with Claude Code

<!-- This is an auto-generated comment: release notes by coderabbit.ai -->

Summary by CodeRabbit

  • New Features

    • セッション開始/終了での状態記録、自動スナップショット保存と事前コンパクト提案の自動化
    • STABLE到達／Blocked／重大レビュー／5時間到達などの重要イベントに基づくプッシュ通知送信（フォールバック記録含む）

  • Documentation

    • Opus 4.7（v8.2）対応のトークン予算管理、Effort動的切替、フェーズ運用手順および通知/フック連携を大幅更新

  • Chores

    • フック定義と環境フラグを設定に追加、スナップショットアーティファクトを追跡除外に登録
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Changed files

  • .claude/claudeos/scripts/hooks/notify-stable.js (added, +145/-0)
  • .claude/claudeos/scripts/hooks/pre-compact.js (modified, +96/-1)
  • .claude/claudeos/scripts/hooks/session-end.js (modified, +52/-1)
  • .claude/claudeos/scripts/hooks/session-start.js (modified, +40/-1)
  • .claude/claudeos/scripts/hooks/suggest-compact.js (modified, +63/-1)
  • .claude/claudeos/snapshots/.gitignore (added, +3/-0)
  • .claude/claudeos/snapshots/.gitkeep (added, +0/-0)
  • .claude/claudeos/system/token-budget.md (modified, +65/-28)
  • .claude/settings.json (modified, +37/-1)
  • CLAUDE.md (modified, +376/-117)
RAW_BUFFERClick to expand / collapse

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/env-vars

Section/Topic

Prompt caching environment variables, especially ENABLE_PROMPT_CACHING_1H, FORCE_PROMPT_CACHING_5M, and the deprecated ENABLE_PROMPT_CACHING_1H_BEDROCK alias

Current Documentation

The env var reference currently documents prompt-caching controls like this:

DISABLE_PROMPT_CACHING | Set to 1 to disable prompt caching for all models (takes precedence over per-model settings)

DISABLE_PROMPT_CACHING_HAIKU | Set to 1 to disable prompt caching for Haiku models

DISABLE_PROMPT_CACHING_OPUS | Set to 1 to disable prompt caching for Opus models

DISABLE_PROMPT_CACHING_SONNET | Set to 1 to disable prompt caching for Sonnet models

ENABLE_PROMPT_CACHING_1H_BEDROCK | Set to 1 when using Bedrock to request a 1-hour prompt cache TTL instead of the default 5 minutes. Bedrock only

The model configuration page also frames prompt-caching configuration as disable-only:

Claude Code automatically uses prompt caching to optimize performance and reduce costs. You can disable prompt caching globally or for specific model tiers:

And the documented table there only lists DISABLE_PROMPT_CACHING, DISABLE_PROMPT_CACHING_HAIKU, DISABLE_PROMPT_CACHING_SONNET, and DISABLE_PROMPT_CACHING_OPUS.

The Vertex AI setup page similarly says:

Prompt caching is automatically supported when you specify the cache_control ephemeral flag. To disable it, set DISABLE_PROMPT_CACHING=1.

I could not find any code.claude.com page documenting ENABLE_PROMPT_CACHING_1H, FORCE_PROMPT_CACHING_5M, or that ENABLE_PROMPT_CACHING_1H_BEDROCK is deprecated but still honored.

What's Wrong or Missing?

Changelog v2.1.108 says:

Added ENABLE_PROMPT_CACHING_1H env var to opt into 1-hour prompt cache TTL on API key, Bedrock, Vertex, and Foundry (ENABLE_PROMPT_CACHING_1H_BEDROCK is deprecated but still honored), and FORCE_PROMPT_CACHING_5M to force 5-minute TTL

But the current docs still present the older Bedrock-only variable as the documented way to request a longer TTL, and they do not document the new generic controls.

A. The new cross-provider 1-hour TTL variable is missing

Users on API key, Vertex, and Foundry do not have documentation telling them to use ENABLE_PROMPT_CACHING_1H.

B. The forced 5-minute override is missing

There is no documentation for FORCE_PROMPT_CACHING_5M, so users cannot discover that Claude Code now has an env var specifically for forcing the 5-minute TTL.

C. The Bedrock-specific variable is now outdated as primary guidance

ENABLE_PROMPT_CACHING_1H_BEDROCK is still documented as current, Bedrock-only guidance, but the changelog says it is deprecated and only kept for backward compatibility.

Suggested Improvement

Update the prompt-caching env var docs to separate three concerns clearly:

  1. Disabling prompt caching entirely (DISABLE_PROMPT_CACHING*)
  2. Opting into a 1-hour TTL with ENABLE_PROMPT_CACHING_1H
  3. Forcing the default 5-minute TTL with FORCE_PROMPT_CACHING_5M

Suggested minimum fix:

  • Add ENABLE_PROMPT_CACHING_1H to env-vars with explicit provider coverage: API key, Bedrock, Vertex, and Foundry
  • Add FORCE_PROMPT_CACHING_5M to env-vars
  • Change ENABLE_PROMPT_CACHING_1H_BEDROCK to a deprecated-alias entry that says it is still honored but ENABLE_PROMPT_CACHING_1H is preferred
  • Update model-config so prompt-caching configuration is not described as disable-only
  • Add short provider-page notes or examples on Bedrock, Vertex, and Foundry setup pages showing where TTL selection fits into prompt-caching configuration
  • Document how these TTL env vars interact if both are set

Example wording for env-vars:

ENABLE_PROMPT_CACHING_1H | Set to 1 to request a 1-hour prompt cache TTL on API key, Bedrock, Vertex, and Foundry

FORCE_PROMPT_CACHING_5M | Set to 1 to force the default 5-minute prompt cache TTL

ENABLE_PROMPT_CACHING_1H_BEDROCK | Deprecated alias for ENABLE_PROMPT_CACHING_1H on Bedrock; still honored for backward compatibility

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

PageContext
https://code.claude.com/docs/en/env-varsPrimary env var reference still documents only the deprecated Bedrock-specific 1-hour variable
https://code.claude.com/docs/en/model-configPrompt caching configuration section currently documents disable-only controls
https://code.claude.com/docs/en/amazon-bedrockBedrock setup example mentions disabling prompt caching but not the new generic 1-hour TTL env var or deprecation of the old one
https://code.claude.com/docs/en/google-vertex-aiVertex setup mentions prompt caching and disable-only guidance, but no TTL override env vars
https://code.claude.com/docs/en/microsoft-foundryFoundry setup page does not document prompt-caching TTL env vars even though v2.1.108 says Foundry supports the new control
https://platform.claude.com/docs/en/build-with-claude/prompt-cachingCross-reference for the underlying 5-minute vs 1-hour prompt-caching TTL concept

Total scope: 6 pages affected

Source: Changelog v2.1.108

Exact changelog entry:

Added ENABLE_PROMPT_CACHING_1H env var to opt into 1-hour prompt cache TTL on API key, Bedrock, Vertex, and Foundry (ENABLE_PROMPT_CACHING_1H_BEDROCK is deprecated but still honored), and FORCE_PROMPT_CACHING_5M to force 5-minute TTL

extent analysis

TL;DR

Update the documentation to include the new environment variables ENABLE_PROMPT_CACHING_1H and FORCE_PROMPT_CACHING_5M, and deprecate ENABLE_PROMPT_CACHING_1H_BEDROCK.

Guidance

  1. Add new environment variables to documentation: Include ENABLE_PROMPT_CACHING_1H and FORCE_PROMPT_CACHING_5M in the environment variable reference page, with clear descriptions of their usage and effects.
  2. Deprecate outdated variable: Update the documentation to reflect that ENABLE_PROMPT_CACHING_1H_BEDROCK is deprecated, but still honored for backward compatibility, and recommend using ENABLE_PROMPT_CACHING_1H instead.
  3. Update model configuration page: Revise the model configuration page to describe prompt-caching configuration as not just disable-only, but also including options for opting into a 1-hour TTL or forcing a 5-minute TTL.
  4. Add provider-page notes: Include short notes or examples on the Bedrock, Vertex, and Foundry setup pages to show how TTL selection fits into prompt-caching configuration.
  5. Document interaction between TTL env vars: Clarify how ENABLE_PROMPT_CACHING_1H and FORCE_PROMPT_CACHING_5M interact if both are set.

Example

The updated environment variable reference page could include the following:

ENABLE_PROMPT_CACHING_1H | Set to 1 to request a 1-hour prompt cache TTL on API key, Bedrock, Vertex, and Foundry

FORCE_PROMPT_CACHING_5M | Set to 1 to force the default 5-minute prompt cache TTL

ENABLE_PROMPT_CACHING_1H_BEDROCK | Deprecated alias for ENABLE_PROMPT_CACHING_1H on Bedrock; still honored for backward compatibility

Notes

The changes should be made to the following pages: env-vars, model-config, amazon-bedrock, google-vertex-ai, microsoft-foundry, and build-with-claude/prompt-caching.

Recommendation

Apply the suggested improvements to update the documentation and ensure that users have accurate and complete information about prompt-caching environment variables.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#prompt template#agent execution#callback error#environment variable

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

claude-code - ✅(Solved) Fix [DOCS] Prompt caching TTL env var docs omit generic 1-hour and forced 5-minute controls [1 pull requests, 1 participants]