Independent research on Claude Code internals, Claude Agent SDK, and related tooling. All findings are based on reverse engineering the publicly distributed npm packages.
Each report includes both English and Chinese versions.
Over 30 open GitHub issues document unexplained token waste, security concerns, and architectural problems in Claude Code — many with dozens of comments and no official response. This repository provides the technical root-cause analysis that the community has been asking for, along with working solutions.
| # | Topic | Description |
|---|---|---|
| 1 | Agent SDK Cache Invalidation | Why Agent SDK V1 query() costs 3–10x more than CLI per message — prompt cache invalidation caused by process-per-call architecture. Fix: V2 persistent session + SDK patch. |
| 2 | System-Reminder Injection | Complete reverse-engineering of the <system-reminder> injection mechanism — 15+ hidden injection types, the readFileState tracking system, 4 root-cause bugs, and why the Agent SDK triggers injection on every single turn. |
| 3 | Prompt Cache Architecture | How Claude Code controls what gets cached and for how long — the single cache_control factory (Ml()), per-model disable gates, server-side 1h TTL gating via feature flag allowlist, system prompt static/dynamic zone split, message-level sliding window, and why byte-for-byte prefix matching makes injection order critical. |
| 4 | Tool Serialization & Cache Stability | The 4-stage tool pipeline, why there is zero .sort() on tool arrays, how deferred tool loading silently busts the cache mid-conversation, and MCP tool description dynamism as a hidden instability source. |
| 5 | Context Lifecycle Management | How Claude Code decides when to compress context — 5 hardcoded threshold constants, the 10-step compaction flow, preserved message segments, the currentDate daily cache-kill problem, and compact chain reactions that compound cache rebuild costs. |
| 6 | Production Cache Optimization | Concrete, tested patches and strategies for maximizing prompt cache efficiency — 3 cli.js patches (context margin, 1h TTL force, compaction threshold), cache keepalive, tool ordering stabilization, efficiency monitoring, and the postinstall patch delivery pattern. |
| 7 | Cache Invalidation Verification | Why MCP tool discovery via ToolSearch doesn't bust the prompt cache — the defer_loading flag excludes deferred tools from the cache prefix entirely. Verified through source code, official docs, GitHub issues, and live experiment. Includes complete cache breakpoint map, three system prompt cache strategies, and a practical scenario guide for every operation that does or doesn't invalidate cache. |
| 8 | Auto Mode Classifier Cost | Auto Mode makes a hidden Opus-level API call before every side-effecting tool use. The classifier receives the full condensed conversation history, only fixed portions benefit from caching, and a Statsig flag can silently double the calls. Includes complete flow, cost estimation, cache analysis, and 4 mitigation options. |
- anthropics/claude-code#16021 — File modification reminders injected every message (23 comments)
- anthropics/claude-code#4464 — system-reminder consuming too many context tokens (22 comments)
- anthropics/claude-code#17601 — 10,000+ hidden injections consuming 15%+ context
- anthropics/claude-code#27599 — Infinite system-reminder repetition in headless mode
- anthropics/claude-code#18560 — system-reminder instructs Claude to ignore CLAUDE.md
- anthropics/claude-code#31447 — Claude social-engineers users into relaxing permissions
- anthropics/claude-code#23537 — System reminders disguised as user input
- anthropics/claude-code#27128 — System messages mislabeled as Human: turn
- anthropics/claude-agent-sdk-typescript#188 — SDK defaults to 1h cache TTL (2x write cost)
- anthropics/claude-code#9769 — Request for system-reminder toggle (open since 2025-10)
- anthropics/claude-code#30730 — Sub-agent injection overrides custom agent definitions
Reports #1–2 are based on @anthropic-ai/claude-code v2.1.71. Reports #3–6 are based on @anthropic-ai/claude-agent-sdk v0.2.76 (cli.js build 2026-03-14). Report #7 is based on @anthropic-ai/claude-code v2.1.85 (cli.js build 2026-03-26). Report #8 is based on @anthropic-ai/claude-code v2.1.88 (cli.js build 2026-03-30). Findings may change with future SDK updates.
If you reference this research in blog posts, articles, or other projects:
CabLate, "Claude Code Research," GitHub, 2026.
https://github.com/cablate/claude-code-research
We welcome new research findings, corrections, and updates. See CONTRIBUTING.md for submission guidelines, quality standards, and the report structure template.
This is independent research. It is not affiliated with, endorsed by, or sponsored by Anthropic. All analysis is performed on publicly distributed npm packages. No proprietary source code is reproduced.
CC-BY-4.0 — You are free to share and adapt this material with appropriate attribution.