RFC-0027: ACP Subagent Zed 兼容性¶

概述¶

本 RFC 提出 AgentPool ACP Server 与 Zed 编辑器 subagent UI 的兼容性改造方案。当前 AgentPool 的 ACP Server 虽然已实现三种 subagent 展示模式（legacy/inline/tool_box），但所有模式均未填充 ACP 协议中的 _meta 扩展字段，导致 Zed 编辑器无法检测和渲染 subagent 面板 UI。Zed 的 subagent 功能已正式 GA（2026-02-27，PR #50493），其 subagent UI 完全依赖于 ToolCallStart/ToolCallProgress 事件中的 _meta.subagent_session_info 字段。

本 RFC 识别了 5 个关键差距（GAP），其中 GAP 1 为 P0 阻塞性问题，并提出 3 个方案选项，通过 4 阶段实施计划（Phase 0-3）逐步实现完整的 Zed subagent 兼容性。

预期结果：Zed 编辑器能够正确检测 AgentPool 的 subagent 工具调用，渲染展开/折叠卡片 UI，并独立管理子会话的生命周期。

背景与上下文¶

当前系统状态¶

AgentPool ACP Server 实现了完整的 ACP v1 协议，包括 initialize、session/new、session/prompt、session/resume、session/fork、session/close、session/list 等方法。对于 subagent 场景，Server 提供了三种展示模式：

⚠️ 重要变更（Phase 1）：当 display_mode == "zed" 时，SpawnSessionStart 处理产出带 _meta（subagent_session_info + tool_name）的 ToolCallStart。inline/tool_box/legacy 模式下 SpawnSessionStart 行为不变（AgentMessageChunk，无 _meta）。子级 ToolCallStart/ToolCallProgress 在所有模式下均不携带 _meta。

重要变更（Phase 2）：当 display_mode == "zed" 时，SubAgentEvent 事件路由到子 ACP session。其他 display_mode 下行为不变。

相关工作¶

现有基础设施¶

AgentPool 核心层已具备子会话管理基础，Phase 2 应桥接而非重建：

Phase 2 的 ACPSessionManager 应委托核心 SessionManager.create_child_session() 管理子会话生命周期，而非在 ACP 层重新实现。

术语表¶

Zed Subagent 实现方式¶

Zed 的 subagent 不是 ACP 协议的标准特性，而是通过 _meta 扩展机制实现：

// Zed: crates/acp_thread/src/acp_thread.rs:69-70
pub const SUBAGENT_SESSION_INFO_META_KEY: &str = "subagent_session_info";
pub const TOOL_NAME_META_KEY: &str = "tool_name";

// Zed: crates/agent/src/tools/spawn_agent_tool.rs:155-168
// spawn 时：创建 SubagentSessionInfo 并写入 _meta
let session_info = SubagentSessionInfo {
    session_id: subagent.id(),
    message_start_index: subagent.num_entries(cx),  // 当前条目数（非硬编码 0）
    message_end_index: None,  // spawn 时未知，后续更新
};
event_stream.update_fields_with_meta(
    acp::ToolCallUpdateFields::new(),
    Some(acp::Meta::from_iter([(
        SUBAGENT_SESSION_INFO_META_KEY.into(),
        serde_json::json!(&session_info),  // ← JSON Object, NOT string
    )])),
);

// 完成时：更新 message_end_index
session_info.message_end_index =
    cx.update(|cx| Some(subagent.num_entries(cx).saturating_sub(1)));
// ⚠️ saturating_sub(1)：0-based index，非 count

Zed 客户端通过 subagent_session_info_from_meta() 函数从 _meta 中提取 SubagentSessionInfo，进而调用 tool_call_for_subagent(session_id) 定位父级 ToolCall 以渲染展开/折叠卡片 UI。

问题陈述¶

GAP 1（P0 阻塞）：_meta 字段从未填充¶

Zed 期望：每个 ToolCallStart 和 ToolCallProgress（Zed 中分别称为 tool_call 和 tool_call_update）均可携带 _meta 字段。对于 subagent 工具调用，Zed 读取： - subagent_session_info：{session_id, message_start_index, message_end_index} — 作为 JSON 对象序列化在 _meta 内 - tool_name：底层工具名称（用于显示归因，Zed 使用 snake_case 的 TOOL_NAME_META_KEY = "tool_name"）

AgentPool 现状：AnnotatedObject（ToolCallStart/ToolCallProgress 的基类）具有 field_meta 字段（序列化为 _meta），但 从未在任何位置填充。在 event_converter.py 的第 449、490、506、552、584、755、781、815、991 行，所有 ToolCallStart() 和 ToolCallProgress() 构造函数均省略了 field_meta 参数。

⚠️ 注意：上述行号中，部分对应非 subagent 的 ToolCall（如 BuiltinToolCallPart）。Phase 1 修改时，仅 subagent 相关的 ToolCallStart/ToolCallProgress 需传入包含 subagent_session_info 的 field_meta；非 subagent ToolCall 可选传入仅含 tool_name 的 field_meta（用于 Zed 工具归因显示），**不得**传入 subagent_session_info。

影响：Zed 完全无法检测 subagent 工具调用。没有 _meta.subagent_session_info，Zed 的 subagent_session_info_from_meta() 返回 None，tool_call_for_subagent() 永远找不到父级 ToolCall。整个 subagent 面板 UI 无法运作。

代码证据：

# event_converter.py:449 — BuiltinToolCallPart ToolCallStart
yield ToolCallStart(
    tool_call_id=tool_call_id,
    title=state.title,
    kind=state.kind,
    raw_input=state.raw_input,
    status="pending",
    # ❌ field_meta 未传入
)

# event_converter.py:755 — inline 模式 subagent text ToolCallStart
yield ToolCallStart(
    tool_call_id=state.text_output_call_id,
    title=f"[`{source_name}`] Output",
    kind="other",
    status="pending",
    content=[ContentToolCallContent.text(text=full_content)]
    if full_content
    else None,
    # ❌ field_meta 未传入
)

GAP 2（P1）：Subagent 事件扁平化到父流¶

Zed 期望：Subagent 在**独立的 ACP session**（通过 session/new 创建）中运行，父级 ToolCall 的 _meta.subagent_session_info.session_id 链接到该子会话。Zed 的 AcpThread::tool_call_for_subagent(session_id) 定位父级 ToolCall 以渲染展开/折叠卡片 UI。

