Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

86.3 KB
Raw Blame
"""Tool-use loop: coordinates brain calls + tool execution across multiple turns.

Flow:
  1. Send request to brain (with tools spec)
  2. Consume stream → aggregate text + tool-calls
  3. If `finish_reason == "tool_use"` or tool-calls present:
       a. Per tool-call: lookup + intent sanity check + ToolExecutor.execute()
       b. Append tool result as new `BrainMessage(role="tool", ...)`
       c. Budget check
       d. Back to step 1 with extended messages
  4. Otherwise: done, return text
"""
from __future__ import annotations

import asyncio
import json
import logging
import re
import time
from collections.abc import Awaitable, Callable, Iterable
from typing import Any
from uuid import UUID, uuid4

from dodaios.brain.cu_gate import (
    CU_BLOCKED_MODEL_FEEDBACK,
    CU_VEHICLE_TOOL_NAMES,
    llm_computer_use_allowed,
)
from dodaios.brain.spawn_gate import (
    SPAWN_VEHICLE_TOOL_NAMES,
    llm_spawn_allowed,
    names_spawn_vehicle,
    spawn_blocked_feedback,
)
from dodaios.core.protocols import (
    Brain,
    BrainMessage,
    BrainRequest,
    ImageBlock,
    ReasoningEffort,
    Tool,
)
from dodaios.core.turn_language import TURN_LANGUAGE, resolve_output_language
from dodaios.i18n import catalog as i18n_catalog
from dodaios.safety.tool_executor import VOICE_CONFIRM_SENTINEL, ToolExecutor

from .iteration_budget import IterationBudget
from .loop_control import (
    PHASE_ACT,
    PHASE_GATHER,
    PHASE_VERIFY,
    LoopControl,
    ToolRecord,
    VerifyOutcome,
    VerifyRequest,
)
from .streaming import StreamingAggregate, aggregate, aggregate_with_consumer
from .tool_call_recovery import extract_leaked_tool_calls
from .tool_shortlist import FIND_TOOLS_NAME

# Central backstop for tool-output bloat: no tool result may exceed this many
# chars in the tool-role message fed back to the brain. Individual tools should
# self-slim (a raw Gmail ``format=full`` message is ~23k chars of headers +
# base64), but this cap guarantees a bound for EVERY tool — present and future —
# so one verbose provider can never flood the context, slow the turn and crowd
# out the answer (live bug 2026-07-01). The event-bus/DB preview cap
# (``safe_preview``) is a separate path and never touched what the model saw.
# Maintainer mandate 2026-08-24: context caps are not a cost lever; the bound
# exists only so one runaway result cannot exceed a provider window outright.
_MAX_TOOL_RESULT_CHARS = 100_000

# Directive appended for the deadline-forced final round (see ``deadline_s``).
# English on purpose: it is model-facing prompt text, never spoken to the user.
_DEADLINE_FINAL_DIRECTIVE = (
    "[time budget exhausted] Answer the user NOW in one or two spoken "
    "sentences using ONLY the tool evidence gathered above. If the evidence "
    "is incomplete, say honestly what you could and could not verify. Do "
    "not call any more tools."
)

# Directive appended for the budget-forced final round (see IterationBudget).
# Exhausting the round budget used to hard-break the loop and DISCARD every
# executed tool result: live 2026-07-17, a delegated voice turn had two fully
# loaded Gmail messages in hand when round 6 hit the cap — the turn returned
# empty text and the user heard "the plugins did not work" although every
# call had succeeded. Mirror the deadline path instead: one last tool-less
# synthesis round over the evidence that is already in the conversation.
_BUDGET_FINAL_DIRECTIVE = (
    "[round budget exhausted] Answer the user NOW in one or two spoken "
    "sentences using ONLY the tool evidence gathered above. If the evidence "
    "is incomplete, say honestly what you could and could not verify. Do "
    "not call any more tools."
)

# What a message the person sent DURING the turn looks like when it reaches the
# model. It is folded into the running job rather than starting a new one, so
# the model must be told that this is a correction in flight, not a new task.
_STEER_PREFIX = (
    "[the person added this while you were working - fold it into the job you "
    "are on, do not start over]\n"
)

# What a failed verification tells the model. Unlike the directives above this
# one keeps the tools: a revision usually needs to LOOK again, not just rewrite.
_VERIFY_DIRECTIVE = (
    "[verification] Your answer was checked against what you actually did. "
    "Fix this, then answer the person again in full:\n"
)

# A provider can repeat the exact same text-serialized call after receiving its
# result. The action must remain exactly-once, but the turn must not end on an
# empty ``tool_use`` round. Force one tool-less synthesis pass instead.
_DUPLICATE_CALL_FINAL_DIRECTIVE = (
    "[duplicate tool call suppressed] The exact requested tool call already "
    "ran and its result is available above. Answer the user NOW from that "
    "evidence. Do not call any more tools."
)


def _cap_tool_result_json(serialized: str) -> str:
    """Truncate an over-long serialized tool result, leaving an honest marker so
    the model knows the payload was clipped (rather than silently ending)."""
    if len(serialized) <= _MAX_TOOL_RESULT_CHARS:
        return serialized
    kept = serialized[:_MAX_TOOL_RESULT_CHARS]
    return (
        f"{kept}… [truncated: tool output was {len(serialized)} chars, "
        f"capped at {_MAX_TOOL_RESULT_CHARS}]"
    )


def _last_user_text(messages: list[BrainMessage]) -> str:
    """The ask a verifier judges against, when the caller passed none.

    A steer line is skipped: the person's original request is what the answer
    has to satisfy, not the correction that refined it.
    """
    for message in reversed(messages):
        if message.role != "user" or not isinstance(message.content, str):
            continue
        text = message.content
        if text.startswith(_STEER_PREFIX) or text.startswith("["):
            continue
        return text
    return ""


def _tool_call_signature(call: dict[str, Any]) -> tuple[str, str]:
    """Canonical name/arguments fingerprint for same-round duplicate calls."""
    arguments = call.get("input", {})
    return (
        str(call.get("name") or ""),
        json.dumps(arguments, sort_keys=True, separators=(",", ":"), default=str),
    )


def _images_from_artifacts(artifacts: object) -> list[ImageBlock]:
    """Extract ImageBlocks from a tool's artifacts (Wave 2 on-demand vision).

    A vision-capable tool (e.g. the screenshot tool) returns
    ``artifacts=({"type": "image", "mime": ..., "data": <base64>},)``. Each image
    artifact becomes an ImageBlock so it can ride on a user-role message back into
    the conversation. Non-image / malformed artifacts are skipped.
    """
    blocks: list[ImageBlock] = []
    for art in artifacts or ():
        if isinstance(art, dict) and art.get("type") == "image" and art.get("data"):
            blocks.append(ImageBlock(
                mime=str(art.get("mime") or "image/jpeg"),
                data_b64=str(art["data"]),
            ))
    return blocks

log = logging.getLogger(__name__)

# Research keywords — if any of these appear in the user utterance, an
# action tool-call (CLI or MCP) is almost always wrong. The sanity check below
# blocks it without executing the tool, and gives the LLM a redirect hint.
_RESEARCH_KEYWORDS = re.compile(
    r"\b("
    r"recherchier\w*|analysier\w*|erklaer\w*|erklär\w*|"  # i18n-allow: German input-matching data (research-intent classifier)
    r"untersuch\w*|vergleich\w*|zusammenfass\w*|"
    r"research|analy[sz]e|explain|compare|summari[sz]e"
    r")\b",
    re.IGNORECASE,
)

# Meta/debug conversation: the user is talking ABOUT the assistant's own
# machinery (its provider, its transcript, the phrase it just spoke) instead of
# giving it a task. Two tiers on purpose. The earlier single tier listed bare
# everyday words — "fehler", "log", "bug", "provider", "brain", "phrase" — so a  # i18n-allow
# perfectly ordinary work turn ("Zeig mir den Fehler im Log und starte den  # i18n-allow
# Dienst neu") was classified as meta-conversation and answered with a canned
# question instead of being carried out.
#
# STRONG markers name assistant machinery with no everyday reading; they stand
# on their own and keep the guard's original case ("Warum hat der
# Provider-Fallback gegriffen?") intact.
_META_DEBUG_STRONG_RE = re.compile(
    r"\b("
    r"api\s*key|"
    r"provider[-\s]*fallback|fallback[-\s]*provider|"
    r"text[-\s]*to[-\s]*speech|tts|"
    r"standardantwort|standardphrase|"  # i18n-allow: input-matching data
    r"jarvis\s+sagt|"  # i18n-allow: input-matching data
    r"verstehst\s+du\s+was\s+ich\s+meine"  # i18n-allow: input-matching data
    r")\b",
    re.IGNORECASE,
)

# WEAK markers are everyday words. They mean meta-conversation ONLY when the
# turn also points at the assistant itself ("dein Log", "warum sagst du das").
_META_DEBUG_WEAK_RE = re.compile(
    r"\b("
    r"provider|brain|transkript|transcript|log|bug|debug|"  # i18n-allow: input data
    r"fehler|fallback|phrase"  # i18n-allow: input-matching data
    r")\b",
    re.IGNORECASE,
)

