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

tests/unit/test_agent.py

@@ -110,6 +110,18 @@ def test_agent_tools_names_and_parameters() -> None:
     assert by_name["read_document"]["function"]["description"] == (
         "Add the full content of one more indexed document to your context"
     )
+    # Phase 63 (A2): the parameter descriptions point the LLM at the
+    # labeled `source:` / `path:` fields of the list_documents output.
+    assert read_params["properties"]["source"]["description"] == (
+        "The document's source, as shown after 'source: ' in the "
+        "list_documents output (e.g. 'Homelab' from "
+        "'source: Homelab | path: homelab/aws-route53.md')."
+    )
+    assert read_params["properties"]["path"]["description"] == (
+        "The document's path, as shown after 'path: ' in the "
+        "list_documents output (e.g. 'homelab/aws-route53.md' from "
+        "'source: Homelab | path: homelab/aws-route53.md')."
+    )
 
 
 # ---------- happy path: list → read → answer ----------
@@ -184,8 +196,8 @@ def test_list_then_read_then_answer(
         "tool_call_id": "call_1",
         "content": (
             "2 documents:\n"
-            "Deployments/backups.md — Backup Strategy\n"
-            "Homelab/aws-route53.md — AWS Route53 Records"
+            "source: Deployments | path: backups.md | title: Backup Strategy\n"
+            "source: Homelab | path: aws-route53.md | title: AWS Route53 Records"
         ),
     }
     # The second follow-up request carries the read call + the FULL text.
@@ -243,7 +255,7 @@ def test_always_list_bounded_by_round_cap(monkeypatch: pytest.MonkeyPatch) -> No
     ``agent_max_rounds`` tool rounds, then one forced ``tools=None``
     request streams the answer — the cap is the only forced exit."""
     monkeypatch.setattr(agent, "list_catalog", lambda db: [("S", "a.md", "A")])
-    listing = "1 documents:\nS/a.md — A"
+    listing = "1 documents:\nsource: S | path: a.md | title: A"
     holder = AgentHolder()
     llm = ScriptedLLM(
         [ToolCallPiece(id="call_1", name="list_documents", arguments={})],
@@ -359,8 +371,8 @@ def test_relist_executes_and_counts(monkeypatch: pytest.MonkeyPatch) -> None:
     assert holder.tool_calls == 2  # both re-lists executed and counted
     listing = (
         "2 documents:\n"
-        "Deployments/backups.md — Backup Strategy\n"
-        "Homelab/aws-route53.md — AWS Route53 Records"
+        "source: Deployments | path: backups.md | title: Backup Strategy\n"
+        "source: Homelab | path: aws-route53.md | title: AWS Route53 Records"
     )
     # The answer request carries the catalog a second time as a tool result.
     assert llm.requests[2][0][3]["content"] == listing  # first listing

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.