docs: clarify parse_session is a single pass

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

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] = {}