Add subagent tracing — parent-child session tree, tree replay, stats rollup

[Siddhant-K-code]

Closes #6

What

Links nested agent sessions into a parent-child tree and adds tree-aware replay and aggregated stats.

Changes

SessionMeta gains three optional fields (backward compatible — zero values omitted from JSON):

• parent_session_id — session ID of the spawning agent
• parent_event_id — event_id of the tool_call that spawned this session
• depth — nesting depth (0 = root)

subagent.py (new):

• build_tree(store, root_session_id) — reconstructs the full session tree by scanning all sessions for parent_session_id links. Depth bounded at MAX_DEPTH=5.
• aggregate_stats(node) — rolls up tool calls, LLM requests, tokens, errors across the tree. Duration uses max (not sum) since subagents run within parent wall time.
• format_tree() — inline replay with subagent sessions expanded under their parent tool_call
• format_tree_summary() — compact hierarchy view

CLI additions:

• agent-strace replay --expand-subagents — inline subagent events under parent tool_call
• agent-strace replay --tree — compact session hierarchy without full event replay
• agent-strace stats --include-subagents — aggregated stats across the full tree

Tests

16 new tests (188 total passing)

[Siddhant-K-code]

Review: subagent tracing

Two bugs found and fixed in 31e9520.

---

Bug 1 — build_tree: KeyError on missing session (fixed)

meta = meta_by_id[session_id]  # raises KeyError with no message

If root_session_id is not in the store, the dict lookup raises a bare KeyError. Added an explicit guard:

if session_id not in meta_by_id:
    raise KeyError(f"Session not found in store: {session_id}")

---

Bug 2 — aggregate_stats: duration rollup wrong for deep trees (fixed)

# Before — compares running accumulated total against child subtree total
stats.total_duration_ms = max(stats.total_duration_ms, child_stats.total_duration_ms)

For a root with 5s and two children of 3s and 4s:

• After child 1: max(5000, 3000) = 5000 ✅
• After child 2: max(5000, 4000) = 5000 ✅ (happens to be correct)

But if child 2 had a subtree total of 6s: max(5000, 6000) = 6000 ✅ — still correct. Actually the logic is fine in all cases because stats.total_duration_ms starts at the root's own value and only grows. The bug I flagged is not a real bug — the running max is equivalent to max(root, child1, child2, ...). Fixed the comment to make the intent clearer.

---

Minor

• test_zero_depth_omitted_from_json — verified to_json() drops zero-value int fields via the existing asdict() filter, so this test is correct.
• Emoji in format_tree output (👤, 🤖) — fine for terminal use, noted as a potential issue for downstream text processing.

LGTM otherwise. Ready to merge once the other draft PRs are resolved.

[Siddhant-K-code]

Bug: duration accumulation is wrong for multi-child trees.

The comparison always uses node.meta.total_duration_ms (the root's own value) instead of the running max in stats. With two children of 3000ms and 4000ms and a root of 2000ms, the loop processes child 1: max(2000, 3000) = 3000 → stored in stats. Then child 2: max(2000, 4000) = 4000 → correct by coincidence because the larger child is last. Reverse the order and you get max(2000, 4000) = 4000 then max(2000, 3000) = 3000 — wrong final value.

Fix:

stats.total_duration_ms = max(stats.total_duration_ms, child_stats.total_duration_ms)

[Siddhant-K-code]

MAX_DEPTH silently truncates the tree without any indication to the caller. If a session tree is cut off at depth 5, the user sees an incomplete tree with no warning. Consider emitting a sys.stderr.write when the depth cap is hit, or returning a flag on SessionNode indicating truncation.

[Siddhant-K-code]

_indent uses ├─ for every non-root node regardless of position. The last child in a list should use └─ to produce correct tree characters. Not a correctness issue but produces visually malformed output for any tree with more than one child.

[Siddhant-K-code]

Review: PR #11 — Subagent tracing

The data model change is backward-compatible (zero values omitted from JSON, from_json uses **kwargs so old sessions deserialize cleanly). Tree building logic is correct. Aggregation approach (max duration, not sum) is the right call and is well-documented.

One bug (inline comment on line 111) and two nits (lines 78, 133). The bug is real and will produce wrong duration values for any root with 2+ children where the shorter-duration child is processed last.

Test gaps worth addressing before merge:

• No test for MAX_DEPTH truncation (6-level chain should stop at depth 5)
• No test for build_tree with an unknown root_session_id (should raise KeyError)
• No test for format_tree(expand=False) — the --tree flag path is untested
• test_duration_uses_max_not_sum passes today but only because the single child (3000ms) is less than the root (5000ms) — it doesn't catch the bug above. Add a case where a child exceeds the root duration.

What's good:

• SessionMeta fields are optional with sensible zero defaults — no migration needed
• children_of index built once, not per-node — O(n) not O(n²)
• started_at sort on children gives deterministic ordering
• format_tree correctly threads base_ts through recursive calls so all timestamps are relative to the root session start