From 830fe14e1d855c42b138d6240628507913b8ba5d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=80=9CSebastian?=
 <64795732+slegarraga@users.noreply.github.com>
Date: Thu, 6 Aug 2026 04:46:24 -0400
Subject: [PATCH] docs: clarify parse_session is a single pass

---
 README.md          | 5 +++--
 agentrace/parse.py | 5 +++--
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 40186ce..a4ee3f0 100644
--- a/README.md
+++ b/README.md
@@ -109,8 +109,9 @@ Zero dependencies beyond `rich`. No API keys, no network: it reads local files.
 
 ## Design notes
 
-**Two passes over the transcript, not one.** Results can appear before every use has been seen in
-unusual orderings. A 34MB file is cheap to scan twice compared to getting the pairing subtly wrong.
+**One pass over the transcript, two maps.** Results can appear before every use has been seen in
+unusual orderings. The pass collects tool_use and tool_result blocks by tool_use_id and joins
+them afterwards.
 
 **A torn final line is skipped, not fatal.** A live session being appended to yields half-written
 JSON. Refusing to parse would mean you cannot analyse a run until it is over, which is exactly
diff --git a/agentrace/parse.py b/agentrace/parse.py
index aad029c..023a4a5 100644
--- a/agentrace/parse.py
+++ b/agentrace/parse.py
@@ -111,8 +111,9 @@ def _records(path: Path) -> Iterator[dict]:
 def parse_session(path: Path) -> Session:
     """Pull every Agent delegation out of one transcript.
 
-    Two passes over the file rather than one: results can appear before we have seen every use in
-    weird orderings, and a 34MB file is cheap to scan twice compared to getting this subtly wrong.
+    Reads the file once and collects tool_use and tool_result blocks into two
+    maps keyed by tool_use_id, then joins them. Pairing does not depend on a
+    result appearing after its use.
     """
     uses: dict[str, dict] = {}
     results: dict[str, dict] = {}