AgentPool 现状：三种展示模式均**未创建独立的 ACP session**： - legacy（服务器默认）：将 subagent 文本扁平化到 AgentMessageChunk 中，使用 markdown headers 分隔 - inline：为每个 subagent 活动创建独立的 ToolCallStart/ToolCallProgress，但全部在**同一 session** - tool_box：在同一 session 中为每个 subagent 调用创建一个 ToolCallStart，累积内容

三种模式均不：(1) 调用 session/new 创建子 ACP session，(2) 通过 ACP 发射 SubagentSpawned 事件，或 (3) 使 subagent 内容作为独立 session 可访问。

GAP 3（P1）：SpawnSessionStart 事件未用于 ACP subagent 信令¶

AgentPool 现状：SpawnSessionStart 事件（定义于 events.py:646）由 subagent_tools.py（第 109 行）发射。ACP converter 在 event_converter.py:686-693 处理该事件，仅发射一个带有 emoji 前缀的简单 AgentMessageChunk.text()。

SpawnSessionStart 事件携带 child_session_id、parent_session_id 和 tool_call_id — 恰好是构建 SubagentSessionInfo 所需的信息。但 ACP converter 未：(1) 创建子 ACP session，(2) 在父级 ToolCallStart 的 _meta 中发射 subagent_session_info，或 (3) 将 subagent 事件路由到子会话。

GAP 4（P2）：无 message_start_index / message_end_index 追踪¶

Zed 期望：SubagentSessionInfo 包含 message_start_index 和 message_end_index（usize 类型），定义子会话线程中的条目范围，用于确定哪些条目属于特定的 subagent turn。

AgentPool 现状：无 message index 追踪概念。

GAP 5（P2）：_meta 中未发射 tool_name 用于工具归因¶

Zed 源码 acp_thread.rs:64-67：

pub fn meta_with_tool_name(tool_name: &str) -> acp::Meta {
    acp::Meta::from_iter([(TOOL_NAME_META_KEY.into(), tool_name.into())])
}

Zed 从 _meta 读取 tool_name key（TOOL_NAME_META_KEY = "tool_name"，snake_case）以显示产生特定 ToolCall 的工具名称。AgentPool 从未设置此字段。

影响分析¶

若不解决上述差距，以下功能将持续不可用：

目标与非目标¶

目标¶

非目标¶

评估标准¶

方案分析¶

选项 1：最小化修复 — 仅填充 _meta（Phase 1）¶

描述：仅实施 Phase 1，在现有 ToolCallStart/ToolCallProgress 构造时填充 field_meta，包含 SubagentSessionInfo 和 tool_name。不创建独立子会话，不路由事件，不新增显示模式。

实施范围： - 在 event_converter.py 中创建 _build_subagent_meta() 辅助方法 - 修改所有 subagent 相关的 ToolCallStart/ToolCallProgress 构造调用，传入 field_meta - SpawnSessionStart 事件处理改为发射带 _meta 的 ToolCallStart，而非纯文本

优势： - 修改范围最小，仅涉及 event_converter.py 一个文件 - 风险最低，不改变事件路由逻辑 - Zed 可立即检测到 subagent 存在（虽然内容仍在同一 session） - 开发工时最短

劣势： - Zed 检测到 subagent_session_info.session_id 后会尝试加载该 session，但 session 不存在 - 不满足 Zed 的完整子会话模型，展开/折叠 UI 可能显示为空或错误 - message_start_index/message_end_index 无法提供有效值 - 仅是临时方案，后续仍需实施 Phase 2

评估：

工作量估算：低（~130 行新增，1-2 天）

风险评估： - 技术风险：低。Zed 可能对不存在的 session_id 显示错误，但不影响父会话 - 兼容性风险：低。_meta 是可选字段，非 Zed 客户端会忽略

选项 2：完整 ACP 子会话支持 — _meta + 子会话创建 + 事件路由 + display_mode=zed（Phase 0+1+2+3）¶

描述：在 Phase 1 基础上，增加子会话创建（Phase 2）和 message index 追踪（Phase 3）。当 SpawnSessionStart 事件到达时，创建独立的子 ACP session；SubAgentEvent 中的内容事件路由到子会话；追踪 message 范围索引。通过 display_mode=zed 配置激活 Zed 适配，无需自动检测客户端类型。

实施范围： - Phase 1：当 display_mode == "zed" 时填充 _meta（SubagentSessionInfo + tool_name）；其他 display_mode 行为不变 - Phase 2：子会话创建与事件路由（仅 display_mode == "zed"） - 修改 SpawnSessionStart 处理：调用 session_manager 创建子 ACP session - 修改 SubAgentEvent 处理：将 inner_event 路由到子会话的 session update 流 - 子会话生命周期管理：spawn 时创建，StreamCompleteEvent 时关闭 - Phase 3：message_start_index / message_end_index 追踪 - 在子会话中维护消息计数器 - 在 ToolCallProgress 的 _meta 中更新 message_end_index

优势： - 完全符合 Zed 的 subagent 数据模型 - 子会话内容独立可访问，Zed 可正确渲染展开/折叠 UI - message_start_index/message_end_index 使 Zed 可精确定位条目范围 - 单一 display_mode=zed 配置，无需额外的路由层或自动检测 - 非 Zed 客户端零影响：legacy/inline/tool_box 模式行为完全不变

劣势： - 修改范围较大，涉及 event_converter.py、session_manager.py、session.py - 子会话生命周期管理增加复杂度（创建、路由、关闭、异常处理） - 子会话的 session update 需要通过父会话的 JSON-RPC 连接发射，需确认 ACP 传输层支持 - 需要处理嵌套 subagent（虽然 Zed 限制 depth=1，但内部可能有多层） - 增加内存占用（每个子会话需要独立的 session 状态）

评估：

工作量估算：中高（~380 行新增，5-7 天）

风险评估： - 技术风险：中。子会话的 session update 发射路径需验证；ACP 传输层是否支持从非活跃 session 发射 update 需确认 - 兼容性风险：低。子会话路由为新增逻辑，现有模式不受影响 - 性能风险：中。每个子会话增加内存和事件处理开销

选项 3：新增 zed_subagent 显示模式 — 全新 display mode 替代现有三种（Phase 0+1+2+3+4）¶

描述：在选项 2 基础上，新增 zed_subagent 显示模式（Phase 4），专为 Zed 客户端优化。同时实现客户端自动检测：当 ACP initialize 握手时检测客户端标识，自动选择 zed_subagent 模式。

⚠️ 注意：选项 2 现已通过 display_mode=zed 实现了 Zed 专用显示模式。选项 3 提议的 zed_subagent 枚举值与选项 2 的 display_mode=zed 功能等价，且选项 3 的客户端自动检测已被明确排除（subagent 适配是 Zed 专属 ad-hoc 扩展，应作为显式配置项）。因此选项 3 相对于选项 2 无增量价值，已被选项 2 的 display_mode=zed 方案取代。

