Claude Code Research

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.

Why This Exists

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.

Reports

#	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.

Related Issues

Token Waste

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

Security / Trust

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

SDK / Architecture

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

SDK Version Baseline

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.

How to Cite

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

Contributing

We welcome new research findings, corrections, and updates. See CONTRIBUTING.md for submission guidelines, quality standards, and the report structure template.

Disclaimer

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.

License

CC-BY-4.0 — You are free to share and adapt this material with appropriate attribution.