#子 Agent 设计：分身术与团队协作

// src/tools/AgentTool/loadAgentsDir.ts (lines 106-165)
type AgentDefinition = {
  agentType: string          // "Explore", "Plan" 等
  whenToUse: string          // 什么时候该用这个 Agent
  tools?: string[]           // 允许使用的工具列表，['*'] 代表全部
  disallowedTools?: string[] // 明确禁止的工具
  model?: string             // 'haiku', 'sonnet', 'opus', 'inherit'
  maxTurns?: number          // 最大执行轮数
  permissionMode?: string    // 'bubble' = 权限弹窗转发给父级
  omitClaudeMd?: boolean     // 是否跳过加载 CLAUDE.md（省 token）
}

// src/tools/AgentTool/built-in/exploreAgent.ts (lines 13-83)
{
  agentType: 'Explore',
  tools: ['Read', 'Glob', 'Grep', 'Bash'],   // 只给只读工具
  disallowedTools: ['Agent', 'Write', 'Edit'], // 禁止写和嵌套
  model: 'haiku',                              // 用最快的小模型
  omitClaudeMd: true,                         // 省掉项目说明（省 token）
}

// 主 Agent 的视角：调用 AgentTool
Agent({
  description: "搜索数据库相关代码",
  prompt: "在项目中找到所有数据库相关的文件和函数",
  subagent_type: "Explore"  // 指定类型
})

// src/tools/AgentTool/runAgent.ts (lines 248-329)
async function* runAgent({
  agentDefinition,    // Agent 类型定义
  promptMessages,     // 初始消息
  toolUseContext,     // 父级的上下文
  canUseTool,         // 权限检查函数
  isAsync,            // 是否后台执行
  availableTools,     // 预计算的工具池
  worktreePath?,      // Git worktree 隔离路径
}) {
  // 1. 生成唯一 Agent ID
  const agentId = generateAgentId()

  // 2. 准备上下文（克隆文件缓存、设置工作目录）
  const agentContext = createSubagentContext(parentContext, {
    agentId,
    agentType: agentDefinition.agentType,
    // 同步 Agent 共享父级的 AbortController
    // 异步 Agent 使用独立的 AbortController
    abortController: isAsync ? new AbortController() : parentAbortController,
  })

  // 3. 进入 query() 循环（和主 Agent 一样的循环！）
  for await (const message of query({
    messages: promptMessages,
    systemPrompt: agentSystemPrompt,
    tools: filteredTools,
    // ...
  })) {
    yield message  // 把每条消息传回给调用者
  }
}

// src/tools/AgentTool/forkSubagent.ts (lines 42-71)
const FORK_AGENT = {
  agentType: 'fork',
  tools: ['*'],           // 继承父级完全相同的工具
  permissionMode: 'bubble', // 权限弹窗转发给父级终端
  model: 'inherit',        // 使用和父级一样的模型
}

// src/tools/AgentTool/forkSubagent.ts (lines 107-169)
function buildForkedMessages(directive, parentAssistantMessage) {
  // 为父消息中的每个工具调用创建占位结果
  const placeholders = parentMessage.content
    .filter(block => block.type === 'tool_use')
    .map(block => ({
      type: 'tool_result',
      tool_use_id: block.id,
      content: 'Fork started — processing in background'
    }))

  // 所有 Fork 使用相同的占位符（→ 缓存命中）
  // 只有最后的指令文本不同
  return [parentAssistantMessage, [...placeholders, directive]]
}

// src/tools/SendMessageTool/SendMessageTool.ts (lines 67-87)
{
  to: string,       // 接收者："agent-名字", "*"（广播）
  summary: string,   // 5-10 字摘要
  message: string,   // 消息内容
}

// src/tools/AgentTool/agentToolUtils.ts (lines 70-116)
function filterToolsForAgent({ tools, isAsync, permissionMode }) {
  // 所有 Agent 都不能用的工具
  const ALWAYS_BLOCKED = ['TaskStop', 'TeamCreate', 'TeamDelete']

  // 后台异步 Agent 只能用这些
  const ASYNC_ALLOWED = [
    'Bash', 'Read', 'Write', 'Glob', 'Grep',
    'FileEdit', 'Agent', 'SendMessage',
    'Skill', 'WebFetch', 'WebSearch',
  ]

  if (isAsync) {
    return tools.filter(t => ASYNC_ALLOWED.includes(t.name))
  }
  return tools.filter(t => !ALWAYS_BLOCKED.includes(t.name))
}

// src/tools/AgentTool/agentMemory.ts

// 三个记忆范围
User 级别:   ~/.claude/agent-memory/       // 跨项目通用
Project 级别: .claude/agent-memory/         // 项目共享（可提交到 Git）
Local 级别:   .claude/agent-memory-local/   // 本地私有

// src/tools/AgentTool/forkSubagent.ts (lines 78-89)
function isInForkChild(messages) {
  // 检查消息中是否有 Fork 标记
  // 如果是 Fork 子代，禁止再次 Fork
  return messages.some(m => hasForkBoilerplateTag(m))
}