实施范围： - Phase 1-3：同选项 2 - Phase 4：zed_subagent 显示模式 + 客户端自动检测 - 新增 zed_subagent display_mode 枚举值 - 实现 _convert_subagent_zed() 方法，完全按照 Zed 期望的事件序列输出 - 在 initialize 响应中读取客户端信息，自动设置 display_mode - 允许 YAML 配置覆盖自动检测

优势： - 专门的 Zed 优化路径，不受现有模式约束 - 自动检测减少用户配置负担 - 完整的 Zed subagent 体验：独立子会话 + 展开/折叠 + 工具归因 + message 范围 - 现有模式完全不受影响，零风险 - 未来可扩展：其他 IDE（如 JetBrains）可能有不同的 subagent 期望，可新增专用模式

劣势： - 新增第 4 种 display_mode，增加维护面积 - 客户端自动检测可能不准确（依赖客户端标识字段，部分客户端可能不提供） - 最长开发周期 - 自动检测逻辑可能在 Zed 版本更新后失效

评估：

工作量估算：高（~530 行新增，7-10 天）

风险评估： - 技术风险：中高。自动检测依赖客户端信息，可能需要 fallback 机制 - 兼容性风险：低。纯新增模式 - 维护风险：中。4 种 display_mode 的维护成本

推荐¶

推荐选项 2：完整 ACP 子会话支持，分阶段实施。

推荐理由：

1. 选项 1 仅是临时方案，Zed 检测到 session_id 但找不到对应 session，用户体验不佳
2. 选项 2 通过 display_mode=zed 提供了 Zed 专用适配，无需自动检测客户端类型
3. 选项 3 已被选项 2 的 display_mode=zed 方案取代，无增量价值
4. 选项 2 的非 Zed 客户端零影响设计：legacy/inline/tool_box 模式行为完全不变
5. 选项 2 的 Phase 1 可立即解决 P0 阻塞问题，Phase ⅔ 渐进式交付

接受的权衡： - Phase 1 阶段 Zed 的 subagent 展开/折叠 UI 内容为空，需等待 Phase 2 完成 - display_mode=zed 需要用户显式配置，不支持自动检测客户端类型

技术设计¶

架构图¶

当前事件流¶

┌─────────────────────────────────────────────────────────────────────┐
│                    当前 ACP Subagent 事件流                          │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  subagent_tools.py                                                   │
│     │                                                                │
│     ├─ SpawnSessionStart ──→ event_converter ──→ AgentMessageChunk  │
│     │                                │                    (emoji文本) │
│     │                                │                               │
│     └─ SubAgentEvent ──────→ event_converter                        │
│                                  │                                   │
│                                  ├── legacy ──→ AgentMessageChunk    │
│                                  │               (markdown headers)  │
│                                  │                                   │
│                                  ├── inline ──→ ToolCallStart       │
│                                  │              ToolCallProgress     │
│                                  │              (同一 session,       │
│                                  │               _meta = None ❌)    │
│                                  │                                   │
│                                  └── tool_box ─→ ToolCallStart      │
│                                                  ToolCallProgress   │
│                                                  (同一 session,     │
│                                                   _meta = None ❌)  │
│                                                                      │
│  Zed 客户端:  _meta 为空 → subagent_session_info_from_meta() = None │
│               → 无法检测 subagent → UI 不可用                        │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

提议事件流¶

┌─────────────────────────────────────────────────────────────────────┐
│                    提议 ACP Subagent 事件流                          │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  initialize 握手                                                     │
│     │                                                                │
│     └─ YAML pool_server.subagent_display_mode 配置                  │
│        ├─ "zed" → Zed 适配模式（含 _meta + 子会话）                  │
│        └─ 其他  → 传统模式（legacy/inline/tool_box）                │
│                                                                      │
│  subagent_tools.py                                                   │
│     │                                                                │
│     ├─ SpawnSessionStart ──→ event_converter                        │
│     │                           │                                    │
│     │     ┌────────────────────┼────────────────────┐               │
│     │     │ display_mode=="zed"│  display_mode!="zed"│               │
│     │     │                    │                      │               │
│     │     │ ├ ToolCallStart    │ └ AgentMessageChunk │               │
│     │     │ │  (含 session_info│   (保持原有行为，    │               │
│     │     │ │   +tool_name ✅) │    无 _meta ❌)      │               │
│     │     │ │                  │                        │               │
│     │     │ └ Phase 2:        │                        │               │
│     │     │   创建子 ACP      │                        │               │
│     │     │   session         │                        │               │
│     │     └────────────────────┴────────────────────┘               │
│     │                                                                │
│     └─ SubAgentEvent ──────→ event_converter                        │
│                                  │                                   │
│     ┌────────────────────────────┼──────────────────────┐           │
│     │ display_mode=="zed"        │  display_mode!="zed"  │           │
│     │                            │                        │           │
│     │ ├ Phase 2: 路由到子会话  │ ├ legacy →             │           │
│     │ │  session/update          │ │  AgentMessageChunk   │           │
│     │ │                          │ │  (无 _meta)          │           │
│     │ │ └ 更新父 ToolCallProgress│ │                      │           │
│     │ │   (含 session_info       │ ├ inline →             │           │
│     │ │    +tool_name ✅)        │ │  ToolCallStart       │           │
│     │ │   [Phase 2]             │ │  (无 _meta ❌)       │           │
│     │ │                          │ │                      │           │
│     │ │ Phase 1: SCEvent→TCP(含_meta)│ └ tool_box →           │           │
│     │ │ 其他P1丢弃(P2→子会话)      │   ToolCallStart        │           │
│     │ │                            │   (无 _meta ❌)        │           │
│     └────────────────────────────┴──────────────────────┘           │
│                                                                      │
│  ✅ 关键: display_mode=="zed" 与传统模式条件分支                      │
│          display_mode=="zed" 时 SpawnSessionStart 使用 ToolCallStart（含 _meta）；传统模式保持 AgentMessageChunk 不变 │
│          inline/tool_box 子级 ToolCallStart/ToolCallProgress 不携带 _meta │
│                                                                      │
│  ⚠️ 向后兼容说明：display_mode!="zed" 时 SpawnSessionStart 保持原有 AgentMessageChunk 行为，非 Zed 客户端零影响。│
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

SubagentSessionInfo 数据模型¶

from __future__ import annotations

import json
from typing import Any, Literal

from pydantic import BaseModel

