feat(agent): search_documents tool — the model can grep the indexed documents for an exact string

tests/integration/test_chat_api.py

@@ -621,6 +621,65 @@ def test_grounded_turn_streams_tool_frames_and_cites_read_doc(
     assert "'docs/homelab/backups.md'" in lines[-1]
 
 
+def test_grounded_turn_streams_search_tool_frames(
+    client, db, seeded_kb: FakeRagLLM
+) -> None:
+    """Phase 68: a scripted ``search_documents`` call streams as
+    ``{type: "tool", name: "search_documents", argument: <pattern>}`` —
+    the raw pattern is the frame's ``argument`` (the UI renders the
+    "searching for" line from it). A non-string pattern — a model error
+    the backend refuses — yields ``argument: null``. A search adds no
+    source: ``done.sources`` stays the retrieval docs (locked A5)."""
+    scripted = FakeRagLLM(
+        tool_script=[
+            [
+                ToolCallPiece(
+                    id="call_1",
+                    name="search_documents",
+                    arguments={"pattern": "Cilium"},
+                ),
+            ],
+            [
+                ToolCallPiece(
+                    id="call_2",
+                    name="search_documents",
+                    arguments={"pattern": 42},  # model error: non-string
+                ),
+            ],
+            # the answer request still carries the tools (2 rounds < the
+            # default cap of 10); the fake's tool_script is exhausted, so
+            # it falls back to the thinking + answer stream
+        ]
+    )
+    fastapi_app.dependency_overrides[chat_api.get_llm] = lambda: scripted
+    try:
+        _, _, frames = _stream_chat(client, QUESTION)
+    finally:
+        fastapi_app.dependency_overrides.clear()
+
+    types = [f["type"] for f in frames]
+    assert "error" not in types
+    assert len(scripted.seen_tools) == 3  # both searches executed (rounds)
+
+    tool_frames = [f for f in frames if f["type"] == "tool"]
+    assert len(tool_frames) == 2
+    first, second = tool_frames
+    assert set(first) == {"type", "name", "argument"}
+    assert first["name"] == "search_documents"
+    assert first["argument"] == "Cilium"  # the raw pattern
+    assert set(second) == {"type", "name", "argument"}
+    assert second["name"] == "search_documents"
+    assert second["argument"] is None  # the non-string pattern → null
+
+    # The searches still answered: deltas, then a grounded done.
+    assert [f for f in frames if f["type"] == "delta"]
+    done = frames[-1]
+    assert done["type"] == "done" and done["deflected"] is False
+    paths = [s["path"] for s in done["sources"]]
+    assert "homelab/kubernetes.md" in paths  # retrieval docs, unchanged
+    assert "homelab/backups.md" not in paths  # a search adds no source
+
+
 def test_deflected_turn_stays_byte_identical_without_tools(
     client, db, seeded_kb: FakeRagLLM
 ) -> None: