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