fix(agent): teach the document-identity contract on ls/read/grep refusals — end the post-harness tool-loop rambling

Phase 72 (72_teaching_refusals) — completed under the 2026-09-04 controlled
methodology (owner directive: stop clearing/re-importing the homelab KB per
iteration; measure tool-calling accuracy on a controlled fixture KB, target
>90%).

Real-model gate verdicts (live, configured chat model 'lite', fixture KB):
- Controlled fixture battery (the new methodology's pass condition —
  contract accuracy >= 90%): PASS, 4 consecutive runs:
  gate: lite PASS turns=10 answered=10 caps=0 tool-turns=10 calls 8/11 executed (73%) contract 11/11 (100%) 2026-09-04 (wall 43.4s)
  gate: lite PASS turns=10 answered=10 caps=0 tool-turns=10 calls 8/13 executed (62%) contract 12/13 (92%) 2026-09-04 (wall 50.6s)
  gate: lite PASS turns=10 answered=10 caps=0 tool-turns=10 calls 7/11 executed (64%) contract 11/11 (100%) 2026-09-04 (wall 46.8s)
  gate: lite PASS turns=10 answered=10 caps=0 tool-turns=10 calls 9/15 executed (60%) contract 14/15 (93%) 2026-09-04 (wall 54.8s)
- Locked derived battery (phase-72 task 05, executed >= 90% bar, run
  unchanged on the same fixture KB):
  gate: lite FAIL turns=10 answered=10 caps=0 tool-turns=10 calls 5/15 executed (33%) contract 12/15 (80%) 2026-09-04 (wall 47.7s)
  The teaching works — every bare-path trap self-corrects in exactly one
  round, zero cap hits, zero repeat loops, 10/10 answered. The locked
  executed bar is blocked by ALREADY_IN_CONTEXT dedupe refusals on the
  corrected re-reads (the trap question seeds its target, so the correct
  combined-form read is refused for redundancy) — a copy-invariant model
  behavior (five copy variants, 0/15 re-reads flipped, 2026-09-03 -> 04)
  and an app-semantics decision for the owner (TOOL_CALLING_TESTING.md
  sections 5 and 7), not a copy lever.

Copy changes this phase owns (unit pins updated to follow):
- app/rag/agent.py: ls teaching refusals (path-like scope -> document-path
  line; unknown source -> no-source line with the source-name
  parenthetical), read/grep 'did you mean source/path?' teaching
  (find_path_candidates: exact or suffix path match, catalog order, cap 3),
  ALREADY_IN_CONTEXT naming the correct action (answer from the text
  already in the prompt), read tool description front-loaded with the
  do-not-read rule (the 2026-09-04 controlled telemetry: the re-read is
  the only remaining refusal class; contract accuracy 92-100% across runs)
- app/rag/prompts.py: TOOLS_SECTION states the document-identity contract
  up front (ls path = source name; read/grep = combined source/path
  including the source name; do-not-read for <documents> documents placed
  next to the read teaching; one-call-per-reply and never-repeat rules)
- tests: refusal pins (unit + integration), new dedicated E2E suite
  tests/e2e/test_tool_path_teaching.py (mock misuse flow, green in
  isolation), regression suites green in isolation (harness_aligned_tools,
  agent_document_tools, agent_unlimited_tools, search_tool, chat_rag).

Gates: uv run pytest green (1501); coverage TOTAL 99% (>90%); ruff +
pyright clean. Carries the still-uncommitted phase-71 todo/ -> complete/
move and both phases' .agent/reports/ (AGENTS.md 8).

tests/unit/test_prompts.py

@@ -10,6 +10,12 @@ And the phase-71 deflection plain-text line (owner-permitted
 2026-09-03): the LOW prompt = pre-phase text + exactly the one new
 line; the ``DEFLECT_MODE`` marker-keying contract is unchanged and
 the line never leaks into the HIGH prompt.