# The turn points AT the assistant: a possessive about its output, its name, or
# a second-person "you said" construction. Deliberately NOT a bare "du"/"you" —
# every second request to an assistant contains one ("Kannst du das Log holen"),
# which is exactly how an everyday word became a meta verdict.
_ASSISTANT_SELF_REFERENCE_RE = re.compile(
    r"(?:"
    r"\bdein\w*\b"  # i18n-allow: input-matching data
    r"|\bjarvis\b"
    r"|\byour\b|\byours\b"
    r"|\bdu\s+(?:sagst|sagtest|antwortest|meinst)\b"  # i18n-allow: input data
    r"|\b(?:sagst|sagtest|antwortest|meinst)\s+du\b"  # i18n-allow: input data
    r"|\b(?:hast|hattest)\s+du\b.{0,40}?\bgesagt\b"  # i18n-allow: input data
    r"|\byou\s+(?:said|say|keep\s+saying|answered|replied)\b"
    r"|\btu\s+respuesta\b"
    r")",
    re.IGNORECASE,
)

_INSTRUCTIONAL_QUESTION_RE = re.compile(
    r"^\s*(?:"
    r"wie\s+(?:kann|koennte|könnte|muss|soll|mach|mache|macht|geht|funktioniert)\s+"  # i18n-allow: German input-matching data (instructional-question classifier)
    r"|was\s+(?:ist|bedeutet|heisst|heißt)\s+"  # i18n-allow: same German input-matching data
    r"|woran\s+erkenne\s+"
    r"|warum\s+"
    r"|how\s+(?:do|can|could|should|would)\s+"
    r"|what\s+(?:is|does|are)\s+"
    r"|why\s+"
    r")",
    re.IGNORECASE,
)

# Clause break inside one spoken turn: punctuation or a coordinating particle.
_CLAUSE_BREAK_RE = re.compile(
    r"[,;:.!?]+"
    r"|\b(?:und|aber|dann|jetzt|also)\b"  # i18n-allow: input-matching data
    r"|\b(?:and|but|then|now)\b"
    r"|\b(?:y|pero|luego|ahora)\b",  # i18n-allow: input-matching data
    re.IGNORECASE,
)

# Bare 2nd-person imperative stems (DE/EN/ES). German infinitives are NOT
# listed and cannot match: "oeffnen"/"machen" have no word boundary after  # i18n-allow
# imperative stem, so only the real command form ("oeffne", "mach") hits.
_IMPERATIVE_VERB_RE = re.compile(
    r"\b("
    r"mach|mache|oeffne|öffne|starte|beende|"  # i18n-allow: input-matching data
    r"schliess|schließ|schliesse|schließe|"  # i18n-allow: input-matching data
    r"stopp|stoppe|pausier|pausiere|spiel|spiele|"  # i18n-allow: input data
    r"zeig|zeige|lies|schick|schicke|"  # i18n-allow: input-matching data
    r"schreib|schreibe|loesch|lösch|loesche|lösche|"  # i18n-allow: input data
    r"installier|installiere|kopier|kopiere|"  # i18n-allow: input-matching data
    r"klick|klicke|tipp|tippe|drueck|drück|"  # i18n-allow: input-matching data
    r"wechsle|wechsel|setz|setze|stell|stelle|"  # i18n-allow: input data
    r"leg|lege|hol|hole|nimm|geh|fahr|fahre|"  # i18n-allow: input-matching data
    r"aktivier|aktiviere|deaktivier|deaktiviere|"  # i18n-allow: input data
    r"open|close|restart|reboot|run|launch|play|send|install|uninstall|delete|"
    r"remove|click|type|switch|show|list|turn|stop|start|"
    r"abre|cierra|inicia|reinicia|ejecuta|envia|envía|"  # i18n-allow: input data
    r"borra|instala|pon|haz|muestra|reproduce"  # i18n-allow: input data
    r")\b",
    re.IGNORECASE,
)

# German 1st-person indicative shares its form with the imperative ("starte"),
# so "…und wie starte ICH das neu?" would otherwise read as a command. A  # i18n-allow
# imperative never carries an explicit subject pronoun.
_INDICATIVE_SUBJECT_RE = re.compile(
    r"\s*(?:ich|man|wir|i|we|you|yo|uno)\b",  # i18n-allow: input data
    re.IGNORECASE,
)

# English puts the subject in FRONT of the verb ("…and how do I restart it?"),
# and an infinitive marker reads the same way ("to open"). Either kills the
# imperative reading just as an explicit German subject does.
_INDICATIVE_SUBJECT_BEFORE_RE = re.compile(
    r"\b(?:i|you|we|they|to|ich|man|wir|zu|que)\s+$",  # i18n-allow: input data
    re.IGNORECASE,
)

# Self-identification patterns: user introduces themselves (name, salutation, pronouns).
# These utterances must NEVER trigger side-effect tools — the Curator
# (dodaios/memory/curator/) extracts the facts automatically in the background
# and merges them into USER.md. Observation 2026-05-05: Gemini-3-Flash-Preview
# interpreted "Ich heiße Ruben Lütke" as a task and spawned a Phase-6  # i18n-allow: forensic quote of the actual German utterance that triggered this bug
# worker for a manual USER.md edit (failed with exit_code=1) —
# a clear tool-choice misfire in weaker models.
_SELF_IDENTIFICATION_RE = re.compile(
    r"^\s*(?:"
    r"ich\s+(?:heisse|heiße)\s+\w+"  # i18n-allow: same German input-matching data (self-identification classifier)
    r"|mein\s+name\s+(?:ist|lautet)\s+\w+"
    r"|nenn(?:e|en\s+sie)?\s+mich\s+\w+"
    r"|du\s+(?:kannst|darfst|sollst)\s+mich\s+\w+\s+nennen"
    r"|sie\s+(?:koennen|können|duerfen|dürfen|sollen)\s+mich\s+\w+\s+nennen"  # i18n-allow: German input-matching data (self-identification classifier)
    r"|meine\s+anrede\s+(?:ist|lautet)\s+\w+"  # i18n-allow: same German input-matching data
    r"|meine\s+pronomen\s+(?:ist|sind|lauten)\s+\w+"  # i18n-allow: same German input-matching data
    r"|my\s+name(?:\s+is|'s)\s+\w+"
    r"|call\s+me\s+\w+"
    r"|you\s+(?:can|may|should)\s+call\s+me\s+\w+"
    r"|i'?m\s+called\s+\w+"
    r"|i\s+am\s+called\s+\w+"
    r")",
    re.IGNORECASE,
)

_SIDE_EFFECT_TOOL_NAMES = {
    "click",
    # The LLM-visible computer-use tool was missing here while its internal
    # sibling ``dispatch_to_harness`` was listed, so the how-to-question guard
    # covered the deterministic path and left the model's own CU call open
    # (found while fixing the 2026-08-25 misroute of a vocabulary question onto
    # the screenshot harness). Both doors to the desktop are guarded now.
    "computer_use",
    "dispatch_to_harness",
    "dispatch_with_review",
    "hotkey",
    "move_mouse",
    "multi_spawn",
    "open_app",
    "remember",
    "run_shell",
    "spawn_worker",
    "type_text",
}


# Possessive markers (DE/EN/ES). "Analysier MEINE Cloud-Kosten" asks about the
# user's OWN resources — the one thing action tools exist for — and is never
# literature research. Restricted to true possessives on purpose: "mir"/"ich"
# would swallow the guard's own baseline case ("Vergleiche MIR mal, was ICH bei
# Google Cloud verbraucht habe"), and "mein\w*" would match the verb "meinst".
_POSSESSIVE_OWN_DATA_RE = re.compile(
    r"\b("
    r"mein(?:e|es|er|em|en)?|unser(?:e|es|er|em|en)?|"  # i18n-allow: input data
    r"my|mine|our|ours|"
    r"mi|mis|nuestr[oa]s?"  # i18n-allow: input-matching data
    r")\b",
    re.IGNORECASE,
)


def _is_own_data_request(utterance: str) -> bool:
    """True when the utterance claims the data as the user's own."""
    return bool(_POSSESSIVE_OWN_DATA_RE.search(utterance or ""))


def _is_research_intent(utterance: str, intent_level: str | None = None) -> bool:
    """Heuristic: does the utterance text indicate a pure research intent?

    Primarily via regex on research verbs. ``intent_level`` from the router can
    be passed as an additional signal (currently only logged — the regex alone
    is precise enough, because intent-level 'deep' also occurs in coding/
    reasoning and is not a reliable research signal on its own).
    """
    if intent_level:
        log.debug("research-check: intent_level=%s utterance=%r", intent_level, utterance[:80])
    return bool(_RESEARCH_KEYWORDS.search(utterance or ""))


def _is_meta_debug_intent(utterance: str) -> bool:
    """User is talking about Jarvis/provider behaviour, not about a task.

    A strong marker decides on its own; an everyday word only counts when the
    turn also points at the assistant. Without that second condition "Zeig mir
    den Fehler im Log und starte den Dienst neu" read as a complaint  # i18n-allow
    about the assistant, and the turn ended on the canned acknowledgement
    instead of doing the work.
    """
    text = utterance or ""
    if _META_DEBUG_STRONG_RE.search(text):
        return True
    return bool(
        _META_DEBUG_WEAK_RE.search(text)
        and _ASSISTANT_SELF_REFERENCE_RE.search(text)
    )


