Function finalize_agent_tool

src/agent/agent_tool_utils.py:200–266

Extract final result from agent messages. Mirrors finalizeAgentTool() from typescript/src/tools/AgentTool/agentToolUtils.ts. Chapter-10 / Chunk C / WI-2.4: token aggregation now goes through ``ProgressTracker``. Pre-WI-2.4 ``total_tokens`` was hard-coded to ``0`` (gap-analysis §2.2

(
    agent_messages: list[Message],
    agent_id: str,
    metadata: dict[str, Any],
    *,
    progress: Any | None = None,
)

def finalize_agent_tool(
    agent_messages: list[Message],
    agent_id: str,
    metadata: dict[str, Any],
    *,
    progress: Any | None = None,
) -> AgentToolResult:
    """Extract final result from agent messages.

    Mirrors finalizeAgentTool() from typescript/src/tools/AgentTool/agentToolUtils.ts.

    Chapter-10 / Chunk C / WI-2.4: token aggregation now goes through
    ``ProgressTracker``. Pre-WI-2.4 ``total_tokens`` was hard-coded to
    ``0`` (gap-analysis §2.2 row); post-WI-2.4 callers pass the live
    tracker via the ``progress`` keyword and we read the chapter-correct
    ``latest_input_tokens + cumulative_output_tokens`` total off it. If
    the caller can't supply a tracker (e.g. a sync agent that didn't
    feed one during iteration), we fall back to recomputing from
    ``message.usage`` so the behavior degrades gracefully rather than
    silently returning zero.
    """
    # Find the last assistant message
    last_assistant: AssistantMessage | None = None
    for msg in reversed(agent_messages):
        if isinstance(msg, AssistantMessage):
            last_assistant = msg
            break

    if last_assistant is None:
        raise ValueError("No assistant messages found")

    # Extract text content from the agent's response
    content: list[dict[str, Any]] = []
    raw_content = last_assistant.content
    if isinstance(raw_content, str):
        if raw_content:
            content = [{"type": "text", "text": raw_content}]
    elif isinstance(raw_content, list):
        for block in raw_content:
            if hasattr(block, "type") and block.type == "text":
                content.append({"type": "text", "text": block.text})

    # If no text content in last message, search backwards
    if not content:
        for msg in reversed(agent_messages):
            if isinstance(msg, AssistantMessage):
                raw = msg.content
                if isinstance(raw, list):
                    for block in raw:
                        if hasattr(block, "type") and block.type == "text":
                            content.append({"type": "text", "text": block.text})
                    if content:
                        break

    total_tool_use_count = count_tool_uses(agent_messages)
    start_time = metadata.get("start_time", time.time())
    duration_ms = int((time.time() - start_time) * 1000)
    total_tokens = _resolve_total_tokens(progress, agent_messages)