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.
Python agent-orchestrationai-agentai-coding-assistantclaude-codecoding-agentcomputer-usedesktop-applocal-firstmcppersonal-jarvisvoice-assistantvoice-coding
"""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