knowledge-agent-execution-and-orchestration-subagent-runtime

name	knowledge-agent-execution-and-orchestration-subagent-runtime
description	覆盖子代理定义发现、前后台 Task 执行、durable resume lineage、结果采纳、验证代理和 managed worktree 生命周期。进入时机：新增 agent Markdown、修改 Task/TaskOutput、 调试后台完成通知、进程重启恢复、resume 或子代理隔离。不包含：团队任务图与成员邮箱 （见 ../agent-teams/）。关键词：SubagentRegistry, SubagentExecutor, BackgroundAgentManager, AgentSessionStore, resume_from, verification, worktree。

Module Structure

子代理是拥有独立 SessionRuntime、transcript 和 sidecar 的 child run；Task 工具负责身份与调用契约，执行器负责运行，后台管理器负责持久状态、通知和崩溃恢复。

Directory Layout

• packages/cli/src/agent/subagents/ — 注册表、执行器、sidecar、恢复、结果采纳和内置代理
  • SubagentRegistry.ts — Markdown/frontmatter 配置加载和优先级
  • SubagentExecutor.ts — 独立 child SessionRuntime 执行
  • BackgroundAgentManager.ts — 后台运行、等待、取消、resume 和 orphan reconciliation
  • AgentSessionStore.ts — durable sidecar 与 lineage/config snapshot
  • SubagentWorktreeLifecycle.ts — 隔离 worktree 准备与收尾
  • SubagentResultAdoption.ts — 父 Task 缺失结果时的重启采纳
  • BackgroundSubagentCompletion.ts — 后台终态通知构造
• packages/cli/src/tools/builtin/task/task.ts — Task 工具前台、后台和 resume 协议
• packages/cli/src/cli/agents.ts — --agents 单次运行定义严格解析
• packages/cli/src/slash-commands/agents.ts — TUI agent 管理入口
• .claude/agents/ — Git 可见的 Claude Code 兼容 agent 定义
• docs/guides/subagents.md — 用户可见配置与恢复契约

Key Entry Points

• createTaskTool() in packages/cli/src/tools/builtin/task/task.ts — 模型侧委派入口
• SubagentRegistry.loadFromStandardLocations() in packages/cli/src/agent/subagents/SubagentRegistry.ts — 分层资源发现
• SubagentExecutor.execute() in packages/cli/src/agent/subagents/SubagentExecutor.ts — 直接前台执行器
• BackgroundAgentManager.startBackgroundAgent() in packages/cli/src/agent/subagents/BackgroundAgentManager.ts — durable 后台 child 启动
• BackgroundAgentManager.resumeAgent() in packages/cli/src/agent/subagents/BackgroundAgentManager.ts — immutable child resume

Gotchas

• resume_from 不会复用原 agent ID，而会创建新的 child run；源运行必须已终止、类型必须一致，并记录 rootAgentId → resumedFrom → resumeDepth，否则恢复被拒绝 (packages/cli/src/tools/builtin/task/task.ts, packages/cli/src/agent/subagents/BackgroundAgentManager.ts)
• resume 使用源 sidecar 中冻结的模型、权限、工具、系统提示、最大回合和隔离配置，不重新读取同名 agent 的最新定义；修改配置不会改变既有 lineage (packages/cli/src/agent/subagents/AgentSessionStore.ts, packages/cli/src/agent/subagents/BackgroundAgentManager.ts, git:888d608f)
• 子代理访问权按 parent sessionId + canonical projectPath 复合校验；只有相同 session ID 不足以跨 workspace 查询、取消、采纳或恢复 child (packages/cli/src/agent/subagents/AgentSessionStore.ts, packages/cli/src/tools/builtin/task/task.ts)
• 子 Agent 的 blacklist 总会加入 EnterWorktree、ExitWorktree 和 TeamCreate；隔离 worktree 由宿主生命周期创建，teammate 也不能嵌套创建团队 (packages/cli/src/agent/subagents/SubagentExecutor.ts, packages/cli/src/agent/subagents/BackgroundAgentManager.ts)
• 隔离运行只有“成功且无改动、无提交”才自动删除 worktree；失败或任何变更都会保留路径与分支，调用方必须按交付语义处理 (packages/cli/src/agent/subagents/SubagentWorktreeLifecycle.ts)
• 后台完成通知只内联最多 32,000 字符结果和 8,000 字符错误，并明确标为不可信数据；需要完整 durable 结果时才调用 TaskOutput，不能通过高频轮询代替 completion push (packages/cli/src/agent/subagents/BackgroundSubagentCompletion.ts, packages/cli/src/tools/builtin/task/task.ts)
• orphan child 只有在 durable turn 已 turn_completed 且恢复上下文中存在最终 assistant 文本时才恢复为 completed；其他情况记为 interrupted failed 并允许用新 ID resume (packages/cli/src/agent/subagents/BackgroundAgentManager.ts)
• running sidecar 同时保存 PID 和进程启动身份，防止 PID 复用被误判为原 owner 仍存活；旧记录缺身份时采用更保守的兼容窗口 (packages/cli/src/agent/subagents/AgentSessionStore.ts, packages/cli/src/agent/subagents/BackgroundAgentManager.ts)
• 父 transcript 中缺失前台 Task 结果时，只有 child ID、owner、description、显式 type、resume lineage 和终态结果全部匹配才会采纳；后台 child 或 cancelled child 不走该路径 (packages/cli/src/agent/subagents/SubagentResultAdoption.ts, git:103e57b7)
• verification 与 goal-verification 是保留名称，用户、项目和命令行 override 都不能覆盖；普通内置 agent 则允许被后续高优先级来源替换 (packages/cli/src/agent/subagents/SubagentRegistry.ts)