+
+And the phase-72 ``<tools>`` copy: the document-identity contract is
+stated up front (the ``ls`` source-name scope, the combined
+``source/path`` identity for ``read``/``grep``) — the same contract
+the teaching refusals in :mod:`app.rag.agent` re-state; the
+``<tools>`` marker keying (HIGH only) is unchanged.
 """
 from __future__ import annotations
 
@@ -170,13 +176,14 @@ def test_tools_section_markers_and_new_tool_names() -> None:
 
 
 def test_tools_section_teaches_the_harness_shapes() -> None:
-    """Copy pins: ``ls``'s phase-63 catalog-line format (and its
-    optional one-source scope), ``grep``'s case-insensitive exact-string
-    locator contract (up to 20 ``source/path:line: text`` lines, a
-    locator not a context-adder), and ``read``'s combined
-    ``source/path`` + full content."""
+    """Copy pins: ``ls``'s phase-63 catalog-line format, ``grep``'s
+case-insensitive exact-string locator contract (up to 20
+``source/path:line: text`` lines, a locator not a context-adder),
+and ``read``'s combined ``source/path`` + full content. (Phase 72:
+the source-name scope clause and the combined-identity clause are
+pinned byte-for-byte in
+:func:`test_tools_section_phase72_contract_clauses`.)"""
     assert "source: X | path: Y | title: Z" in TOOLS_SECTION
-    assert "pass a source name as `path`" in TOOLS_SECTION
     assert "case-insensitive" in TOOLS_SECTION
     assert "up to 20" in TOOLS_SECTION
     assert "source/path:line: text" in TOOLS_SECTION
@@ -186,6 +193,66 @@ def test_tools_section_teaches_the_harness_shapes() -> None:
     assert "Answer as soon as you have what you need" in TOOLS_SECTION
 
 
+def test_tools_section_phase72_contract_clauses() -> None:
+    """Phase 72: the two contract clauses the teaching refusals
+    re-state after the fact, pinned byte-for-byte in the constant —
+    the ``ls`` source-name clause (its optional ``path`` is a source
+    name, not a directory or file path; omit it to list every
+    document) and the ``read``/``grep`` combined-identity clause
+    (the combined ``source/path`` string exactly as shown in the
+    ``ls`` output, *including the source name*; a bare document path
+    will not resolve)."""
+    # The ls source-name clause.
+    assert (
+        "a source name (e.g. 'homelab'), not a directory or file "
+        "path — omit it to list every document"
+    ) in TOOLS_SECTION
+    # The read combined-identity clause.
+    assert (
+        "combined `source/path` string, exactly as shown in the `ls` "
+        "output — including the source name"
+    ) in TOOLS_SECTION
+    # The bare-path note: read clause AND grep clause (exactly twice).
+    assert TOOLS_SECTION.count(
+        "a bare document path (without the source name) will not resolve"
+    ) == 2
+    # The pre-phase-70 scope wording is gone — replaced by the
+    # explicit source-name contract.
+    assert "pass a source name as `path`" not in TOOLS_SECTION
+
+
+def test_tools_section_phase72_clauses_in_high_prompt_not_low() -> None:
+    """Phase 72: the contract clauses ride the HIGH prompt with the
+    rest of the section and never leak into the LOW/deflection prompt
+    (whose byte-identity is pinned in
+    :func:`test_zero_note_prompt_is_byte_identical_to_pre_steering`)."""
+    doc = _doc("kubernetes.md", "Talos Linux on three nodes.", "Kubernetes Homelab Cluster")
+    high = build_high_prompt([doc])
+    assert "<tools>" in high
+    assert "not a directory or file path" in high
+    assert "including the source name" in high
+    for low in (build_deflect_prompt(["T1"]), build_deflect_prompt([])):
+        assert "<tools>" not in low
+        assert "not a directory or file path" not in low
+        assert "including the source name" not in low
+
+
+def test_documents_section_has_no_leading_intro() -> None:
+    """Phase 72, task 05 (gate iterations 2-3, reverted): the
+    ``<documents>`` section must NOT lead with an in-context reminder
+    or name the ``<document>`` blocks — the live telemetry showed that
+    copy primed the model to latch the seed documents' paths as
+    ``ls`` scopes (the incident turn regressed to a cap-reached loop
+    on run 2 and re-trapped on run 5), and the reminder never flipped
+    the seed-doc ``read``s (15/15 across gate runs 1-5). The section
+    is exactly the document blocks again."""
+    doc = _doc("kubernetes.md", "Talos Linux on three nodes.", "Kubernetes Homelab Cluster")
+    high = build_high_prompt([doc])
+    i_open = high.index("<documents>")
+    i_block = high.index('<document source="Homelab"')
+    assert high[i_open : i_block] == "<documents>\n"  # no intro line
+
+
 def test_tools_section_old_names_and_budget_copy_gone() -> None:
     """The phase-37/68 tool names and the phase-37 per-tool budget line
     (phase 45: the round cap is the bound — the prompt does not