# Module-level constants matching Zed's acp_thread.rs
TOOL_NAME_META_KEY: str = "tool_name"
SUBAGENT_SESSION_INFO_META_KEY: str = "subagent_session_info"


class SubagentSessionInfo(BaseModel):
    """ACP _meta 中 subagent_session_info 的 Python 表示。

    与 Zed 的 AcpThread 期望格式对齐。

    ⚠️ WARNING: 序列化为 JSON **对象**（非 JSON 字符串）存入 _meta["subagent_session_info"]。
    Zed 使用 serde_json::json!(&session_info) 写入 Value::Object，
    使用 serde_json::from_value(v.clone()) 读取。
    若误传为字符串，Zed 的 from_value 会静默失败（.ok() → None），
    导致整个 _meta 机制失效。
    """

    session_id: str
    """子 ACP session 的唯一标识符。"""

    message_start_index: int
    """子会话中该 turn 的起始条目索引（0-based）。

    对应 Zed SubagentSessionInfo.message_start_index (usize, required)。
    """

    message_end_index: int | None = None
    """子会话中该 turn 的结束条目索引（0-based）。

    对应 Zed SubagentSessionInfo.message_end_index (Option<usize>)。
    """

    @classmethod
    def from_meta(cls, meta: dict[str, Any]) -> SubagentSessionInfo | None:
        """从 _meta 字典中提取 SubagentSessionInfo。

        Args:
            meta: _meta 字典，值应为 JSON 对象（dict）。

        Returns:
            SubagentSessionInfo 实例，若 meta 中无 subagent_session_info 则返回 None。

        ⚠️ 正确格式为 dict（JSON 对象）；若误传为 str（JSON 字符串），
        此方法尝试作为 fallback 解析，但 Zed 端 from_value 会静默失败。
        """
        raw = meta.get(SUBAGENT_SESSION_INFO_META_KEY)
        if raw is None:
            return None
        if isinstance(raw, dict):
            return cls.model_validate(raw)
        if isinstance(raw, str):
            # Fallback: 尝试解析 JSON 字符串（兼容错误格式）
            try:
                data = json.loads(raw)
                return cls.model_validate(data)
            except (json.JSONDecodeError, ValueError):
                return None
        return None


def build_subagent_meta(
    session_info: SubagentSessionInfo,
    tool_name: str | None = None,
) -> dict[str, Any]:
    """构建包含 SubagentSessionInfo 的 _meta 字典。

    此函数为底层实现，由 `_build_subagent_field_meta()` 调用。

    `_build_subagent_field_meta()` 为推荐调用入口，包含空值安全检查和 WARNING 日志。
    `build_subagent_meta()` 为底层实现，直接调用不安全。

    Args:
        session_info: 子会话信息
        tool_name: 工具名称（用于 Zed 的 tool_name 归因）

    Returns:
        可传入 ToolCallStart/ToolCallProgress 的 field_meta 参数的字典。
        返回类型为 dict[str, Any] 以匹配 AnnotatedObject.field_meta 的类型定义。

    ⚠️ WARNING: subagent_session_info 的值必须为 dict（JSON 对象），
    绝不能为 str（JSON 字符串）。这是 Zed 的 serde_json::from_value 要求。

    常量 TOOL_NAME_META_KEY 和 SUBAGENT_SESSION_INFO_META_KEY 为模块级定义，
    匹配 Zed 的 acp_thread.rs 中的常量。
    """
    meta: dict[str, Any] = {
        SUBAGENT_SESSION_INFO_META_KEY: session_info.model_dump(),
    }
    if tool_name is not None:
        meta[TOOL_NAME_META_KEY] = tool_name
    return meta

路由模式设计¶

Subagent 事件路由通过 display_mode 配置控制。新增 zed 模式专为 Zed 编辑器适配，为 Zed 专属的 _meta.subagent_session_info 扩展机制提供支持。

zed 模式是 ad-hoc 适配，非 ACP 协议标准特性。其他 ACP 客户端无需支持此模式，使用 legacy/inline/tool_box 即可。

四种 display_mode 对比¶

YAML 配置¶

pool_server:
  subagent_display_mode: zed  # legacy | inline | tool_box | zed

单一配置项，无需额外的路由配置。使用现有 pool_server.subagent_display_mode 配置键，仅新增 "zed" 枚举值。无需额外配置键或迁移。

⚠️ 配置注意事项¶

• "zed" 模式专为 Zed 编辑器设计，非 Zed 客户端可能无法正确渲染 _meta.subagent_session_info 扩展字段
• 服务器启动时若检测到 display_mode == "zed"，应输出 WARNING 日志："Subagent display_mode='zed' is designed for Zed editor clients only. Other clients may not render subagent UI correctly."
• "zed" 永远不会作为默认值 — 必须用户显式配置。若未配置 subagent_display_mode 或配置为 legacy/inline/tool_box，subagent 行为与当前完全一致。

@dataclass
class ACPEventConverter:
    _display_mode: Literal["legacy", "inline", "tool_box", "zed"] = "legacy"
    _session_manager: SessionManager | None = None  # Phase 2 新增
    _subagent_tool_map: dict[str, str] = field(default_factory=dict)
    # 注：Phase 3 将新增 _subagent_message_counts: dict[str, int] = field(default_factory=dict)

⚠️ _meta 填充约束¶

关键规则：_meta.subagent_session_info 仅在 display_mode == "zed" 时，由 SpawnSessionStart 产出的 ToolCallStart 及其后续 ToolCallProgress 中设置。_convert_subagent_inline / _convert_subagent_tool_box 产出的子级 ToolCallStart / ToolCallProgress **不得**携带任何 _meta 字段。

此约束仅在 display_mode == "zed" 时有意义。其他 display_mode 下不填充任何 _meta。

原因：Zed 的 is_subagent() 通过 subagent_session_info.is_some() 检测 subagent。如果子级 ToolCall 也携带此字段，Zed 会将所有子级 ToolCall 视为独立的 subagent 父级，导致 UI 渲染混乱。

inline/tool_box 子级 ToolCallStart/ToolCallProgress **不得**携带任何 _meta 字段。仅 display_mode == "zed" 时 SpawnSessionStart 产出的 ToolCallStart/ToolCallProgress 携带 _meta（含 subagent_session_info + tool_name）。

tool_name 选择说明：SpawnSessionStart 产出的 ToolCallStart 使用 tool_name="task"，这是 AgentPool 中创建子代理的工具名（定义于 subagent_tools.py），与现有 subagent_tools.py 保持一致。Zed 使用 _meta.tool_name 在 UI 中显示工具归因。

事件流规范¶