Architecture

• 每个 child 创建独立 SessionRuntime 和 Agent，继承父 Session 冻结的 agent/model/LSP 资源及 Provider admission owner，但使用自己的 session ID、transcript 和取消边界 (packages/cli/src/agent/subagents/SubagentExecutor.ts, packages/cli/src/agent/subagents/BackgroundAgentManager.ts)
• Task 前台和后台路径共享相同 canonical 终态结果构造器；结果 metadata 承载 lineage、验证证据、修改文件与 worktree 信息，避免各表面自行解释 child sidecar (packages/cli/src/agent/subagents/SubagentResultAdoption.ts, packages/cli/src/tools/builtin/task/task.ts)
• 后台 child 先提交 terminal sidecar，再由父 Runtime 校验并写入 client-hidden inbox receipt；父 Agent 在安全边界消费该消息并继续，而不是把后台回调直接拼进当前模型输出 (packages/cli/src/agent/subagents/BackgroundSubagentCompletion.ts, packages/cli/src/agent/Agent.ts, git:aa5060a7)
• Task 工具声明 parallelism: shared 以支持同一模型响应批量委派，但不在流式预启动 allowlist；child 只会在父 tool-call durable identity 建立后启动 (packages/cli/src/tools/builtin/task/task.ts, packages/cli/src/agent/loop/StreamingToolExecutor.ts)
• 子代理 LoopEvent 经 bridge 同时更新本地 progress store 和父 Session Bus；终态事件只发送一次，后台路径随后再触发 durable completion notification (packages/cli/src/tools/builtin/task/task.ts)

Decisions

• 配置覆盖顺序为内置、Claude 用户级、受信 Claude 项目级、Blade 用户级、受信 Blade 项目级，最后是 invocation --agents；项目来源受 Workspace Trust 限制 (packages/cli/src/agent/subagents/SubagentRegistry.ts, packages/cli/src/cli/agents.ts)
• Agent sidecar 使用 schema v2、0600 原子 fsync 写入和 0700 目录；公开投影刻意排除 prompt、消息、配置快照、workspace 与进程身份 (packages/cli/src/agent/subagents/AgentSessionStore.ts)
• 终态 sidecar 缓存上限为 256，淘汰时跳过 running session；这是为了限制长驻 server 内存，同时不丢失活跃 child 的协调状态 (packages/cli/src/agent/subagents/AgentSessionStore.ts, git:8887f958)
• 内置独立验证代理优先使用宿主提供的 JSON Schema verdict，兼容路径也只接受恰好一个固定 verdict 标题；修改文件与成功验证命令由工具 metadata 采集 (packages/cli/src/agent/subagents/builtinVerificationAgent.ts, packages/cli/src/agent/subagents/SubagentExecutor.ts)

Patterns

• fresh Task 必须显式给 subagent_type，resume 可省略并从源运行继承；两者都先生成 canonical subagent_session_id，用于流式、持久化和重启恢复关联 (packages/cli/src/tools/builtin/task/task.ts, packages/cli/src/agent/loop/durableToolIdentity.ts)
• 后台活动最多每秒刷新一次 sidecar 的 lastActiveAt，避免每个 LoopEvent 都写盘；最终消息、统计和 worktree outcome 在终态一次性保存 (packages/cli/src/agent/subagents/BackgroundAgentManager.ts)
• agent 配置的 tools 为空或缺失表示继承全部工具，disallowedTools 始终优先；Claude Code 权限名会先映射到 Blade permission mode (packages/cli/src/agent/subagents/types.ts, packages/cli/src/agent/subagents/SubagentRegistry.ts)

Recovery Semantics

• orphan reconciliation 先取得 child Session lease，再回收该 child 的前后台进程、修复 interrupted turn，并把 child JSONL 与 sidecar 已继承历史按最大首尾重叠合并 (packages/cli/src/agent/subagents/BackgroundAgentManager.ts)
• 后台 completion inbox ID 由 child ID 确定，父 ACK 因而可 exactly-once；同一终态重复通知不会形成不同的父输入身份 (packages/cli/src/agent/subagents/BackgroundSubagentCompletion.ts)
• restart recovery 无法验证 durable history 时写 restartRecovery: failed 并永久禁止该 run 再 resume，但不会把损坏 child 当作成功回接父会话 (packages/cli/src/agent/subagents/BackgroundAgentManager.ts)