Tracing сессий и под-агентов в Braintrust

engineering

braintrust-tracing is a Claude Code skill that documents the architecture for tracing Claude Code sessions in Braintrust, covering span hierarchy, hook event flow, and sub-agent correlation. It maps seven hook types — SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SubagentStop, and SessionEnd — to their roles in building a Session → Turn → LLM/Tool span tree. A key section explains why sub-agents produce orphaned traces: context injected via PreToolUse into Task prompts never reaches the sub-agent's SessionStart, so correlation relies on matching the sub-agent's session_id (captured in SubagentStop) with the orphaned trace's root_span_id. Debugging relies on live log tailing at ~/.claude/state/braintrust_hook.log, per-session JSON state files, and braintrust_analyze.py scripts for listing, replaying, and analyzing sessions.