MOC - Claude Code Research
研究目标
这份索引页用于整理 Claude Code / agent runtime / tool system / subagent orchestration 的源码阅读结果。
当前主线
- Claude Code 源码阅读路线
- Claude Code 架构总览
- Agent 调用链
- AgentTool 解析
- runAgent 解析
- query.ts 工具分发链
- createSubagentContext 解析
- toolExecution.ts 解析
- query.ts 中 tool_use → tool_result 收束逻辑
- Fork subagent 机制
- Task 系统总览
- Prompt cache 设计
- 权限系统如何影响 AgentTool
主题分组
1. 主调用链
2. Tool 系统
3. Agent 体系
- AgentTool 解析
- runAgent 解析
- createSubagentContext 解析
- Fork subagent 机制
- teleportToRemote 决策树
- teleportToRemote session_context 与 outcomes
- createAndUploadGitBundle 机制
- task-notification 到 attachment 回流序列图
- foreground 到 background 热切换机制
- AgentTool 清理顺序与泄漏防线
- runAgent finally 实际清理项
- killShellTasksForAgent 机制
- AgentTool sync async remote 三路总图
4. Task / 生命周期
- Task 系统总览
- AgentTool 异步执行到 TaskNotification 回流 trace
- RemoteAgentTask 到 TaskNotification 回流 trace
- LocalAgentTask vs RemoteAgentTask
- ShellCommand TaskOutput LocalShellTask 后台执行模型
5. 横切主题
6. 外部综述 / 二手资料
- 2026-04-12 sathwick reverse-engineering-claude-code 摘要
- 2026-04-12 wavespeed claude-code-architecture-deep-dive 摘要
- 2026-04-13 Windy how-claude-code-works 摘要
7. 后续建议补充
当前结论
Agent在这个系统里是一个一等工具，而不是框架外的魔法能力- 主 agent 和子 agent 共用同一个
query()主循环 AgentTool.call()负责把“agent 调用”路由到同步 / 后台 / fork / worktree / remote 等具体路径runAgent()是真正的子 agent 启动器toolExecution.ts定义了单工具执行协议query.ts负责把tool_use严格收束成合法的tool_result轨迹- fork subagent 的重点是共享父上下文并最大化 prompt cache 命中，而不是简单地换个 agent type
- Task 层负责的不是推理，而是任务生命周期：注册、进度、通知、恢复、终止
- prompt cache 不是小优化，而是反过来塑造架构的约束
- 权限系统不是挂在 AgentTool 外面的壳，而是它的治理骨架
- 长会话工程（压缩、失败恢复、后台通知）是理解 Claude Code 成熟度的另一个横切视角
- shell、agent、remote 虽然中间执行壳不同，但在 output file、task-notification、attachment re-entry 这些长会话治理协议上明显在收敛
阅读建议
如果要继续深挖，优先顺序建议是：
Remote agent 机制从 QueryEngine 到 TaskNotification 的完整总图- 回头挑一个真实执行路径，做一次端到端 trace