SpawnSessionStart → ToolCallStart（带 _meta）¶

当 display_mode == "zed" 时，SpawnSessionStart 事件到达时，event_converter 应：

1. 发射 ToolCallStart，field_meta 包含 subagent_session_info 和 tool_name
2. 记录 tool_call_id 与 child_session_id 的映射关系
3. 创建子 ACP session（Phase 2）

当 display_mode != "zed" 时，SpawnSessionStart 保持原有 AgentMessageChunk 行为不变。

# event_converter.py — SpawnSessionStart 处理（提议）
case SpawnSessionStart(
    child_session_id=child_id,
    parent_session_id=parent_id,
    tool_call_id=tc_id,
    source_name=source_name,
    spawn_mechanism=mechanism,
    description=description,
):
    if self._display_mode == "zed":
        # zed 模式：发射带 _meta 的 ToolCallStart
        meta = self._build_subagent_field_meta(child_session_id=child_id, tool_name="task")

        # Phase 2: 创建子 ACP session
        # await self._session_manager.new_session(
        #     session_id=child_id,
        #     parent_session_id=parent_id,
        # )

        # 记录映射
        self._subagent_tool_map[child_id] = tc_id or f"spawn:{child_id}"

        icon = "⚡" if mechanism == "spawn" else "🚀"
        yield ToolCallStart(
            tool_call_id=tc_id or f"spawn:{child_id}",
            title=f"{icon} `{source_name}`: {description}",
            kind="other",
            status="in_progress",
            field_meta=meta,
        )
    else:
        # 非 zed 模式：保持原有 AgentMessageChunk 行为
        icon = "⚡" if mechanism == "spawn" else "🚀"
        yield AgentMessageChunk.text(f"{icon} `{source_name}`: {description}")

SubAgentEvent 处理（Phase 1）¶

实际实现不使用独立的 _convert_subagent_event() 方法，而是拆分在 convert() 方法的两个位置：

1. SpawnSessionStart → 见上方 convert() 方法的 SpawnSessionStart case（lines 637-671）
2. StreamCompleteEvent → 见下方 convert() 方法的 SubAgentEvent case 中 StreamCompleteEvent 分支（lines 688-697）

inline/tool_box 子级 ToolCallStart/ToolCallProgress 修改在现有 _convert_subagent_inline / _convert_subagent_tool_box 方法中进行（子级 ToolCall 不携带 _meta，无需修改）。

StreamCompleteEvent → ToolCallProgress（完成父级 ToolCall）¶

⚠️ StreamCompleteEvent 本身不含 child_session_id 字段。子代理完成事件通过 SubAgentEvent 包装传递，child_session_id 在 SubAgentEvent 外层。

当 display_mode == "zed" 时，子代理完成时 SubAgentEvent(event=StreamCompleteEvent(...)) 到达。在 convert() 方法的 SubAgentEvent case 分支内，通过匹配 inner_event 类型处理，使用 SubAgentEvent.child_session_id 从 _subagent_tool_map 查找对应的 tool_call_id，发射 ToolCallProgress 完成父级 ToolCall。当 display_mode != "zed" 时，不发射 ToolCallProgress（无父级 ToolCallStart 需要完成）。

# event_converter.py — StreamCompleteEvent 处理（Phase 1 提议）
# 在 convert() 方法的 SubAgentEvent case 分支内：
case SubAgentEvent(child_session_id=child_id, tool_call_id=_, event=inner_event)
    if self._display_mode == "zed" and child_id in self._subagent_tool_map
       and isinstance(inner_event, StreamCompleteEvent):
    # Phase 1: 仅处理 StreamCompleteEvent 以完成父级 ToolCall
    # 非 StreamCompleteEvent 的 SubAgentEvent（文本输出、工具调用等）在 Phase 1 中丢弃
    # Phase 2 将这些事件路由到子 ACP session
    tc_id = self._subagent_tool_map[child_id]
    meta = self._build_subagent_field_meta(child_session_id=child_id, tool_name="task")
    yield ToolCallProgress(tool_call_id=tc_id, status="completed", field_meta=meta)

各 display_mode 行为：

• display_mode == "zed"：发射 ToolCallProgress(status="completed", field_meta=meta) 完成父级 ToolCall
• display_mode != "zed"：不发射 ToolCallProgress（无父级 ToolCallStart 需要完成）

SubAgentEvent → 子会话路由（Phase 2）¶

# event_converter.py — SubAgentEvent 处理（提议，Phase 2）
case SubAgentEvent(
    source_name=source_name,
    source_type=source_type,
    event=inner_event,
    depth=depth,
    child_session_id=child_id,
    parent_session_id=parent_id,
    tool_call_id=tc_id,
):
    if self._display_mode == "zed":
        # zed 模式：事件路由到子会话
        # async for update in self._convert_event_to_session_update(inner_event):
        #     await self._session_manager.send_session_update(child_id, update)
        # ⚠️ Zed 使用 num_entries.saturating_sub(1) 计算 end_index（0-based index，非 count）
        # message_end_index=message_count - 1 if message_count > 0 else None
        # ...
        pass  # Phase 2 实现
    else:
        # 传统模式：使用 legacy/inline/tool_box 转换
        match self._display_mode:
            case "inline":
                async for update in self._convert_subagent_inline(
                    source_name, source_type, inner_event, depth,
                    child_session_id=child_id, tool_call_id=tc_id,
                ):
                    yield update
            case "tool_box":
                async for update in self._convert_subagent_tool_box(
                    source_name, source_type, inner_event, depth,
                    child_session_id=child_id, tool_call_id=tc_id,
                ):
                    yield update
            case "legacy":
                async for update in self._convert_subagent_legacy(
                    source_name, source_type, inner_event, depth,
                    child_session_id=child_id, tool_call_id=tc_id,
                ):
                    yield update

API 变更¶

event_converter.py 方法签名变更¶

import logging
from typing import Any, Literal

from .subagent_meta import SubagentSessionInfo, build_subagent_meta

logger = logging.getLogger(__name__)

