fix(agent): unambiguous document listing format for LLM parsing

tests/unit/test_mock_tool_flow.py

@@ -33,21 +33,25 @@ SYSTEM_LOW = "<relevance>LOW</relevance>\n"
 TOOLS = [{"type": "function", "function": {"name": "list_documents"}}]
 
 #: The agent's ``list_documents`` output for a two-document KB
-# (``app/rag/agent.py`` ``_execute_tool``): one ``source/path — title``
-#: line per document, ``(source, path)`` order.
+#: (``app/rag/agent.py`` ``_execute_tool``): one
+#: ``source: X | path: Y | title: Z`` line per document (phase 63: labeled,
+#: unambiguous fields), ``(source, path)`` order.
 CATALOG_2 = (
     "2 documents:\n"
-    "Deployments/example-record-file.json — Example Record File\n"
-    "Homelab/aws-route53.md — AWS Route 53 Notes"
+    "source: Deployments | path: example-record-file.json | title: Example Record File\n"
+    "source: Homelab | path: aws-route53.md | title: AWS Route 53 Notes"
 )
 
-CATALOG_1 = "1 documents:\nDeployments/example-record-file.json — Example Record File"
+CATALOG_1 = (
+    "1 documents:\n"
+    "source: Deployments | path: example-record-file.json | title: Example Record File"
+)
 
 CATALOG_3 = (
     "3 documents:\n"
-    "Deployments/aaa.md — AAA\n"
-    "Deployments/bbb.md — BBB\n"
-    "Homelab/ccc.md — CCC"
+    "source: Deployments | path: aaa.md | title: AAA\n"
+    "source: Deployments | path: bbb.md | title: BBB\n"
+    "source: Homelab | path: ccc.md | title: CCC"
 )
 
 DOC1_SP = "Deployments/example-record-file.json"
@@ -116,10 +120,23 @@ def test_single_flow_list_step() -> None:
 
 def test_single_flow_read_step_first_catalog_line() -> None:
     flow = _tool_flow(_body(SINGLE_USER, (CATALOG_3,)))
-    # The FIRST listing line (Deployments/aaa.md), rsplit convention.
+    # The FIRST listing line (Deployments/aaa.md), labeled fields.
     assert flow == ("read", "Deployments", "aaa.md", "call_1")
 
 
+def test_read_step_nested_path_stays_intact() -> None:
+    # Phase 63 bug report: the path itself contains ``/`` — the old
+    # ``source/path — title`` + ``rpartition("/")`` parse misread the
+    # split (``source=brain-of-reese-main/homelab``). The labeled fields
+    # recover the nested path intact, however deep.
+    catalog = (
+        "1 documents:\n"
+        "source: brain-of-reese-main | path: homelab/aws-route53.md | title: aws-route53"
+    )
+    flow = _tool_flow(_body(SINGLE_USER, (catalog,)))
+    assert flow == ("read", "brain-of-reese-main", "homelab/aws-route53.md", "call_1")
+
+
 def test_single_flow_answer_step_with_tools_offered() -> None:
     # Phase 45: the round cap keeps the tools offered until it is hit —
     # the answer step fires regardless of the ``tools`` parameter.