feat(rag): agent document tools — list/read tools with env-tuned budgets, SSE tool events + "calling tool" UI

Grounded chat turns now run the agent loop (app/rag/agent.py) instead
of a bare chat_stream: while the per-turn budgets last
(BOR_AGENT_LIST_CALLS / BOR_AGENT_READ_CALLS, default 1 each) the model
gets list_documents (the indexed catalog, /api/docs order) and
read_document (full text, never truncated — A7-revised contract); once
both budgets are spent the tools key is dropped from the request and
the model must answer. Rejected calls (unknown tool, unknown/missing
path, document already in context, spent budget) consume no budget.
Budgets 0/0 make exactly one tools=None request — byte-identical to
the pre-phase path (budgets-as-kill-switch). Deflected turns keep the
direct chat_stream (A8 unchanged; the LOW prompt never carries the
<tools> section).

SSE contract gains {"type":"tool","name":...,"argument":
"source/path"|null} frames ahead of the answer deltas (PLAN §4
extension, owner permission 2026-08-26); done.sources, query_log.sources
and the per-turn log line (gains tool_calls=N) report the retrieval
docs + read docs, deduped. The UI shows a "calling tool"
button/label state and one visible .tool-call line per call above the
answer; the lines persist with the chat record and re-render on
reload. chat_stream passes tools through and accumulates streaming
tool_calls deltas into ToolCallPiece (tools=None stays byte-identical).

E2E: deterministic mock tool flow ("use your tools" + <tools> marker:
list -> read first catalog line -> quoted answer) plus the story suite
(marker flow, reload re-render, plain/deflected no-tool regressions).
Docs: .env.example + README (the two tools, the budgets, the SSE tool
frame, the "calling tool" UI state).

probe: turbo tool_calls=supported 2026-08-26 (uv run python -m
scripts.llm_probe --tools — non-streaming + streaming
finish_reason=tool_calls, indexed delta.tool_calls partials)

tests/unit/test_prompts.py

@@ -16,6 +16,7 @@ from app.config import Settings
 from app.models import Document
 from app.rag.prompts import (
     PERSONA,
+    TOOLS_SECTION,
     _base,
     build_deflect_prompt,
     build_high_prompt,
@@ -116,14 +117,18 @@ def test_low_prompt_with_no_titles() -> None:
 
 def test_zero_note_prompt_is_byte_identical_to_pre_steering() -> None:
     """Phase 15 contract: with no steering notes the prompt is exactly what
-    it was before the <tuning> section existed."""
+    it was before the <tuning> section existed. (Phase 37: the HIGH prompt
+    additionally carries the ``<tools>`` section after the mode body — the
+    fixtures account for it; the LOW prompt is untouched.)"""
     doc = _doc("kubernetes.md", "Talos Linux on three nodes.", "Kubernetes Homelab Cluster")
     block = (
         '<document source="Homelab" path="kubernetes.md" title="Kubernetes Homelab Cluster">\n'
         "Talos Linux on three nodes.\n"
         "</document>"
     )
-    assert build_high_prompt([doc]) == _base("HIGH") + "\n<documents>\n" + block + "\n</documents>"
+    assert build_high_prompt([doc]) == (
+        _base("HIGH") + "\n<documents>\n" + block + "\n</documents>" + "\n" + TOOLS_SECTION
+    )
     assert build_deflect_prompt(["T1", "T2"]) == (
         _base("LOW")
         + "\nDEFLECT_MODE: retrieval was weak — the titles below are the closest "
@@ -220,14 +225,16 @@ def test_kb_section_tiny_budget_never_exceeds_cap() -> None:
 def test_no_overview_prompt_is_byte_identical_to_pre_phase() -> None:
     """Phase 31 contract: with no KB overview (None, empty, or blank)
     every prompt is exactly what it was before the ``<knowledge_base>``
-    section existed — with or without steering notes."""
+    section existed — with or without steering notes. (Phase 37: the HIGH
+    prompt additionally carries the ``<tools>`` section after the mode
+    body — the fixtures account for it; the LOW prompt is untouched.)"""
     doc = _doc("kubernetes.md", "Talos Linux on three nodes.", "Kubernetes Homelab Cluster")
     block = (
         '<document source="Homelab" path="kubernetes.md" title="Kubernetes Homelab Cluster">\n'
         "Talos Linux on three nodes.\n"
         "</document>"
     )
-    docs_block = "\n<documents>\n" + block + "\n</documents>"
+    docs_block = "\n<documents>\n" + block + "\n</documents>" + "\n" + TOOLS_SECTION
     high_plain = _base("HIGH") + docs_block
     high_steered = _base("HIGH") + "\n" + build_steering_section(["be concise"]) + docs_block
     low_plain = (