@dataclass
class ACPEventConverter:
    """ACP event converter with subagent _meta support."""

    # 以下字段为 dataclass 字段声明（ACPEventConverter 为 @dataclass 类）
    _display_mode: Literal["legacy", "inline", "tool_box", "zed"] = "legacy"
    _session_manager: SessionManager | None = None  # Phase 2 新增

    # Phase 1 新增
    _subagent_tool_map: dict[str, str] = field(default_factory=dict)  # child_session_id → tool_call_id
    # 注：Phase 3 将新增 _subagent_message_counts: dict[str, int] = field(default_factory=dict)

    def _build_subagent_field_meta(
        self,
        child_session_id: str,
        tool_name: str | None = None,
        message_start_index: int = 0,
        message_end_index: int | None = None,
    ) -> dict[str, Any] | None:
        """为 subagent 工具调用构建 _meta 字段。

        Args:
            child_session_id: 子会话 ID
            tool_name: 底层工具名称
            message_start_index: 起始消息索引（默认 0，假设子会话总是新建的）
            message_end_index: 结束消息索引

        Returns:
            field_meta 字典，若 child_session_id 为空则返回 None。
        """
        if not child_session_id:
            logger.warning("build_subagent_field_meta called with empty child_session_id, skipping _meta fill")
            return None
        session_info = SubagentSessionInfo(
            session_id=child_session_id,
            message_start_index=message_start_index,
            message_end_index=message_end_index,
        )
        return build_subagent_meta(session_info, tool_name=tool_name)

两层默认值说明：event_converter.py 的字段默认值为 "legacy"（通过 _get_display_mode() 环境变量回退），而 server.py/session_manager.py 在构造时传入 "tool_box" 作为参数默认值。实际运行时默认为 "tool_box"，但 converter 层面的字段默认值必须保持 "legacy" 以匹配源码行为。

reset() 行为变更¶

reset() 方法在 StreamCompleteEvent 时被调用，用于清理单次 prompt 响应的状态。但 _subagent_tool_map 和 _subagent_message_counts 是**跨 prompt 生命周期**的状态（一个 subagent 可能跨多个 prompt 运行），不应被 reset() 清除。

def reset(self) -> None:
    """重置单次 prompt 响应的状态，但保留跨 prompt 的 subagent 追踪状态。"""
    # 清理单次响应状态（使用实际 dataclass 字段）
    self._current_tool_inputs.clear()
    self._tool_states.clear()
    # ... 其他单次响应状态清理

    # ⚠️ 不清理 subagent 追踪状态
    # self._subagent_tool_map 保留 — 在父 session close 时清理
    # self._subagent_message_counts 保留 — 在父 session close 时清理  [Phase 3 新增]

⚠️ 当前 event_converter.py 存在 reset() body 重复声明（字段赋值与 dataclass field(default_factory=...) 重复）和 reset() 被调用两次的 bug。Phase 1 应一并清理。

_subagent_tool_map（及 Phase 3 的 _subagent_message_counts）应在父会话 session/close 时清理，而非 reset() 时。

此外，当前 event_converter.py 存在 self.reset() 在 StreamCompleteEvent handler 中被调用两次的 bug（lines 670, 673），应在 Phase 1 中一并修复。

session/close 清理¶

_subagent_tool_map 的生命周期与父会话绑定，应在父会话 session/close 时显式清理：

# 在 session/close 处理中清理 _subagent_tool_map
# 具体实现见「EventConverter 清理钩子」小节的 cleanup() 方法

设计理由：_subagent_tool_map 跨多个 prompt 生命周期持久存在，reset() 不应清除它。清理路径必须显式绑定到 session/close，确保会话结束时不会遗留过期的映射条目。

EventConverter 清理钩子¶

ACPEventConverter 添加 cleanup() 方法，在 AcpSession.close() 中调用：

# event_converter.py
def cleanup(self) -> None:
    """清理会话级别的持久状态。在 session/close 时由 AcpSession 调用。"""
    for child_id in list(self._subagent_tool_map.keys()):
        # Phase 2: await self._session_manager.close_session(child_id)
        del self._subagent_tool_map[child_id]
    # Phase 3: for child_id in list(self._subagent_message_counts.keys()):
    #     del self._subagent_message_counts[child_id]

⚠️ Phase 2 变更：cleanup() 将变更为 async def cleanup()，AcpSession.close() 中需改为 await self._converter.cleanup()。

# session.py — AcpSession.close() 中添加
def close(self) -> None:
    # ... 现有清理逻辑 ...
    if self._converter is not None:
        self._converter.cleanup()

设计理由：ACPEventConverter 没有 session 生命周期感知，cleanup() 提供显式的会话结束信号，避免 _subagent_tool_map 在长期运行会话中造成内存泄漏。

session_manager.py 变更（Phase 2）¶

class SessionManager:
    """ACP session lifecycle management."""

    async def new_session(
        self,
        session_id: str | None = None,
        parent_session_id: str | None = None,
        cwd: str | None = None,
    ) -> AcpSession:
        """创建新的 ACP session。

        Args:
            session_id: 可选的 session ID（用于子会话预分配）
            parent_session_id: 父会话 ID（用于 subagent 关联）
            cwd: 工作目录

        Returns:
            新创建的 AcpSession 实例。
        """
        ...

    async def send_session_update(
        self,
        session_id: str,
        update: ACPSessionUpdate,
    ) -> None:
        """向指定 session 发射 session update 事件。

        用于将子会话的事件通过 ACP 传输层发送给客户端。

        Args:
            session_id: 目标 session ID
            update: ACP session update 对象
        """
        ...

    async def get_message_count(
        self,
        session_id: str,
    ) -> int:
        """获取指定 session 的当前消息数量。

        用于计算 message_end_index。

        Args:
            session_id: 目标 session ID

        Returns:
            当前消息条目数量。
        """
        ...

子会话生命周期状态机¶

┌──────────┐  SpawnSessionStart  ┌──────────┐
│ 不存在    │ ──────────────────→ │ 已创建    │
│          │                     │ (active) │
└──────────┘                     └────┬─────┘
                                      │
                        SubAgentEvent │ (事件路由到子会话)
                                      │
                                      ▼
                                 ┌──────────┐
                   ┌─────────────│ 运行中    │
                   │             │ (running)│
                   │             └────┬─────┘
                   │                  │
      StreamCompleteEvent            │  父会话取消
      (成功/错误)                    │  (session/cancel)
                   │                  │
                   ▼                  ▼
             ┌──────────┐      ┌──────────┐
             │ 已完成    │      │ 已取消    │
             │ (closed) │      │ (closed) │
             └──────────┘      └──────────┘

异常路径：
  - 子会话运行时父会话 session/close → 遍历所有子会话，执行 close
  - ACP 服务器崩溃 → 重启后通过 SessionManager.get_child_sessions() 检测孤立会话
  - 子会话创建后 SubAgentEvent 未到达 → 子会话超时关闭（建议 5 分钟）

状态转换规则：

