Subagent Orchestration
Section titled “Subagent Orchestration”本文档记录 OAH subagent 流程的目标形态、当前实现、以及对 Claude Code / opencode 的调研结论。后续 subagent 相关改造以 Claude Code 为主线,opencode 作为产品体验和 session 结构设计参考。
Subagent 应该像一个可追踪、可恢复、可继续沟通的后台任务:
- 主 agent 通过
SubAgent明确启动或继续一个子任务。 - 后台启动应立即返回
async_launched,让主 agent 不再轮询、睡眠或重复做同一件事。 - 子任务完成后,结果以结构化
<task-notification>注入父会话。 - 主 agent 能通过
TaskOutput用task_id显式读取任务状态和输出。 - 子任务输出在 OAH 使用 PostgreSQL 作为事实源;OAP 使用 SQLite 作为本地事实源。
- 子 session / child run / parent run / tool use id 必须能串起来,便于 UI、审计、恢复和后续继续任务。
Claude Code 参考
Section titled “Claude Code 参考”关键参考文件:
references/claude-code-source-code/src/tools/AgentTool/AgentTool.tsxreferences/claude-code-source-code/src/tasks/LocalAgentTask/LocalAgentTask.tsxreferences/claude-code-source-code/src/tools/TaskOutputTool/TaskOutputTool.tsxreferences/claude-code-source-code/src/utils/task/diskOutput.tsreferences/claude-code-source-code/src/query.tsreferences/claude-code-source-code/src/Task.ts
Claude Code 的核心模型:
AgentTool启动 local agent task。- 异步启动结果包含
status: "async_launched"、agentId、description、prompt、outputFile、可选canReadOutputFile。 LocalAgentTaskState是一等内部状态,保存type: "local_agent"、agentId、prompt、selectedAgent、agentType、model、error、result、progress、retrieved、messages、lastReportedToolCount、lastReportedTokenCount、isBackgrounded、pendingMessages、retain、diskLoaded、evictAfter,并继承 task base 里的toolUseId/notified等字段。- local agent 的
outputFile通常是 agent transcript 的 symlink。 - 子任务完成后通过
enqueueAgentNotification()进入 pending notification queue。 - notification XML 包含
<task-id>、可选<tool_use_id>、<output_file>、<status>、<summary>、可选<result>、<usage>、<worktree>。 query.tsdrain pending notification,把它作为后续用户侧输入交给主 loop。- Claude Code 的内部 Message 设计把模型兼容和 UI 呈现分开:task notification 虽然作为用户侧输入进入主 loop,但队列项带有
mode: "task-notification",属于 non-editable notification,不按普通用户输入渲染。 - CLI UI 的
UserAgentNotificationMessage只从 XML 中提取<summary>和<status>,渲染为一条带状态色点的 compact agent notification,而不是 “You” 消息气泡。 - Claude 的 agent finalization 会优先从最终 assistant/result content 提取干净 final text;
TaskOutputTool读取 local agent 时也优先使用agentTask.result,避免把 transcript/tool result 当成最终答案。 TaskOutputTool可按task_id读取任务输出,支持block和timeout,返回<retrieval_status>、<task_id>、<task_type>、<status>、<output>。TaskOutputTool在 Claude Code 中已经提示 deprecated,优先建议直接Readtask output file;但它仍是显式恢复/检查输出的稳定工具。
对 OAH 的结论:
- OAH 应优先模仿 Claude 的 tool call 边界、task state 字段、notification XML 和
TaskOutput语义。 - OAH 不必照搬 disk transcript 作为事实源;在 OAH/OAP 双形态下,DB-first 更符合现有存储架构。
- OAH 刻意不把
.output/output_file暴露给模型。Claude Code 这样做是因为 transcript symlink 是本地事实源;OAH 的事实源是 PG/SQLite,历史会话证明模型看到.output后会倾向直接Read文件并拿到 transcript/过程文本,效果明显变差。因此 OAH 只保留内部outputFilemetadata 和output_ref,模型可见结果走 notification /TaskOutput。 - Claude 的 pending notification queue 已在 OAH 侧补齐为 session-scoped DB queue;后续重点转向 output file/Read 兼容、child session UX 和权限收窄。
opencode 参考
Section titled “opencode 参考”关键参考文件:
references/opencode/packages/opencode/src/tool/task.tsreferences/opencode/packages/opencode/src/session/prompt.tsreferences/opencode/packages/opencode/src/session/index.tsreferences/opencode/packages/opencode/src/cli/cmd/tui/routes/session/index.tsxreferences/opencode/packages/opencode/src/cli/cmd/tui/routes/session/subagent-footer.tsx
opencode 的核心模型:
task工具创建或复用一个parentID指向父 session 的子 session。task_id直接是子 session id,可用于继续同一个 subagent session。- 工具会等待子 session 完成,然后把
<task_result>作为 tool output 返回父会话。 - tool metadata 保存
sessionId和model,TUI 能浏览和切换父子 session。 - 子 agent 的
task/todowrite权限会按 agent permission 进行限制,避免无限递归和能力泄漏。
对 OAH 的结论:
- opencode 的同步返回模型不作为 OAH 主线,因为我们要对齐 Claude 的 async background agent。
- opencode 值得借鉴的是父子 session 关系的清晰暴露、子 session 可浏览、
task_id可继续、metadata 可追踪、以及 subagent 权限收窄。
当前 OAH 实现
Section titled “当前 OAH 实现”当前已落地的行为:
SubAgent支持后台启动,并返回status: async_launched。SubAgent启动结果包含agentId、task_id、run_id、subagent_name、description、output_ref;不再把outputFile/output_file/canReadOutputFile暴露给模型。- tool call 的
toolCallId会作为toolUseId贯穿到 delegated run metadata、agent_tasks记录和<task-notification>。 - 后台子任务完成后会立即在父 session 中生成 user-role
<task-notification>runtime message。 - notification XML 包含
<task-id>、<tool_use_id>、<output_ref>、<status>、<summary>、<result>或<error>;<output_file>仅保留在历史兼容和内部 metadata 中,不进入新模型可见 XML。 - OAH 额外在 notification XML 中包含
<child_run_id>,用于 Web/Inspector 从 task 卡片精确跳转到子 run 时间线。 - notification / TaskOutput 会尽量携带
<usage>,字段包括total_tokens、input_tokens、output_tokens、tool_uses、duration_ms。这些值由 child run 的 run steps 汇总而来。 - 子任务最终结果提取已按 Claude Code 思路收敛:
- 优先使用 child run 中最近的有意义 assistant text。
- 如果最后一条 assistant 只是纯 tool call,会向前回退到最近一条 assistant text。
- 如果 assistant text 明显是过程话术,或 assistant 仍混合工具调用状态,则不把它当最终结果,而是创建一次 delegated output follow-up,让 subagent 只返回最终结果。
- 只有在没有 assistant text 时,才兼容性回退到最后一个 tool result。
- 执行层现在会按当前 agent 的 OAH 内置工具白名单做最终授权;即使模型或 provider 返回了未暴露的
SubAgent/TaskOutput/ native / action / skill tool call,也会在 tool execution 阶段返回tool_not_available_for_agent,不会创建隐藏子任务。 - 外部 MCP/tool server 工具已接入统一运行期追踪:
tool.started/tool.completed/tool.failedevent、tool_callrun step、tool result message metadata、tool call audit record 都会保存sourceType: "tool"。 - 外部 MCP/tool server 工具在实际
execute前会重新检查enabled、include、exclude和toolPrefix;唯一短别名复用同一个 guarded tool definition,不能绕过 allowlist。 - 子任务完成时优先写入 session-scoped pending notification queue:
- memory 使用
InMemoryAgentTaskNotificationRepository。 - OAH / PostgreSQL 使用
agent_task_notifications表。 - OAP / SQLite 使用 workspace 本地
agent_task_notifications表和 JSON payload。
- memory 使用
ModelRunExecutor会在模型调用前 drain 已存在的 pending notifications;模型响应结束后如发现子任务刚完成,也会 drain 并继续同一个 run 的模型 loop。- notification 有两段状态:
- child terminal 时,先创建父 session runtime message,
visibleInTranscript: true、eligibleForModelContext: false、taskNotificationPendingModelDelivery: true,因此 Web 端能立刻看到结果,但主模型不会提前看到 partial sibling result。 - sibling batch ready 且 drain 时,更新同一条 message,标记
taskNotificationConsumedAt、taskNotificationDeliveredToModel: true、taskNotificationPendingModelDelivery: false、eligibleForModelContext: true,再进入 LLM 输入投影。
- child terminal 时,先创建父 session runtime message,
- drain 不再创建第二条 Web/Transcript message,而是更新同一个 runtime message;仅在没有 notification repository 的兼容路径下才直接创建可投喂 message。
- Runtime Message 已按 Claude Code 的内部 Message 设计拆分语义:
role仍表示 provider chat role;task notification 保持role: "user",确保模型以 user-side input 接收。origin: "engine"表示它不是人类输入。mode: "task-notification"对齐 Claude Code 的 queued command mode,后续 UI、队列、投影、历史管理都应优先用它判断。EngineMessage.kind: "task_notification"是 OAH 内部 runtime 语义;旧数据如果只有metadata.taskNotification: true,也会被投影为task_notification。- Web / transcript 展示读取的是 runtime message 流,不读取 LLM 输入 projection;LLM projection 只是同一批 runtime messages 的消费侧过滤,主要通过
eligibleForModelContext控制。 - 外部
createSessionMessage的用户 metadata 会清理runtimeKind、origin、mode、synthetic、taskNotification、delegatedUpdate等保留字段,避免客户端伪造 runtime notification。
agent_tasks是子任务输出事实源:- OAH / PostgreSQL 使用
agent_tasks表。 - OAP / SQLite 使用 workspace 本地
agent_tasks表和 JSON payload。 - tests / embedded 使用 memory repository。
- OAH / PostgreSQL 使用
agent_tasks.task_state保存 Claude-likeLocalAgentTaskStateRecord:type: "local_agent"、agentId、prompt、agentType、model。retrieved、lastReportedToolCount、lastReportedTokenCount、isBackgrounded、pendingMessages、retain、diskLoaded、notified。- OAH 不把这个结构直接发给模型,它用于 runtime 恢复、UI、审计、后续继续任务和更接近 Claude Code 的 task lifecycle。
SubAgent(..., task_id=...)继续一个仍在运行的 child session 时,会按 Claude Code 的pendingMessages思路处理:- 新的 child run 先进入 child session 的 pending run queue,不并发执行同一个 subagent session。
agent_tasks.task_state.pendingMessages记录追加 prompt,便于 UI/审计/恢复知道这不是一个新 worker,而是发给同一个 worker 的后续消息。- 当前 child run terminal 后,session queue dispatch 下一条 queued child run,pending messages 在 terminal task state 中清空。
TaskOutput/Read agent-task://.../output成功读取 terminal task 后会标记task_state.retrieved=true;terminal notification 会标记task_state.notified=true,usage 会同步到lastReportedToolCount/lastReportedTokenCount。TaskOutput已提供 Claude 风格的显式读取能力,支持task_id、block、timeout。- child session 浏览链路已落地:
SessionRepository.listChildrenByParentSessionId()是存储侧统一接口。GET /api/v1/sessions/{sessionId}/children可列出直接子会话。- Web runtime sidebar 使用
parentSessionId构建 session tree,subagent session 不再作为顶层 session 与父 session 并列展示。 - Web conversation 识别
<task-notification>和TaskOutputXML,渲染为 subagent task 卡片,并可直接打开对应 child session。 - Web conversation 对 task notification 使用 Claude Code 风格的 presentation 分流:后端仍保存 user-role synthetic message 以保持模型输入兼容,但 UI 会优先根据
mode: "task-notification",并兼容metadata.taskNotification/<task-notification>,把它渲染为 compact runtime notification,不显示为右侧 “You” 气泡。 - service-routed PostgreSQL registry 已同步
parent_session_id,并在启动迁移时从sessions.parent_session_id回填历史 registry 行,保证 Web 工作区 session 列表能拿到父子关系。
仍保留的差异:
- Claude Code 的 pending queue 是进程内 task state 结构;OAH 为了支持 OAH/OAP 恢复与审计,将 pending queue 持久化到 PG / SQLite / memory repository。
- 如果父 run 已经 terminal,OAH 会把同一父 run 创建的 pending task notifications coalesce 到一个
taskNotificationContinuationrun,再让主 agent 一次性看见 sibling subagents 的完成结果;Claude Code 主路径是 queued command drain,不创建单独 notification run。 - OAH 新模型可见消息不再包含
output_file;历史output_file仍可被 Web 解析,内部 metadata 仍可用于调试。Claude 的 transcript symlink 事实源不适合直接照搬到 OAH/OAP。 - OAH 还没有
<worktree>输出。 - OAH 已提供 API 级 child session 浏览;UI/TUI 级父子 session 切换体验仍待完善。
- OAH 已有执行层内置工具授权 guard,并已为 MCP/tool server 工具补齐统一 run step / event / audit 记录和执行期 allowlist guard。
sequenceDiagram participant Main as Main agent run participant Tool as SubAgent tool participant Child as Child session/run participant Store as Agent task store participant Queue as Pending notification queue
Main->>Tool: SubAgent(description, prompt, run_in_background) Tool->>Child: create/reuse child session and child run Tool->>Store: upsert task record with toolUseId/outputRef/internal outputFile/taskState Tool-->>Main: status=async_launched, task_id, output_ref Child-->>Store: finalText/error/status Child-->>Queue: enqueue task-notification Child-->>Main: persist visible runtime notification Queue-->>Main: mark same notification model-eligible when batch drains Main->>Store: optional TaskOutput(task_id)Phase 1: Claude tool boundary
Section titled “Phase 1: Claude tool boundary”已完成:
SubAgent后台启动返回async_launched。- 透传
toolUseId。 - notification XML 增加
<tool_use_id>。 agent_tasks在 PG / SQLite / memory 中落地。- 新增
TaskOutput。 - 模型可见
SubAgent/<task-notification>/TaskOutput输出移除output_file,避免模型被引导读取 transcript 文件。
Phase 2: Pending Notification Queue
Section titled “Phase 2: Pending Notification Queue”已完成:
- 新增
AgentTaskNotificationRecord和AgentTaskNotificationRepository。 - pending notification record 将
toolUseId作为一等字段保存,便于和原始SubAgenttool call 对齐。 - memory / PG / SQLite 分别实现 pending notification repository。
- 子任务完成时,如果父 run 仍 active,优先 enqueue notification payload,并立即创建父 session 中可见但暂不进入模型上下文的 runtime message。
ModelRunExecutor在模型输入前 drain 当前 session 的 pending notifications,并把它们作为 synthetic user messages 加入allMessages。- 模型响应结束后如果刚好有子任务完成,会 drain notification 并继续同一个 run 的模型 loop,让主 agent 看到子任务结果后继续思考。
- drain 后更新同一条 message 的 metadata,使其进入模型上下文,更新 consumed 状态,并发布现有
message.completed兼容事件。 - 父 run terminal 后不再为每个 child completion 单独续跑;同一父 run 的 sibling child notifications 会等全部 terminal 后 coalesce 为一个
taskNotificationContinuationrun。 - 保留 fallback notification run,仅在没有 notification repository 时启用。
Phase 2.5: Claude-like Task Lifecycle
Section titled “Phase 2.5: Claude-like Task Lifecycle”已部分完成:
agent_tasks.task_state从静态 metadata 扩展为 lifecycle state。- 子任务启动时记录
isBackgrounded、prompt、agentType、model。 - 子任务 terminal 后记录
notified、evictAfter、token/tool count,并清空pendingMessages。 TaskOutput成功读取 terminal task 后记录retrieved=true。- 运行中的 subagent 收到
SubAgent(task_id=...)追加消息时,child run 进入 child session queue,pendingMessages记录待处理 prompt。
后续可选:
- Web 端用
pendingMessages显示“已给 subagent 排队的后续指令”。 retain/diskLoaded目前主要是为 child session UI 和 transcript bootstrap 预留,后续可在打开 subagent panel 时赋予真实行为。
Phase 3: Output File / Read Compatibility
Section titled “Phase 3: Output File / Read Compatibility”已完成但有 OAH 特化取舍:
- 保持 DB-first,不把
.output/output_file作为模型可见事实源。 Read支持agent-task://<taskId>/output,并从agent_tasks读取当前状态/输出。Read支持历史output_file兼容路径,但新SubAgent/<task-notification>不再返回该路径。- 读取结果复用
TaskOutput的 XML 结构,包含<retrieval_status>、<task_id>、<task_type>、<status>、<output_ref>、<output>/<error>。 TaskOutput的 tool prompt 明确建议等待 notification;只有显式检查/恢复 missed output 时才用TaskOutput或agent-task://<taskId>/output。
后续可选:
- OAH/OAP 可以物化
.openharness/state/tasks/<taskId>.output作为调试缓存,但不要把路径放进模型默认输出;事实源仍是 PG/SQLite。
Phase 4: Session UX
Section titled “Phase 4: Session UX”已部分完成:
- API 暴露 parent session 的直接 child sessions:
GET /api/v1/sessions/{sessionId}/children。 SessionRepository增加listChildrenByParentSessionId(),memory / PostgreSQL / SQLite / service-routed storage 均已接入。- CLI API client 增加
listChildSessions(parentSessionId),便于 TUI 后续接入。 - Web runtime sidebar 已按
parentSessionId渲染 session tree:- 顶层列表只显示没有
parentSessionId的主 session。 - 子 session 作为父 session 的下一层显示,并带有 subagent 图标和 tooltip 标识。
- 当前选中的子 session 会自动展开它的祖先 session。
- 删除父 session 时会沿本地 session tree 一起移除已知子 session。
- 顶层列表只显示没有
- Web conversation 已识别 subagent task 输出:
<task-notification>不再只作为普通 XML 文本显示,而是展示状态、summary、result/error、child_run_id、output_ref、usage和 task lifecycle 徽标;历史output_file只做兼容解析,不再作为新 UI 主信息展示。TaskOutput/Read agent-task://.../output返回的<retrieval_status>XML 也会展示为同一类 task 卡片,并携带child_session_id/child_run_id/usage/task_state。- 卡片中的
task_id在 OAH 中等于 child session id,因此可以直接打开 child session。 - 如果 task 卡片带有
child_run_id,可以直接打开 Inspector 的 run 时间线。
- service-routed PostgreSQL 的
session_registry已持久化和回填parent_session_id,避免通过 workspace session list 同步到 Web 时丢失父子关系。
后续目标:
- Web/TUI 能像 opencode 一样查看 subagent session。
task_id继续同一个 child session 的行为在 UI 上可见。- UI 可显示 queued pending message 数量和 retrieved/notified/background/token/tool 状态,但不展示 pending prompt 原文。
- notification 和 TaskOutput 都已能跳转到 child session 和 child run。
Phase 5: Permissions and Safety
Section titled “Phase 5: Permissions and Safety”已部分完成:
- 将“模型侧可见工具”和“执行侧可运行工具”拆成两条边界:
activeToolNamesForAgent()保留模型请求/AI SDK active tools 的语义。visibleEngineToolNamesForAgent()只计算 OAH 内置工具白名单,用于执行期最终授权。isToolVisibleToAgent()只基于visibleEngineToolNamesForAgent(),不再因为 agent 有 enabled external tool server 就放行所有内置工具。
ToolExecutionService在 before-tool hooks 和 run step 创建之前检查工具可用性;未授权工具直接抛出tool_not_available_for_agent。- subagent mode 默认不能继续调用
SubAgent/TaskOutput,即使配置里误填了subagents,也会被canDelegateFromAgent()和执行层 guard 拦住。 - 已增加 focused tests:
- subagent 试图调用 nested
SubAgent时,只生成 failed tool result,不创建孙级 child session。 - agent 有 enabled external tool server 时,仍不能执行未授权的 OAH 内置
SubAgent。 - 外部工具成功时生成
tool.started/tool.completed、completedtool_callstep、tool result metadata 和 audit record。 - 外部工具失败时生成
tool.failed、failedtool_callstep、failed tool result message 和 audit record。 - MCP 工具
include/exclude在 prepare 后被篡改时,prefixed 名称和唯一短别名都会在执行期被拦截。
- subagent 试图调用 nested
后续目标:
- 借鉴 opencode,对 subagent 可用 native/action/skill/MCP 能力继续收窄和显式化。
- 增加 max concurrent subagents、max depth、task timeout、output size cap。
Phase 6: Parallelism and Worker Affinity
Section titled “Phase 6: Parallelism and Worker Affinity”已部分完成:
- 现场会话
ses_380876322f5a4233b5fe7145b4e1a4b9证明:一次父 run 可以正确创建多个 background subagents,delegatedRuns中会记录全部 child run。 - 该会话的问题不在
SubAgenttool call 创建阶段,而在 Redis worker 调度阶段:- child run 都带 workspace placement / preferred-worker affinity。
- 当 owner runtime 只有少量本地 slot 时,父 run 与先启动的 child run 会占满本地 slot。
- 其他 runtime 即使有 idle worker,也不能 claim 该 workspace 的 preferred run。
- 旧 worker-pool sizing 会用 remote idle worker 抵扣本地扩容需求,导致 preferred subagent backlog 没有及时扩出 owner-local slot。
- Redis scheduling pressure 增加 affinity 维度:
preferredReadySessionCountpreferredReadyQueueDepthpreferredSubagentReadySessionCountpreferredSubagentReadyQueueDepth
- worker pool sizing 对 preferred backlog 使用 local busy / local active 计算,不再让 remote idle worker 满足 owner-local backlog。
- health contract / worker pool snapshot / recent decisions / Web Storage 面板均展示 preferred pressure,便于诊断“看起来有 idle worker,但某 workspace 的 subagent 仍排队”的情况。
- 已增加 focused regression test:remote idle workers 不应抵消 local owner 的 preferred subagent backlog。
- 现场会话
ses_380876322f5a4233b5fe7145b4e1a4b9的TaskOutput/Read output_file失败根因:- Docker OAH 使用 service-routed PostgreSQL persistence。
createPostgresRuntimePersistence()已提供agentTaskRepository/agentTaskNotificationRepository,但createServiceRoutedPostgresRuntimePersistence()曾经没有对外暴露和路由这两个 repository。- Engine 因此认为 task output storage 未配置,
TaskOutput和 DB-backedRead output_file都返回agent_task_output_unavailable。 - 失败不是因为
task_id错误;该会话里的task_id就是 child session id,符合 Claude/opencode 风格。
- service-routed PostgreSQL 现在会把
agent_tasks按 workspace service 路由到 service DB,把 pending task notifications 按 parent session 路由到对应 DB。 - 为历史缺失
agent_tasks的会话增加了 recovery:TaskOutput找不到 task row 时,会从 child session、child run、parent rundelegatedRunsmetadata 和 child messages 恢复 task 记录,并在 child run 已 terminal 时回填 final output。 - 现场会话
ses_2042339fcc864d7a964a7207f62d20cb暴露了两个细节:- sibling subagents 的 notification 可以等全部 terminal 后再 coalesce 给父 agent,但注入父会话的 runtime message
createdAt必须保留各自 child completion time;drain/consume 时间只放入 metadata,避免 Web conversation 看起来所有 subagent 都在最后一刻返回。 - subagent final output 不能用最后一个成功 tool result 兜底。成功的
WebFetch/Bashresult 只是过程证据,不是 delegated final answer;如果没有可用 assistant final text,应发 delegated output follow-up 让 subagent 综合已有工作输出最终结果。失败 tool result 仍可作为错误诊断兜底,例如 nestedSubAgent被执行期 guard 拦截。
- sibling subagents 的 notification 可以等全部 terminal 后再 coalesce 给父 agent,但注入父会话的 runtime message
后续目标:
- 对照 Claude Code 的 Task 行为,继续优化“多个 background subagents 同组完成后的主 agent 唤醒策略”:
- 当前机制仍可能在第一个 child terminal 后先产生一次父会话续跑。
- 更接近 Claude 的体验是 notification 先沉淀为 runtime message / queued command,主 agent 在合适时机批量读取,而不是每个 child 完成立刻打断式续跑。
- 为 subagent run 增加更清晰的 timeout / stuck diagnostics,尤其是长时间
waiting_tool的 WebFetch / model step。 - 对 worker pool 做 workspace-affinity-aware 的调度指标,不只统计 preferred backlog 总量,还能按 owner runtime / workspace 聚合。
- Claude Code 是主行为目标;opencode 只作为产品结构和 session UX 参考。
- 优先稳定 tool call 边界,再改调度和 UI。
- 任何 notification 迁移都必须防止重复消费。
- OAH / OAP 的事实源分别是 PG / SQLite,不把 transcript 文件作为唯一事实源。
- XML 字段尽量与 Claude 保持一致;OAH-only 字段要有明确兼容理由。