子代理默认使用 expert 模式，由父代理委派专家，子代理不再委派。swarm 模式允许成员继续委派，并按会话发送消息。两种模式共用以下专家角色、模型路由与路径权限。启用方式见子代理配置。
子代理委派通过 Agent 的专用工具进入任务池 SubagentPool。系统内置了六个可供委派的专家角色：
| 专家名称 | 对应工具 | 核心用途 | 是否允许写入 |
|---|---|---|---|
explorer |
agent__explore |
聚焦只读代码库探索 | 否 |
fixer |
agent__fixer |
限定范围的实现与代码修复 | 是 |
oracle |
agent__oracle |
根因分析、风险审查与验证建议 | 否 |
designer |
agent__designer |
方案设计、接口梳理与交互决策 | 否 |
librarian |
agent__librarian |
资料整理、代码检索与上下文归档 | 否 |
general |
agent__general |
限定范围的通用任务与文件修改 | 是 |
reviewer 是权限审查专家，historian 是内部历史整理专家。两者可配置独立模型，属于系统内部专家，不对外提供委派工具。reviewer 输出包含 execute、ask_user 和 refuse 的结构化判定。判定为 ask_user 时，系统先退回请求方补充说明。仍不明确时，系统弹出人工审批。审查失败、缺少凭据或输出异常时，系统直接拒绝。单次运行模式（如 --print）遇人工审批直接返回失败。expert 模式的子代理禁止递归委派。historian 的运行机制参见历史整理与证据恢复。
任务池提供以下管理工具：
agent__jobs：列出主会话日志记录与活动任务池中的所有任务；agent__status：查询指定任务的实时运行状态或归档记录；agent__wait：等待指定的活动后台任务完成并获取最终结果；agent__cancel：向运行中的任务发送取消请求；agent__send：向同树成员或根会话发送消息（仅限 swarm 模式）。
swarm 沿用六个可委派角色。agent__jobs 返回根会话和所有深度成员的最新状态，不包含对话。agent__status 接受 session_id 查询最新状态，或接受 run_id 查询某次执行，两者互斥。
成员的 child_session_id、角色和根树内的 pool_ordinal 保持稳定。恢复或接管生成新的 run_id。发送消息使用 session_id，成员填写子会话 ID，主脑填写根会话 ID。池序号仅供展示，主脑没有子会话 ID 或池序号。
同树成员与主脑使用 agent__send 发送消息。
{"session_id":"目标会话 ID","message":"补充任务或协作信息"}消息进入目标会话的有界先进先出队列。accepted: true 只表示已入队，不表示已持久化或处理完成。未知或跨树目标、已取消或正在停止的会话、满队列、空正文及超大正文会在入队前拒绝。
消息不打断当前模型请求或工具执行。目标在回合边界取出消息，写入一次 user 消息并开启独立回合。已结束的成员可由消息启动新 run，继续使用原有子会话的已处理历史、角色、路由与路径范围，并重新申请路径锁。成员在 run 之间不常驻。
待处理队列只保存在当前进程中，正常 run 交接保留队列，崩溃后不重放。已处理的 user 消息写入 transcript，供恢复与归档使用。启动、记录或执行失败通过 error/lifecycle 反馈，入队回执不保证消息恰好处理一次。
同树消息与跨实例消息使用两套通道。agent__send 面向同一 swarm 树，按 session_id 寻址成员或根会话。peer__send 面向本机独立的 letcode 主会话，按 peer__discover 返回的实例地址发送文本，不经过 swarm 队列。
根深度为 0，max_depth 包含上限。所有分支共享 max_concurrent 个子代理并发名额，主脑不占名额。启动预约、运行中的 run 和消息恢复预约均占一个名额。完成、失败、取消、超时或启动失败后释放名额，历史身份和序号继续保留。
新成员、接管和消息唤醒都须取得名额。满额时明确拒绝启动，不自动排队。给正在执行或已预约恢复的目标发送消息，仍按该目标的待处理队列容量接纳。
后代权限只能收窄父代理授权。只读成员可查询名册、发送消息并委派只读工作，不能委派可写工作。fixer 与 general 仍须声明非空 owned_paths。路径锁包含祖先，重叠读写或写写请求直接拒绝。等待、取消与接管限于调用者管理的 run 及后代，同树可见性不扩大控制权限。
每次 swarm 子 run 使用有限超时，依次取请求、专家模板或 run_timeout_secs。期限从激活时计算，消息与回合交接不延长本次 run。超时使待处理消息失败，后续显式发送可启动新 run 并取得新期限。expert 保持原超时解析，不套用 swarm 默认值。
显式取消或中断先关闭相关子树的新任务与消息恢复，再通知后代停止；结束或切换根会话覆盖整树。受管理的终态不保证外部进程停止、副作用撤销或持续互发消息的全局终止。
新根会话记录一次配置快照。恢复保留原树上限、亲缘与历史成员，按当前执行状态申请并发名额；配置重载只影响后续新根会话。旧记录中的 max_descendants 数值按并发上限读取。旧记录缺少 swarm 元信息时按 expert 恢复，swarm 恢复信息缺失或损坏时报错。
规范化的委派请求必须包含 task 或 objective，系统优先采纳 objective。请求还可指定成功标准 success_criteria、允许路径 allowed_paths、禁止路径 forbidden_paths、独占所有权路径 owned_paths、模型路由 model、目标子会话 ID target_child_session_id 和后台运行标志 background。
model 与 target_child_session_id 互斥。委派 fixer 或 general 时必须提供非空的 owned_paths，用于申请独占写锁。三类路径范围均可声明尚不存在的文件或目录。超时时间、工具预算、作用域、权限模式、写入权限和返回结构由专家模板约束，模型不能在 Prompt 中自行扩大权限。
子代理系统提示由父会话前置指令、专家角色设定、通用委派约定与结构化报告契约组成。任务目标、验收条件、路径范围、单次模型路由、接管目标与执行边界通过委派任务提示传递。只读工具受允许路径与所有权路径约束；结构化文件写入工具严格限制在所有权路径内；禁止路径的优先级最高，覆盖其他所有范围。
任务池在规范化路径根节点上管理并发锁：只读任务之间支持并发；读写或写写任务在路径重叠、属于父子目录关系时会被判定为冲突并拒绝执行。任务结束时，任务池核对子代理日志中实际变更的文件列表；超出路径锁范围的修改会导致任务判定为逻辑失败。
每个子代理任务在启动前均独立解析并准备专属的模型路由。专家路由始终由当前配置决定，不存在会话级覆盖；路由安装后，子代理直接使用已解析路由发起请求。
委派工具的 model 参数说明列出该专家允许的完整 provider/model 路由，随专家配置更新。allowed_models 为空时，不接受显式模型覆盖，省略 model 或传入 null 使用默认路由。
子代理路由解析遵循以下规则：
allowed_models非空时取第一项作为专家默认路由；否则使用专家配置中的provider与model；再否则回落到配置中的新会话默认模型（active_provider与其default_model）；- 单次
agent__*委派传入model时，必须命中该专家的allowed_models白名单； - 子代理的上下文压缩及其他单次请求沿用当前子代理路由，不另选路由；
- 接管子会话时沿用子会话记录的路由；该路由已不可用时拒绝接管，并提示调用方新开子会话；
- 子代理各工具的权限边界相互独立，执行身份归属于该子代理的权威路由；
- 专家在
[agents.<expert>]声明的reasoning_effort在创建子代理时应用；该专家解析到的模型不支持所写档位时，委派直接失败并给出可用档位； - 子代理创建时继承父代理的 Fast Mode 开关状态，随后各自维护。子代理自动关闭 Fast Mode 不影响父会话，父会话后续切换也不影响已启动的子代理。
通过 SubagentPool::start_named_governed 可以启动子代理任务。处理流程如下：
- 匹配目标专家模板；
- 规范化输入参数，计算路径访问范围、超时时间、工具配额与执行路由；
- 申请路径锁预约，分配稳定的
run_id与单调递增的任务序号； - 创建子会话日志文件，依次写入会话启动记录、运行状态、子代理启动事件和委派输入；
- 创建子 Agent 实例，注入路由、路径作用域与子日志上下文；
- 在父会话日志中记录对应的启动事件；
- 激活执行槽位与取消通道，开始执行子代理提示词。
激活的槽位同时覆盖预约阶段和执行阶段，尚未完成初始化的任务同样可以被取消。
指定 target_child_session_id 可以接管已终止的子会话继续工作。接管必须满足以下条件：
- 目标子会话归属于当前父会话；
- 目标子会话日志完整可读；
- 日志中记录的专家名称与本次调用的专家模板完全一致；
- 子会话当前处于终止状态（完成、失败、配额耗尽、取消或超时）；
- 日志中记录了可解析的服务商与模型路由；
- 没有其他活跃任务正在接管同一个子会话。
接管模式不接受外部覆盖模型，子会话继续使用它自己记录的路由。该路由已不可用时拒绝接管，并提示调用方新开子会话。
接管成功后，系统会在原日志末尾追加新的运行记录，继承原有的回合历史与上下文分支，沿用原任务序号并生成新的运行 ID。正在运行的子会话、损坏的日志文件或专家类型不匹配均会导致接管被直接拒绝。
任务池依次经历资源预约、活跃执行、终态处理与归档查询四个阶段。终态状态包括已完成（completed）、执行失败（failed）、配额耗尽（budget_exhausted）、已取消（cancelled）与超时（timed_out）。工具调用超限映射为配额耗尽，执行异常映射为失败。
终态处理阶段会核对实际文件修改范围，写入完成状态与汇总结果，并将执行槽位转移到已完成任务表中。任务在异常中断时释放守卫，系统会自动生成取消总结；正常完成时由守卫持久化最终结果并唤醒等待任务。
前台委派调用会等待任务终态，并在工具结果中返回运行标识、专家名称、完成状态、摘要、结构化结果与活动标记（active: false）。
后台委派需要父级提供后台执行与结果接收能力。任务派发后立即返回运行中状态（status: running）与后台标记（background: true）。根会话通过 BackgroundSubagentCompleted 事件接收直接子任务结果。swarm 成员使用自己的完成队列，在内部续跑边界接收后台后代结果。
agent__wait 仅等待活跃任务，同一任务只允许单个前台工具认领。expert 模式下，agent__status 优先查询已完成缓存，其次查询活动任务，最后回退读取子会话日志。agent__jobs 按序号汇总所有任务并覆盖当前状态。swarm 模式使用根树名册查询最新状态，并保留按 run_id 查询历史执行的能力。agent__cancel 向运行中任务发送取消信号，传入无效 ID 时直接报错。
子代理在日志中记录以下关键事件：
SubagentStarted：记录运行标识、父子会话关联、专家名称、任务摘要与序号；SubagentDelegation：写入子会话日志，记录本次委派的输入契约，子会话视图据此渲染委派卡片；SubagentLifecycle：记录状态变更与详细说明；SubagentResult：记录最终状态与产出结果。
完成的结构化数据可作为父会话的审计证据，完整保留执行来源。父日志记录任务调度关系，子日志保存具体的交互与工具调用。任务看板可通过两套日志完整还原执行轨迹。
结构化产出统一包含执行发现、读取文件、修改文件、执行命令、验证结果、阻碍因素和后续建议，便于父级 Agent 理解与汇总。
模型报告使用与 Historian 相同的自定义标签子集，由宿主直接解析，不做额外的模型改写。工具结果、结构化证据和日志仍使用 JSON，旧 JSON 报告保持可读。
报告包在 <subagent_report> 内，<status> 和 <summary> 各写一次。列表项使用重复的 <finding>、<file_read>、<file_changed>、<command_run>、<validation>、<blocker> 和 <next_step>，空列表省略对应标签。
<subagent_report>
<status>completed</status>
<summary>完成局部修复</summary>
<finding>核实了 Vec<T> & ready 的处理</finding>
<file_changed>src/main.rs</file_changed>
<validation>cargo test passed</validation>
</subagent_report>
这套语法只识别固定的开闭标签，不支持属性、嵌套、自闭合标签或实体解码。字段正文原样保留，无需转义；正文中的完整契约标签仍会被识别为分隔符。字段值读到最近的同名闭标签、下一个契约开标签或报告末尾。标量取第一次出现的值，列表按出现顺序收集。缺少有效的状态或摘要时，结果标记为 malformed 并保留原文摘录。
src/agent/catalog.rs：定义专家模板、子代理能力契约与目录信息。src/tool/delegation.rs：实现委派输入规范化、路径作用域检查与工具模式。src/subagent/route_factory.rs：负责子代理路由准备、模型白名单、专家设置与接管校验。src/subagent/pool.rs：管理任务池预约、并发路径锁、会话接管、生命周期与等待取消。src/subagent/swarm.rs：从 transcript 重建根树名册与历史 run。src/subagent/messaging.rs：管理消息队列、成员恢复与子树停止。src/subagent/result.rs：处理任务摘要、结构化结果组装与终态映射。src/session/subagent_delegate.rs：集成会话级路由展示、后台控制通道与父子交互。src/transcript/recorder.rs：持久化子代理启动、状态变迁与执行结果。