feat(agent): align the document tools with the harness-trained shape — ls, read(path), grep(pattern, path?)

app/rag/prompts.py

@@ -24,11 +24,13 @@ the ``<tuning>`` section (order: ``<relevance>`` →
 roughly what the KB contains before retrieval. With an empty row the
 prompt is byte-identical to the pre-phase text.
 
-Agent tools (phase 37): the **HIGH** prompt only carries a ``<tools>``
-section after the ``<documents>`` body — the grounded turn may call the
-server-side ``list_documents`` / ``read_document`` tools (round-capped,
-see :mod:`app.rag.agent`). The LOW/deflection prompt never carries it
-and stays byte-identical to the pre-phase text.
+Agent tools (phase 37; phase 70: the copy teaches the harness-aligned
+``ls`` / ``read`` / ``grep`` shapes): the **HIGH** prompt only carries a
+``<tools>`` section after the ``<documents>`` body — the grounded turn
+may extend its context through the three server-side tools (round-
+capped, see :mod:`app.rag.agent`; the cap is the bound and this section
+does not re-state it, phase 45). The LOW/deflection prompt never
+carries it and stays byte-identical to the pre-phase text.
 """
 from __future__ import annotations
 
@@ -73,21 +75,29 @@ _KB_INTRO = (
 )
 
 #: The ``<tools>`` instructions section — **HIGH prompt only** (phase 37,
-#: task 03): a grounded turn may extend its context through the two
-#: server-side tools (round cap: ``BOR_AGENT_MAX_ROUNDS``, see
-#: :mod:`app.rag.agent`). Appended after
-#: the mode body (``<documents>``), so the instructions are the last
-#: thing the model reads. The LOW/deflection prompt never carries it —
-#: a deflection has no grounded context to extend — and stays
-#: byte-identical to the pre-phase text. The E2E mock keys off the
-#: ``<tools>`` marker's *presence*, not this wording.
+#: task 03; phase 70: the copy is rewritten for the harness-aligned
+#: ``ls`` / ``read`` / ``grep`` shapes, names/args exactly as the
+#: ``AGENT_TOOLS`` schemas in :mod:`app.rag.agent`): a grounded turn may
+#: extend its context through the three server-side tools (round cap:
+#: ``BOR_AGENT_MAX_ROUNDS`` — the cap is the bound and this section does
+#: not re-state it, phase 45). Appended after the mode body
+#: (``<documents>``), so the instructions are the last thing the model
+#: reads. The LOW/deflection prompt never carries it — a deflection has
+#: no grounded context to extend — and stays byte-identical to the
+#: pre-phase text. The E2E mock keys off the ``<tools>`` marker's
+#: *presence*, not this wording.
 TOOLS_SECTION: str = (
     "<tools>\n"
-    "If the documents in your context reference other files, or you need "
-    "content that is not included above, call `list_documents` to see what "
-    "is indexed, then `read_document` to pull in exactly one more document. "
-    "Answer as soon as you have what you need — do not read more than one "
-    "extra document.\n"
+    "You may extend your context with three tools. `ls` lists the "
+    "indexed documents as `source: X | path: Y | title: Z` lines "
+    "(pass a source name as `path` to list one source's documents; "
+    "omit it to list every document). `grep` locates an exact string "
+    "(case-insensitive) in the indexed documents and returns up to 20 "
+    "matching `source/path:line: text` lines — a locator, not a "
+    "context-adder: read the winner with `read`. `read` pulls in one "
+    "document by its combined `source/path` string, exactly as shown in "
+    "the `ls` output, adding its full content to your context. Answer "
+    "as soon as you have what you need.\n"
     "</tools>"
 )
 
@@ -180,7 +190,8 @@ def build_high_prompt(
     kb_overview: str | None = None,
 ) -> str:
     """Grounded turn: locked persona (+ steering, + KB overview) + full
-texts of the top documents + the ``<tools>`` instructions (phase 37).
+texts of the top documents + the ``<tools>`` instructions (phase 37;
+the phase-70 copy teaches the ``ls`` / ``read`` / ``grep`` shapes).
 
     Section order: ``<relevance>`` → ``<knowledge_base>`` → ``<tuning>``
     → ``<documents>`` → ``<tools>``; empty steering/overview omit their