feat(acp): RFC-0042 ACP Subagents Protocol Implementation

[Million-mo]

Summary

Implement the ACP Subagents Protocol (RFC-0042) in AgentPool to standardize subagent discovery, delegation, and session hierarchy for external ACP clients.

Changes

Phase 1 — Core Protocol Surface

• ACP Schema Extensions ()

  • Add "subagent" to ToolCallKind Literal
  • Create SubagentRunInfo, SubagentInfo, SubagentCapabilities
  • Add hierarchy fields to SessionInfo (parent_session_id, child_session_ids, depth)
  • Add subagent field to ToolCallStart / ToolCallProgress
  • Add available_subagents to lifecycle responses

• SpawnSessionStart — Add run_mode field (Literal["foreground", "background"])

  • Populated by subagent tools, team, and teamrun

• SessionData Hierarchy — Typed property accessors for parent_tool_call_id and subagent_id

  • Stored in metadata dict (no SQL schema changes)

• ToolKind Sync Guardrail — Cross-definition equality test

Phase 2 — Advanced Features

• Event Converter — Emits ToolCallStart(kind="subagent") for tool_box and inline modes

  • Subagent state management (completion/error cleanup)

• Foreground Cancellation — Propagates to child sessions, background children survive

• Capability Advertisement — Static availableSubagents in all session lifecycle responses

• Delegation Handler — auto/disable/prefer/require policies with capability gating

• SubagentCatalogProvider — Debounced updates (500ms) with cycle detection

• Dynamic Notifications — available_subagents_update emitted after catalog changes

Testing

• 131 tests added/updated across:
  • Schema types (48 tests)
  • Event converter (20 tests + 16 snapshots)
  • Cancellation (13 tests)
  • Capabilities (11 tests)
  • Catalog (20 tests)
  • Delegation (11 tests)
  • Integration (8 tests)

Verification

• All Must Have items implemented (12/12)
• All Must NOT Have guardrails respected (9/9)
• No OpenCode subagent behavior changes
• No new SQL columns
• Cross-protocol regression: clean

Related

• RFC: docs/rfcs/draft/RFC-0042-acp-subagents.md

---

备份迁移自 SRC-PR#43 · 作者 @Leoyzen · 创建于 2026-06-01T10:13:29Z · head=feat/0042 base=develop/agentic
源状态: closed

[Million-mo]

评论 by @Leoyzen 于 2026-06-01T11:40:34Z（备份迁移）

/gemini review

[Million-mo]

评论 by @Leoyzen 于 2026-06-01T14:52:15Z（备份迁移）

All review comments have been addressed in commit b274cb1af. Here's a summary of fixes:

Critical/High Priority:

1. acp_agent.py:266 — Fixed undefined pool variable → self.agent_pool
2. acp_agent.py:576 — Added list() snapshot for dict iteration to prevent concurrent modification errors
3. session.py:662 — Added None guard for self.agent_pool before accessing .nodes
4. session.py:719 — Wrapped each enable_tool in try-except to prevent partial re-enable failures

Medium Priority:
5. subagent_catalog.py:84 — Added None guard for self.pool before accessing .all_agents
6. subagent_catalog.py:139 — Added list() snapshot for notification channels iteration
7. subagent_catalog.py:145 — Added list() snapshot for callbacks iteration

All 77 affected tests pass. Ready for re-review! 🚀

[Million-mo]

评论 by @Leoyzen 于 2026-06-01T14:53:15Z（备份迁移）

/gemini review

[Million-mo]

评论 by @Leoyzen 于 2026-06-05T02:36:48Z（备份迁移）

Rebase Complete: develop/agentic → feat/0042

I've rebased the develop/agentic branch onto feat/0042 and pushed the result. This merges the SessionPool orchestration from develop/agentic with the subagent delegation features from feat/0042.

Changes in this push

Merged capabilities:

• SessionPool-backed session orchestration (from develop/agentic)
• Subagent catalog, delegation policies, and foreground cancellation (from feat/0042)
• ACPProtocolHandler for elicitation via SessionPool
• Unified event converter supporting TurnCompleteUpdate, UsageUpdate, and subagent ToolCallStart

Removed (breaking):

• get_or_create_session_agent() — sessions now managed by SessionPool
• sessions/manager.py — replaced by SessionPool
• Old stream depth/session tests (superseded by SessionPool)

Test results:

• 236 passed (+12 vs baseline), 24 failed (all pre-existing), 3 skipped
• 16 snapshots updated

Known gaps

• SessionData does not yet have parent_tool_call_id/subagent_id fields needed for full subagent hierarchy in SessionPool mode. This is documented and tracked.

The branch is ready for review. 🚀

[Million-mo]

评论 by @Leoyzen 于 2026-06-08T09:54:16Z（备份迁移）

/gemini review

[Million-mo]

评论 by @Leoyzen 于 2026-06-08T10:08:48Z（备份迁移）

/gemini review

[Million-mo]

评论 by @Million-mo 于 2026-07-17T09:50:42Z（备份迁移）

状态分析

此 PR 部分功能已在主分支实现，但核心高级功能尚未实现，且 PR 已严重过期（CONFLICTING，最后更新 2026-07-01）。关闭此 PR 并创建新 Issue 追踪剩余工作。

已在主分支实现的

• "subagent" 加入 ToolCallKind Literal（tool_call.py:40）
• SubagentRunInfo 模型（tool_call.py:48-60）
• subagent 字段加入 ToolCallStart/ToolCallProgress（tool_call.py:84, session_updates.py:319,434）
• run_mode (foreground/background)（tool_call.py:57）
• parent_tool_call_id 跟踪（event_converter.py:148, handler.py:137）
• Event Converter 发 ToolCallStart(kind="subagent")
• 子会话创建与路由（session_manager.py）
• Guardrail 测试（tests/acp/test_meta_guardrails.py）

尚未实现的（需重新评估）

• SubagentInfo / SubagentCapabilities 模型
• SessionInfo 层级字段（parent_session_id, child_session_ids, depth）
• available_subagents 在 lifecycle responses 中
• SubagentCatalogProvider（去抖更新 + 循环检测）
• available_subagents_update 动态通知
• Delegation Handler（auto/disable/prefer/require 策略）
• Foreground cancellation 传播到子会话

结论

Phase 1 schema 层已通过 PR #65 大重构合并入主分支。Phase 2 高级功能需要基于当前架构重新评估实现方案。关闭此 PR，新 Issue 追踪剩余工作。