Native when you can, text-parse when you must.

01 The tool loop.

ToolLoop.run() in tools/loop.py is the heart of in-turn tool dispatch. The same loop handles both native and text-parsed tools — the difference is in where the tool calls come from in the model's response.

The loop tracks two parallel records:

• tool_context — a list of dicts {tools_called: [...], results: "..."} used to build the history-persisted summary block (so the next turn sees a "Tool Results @ ..." system message).
• tool_call_details — per-call dicts with name, arguments, result, and iteration. Used by debug logging and by the turn-log writer.

02 Format handlers.

tools/formats/ defines a small interface, ToolFormatHandler, with three handlers:

The active handler is picked once per turn from config.get_tool_format(model_alias=..., model_def=...). OpenAI and Grok use native; local models (llama.cpp, vLLM, Ollama) use ReAct.

03 Why ReAct for local models.

The trade-off is that text-parsed tool calls are messier: models invent variant names, malform JSON, hallucinate observations, or trail off into commentary. react.py handles all of this with a fallback ladder.

04 ReAct parsing.

The ReAct handler looks for the standard markers (Thought:, Action:, Action Input:, Observation:) plus a set of alternative markers (# Tool:, Tool:, Function:) that some models use. Tool names are normalized through a 30-entry alias table — retrieve_conversation_history, search_memory, save_memory, google, etc. all map to canonical tool names so the executor doesn't fail on naming drift.

Arguments are JSON — but loose JSON. _try_fix_json walks a series of repair attempts: unbalanced braces, trailing commas, single quotes, unquoted keys. If json5 is installed it's tried as a last resort. If everything fails, the call is recorded with an error result and the model sees the failure in the next iteration.

Stop sequences from ReActFormatHandler.get_stop_sequences() include Observation: and a few variants — they cut the model off the moment it tries to hallucinate a tool result, before it can wander into fiction. Adapters like DolphinAdapter add their own model-specific stops that get concatenated.

05 Cross-format fallbacks inside the loop.

Even with a format picked, models go off-script. ToolLoop.run() has a short fallback ladder: if the configured handler finds no tool calls but the response contains <tool_call>, <function_call>, or action: + action input:, it instantiates the matching handler dynamically, parses again, and logs a warning. This catches models that "leak" a different format than was requested without failing the turn.

After a tool runs, the loop appends an assistant message and the tool result message. For ReAct, the assistant message is truncated at the end of the last detected tool-call's raw text — otherwise hallucinated continuations like "the result is X, so I'll also..." poison the next iteration. Native mode appends the message verbatim with tool_calls attached, since the SDK handles structuring.

06 The executor.

ToolExecutor in tools/executor.py (1,943 lines) is where the call actually runs. It owns references to every backend client (memory, profile, search, home, HA-native, news, web-fetch, model lifecycle, history) and a dispatch table mapping tool names to handler methods.

The consolidated catalog is intentionally small. Most "tools" are action-based — one tool with an action parameter that selects the operation:

Legacy single-purpose names (search_memories, store_memory, web_search, get_current_time, …) are kept in the dispatch table as aliases routing to the consolidated handlers. Existing prompts and fine-tunes that emit the old names still work.

A per-turn call counter (default max 20, configurable via MAX_TOOL_CALLS_PER_TURN) prevents runaway loops. HA-mode caps it at 3 — device commands almost never need more, and the cap stops a chatty model from spamming the smart-home graph.

07 Home Assistant native tools.

When the configured HomeAssistantNativeClient is initialized, llm-bawt also exposes HA's own catalog — HassTurnOn, HassTurnOff, HassLightSet, HassSetPosition, GetLiveContext, GetDateTime — converted into Tool objects via ha_tools_to_tool_definitions. These pass through the same format handler and executor, but the executor delegates to the HA MCP client rather than the consolidated home tool. The native catalog gives the model finer-grained control when configured, with extensive prompt guidance baked into the format handler about device-control semantics (cover open/close vs on/off, friendly names vs entity IDs, area/floor targeting).

08 Streaming tool events.

The non-streaming tool loop in loop.py is the simpler case — every iteration runs synchronously, then the final answer is returned. For SSE streaming, tools/streaming.py (352 lines) implements stream_with_tools:

• The model's response is streamed token-by-token into a buffer.
• The buffer is checked for tool-call markers as it grows. Until a decision threshold (~80 chars) it's not yet clear whether the response is text or a tool call.
• If markers appear, the stream is consumed silently until the call completes, then the tool runs and emits tool_call / tool_result events to the SSE channel.
• If the response is clearly text, buffered chunks flush to the SSE stream as content deltas and the model continues streaming normally.

This is how the BawtHub UI shows tool calls inline with the answer: the SSE event types tool_call and tool_result are intercepted by the frontend's chunk parser and rendered as their own card UI inside the assistant bubble. Frontends that don't care just ignore them — the standard content deltas still arrive in the right order.

09 Output sanitization.

Three layers of cleanup run before the final response is returned to the caller:

1. Adapter cleaning. Per the adapters page, model-specific quirks (Pygmalion BBCode, Dolphin hallucinated observations) are stripped. Runs after streaming, before format-handler sanitization.
2. Handler sanitization. Each handler implements sanitize_response — removes trailing tool markers, residual Observation: stubs, and any other format-specific scaffolding from the final answer.
3. Cross-format leakage. shared/output_sanitizer.strip_tool_protocol_leakage catches stray tool-protocol fragments that snuck through both layers — e.g. an OpenAI model that emitted a ReAct-style Thought: by mistake.

10 Key files.