agentengine-sdk-python 0.8.5__py3-none-any.whl → 0.8.6__py3-none-any.whl

ksadk/harness/engine/graph_builder.py

@@ -7,38 +7,47 @@
 
 from __future__ import annotations
 
-import os
-import re
-from typing import Any
+import logging
 
 from langgraph.graph import END, START, StateGraph
 from langgraph.types import interrupt
 
 from ksadk.harness.engine import budgets
 from ksadk.harness.engine.base import ExecutionEngineError
+from ksadk.harness.engine.hooked_reasoner import (
+    _HookedReasoner,
+    flush_hook_degradations,
+)
 from ksadk.harness.engine.langgraph import _GraphState
-from ksadk.harness.engine.mcp_disclosure import MCP_CALL_TOOL_TOOL, McpDisclosureCursors
 from ksadk.harness.engine.policy_runtime import revalidate_policy
 from ksadk.harness.engine.spans import wrap_node_span
-from ksadk.harness.engine.subagents import ChildApprovalPending
 from ksadk.harness.events import EventType
-from ksadk.harness.loop import (
-    ModelFailoverExhausted,
-    ReasonInput,
-    ToolCallInput,
-    execute_tool_calls,
-    reason_turn_async,
-)
-from ksadk.harness.loop.reason import ReasoningLimitError
 from ksadk.harness.reasoner import HarnessReasoningTurn
 from ksadk.harness.run_control import ControlAction, RunControlStop
 
-_DELEGATION_PREFACE = re.compile(
-    r"(?:\blet\s+me\s+(?:delegate|dispatch)|"
-    r"\bi\s+(?:will|'ll|am\s+going\s+to)\s+(?:delegate|dispatch)|"
-    r"(?:让我|我会|我将|接下来|准备|正在)(?:先)?(?:并行)?(?:派发|分派|调度|处理).{0,80}(?:子任务|子智能体|subtasks?))",
-    re.IGNORECASE,
-)
+logger = logging.getLogger(__name__)
+
+
+def _model_failure_error(error: ModelFailoverExhausted) -> RuntimeError:
+    """Preserve provider failure facts when the graph boundary wraps errors.
+
+    The graph engine exposes a plain exception to its outer runner for
+    compatibility, but Studio still needs the stable category and HTTP status
+    to render an actionable terminal card (especially rate limit 429).
+    """
+
+    wrapped = RuntimeError(str(error))
+    failure = error.failure
+    # Unknown-kind failures keep the legacy payload shape (no error_category)
+    # so sub-agent dispatch still falls back to "child_failed" and applies its
+    # retry policy; only classified failures carry their category upstream.
+    if failure.kind.value != "unknown":
+        setattr(wrapped, "error_category", failure.kind.value)
+    if failure.status_code is not None:
+        setattr(wrapped, "status_code", failure.status_code)
+    if failure.kind.value == "rate_limit":
+        setattr(wrapped, "error_code", "MODEL_RATE_LIMITED")
+    return wrapped
 
 
 def build_graph(engine, run):
@@ -56,8 +65,11 @@ def build_graph(engine, run):
         if event.event_type == EventType.USAGE_REPORTED:
             input_tokens = int(event.payload.get("input_tokens") or 0)
             output_tokens = int(event.payload.get("output_tokens") or 0)
-            budgets.spend(run, "tokens", int(event.payload.get("total_tokens") or
-                                             input_tokens + output_tokens))
+            budgets.spend(
+                run,
+                "tokens",
+                int(event.payload.get("total_tokens") or input_tokens + output_tokens),
+            )
             budgets.spend(run, "input_tokens", input_tokens)
             budgets.spend(run, "output_tokens", output_tokens)
         if event.event_type == EventType.ARTIFACT_CREATED:
@@ -73,6 +85,9 @@ def build_graph(engine, run):
 
     def _before_model(state: _GraphState) -> None:
         _restore_controller(state)
+        if isinstance(engine._reasoner, _HookedReasoner):
+            # G5 §5.2：包装后的 Reasoner 从活跃 Run 取钩子上下文（模型调用节点统一设置）。
+            engine._active_hook_run = run
         if run.controller is None:
             budgets.check(run, "tokens", 0)
             budgets.check(run, "models")
@@ -124,262 +139,22 @@ def build_graph(engine, run):
         state["turn_count"] += 1
         # 收口 5：Turn 区间事件（模型/工具/usage 事件按 seq 落在区间内）。
         turn_id = f"{run.handle.run_id}:t{state['turn_count']}"
