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. 主调用链

• Claude Code 架构总览
• Agent 调用链
• query.ts 中 tool_use → tool_result 收束逻辑

2. Tool 系统

• query.ts 工具分发链
• toolExecution.ts 解析

3. Agent 体系

• AgentTool 解析
• runAgent 解析
• createSubagentContext 解析
• Fork subagent 机制

4. Task / 生命周期

• Task 系统总览

5. 横切主题

• Prompt cache 设计
• 权限系统如何影响 AgentTool

6. 后续建议补充

• Remote agent 机制
• 从 QueryEngine 到 TaskNotification 的完整总图

当前结论

• 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 外面的壳，而是它的治理骨架

阅读建议

如果要继续深挖，优先顺序建议是：

1. Remote agent 机制
2. 从 QueryEngine 到 TaskNotification 的完整总图
3. 回头挑一个真实执行路径，做一次端到端 trace