Claude Code Source Notes

Claude Code 源码阅读系列

这个系列先从一次普通任务的运行主线开始：入口、队列、REPL、query loop、模型流、工具执行和恢复记录先串起来，再逐篇拆 Memory、上下文、工具、权限、MCP、subagent、hooks、transcript、resume 和 prompt cache。

源码依据为公开镜像的 2026-03-31 固定快照，不能代表当前发行版。每篇区分快照内可见的客户端机制、当前官方文档合同与未公开实现。

不先钻某个机制，而是沿 CLI、REPL、队列、query()、模型调用、工具执行、 messages、transcript 和 resume 建立源码阅读路线。

沿 CLAUDE.md 与各类 memory 文件，区分缓存读取、失效重载和不同请求入口；文件写入不等于下一次请求立即更新。

从 context.ts、query.ts、microcompact、auto compact 和 prompt cache 入口出发，拆开 Claude Code 如何把一长串工作会话变成下一次模型请求。

模型给出的 tool_use 只是一张申请单。沿 ToolUseContext、 runTools() 和 runToolUse()，看 runtime 怎样找到工具、校验参数、检查权限，再把 tool_result 送回下一轮请求。

沿 ToolPermissionContext、permission modes、allow/deny/ask 规则、 PreToolUse、PermissionRequest 和拒绝回填，说明本地操作怎样被允许、拒绝或交给用户决定。

沿 getCommands()、slash command、SkillTool、MCP 连接和 assembleToolPool()，拆开扩展能力怎样进入本轮命令表与工具池。

沿 AgentTool、runAgent()、fork path、worker tool pool 和 createSubagentContext()，比较普通 subagent 的隔离状态与 fork 的缓存前缀复用。

沿 HOOK_EVENTS、getMatchingHooks()、executeHooks()、 PreToolUse、SessionStart、Stop 和 compact hooks，说明 hooks 在哪些步骤运行、收到什么输入，又能改变哪些结果。

沿 recordTranscript()、loadConversationForResume()、 processResumedConversation() 和 REPL /resume，拆开旧会话怎样恢复成可继续执行的 runtime。

沿 cache_control、稳定前缀、动态工具避让、fork cache-safe params、 cached microcompact 和 cache break detection，说明为什么稳定的请求前缀才会带来缓存复用。