@ngocsangairvds/vsaf 4.1.7 → 4.1.9

package/skills/vds-skill/vds-scripts/vds_agent_core/src/vds_agent_core/agents/loop.py

@@ -1,864 +0,0 @@
-"""Bounded autonomy loop for tool-first analysis (generic, extracted from audit).
-
-The loop is intentionally conservative and deterministic:
-- hard bounds on steps, timeout, and budget
-- strict termination reason taxonomy for observability
-- tool calls delegated through centralized ToolRegistry
-- orchestrator-specific behavior injected via LoopBehaviorHooks
-"""
-
-from __future__ import annotations
-
-import hashlib
-import json
-import time
-from collections.abc import Callable
-from contextlib import contextmanager
-from dataclasses import dataclass, field
-from enum import StrEnum
-from typing import TYPE_CHECKING, Any
-
-from pydantic import BaseModel, ConfigDict, Field
-
-from vds_agent_core.agents.hooks import LoopBehaviorHooks, NoOpHooks
-from vds_agent_core.observability import AgentTracer
-
-if TYPE_CHECKING:
-    from vds_agent_core.agents.tools import ToolRegistry
-
-
-@contextmanager
-def _nullcontext():
-    """No-op context manager for when tracing is disabled."""
-    yield
-
-
-_REQUIREMENT_ANALYSIS_DIAGNOSTIC_KEYS: tuple[str, ...] = (
-    "analysis_mode",
-    "analysis_reason_codes",
-    "required_anchor_modalities",
-    "project_scope_required",
-    "generic_anchor_exemption",
-    "minimum_substantive_code_anchors",
-    "finalization_policy",
-)
-
-
-class _StrictModel(BaseModel):
-    model_config = ConfigDict(extra="forbid", strict=True)
-
-
-class LoopTerminationReason(StrEnum):
-    """Canonical loop termination reasons."""
-
-    COMPLETED = "completed"
-    MAX_STEPS = "max_steps"
-    TIMEOUT = "timeout"
-    BUDGET_EXHAUSTED = "budget_exhausted"
-    INSUFFICIENT_EVIDENCE = "insufficient_evidence"
-    TOOL_ERROR = "tool_error"
-    STAGNATION = "stagnation"
-
-
-@dataclass(slots=True)
-class AgentLoopConfig:
-    """Execution bounds for the autonomy loop."""
-
-    max_steps: int = 15
-    timeout_seconds: float = 10.0
-    budget_units: int = 15
-    tool_calls_limit: int = 12
-    require_evidence: bool = False
-    min_evidence_refs: int = 1
-    stagnation_threshold: int = 3
-    """Number of consecutive steps without progress before stagnation termination."""
-    checkpoint_key: str | None = None
-    """Optional state checkpoint key for persistence/resume."""
-    checkpoint_manager: Any | None = field(default=None, repr=False)
-    """Optional CheckpointManager for state persistence (opt-in)."""
-    evidence_overrides: dict[str, dict[str, int]] = field(default_factory=dict)
-
-
-class AgentLoopAction(_StrictModel):
-    """Planner-selected action for the next step."""
-
-    tool: str
-    payload: dict[str, Any] = Field(default_factory=dict)
-    budget_cost: int = Field(default=1, ge=1)
-    route_id: str | None = None
-    route_reason: str | None = None
-    route_confidence: float = Field(default=0.0, ge=0.0, le=1.0)
-    ambiguity_reason_codes: list[str] = Field(default_factory=list)
-    required_steps: list[str] = Field(default_factory=list)
-    required_tools: list[str] = Field(default_factory=list)
-    override_source: str | None = None
-    override_reason: str | None = None
-    depth_level: int = Field(default=1, ge=1)
-    depth_increase_reason: str | None = None
-
-
-class AgentLoopStep(_StrictModel):
-    """Per-step execution trace."""
-
-    step: int = Field(ge=1)
-    tool: str
-    budget_cost: int = Field(ge=1)
-    budget_remaining: int = Field(ge=0)
-    output: dict[str, Any] = Field(default_factory=dict)
-    route_id: str | None = None
-    route_reason: str | None = None
-    route_confidence: float = Field(default=0.0, ge=0.0, le=1.0)
-    ambiguity_reason_codes: list[str] = Field(default_factory=list)
-    required_steps: list[str] = Field(default_factory=list)
-    required_tools: list[str] = Field(default_factory=list)
-    override_source: str | None = None
-    override_reason: str | None = None
-    depth_level: int = Field(default=1, ge=1)
-    depth_increase_reason: str | None = None
-    payload: dict[str, Any] = Field(default_factory=dict)
-
-
-class AgentLoopResult(_StrictModel):
-    """Bounded loop result with trace metadata hooks."""
-
-    termination_reason: LoopTerminationReason
-    steps_executed: int = Field(ge=0)
-    budget_remaining: int = Field(ge=0)
-    elapsed_seconds: float = Field(ge=0.0)
-    evidence_refs: list[str] = Field(default_factory=list)
-    trace_steps: list[AgentLoopStep] = Field(default_factory=list)
-    tool_error: str | None = None
-    docs_intent_utilization: dict[str, Any] = Field(default_factory=dict)
-    code_ranking_diagnostics: dict[str, Any] = Field(default_factory=dict)
-    project_artifact_refs: list[dict[str, Any]] = Field(default_factory=list)
-    cross_repo_evidence_refs: list[dict[str, Any]] = Field(default_factory=list)
-    config_repo_companion_refs: list[dict[str, Any]] = Field(default_factory=list)
-    prior_knowledge_refs: list[dict[str, Any]] = Field(default_factory=list)
-    max_depth_level: int = Field(default=0, ge=0)
-    depth_stop_reason: str | None = None
-
-    def to_trace_metadata(self) -> dict[str, Any]:
-        """Serialize stable metadata payload for row evaluator passthrough."""
-        normalized_tool_error: str | bool = False
-        raw_tool_error = self.tool_error
-        if isinstance(raw_tool_error, str):
-            normalized_text = raw_tool_error.strip()
-            if normalized_text:
-                normalized_tool_error = normalized_text
-        normalized_depth_stop_reason: str | bool = False
-        raw_depth_stop_reason = self.depth_stop_reason
-        if isinstance(raw_depth_stop_reason, str):
-            normalized_depth_text = raw_depth_stop_reason.strip()
-            if normalized_depth_text:
-                normalized_depth_stop_reason = normalized_depth_text
-        return {
-            "termination_reason": self.termination_reason.value,
-            "steps_executed": self.steps_executed,
-            "budget_remaining": self.budget_remaining,
-            "elapsed_seconds": self.elapsed_seconds,
-            "evidence_refs": list(self.evidence_refs),
-            "trace_steps": [step.model_dump() for step in self.trace_steps],
-            "tool_error": normalized_tool_error,
-            "docs_intent_utilization": dict(self.docs_intent_utilization),
-            "code_ranking_diagnostics": dict(self.code_ranking_diagnostics),
-            "project_artifact_refs": list(self.project_artifact_refs),
-            "cross_repo_evidence_refs": list(self.cross_repo_evidence_refs),
-            "config_repo_companion_refs": list(self.config_repo_companion_refs),
-            "prior_knowledge_refs": list(self.prior_knowledge_refs),
-            "max_depth_level": int(self.max_depth_level or 0),
-            "depth_stop_reason": normalized_depth_stop_reason,
-        }
-
-
-PlannerFn = Callable[[int, dict[str, Any], list[AgentLoopStep]], AgentLoopAction | None]
-
-
-class BoundedAgentLoop:
-    """Deterministic, bounded autonomy loop over typed tool calls.
-
-    Orchestrator-specific behavior is injected via ``hooks``.  The default
-    ``NoOpHooks`` makes the loop fully generic (no audit coupling).
-    """
-
-    def __init__(
-        self,
-        registry: ToolRegistry,
-        config: AgentLoopConfig,
-        *,
-        planner: PlannerFn | None = None,
-        clock: Callable[[], float] | None = None,
-        hooks: LoopBehaviorHooks | None = None,
-    ) -> None:
-        self.registry = registry
-        self.config = config
-        self._planner = planner
-        self._clock = clock or time.monotonic
-        self._hooks = hooks or NoOpHooks()
-        self._call_history: set[str] = set()
-        self._stagnation_counter: int = 0
-        self._tracer = AgentTracer()
-
-    def run(
-        self,
-        *,
-        initial_context: dict[str, Any] | None = None,
-        reset_stagnation_counter: bool = False,
-    ) -> AgentLoopResult:
-        self._call_history.clear()
-        self._stagnation_counter = 0
-
-        context = dict(initial_context or {})
-        context["_loop_behavior_hooks"] = self._hooks
-        evidence_refs = list(context.get("evidence_refs") or [])
-        if "seed_evidence_refs" not in context:
-            context["seed_evidence_refs"] = list(evidence_refs)
-        if self.config.evidence_overrides:
-            context.setdefault("_evidence_overrides", self.config.evidence_overrides)
-
-        budget_remaining = max(0, int(self.config.budget_units))
-        _max_steps = max(0, int(self.config.max_steps))
-        timeout_seconds = max(0.0, float(self.config.timeout_seconds))
-        _tool_calls_limit = max(0, int(self.config.tool_calls_limit))
-        tool_calls_used = 0
-        trace: list[AgentLoopStep] = []
-        step_count = 0
-        max_depth_level = 0
-
-        started = self._clock()
-
-        if timeout_seconds == 0.0:
-            return self._build_result(
-                termination_reason=LoopTerminationReason.TIMEOUT,
-                steps_executed=0,
-                budget_remaining=budget_remaining,
-                elapsed_seconds=0.0,
-                evidence_refs=evidence_refs,
-                trace_steps=trace,
-                context=context,
-                max_depth_level=max_depth_level,
-            )
-
-        if budget_remaining <= 0:
-            return self._build_result(
-                termination_reason=LoopTerminationReason.BUDGET_EXHAUSTED,
-                steps_executed=0,
-                budget_remaining=0,
-                elapsed_seconds=max(0.0, self._clock() - started),
-                evidence_refs=evidence_refs,
-                trace_steps=trace,
-                context=context,
-                max_depth_level=max_depth_level,
-            )
-
-        trace_context = self._hooks.get_trace_context()
-        tracing_active = bool(trace_context) and self._tracer.is_enabled
-
-        if tracing_active:
-            config_for_tracer = {
-                "max_steps": self.config.max_steps,
-                "timeout_seconds": self.config.timeout_seconds,
-                "budget_units": self.config.budget_units,
-            }
-            loop_id = trace_context.get("loop_id", "unknown")
-            with self._tracer.trace_loop(loop_id, config_for_tracer) as loop_span:
-                if loop_span:
-                    for key, value in trace_context.items():
-                        if key != "loop_id" and value is not None:
-                            loop_span.set_attribute(f"trace.context.{key}", str(value))
-                result = self._run_loop(
-                    context=context,
-                    started=started,
-                    trace=trace,
-                    step_count=step_count,
-                    max_depth_level=max_depth_level,
-                    budget_remaining=budget_remaining,
-                    tool_calls_used=tool_calls_used,
-                    tracing_active=tracing_active,
-                    evidence_refs=evidence_refs,
-                )
-        else:
-            result = self._run_loop(
-                context=context,
-                started=started,
-                trace=trace,
-                step_count=step_count,
-                max_depth_level=max_depth_level,
-                budget_remaining=budget_remaining,
-                tool_calls_used=tool_calls_used,
-                tracing_active=tracing_active,
-                evidence_refs=evidence_refs,
-            )
-        return result
-
-    def _run_loop(
-        self,
-        *,
-        context: dict[str, Any],
-        started: float,
-        trace: list[AgentLoopStep],
-        step_count: int,
-        max_depth_level: int,
-        budget_remaining: int,
-        tool_calls_used: int,
-        tracing_active: bool,
-        evidence_refs: list[str],
-    ) -> AgentLoopResult:
-        """Inner loop implementation (extracted for tracing integration)."""
-        max_steps = max(0, int(self.config.max_steps))
-        timeout_seconds = max(0.0, float(self.config.timeout_seconds))
-        tool_calls_limit = max(0, int(self.config.tool_calls_limit))
-
-        while step_count < max_steps:
-            elapsed = max(0.0, self._clock() - started)
-            if elapsed >= timeout_seconds:
-                return self._build_result(
-                    termination_reason=LoopTerminationReason.TIMEOUT,
-                    steps_executed=step_count,
-                    budget_remaining=budget_remaining,
-                    elapsed_seconds=elapsed,
-                    evidence_refs=evidence_refs,
-                    trace_steps=trace,
-                    context=context,
-                    max_depth_level=max_depth_level,
-                )
-
-            action = self._next_action(step_count + 1, context, trace)
-            if action is None:
-                return self._finish_without_next_action(
-                    started=started,
-                    steps_executed=step_count,
-                    budget_remaining=budget_remaining,
-                    evidence_refs=evidence_refs,
-                    trace=trace,
-                    context=context,
-                    max_depth_level=max_depth_level,
-                )
-
-            if action.budget_cost > budget_remaining:
-                return self._build_result(
-                    termination_reason=LoopTerminationReason.BUDGET_EXHAUSTED,
-                    steps_executed=step_count,
-                    budget_remaining=budget_remaining,
-                    elapsed_seconds=max(0.0, self._clock() - started),
-                    evidence_refs=evidence_refs,
-                    trace_steps=trace,
-                    context=context,
-                    max_depth_level=max_depth_level,
-                )
-
-            with self._tracer.trace_tool_call(action.tool, dict(action.payload)) if tracing_active else _nullcontext():
-                try:
-                    response = self.registry.invoke(action.tool, action.payload)
-                except Exception as exc:
-                    return self._build_result(
-                        termination_reason=LoopTerminationReason.TOOL_ERROR,
-                        steps_executed=step_count,
-                        budget_remaining=budget_remaining,
-                        elapsed_seconds=max(0.0, self._clock() - started),
-                        evidence_refs=evidence_refs,
-                        trace_steps=trace,
-                        tool_error=f"{type(exc).__name__}: {exc}",
-                        context=context,
-                        max_depth_level=max_depth_level,
-                    )
-
-            step_count += 1
-            tool_calls_used += 1
-            budget_remaining = max(0, budget_remaining - action.budget_cost)
-            output_payload = response.payload
-            trace.append(
-                AgentLoopStep(
-                    step=step_count,
-                    tool=action.tool,
-                    budget_cost=action.budget_cost,
-                    budget_remaining=budget_remaining,
-                    output=output_payload,
-                    route_id=action.route_id,
-                    route_reason=action.route_reason,
-                    route_confidence=float(action.route_confidence or 0.0),
-                    ambiguity_reason_codes=list(action.ambiguity_reason_codes),
-                    required_steps=list(action.required_steps),
-                    required_tools=list(action.required_tools),
-                    override_source=action.override_source,
-                    override_reason=action.override_reason,
-                    depth_level=int(action.depth_level or 1),
-                    depth_increase_reason=action.depth_increase_reason,
-                    payload=dict(action.payload),
-                )
-            )
-            max_depth_level = max(max_depth_level, int(action.depth_level or 1))
-            context[f"tool_{action.tool}_output"] = output_payload
-
-            # Hook: wire context from first-step context query output
-            if (
-                self._hooks.should_skip_first_step(action.tool, context)
-                and step_count == 1
-                and "control_objective" not in context
-            ):
-                _grc_ctx = output_payload.get("context", {}) if isinstance(output_payload, dict) else {}
-                _interp = _grc_ctx.get("requirement_interpretation", {}) if isinstance(_grc_ctx, dict) else {}
-                _control_obj = (
-                    str(_interp.get("control_objective") or "").strip() if isinstance(_interp, dict) else ""
-                ) or (str(_grc_ctx.get("requirement_category") or "").strip() if isinstance(_grc_ctx, dict) else "")
-                if _control_obj:
-                    context["control_objective"] = _control_obj
-
-            if action.route_id:
-                context["route_id"] = action.route_id
-                context["route_reason"] = action.route_reason
-                context["route_confidence"] = float(action.route_confidence or 0.0)
-                context["ambiguity_reason_codes"] = list(action.ambiguity_reason_codes)
-                context["required_steps"] = list(action.required_steps)
-                context["required_tools"] = list(action.required_tools)
-                context["override_source"] = action.override_source
-                context["override_reason"] = action.override_reason
-
-            prev_evidence_count = len(evidence_refs)
-
-            # Hook: check if this tool records evidence
-            if self._hooks.is_evidence_recording(action.tool):
-                rows = output_payload.get("refs") or []
-                evidence_refs = [str(row.get("ref_value", "")) for row in rows if row.get("ref_value")]
-                context["evidence_refs"] = evidence_refs
-
-            # Stagnation detection
-            _is_breadth_enforcement = action.route_reason == "breadth_enforcement"
-            call_hash = self._compute_call_hash(action.tool, action.payload)
-            if _is_breadth_enforcement:
-                self._call_history.add(call_hash)
-                self._stagnation_counter = 0
-            elif call_hash in self._call_history:
-                self._stagnation_counter += 1
-            else:
-                self._call_history.add(call_hash)
-                self._stagnation_counter = 0
-
-            # Hook: use is_context_query instead of hardcoded ToolName.GET_ROW_CONTEXT
-            if (
-                not _is_breadth_enforcement
-                and len(evidence_refs) == prev_evidence_count
-                and not self._hooks.is_context_query(action.tool)
-            ):
-                self._stagnation_counter += 1
-
-            effective_stagnation_threshold = self._effective_stagnation_threshold(
-                context,
-                self.config.stagnation_threshold,
-                step_count,
-            )
-
-            if self._stagnation_counter >= effective_stagnation_threshold:
-                return self._build_result(
-                    termination_reason=LoopTerminationReason.STAGNATION,
-                    steps_executed=step_count,
-                    budget_remaining=budget_remaining,
-                    elapsed_seconds=max(0.0, self._clock() - started),
-                    evidence_refs=evidence_refs,
-                    trace_steps=trace,
-                    context=context,
-                    max_depth_level=max_depth_level,
-                )
-
-            if tool_calls_limit > 0 and tool_calls_used >= tool_calls_limit:
-                return self._build_result(
-                    termination_reason=LoopTerminationReason.BUDGET_EXHAUSTED,
-                    steps_executed=step_count,
-                    budget_remaining=budget_remaining,
-                    elapsed_seconds=max(0.0, self._clock() - started),
-                    evidence_refs=evidence_refs,
-                    trace_steps=trace,
-                    context=context,
-                    max_depth_level=max_depth_level,
-                )
-
-        # Hook: use has_read_activity instead of hardcoded ToolName check
-        if self._hooks.has_read_activity(trace):
-            next_action = self._next_action(step_count + 1, context, trace)
-            if next_action is None:
-                return self._finish_without_next_action(
-                    started=started,
-                    steps_executed=step_count,
-                    budget_remaining=budget_remaining,
-                    evidence_refs=evidence_refs,
-                    trace=trace,
-                    context=context,
-                    max_depth_level=max_depth_level,
-                )
-
-        return self._build_result(
-            termination_reason=LoopTerminationReason.MAX_STEPS,
-            steps_executed=step_count,
-            budget_remaining=budget_remaining,
-            elapsed_seconds=max(0.0, self._clock() - started),
-            evidence_refs=evidence_refs,
-            trace_steps=trace,
-            context=context,
-            max_depth_level=max_depth_level,
-        )
-
-    def _next_action(
-        self,
-        step_number: int,
-        context: dict[str, Any],
-        trace: list[AgentLoopStep],
-    ) -> AgentLoopAction | None:
-        if self._planner is None:
-            return None
-        return self._planner(step_number, context, trace)
-
-    def _finish_without_next_action(
-        self,
-        *,
-        started: float,
-        steps_executed: int,
-        budget_remaining: int,
-        evidence_refs: list[str],
-        trace: list[AgentLoopStep],
-        context: dict[str, Any],
-        max_depth_level: int,
-    ) -> AgentLoopResult:
-        if self.config.require_evidence and len(evidence_refs) < max(1, self.config.min_evidence_refs):
-            reason = LoopTerminationReason.INSUFFICIENT_EVIDENCE
-        else:
-            reason = self._apply_evidence_gate(evidence_refs=evidence_refs, trace=trace, context=context)
-
-        return self._build_result(
-            termination_reason=reason,
-            steps_executed=steps_executed,
-            budget_remaining=budget_remaining,
-            elapsed_seconds=max(0.0, self._clock() - started),
-            evidence_refs=evidence_refs,
-            trace_steps=trace,
-            context=context,
-            max_depth_level=max_depth_level,
-        )
-
-    def _apply_evidence_gate(
-        self,
-        *,
-        evidence_refs: list[str],
-        trace: list[AgentLoopStep],
-        context: dict[str, Any],
-    ) -> LoopTerminationReason:
-        """Control-objective evidence gate — delegates to hooks for requirements lookup."""
-        if int(context.get("evidence_gate_retry_count") or 0) >= 1:
-            return LoopTerminationReason.COMPLETED
-
-        requirements = self._hooks.lookup_evidence_requirements(context)
-
-        # Only orchestrator-specific rows have stricter requirements.
-        # If requirements dict is empty or explicitly marked as default, skip the gate.
-        # Non-default requirements (e.g., architecture rows) must have min_evidence_refs.
-        if not requirements or requirements.get("is_default", False):
-            return LoopTerminationReason.COMPLETED
-
-        search_pattern_count = sum(1 for step in trace if step.tool == "search_code")
-        evidence_count = len(evidence_refs)
-        min_refs: int = requirements.get("min_evidence_refs", 1)
-        min_searches: int = requirements.get("min_search_patterns", 1)
-
-        if evidence_count < min_refs or search_pattern_count < min_searches:
-            context["control_objective_evidence_gate_applied"] = True
-            context["required_min_evidence_refs"] = min_refs
-            context["required_min_search_patterns"] = min_searches
-            context["observed_evidence_refs"] = evidence_count
-            context["observed_search_patterns"] = search_pattern_count
-            context["evidence_gate_reason_code"] = "evidence_gate_failed"
-            return LoopTerminationReason.INSUFFICIENT_EVIDENCE
-
-        return LoopTerminationReason.COMPLETED
-
-    @staticmethod
-    def _effective_stagnation_threshold(
-        context: dict[str, Any],
-        base_threshold: int,
-        current_step: int,
-    ) -> int:
-        """Raise stagnation threshold for cross-repo exploration rows."""
-        _CROSS_REPO_GRACE_STEPS = 10
-        _CROSS_REPO_TAGS = {"shared_library", "config_pattern", "architecture"}
-
-        scope_hint = str(context.get("scope_hint") or "").strip().lower()
-        requirement_type_tag = str(context.get("requirement_type_tag") or "").strip().lower()
-
-        is_cross_repo = (
-            scope_hint in {"all", "lib", "config"}
-            or requirement_type_tag in _CROSS_REPO_TAGS
-            or bool(context.get("shared_library_routing_activated"))
-            or bool(context.get("config_repo_companion_applied"))
-        )
-
-        if is_cross_repo and current_step <= _CROSS_REPO_GRACE_STEPS:
-            return max(base_threshold, base_threshold * 2)
-
-        return base_threshold
-
-    @staticmethod
-    def _compute_call_hash(tool_name: str, payload: dict[str, Any]) -> str:
-        """Compute a deterministic hash for a tool call to detect repetition."""
-        normalized = json.dumps({"tool": tool_name, "args": payload}, sort_keys=True, separators=(",", ":"))
-        return hashlib.sha256(normalized.encode("utf-8")).hexdigest()[:16]
-
-    def _count_docs_tool_steps(self, trace_steps: list[AgentLoopStep]) -> int:
-        """Count doc-related tool steps using hooks."""
-        return self._hooks.count_doc_reads(trace_steps)
-
-    @staticmethod
-    def _count_docs_tool_steps_from_trace(
-        *,
-        context: dict[str, Any],
-        trace_steps: list[AgentLoopStep],
-    ) -> int:
-        hooks = context.get("_loop_behavior_hooks")
-        count_doc_reads = getattr(hooks, "count_doc_reads", None)
-        if callable(count_doc_reads):
-            return int(count_doc_reads(trace_steps))
-        return 0
-
-    @staticmethod
-    def _count_doc_search_steps_from_trace(
-        *,
-        context: dict[str, Any],
-        trace_steps: list[AgentLoopStep],
-    ) -> int:
-        hooks = context.get("_loop_behavior_hooks")
-        is_doc_search = getattr(hooks, "is_doc_search", None)
-        if not callable(is_doc_search):
-            return 0
-        return sum(1 for step in trace_steps if is_doc_search(str(step.tool)))
-
-    @classmethod
-    def _docs_intent_utilization(
-        cls,
-        *,
-        context: dict[str, Any],
-        trace_steps: list[AgentLoopStep],
-    ) -> dict[str, Any]:
-        def _route_mode(value: Any, *, route_id_value: str) -> str:
-            mode = str(value or "").strip()
-            if mode:
-                return mode
-            normalized_route_id = str(route_id_value or "").strip().lower()
-            if normalized_route_id.startswith("docs_"):
-                return "docs_only"
-            if normalized_route_id.startswith("code_"):
-                return "code_only"
-            if normalized_route_id.startswith("hybrid_docs_first"):
-                return "hybrid_docs_first"
-            if normalized_route_id.startswith("hybrid_code_first"):
-                return "hybrid_code_first"
-            return ""
-
-        route_decision = context.get("tool_first_route_decision")
-        route_payload = route_decision if isinstance(route_decision, dict) else {}
-        route_id = str(route_payload.get("route_id") or context.get("route_id") or "").strip()
-        route_mode = _route_mode(route_payload.get("route_mode"), route_id_value=route_id)
-        docs_target = bool(route_payload.get("docs_target"))
-        code_target = bool(route_payload.get("code_target"))
-        is_hybrid_route = route_id.startswith("hybrid_")
-        docs_path_expected = bool(route_id.startswith("docs_") or is_hybrid_route or docs_target)
-        docs_step_count = cls._count_docs_tool_steps_from_trace(context=context, trace_steps=trace_steps)
-        docs_search_step_count = cls._count_doc_search_steps_from_trace(context=context, trace_steps=trace_steps)
-        docs_read_step_count = max(0, docs_step_count - docs_search_step_count)
-        docs_hit_count = 0
-        hooks = context.get("_loop_behavior_hooks")
-        is_doc_search = getattr(hooks, "is_doc_search", None)
-        for step in trace_steps:
-            if not callable(is_doc_search) or not is_doc_search(str(step.tool)):
-                continue
-            output_payload = step.output if isinstance(step.output, dict) else {}
-            hits = output_payload.get("hits")
-            if isinstance(hits, list):
-                docs_hit_count += len(hits)
-        docs_path_executed = docs_step_count > 0
-        docs_path_effective = docs_read_step_count > 0
-        docs_skip_reason: str | bool = False
-        if docs_path_expected and not docs_path_effective:
-            explicit_reason = str(context.get("tool_first_docs_skip_reason") or "").strip()
-            if explicit_reason:
-                docs_skip_reason = explicit_reason
-            elif docs_search_step_count > 0 and docs_hit_count == 0:
-                docs_skip_reason = "docs_search_no_hits"
-            elif docs_search_step_count > 0 and docs_hit_count > 0 and docs_read_step_count == 0:
-                docs_skip_reason = "docs_search_hits_not_read"
-            else:
-                runtime_context = (
-                    context.get("tool_get_row_context_output", {}).get("context", {}).get("runtime_context", {})
-                )
-                state_ready = bool(runtime_context.get("state_dsn")) and bool(runtime_context.get("project_key"))
-                if not state_ready:
-                    docs_skip_reason = "docs_state_unavailable"
-                elif is_hybrid_route and code_target:
-                    docs_skip_reason = "hybrid_route_prioritized_code_path"
-                elif docs_path_executed and docs_read_step_count == 0:
-                    docs_skip_reason = "docs_path_executed_without_read"
-                else:
-                    docs_skip_reason = "docs_path_not_executed"
-
-        db_family_payload = context.get("tool_first_db_family_coverage")
-        db_family_requirement = bool(
-            db_family_payload.get("db_requirement") if isinstance(db_family_payload, dict) else False
-        )
-        route_escalation_required = bool(route_mode == "docs_only" and (code_target or db_family_requirement))
-        route_escalation_applied = False
-        route_escalation_reason: str | bool = False
-        route_escalation_step_index: int | bool = False
-        if route_escalation_required:
-            transitions = context.get("tool_first_route_transitions")
-            if isinstance(transitions, list):
-                for entry in transitions:
-                    if not isinstance(entry, dict):
-                        continue
-                    from_mode = _route_mode(
-                        entry.get("from_route_mode"),
-                        route_id_value=str(entry.get("from_route_id") or ""),
-                    )
-                    to_mode = _route_mode(
-                        entry.get("to_route_mode"),
-                        route_id_value=str(entry.get("to_route_id") or ""),
-                    )
-                    if from_mode != "docs_only" or to_mode not in {"hybrid_code_first", "code_only"}:
-                        continue
-                    route_escalation_applied = True
-                    transition_reason = str(entry.get("reason") or "").strip()
-                    route_escalation_reason = transition_reason or "docs_only_route_code_fallback"
-                    try:
-                        step_index = int(entry.get("step_number") or 0)
-                    except (TypeError, ValueError):
-                        step_index = 0
-                    route_escalation_step_index = step_index if step_index > 0 else False
-                    break
-            if not route_escalation_applied:
-                explicit_reason = str(context.get("tool_first_docs_skip_reason") or "").strip()
-                if explicit_reason:
-                    route_escalation_reason = explicit_reason
-                elif docs_path_effective:
-                    route_escalation_reason = "docs_path_effective"
-                elif docs_search_step_count > 0 and docs_hit_count == 0:
-                    route_escalation_reason = "docs_search_no_hits"
-                elif docs_search_step_count > 0 and docs_hit_count > 0 and docs_read_step_count == 0:
-                    route_escalation_reason = "docs_search_hits_not_read"
-                elif not docs_path_executed:
-                    route_escalation_reason = "docs_path_not_executed"
-                else:
-                    route_escalation_reason = "route_escalation_not_applied"
-        return {
-            "route_id": route_id,
-            "route_mode": route_mode or False,
-            "docs_target": docs_target,
-            "code_target": code_target,
-            "is_hybrid_route": is_hybrid_route,
-            "docs_path_expected": docs_path_expected,
-            "docs_path_executed": docs_path_executed,
-            "docs_path_effective": docs_path_effective,
-            "docs_step_count": docs_step_count,
-            "docs_search_step_count": docs_search_step_count,
-            "docs_read_step_count": docs_read_step_count,
-            "docs_hit_count": docs_hit_count,
-            "docs_skip_reason": docs_skip_reason,
-            "docs_path_skip_reason": docs_skip_reason,
-            "db_family_requirement": db_family_requirement,
-            "route_escalation_required": route_escalation_required,
-            "route_escalation_applied": route_escalation_applied,
-            "route_escalation_reason": route_escalation_reason,
-            "route_escalation_step_index": route_escalation_step_index,
-        }
-
-    @staticmethod
-    def _resolve_depth_stop_reason(
-        *,
-        context: dict[str, Any],
-        termination_reason: LoopTerminationReason,
-        max_depth_level: int,
-    ) -> str | None:
-        if max_depth_level <= 1:
-            return None
-        explicit = str(context.get("tool_first_depth_stop_reason") or "").strip()
-        if explicit:
-            return explicit
-        reason_map: dict[LoopTerminationReason, str] = {
-            LoopTerminationReason.COMPLETED: "planner_converged",
-            LoopTerminationReason.INSUFFICIENT_EVIDENCE: "planner_converged",
-            LoopTerminationReason.MAX_STEPS: "max_steps_reached",
-            LoopTerminationReason.TIMEOUT: "timeout_reached",
-            LoopTerminationReason.BUDGET_EXHAUSTED: "budget_exhausted",
-            LoopTerminationReason.STAGNATION: "stagnation_guardrail",
-            LoopTerminationReason.TOOL_ERROR: "tool_error",
-        }
-        return reason_map.get(termination_reason)
-
-    def _build_result(
-        self,
-        *,
-        termination_reason: LoopTerminationReason,
-        steps_executed: int,
-        budget_remaining: int,
-        elapsed_seconds: float,
-        evidence_refs: list[str],
-        trace_steps: list[AgentLoopStep],
-        context: dict[str, Any],
-        max_depth_level: int,
-        tool_error: str | None = None,
-    ) -> AgentLoopResult:
-        docs_intent_utilization = self._docs_intent_utilization(context=context, trace_steps=trace_steps)
-        raw_code_ranking = context.get("tool_first_code_ranking_diagnostics")
-        code_ranking_diagnostics = dict(raw_code_ranking) if isinstance(raw_code_ranking, dict) else {}
-        requirement_analysis_snapshot: dict[str, Any] = {}
-        raw_requirement_analysis = context.get("requirement_analysis")
-        if isinstance(raw_requirement_analysis, dict):
-            requirement_analysis_snapshot = dict(raw_requirement_analysis)
-        else:
-            requirement_analysis_snapshot = {
-                key: context.get(key) for key in _REQUIREMENT_ANALYSIS_DIAGNOSTIC_KEYS if key in context
-            }
-        if requirement_analysis_snapshot:
-            existing_snapshot = code_ranking_diagnostics.get("requirement_analysis")
-            if not isinstance(existing_snapshot, dict) or not existing_snapshot:
-                code_ranking_diagnostics["requirement_analysis"] = requirement_analysis_snapshot
-        if context.get("control_objective_evidence_gate_applied"):
-            code_ranking_diagnostics["evidence_gate"] = {
-                "applied": True,
-                "control_objective": context.get("control_objective"),
-                "required_min_evidence_refs": context.get("required_min_evidence_refs"),
-                "required_min_search_patterns": context.get("required_min_search_patterns"),
-                "observed_evidence_refs": context.get("observed_evidence_refs"),
-                "observed_search_patterns": context.get("observed_search_patterns"),
-                "reason_code": context.get("evidence_gate_reason_code"),
-            }
-        for _p172_key in (
-            "skill_first_loaded_at_step",
-            "search_pattern_diversity_count",
-            "breadth_enforcement_applied",
-            "control_objective_evidence_gate_applied",
-            "required_min_evidence_refs",
-            "required_min_search_patterns",
-            "diversity_gate_waived",
-            "skill_content_hash",
-        ):
-            if _p172_key in context:
-                code_ranking_diagnostics[_p172_key] = context[_p172_key]
-        normalized_max_depth = max_depth_level
-        if normalized_max_depth <= 0 and trace_steps:
-            normalized_max_depth = max(int(step.depth_level or 1) for step in trace_steps)
-        depth_stop_reason = self._resolve_depth_stop_reason(
-            context=context,
-            termination_reason=termination_reason,
-            max_depth_level=normalized_max_depth,
-        )
-        return AgentLoopResult(
-            termination_reason=termination_reason,
-            steps_executed=steps_executed,
-            budget_remaining=budget_remaining,
-            elapsed_seconds=elapsed_seconds,
-            evidence_refs=evidence_refs,
-            trace_steps=trace_steps,
-            tool_error=tool_error,
-            docs_intent_utilization=docs_intent_utilization,
-            code_ranking_diagnostics=code_ranking_diagnostics,
-            project_artifact_refs=list(context.get("project_artifact_refs") or []),
-            cross_repo_evidence_refs=list(context.get("cross_repo_evidence_refs") or []),
-            config_repo_companion_refs=list(context.get("config_repo_companion_refs") or []),
-            prior_knowledge_refs=list(context.get("prior_knowledge_refs") or []),
-            max_depth_level=normalized_max_depth,
-            depth_stop_reason=depth_stop_reason,
-        )