langchain-agentx-python 1.1.9__tar.gz → 1.2.1__tar.gz

{langchain-agentx-python-1.1.9/langchain_agentx_python.egg-info → langchain-agentx-python-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: langchain-agentx-python
-Version: 1.1.9
+Version: 1.2.1
 Summary: LangChain/LangGraph-based agent utilities for CodeBaseX.
 Author-email: GoodMood2008 <GoodMood2008@users.noreply.github.com>
 License:                                  Apache License

{langchain-agentx-python-1.1.9 → langchain-agentx-python-1.2.1}/langchain_agentx/__init__.py

@@ -11,7 +11,7 @@ from langchain_agentx import create_loop_agent
 ```
 """
 
-__version__ = "1.1.9"
+__version__ = "1.2.1"
 
 from .loop import (  # noqa: F401
     create_loop_agent,

{langchain-agentx-python-1.1.9 → langchain-agentx-python-1.2.1}/langchain_agentx/loop/subagent/__init__.py

@@ -44,6 +44,12 @@ from langchain_agentx.loop.subagent.transcript import (
     SubagentTranscriptStore,
 )
 from langchain_agentx.loop.subagent.graph import create_subagent_graph
+from langchain_agentx.loop.subagent.active_run_registry import (
+    ActiveSubagentRun,
+    SubagentActiveRunRegistry,
+    get_subagent_active_run_registry,
+    reset_subagent_active_run_registry,
+)
 
 __all__ = [
     "ForkedAgentResult",
@@ -67,6 +73,10 @@ __all__ = [
     "SubagentTranscriptManager",
     "SubagentTranscriptStore",
     "create_subagent_graph",
+    "ActiveSubagentRun",
+    "SubagentActiveRunRegistry",
+    "get_subagent_active_run_registry",
+    "reset_subagent_active_run_registry",
     # fork_boilerplate
     "FORK_BOILERPLATE_TAG",
     "FORK_DIRECTIVE_PREFIX",

langchain-agentx-python-1.2.1/langchain_agentx/loop/subagent/active_run_registry.py

@@ -0,0 +1,132 @@
+"""
+loop/subagent/active_run_registry.py — 子 Agent 活跃运行注册表
+
+职责：在 Agent 工具执行期间维护 tool_call_id ↔ (agent_id, subagent_type) 映射，
+      供 adapter 边界事件（subagent-start/end）与 progress 冒泡共用同一 agent_id。
+链路位置：AgentRuntimeTool / RuntimeToolExecutionEngine → registry → event adapter（Phase 3）。
+当前裁剪范围：进程内单例；同一 tool_call_id 下允许多 agent_id（并行子 run）。
+"""
+
+from __future__ import annotations
+
+import threading
+import uuid
+from dataclasses import dataclass
+from typing import Any
+
+_DEFAULT_REGISTRY: SubagentActiveRunRegistry | None = None
+
+
+@dataclass(frozen=True)
+class ActiveSubagentRun:
+    """单次 Agent 工具触发的子 run 关联键。"""
+
+    tool_call_id: str
+    agent_id: str
+    subagent_type: str
+
+
+class SubagentActiveRunRegistry:
+    """按 tool_call_id 注册/查询/注销活跃子 Agent run。"""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._by_tool_call_id: dict[str, list[ActiveSubagentRun]] = {}
+
+    def register(
+        self,
+        *,
+        tool_call_id: str,
+        agent_id: str,
+        subagent_type: str,
+    ) -> ActiveSubagentRun:
+        if not tool_call_id or not agent_id:
+            raise ValueError("tool_call_id and agent_id are required")
+        run = ActiveSubagentRun(
+            tool_call_id=tool_call_id,
+            agent_id=agent_id,
+            subagent_type=subagent_type,
+        )
+        with self._lock:
+            bucket = self._by_tool_call_id.setdefault(tool_call_id, [])
+            if not any(r.agent_id == agent_id for r in bucket):
+                bucket.append(run)
+        return run
+
+    def ensure(
+        self,
+        *,
+        tool_call_id: str,
+        subagent_type: str,
+        agent_id: str | None = None,
+    ) -> ActiveSubagentRun:
+        """注册或复用已有 run（同一 tool_call_id 下 idempotent）。"""
+        if not tool_call_id:
+            raise ValueError("tool_call_id is required")
+        with self._lock:
+            bucket = self._by_tool_call_id.get(tool_call_id, [])
+            if bucket:
+                return bucket[-1]
+        resolved_id = agent_id or str(uuid.uuid4())
+        return self.register(
+            tool_call_id=tool_call_id,
+            agent_id=resolved_id,
+            subagent_type=subagent_type,
+        )
+
+    def lookup(self, tool_call_id: str) -> list[ActiveSubagentRun]:
+        if not tool_call_id:
+            return []
+        with self._lock:
+            return list(self._by_tool_call_id.get(tool_call_id, ()))
+
+    def lookup_latest(self, tool_call_id: str) -> ActiveSubagentRun | None:
+        runs = self.lookup(tool_call_id)
+        return runs[-1] if runs else None
+
+    def unregister(self, *, tool_call_id: str, agent_id: str) -> None:
+        if not tool_call_id or not agent_id:
+            return
+        with self._lock:
+            bucket = self._by_tool_call_id.get(tool_call_id)
+            if not bucket:
+                return
+            self._by_tool_call_id[tool_call_id] = [
+                r for r in bucket if r.agent_id != agent_id
+            ]
+            if not self._by_tool_call_id[tool_call_id]:
+                del self._by_tool_call_id[tool_call_id]
+
+    def clear(self) -> None:
+        with self._lock:
+            self._by_tool_call_id.clear()
+
+
+def get_subagent_active_run_registry() -> SubagentActiveRunRegistry:
+    global _DEFAULT_REGISTRY
+    if _DEFAULT_REGISTRY is None:
+        _DEFAULT_REGISTRY = SubagentActiveRunRegistry()
+    return _DEFAULT_REGISTRY
+
+
+def reset_subagent_active_run_registry() -> SubagentActiveRunRegistry:
+    """测试隔离：重置为全新 registry 实例。"""
+    global _DEFAULT_REGISTRY
+    _DEFAULT_REGISTRY = SubagentActiveRunRegistry()
+    return _DEFAULT_REGISTRY
+
+
+def resolve_subagent_type_from_raw_args(raw_args: dict[str, Any]) -> str:
+    subagent_type = raw_args.get("subagent_type")
+    if isinstance(subagent_type, str) and subagent_type.strip():
+        return subagent_type.strip()
+    return "general-purpose"
+
+
+__all__ = [
+    "ActiveSubagentRun",
+    "SubagentActiveRunRegistry",
+    "get_subagent_active_run_registry",
+    "reset_subagent_active_run_registry",
+    "resolve_subagent_type_from_raw_args",
+]

{langchain-agentx-python-1.1.9 → langchain-agentx-python-1.2.1}/langchain_agentx/loop/subagent/context.py

@@ -131,6 +131,7 @@ def create_subagent_context(
     fork_from_parent: bool = False,
     is_async: bool = False,
     *,
+    agent_id: str | None = None,
     path_prep: PreparedSubagentPaths | None = None,
     inject_fork_worktree_notice: bool = False,
     fork_worktree_parent_cwd: str | None = None,
@@ -161,7 +162,7 @@ def create_subagent_context(
     Returns:
         SubagentContext 实例
     """
-    agent_id = str(uuid.uuid4())
+    agent_id = agent_id if isinstance(agent_id, str) and agent_id.strip() else str(uuid.uuid4())
     parent_run_id_raw = getattr(parent_ctx, "run_id", None)
     if not isinstance(parent_run_id_raw, str) or not parent_run_id_raw:
         parent_run_id_raw = getattr(parent_ctx, "session_id", None)

{langchain-agentx-python-1.1.9 → langchain-agentx-python-1.2.1}/langchain_agentx/loop/subagent/orchestrator.py

@@ -77,6 +77,7 @@ class SubagentOrchestrator:
         ctx: "ToolExecutionContext",
         subagent_config: "SubagentConfig",
         *,
+        agent_id: str | None = None,
         skill_allowed_tools: list[str] | None = None,
         skill_effort_override: str | None = None,
         force_sync: bool = False,
@@ -88,7 +89,7 @@ class SubagentOrchestrator:
         from langchain_agentx.tools.agent.models import AgentToolOutput
 
         log = self._build_logger(ctx)
-        child_agent_id = str(uuid.uuid4())
+        child_agent_id = agent_id if isinstance(agent_id, str) and agent_id.strip() else str(uuid.uuid4())
 
         parent_registry = getattr(ctx, "tool_registry", None)
         if parent_registry is None or not hasattr(parent_registry, "list"):
@@ -176,13 +177,13 @@ class SubagentOrchestrator:
                 fork_from_parent=(self._mode == "fork"),
                 is_async=is_async,
                 model=runtime_ctx.model,
+                agent_id=child_agent_id,
                 path_prep=prepared,
                 inject_fork_worktree_notice=inject_fork_wt,
                 fork_worktree_parent_cwd=parent_notice_cwd,
                 fork_worktree_path=prepared.worktree_dir,
                 available_tools=runtime_tools,
             )
-            subagent_ctx.agent_id = child_agent_id
             scope = propagate_subagent_tool_scope(
                 parent_ctx=ctx,
                 subagent_config=subagent_config,
@@ -270,6 +271,7 @@ class SubagentOrchestrator:
         ctx: "ToolExecutionContext",
         subagent_config: "SubagentConfig",
         *,
+        agent_id: str | None = None,
         skill_allowed_tools: list[str] | None = None,
         skill_effort_override: str | None = None,
         force_sync: bool = False,
@@ -281,7 +283,7 @@ class SubagentOrchestrator:
         from langchain_agentx.tools.agent.models import AgentToolOutput
 
         log = self._build_logger(ctx)
-        child_agent_id = str(uuid.uuid4())
+        child_agent_id = agent_id if isinstance(agent_id, str) and agent_id.strip() else str(uuid.uuid4())
 
         parent_registry = getattr(ctx, "tool_registry", None)
         if parent_registry is None or not hasattr(parent_registry, "list"):
@@ -368,13 +370,13 @@ class SubagentOrchestrator:
                 fork_from_parent=(self._mode == "fork"),
                 is_async=is_async,
                 model=runtime_ctx.model,
+                agent_id=child_agent_id,
                 path_prep=prepared,
                 inject_fork_worktree_notice=inject_fork_wt,
                 fork_worktree_parent_cwd=parent_notice_cwd,
                 fork_worktree_path=prepared.worktree_dir,
                 available_tools=runtime_tools,
             )
-            subagent_ctx.agent_id = child_agent_id
             scope = propagate_subagent_tool_scope(
                 parent_ctx=ctx,
                 subagent_config=subagent_config,

{langchain-agentx-python-1.1.9 → langchain-agentx-python-1.2.1}/langchain_agentx/loop/subagent/progress.py

@@ -75,20 +75,17 @@ class SubagentExecutionTrace:
 
 @dataclass
 class SubagentProgressEvent:
-    """子 Agent 进度事件
+    """子 Agent 进度事件（runner 内部 + trace 记录）。
 
     type 枚举：
-    - tool_use: 工具调用开始
-    - tool_result: 工具调用结束
-    - model_step: 模型推理完成
+    - tool_use / tool_result: 对外 SSE 冒泡（经 _emit_progress → tool_progress）
+    - model_step: internal/trace-only，不 emit 到父 SSE（CC：Thinking 不折叠）
     - hint: 后台化提示（v2）
-    - completed: 子 Agent 正常完成
-    - error: 子 Agent 以错误终态结束（含可恢复类 max_tokens 等）
+    - completed / error: internal/trace-only；边界由 adapter SUBAGENT_END 表达
 
     与 CC 对齐：
-    - CC 的 ProgressMessage 包含完整的 message 对象（assistant/user 消息）
-    - 本 SDK 通过 tool_call_detail 携带工具调用的详细信息
-    - parent_tool_use_id 用于事件冒泡，标识父级工具调用
+    - CC AgentTool.tsx 仅 forward tool_use/tool_result（L1106-1108）
+    - 本 SDK 通过 tool_call_detail 携带工具调用的详细信息（present_for_display / trace）
     """
     type: Literal["tool_use", "tool_result", "model_step", "hint", "completed", "error"]
     subagent_type: str = ""
@@ -97,9 +94,5 @@ class SubagentProgressEvent:
     tool_name: str = ""
     summary: str = ""
     meta: dict[str, Any] = field(default_factory=dict)
-    # 新增：工具调用详情（用于 present_for_display 展示）
     tool_call_detail: SubagentToolCall | None = None
-    # 新增：执行轨迹引用（共享状态）
     trace: SubagentExecutionTrace | None = None
-    # 新增：父级 tool_use_id，用于事件冒泡（CC 对齐）
-    parent_tool_use_id: str | None = None

{langchain-agentx-python-1.1.9 → langchain-agentx-python-1.2.1}/langchain_agentx/loop/subagent/runner.py

@@ -11,14 +11,17 @@ CC 对照：runAgent.ts runAgent()；onProgress 回调逻辑
   2. 构造 SubagentTranscriptManager（InMemoryTranscriptStore）
   3. create_subagent_graph(ctx, tools, model) 创建子图
   4. 将 ctx.initial_messages 转为 LangChain HumanMessage 列表作为图输入
-  5. astream_events 循环（单线收集，CC agentMessages 累积模式）：
+  5. **独立 LoopStreamDriver 消费子 graph**（Phase 4 隔离 SSOT）：
+       子 graph 的 on_chat_model_stream / 裸 tool-call 等 **不 yield 到父 adapter 流**；
+       父 SSE 仅见 adispatch_custom_event("tool_progress") 冒泡 + 父 graph 自身事件。
+       见 _collect_subagent_events 内 LoopStreamDriver.run() 注释。
        on_tool_start      → on_progress(tool_use)
        on_tool_end        → on_progress(tool_result) + transcript.append()
-       on_chat_model_end  → 累积 assistant 消息 + total_steps 计数 + on_progress(model_step)
+       on_chat_model_end  → 累积 assistant 消息 + total_steps 计数（不上 SSE）
        on_chain_end(LangGraph) → 提取 terminal_reason 与 loop 快照（transition / withheld_error）
   6. 从累积的 assistant 消息中提取最终内容（CC finalizeAgentTool 语义）
   7. SubagentTerminationClassifier 对齐主 Agent finish payload 终态语义
-  8. on_progress(completed|error)，返回 SubagentResult
+  8. 返回 SubagentResult（边界 completed/error 由 adapter SUBAGENT_END 表达，不经 tool_progress）
   try/finally：确保 transcript.cleanup() + cleanup_subagent_context() 必然执行
 """
 
@@ -213,11 +216,21 @@ async def _emit_progress(
     ctx: SubagentContext,
     event: SubagentProgressEvent,
 ) -> None:
-    """发射子 Agent 进度事件到父 graph。
+    """发射子 Agent 工具进度到父 graph（CC 对齐：仅 tool_use / tool_result）。
 
     通过 adispatch_custom_event 将子 agent 事件冒泡到父 graph 的 astream_events 流。
     父 graph 的 config 通过 ctx.runnable_config 传递（在 _collect_subagent_events 中合并）。
     """
+    if event.type not in ("tool_use", "tool_result"):
+        return
+    if not event.tool_name:
+        logger.debug(
+            "skip subagent progress emit: empty tool_name phase=%s agent_id=%s",
+            event.type,
+            event.agent_id,
+        )
+        return
+
     from langchain_core.callbacks import adispatch_custom_event
 
     parent_config = getattr(ctx, "runnable_config", None)
@@ -228,15 +241,14 @@ async def _emit_progress(
         await adispatch_custom_event(
             name="tool_progress",
             data={
-                "tool_name": event.tool_name or "Agent",
+                "tool_name": event.tool_name,
                 "tool_call_id": ctx.parent_tool_call_id,
                 "agent_id": event.agent_id,
                 "phase": event.type,
+                "step": event.step,
+                "summary": event.summary,
                 "data": {
                     "subagent_type": event.subagent_type,
-                    "summary": event.summary,
-                    "step": event.step,
-                    "parent_tool_use_id": event.parent_tool_use_id,
                 },
             },
             config=parent_config,
@@ -377,16 +389,6 @@ async def _handle_chat_model_end_event(
     has_tool_calls = bool(output is not None and getattr(output, "tool_calls", None))
     if not has_tool_calls:
         total_steps += 1
-        await _emit_progress(
-            ctx,
-            SubagentProgressEvent(
-                type="model_step",
-                subagent_type=ctx.subagent_type,
-                agent_id=ctx.agent_id,
-                step=total_steps,
-                summary="model responded",
-            ),
-        )
     return total_steps
 
 
@@ -441,7 +443,10 @@ async def _collect_subagent_events(
     tool_step = 0
     loop_snapshot: dict[str, Any] = {}
 
-    # 构建子 graph config：合并父 runnable_config 使事件自动冒泡
+    # Phase 4 架构隔离：子 graph 在独立 LoopStreamDriver 内消费 astream_events。
+    # 此处循环仅更新 trace/transcript 并经 _emit_progress → adispatch_custom_event 冒泡；
+    # 子 graph 的 text-delta / 裸 tool-call 等不会 yield 到父 graph 的 adapter 流（对齐 CC runAgent.ts）。
+    # 父 runnable_config 合并仅用于 custom event 回调链，非 subgraph 事件合并。
     config = {"tags": run_tags}
     parent_runnable_config = getattr(ctx, "runnable_config", None)
     if parent_runnable_config is not None:
@@ -563,35 +568,6 @@ async def _build_subagent_result(
         )
     # 更新 trace 的 terminal_reason
     trace.terminal_reason = collected.terminal_reason
-    if semantics.is_error:
-        if semantics.errors:
-            progress_summary = semantics.errors[0][:200]
-        elif collected.error_message:
-            progress_summary = collected.error_message[:200]
-        else:
-            progress_summary = f"subagent ended: {collected.terminal_reason}"
-        progress_type: Literal["completed", "error"] = "error"
-    else:
-        progress_summary = content[:200] if content else "done"
-        progress_type = "completed"
-    await _emit_progress(
-        ctx,
-        SubagentProgressEvent(
-            type=progress_type,
-            subagent_type=ctx.subagent_type,
-            agent_id=ctx.agent_id,
-            step=collected.total_steps,
-            summary=progress_summary,
-            meta={
-                "is_error": semantics.is_error,
-                "recoverable": semantics.recoverable,
-                "error_kind": semantics.error_kind,
-                "recovery_exhausted": semantics.recovery_exhausted,
-                "terminal_reason": collected.terminal_reason,
-            },
-            trace=trace,
-        ),
-    )
     return SubagentResult(
         agent_id=ctx.agent_id,
         content=content,

{langchain-agentx-python-1.1.9 → langchain-agentx-python-1.2.1}/langchain_agentx/observability/events/langchain_agentx_event_adapter.py

@@ -37,6 +37,10 @@ from langchain_agentx.observability.events.finish_event_payload_composer import
 from langchain_agentx.observability.events.tool_call_id_resolver import (
     ToolCallIdResolver,
 )
+from langchain_agentx.observability.events.subagent_event_mapper import (
+    SubagentBoundaryPayloadBuilder,
+    SubagentProgressEventMapper,
+)
 
 # out-of-band 投影平铺字段（与 envelope_to_event_artifact v1 对齐）
 _ARTIFACT_V1_EVENT_FIELDS: tuple[str, ...] = (
@@ -151,6 +155,10 @@ class EventAdapterState:
     # 工具级别
     current_tool: Optional[str] = None
     tool_input_chunks: list[str] = field(default_factory=list)
+    # Agent 工具边界：on_tool_end 时 registry 可能已 unregister，start 时快照
+    subagent_boundary_by_tool_call_id: Dict[str, Dict[str, str]] = field(
+        default_factory=dict
+    )
 
     # 本轮答案累积（用于在 finish 事件中携带完整 answer；优先 text，其次 reason，最后 on_chain_end）
     accumulated_answer: str = ""   # 仅累积 text（最后一轮 model）
@@ -208,12 +216,22 @@ class LangGraphToLangchainAgentEventAdapter:
         self.enable_subagent_events: bool = config.get("enable_subagent_events", True)
         self.synthesize_tool_call: bool = config.get("synthesize_tool_call", True)
         self.enable_tool_input_start: bool = config.get("enable_tool_input_start", False)
+        # Phase 4 防御性桩：未来 subgraph 合并模式可按 checkpoint_ns 深度过滤无父键子事件（默认关闭）
+        self.filter_unparented_subgraph_events: bool = config.get(
+            "filter_unparented_subgraph_events", False
+        )
         self._finish_payload_composer = FinishEventPayloadComposer()
 
     async def adapt(
         self, events: AsyncIterator[Dict[str, Any]]
     ) -> AsyncIterator[LangchainAgentEvent]:
-        """主转换函数：将 LangGraph 事件流转换为 LangChain AgentX 风格事件流。"""
+        """主转换函数：将 LangGraph 事件流转换为 LangChain AgentX 风格事件流。
+
+        方案 A 基线：本 adapter 仅消费**父 graph** astream_events。子 agent 活动经
+        runner._collect_subagent_events 独立 LoopStreamDriver 消费，除 tool_progress
+        custom event 外不进入主流。若未来启用 subgraph 合并，可设
+        filter_unparented_subgraph_events=True 按 checkpoint_ns 过滤（当前未实现）。
+        """
 
         async for event in events:
             event_type = event.get("event")
@@ -480,6 +498,48 @@ class LangGraphToLangchainAgentEventAdapter:
     def _is_agent_tool(self, name: str) -> bool:
         return name in self.agent_tool_names
 
+    def _resolve_subagent_boundary_keys(
+        self,
+        tool_call_id: str,
+        tool_input: dict[str, Any],
+    ) -> tuple[str, str]:
+        from langchain_agentx.loop.subagent.active_run_registry import (
+            get_subagent_active_run_registry,
+            resolve_subagent_type_from_raw_args,
+        )
+
+        subagent_type = resolve_subagent_type_from_raw_args(tool_input)
+        agent_id = ""
+        if tool_call_id:
+            run = get_subagent_active_run_registry().lookup_latest(tool_call_id)
+            if run is not None:
+                agent_id = run.agent_id
+                subagent_type = run.subagent_type
+        return agent_id, subagent_type
+
+    def _snapshot_subagent_boundary(
+        self,
+        *,
+        tool_call_id: str,
+        agent_id: str,
+        subagent_type: str,
+    ) -> None:
+        if not tool_call_id:
+            return
+        self.state.subagent_boundary_by_tool_call_id[tool_call_id] = {
+            "agent_id": agent_id,
+            "subagent_type": subagent_type,
+        }
+
+    def _pop_subagent_boundary_snapshot(
+        self,
+        tool_call_id: str,
+    ) -> tuple[str, str]:
+        if not tool_call_id:
+            return "", ""
+        snapshot = self.state.subagent_boundary_by_tool_call_id.pop(tool_call_id, {})
+        return snapshot.get("agent_id", ""), snapshot.get("subagent_type", "")
+
     def _hook_event_from_name(self, name: str) -> str:
         mapping = {
             "hook_loop_start": "loop_start",
@@ -1148,9 +1208,22 @@ class LangGraphToLangchainAgentEventAdapter:
             tool_name=name,
         )
         if self.enable_subagent_events and self._is_agent_tool(name):
+            agent_id, subagent_type = self._resolve_subagent_boundary_keys(
+                tool_call_id, tool_input
+            )
+            self._snapshot_subagent_boundary(
+                tool_call_id=tool_call_id,
+                agent_id=agent_id,
+                subagent_type=subagent_type,
+            )
             yield self._event(
                 event_type=LangchainAgentEventType.SUBAGENT_START,
-                data={"tool_name": name},
+                data=SubagentBoundaryPayloadBuilder.build_start(
+                    tool_name=name,
+                    tool_call_id=tool_call_id,
+                    agent_id=agent_id,
+                    subagent_type=subagent_type,
+                ),
                 step_index=self.state.step_index,
                 tool_name=name,
             )
@@ -1231,9 +1304,16 @@ class LangGraphToLangchainAgentEventAdapter:
             )
         if self.enable_subagent_events and self._is_agent_tool(name):
             child_session_id = self._extract_child_session_id_from_tool_output(output)
+            agent_id, subagent_type = self._pop_subagent_boundary_snapshot(tool_call_id)
             yield self._event(
                 event_type=LangchainAgentEventType.SUBAGENT_END,
-                data={"tool_name": name, "child_session_id": child_session_id},
+                data=SubagentBoundaryPayloadBuilder.build_end(
+                    tool_name=name,
+                    tool_call_id=tool_call_id,
+                    agent_id=agent_id,
+                    subagent_type=subagent_type,
+                    child_session_id=child_session_id,
+                ),
                 step_index=self.state.step_index,
                 tool_name=name,
                 session_id=str(child_session_id) if child_session_id else None,
@@ -1442,12 +1522,28 @@ class LangGraphToLangchainAgentEventAdapter:
             )
             return
 
-        # 主 agent 工具进度（Bash、WebSearch 等）— 不受 enable_subagent_events 影响
+        # tool_progress：先尝试 subagent 分流，再 fallback 主 agent TOOL_PROGRESS
         if event_name == "tool_progress":
             data = event.get("data", {})
             if not isinstance(data, dict):
                 return
 
+            if self.enable_subagent_events:
+                mapped = SubagentProgressEventMapper.map_custom_tool_progress(data)
+                if mapped is not None:
+                    yield self._event(
+                        event_type=mapped.event_type,
+                        data=mapped.data,
+                        step_index=self.state.step_index,
+                        tool_name=mapped.tool_name,
+                    )
+                    return
+                agent_id = data.get("agent_id")
+                if isinstance(agent_id, str) and agent_id.strip():
+                    phase = data.get("phase")
+                    if phase == "model_step":
+                        return
+
             yield self._event(
                 event_type=LangchainAgentEventType.TOOL_PROGRESS,
                 data={
@@ -1455,6 +1551,8 @@ class LangGraphToLangchainAgentEventAdapter:
                     "tool_call_id": data.get("tool_call_id", ""),
                     "agent_id": data.get("agent_id", ""),
                     "phase": data.get("phase", ""),
+                    "step": data.get("step", ""),
+                    "summary": data.get("summary", ""),
                     "data": data.get("data", {}),
                 },
                 step_index=self.state.step_index,
@@ -1465,55 +1563,22 @@ class LangGraphToLangchainAgentEventAdapter:
         if not self.enable_subagent_events:
             return
 
-        # 处理子 agent 事件（兼容旧的 subagent_progress）
-        if event_name != "subagent_progress":
-            return
-
-        data = event.get("data", {})
-        if not isinstance(data, dict):
-            return
-
-        event_type = data.get("type", "")
-        parent_tool_use_id = data.get("parent_tool_use_id")
-
-        # 映射到 SDK 事件类型
-        type_mapping = {
-            "tool_use": LangchainAgentEventType.SUBAGENT_TOOL_CALL,
-            "tool_result": LangchainAgentEventType.SUBAGENT_TOOL_RESULT,
-            "model_step": LangchainAgentEventType.SUBAGENT_MODEL_STEP,
-            "completed": None,  # 不发事件，由 SUBAGENT_END 表示
-        }
-
-        target_type = type_mapping.get(event_type)
-        if target_type is None:
+        # 遗留 subagent_progress（runner 已改用 tool_progress；保留兼容）
+        if event_name == "subagent_progress":
+            data = event.get("data", {})
+            if not isinstance(data, dict):
+                return
+            mapped = SubagentProgressEventMapper.map_legacy_subagent_progress(data)
+            if mapped is None:
+                return
+            yield self._event(
+                event_type=mapped.event_type,
+                data=mapped.data,
+                step_index=self.state.step_index,
+                tool_name=mapped.tool_name,
+            )
             return
 
-        event_data: Dict[str, Any] = {
-            "subagent_type": data.get("subagent_type", ""),
-            "agent_id": data.get("agent_id", ""),
-            "summary": data.get("summary", "")[:200],
-        }
-
-        if parent_tool_use_id:
-            event_data["parent_tool_use_id"] = parent_tool_use_id
-
-        if event_type == "tool_use":
-            event_data["tool_name"] = data.get("tool_name", "")
-            event_data["status"] = "running"
-            event_data["step"] = data.get("step", 0)
-        elif event_type == "tool_result":
-            event_data["tool_name"] = data.get("tool_name", "")
-            event_data["summary"] = data.get("summary", "")[:200]
-        elif event_type == "model_step":
-            event_data["text"] = data.get("summary", "")
-
-        yield self._event(
-            event_type=target_type,
-            data=event_data,
-            step_index=self.state.step_index,
-            tool_name=data.get("tool_name"),
-        )
-
 
 __all__ = [
     "LangchainAgentEventType",