# Spoken fallback phrases, localized. Live bug 2026-06-10 23:13
# (data/jarvis_desktop.log): the anti-silence fallback was a hardcoded German
# string, so the English turn "Hey, what's the weather like today?" was
# answered in German. A pinned reply language (brain.reply_language) wins;
# in "auto" mode the phrase mirrors the language detected from the user's
# text; ambiguous text keeps the historical German default.
_ANTI_SILENCE_PHRASES: dict[str, str] = i18n_catalog.table("tool_loop.anti_silence")

# Meta-/debug feedback acknowledgement. Must NOT narrate background bookkeeping
# (the maintainer finds "ich notiere das Feedback" / "I'm noting that" / "tomo
# nota" annoying — that work happens silently, BACKGROUND_ACTION_RE strips it
# anyway). A brief, neutral acknowledgement that invites the actual correction.
_META_DEBUG_ACK_PHRASES: dict[str, str] = i18n_catalog.table("tool_loop.meta_debug_ack")


def _localized_phrase(
    phrases: dict[str, str],
    user_utterance: str,
    reply_language: str,
    conversation_language: str = "",
) -> str:
    """Pick the phrase variant matching the pin or the user's turn language.

    A pinned ``reply_language`` (de/en/es/pt) wins outright. In ``auto`` mode the
    language is detected from the utterance TEXT — the tool-use loop never
    receives the STT language tag (the pipeline resolves the turn language from
    that tag separately, and the loop is only handed ``user_utterance``), so we
    pass ``"unknown"`` as the tag and let the text decide. Ambiguous text keeps
    the historical German default. (Under the common ``[stt].language="de"`` pin
    the tag would resolve to ``de`` anyway, so the text-only path is equivalent
    there and strictly better when the text is clearly English/Spanish.) The
    running ``conversation_language`` keeps a short or ambiguous turn in the
    conversation's language; anything without translations reads English.
    """
    turn = TURN_LANGUAGE.get()
    if turn and str(reply_language or "").strip().lower() not in phrases:
        # Inside a brain turn: the language generate() resolved for it, so an
        # internal English prompt as the utterance never makes this English.
        return i18n_catalog.pick(phrases, turn)
    lang = resolve_output_language(
        reply_language, "unknown", user_utterance, conversation_language=conversation_language
    )
    return i18n_catalog.pick(phrases, lang)


def _anti_silence_phrase(
    user_utterance: str, reply_language: str = "auto", conversation_language: str = ""
) -> str:
    return _localized_phrase(
        _ANTI_SILENCE_PHRASES, user_utterance, reply_language, conversation_language
    )


def _meta_debug_ack_phrase(
    user_utterance: str, reply_language: str = "auto", conversation_language: str = ""
) -> str:
    return _localized_phrase(
        _META_DEBUG_ACK_PHRASES, user_utterance, reply_language, conversation_language
    )


def _has_indicative_subject_before(text: str, end: int) -> bool:
    """Does ``text[:end]`` end in a subject or infinitive marker plus whitespace?

    Same answer as ``_INDICATIVE_SUBJECT_BEFORE_RE.search(text[:end])``, but it
    only looks at the end of the prefix. Searching the whole prefix once per
    verb match made a long run of "to mach to mach ..." quadratic.
    """
    cut = end
    while cut > 0 and text[cut - 1].isspace():
        cut -= 1
    if cut == end:
        return False
    # The longest subject word has four letters; one more character lets the
    # leading word boundary see what precedes it.
    return _INDICATIVE_SUBJECT_BEFORE_RE.search(text[max(0, cut - 5):end]) is not None


def _has_trailing_imperative(utterance: str) -> bool:
    """True when a command follows the question inside the SAME turn.

    Only the part after the FIRST clause break is searched. In "How do I open
    Spotify?" the verb belongs to the question itself and must not defuse the
    guard. In "Warum ist Spotify nicht offen, mach es auf" the order  # i18n-allow
    sits behind the comma, and it is what the user actually wants done.
    """
    parts = _CLAUSE_BREAK_RE.split(utterance or "", maxsplit=1)
    if len(parts) < 2:
        return False
    tail = parts[1]
    for match in _IMPERATIVE_VERB_RE.finditer(tail):
        if _INDICATIVE_SUBJECT_RE.match(tail, match.end()):
            continue
        if _has_indicative_subject_before(tail, match.start()):
            continue
        return True
    return False


def _is_instructional_question(utterance: str) -> bool:
    """User is asking for an explanation or how-to, not for execution.

    The question opener alone is not enough. "Warum ist Spotify nicht  # i18n-allow
    offen, mach es auf" opens with a question word and still ends in an  # i18n-allow
    order; blocking every side-effect tool on the opener meant that order
    could never run — the user said something and nothing happened. The
    guard therefore stands down as soon as a command follows the question
    in the same turn. A pure how-to carries no such command and stays
    blocked ("Wie kann ich bei Windows reinzoomen?").  # i18n-allow
    """
    text = utterance or ""
    if not _INSTRUCTIONAL_QUESTION_RE.search(text):
        return False
    return not _has_trailing_imperative(text)


def _is_self_identification(utterance: str) -> bool:
    """User is introducing themselves (name, salutation, pronouns) — NOT an action request.

    Such utterances are picked up by the Curator background job and
    persisted in USER.md; a manual tool-call (run_shell, dispatch_*,
    spawn_sub_jarvis, ...) is always a wrong choice by the LLM here.
    """
    return bool(_SELF_IDENTIFICATION_RE.search(utterance or ""))


def _is_action_tool(tool: Any) -> bool:
    """True if the tool operates on a connected system (CLI or MCP).

    Recognises two patterns:
    - Name prefix ``cli_`` (CliTool instances)
    - Flag ``is_action_tool=True`` (set by MCPToolAdapter)
    Used by the sanity guard to block research intents against action tools —
    regardless of whether it is a CLI or MCP server.
    """
    name = getattr(tool, "name", "")
    if isinstance(name, str) and name.startswith("cli_"):
        return True
    return bool(getattr(tool, "is_action_tool", False))


# Handing work to one of the user's own agents is never a query against a
# connected system: a research agent asked to research is the intended route,
# so the research guard below must not turn the hand-off into a denial.
_AGENT_HANDOFF_TOOLS = frozenset({"delegate_to_agent", "message_agent", "ask_agent"})


def _should_block_action_as_research(
    tool: Any,
    tool_name: str,
    user_utterance: str,
    intent_level: str | None,
    evidence_required_tool: str = "",
) -> bool:
    """Research-intent sanity guard: block an action tool (CLI/MCP) when the
    utterance is research-shaped — UNLESS the evidence gate already mandated
    THIS exact tool for the turn.

    The evidence mandate is the *more specific* rule (it named a concrete tool
    for a concrete data lookup, e.g. ``cli_gcloud`` for "...meine Google-Cloud-
    Kosten..."), so it wins over the *generic* research keyword guard. Without
    this exception the two deterministic rules collide — the evidence gate
    forces the tool while this guard forbids it — and the only reachable
    outcome is the unverified-answer fallback (trace 5edf0245). The override is
    scoped to the mandated tool only, so other action tools stay blocked under
    a research intent.

    A possessive is the second stand-down. The guard's premise is that the user
    wants information *about* a topic, not a query against their own system —
    "Analysier meine Cloud-Kosten" is the exact opposite, and blocking every
    cli_*/MCP tool there left the request unanswerable unless the evidence gate
    happened to mandate that one tool. A request that names the data as the
    user's own is an action on their own resources, not literature research.
    """
    if tool is None or not _is_action_tool(tool):
        return False
    if tool_name in _AGENT_HANDOFF_TOOLS:
        return False
    if tool_name and tool_name == evidence_required_tool:
        return False
    if _is_own_data_request(user_utterance):
        return False
    return _is_research_intent(user_utterance, intent_level)


def _is_side_effect_tool(tool: Any) -> bool:
    """True for tools that execute or mutate something locally or externally."""
    name = getattr(tool, "name", "")
    if isinstance(name, str):
        normalized = name.replace("-", "_")
        if normalized in _SIDE_EFFECT_TOOL_NAMES:
            return True
        if normalized.startswith("cli_"):
            return True
    return _is_action_tool(tool)


# STT hallucination markers: typical YouTube end-cards, ad outros,
# copyright strings that Whisper sometimes recognises as an utterance. If these
# end up in a tool argument, the brain has interpreted a hallucination as a
# command — do NOT execute the tool call.
_ARG_HALLUCINATION_RE = re.compile(
    r"\b("
    r"im\s+auftrag\s+des|mediagroup|"
    r"untertitel\s+(von|der|im\s+auftrag)|"  # i18n-allow: German STT-hallucination matching data
    r"abonnier(e|t|en)?\s+(den|meinen)\s+kanal|"
    r"thanks\s+for\s+watching|please\s+subscribe|"
    r"copyright\s+\d{4}|all\s+rights\s+reserved"
    r")\b",
    re.IGNORECASE,
)

# Per-tool maximum arg length. Blocks hallucination args in fields that are
# expected to be short. ``type_text`` and ``run_shell`` are intentionally
# uncapped — legitimately long text/commands can appear there.
_ARG_MAXLEN: dict[str, tuple[str, int]] = {
    "open_app":    ("app_name", 80),
    "open-app":    ("app_name", 80),
    "search_web":  ("query", 200),
    "search-web":  ("query", 200),
}