-        run.events.append(
-            engine._event(
-                run,
-                EventType.TURN_STARTED,
-                {"turn_id": turn_id, "turn_number": state["turn_count"]},
-            )
-        )
-
-        def _reason_input() -> ReasonInput:
-            max_total_tokens = budgets.limit(run, "tokens")
-            if (
-                run.controller is not None
-                and run.controller.spec.limits.max_total_tokens is not None
-            ):
-                controlled_limit = run.controller.spec.limits.max_total_tokens
-                max_total_tokens = (
-                    min(int(max_total_tokens), controlled_limit)
-                    if max_total_tokens is not None
-                    else controlled_limit
-                )
-            # Model Profile 的输出上限是每次调用的硬限制；Run 总预算则是
-            # 随执行消耗递减的剩余额度。两者同时存在时必须取更小值。
-            max_output_tokens = spec.model.max_output_tokens
-            if max_total_tokens is not None:
-                from ksadk.harness.engine.context_pipeline import count_tokens
-                from ksadk.harness.subagent import SubAgentExecutionError
-
-                used = max(
-                    int(state.get("usage_tokens") or 0),
-                    run.budget_usage.get("tokens", 0),
-                    run.controller.total_tokens if run.controller is not None else 0,
-                )
-                estimated_input = sum(
-                    count_tokens(str(message.get("content") or "")) for message in state["messages"]
-                ) + count_tokens(spec.prompt.instructions or "")
-                remaining = int(max_total_tokens) - used - estimated_input
-                if remaining < 1:
-                    if run.controller is not None:
-                        run.controller.stop_reason = "total_tokens_hard_limit"
-                        run.controller.budget_exhausted = True
-                        state["run_control"] = run.controller.snapshot()
-                        raise RunControlStop("total_tokens_hard_limit")
-                    raise SubAgentExecutionError(
-                        "budget_exhausted",
-                        "sub-agent token budget exhausted before model invocation "
-                        f"(limit={max_total_tokens}, used={used}, "
-                        f"estimated_input={estimated_input})",
-                    )
-                max_output_tokens = (
-                    min(max_output_tokens, remaining)
-                    if max_output_tokens is not None
-                    else remaining
-                )
-            streaming = getattr(engine._reasoner, "_streaming", None) is True or os.getenv(
-                "KSADK_MODEL_STREAMING", ""
-            ).strip().lower() in {"1", "true", "yes", "on"}
-
-            def _live_event_sink(event):
-                run.events.append(event)
-                run.seq = max(run.seq, event.seq_id)
-                _capture_control_event(event)
-
-            delegation_synthesis = bool(state.get("delegation_synthesis_pending"))
-            closing_turn = state["turn_count"] >= engine._max_reasoning_turns and any(
-                message.get("role") == "tool" for message in state["messages"]
-            )
-            instructions = spec.prompt.instructions or ""
-            if delegation_synthesis:
-                instructions += (
-                    "\n\n已调度的子任务均已结束。现在必须直接综合已有子任务结果回答"
-                    "用户；不得再次派发、描述将要执行的计划或把处理中话术当成答案。"
-                    "若部分子任务失败，应明确指出失败项，并基于其余结果给出当前最佳结论。"
-                )
-            if closing_turn:
-                instructions += (
-                    "\n\n这是本次执行的最后一轮。禁止再调用或模拟调用工具，禁止描述"
-                    "后续计划或说将继续查找。必须现在基于已有证据输出完整、可交付的"
-                    "当前最佳答案；证据不足的部分直接标为未验证。"
-                )
-            reason_messages = list(state["messages"])
-            if closing_turn:
-                # Several OpenAI-compatible models follow the newest user
-                # message more reliably than a system-prompt suffix.  Without
-                # this explicit hand-off GLM can keep emitting a textual call
-                # to a tool used in the previous turn even though the closing
-                # turn deliberately has no tool schema.  The provider then
-                # (correctly) rejects that call as undeclared and turns an
-                # otherwise useful research run into a failure.  Keep the
-                # safety boundary -- no tools are disclosed -- but make the
-                # required transition from evidence collection to synthesis
-                # unambiguous in the conversational context as well.
-                reason_messages.append(
-                    {
-                        "role": "user",
-                        "content": (
-                            "资料收集阶段已经结束。不要再搜索、查看网页或调用任何工具；"
-                            "请只使用上文已有证据，现在直接给出最终结论。若证据不足，"
-                            "明确标为未验证。"
-                        ),
-                    }
-                )
-            synthesis_tools = (
-                list(run.tools.values())
-                + engine._skill_disclosure.tools(run.skill_catalog)
-                + engine._mcp_disclosure.tools(run.mcp_catalog)
-            )
-            available_tools = (
-                synthesis_tools
-                + list(run.sub_agents.values())
-                + (
-                    [engine._delegation_runtime]
-                    if engine._delegation_runtime is not None
-                    else []
-                )
-            )
-
-            return ReasonInput(
-                model_ref=spec.model.profile_ref,
-                fallback_model_refs=spec.model.fallback_profile_refs,
-                provider_policy=spec.model.provider_policy,
-                instructions=instructions,
-                messages=reason_messages,
-                # A synthesis turn must not spawn more children, but it still
-                # needs ordinary tools to produce the deliverable the user
-                # requested (for example, save a Markdown report). Removing
-                # every tool here made GLM emit a textual write call against an
-                # empty schema, which could only fail after all children had
-                # already completed.
-                tools=(
-                    []
-                    if closing_turn
-                    else synthesis_tools if delegation_synthesis else available_tools
-                ),
-                reasoner=engine._reasoner,
-                agent_id=run.state.agent_id,
-                user_id=run.state.user_id,
-                session_id=run.state.session_id,
-                run_id=run.handle.run_id,
-                seq_start=run.seq,
-                max_turns=engine._max_reasoning_turns,
-                max_output_tokens=max_output_tokens,
-                streaming=streaming,
-                live_event_sink=_live_event_sink if streaming else None,
-            )
-
-        try:
-            out = await reason_turn_async(state["turn_count"], _reason_input())
-        except ModelFailoverExhausted as exc:
-            # reason_turn 在最后一次失败时仍必须把每次 started/failed
-            # 审计事件交还引擎，不能因异常路径丢失配对事实。
-            for event in exc.events:
-                if event.seq_id <= run.seq:
-                    continue
-                run.events.append(event)
-                run.seq = max(run.seq, event.seq_id)
-            if exc.stop_reason.value == "recover_context" and engine._context_engine is not None:
-                state["messages"] = await engine._context_pipeline.recover_model_overflow(
-                    run,
-                    state["messages"],
-                    spec.prompt.instructions or "",
-                )
-                # 恢复调用仍属于同一个 Turn，但使用压缩后输入及新的 seq 起点。
-                try:
-                    out = await reason_turn_async(state["turn_count"], _reason_input())
-                except ModelFailoverExhausted as retry_exc:
-                    for event in retry_exc.events:
-                        if event.seq_id <= run.seq:
-                            continue
-                        run.events.append(event)
-                        run.seq = max(run.seq, event.seq_id)
-                    raise RuntimeError(str(retry_exc)) from retry_exc
-            else:
-                raise RuntimeError(str(exc)) from exc
-        except ReasoningLimitError as exc:
-            raise RuntimeError(str(exc)) from exc
-        # 部分 Provider 在最后一个披露工具返回后会给出空 assistant 消息，
-        # 随即把 Run 当成正常结束。只在本 Run 已执行过工具且尚未重试时，
-        # 增加一次无工具收口轮；避免 Skill/MCP 已拿到 L3 证据却没有最终答案。
-        assistant_text = "\n".join(
-            str(message.get("content") or "").strip()
-            for message in out.new_messages
-            if message.get("role") == "assistant"
-        ).strip()
-        unfinished_delegation_answer = bool(
-            state.get("delegation_synthesis_pending")
-            and _DELEGATION_PREFACE.search(assistant_text)
-        )
-        if (
-            out.route == "final"
-            and (not assistant_text or unfinished_delegation_answer)
-            and any(message.get("role") == "tool" for message in state["messages"])
-            and int(state.get("finalization_retries") or 0) < 1
-            and ("reason", "tool_calls") in set(run.compiled.plan.edges or ())
-        ):
-            state["finalization_retries"] = int(state.get("finalization_retries") or 0) + 1
-            out.events = [
-                event
-                for event in out.events
-                if not (
-                    event.event_type == EventType.TEXT_COMPLETED and event.phase == "final_answer"
-                )
-            ]
-            out.new_messages = []
-            out.pending_tool_calls = []
-            out.route = "tool_calls"
-            state["messages"].append(
-                {
-                    "role": "user",
-                    "content": (
-                        "上一轮没有形成可交付答案。所有已派发任务都已经结束，"
-                        "请立即基于现有工具和子任务结果给出完整答案；不得描述"
-                        "将要派发、继续处理或稍后完成。"
-                    ),
-                }
-            )
-        if out.route == "final" and state.get("delegation_synthesis_pending"):
-            state["delegation_synthesis_pending"] = False
-        for ev in out.events:
-            if ev.seq_id <= run.seq:
-                continue
-            # 长任务方案 §6.3：Actual Token 回填到最近一次 ContextManifest
-            # （actual_usage_ref 指向 usage.reported 事件）。同时在 usage
-            # 事件 payload 落 manifest_id —— 事件流层面可直接查询
-            # 「某次模型调用实际对应哪个 Manifest」（§6.2 闭环）。
-            if ev.event_type == EventType.USAGE_REPORTED and run.context_manifest:
-                ev.payload["manifest_id"] = run.context_manifest.manifest_id
-                run.context_manifest = run.context_manifest.with_actual(
-                    input_tokens=int(ev.payload.get("input_tokens") or 0),
-                    output_tokens=int(ev.payload.get("output_tokens") or 0),
-                    usage_ref=ev.event_id,
-                )
-            run.events.append(ev)
-            run.seq = max(run.seq, ev.seq_id)
-            _capture_control_event(ev)
-            if ev.event_type == EventType.USAGE_REPORTED:
-                state["usage_tokens"] = (
-                    int(state.get("usage_tokens") or 0)
-                    + int(ev.payload.get("input_tokens") or 0)
-                    + int(ev.payload.get("output_tokens") or 0)
-                )
-        state["messages"].extend(out.new_messages)
-        state["pending_tool_calls"] = out.pending_tool_calls
-        state["tool_batch_succeeded"] = []
-        state["tool_batch_failed"] = False
-        state["route"] = out.route
-        run.events.append(
-            engine._event(
-                run,
-                EventType.TURN_COMPLETED,
-                {"turn_id": turn_id, "turn_number": state["turn_count"]},
-            )
-        )
-        if run.controller is not None:
-            state["run_control"] = run.controller.snapshot()
-            if run.controller.stop_reason:
-                raise RunControlStop(run.controller.stop_reason)
+        # Native Harness Phase 1：reason 主体已抽出为引擎无关的纯函数 handler
+        # （engine/phases/reason.py）。本包装负责图内前置（策略重校验 / _before_model
+        # / turn_count / turn_id 构造），handler 负责 turn 区间内全部事件与状态推进。
+        from ksadk.harness.engine.phases.context import PhaseContext
+        from ksadk.harness.engine.phases.reason import reason_phase
+
+        ctx = PhaseContext(spec=spec, run=run, engine=engine, turn_id=turn_id, state=state)
+        result = await reason_phase(ctx)
+        state.update(result.state)
+        # Phase 1 过渡期：handler 仍直接写 run.events/run.seq，故此处仅作纵深防御
+        # （seq_id 已推进时不再重复 append；Phase 2 切断直写后此循环成为唯一出口）。
+        for ev in result.events:
+            if ev.seq_id > run.seq:
+                run.events.append(ev)
+                run.seq = max(run.seq, ev.seq_id)
+                _capture_control_event(ev)
         return state
 
     async def tool_calls(state: _GraphState) -> _GraphState:
