langchain-agentx-python 2.0.1__py3-none-any.whl → 2.1.1__py3-none-any.whl

langchain_agentx/__init__.py

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

langchain_agentx/loop/graph/graph_edges.py

@@ -70,7 +70,6 @@ from ..exit.reason_codes import (
     TRANSITION_MAX_OUTPUT_TOKENS_ESCALATE,
     TRANSITION_MAX_OUTPUT_TOKENS_RECOVERY,
     TRANSITION_MAX_OUTPUT_TOKENS_RECOVERY_EXHAUSTED,
-    TRANSITION_REACTIVE_COMPACT_RETRY,
     TRANSITION_STOP_HOOK_BLOCKING,
     TRANSITION_STOP_HOOK_PREVENTED,
     TRANSITION_TASK_NOTIFICATION_ARRIVED,
@@ -452,6 +451,8 @@ class LoopControllerEdge:
             step=state.get("step", 0),
             turn_count=int(state.get("turn_count", 0) or 0),
             provider_finish_reason=state.get("finish_reason"),
+            error_kind="context_window",
+            recovery_exhausted=True,
         )
         state["transition"] = {
             "reason": TRANSITION_CONTEXT_WINDOW_RECOVERY_EXHAUSTED,
@@ -585,23 +586,6 @@ class LoopControllerEdge:
                 state,
                 destination=self._model_destination,
             )
