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

app/schemas.py

@@ -71,20 +71,24 @@ class ChatThinkingEvent(BaseModel):
 class ChatToolEvent(BaseModel):
     """SSE frame for one agent tool call (phase 37, PLAN §4 extension).
 
-    A15 extension (owner permission 2026-08-26): a grounded turn may call
-    the server-side document tools (``list_documents`` / ``read_document``,
-    see :mod:`app.rag.agent`); each model-requested call streams as
-    ``{type: "tool", name: str, argument: str | null}`` ahead of the
-    answer's ``delta`` frames. ``argument`` is the read document's
-    ``"source/path"`` for ``read_document`` and null otherwise. The client
+    A15 extension (owner permission 2026-08-26; ``search_documents``
+    added in phase 68): a grounded turn may call the server-side
+    document tools (``list_documents`` / ``read_document`` /
+    ``search_documents``, see :mod:`app.rag.agent`); each model-requested
+    call streams as ``{type: "tool", name: str, argument: str | null}``
+    ahead of the answer's ``delta`` frames. ``argument`` is the read
+    document's ``"source/path"`` for ``read_document``, the search
+    pattern for ``search_documents``, and null otherwise (a non-string
+    pattern — a model error the backend refuses — is null). The client
     renders each frame as a "calling tool" line/state (phase 37 task 05);
     the ``delta`` / ``done`` shapes are unchanged — the read document is
-    reflected in ``done.sources`` instead.
+    reflected in ``done.sources`` instead (a search adds no source: it is
+    a locator, locked A5).
     """
 
     type: Literal["tool"] = "tool"
-    name: str  # "list_documents" | "read_document"
-    argument: str | None = None  # "source/path" for read_document
+    name: str  # "list_documents" | "read_document" | "search_documents"
+    argument: str | None = None  # "source/path" for read_document, pattern for search_documents
 
 
 class ChatDoneEvent(BaseModel):