def _canonical_tool_name(name: str) -> str:
    """Separator- and case-insensitive canonical form of a tool name.

    The registered tool surface mixes naming conventions (``wiki-recall`` vs
    ``run_shell``), so models cross-normalize and invent the OTHER spelling of a
    real tool (live incident 2026-07-05: gemini called ``run-shell``). Dots are
    folded too: the system prompt advertises CapabilityRegistry ids like
    ``cli.gcloud`` whose registered tool is ``cli_gcloud``. All spellings
    collapse to one canonical key so an unambiguous variant still resolves to
    the registered tool instead of the missing-tool refusal.
    """
    return (name or "").strip().lower().replace("-", "_").replace(".", "_")


def _is_stt_hallucinated(tool_name: str, args: Any) -> tuple[bool, str]:
    """Checks whether the tool args look like an STT hallucination.

    Returns ``(blocked, reason)``. ``blocked=True`` means the tool call
    should NOT be executed; ``reason`` is fed back to the LLM as an error
    so it switches to asking the user for clarification.
    """
    if not isinstance(args, dict):
        return False, ""

    # Per-tool max-length check on the primary field
    field_spec = _ARG_MAXLEN.get(tool_name)
    if field_spec:
        fname, maxlen = field_spec
        val = str(args.get(fname, ""))
        if len(val) > maxlen:
            return True, f"Arg '{fname}' ist {len(val)} chars (erlaubt: {maxlen})"

    # Generic ad/outro marker check across all string args
    for k, v in args.items():
        if isinstance(v, str) and _ARG_HALLUCINATION_RE.search(v):
            return True, f"Arg '{k}' enthaelt Werbe-/Outro-Marker"

    return False, ""


class ToolUseLoop:
    """Loop until no more tool calls are pending or the budget is exhausted."""

    def __init__(
        self,
        brain: Brain,
        tools: dict[str, Tool],
        executor: ToolExecutor,
        *,
        system_prompt: str | None = None,
        budget: IterationBudget | None = None,
        max_tokens: int = 32_768,
        deadline_s: float | None = None,
        reasoning_effort: ReasoningEffort | None = None,
        tool_context: dict[str, Any] | None = None,
        loop_control: LoopControl | None = None,
        deferred_tools: Iterable[str] = (),
    ) -> None:
        self._brain = brain
        self._tools = tools
        self._executor = executor
        # Tools of this turn whose schemas are NOT sent (dodaios/brain/
        # tool_shortlist.py). They stay in ``tools`` and run when called; the
        # ``find_tools`` tool reveals the ones the model asked about, and the
        # next round then carries their schemas.
        self._hidden: set[str] = {name for name in deferred_tools if name in tools}
        self._surface_changed = False
        finder = tools.get(FIND_TOOLS_NAME) if self._hidden else None
        bind = getattr(finder, "bind", None)
        if callable(bind):
            bind(self._reveal_tools)
        # Caller-supplied keys for every tool's ``ExecutionContext.config``
        # (see BrainDispatcher.tool_context). Per-turn keys set below win.
        self._tool_context = dict(tool_context or {})
        # A scheduled/background turn (BUG-212): an unknown tool name is fed
        # back and the loop continues — no listener to keep from silence.
        self._unattended = bool(self._tool_context.get("unattended"))
        # Canonical form → registered name, for hyphen/underscore-tolerant
        # lookup. A canonical collision (two registered tools differing only in
        # separator/case) maps to None: an inexact name must never guess
        # between twins — only the exact spelling reaches either of them.
        self._alias_map: dict[str, str | None] = {}
        for registered in tools:
            canon = _canonical_tool_name(registered)
            self._alias_map[canon] = (
                None if canon in self._alias_map else registered
            )
        self._system_prompt = system_prompt
        self._budget = budget or IterationBudget()
        # Per-response output ceiling forwarded onto every BrainRequest this
        # loop issues. Safety ceiling, not a target (see BrainConfig.max_tokens).
        self._max_tokens = max_tokens
        # Wall-clock bound for the WHOLE loop (voice turns; live incident
        # 2026-07-14: 14 rounds / 66 s). The iteration budget counts rounds,
        # not seconds — one slow provider round can eat a minute on its own.
        # When exceeded after a tool round, the loop runs exactly ONE final
        # round WITHOUT tools plus an answer-now directive, so the user
        # always hears a grounded answer instead of more tool churn.
        # ``None`` (default) = unbounded, previous behavior.
        self._deadline_s = deadline_s
        # Forwarded onto every per-round BrainRequest. Delegated realtime
        # voice turns pass "none": a thinking-by-default model (Gemini Flash)
        # otherwise spends seconds of internal reasoning on EVERY round of a
        # multi-round tool loop — live 2026-07-17: 3-6 rounds over a ~53k-token
        # context ran the 20 s deadline out on plain questions. Same rationale
        # as the router-tier thinking cap and the Computer-Use calls
        # (dodaios/cu/brain_call.py); providers without a reasoning knob ignore
        # the hint (capability hint, never a provider pin — AP-21).
        self._reasoning_effort = reasoning_effort
        # Steering, phases and verification (dodaios/brain/loop_control.py).
        # ``None`` on every path but the chat: those turns are unchanged.
        self._control = loop_control
        self._last_phase: tuple[str, str] | None = None

    def _resolve_tool(self, requested: str) -> tuple[Tool | None, str]:
        """Look up a model-requested tool name, tolerating separator/case drift.

        Exact match wins. Otherwise the canonical (hyphen/underscore/case-
        insensitive) form resolves — but only when it maps to exactly ONE
        registered tool. Returns ``(tool, registered_name)``; unknown names
        return ``(None, requested)`` so the anti-silence fallback still fires.
        """
        tool = self._tools.get(requested)
        if tool is not None or not requested:
            return tool, requested
        alias = self._alias_map.get(_canonical_tool_name(requested))
        if alias is None:
            # Capability ids are NOT tool names, but the system prompt renders
            # them verbatim (``skill.paired.<plugin>`` from the paired-skill
            # coupling) and a model occasionally calls one as a tool (live
            # 2026-07-18 18:15: 'skill.paired.google_calendar' hit the
            # anti-silence fallback although the real ``google_calendar`` tool
            # was registered). A paired capability id's tail IS the native
            # tool / plugin id, so strip the namespace and resolve the rest.
            try:
                from dodaios.skills.plugin_coupling import PAIRED_CAP_PREFIX
            except Exception:  # noqa: BLE001 — resolution aid must never break the loop
                PAIRED_CAP_PREFIX = "skill.paired."
            if requested.startswith(PAIRED_CAP_PREFIX):
                stripped = requested[len(PAIRED_CAP_PREFIX):]
                tool = self._tools.get(stripped)
                if tool is None:
                    inner = self._alias_map.get(_canonical_tool_name(stripped))
                    if inner is not None:
                        tool = self._tools.get(inner)
                        stripped = inner if tool is not None else stripped
                if tool is not None:
                    log.info(
                        "tool_use_loop: model called capability id %r — "
                        "resolved to registered tool %r", requested, stripped,
                    )
                    return tool, stripped
            return None, requested
        tool = self._tools.get(alias)
        if tool is None:
            return None, requested
        log.info(
            "tool_use_loop: model called tool %r — resolved to registered "
            "tool %r via separator-insensitive alias", requested, alias,
        )
        return tool, alias

    def _reroute_music_tool(
        self,
        tool: Tool | None,
        tool_name: str,
        tool_args: Any,
        user_utterance: str,
    ) -> tuple[Tool | None, str, Any]:
        """Send an unnamed music call to the preferred/only connected service.

        Same resolver the skill capture uses. A named service still wins.
        Never raises — a fault keeps the model's pick.
        """
        try:
            from dodaios.core.music_constants import MUSIC_PLUGIN_IDS
            from dodaios.core.music_service import (
                adapt_music_arguments,
                reroute_music_tool,
            )
        except Exception:  # noqa: BLE001 — a routing nicety must never break a turn
            return tool, tool_name, tool_args
        if tool_name not in MUSIC_PLUGIN_IDS:
            return tool, tool_name, tool_args
        try:
            target = reroute_music_tool(tool_name, user_utterance)
        except Exception as exc:  # noqa: BLE001
            log.debug("tool_use_loop: music tool reroute skipped: %s", exc)
            return tool, tool_name, tool_args
        if target == tool_name:
            return tool, tool_name, tool_args
        new_tool, new_name = self._resolve_tool(target)
        if new_tool is None:
            return tool, tool_name, tool_args
        log.info(
            "tool_use_loop: music tool rerouted %s -> %s",
            tool_name,
            new_name,
        )
        args = tool_args if isinstance(tool_args, dict) else {}
        try:
            adapted = adapt_music_arguments(
                user_utterance, source=tool_name, target=new_name, args=args
            )
        except Exception as exc:  # noqa: BLE001
            log.debug("tool_use_loop: music arg adapt skipped: %s", exc)
            adapted = args
        return new_tool, new_name, adapted

    async def _publish_guard_denied(
        self, tool_name: str, reason: str, tid: UUID,
    ) -> None:
        """Make a guard-blocked / unknown-name tool call visible on the bus.

        The guard branches in ``run`` never reach ``ToolExecutor.execute``, so
        no ActionProposed/ActionExecuted fires — the session timeline showed NO
        trace of why a turn refused (2026-07-06 audit). Defensive: test fakes
        and older executors may not have the publisher; skip silently then.
        """
        publisher = getattr(self._executor, "publish_guard_denied", None)
        if publisher is None:
            return
        try:
            await publisher(tool_name, reason, trace_id=tid)
        except Exception:  # noqa: BLE001 — observability must never break the loop
            log.debug("guard-denied publish failed", exc_info=True)

    def _tool_schemas(self) -> list[dict[str, Any]]:
        """Schemas in Anthropic-compatible format (providers normalise)."""
        return [
            {
                "name": tool.name,
                "description": getattr(tool, "description", ""),
                "input_schema": tool.schema,
            }
            for name, tool in self._tools.items()
            if name not in self._hidden
        ]

    def _reveal_tools(self, names: Iterable[str]) -> None:
        """Show the schemas of deferred tools from the next round on."""
        found = {name for name in names if name in self._hidden}
        if found:
            self._hidden -= found
            self._surface_changed = True

    async def _phase(self, phase: str, detail: str = "") -> None:
        """Report what the turn is doing — once per change, never per token."""
        control = self._control
        if control is None or control.on_phase is None:
            return
        if self._last_phase == (phase, detail):
            return
        self._last_phase = (phase, detail)
        try:
            await control.on_phase(phase, detail)
        except asyncio.CancelledError:
            raise
        except Exception:  # noqa: BLE001 — a phase listener never breaks the turn
            log.debug("on_phase callback raised (ignored)", exc_info=True)

    def _drain_steer(self) -> list[str]:
        """What the person typed while this turn was running."""
        control = self._control
        if control is None or control.drain_steer is None:
            return []
        try:
            return [str(t).strip() for t in control.drain_steer() if str(t).strip()]
        except Exception:  # noqa: BLE001 — a broken inbox costs the steer, not the turn
            log.warning("drain_steer raised (ignored)", exc_info=True)
            return []

    @staticmethod
    def _append_steer(messages: list[BrainMessage], texts: list[str]) -> None:
        for text in texts:
            messages.append(BrainMessage(role="user", content=_STEER_PREFIX + text))

    async def _ask_once(self, system: str, user: str) -> str:
        """One tool-less question on THIS turn's brain — how a verifier runs
        without a provider, a key or a model id of its own (AP-6/AP-21)."""
        req = BrainRequest(
            messages=(BrainMessage(role="user", content=user),),
            tools=(),
            system=system,
            max_tokens=2_000,
            stream=True,
        )
        agg = await aggregate(self._brain.complete(req))
        return agg.text

    async def _run_verify(
        self,
        user_utterance: str,
        answer: str,
        tool_log: tuple[ToolRecord, ...],
        *,
        attempt: int,
        blocked: bool,
    ) -> VerifyOutcome | None:
        """The check that runs where the loop would otherwise finish.

        ``None`` means no verification happened: no hook, a forced final round
        (the turn is already out of budget or time), or the revision cap is
        reached. A verifier that raises is logged and the turn is accepted —
        a broken check never costs the person their answer.
        """
        control = self._control
        if control is None or control.verify is None or blocked:
            return None
        if attempt >= max(0, control.max_verify):
            return None
        await self._phase(PHASE_VERIFY, "checking the answer")
        try:
            return await control.verify(
                VerifyRequest(
                    user_text=user_utterance,
                    answer=answer,
                    tool_log=tool_log,
                    attempt=attempt,
                ),
                self._ask_once,
            )
        except asyncio.CancelledError:
            raise
        except Exception:  # noqa: BLE001 — fail open: an unchecked answer beats none
            log.warning("verify hook raised — accepting the turn", exc_info=True)
            return None

    async def run(
        self,
        messages: list[BrainMessage],
        *,
        trace_id: UUID | None = None,
        user_utterance: str = "",
        intent_level: str | None = None,
        evidence_required_tool: str = "",
        text_consumer: Callable[[str], None] | None = None,
        ack_emitter: Callable[[str, dict[str, Any]], Awaitable[None]] | None = None,
        on_progress: Callable[[], None] | None = None,
        reply_language: str = "auto",
        conversation_language: str = "",
        voice_confirm: bool = False,
    ) -> StreamingAggregate:
        """Executes the complete loop and returns the final aggregate.

        ``intent_level`` comes from the router (``fast``/``deep``/``code``) and is
        currently forwarded to the research heuristic; in the future it can be used
        for further tier-aware logic (e.g. tool-visibility filtering).

        ``text_consumer`` (latency-sprint-1): called synchronously per brain text chunk —
        enables sentence streaming in the speech pipeline. When ``None`` (default),
        the loop behaves identically to the previous implementation.
        Pre-tool-use texts are also delivered; the persona prompt prohibits
        filler openers anyway, so this is non-critical.

        ``on_progress`` (stall-timeout signal, live bug 2026-06-01): called
        synchronously at every "the brain is actively working" boundary — once
        per completed model round and once per executed tool. A vision/tool turn
        streams little or no text, so the speech pipeline cannot tell "still
        working" from "stalled" by watching text chunks alone; these pings let
        its *no-progress* deadline reset across the long silent gaps (model
        thinking + tool execution) instead of guillotining a working turn at a
        hard wall-clock cap. ``None`` (default) is a no-op. Callback exceptions
        are swallowed so a buggy consumer can never break tool execution.

        ``ack_emitter`` (perceived-latency pattern): if provided, awaited
        exactly once on the first iteration that has tool calls scheduled,
        with the first tool's name + input. The caller decides whether to
        publish an ``AnnouncementRequested`` (skip-list / template selection
        live in the caller). Subsequent iterations of the same turn never
        re-emit — multi-step tool plans get a single ack at the start, not
        chatter at every step. Emitter exceptions are logged but do not
        block tool execution.

        ``reply_language`` (live bug 2026-06-10): the ``brain.reply_language``
        pin (``auto``/``de``/``en``/``es``/``pt``) — selects the language of the
        spoken fallback phrases; ``auto`` mirrors the user's utterance.
        """
        tid = trace_id or uuid4()
        current_messages = list(messages)
        tools_payload = self._tool_schemas()
        final_agg = StreamingAggregate()
        ack_attempted = False
        loop_started = time.monotonic()
        deadline_forced = False
        seen_call_ids: set[str] = set()
        tool_log: list[ToolRecord] = []
        verify_rounds = 0
        round_no = 0

        def _progress() -> None:
            # Stall-timeout heartbeat (see ``on_progress`` in the docstring).
            # Swallow everything: a progress consumer must never break the loop.
            if on_progress is not None:
                try:
                    on_progress()
                except Exception:  # noqa: BLE001
                    log.debug("on_progress callback raised (ignored)", exc_info=True)

        def _delta_progress(_delta: object) -> None:
            _progress()

        while True:
            # A message the person sent while this turn was running joins the
            # NEXT round as their own words. It must not touch tools_payload or
            # deadline_forced: steering continues the job, it does not end it.
            pending = self._drain_steer()
            if pending:
                self._append_steer(current_messages, pending)
                log.info("tool_use_loop: %d steer message(s) folded in", len(pending))
            round_no += 1
            await self._phase(PHASE_GATHER, f"round {round_no}")
            if self._surface_changed:
                self._surface_changed = False
                # Only while tools are still on offer: a round that was forced
                # tool-less (deadline, final answer) must stay that way.
                if tools_payload:
                    tools_payload = self._tool_schemas()

            req = BrainRequest(
                messages=tuple(current_messages),
                tools=tuple(tools_payload),
                system=self._system_prompt,
                max_tokens=self._max_tokens,
                stream=True,
                reasoning_effort=self._reasoning_effort,
            )
            stream = self._brain.complete(req)
            if text_consumer is not None:
                agg = await aggregate_with_consumer(
                    stream,
                    text_consumer,
                    delta_consumer=_delta_progress,
                )
            else:
                agg = await aggregate(stream)
            # A model round finished — the brain is alive and working. Reset the
            # pipeline's no-progress deadline before the (possibly long) tool
            # execution + next round so a slow-but-working turn is not cut off.
            _progress()

            # Some providers occasionally serialize a function call into the
            # response text instead of emitting a structured tool-call delta.
            # Rehydrate only explicit call envelopes, then continue through the
            # normal executor, risk, confirmation, telemetry, and synthesis
            # path. This is shared by native, plugin, skill, and MCP tools.
            if not deadline_forced and tools_payload:
                # The offered schemas let chat-template markup (Qwen
                # ``<tool_call>``, Mistral ``[TOOL_CALLS]``) be recovered for
                # the tools that really exist this round.
                recovered_calls = extract_leaked_tool_calls(agg.text, tools_payload)
                if recovered_calls:
                    structured_signatures = {
                        _tool_call_signature(call) for call in agg.tool_calls
                    }
                    recovered_calls = [
                        call
                        for call in recovered_calls
                        if _tool_call_signature(call) not in structured_signatures
                    ]
                    log.warning(
                        "tool_use_loop: recovered %d text-serialized tool call(s): %s",
                        len(recovered_calls),
                        ", ".join(call["name"] for call in recovered_calls),
                    )
                    agg.tool_calls.extend(recovered_calls)
                    agg.text = ""
                    if agg.tool_calls:
                        agg.finish_reason = "tool_use"

            duplicate_only_round = False
            if agg.tool_calls:
                had_tool_calls = True
                unique_calls: list[dict[str, Any]] = []
                for call in agg.tool_calls:
                    call_id = str(call.get("id") or "")
                    if call_id and call_id in seen_call_ids:
                        log.warning(
                            "tool_use_loop: skipped duplicate tool-call id %s",
                            call_id,
                        )
                        continue
                    if call_id:
                        seen_call_ids.add(call_id)
                    unique_calls.append(call)
                agg.tool_calls = unique_calls
                duplicate_only_round = had_tool_calls and not unique_calls

            # Accumulate final text
            if agg.text:
                final_agg.text += agg.text
            final_agg.finish_reason = agg.finish_reason
            for k, v in agg.usage.items():
                final_agg.usage[k] = final_agg.usage.get(k, 0) + int(v)

            # Budget tracking
            self._budget.record_turn(
                tokens_in=agg.usage.get("input_tokens", 0),
                tokens_out=agg.usage.get("output_tokens", 0),
            )

            # A repeated call was already executed in an earlier model round.
            # Suppressing it is correct, but treating the now-empty call list
            # as a completed answer would return silence. Give the provider one
            # final tool-less round over the existing result instead.
            if duplicate_only_round and not deadline_forced:
                log.warning(
                    "tool_use_loop: duplicate-only round; forcing final "
                    "tool-less synthesis"
                )
                deadline_forced = True
                tools_payload = []
                current_messages.append(
                    BrainMessage(role="user", content=_DUPLICATE_CALL_FINAL_DIRECTIVE)
                )
                continue

            # No tool calls → the answer is written. Before it stands: did
            # the person say something else while we worked, and does the
            # answer hold against what actually ran?
            if not agg.tool_calls:
                late = self._drain_steer()
                if late:
                    self._append_steer(current_messages, late)
                    continue
                outcome = await self._run_verify(
                    user_utterance or _last_user_text(current_messages),
                    final_agg.text,
                    tuple(tool_log),
                    attempt=verify_rounds,
                    blocked=deadline_forced,
                )
                if outcome is not None and not outcome.accepted and outcome.instruction:
                    verify_rounds += 1
                    log.info(
                        "tool_use_loop: verification asked for a revision (%d/%d)",
                        verify_rounds,
                        self._control.max_verify if self._control else 0,
                    )
                    current_messages.append(
                        BrainMessage(role="assistant", content=agg.text)
                    )
                    current_messages.append(
                        BrainMessage(
                            role="user", content=_VERIFY_DIRECTIVE + outcome.instruction
                        )
                    )
                    # The revision IS the answer: the draft was already closed
                    # into its own block by the verify phase hook.
                    final_agg.text = ""
                    continue
                break

            # The deadline-forced round is the LAST round, period. With
            # ``tools_payload = []`` a well-behaved provider cannot emit tool
            # calls anymore; if one hallucinates a call anyway, stop here
            # rather than looping on a dead deadline.
            if deadline_forced:
                log.warning(
                    "tool_use_loop: provider emitted a tool call in the "
                    "deadline-forced tool-less round — ending the turn"
                )
                break

            # Budget exhausted before executing this round's calls → skip them
            # and force ONE final tool-less answer round over the evidence
            # already gathered (see _BUDGET_FINAL_DIRECTIVE). The unexecuted
            # calls are deliberately NOT appended to the history, so the
            # provider never waits for tool results that will not come.
            if self._budget.exceeded():
                log.warning(
                    "IterationBudget exhausted: %s — forcing a final "
                    "tool-less answer round",
                    self._budget.snapshot(),
                )
                final_agg.finish_reason = "budget_exceeded"
                deadline_forced = True
                tools_payload = []
                current_messages.append(
                    BrainMessage(role="user", content=_BUDGET_FINAL_DIRECTIVE)
                )
                continue

            # Pre-execution acknowledgment (perceived-latency pattern). Fires
            # exactly once per turn, on the first iteration that has tool
            # calls. Done after both early-exit checks so we never ack for a
            # tool that won't actually run. The emitter is responsible for
            # skip-list filtering and template selection.
            if ack_emitter is not None and not ack_attempted:
                ack_attempted = True
                first_call = agg.tool_calls[0]
                first_name = first_call.get("name", "") or ""
                # Normalize to the registered name so the caller's skip-list /
                # template selection (keyed on registered names) still matches
                # when the model used the other separator spelling.
                _, first_name = self._resolve_tool(first_name)
                first_input = first_call.get("input", {}) or {}
                if not isinstance(first_input, dict):
                    first_input = {}
                _, first_name, first_input = self._reroute_music_tool(
                    None, first_name, first_input, user_utterance
                )
                try:
                    await ack_emitter(first_name, first_input)
                except Exception as exc:  # noqa: BLE001 — emitter must never block tool execution
                    log.warning("ack_emitter failed: %s", exc)

            await self._phase(
                PHASE_ACT,
                ", ".join(str(tc.get("name") or "") for tc in agg.tool_calls[:3]),
            )

            # Add assistant turn with tool-calls to the message history
            # (for providers that expect role=assistant with tool_calls)
            assistant_content: list[dict[str, Any]] = []
            if agg.text:
                assistant_content.append({"type": "text", "text": agg.text})
            for tc in agg.tool_calls:
                tool_use_part: dict[str, Any] = {
                    "type": "tool_use",
                    "id": tc.get("id", f"call_{uuid4().hex[:8]}"),
                    "name": tc.get("name", ""),
                    "input": tc.get("input", {}),
                }
                # Gemini 3 thinking models require their functionCall
                # thought_signature back VERBATIM when the call is replayed
                # in history (400 INVALID_ARGUMENT otherwise). Providers that
                # never emit the key are unaffected.
                if tc.get("thought_signature"):
                    tool_use_part["thought_signature"] = tc["thought_signature"]
                assistant_content.append(tool_use_part)
            current_messages.append(BrainMessage(
                role="assistant",
                content=assistant_content if assistant_content else agg.text,
            ))

            # Execute tools
            suppress_output: str | None = None
            # Held back until the whole round is done: a canned line may only
            # end the turn when nothing else in it produced a result.
            meta_debug_ack: str | None = None
            unknown_tool_requested = False
            for tc in agg.tool_calls:
                tool_name = tc.get("name", "")
                tool_args = tc.get("input", {})
                call_id = tc.get("id", "")
                final_agg.tool_calls.append(dict(tc))
                # Wave 2: reset per tool-call so a guard/refusal branch on a
                # later iteration cannot reuse a stale executor result when we
                # check for image artifacts below.
                result = None

                # Separator-tolerant resolution: from here on ``tool_name`` is
                # the REGISTERED name (guards, telemetry, executed_tool_names
                # and the tool-result message all key on it); the raw model
                # spelling stays in ``final_agg.tool_calls`` above.
                tool, tool_name = self._resolve_tool(tool_name)
                tool, tool_name, tool_args = self._reroute_music_tool(
                    tool, tool_name, tool_args, user_utterance
                )
                stt_blocked, stt_reason = (
                    _is_stt_hallucinated(tool_name, tool_args)
                    if tool is not None else (False, "")
                )
                if (
                    tool is not None
                    and _is_instructional_question(user_utterance)
                    and _is_side_effect_tool(tool)
                ):
                    log.info(
                        "tool_use_loop: side-effect tool '%s' blocked for a how-to question",
                        tool_name,
                    )
                    await self._publish_guard_denied(
                        tool_name,
                        "guard: how-to question — side-effect tool not executed",
                        tid,
                    )
                    tool_result_payload = {
                        "success": False,
                        "output": None,
                        "error": (
                            "Tool not executed: the user is asking a how-to or "
                            "explanation question. Answer directly with the "
                            "appropriate short instructions. Do not run any "
                            "app, shell, harness, or computer-use action."
                        ),
                    }
                elif (
                    tool is not None
                    and _is_self_identification(user_utterance)
                    and _is_side_effect_tool(tool)
                ):
                    log.info(
                        "tool_use_loop: side-effect tool '%s' blocked for self-identification",
                        tool_name,
                    )
                    await self._publish_guard_denied(
                        tool_name,
                        "guard: self-identification turn — side-effect tool not executed",
                        tid,
                    )
                    tool_result_payload = {
                        "success": False,
                        "output": None,
                        "error": (
                            "Tool not executed: the user is introducing "
                            "themselves (name, salutation, or pronouns). Reply "
                            "with a short, friendly acknowledgement (1-2 "
                            "sentences max). The Curator extracts the facts "
                            "automatically in the background and persists them "
                            "to USER.md — you must NOT manually edit USER.md, "
                            "spawn a worker, or invoke a shell."
                        ),
                    }
                elif tool is None:
                    # AD-OE6 anti-silence: the model named a tool that is not in
                    # the router tool set (e.g. the prompt advertised a tool that
                    # was missing from ROUTER_TOOLS). Feed the error back AND set
                    # a spoken fallback so the turn never ends in silence — the
                    # historical "action command -> empty -> user hears nothing"
                    # failure (BUG-007/016/020/028 class). With the ROUTER_TOOLS
                    # fix this should be rare, but never silent again.
                    log.warning(
                        "tool_use_loop: tool '%s' not in the router tool set — "
                        "anti-silence fallback instead of an empty response", tool_name,
                    )
                    await self._publish_guard_denied(
                        tool_name,
                        "unknown tool name — not in this turn's tool set "
                        "(model-invented or gated off this turn)",
                        tid,
                    )
                    # Name what IS available: a scheduled turn whose system
                    # prompt advertises skills/CLIs it was not granted recovers
                    # from "run-skill is not here" only if it learns what is
                    # (BUG-212 — the briefing ended on the fallback phrase).
                    available = (
                        ", ".join(sorted(n for n in self._tools if n not in self._hidden))
                        or "none"
                    )
                    tool_result_payload = {
                        "error": (
                            f"Tool '{tool_name}' is not available in this turn. "
                            f"Available tools: {available}. Continue with those "
                            "and answer from what they return."
                        ),
                    }
                    unknown_tool_requested = True
                elif (
                    tool_name == "spawn_worker"
                    and _is_meta_debug_intent(user_utterance)
                    # A turn that names the vehicle out loud ("spawn an agent
                    # that finds out why the fallback fired") is a delegation
                    # request, not meta-conversation. The explicit-delegation
                    # gate below stays the authority on whether it may run;
                    # this guard only stops the model from delegating a
                    # conversation the user wanted answered. ``names_spawn_
                    # vehicle`` is the pure form of that test — calling
                    # ``llm_spawn_allowed`` here would consume the offer window
                    # a second time in the same turn.
                    and not names_spawn_vehicle(user_utterance)
                ):
                    log.info(
                        "tool_use_loop: spawn_worker blocked for a meta/debug utterance"
                    )
                    await self._publish_guard_denied(
                        tool_name,
                        "guard: meta/debug utterance — spawn_worker not executed",
                        tid,
                    )
                    # Asking the LLM to "answer directly and concretely" via a
                    # tool_result error message turned out to be unreliable —
                    # Gemini Flash regularly ignores the instruction, the
                    # outer loop never produces a text chunk, and Brain-Stream
                    # times out after 40s with nothing in `final_agg.text`.
                    # The user then hears silence ("listens, thinks, listens
                    # again, never speaks").
                    #
                    # The Meta-Debug verdict is already deterministic and
                    # high-precision (intent classifier matched the utterance
                    # against a curated keyword set). Short-circuit the loop
                    # with a neutral acknowledgement so the user always hears
                    # *something*, and let the LLM weigh in next turn instead
                    # of stalling this one.
                    #
                    # Only ever a LAST resort: parked here and applied after
                    # the round (see below), because it ends the turn — and it
                    # used to do so even when another call in the same round
                    # had already succeeded, throwing that work away.
                    meta_debug_ack = _meta_debug_ack_phrase(
                        user_utterance, reply_language, conversation_language
                    )
                    tool_result_payload = {
                        "success": False,
                        "blocked": True,
                        "output": None,
                        "error": (
                            "spawn_worker was not executed: the user is talking "
                            "about Dodaios/provider/transcript behavior. Answer "
                            "directly and concretely; no delegation, no "
                            "confirmation phrase."
                        ),
                    }
                elif (
                    tool_name in SPAWN_VEHICLE_TOOL_NAMES
                    and not llm_spawn_allowed(user_utterance)
                ):
                    # Explicit-delegation gate (maintainer mandate 2026-07-18):
                    # an LLM-chosen spawn runs ONLY when the user's own turn
                    # asks for an agent (or confirms an offer one turn later).
                    # Deterministic enforcement — the SPAWN-CRITERIA prompt and
                    # the tool description alone failed to stop conversational
                    # auto-spawns repeatedly. See dodaios/brain/spawn_gate.py.
                    log.info(
                        "tool_use_loop: %s blocked — no explicit delegation "
                        "request in the user turn", tool_name,
                    )
                    await self._publish_guard_denied(
                        tool_name,
                        "guard: no explicit delegation request — spawn not executed",
                        tid,
                    )
                    # ``blocked`` marks a POLICY decision, never a broken tool.
                    # Two readers, both real: the MODEL sees it in the tool
                    # result JSON below and can tell "not permitted" from
                    # "broken" (a broken tool is worth retrying, a gated one
                    # never is), and the realtime bridge sets the same flag so
                    # its voice layer skips the block when it composes the
                    # turn's spoken outcome. The error text itself is addressed
                    # to the model and must never be read out (live forensic
                    # 2026-08-20 13:41:24 — a block became the spoken result of
                    # the turn and buried the real reason from an earlier call).
                    tool_result_payload = {
                        "success": False,
                        "blocked": True,
                        "output": None,
                        "error": spawn_blocked_feedback(user_utterance),
                    }
                elif (
                    tool_name in CU_VEHICLE_TOOL_NAMES
                    and not llm_computer_use_allowed(user_utterance)
                ):
                    # Explicit-desktop gate (live incident 2026-07-21 11:36):
                    # a pure knowledge question delegated by realtime was
                    # answered by physically googling in the user's browser.
                    # An LLM-chosen computer_use runs ONLY when the user's own
                    # turn asks for an on-screen action (or the conversation is
                    # still inside a recent desktop episode). Deterministic —
                    # the tool description alone is advice, not enforcement
                    # (spawn-gate lesson). See dodaios/brain/cu_gate.py.
                    log.info(
                        "tool_use_loop: computer_use blocked — no explicit "
                        "desktop request in the user turn"
                    )
                    await self._publish_guard_denied(
                        tool_name,
                        "guard: no explicit desktop request — "
                        "computer_use not executed",
                        tid,
                    )
                    tool_result_payload = {
                        "success": False,
                        "blocked": True,
                        "output": None,
                        "error": CU_BLOCKED_MODEL_FEEDBACK,
                    }
                elif stt_blocked:
                    # Arg sanity guard: the tool args look like a Whisper
                    # hallucination (ad outro, copyright string, overly long app name).
                    # Do NOT execute the tool; the LLM gets a structured error
                    # and should ask the user again.
                    log.info(
                        "tool_use_loop: STT-hallucination guard blocked %s — %s",
                        tool_name, stt_reason,
                    )
                    await self._publish_guard_denied(
                        tool_name,
                        f"guard: STT-hallucination suspect args — {stt_reason}",
                        tid,
                    )
                    tool_result_payload = {
                        "success": False,
                        "blocked": True,
                        "output": None,
                        "error": (
                            f"Tool '{tool_name}' NOT executed: {stt_reason}. "
                            f"Likely an STT misheard word. Answer the user "
                            f"with a short follow-up question (max 1 sentence) "
                            f"instead of calling the tool again with the same value."
                        ),
                    }
                elif _should_block_action_as_research(
                    tool, tool_name, user_utterance, intent_level,
                    evidence_required_tool,
                ):
                    # Intent sanity guard: the user used a research keyword but
                    # the LLM still wants to fire an action tool (CLI or MCP)
                    # against the connected system. This is almost always a wrong
                    # choice (user wants info *about* Supabase, not to query their DB).
                    # Instead of executing → tool result with redirect hint;
                    # the LLM corrects itself in the next turn.
                    log.info(
                        "tool_use_loop: action tool '%s' blocked on research intent "
                        "(intent_level=%s) — LLM redirected to search_web",
                        tool_name, intent_level,
                    )
                    await self._publish_guard_denied(
                        tool_name,
                        "guard: research intent — action tool redirected to search_web",
                        tid,
                    )
                    tool_result_payload = {
                        "success": False,
                        "blocked": True,
                        "output": None,
                        "error": (
                            f"Tool '{tool_name}' was not executed: the utterance "
                            f"'{user_utterance[:120]}' sounds like research (info "
                            f"*about* a topic), not an action on the connected "
                            f"system. Use search_web instead for general research. "
                            f"Action tools (cli_* and MCP) are only meant for "
                            f"targeted operations on your own resources, e.g. "
                            f"'list my projects'."
                        ),
                    }
                else:
                    # Stamp the turn's resolved output language so deterministic
                    # tool readbacks (computer_use "On it"/"Done") speak the
                    # conversation's language instead of re-deriving it from the
                    # bare utterance — a lone "Now" must not flip a German turn
                    # to English (forensic 2026-06-18). One value, honoring the
                    # pin AND conversation stickiness (Runtime Output Language).
                    out_lang = resolve_output_language(
                        reply_language, "unknown", user_utterance,
                        conversation_language=conversation_language,
                    )
                    result = await self._executor.execute(
                        tool, tool_args,
                        # A turn whose text the application composed (a
                        # continuation with delegated results) names the
                        # person's own request for the tools' checks.
                        user_utterance=str(
                            self._tool_context.get("person_request") or user_utterance
                        ),
                        config_snapshot={
                            **self._tool_context,
                            "output_language": out_lang,
                            "voice_confirm": voice_confirm,
                        },
                        trace_id=tid,
                        # Session-Decision-Log: the model's natural-language text
                        # emitted alongside this tool call IS the "why". Captured
                        # for free (no extra call); the executor redacts + caps it.
                        rationale=agg.text or "",
                    )
                    # Two-turn voice/chat confirmation: the executor deferred this
                    # consequential tool instead of blocking. Speak a short
                    # confirmation question and END the turn (no second brain
                    # round) — the user's next "ja" resumes the stashed action via
                    # the BrainManager. The pending descriptor rides out-of-band on
                    # ``final_agg.voice_confirm`` (never serialized into history).
                    if (
                        result is not None
                        and result.error == VOICE_CONFIRM_SENTINEL
                        and isinstance(result.output, dict)
                    ):
                        # Lazy import: ``dodaios.voice`` couples to ``dodaios.core.
                        # self_mod`` via its package __init__, so importing it at
                        # this low-level module's load time creates an order-
                        # dependent circular import. Import on first use instead.
                        from dodaios.voice.tool_confirmation import (
                            format_tool_confirmation,
                        )
                        impact = result.output.get("impact")
                        if not isinstance(impact, dict):
                            impact = {}
                        question = format_tool_confirmation(
                            result.output.get("tool_name", tool_name),
                            language=out_lang,
                            impact_level=impact.get("level"),
                            impact_commands=impact.get("commands"),
                        )
                        final_agg.text = question
                        final_agg.finish_reason = "voice_confirm_pending"
                        final_agg.voice_confirm = {
                            "trace_id": result.output.get("trace_id"),
                            "tool_name": result.output.get("tool_name", tool_name),
                        }
                        if text_consumer is not None and question:
                            try:
                                text_consumer(question)
                            except Exception:  # noqa: BLE001 — consumer errors must not lose the turn
                                log.debug("text_consumer failed on confirm question", exc_info=True)
                        return final_agg
                    tool_result_payload = {
                        "success": result.success,
                        "output": result.output,
                        "error": result.error,
                    }
                    # Appshots use the same in-memory image envelope as Live.
                    # Never serialize pixels as tool-result text (or log them).
                    if isinstance(result.output, dict) and "_image" in result.output:
                        tool_result_payload["output"] = {
                            k: v for k, v in result.output.items() if k != "_image"
                        }
                    # Record a tool that ACTUALLY ran (success only) so consumers
                    # can tell a real side effect from a merely-requested or
                    # guard-blocked call. The guard branches above never reach
                    # here, so a blocked computer_use / open_app is correctly
                    # absent — this is what keeps the voice pipeline from speaking
                    # "Erledigt." for a desktop action that did not happen
                    # (2026-06-09).
                    # A lookup that only names other tools is not an action:
                    # counting it would let "I sent the mail" stand after a
                    # turn that only searched for the mail tool.
                    if result.success and not getattr(tool, "is_lookup_only", False):
                        final_agg.executed_tool_names.add(tool_name)
                    # suppress_response=True: tool provides its own final response,
                    # the second brain iteration is skipped (fix for 1-3 s stall
                    # after fire-and-forget tool calls like spawn_worker).
                    if (
                        getattr(tool, "suppress_response", False)
                        and result.success
                    ):
                        suppress_output = result.output

                    # Wave 1.4 — deterministic honest readback for a config
                    # change. In the voice/chat path config applies immediately
                    # (auto_apply="all", no pre-confirm), so the post-change line
                    # must be the REAL pipeline outcome (applied / rolled back /
                    # refused), never a free-form "done" the brain invents. Render
                    # it here and suppress the second brain turn. Language = the
                    # already-resolved output_language (no per-layer re-derivation,
                    # Runtime Output Language doctrine). Lazy import: dodaios.voice
                    # couples to dodaios.core.self_mod via its package __init__.
                    if tool_name == "set_config_value":
                        from dodaios.voice.config_readback import config_readback

                        readback = config_readback(
                            success=result.success,
                            output=result.output,
                            language=out_lang,
                        )
                        if readback is not None:
                            suppress_output = readback

                # Append tool result as a new message. Cap it centrally so no
                # tool can flood the brain's context with an unbounded raw payload
                # (the actual image artifacts still ride separately as a user-role
                # message below, so clipping this text never blinds vision).
                current_messages.append(BrainMessage(
                    role="tool",
                    content=[{
                        "type": "tool_result",
                        "tool_use_id": call_id,
                        "content": _cap_tool_result_json(
                            json.dumps(
                                tool_result_payload, ensure_ascii=False,
                                separators=(",", ":"), default=str,
                            )
                        ),
                    }],
                    tool_call_id=call_id,
                    name=tool_name,
                ))
                if self._control is not None:
                    # The verifier's only evidence that something happened.
                    body = tool_result_payload.get("output")
                    if body in (None, ""):
                        body = tool_result_payload.get("error") or ""
                    tool_log.append(ToolRecord(
                        name=tool_name,
                        ok=bool(tool_result_payload.get("success")),
                        blocked=bool(tool_result_payload.get("blocked")),
                        preview=str(body)[:200],
                    ))
                # A tool just finished — another active-work boundary. Reset the
                # no-progress deadline so a slow tool (a vision capture, an MCP
                # round-trip) does not count as a stall.
                _progress()

                # Wave 2 (vision-on-demand): if the tool returned image
                # artifact(s), feed them back as a user-role message so a
                # vision-capable provider can actually see them on the next
                # iteration. A tool-role message becomes a Gemini functionResponse
                # (no image support), so the image MUST ride on a user message.
                # Gated on a real execution — the refusal/guard branches above
                # leave result=None, so this only fires for tools that ran.
                if result is not None:
                    _img_blocks = _images_from_artifacts(
                        getattr(result, "artifacts", ()) or ()
                    )
                    if isinstance(result.output, dict) and isinstance(
                        result.output.get("_image"), dict,
                    ):
                        picture = result.output["_image"]
                        _img_blocks.append(ImageBlock(
                            mime=picture["mime"], data_b64=picture["data"],
                        ))
                    if _img_blocks:
                        current_messages.append(BrainMessage(
                            role="user",
                            content="(Tool screenshot — describe or use it as needed.)",
                            images=tuple(_img_blocks),
                        ))

            # The meta/debug acknowledgement ends the turn on a canned line, so
            # it may only speak when this turn produced nothing else. A round
            # that ran run_shell successfully AND requested a spawn used to end
            # on "Verstanden. Was genau hätte anders sein sollen?", the  # i18n-allow
            # shell result was discarded, and the user heard nothing of the work
            # that DID happen. Same rule as the missing-tool fallback below.
            if (
                meta_debug_ack is not None
                and suppress_output is None
                and not final_agg.executed_tool_names
            ):
                suppress_output = meta_debug_ack

            # A missing tool is a full-turn refusal only when nothing else ran.
            # In a multi-call round, one stale/model-invented name must never
            # overwrite successful evidence from another call with the generic
            # "missing tool" phrase. Feed both results back to the model so it
            # can report the partial outcome honestly.
            # An unattended turn (a scheduled task or routine, BUG-212) has no
            # listener to protect from silence and nobody to re-ask: the error
            # is already in the history, so let the model take another round
            # with the tools it does have instead of ending on the phrase.
            if (
                unknown_tool_requested
                and suppress_output is None
                and not final_agg.executed_tool_names
                and not self._unattended
            ):
                suppress_output = _anti_silence_phrase(
                    user_utterance, reply_language, conversation_language
                )

            # Budget check after execution: the results of this round are
            # already in the history — force ONE final tool-less answer round
            # over them instead of discarding the evidence with a hard break.
            if self._budget.exceeded():
                log.warning(
                    "tool_use_loop: iteration budget exhausted after %d "
                    "round(s) — forcing a final tool-less answer round",
                    self._budget.turns_used,
                )
                final_agg.finish_reason = "budget_exceeded"
                deadline_forced = True
                tools_payload = []
                current_messages.append(BrainMessage(
                    role="user",
                    content=_BUDGET_FINAL_DIRECTIVE,
                ))

            # Wall-clock deadline check after execution: force ONE final
            # tool-less answer round from the evidence gathered so far.
            elif (
                self._deadline_s is not None
                and time.monotonic() - loop_started >= self._deadline_s
            ):
                deadline_forced = True
                elapsed = time.monotonic() - loop_started
                log.warning(
                    "tool_use_loop: %.1fs deadline reached after %.1fs / "
                    "%d round(s) — forcing a final tool-less answer round",
                    self._deadline_s, elapsed, self._budget.turns_used,
                )
                tools_payload = []
                current_messages.append(BrainMessage(
                    role="user",
                    content=_DEADLINE_FINAL_DIRECTIVE,
                ))

            # Fire-and-forget: if any tool has suppress_response=True,
            # skip the second brain iteration and return immediately.
            if suppress_output is not None:
                final_agg.text = suppress_output
                final_agg.finish_reason = "suppress_response"
                # Feed the suppress text into the sentence-stream consumer
                # (when present) so the TTS path actually speaks it. Without
                # this hook, `final_agg.text` is set but the speech-pipeline
                # never received any text-chunk, so the Brain-Stream log
                # line printed `🤖 Jarvis [de] (streamed): ` with nothing
                # after — the user heard silence even though we had an ACK
                # phrase ready. Verified live 2026-05-13: Voice-Spawn-ACK
                # was suppressed for exactly this reason.
                if text_consumer is not None and suppress_output:
                    try:
                        text_consumer(suppress_output)
                    except Exception:  # noqa: BLE001
                        # Consumer errors must not block the final return —
                        # speech-pipeline bugs are surfaced upstream via
                        # AnnouncementRequested events.
                        pass
                break

        return final_agg