subagents: 为 Direct Subagent 研究可选的结构化结果合同

[tt-a1i]

一句话结论

OpenPI Workflow child 已支持调用方提供 schema，并用 terminating structured_output 做运行时校验；Direct Subagent 仍只有 finalText。

建议把“可选结构化交付”下沉为共享 child-session boundary 能力，让轻量 delegation 也能请求可验证结果，而不必为了一个 typed result 升级成 Workflow。

固定证据

对比固定在：

• OpenPI main@2a69d3f32994da4123f1312b7fa84ef3d6119be1
• OMP main@7623b960540518bb1291808bbae28332065e9dba

OMP 当前：

• 单个 task item 可声明 outputSchema 和 schemaMode，结果包含验证状态、解析数据和错误：task input/output contract, structured result
• child 通过 hidden yield 提交结果；校验错误会返回精确反馈，并有有界重试/终止边界：yield validation, bounded correction

OpenPI 当前：

• Direct Subagent 的 terminal outcome 与 snapshot 只保存 finalText：direct outcome, snapshot
• subagent_spawn schema 没有 output schema 参数：spawn surface
• Workflow runner 已经有可复用的正确性语义：schema supplied 时注入一次性 terminating tool，缺失提交则 ok:false：workflow structured tool, missing result failure

为什么值得讨论

Direct Subagent 更适合模型自由做简单 fan-out；Workflow 适合需要持久 run、replay、安全 sandbox、分阶段编排的任务。仅仅为了拿到结构化 findings 就要求 Workflow，会把正交的数据合同和更重的 orchestration lifecycle 绑在一起。

可选 schema 能减少父 Agent 对自然语言报告的脆弱解析，尤其适合：

• code review findings：{severity,path,line,summary}
• research evidence：{claim,source,confidence}
• test matrix：{case,status,evidence}
• 多 child 汇聚前的统一数据形状

OpenPI 应保留的优势

• schema 是调用方可选机制，不变成默认工作流；
• parent model 仍决定 fan-out、schema 和综合策略；
• child authority 仍是 parent 与 role allowlist 的 fail-closed intersection；
• 不引入 OMP 的递归 team、全局 hub 或第二套 Session；
• ordinary delegation 无 schema 时保持当前轻量文本路径。

设计方向

优先抽出 Workflow 已有的 terminating structured-result contract，而不是再造另一种协议：

• Direct spawn 可选 output_schema（名称需与现有 OpenPI/ Pi vocabulary 最终统一）；
• child 仅在 schema 存在时得到 terminating tool；
• tool 必须在 child-safe 分类 drift guard 中显式归类；
• parent 同时得到 bounded text projection 与 typed details；完整原始结果按现有 artifact 合同保存；
• schema invalid、child 未提交、validation failed、aborted 必须是不同终态；
• 是否允许纠错重试要有明确上限，不能无限延长 child lifecycle。

非目标

• 不把所有 Direct Subagent 改成 structured-only；
• 不要求 Workflow 迁移到 Direct Subagent；
• 不让 schema 扩大 child tools 或权限；
• 不在 prompt 中假装校验成功；
• 不把任意大 JSON 内联进 parent context。

完成条件

• 先提取 Direct / Workflow 共享的 child result contract，避免两套验证语义
• 明确 absent schema、valid、invalid schema、missing submission、validation failure、abort/cancel 的终态
• structured tool 通过 child boundary drift guard，且只在请求 schema 时存在
• parent projection 有界，完整 artifact 有总字节/depth/node 上限
• 覆盖 background auto-delivery、explicit wait、resume 与 compact display
• 至少用 review/research fan-out 比较文本解析与 typed result 的成功率和 token
• ordinary text-only spawn 的 schema 与 prompt 成本不回退

与现有 Issue 的关系

• 研究 OMP：模型能力 × Harness 脚手架强度的收益曲线 #45：OMP Harness 总调研
• Workflow 大规模结果汇聚：公平 handoff、分层 Report 与动态父会话投影 #90：大规模 Workflow handoff / report 汇聚
• workflows: structured-result artifacts lack an aggregate size cap; node limit does not stop traversal #111：Workflow structured artifact 的聚合大小边界，已关闭
• 本 Issue：Direct Subagent 的轻量可选数据合同，不扩张 Workflow 控制面

[627150795]

I am taking a focused first pass on this issue: define the structured Direct Subagent result contract and boundaries between canonical result, parent projection, and optional schema validation. This pass will be docs/design-only and will not claim the runtime feature is implemented.

[627150795]

I opened #260 (#260) for the focused first pass I claimed here. Scope: docs/design contract for canonical structured Subagent results, parent projections, optional schema validation, partial/failure outcomes, evidence, and bounded delivery. Validation passed: git diff --check, bun run lint, and bun run typecheck. This is intentionally docs-only and does not claim the complete runtime feature is implemented or close this Issue automatically.

[testikun]

我来认领 #155 尚未落地的运行时代码阶段，不重复此前的结构化结果设计文档。

技术方案：为 subagent_spawn 增加可选 output_schema，只在调用方提供 schema 时向 child 注入一次性 terminating structured-result tool；把 Workflow 现有的 schema 校验/边界提取为共享 child-session primitive，明确区分 absent、valid、invalid schema、missing submission、validation failure 与 abort/cancel。父会话继续获得有界文本投影，并为 canonical structured value 使用完整但有 byte/depth/node/string 上限的 artifact；普通 text-only spawn 的 schema/prompt 保持不变。

实现已完成：PR #373

验证结果：

• bun run check 通过；
• Node 22 全量测试 1,248 passed / 1 skipped / 0 failed；
• Vitest 30 passed / 0 failed；
• Workflow 兼容与共享 structured-output 聚焦测试 22 passed / 0 failed。

该范围不修改 UI，因此不适用真实 UI 截图要求。