-        if not state.get("has_attempted_reactive_compact", False):
-            state["has_attempted_reactive_compact"] = True
-            state["transition"] = {
-                "reason": TRANSITION_REACTIVE_COMPACT_RETRY,
-                "error_reason": withheld_error.get("reason"),
-            }
-            emit_loop_decision_event(
-                state=state,
-                decision="continue",
-                selected_edge=self._model_destination,
-                reason_code="reactive_compact_retry",
-                evidence={"withheld_error": withheld_error, "step": state.get("step", 0)},
-            )
-            return self._set_continue_resolution(
-                state,
-                destination=self._model_destination,
-            )
         state["transition"] = {
             "reason": TRANSITION_WITHHOLD_RECOVERY_RETRY,
             "error_reason": withheld_error.get("reason"),

langchain_agentx/loop/graph/reactive_compact_node.py

@@ -171,6 +171,7 @@ class ReactiveCompactNode:
         terminal = build_loop_terminal(
             reason=TERMINAL_REASON_MAX_TOKENS,
             error_kind="context_window",
+            recovery_exhausted=True,
         )
         patch = {
             STATE_HAS_ATTEMPTED_REACTIVE_COMPACT: True,

langchain_agentx/loop/model/model_node.py

@@ -1248,6 +1248,29 @@ class ModelNode(Runnable):
             and max_output_tokens_override is not None
             and max_output_tokens_recovery_count < MAX_OUTPUT_TOKENS_RECOVERY_LIMIT
         )
+        if (
+            should_end
+            and terminal_reason in RECOVERABLE_TERMINAL_REASONS
+            and overflow_kind == "context_window"
+        ):
+            withheld_error = build_withheld_error(
+                terminal_reason=terminal_reason,
+                finish_reason=finish_reason,
+                last_ai_message=last_ai_message,
+            )
+            return {
+                "should_end": False,
+                "terminal_reason": None,
+                "withheld_error": withheld_error,
+                "withhold_retry_count": withhold_retry_count,
+                "max_output_tokens_override": max_output_tokens_override,
+                "max_output_tokens_recovery_count": max_output_tokens_recovery_count,
+                "transition": {
+                    "reason": TRANSITION_WITHHOLD_RECOVERY_RETRY,
+                    "error_reason": withheld_error["reason"],
+                    "attempt": withhold_retry_count,
+                },
+            }
         if should_end and terminal_reason in RECOVERABLE_TERMINAL_REASONS and (
             can_default_withhold_retry or can_max_tokens_recovery_retry
         ):

langchain_agentx/loop/stream/loop_driver.py

@@ -10,6 +10,7 @@ loop_driver.py — Loop-aware shared stream driver.
 当前裁剪范围：
     root closeout 捕获、synthetic error/finish、orphan tool_result repair（stream surface）。
     正常结束但缺 root on_chain_end(LangGraph) 时打 anomaly WARNING（不伪造 synthetic finish）。
+    R1 反应恢复：单次 drain 内 budgeted continue 重入（S2，对齐 CC queryLoop continue）。
 """
 
 from __future__ import annotations
@@ -23,6 +24,7 @@ from langgraph.errors import GraphRecursionError
 from ..exit.reason_codes import (
     TERMINAL_REASON_GRAPH_RUNTIME_ERROR,
     TERMINAL_REASON_RUNTIME_BUDGET_EXHAUSTED,
+    TRANSITION_REACTIVE_COMPACT_RETRY,
 )
 from ..exit.terminal import apply_terminal_reason_projection, build_loop_terminal, read_terminal_reason
 from langchain_agentx.observability.events.tool_call_id_resolver import ToolCallIdResolver
@@ -57,6 +59,7 @@ class LoopStreamDriver:
         *,
         config: dict[str, Any] | None = None,
         version: str = "v2",
+        max_reactive_continue_per_drain: int = 0,
     ) -> AsyncIterator[dict[str, Any]]:
         self._graph_input = dict(graph_input)
         self._assistant_turn_count = 0
@@ -66,83 +69,173 @@ class LoopStreamDriver:
         self.result.last_raw_event = None
         self.result.saw_chat_model_end_last_turn = False
         self.result.saw_partial_superseded = False
+        self.result.reactive_continue_drains = 0
+        current_input = dict(graph_input)
+        reactive_continues = 0
         try:
-            try:
-                async for event in graph.astream_events(
-                    graph_input,
+            while True:
+                async for event in self._stream_single_drain(
+                    graph,
+                    current_input,
                     config=config,
                     version=version,
                 ):
-                    self._observe_event(event)
                     yield event
-                self.result.graph_completed = True
-                self._log_missing_root_chain_end_anomaly()
-            except asyncio.CancelledError as exc:
-                self.result.final_error = exc
-                for repair in self._orphan_tool_result_repairs(closeout_kind="cancelled"):
-                    yield repair
-                raise
-            except GraphRecursionError as exc:
-                self.result.final_error = exc
-                self._log_catch_error(exc)
-                for repair in self._orphan_tool_result_repairs(closeout_kind="interrupted"):
-                    yield repair
-                if not self.result.saw_error_visible_surface:
-                    self.result.saw_error_visible_surface = True
-                    yield build_synthetic_error_visible_event(
-                        message="Runtime budget exhausted (recursion limit reached)",
-                        error_kind="graph_recursion_error",
-                    )
-                if not self.result.saw_finish_surface:
-                    terminal = build_loop_terminal(
-                        reason=TERMINAL_REASON_RUNTIME_BUDGET_EXHAUSTED,
-                        error_kind="graph_recursion_error",
-                        step=(self.result.last_loop_snapshot or {}).get("step"),
-                        turn_count=(self.result.last_loop_snapshot or {}).get("turn_count"),
-                        provider_finish_reason=(self.result.last_loop_snapshot or {}).get("finish_reason"),
-                        errors=[str(exc)],
-                        metadata={
-                            "langgraph_error_type": "GraphRecursionError",
-                        },
-                    )
-                    self.result.terminal = terminal
-                    synthetic_output = self._build_synthetic_graph_output(terminal)
-                    self.result.graph_output = synthetic_output
-                    self.result.saw_finish_surface = True
-                    yield build_synthetic_root_chain_end(graph_output=synthetic_output)
-                self._log_catch_error_diagnostic(exc)
-                raise
-            except Exception as exc:
-                self.result.final_error = exc
-                # CC catch 协议 §5.3.3：先记录日志 / 观测，再补 stream surface，最后 re-raise
-                self._log_catch_error(exc)
-                for repair in self._orphan_tool_result_repairs(closeout_kind="interrupted"):
-                    yield repair
-                if not self.result.saw_error_visible_surface:
-                    self.result.saw_error_visible_surface = True
-                    yield build_synthetic_error_visible_event(
-                        message=str(exc),
-                        error_kind="graph_runtime_error",
-                    )
-                if not self.result.saw_finish_surface:
-                    terminal = build_loop_terminal(
-                        reason=TERMINAL_REASON_GRAPH_RUNTIME_ERROR,
-                        error_kind="graph_runtime_error",
-                        step=(self.result.last_loop_snapshot or {}).get("step"),
-                        turn_count=(self.result.last_loop_snapshot or {}).get("turn_count"),
-                        provider_finish_reason=(self.result.last_loop_snapshot or {}).get("finish_reason"),
-                        errors=[str(exc)],
-                    )
-                    self.result.terminal = terminal
-                    synthetic_output = self._build_synthetic_graph_output(terminal)
-                    self.result.graph_output = synthetic_output
-                    self.result.saw_finish_surface = True
-                    yield build_synthetic_root_chain_end(graph_output=synthetic_output)
-                self._log_catch_error_diagnostic(exc)
-                raise
+                if not self._should_reactive_continue_drain(
+                    continues_used=reactive_continues,
+                    max_continues=max_reactive_continue_per_drain,
+                ):
+                    break
+                reactive_continues += 1
+                self.result.reactive_continue_drains = reactive_continues
+                current_input = self._build_continue_graph_input(
+                    current_input,
+                    self.result.graph_output or {},
+                )
+                self._graph_input = dict(current_input)
+                self._reset_for_continue_drain()
+                logger.info(
+                    "LoopStreamDriver R1 continue: drain %s/%s transition=%s",
+                    reactive_continues,
+                    max_reactive_continue_per_drain,
+                    (self.result.graph_output or {}).get("transition", {}).get("reason"),
+                )
         finally:
             self._log_stream_closeout_summary()
 
+    async def _stream_single_drain(
+        self,
+        graph: Any,
+        graph_input: dict[str, Any],
+        *,
+        config: dict[str, Any] | None = None,
+        version: str = "v2",
+    ) -> AsyncIterator[dict[str, Any]]:
+        try:
+            async for event in graph.astream_events(
+                graph_input,
+                config=config,
+                version=version,
+            ):
+                self._observe_event(event)
+                yield event
+            self.result.graph_completed = True
+            self._log_missing_root_chain_end_anomaly()
+        except asyncio.CancelledError as exc:
+            self.result.final_error = exc
+            for repair in self._orphan_tool_result_repairs(closeout_kind="cancelled"):
+                yield repair
+            raise
+        except GraphRecursionError as exc:
+            self.result.final_error = exc
+            self._log_catch_error(exc)
+            for repair in self._orphan_tool_result_repairs(closeout_kind="interrupted"):
+                yield repair
+            if not self.result.saw_error_visible_surface:
+                self.result.saw_error_visible_surface = True
+                yield build_synthetic_error_visible_event(
+                    message="Runtime budget exhausted (recursion limit reached)",
+                    error_kind="graph_recursion_error",
+                )
+            if not self.result.saw_finish_surface:
+                terminal = build_loop_terminal(
+                    reason=TERMINAL_REASON_RUNTIME_BUDGET_EXHAUSTED,
+                    error_kind="graph_recursion_error",
+                    step=(self.result.last_loop_snapshot or {}).get("step"),
+                    turn_count=(self.result.last_loop_snapshot or {}).get("turn_count"),
+                    provider_finish_reason=(self.result.last_loop_snapshot or {}).get("finish_reason"),
+                    errors=[str(exc)],
+                    metadata={
+                        "langgraph_error_type": "GraphRecursionError",
+                    },
+                )
+                self.result.terminal = terminal
+                synthetic_output = self._build_synthetic_graph_output(terminal)
+                self.result.graph_output = synthetic_output
+                self.result.saw_finish_surface = True
+                yield build_synthetic_root_chain_end(graph_output=synthetic_output)
+            self._log_catch_error_diagnostic(exc)
+            raise
+        except Exception as exc:
+            self.result.final_error = exc
+            # CC catch 协议 §5.3.3：先记录日志 / 观测，再补 stream surface，最后 re-raise
+            self._log_catch_error(exc)
+            for repair in self._orphan_tool_result_repairs(closeout_kind="interrupted"):
+                yield repair
+            if not self.result.saw_error_visible_surface:
+                self.result.saw_error_visible_surface = True
+                yield build_synthetic_error_visible_event(
+                    message=str(exc),
+                    error_kind="graph_runtime_error",
+                )
+            if not self.result.saw_finish_surface:
+                terminal = build_loop_terminal(
+                    reason=TERMINAL_REASON_GRAPH_RUNTIME_ERROR,
+                    error_kind="graph_runtime_error",
+                    step=(self.result.last_loop_snapshot or {}).get("step"),
+                    turn_count=(self.result.last_loop_snapshot or {}).get("turn_count"),
+                    provider_finish_reason=(self.result.last_loop_snapshot or {}).get("finish_reason"),
+                    errors=[str(exc)],
+                )
+                self.result.terminal = terminal
+                synthetic_output = self._build_synthetic_graph_output(terminal)
+                self.result.graph_output = synthetic_output
+                self.result.saw_finish_surface = True
+                yield build_synthetic_root_chain_end(graph_output=synthetic_output)
+            self._log_catch_error_diagnostic(exc)
+            raise
+
+    def _should_reactive_continue_drain(
+        self,
+        *,
+        continues_used: int,
+        max_continues: int,
+    ) -> bool:
+        if max_continues <= 0 or continues_used >= max_continues:
+            return False
+        if self.result.final_error is not None:
+            return False
+        if not self.result.saw_root_chain_end or not self.result.graph_completed:
+            return False
+        output = self.result.graph_output
+        if not isinstance(output, dict):
+            return False
+        resolution = output.get("resolution")
+        if not isinstance(resolution, dict) or resolution.get("kind") != "continue":
+            return False
+        transition = resolution.get("transition")
+        if not isinstance(transition, dict):
+            transition = output.get("transition")
+        if not isinstance(transition, dict):
+            return False
+        return transition.get("reason") == TRANSITION_REACTIVE_COMPACT_RETRY
+
+    def _build_continue_graph_input(
+        self,
+        prior_input: dict[str, Any],
+        graph_output: dict[str, Any],
+    ) -> dict[str, Any]:
+        continued = dict(prior_input)
+        messages = graph_output.get("messages")
+        if isinstance(messages, list):
+            continued["messages"] = list(messages)
+        for key in (
+            "has_attempted_reactive_compact",
+            "_session_id",
+            "_run_id",
+            "_trace_collector",
+        ):
+            if key in graph_output:
+                continued[key] = graph_output[key]
+        return continued
+
+    def _reset_for_continue_drain(self) -> None:
+        self._pending_tool_calls.clear()
+        self.result.saw_root_chain_end = False
+        self.result.saw_finish_surface = False
+        self.result.graph_completed = False
+        self.result.final_error = None
+
     def _observe_event(self, event: dict[str, Any]) -> None:
         event_name = str(event.get("event") or "")
         name = str(event.get("name") or "")

langchain_agentx/loop/stream/result.py

@@ -31,6 +31,7 @@ class StreamDriverResult:
     last_raw_event: str | None = None
     saw_chat_model_end_last_turn: bool = False
     saw_partial_superseded: bool = False
+    reactive_continue_drains: int = 0
 
 
 __all__ = ["StreamDriverResult"]

langchain_agentx/loop/subagent/context.py

@@ -29,6 +29,12 @@ from collections.abc import Callable
 from dataclasses import dataclass, field
 from typing import Any, Literal
 
+from langchain_agentx.observability.events.finish_outcome import (
+    RecoveryPolicy,
+    RecoveryPolicyMode,
+    coerce_recovery_policy,
+)
+
 from langchain_agentx.loop.context.query_source import LoopCompilationContext
 from langchain_agentx.loop.exit.query_source import QuerySource
 from langchain_agentx.loop.runtime.subagent_execution_paths import (
@@ -85,7 +91,7 @@ class SubagentContext:
     parent_tool_call_id: str | None = None  # 触发本子 Agent 的 tool_call_id
     parent_conversation_session_id: str | None = None
     enable_trace: bool = True
-    runnable_config: Any = None  # 父 graph 的 runnable_config，用于子 graph 事件自动冒泡到父 graph
+    runnable_config: Any = None  # 父 runnable_config：仅供 tool_progress custom event 回调链；非子 raw 合并
     isolation: str = "none"
     worktree_dir: str | None = None
     workspace_root: str = ""
@@ -107,6 +113,9 @@ class SubagentContext:
     # Thinking 控制字段（request-side 生成意图，与 UI 展示意图分离）
     thinking_generation_enabled: bool = True  # 子代理 request-side thinking 生成开关
 
+    # R1 恢复策略（S4→S2；None 在 runner 层按 interactive 解析）
+    recovery: RecoveryPolicy | None = None
+
 
 @dataclass
 class SubagentResult:
@@ -150,6 +159,7 @@ def create_subagent_context(
     thinking_generation_enabled: bool = True,
     query_source: str | None = None,
     is_builtin_subagent: bool = False,
+    recovery: RecoveryPolicy | RecoveryPolicyMode | None = None,
 ) -> SubagentContext:
     """工厂函数：从父上下文创建子 Agent 上下文
 
@@ -285,6 +295,14 @@ def create_subagent_context(
         effective_cwd=effective_cwd,
     )
 
+    resolved_recovery: RecoveryPolicy | None = None
+    if recovery is not None:
+        resolved_recovery = coerce_recovery_policy(recovery)
+    else:
+        parent_recovery = getattr(parent_ctx, "recovery", None)
+        if isinstance(parent_recovery, (RecoveryPolicy, str)):
+            resolved_recovery = coerce_recovery_policy(parent_recovery)
+
     return SubagentContext(
         agent_id=agent_id,
         initial_messages=initial_messages,
@@ -317,6 +335,7 @@ def create_subagent_context(
         available_tools=list(available_tools or []),
         thinking_generation_enabled=thinking_generation_enabled,
         query_source=resolved_query_source,
+        recovery=resolved_recovery,
     )
 
 

langchain_agentx/loop/subagent/orchestrator.py

@@ -307,7 +307,8 @@ class SubagentOrchestrator:
     ) -> "AgentToolOutput":
         """异步执行子代理。
 
-        子 graph 事件通过 config 自动冒泡到父 graph，无需手动回调。
+        子 graph 在独立 LoopStreamDriver 消费（Phase-4）；progress 经 custom event 冒泡，
+        裸子 on_tool_* 不并进父 astream。
         """
         from langchain_agentx.tools.agent.models import AgentToolOutput
 
@@ -595,7 +596,7 @@ class SubagentOrchestrator:
     ) -> Any:
         """异步启动子 agent。
 
-        子 graph 事件通过 config 自动冒泡到父 graph。
+        子 graph Phase-4 独立 Driver 消费；progress 经 custom event 冒泡到父流。
         """
         owner_run_ctx = get_run_context()
         handle = self._register_background_agent(

langchain_agentx/loop/subagent/runner.py

@@ -55,6 +55,11 @@ from langchain_agentx.loop.message_contract import (
     is_synthetic_transcript_tool_id,
     to_record,
 )
+from langchain_agentx.observability.events.finish_outcome import (
+    RecoveryPolicy,
+    RecoveryPolicyMode,
+    coerce_recovery_policy,
+)
 from langchain_agentx.observability.events.tool_call_id_resolver import ToolCallIdResolver
 from langchain_agentx.observability.events.tool_outcome_resolver import (
     error_message_for_outcome,
@@ -221,7 +226,7 @@ async def _emit_progress(
     """发射子 Agent teaser lane 到父 graph（CC 对齐：仅 tool_use / tool_result）。
 
     同步 dispatch 优先：并行线程池 / _run_coroutine_sync 子线程内 adispatch 无法触达父回调链。
-    父 graph 的 config 通过 ctx.runnable_config 传递（在 _collect_subagent_events 中合并）。
+    父 config 经 ctx.runnable_config 仅服务 custom event 派发（Phase-4 不合并父 callbacks）。
     """
     if event.type not in ("tool_use", "tool_result"):
         return
@@ -504,6 +509,7 @@ async def _collect_subagent_events(
     run_tags: list[str],
     transcript: SubagentTranscriptManager,
     trace: SubagentExecutionTrace,
+    recovery: RecoveryPolicy | RecoveryPolicyMode | None = None,
 ) -> _EventCollectionResult:
     collected_assistant_messages: list[Any] = []
     terminal_reason = "completed"
@@ -533,12 +539,16 @@ async def _collect_subagent_events(
                     config["configurable"] = dict(configurable)
 
     try:
+        recovery_policy = coerce_recovery_policy(
+            recovery if recovery is not None else ctx.recovery
+        )
         driver = LoopStreamDriver()
         async for event in driver.run(
             graph,
             graph_input,
             config=config,
             version="v2",
+            max_reactive_continue_per_drain=recovery_policy.reactive_continue_budget(),
         ):
             event_name = event.get("event", "")
             data = event.get("data") or {}
@@ -667,6 +677,7 @@ async def run_subagent(
     loader: Any,
     model: Any | None = None,
     allowed_tool_names: set[str] | None = None,
+    recovery: RecoveryPolicy | RecoveryPolicyMode | None = None,
 ) -> SubagentResult:
     """运行子 Agent（plain/fork 同步路径）。
 
@@ -715,6 +726,7 @@ async def run_subagent(
             run_tags=run_tags,
             transcript=transcript,
             trace=trace,
+            recovery=recovery,
         )
         return await _build_subagent_result(
             ctx=ctx,

langchain_agentx/observability/__init__.py

@@ -12,7 +12,9 @@ from .events import (
     LangGraphToLangchainAgentEventAdapter,
     RecoveryAction,
     RecoveryActionResolver,
+    RecoveryPolicy,
     RecoveryPolicyMode,
+    coerce_recovery_policy,
     create_langgraph_event_adapter,
     enrich_run_result,
 )
@@ -69,7 +71,9 @@ __all__ = [
     "create_langgraph_event_adapter",
     "RecoveryAction",
     "RecoveryActionResolver",
+    "RecoveryPolicy",
     "RecoveryPolicyMode",
+    "coerce_recovery_policy",
     "enrich_run_result",
     "REASON_CODES",
     "export_call_chain",

langchain_agentx/observability/events/__init__.py

@@ -13,7 +13,9 @@ from .finish_outcome import (
     FinishOutcomeParser,
     RecoveryAction,
     RecoveryActionResolver,
+    RecoveryPolicy,
     RecoveryPolicyMode,
+    coerce_recovery_policy,
     enrich_run_result,
 )
 from .factory import (
@@ -32,7 +34,9 @@ __all__ = [
     "FinishOutcomeParser",
     "RecoveryAction",
     "RecoveryActionResolver",
+    "RecoveryPolicy",
     "RecoveryPolicyMode",
+    "coerce_recovery_policy",
     "enrich_run_result",
     "ILangGraphEventAdapter",
     "create_langgraph_event_adapter",

langchain_agentx/observability/events/agent_event_projector.py

@@ -219,6 +219,10 @@ class AgentEventProjector:
         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)
+        # Doc-34 F5：活跃子窗内抑制非 Agent 主台 tool-*（默认 on；关则恢复旧投影）
+        self.suppress_subagent_child_main_tier_tools: bool = bool(
+            config.get("suppress_subagent_child_main_tier_tools", True)
+        )
         self.filter_unparented_subgraph_events: bool = config.get(
             "filter_unparented_subgraph_events", False
         )
@@ -528,9 +532,17 @@ class AgentEventProjector:
             self._sync_accumulated_answer_mirror()
 
     def _should_suppress_main_tier_text_stream(self) -> bool:
-        """D28 SDK-1：子 Agent 窗口内不 emit 父 main-tier TEXT_* / REASONING_*。"""
+        """Doc-33：子 Agent 窗口内不 emit 父 main-tier TEXT_* / REASONING_*。"""
         return self.state.subagent_window_text_guard.should_suppress_main_tier_stream
 
+    def _should_suppress_main_tier_child_tool_events(self, tool_name: str) -> bool:
+        """Doc-34 F2/F3/F5：flag on 且非 Agent 且 open_runs>0 → 抑制主台 tool-*。"""
+        if not self.suppress_subagent_child_main_tier_tools:
+            return False
+        if self._is_agent_tool(tool_name):
+            return False
+        return self.state.subagent_window_text_guard.should_suppress_main_tier_tool_events
+
     def _on_subagent_start_boundary(self) -> None:
         self.state.subagent_window_text_guard.on_subagent_start()
 
@@ -888,6 +900,7 @@ class AgentEventProjector:
                 messages=messages if isinstance(messages, list) else None,
             )
             self._closeout_saw_finish_emitted = True
+            self.state.subagent_window_text_guard.warn_if_unbalanced_at_finish(logger)
             yield self._event(
                 event_type=LangchainAgentEventType.FINISH,
                 data=finish_data,
@@ -1113,6 +1126,16 @@ class AgentEventProjector:
 
         self.state.current_tool = name
 
+        # Doc-34 F2：非 Agent 且窗开 → 在任何 TOOL_INPUT_* / TOOL_CALL 之前 return
+        if self._should_suppress_main_tier_child_tool_events(name):
+            self.state.subagent_window_text_guard.note_suppressed_child_tool_start()
+            logger.debug(
+                "Doc-34: suppress main-tier tool_start name=%s open_runs=%s",
+                name,
+                self.state.subagent_window_text_guard.open_runs,
+            )
+            return
+
         if self.enable_tool_input_start:
             yield self._event(
                 event_type=LangchainAgentEventType.TOOL_INPUT_START,
@@ -1192,6 +1215,11 @@ class AgentEventProjector:
         data = event.get("data", {}) or {}
         tool_call_id = ToolCallIdResolver.resolve_from_langgraph_tool_event(event)
 
+        # Doc-34 F2：窗内非 Agent 对称抑制 RESULT/ERROR（不碰 Agent end → on_subagent_end）
+        if self._should_suppress_main_tier_child_tool_events(name):
+            self.state.current_tool = None
+            return
+
         output = data.get("output")
 
         event_type, event_data = self._classify_tool_end_event(

langchain_agentx/observability/events/finish_outcome.py

@@ -54,6 +54,34 @@ FINISH_OUTCOME_KEYS = frozenset(
 RecoveryPolicyMode = Literal["interactive", "auto"]
 
 
+@dataclass(frozen=True)
+class RecoveryPolicy:
+    """Stream 恢复策略配置面（S4 消费方 → S2 LoopStreamDriver 注入）。
+
+    非 Session 编排 API：仅控制 R1 reactive continue 预算与 finish 消费模式。
+    """
+
+    mode: RecoveryPolicyMode = "interactive"
+    max_reactive_continue_per_drain: int = 1
+
+    def reactive_continue_budget(self) -> int:
+        """返回 LoopStreamDriver R1 continue 预算（interactive 禁用自动 continue）。"""
+        if self.mode == "interactive":
+            return 0
+        return self.max_reactive_continue_per_drain
+
+
+def coerce_recovery_policy(
+    recovery: RecoveryPolicy | RecoveryPolicyMode | None = None,
+) -> RecoveryPolicy:
+    """将消费方传入的 recovery 规范化为 RecoveryPolicy。"""
+    if recovery is None:
+        return RecoveryPolicy()
+    if isinstance(recovery, str):
+        return RecoveryPolicy(mode=recovery)
+    return recovery
+
+
 class RecoveryAction(str, Enum):
     """消费方建议动作（不含具体 UI 文案）。"""
 
@@ -248,6 +276,8 @@ __all__ = [
     "FinishOutcomeParser",
     "RecoveryAction",
     "RecoveryActionResolver",
+    "RecoveryPolicy",
     "RecoveryPolicyMode",
+    "coerce_recovery_policy",
     "enrich_run_result",
 ]