1. SpawnSessionStart → 创建子会话 (active)
2. SubAgentEvent → 事件路由到子会话 (running)
3. StreamCompleteEvent(success) → 子会话关闭 (closed)，父 ToolCallProgress → completed
4. StreamCompleteEvent(error) → 子会话关闭 (closed)，父 ToolCallProgress → failed
5. 父 session/cancel → 所有子会话 cancelled + closed
6. 父 session/close → 所有子会话 closed
7. 超时 → 子会话 closed，父 ToolCallProgress → failed

安全考量¶

1. Session ID 注入：SubagentSessionInfo.session_id 由服务端生成，不接受客户端输入。使用 identifier.ascending("session") 生成，确保不可预测。

2. 子会话隔离：子会话继承父会话的权限范围。不允许子会话访问父会话之外的资源。工作目录（cwd）与父会话一致。

3. _meta 数据泄露：_meta 字段通过 ACP JSON-RPC 传输，可能被客户端日志记录。不应在 _meta 中包含敏感信息（如 API key、用户凭证）。SubagentSessionInfo 仅包含 session ID 和索引，无安全风险。

4. 拒绝服务：恶意客户端可能通过频繁触发 subagent 创建大量子会话。需实施子会话数量上限（建议与 Zed 的 MAX_SUBAGENT_DEPTH=1 对齐，即每个父会话最多 N 个并发子会话）。

5. 子会话生命周期：子会话必须在父会话关闭时一并关闭，避免孤立会话占用资源。在 session/close 处理中遍历并关闭所有子会话。

实施计划¶

Phase 0：子会话 session/update 传输验证 — Spike（0.5-1 天）¶

目标：验证 Zed 能否接收通过父会话 client 连接发送的子会话 session/update

范围： - [ ] 创建 PoC：在 ACP process_prompt 中手动创建子 session，发送 session/update - [ ] 验证 Zed 能否收到并处理带有子 session_id 的 update notification - [ ] 验证 Zed 是否需要通过 session/new 预先知晓子会话 - [ ] 如需 session/new，验证服务端代理调用的可行性 - [ ] 输出：技术可行性报告，确定 Phase 2 的传输路径设计

Go/No-Go 准则： - Go：Zed 能接收通过父会话连接发送的、session_id 不同于父会话的 session/update notification（无需先 session/new） - Go（替代路径）：Zed 需要 session/new 知晓子会话，但 ACP 传输层支持服务端主动发送 session/new 响应给客户端 - No-Go：Zed 既不接受未知 session_id 的 session/update，ACP 传输层也不支持服务端主动调用 session/new → Phase 2 必须使用替代设计（将子会话内容嵌入父 ToolCallProgress 的 content 字段）

预估工期：0.5-1 天 依赖：无 阻塞：Phase 2 的设计依赖此 spike 的结果

Phase 1：填充 _meta（SubagentSessionInfo + tool_name）— P0¶

目标：G1 + G2，使 Zed 可检测 subagent 工具调用

范围： - [ ] 创建 SubagentSessionInfo 数据模型（~40 行） - [ ] 创建 build_subagent_meta() 和 _build_subagent_field_meta() 辅助方法（~35 行） - [ ] 增加 ACPEventConverter 字段声明 _subagent_tool_map（~5 行） - [ ] 修改 SpawnSessionStart 处理：当 display_mode == "zed" 时发射带 _meta 的 ToolCallStart；当 display_mode != "zed" 时保持原有 AgentMessageChunk 行为不变 - [ ] 修改 StreamCompleteEvent 处理：当 display_mode == "zed" 时对 SpawnSessionStart 产出的 ToolCallStart 发射 ToolCallProgress (status=completed) - [ ] 非 StreamCompleteEvent 的 SubAgentEvent 在 display_mode == "zed" 时丢弃（Phase 2 路由到子会话） - [ ] 修改 _convert_subagent_inline 中所有 ToolCallStart/ToolCallProgress 调用，不变（子级 ToolCall 不携带 _meta） - [ ] 修改 _convert_subagent_tool_box 中所有 ToolCallStart/ToolCallProgress 调用，不变（子级 ToolCall 不携带 _meta） - [ ] 编写测试：验证 display_mode != "zed" 时 ToolCallStart.field_meta 为 None（无 subagent_session_info 泄露） - [ ] 编写测试：验证 inline/tool_box 子级 ToolCallStart.field_meta 为 None - [ ] 编写测试：验证仅 display_mode == "zed" 时 SpawnSessionStart 产出的 ToolCallStart.field_meta 包含 subagent_session_info - [ ] 编写测试：验证 display_mode == "zed" 时 StreamCompleteEvent 产出的 ToolCallProgress.field_meta 包含 subagent_session_info - [ ] 编写测试：验证 display_mode == "zed" 时非 StreamCompleteEvent 的 SubAgentEvent（如文本输出事件）不产生任何 ACP 事件（Phase 1 丢弃行为） - [ ] 为 SubagentSessionInfo 和 build_subagent_meta 编写单元测试 - [ ] 添加 ACP 快照测试，验证 subagent 工具调用的完整 JSON-RPC 输出格式 - [ ] 快照测试对比 emitted JSON-RPC messages 与参考文件，确保 _meta.subagent_session_info 为 JSON 对象（非字符串） - [ ] 修复 reset() 在 StreamCompleteEvent 中被调用两次的 bug - [ ] 清理 reset() body 中与 dataclass field(default_factory=...) 重复的字段赋值声明 - [ ] 确认 reset() 不清除 _subagent_tool_map - [ ] 修复 subagent_tools.py 中 SpawnSessionStart 双重发射 bug（task() 和 _stream_task() 均 emit，同步模式下产生两个 ToolCallStart） - [ ] 在 session/close 处理中清理 _subagent_tool_map - [ ] 在 ACPEventConverter 中添加 cleanup() 方法 - [ ] 在 AcpSession.close() 中调用 converter.cleanup()

类型定义传播清单¶

添加 "zed" 到 display_mode Literal 类型需更新以下文件：

• 更新上述所有文件中的 display_mode Literal 类型，添加 "zed" 值
• 更新 server.py 中 _coerce_subagent_display_mode() 处理 "zed" 值
• 更新 event_converter.py 中 _get_display_mode() 验证逻辑，接受 "zed"

关于 "legacy" 类型差异：event_converter.py 的 _display_mode 类型包含 "legacy"（通过环境变量 _get_display_mode() 默认值），但 server.py/pool_server.py 等服务器层类型不包含 "legacy"。"legacy" 是 event_converter 内部回退值，非 YAML 配置可选项。本次仅新增 "zed"，不改变 "legacy" 的现有分布。