@@ -387,361 +162,62 @@ def build_graph(engine, run):
         _restore_controller(state)
         run.child_approval_decision = state.get("child_approval_decision")
         state["child_approval_decision"] = {}
-        class _GraphApprovalResolver:
-            # LangGraph interrupt 同步语义：首次抛 GraphInterrupt，resume 后返回审批决定。
-            def request(self, *, call_id, name, arguments):  # type: ignore[no-untyped-def]
-                return interrupt(
-                    {"call_id": call_id, "name": name, "args": arguments, "risk": "high"}
-                )
-
-        # 披露游标活在图状态（随 Checkpoint 持久化）；节点结束写回。
-        cursors = McpDisclosureCursors(
-            # Checkpoint 反序列化会把 tuple 变 list（不可哈希），统一还原。
-            listed={tuple(item) for item in (state.get("mcp_listed") or ())},
-            schema_read={tuple(item) for item in (state.get("mcp_schema_read") or ())},
-        )
-
-        def _mcp_approval_decider(name: str, arguments: dict[str, Any]) -> bool:
-            # P0.1：按实际目标 Server 动态决策——只有 mcp_call_tool 指向
-            # high/critical 风险 Server 时才要求审批（高低风险混用不误伤）。
-            return name == MCP_CALL_TOOL_TOOL and engine._mcp_disclosure.approval_decider(arguments)
-
-        class _EngineToolExecutor:
-            @staticmethod
-            def validate_arguments(name, arguments):  # type: ignore[no-untyped-def]
-                tool = run.tools.get(name)
-                if tool is None:
-                    return None
-                raw_schema = getattr(tool, "parameters", None)
-                # Host tests and backward-compatible integrations may still
-                # register a plain callable.  With no published schema there
-                # is nothing to validate here; execution retains its previous
-                # behaviour.
-                if not isinstance(raw_schema, dict):
-                    return None
-                schema = raw_schema
-                required = schema.get("required") or ()
-                missing = [
-                    str(field)
-                    for field in required
-                    if str(field) not in arguments
-                    or arguments.get(str(field)) is None
-                ]
-                if missing:
-                    return "missing required fields: " + ", ".join(missing)
-                try:
-                    from jsonschema.validators import validator_for
-
-                    validator = validator_for(schema)(schema)
-                    error = next(validator.iter_errors(arguments), None)
-                except Exception as exc:  # malformed host schema is not a model error
-                    return f"tool schema validation failed: {exc}"
-                return f"schema mismatch: {error.message}" if error is not None else None
-
-            async def execute(self, name, arguments):  # type: ignore[no-untyped-def]
-                return await engine._invoke_tool(name, arguments, run=run, mcp_cursors=cursors)
-
-            async def execute_with_context(  # type: ignore[no-untyped-def]
-                self, name, arguments, context
-            ):
-                return await engine._invoke_tool(
-                    name,
-                    arguments,
-                    run=run,
-                    mcp_cursors=cursors,
-                    call_id=context.call_id,
-                )
-
-            def reliability(self, name, arguments, *, receipt_enabled):  # type: ignore[no-untyped-def]
-                if engine._mcp_disclosure.is_tool(name):
-                    return engine._mcp_disclosure.reliability(
-                        name,
-                        arguments,
-                        receipt_enabled=receipt_enabled,
-                    )
-                if engine._capability_runtime is not None:
-                    return engine._capability_runtime.reliability(name)
-                from ksadk.harness.tool_reliability import classify_tool_reliability
-
-                return classify_tool_reliability(side_effect="unknown")
-
-        from ksadk.harness.subagent import order_subagent_tool_calls
-
-        pending_tool_calls = order_subagent_tool_calls(
-            list(state["pending_tool_calls"]), run.sub_agents
-        )
-        def _parallel_safe(name, arguments):
-            sub = run.sub_agents.get(name)
-            if sub is not None:
-                return not (sub.tools or (sub.inherit_skills and run.skill_catalog)
-                            or (sub.inherit_mcp and run.mcp_catalog))
-            return bool(
-                engine._delegation_runtime is not None
-                and engine._delegation_runtime.is_tool(name)
-                and engine._capability_runtime is None
-                and engine._delegation_runtime.parallel_safe(
-                    arguments,
-                    parent_run=run,
-                )
-            )
-
-        # Commit sequential siblings at separate checkpoint boundaries. Only
-        # children proven unable to request approval may share a parallel node.
-        parallel = len(pending_tool_calls) > 1 and engine._capability_runtime is None and all(
-            _parallel_safe(p["name"], p["arguments"])
-            and p["name"] not in run.approval_required
-            and not (run.sub_agents.get(p["name"]) and run.sub_agents[p["name"]].depends_on)
-            for p in pending_tool_calls
-        ) and spec.execution_strategy.config.get("subagent_failure_mode", "partial") != "fail_fast"
-        remaining_calls = [] if parallel else pending_tool_calls[1:]
-        pending_tool_calls = pending_tool_calls if parallel else pending_tool_calls[:1]
-        # Chat only needs an aggregate lifecycle signal. Provider selection,
-        # child labels and task bodies remain available in the execution trace
-        # and tool receipts, but are deliberately not expanded into one visible
-        # progress card per child.
-        delegation_calls = (
-            [
-                pending
-                for pending in pending_tool_calls
-                if engine._delegation_runtime is not None
-                and engine._delegation_runtime.is_tool(str(pending.get("name") or ""))
-            ]
-            if engine._delegation_runtime is not None
-            else []
+        # Native Harness Phase 1：tool_calls 主体已抽出为引擎无关的纯函数 handler
+        # （engine/phases/tools.py）。本包装负责图内前置（策略重校验 / 控制器恢复 /
+        # child-approval 决定接收）与**挂起原语翻译**：handler 返回 NeedInteraction
+        # 表示需要外部交互，LangGraph 侧在此调 interrupt() 挂起，resume 后把决定写回
+        # 状态并重新进入 handler（同一节点调用内循环，故前置只执行一次——与旧
+        # interrupt() 语义下"节点整体重放"的次数一致）。
+        from ksadk.harness.engine.phases.context import PhaseContext
+        from ksadk.harness.engine.phases.tools import (
+            TOOL_APPROVAL_DECISION_KEY,
+            TOOL_APPROVAL_REPLAY_ATTR,
+            tools_phase,
         )
-        delegation_labels: list[str] = []
-        ordinary_calls = [
-            pending for pending in pending_tool_calls if pending not in delegation_calls
-        ]
-
-        def _emit_tool_progress(status: str) -> None:
-            if not ordinary_calls:
-                return
-            tools = [str(pending.get("name") or "tool") for pending in ordinary_calls]
-            lowered = " ".join(tools).lower()
-            activity_kind = (
-                "write"
-                if any(token in lowered for token in ("write", "edit", "save"))
-                else "search"
-                if "search" in lowered
-                else "fetch"
-                if "fetch" in lowered
-                else "read"
-                if any(token in lowered for token in ("read", "list"))
-                else "command"
-                if any(token in lowered for token in ("command", "shell", "exec"))
-                else "tool"
-            )
-            batch_id = ":".join(
-                str(pending.get("call_id") or index)
-                for index, pending in enumerate(ordinary_calls, start=1)
-            )
-            # Repeated search/fetch/read turns are useful trace evidence but
-            # become dozens of duplicate chat rows during long research. Keep
-            # one public lifecycle per human activity class.
-            if status == "running":
-                if activity_kind in run.public_tool_activity_kinds:
-                    return
-                run.public_tool_activity_kinds.add(activity_kind)
-                run.public_tool_activity_batches.add(batch_id)
-            elif batch_id not in run.public_tool_activity_batches:
-                return
-            progress_event = engine._event(
-                run,
-                EventType.RUN_PROGRESS,
-                {
-                    "kind": "tool.batch",
-                    "status": status,
-                    "count": len(ordinary_calls),
-                    "batch_id": batch_id,
-                    "activity_kind": activity_kind,
-                    # Tool arguments and results stay in Trace/receipts.  The
-                    # chat surface only receives stable capability names and
-                    # turns them into human activity summaries.
-                    "tools": tools,
-                },
-            )
-            run.events.append(progress_event)
-            _capture_control_event(progress_event)
-
-        def _emit_delegation_progress(status: str) -> None:
-            if not delegation_calls:
-                return
-            progress_event = engine._event(
-                run,
-                EventType.RUN_PROGRESS,
-                {
-                    "kind": "delegation.batch",
-                    "status": status,
-                    "count": len(delegation_calls),
-                    "labels": delegation_labels,
-                },
-            )
-            run.events.append(progress_event)
-            _capture_control_event(progress_event)
 
-        if delegation_calls:
-            delegation_labels = [
-                engine._delegation_runtime.public_label(
-                    dict(pending.get("arguments") or {}),
-                    call_id=str(pending.get("call_id") or ""),
-                )
-                for pending in delegation_calls
-            ]
-            _emit_delegation_progress("running")
-        _emit_tool_progress("running")
-        has_subagent_dependencies = any(
-            run.sub_agents[name].depends_on
-            for name in (str(call.get("name") or "") for call in pending_tool_calls)
-            if name in run.sub_agents
-        )
-        subagent_failure_mode = str(
-            run.compiled.spec.execution_strategy.config.get("subagent_failure_mode", "partial")
+        # 重放检测：引擎在挂起时把审批 call_id 记到 run.pending_approval_call_id，
+        # attach 亦会从 Checkpoint 重建它（跨进程恢复同样成立）。resume 后 LangGraph
+        # 整体重放本节点，而重放期间 handler 仍拿不到决定（决定要等下面 interrupt()
+        # 返回）会再走一次挂起分支；旧实现里那一次是 interrupt() 内联返回决定、不走
+        # 异常分支，故 handler 据此跳过重复补发的失败态进度。Phase 2 Native 引擎以
+        # NeedInteraction 表达挂起，不需该标记。
+        setattr(
+            run,
+            TOOL_APPROVAL_REPLAY_ATTR,
+            str(getattr(run, "pending_approval_call_id", "") or ""),
         )
-        def _live_tool_event(event):
-            if (event.event_type == EventType.TOOL_CALL_BEGIN
-                    and str(event.payload.get("call_id") or "") in run.budget_tool_calls):
-                return  # The same pending delegate resumes; it does not start twice.
-            run.seq += 1
-            event.seq_id = run.seq
-            run.events.append(event)
-            _capture_control_event(event)
 
-        try:
-            out = await execute_tool_calls(
-                ToolCallInput(
-                    pending_tool_calls=pending_tool_calls,
-                    approval_required=frozenset(run.approval_required),
-                    approval_decider=_mcp_approval_decider,
-                    parallel_safe_decider=(
-                        lambda name, _arguments: (
-                            (
-                                name in run.sub_agents and _parallel_safe(name, _arguments)
-                                or (
-                                    engine._delegation_runtime is not None
-                                    and engine._delegation_runtime.is_tool(name)
-                                )
-                            )
-                            and not has_subagent_dependencies
-                            and subagent_failure_mode != "fail_fast"
-                        )
-                    ),
-                    stop_on_error_decider=(
-                        lambda name, _arguments: (
-                            subagent_failure_mode == "fail_fast" and name in run.sub_agents
-                        )
-                    ),
-                    cancel_pending_decider=lambda name, _arguments: (
-                        name in run.sub_agents
-                        or (
-                            engine._delegation_runtime is not None
-                            and engine._delegation_runtime.is_tool(name)
-                        )
-                    ),
-                    dependencies={
-                        name: tuple(spec.depends_on)
-                        for name, spec in run.sub_agents.items()
-                        if spec.depends_on
-                    },
-                    max_parallelism=int(
-                        run.compiled.spec.execution_strategy.config.get("max_parallel_subagents", 4)
-                    ),
-                    capability_runtime=engine._capability_runtime,
-                    tenant_id=engine._tenant_id,
-                    authorization_agent_id=run.request.metadata.get("authorization_agent_id"),
-                    succeeded_tools=frozenset(state.get("tool_batch_succeeded") or ()),
-                    prior_failure=bool(state.get("tool_batch_failed")),
-                    live_event_sink=_live_tool_event,
-                    argument_validator=_EngineToolExecutor.validate_arguments,
-                    approval_resolver=_GraphApprovalResolver(),
-                    tool_executor=_EngineToolExecutor(),
-                    agent_id=run.state.agent_id,
-                    user_id=run.state.user_id,
-                    session_id=run.state.session_id,
-                    run_id=run.handle.run_id,
-                    seq_start=run.seq,
-                    working_context=run.state.working_context,
-                )
-            )
-        except ChildApprovalPending as exc:
-            state["child_approval"] = exc.detail
-            state["route"] = "child_approval"
-            state["budget"] = budgets.snapshot(run)
-            return state
-        except BaseException:
-            _emit_delegation_progress("failed")
-            _emit_tool_progress("failed")
-            raise
-        for ev in out.events:
-            _capture_control_event(ev)
-            if ev.event_type == EventType.TOOL_CALL_END:
-                if not ev.payload.get("error"):
-                    state.setdefault("tool_batch_succeeded", []).append(ev.payload["name"])
-                elif (
-                    subagent_failure_mode == "fail_fast"
-                    and ev.payload.get("name") in run.sub_agents
-                ):
-                    state["tool_batch_failed"] = True
-        tool_errors = any(
-            event.event_type == EventType.TOOL_CALL_END and event.payload.get("error")
-            for event in out.events
-            if str(event.payload.get("name") or "")
-            not in {str(call.get("name") or "") for call in delegation_calls}
-        )
-        _emit_tool_progress("failed" if tool_errors else "completed")
-        # 收口 6：子 Agent 事件统一重排并入（tool.call.begin/end 之后）。
-        from ksadk.harness.subagent import resequence_child_events
+        ctx = PhaseContext(spec=spec, run=run, engine=engine, turn_id="", state=state)
+        while True:
+            result = await tools_phase(ctx)
+            state.update(result.state)
+            # Phase 1 过渡期：handler 仍直接写 run.events/run.seq，故此处仅作纵深防御
+            # （seq_id 已推进时不再重复 append；Phase 2 切断直写后此循环成为唯一出口）。
+            for ev in result.events:
+                if ev.seq_id > run.seq:
+                    run.events.append(ev)
+                    run.seq = max(run.seq, ev.seq_id)
+                    _capture_control_event(ev)
+            if result.interaction is None:
+                return state
+            if result.interaction.kind == "child_approval":
+                # Phase 1：子 Agent 审批仍由专用 ``child_approval`` 节点挂起
+                # （route="child_approval" 由 handler 写入）。不在本节点内 interrupt 的
+                # 实测原因：在**已 resume 过**的 tool_calls 任务里再次 interrupt，
+                # LangGraph 会把 Checkpoint 的 ``next`` 清空，attach 无法从 snapshot
+                # 推断挂起（test_second_child_approval_never_reuses_first_decision）。
+                # handler 仍把 child_approval NeedInteraction 显式交还，供 Phase 2
+                # Native 引擎直接挂起（届时不再需要图节点）。
+                return state
+            payload = result.interaction.request_payload
+            # LangGraph suspension: interrupt() resumes with the approval decision.
+            decision = interrupt(payload)
+            state[TOOL_APPROVAL_DECISION_KEY] = {
+                "call_id": str(payload.get("call_id") or ""),
+                "decision": decision,
+            }
+            # Re-enter tools to execute the now-decided call.
 
-        child_events = engine._pending_child_events.pop(run.handle.run_id, [])
-        for event in child_events:
-            _capture_control_event(event)
-        resequence_child_events(run, child_events)
-        subagent_events = engine._pending_subagent_events.pop(run.handle.run_id, {})
-        for pending in pending_tool_calls:
-            pending_events = subagent_events.get(str(pending.get("call_id") or ""), [])
-            for event in pending_events:
-                _capture_control_event(event)
-            resequence_child_events(
-                run,
-                pending_events,
-            )
-        if delegation_calls:
-            delegated_call_ids = {str(pending.get("call_id") or "") for pending in delegation_calls}
-            failed = any(
-                event.event_type == EventType.TOOL_CALL_END
-                and str(event.payload.get("call_id") or "") in delegated_call_ids
-                and bool(event.payload.get("error"))
-                for event in out.events
-            )
-            _emit_delegation_progress("failed" if failed else "completed")
-            state["delegation_synthesis_pending"] = True
-        state["messages"].extend(out.new_messages)
-        if out.working_context is not None:
-            run.state.working_context = out.working_context
-        state["pending_tool_calls"] = remaining_calls
-        state["mcp_listed"] = sorted(cursors.listed)
-        state["mcp_schema_read"] = sorted(cursors.schema_read)
-        state["route"] = "tool_calls" if remaining_calls else out.route
-        if run.controller is not None:
-            if (
-                run.controller.replan_reason
-                and run.controller.guidance_emitted_revision != run.controller.guidance_revision
-            ):
-                run.events.append(
-                    engine._event(
-                        run,
-                        EventType.RUN_PROGRESS,
-                        {
-                            "kind": "run_control",
-                            "status": "in_progress",
-                            "action": "replan",
-                            "reason": run.controller.replan_reason,
-                            "plan_revision": run.controller.guidance_revision,
-                        },
-                    )
-                )
-            state["run_control"] = run.controller.snapshot()
-        return state
 
     def route(state: _GraphState) -> str:
         return state["route"]
@@ -757,12 +233,16 @@ def build_graph(engine, run):
     async def plan_node(state: _GraphState) -> _GraphState:
         """plan-execute 拓扑的规划节点：一次无工具模型调用产出执行计划。"""
         _before_model(state)
+        reasoning_effort = str(run.request.config.get("effort") or "").strip().lower() or None
         turn: HarnessReasoningTurn = await engine._reasoner.complete(
             model=spec.model.profile_ref,
             prompt=(spec.prompt.instructions or "") + "\n请先给出分步执行计划，再开始执行。",
             messages=tuple(state["messages"]),
             tools=[],
+            **({"reasoning_effort": reasoning_effort} if reasoning_effort else {}),
         )
+        # 直接调 Reasoner 的节点也要先 flush 降级再发自己的后续事件，保持 seq 单调。
+        flush_hook_degradations(engine, run)
         state["messages"].append(
             {"role": "assistant", "content": "【执行计划】\n" + (turn.final_text or "")}
         )
@@ -782,6 +262,7 @@ def build_graph(engine, run):
     async def review_node(state: _GraphState) -> _GraphState:
         """plan-execute-review 拓扑的独立审查节点：对最终回答做一次批判。"""
         _before_model(state)
+        reasoning_effort = str(run.request.config.get("effort") or "").strip().lower() or None
         messages = list(state["messages"]) + [
             {"role": "user", "content": "请审查以上回答的准确性与遗漏，指出问题（如有）。"}
         ]
@@ -790,7 +271,9 @@ def build_graph(engine, run):
             prompt=spec.prompt.instructions or "",
             messages=tuple(messages),
             tools=[],
+            **({"reasoning_effort": reasoning_effort} if reasoning_effort else {}),
         )
+        flush_hook_degradations(engine, run)
         state["messages"].append(
             {"role": "assistant", "content": "【审查】\n" + (turn.final_text or "")}
         )
@@ -839,6 +322,10 @@ def build_graph(engine, run):
     reason_mapping = {}
     if "tool_calls" in reason_successors:
         reason_mapping["tool_calls"] = "tool_calls"
+    # A live user correction may arrive while the final model response is in
+    # flight. The reason handler rejects that stale candidate and re-enters
+    # itself with the accepted correction, even for text-only plans.
+    reason_mapping["reason"] = "reason"
     reason_mapping["final"] = END if exit_target == "final" else exit_target
     if "reason" in node_impls and "reason" in plan.nodes and "reason" != exit_target:
         builder.add_conditional_edges("reason", route, reason_mapping)
@@ -846,9 +333,15 @@ def build_graph(engine, run):
         if src == "reason":
             continue  # 已由条件边覆盖。
         if src == "tool_calls":
-            builder.add_conditional_edges("tool_calls", route, {
-                "tool_calls": "tool_calls", "child_approval": "child_approval", "reason": dst,
-            })
+            builder.add_conditional_edges(
+                "tool_calls",
+                route,
+                {
+                    "tool_calls": "tool_calls",
+                    "child_approval": "child_approval",
+                    "reason": dst,
+                },
+            )
             continue
         if dst == "final":
             if src in node_impls and src != "reason":