subagent-delegation 是一份规范（Canonical Protocol），用于把 GSD 工作委派给 Antigravity 原生子代理。资料将其定位为 GSD 的核心机制而非可选优化：PROJECT_RULES.md 中的质量阈值依赖委派才能实现；一个为规划阶段读取二十个文件的编排器，已经花掉了该阶段所需的上下文。
用途与前置条件
原生子代理需要 Antigravity 2.0 或更高版本，通过 invoke_subagent 调用。能力检测方式是查看该工具是否在可用工具列表中，不要通过实际调用来探测——失败调用会浪费一轮对话并让用户困惑。若该工具可用，按协议委派；不可用则走内联降级。资料明确：普通子代理不受计划门槛限制，仅多代理团队协作（/teamwork-preview、Agent Teams）属 Ultra 独占，GSD 从不使用它；因此若委派不可用，原因是 IDE 版本而非订阅。
可委派的工作
资料给出映射关系：执行 PLAN.md 交给 gsd-executor，每个计划一个干净上下文是 GSD 的核心承诺；为某阶段编写计划交给 gsd-planner，因为计划编写需阅读规格、路线图与研究；验证阶段交给 gsd-verifier，独立性要求一个从未看过该工作的上下文；代码库映射与研究交给 gsd-researcher，探索是单项最大的上下文开销；排查缺陷交给 gsd-debugger，受污染的上下文会重复自己失败的假设。编排器保留：参数解析、文件存在性检查、波次分组、读取子代理的紧凑结果、更新 STATE.md 与 ROADMAP.md、与用户交流。其余工作均可委派；存疑时倾向委派——多一个子代理的成本是 token，编排器上下文被污染的成本是本次会话的剩余部分。
调用方式
调用 invoke_subagent，以子代理在 .agents/agents/*.md 定义中的名称定位它；具体参数模式由 IDE 提供，需遵循。本协议约束的是提示词内容而非传输格式。子代理不继承对话历史，从空白开始；未写入其提示词的内容对它不存在。每次调用提示词必须包含：目标子代理在其 Invocation Contract 表中声明的契约字段；路径而非内容（如 .gsd/phases/2/1-PLAN.md，绝不粘贴计划正文）；来自 STATE.md 的约束（已作出的决定、已知阻塞）；返回契约，重申只要紧凑块。禁止把文件内容粘贴进子代理提示词——它能自行读取，粘贴会加倍 token 成本，并在内容变动时与磁盘脱节。
工具授权
子代理定义中的 tools: 默认为空列表，不继承父级工具集。省略 tools: 的子代理无法写文件，会一直探索到最后才发现无法产出产物，因此 .agents/agents/ 中每个定义都显式声明工具。资料列出需求与工具对应：读取与搜索用 view_file、list_dir、find_by_name、grep_search；写产物用 write_to_file、replace_file_content、multi_replace_file_content；提交、测试、验证命令用 run_command；外部研究用 search_web、read_url_content；返回父级用 send_message。工具名必须逐一照抄；未映射或拼错的名称会让子代理挂起而非失败，这是最糟的失败模式，因为它看起来像在慢速工作。scripts/validate-agents.ps1/.sh 强制两条规则：tools: 必须存在且非空；每个声明名称必须存在于上表注册表中。
工作区隔离
三种模式：inherit 用于顺序工作，同一时间只有一个子代理接触工作区；branch 用于两个及以上子代理并发写文件（隔离的 git worktree）；share 用于只读的并发工作，如研究、映射、验证。波次映射规则：单计划的波次用 inherit；多计划的波次用 branch，每个计划一个 worktree，波次完成后合并。并发写者共享工作区会互相破坏提交，这不是理论风险。
结果处理
子代理返回其紧凑块，只有该块进入编排器上下文。不要为确认而重读子代理写的产物；若之后需要其内容，到时再读。不要向用户完整复述摘要，只报告状态、路径和必须由用户决定的一件事。按状态路由：blocked、checkpoint、needs_input、escalate、fail 在调用工作流中各有既定下一步，需遵循。死掉的子代理不等于完成的子代理：若子代理无返回或死亡，报告为失败并停止，不要静默地改为内联重做——那正是委派要防止的上下文膨胀。若子代理返回的是文件内容，无论听起来多完整都应视为失败：契约是路径，负载意味着产物从未落到磁盘；应视为 blocked，查明它缺少哪项能力并修正定义，不要把内容继续粘贴下去，否则委派只花了 token 而毫无所得。嵌套深度上限为 10 层，GSD 从不需要超过 2 层（编排器到子代理）；想要再委派的子代理应返回 needs_input。
内联降级
在 Antigravity 1.x 上不存在 invoke_subagent，工作流仍以降级模式运行：编排器在自己的上下文中完成工作。降级时应在开始时告知用户一次，提示子代理委派不可用（需 Antigravity 2.0+）、正在内联运行、上下文会更快填满，并建议每个会话只跑一个计划、计划之间用 /pause。降级模式纪律：每次调用只执行一个计划，绝不同时跑整个波次；每个计划后 /pause，让用户在新会话中 /resume；关注 skills/context-health-monitor 阈值，到 70% 即停止。不要静默假装在委派——该协议要修复的失败正是工作流描述了从不生成的子代理。