⚠️ 嵌套 SpawnSessionStart 说明：当前 _convert_subagent_legacy 对嵌套 SpawnSessionStart 执行 pass（丢弃），_convert_subagent_inline / _convert_subagent_tool_box 未处理该事件（走默认分支）。Phase 1 不修改此行为（Zed 限制 MAX_SUBAGENT_DEPTH=1，嵌套场景罕见）。Phase 2 应添加嵌套 SpawnSessionStart 的 ToolCallStart 处理。

预估代码量：~130 行新增 预估工期：1-2 天 依赖：无 回滚策略：还原 event_converter.py 中的 field_meta 参数即可

Phase 2：子会话创建与事件路由 — P1¶

目标：G3，创建独立子 ACP session，路由事件

范围： - [ ] 修改 ACPEventConverter.__init__ 接收 session_manager 参数 - [ ] 当 display_mode == "zed" 时，SpawnSessionStart 处理中调用 session_manager.new_session() 创建子会话 - [ ] 当 display_mode == "zed" 时，SubAgentEvent 处理将 inner_event 路由到子会话 - [ ] ToolCallProgress 必须携带 subagent_session_info（与 ToolCallStart 保持一致） - [ ] 处理 StreamCompleteEvent：更新父 ToolCallProgress 状态为 completed，关闭子会话 - [ ] 修改 session_manager.py：支持 parent_session_id 参数和 send_session_update 方法 - [ ] 处理子会话关闭时的资源清理 - [ ] 编写集成测试 - [ ] 添加 ACP 快照测试，验证子会话 session/update 的传输格式

预估代码量：~300 行新增 预估工期：3-5 天 依赖：Phase 1 回滚策略：移除 session_manager 参数和子会话路由逻辑，回退到 Phase 1 行为

Phase 3：message_start_index / message_end_index 追踪 — P2¶

目标：G4，提供精确的消息范围索引

范围： - [ ] 在 ACPEventConverter 中维护 _subagent_message_counts 映射 - [ ] 子会话创建时记录 message_start_index - [ ] 每次 inner_event 路由后更新 message_end_index - [ ] 在 ToolCallProgress 的 field_meta 中更新 message_end_index - [ ] ⚠️ message_end_index 使用 0-based index（匹配 Zed 的 saturating_sub(1) 语义），即 message_count - 1 if message_count > 0 else None - [ ] 编写单元测试验证索引正确性 - [ ] 确保 message_start_index 始终有值（子会话创建时设为 0）

假设：本 RFC 假设子会话总是新建的（非恢复），因此 message_start_index 始终为 0。若未来支持子会话恢复，需更新此值为 session.get_entry_count()。

预估代码量：~80 行新增 预估工期：1-2 天 依赖：Phase 2 回滚策略：移除 _subagent_message_counts 和索引更新逻辑

里程碑总览¶

依赖关系¶

Phase 0 ──────→ Phase 2 ──→ Phase 3
Phase 1 ──────→ Phase 2

Phase 0 与 Phase 1 可并行执行。Phase 0 仅阻塞 Phase 2（需要传输验证结果），Phase 1 可立即开始。

开放问题¶

1. 子会话 session update 的发射路径：ACP 传输层当前仅支持从活跃 session（即正在执行 session/prompt 的 session）发射 update。子会话的 update 是否需要通过父会话的 JSON-RPC 连接中继？这需要确认 ACP JSON-RPC 传输层的具体实现。Phase 0 Spike 将验证此路径。

2. 嵌套 subagent 的消息索引：当 subagent 本身也调用 subagent 时（虽然 Zed 限制 MAX_SUBAGENT_DEPTH=1，但 AgentPool 内部可能有多层），message_start_index/message_end_index 的语义是否仍与 Zed 期望一致？

3. 非 Zed 客户端的 _meta 兼容性：填充 _meta 后，其他 ACP 客户端（如 JetBrains IDE、VS Code ACP 适配器）如何处理未知的 _meta 字段？根据 ACP 协议规范，客户端应忽略未知的 _meta key，但需验证实际行为。

4. Zed 版本兼容性：_meta.subagent_session_info 格式是否为 Zed 稳定接口？若 Zed 在未来版本更改格式，AgentPool 需要如何适配？

5. 子会话的超时清理策略：若 SubAgentEvent 长时间未到达（如 LLM 响应超时），子会话应在多少时间后自动关闭？

6. 子会话的 session/prompt（已解决）：AgentPool 的子会话**不支持**独立的 session/prompt 调用。子会话仅作为事件接收容器，通过 send_session_update() 接收父会话路由的事件。这与 Zed 的 SubagentHandle.send() 内部 API 语义一致（Zed 的子会话不通过 ACP session/prompt 发送消息）。

决策记录¶

参考¶

调研文档¶

• Zed ACP Subagent 功能调研报告 — 完整的 Zed subagent 实现分析和 AgentPool 差距对比

Zed 源码¶

• ~/src/zed/crates/agent/src/tools/spawn_agent_tool.rs — Zed 的 spawn_agent tool：通过 _meta 发射 SubagentSessionInfo
• ~/src/zed/crates/acp_thread/src/acp_thread.rs — Zed 客户端：从 _meta 提取 SubagentSessionInfo 以渲染 subagent UI
• ~/src/zed/crates/agent_ui/src/acp/thread_view/active_thread.rs — Zed subagent 卡片 UI 渲染

ACP Schema 文件¶

• packages/agentpool/src/acp/schema/base.py — AnnotatedObject 基类，field_meta 字段（序列化为 _meta）
• packages/agentpool/src/acp/schema/session_updates.py — ToolCallStart/ToolCallProgress 定义

AgentPool 源码¶

• packages/agentpool/src/agentpool_server/acp_server/event_converter.py — 核心 ACP 事件转换器
• packages/agentpool/src/agentpool_server/acp_server/session.py — ACP session 管理
• packages/agentpool/src/agentpool_server/acp_server/session_manager.py — Session 生命周期管理
• packages/agentpool/src/agentpool_server/acp_server/server.py — ACP server 入口
• packages/agentpool_toolsets/builtin/subagent_tools.py — 发射 SubAgentEvent 和 SpawnSessionStart
• packages/agentpool/src/agentpool/agents/events/events.py — 事件定义：SubAgentEvent（line 614）、SpawnSessionStart（line 646）

相关 RFC¶

• RFC-0013: Subagent Event Stream Unification for OpenCode Protocol
• RFC-0014: SpawnSessionStart Event for Explicit Subsession Creation
• RFC-0025: Shared Agent Architecture
• RFC-0026: Per-Session Agent Isolation

ACP 协议¶

• ACP 协议官网
• ACP 扩展性文档
• ACP Proxy Chains RFD