jared
/
SecondBrain
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
SecondBrain/reference/claude-code-subagent-transc...

3.3 KiB
Raw Blame History

type subtype title summary tags scope last_updated date last_reviewed related source
reference api-integration Claude Code subagent transcripts persist as separate JSONL files with usage token blocks Where Claude Code stores subagent (Agent-tool) transcripts on disk and how to recover per-subagent token spend — parent transcripts contain no sidechain lines, but each subagent gets its own JSONL under <session-id>/subagents/ with a message.usage block per assistant message.
type/reference
tool/claude-code
domain/llm-evaluation
domain/orchestration
global 2026-07-08 2026-07-08 2026-07-08
orchestration-prompting-claude-5-era
running-autoresearch-skill-evals
os-orchestration-ws1-session-audit-results
cc-os

Claude Code subagent transcripts and token accounting

The fact

As of Claude Code circa 2026-07 (verified 2026-07-08 on both an interactive session and a headless claude -p session):

  • The parent session transcript (~/.claude/projects/<flattened-cwd>/<session-id>.jsonl) contains no isSidechain: true lines for Agent-tool subagents — a spawn appears only as a tool_use/tool_result pair (with toolUseResult.agentId / resolvedModel) plus a later <task-notification> text block. Subagent spend is not in the parent file.
  • Each subagent's full transcript IS persisted separately at: ~/.claude/projects/<flattened-cwd>/<session-id>/subagents/agent-<agentId>.jsonl (<flattened-cwd> = absolute cwd with / → -; <session-id> = parent transcript basename without .jsonl). The background-task .output files under the session temp dir are symlinks to these.
  • Subagent transcripts are native-format JSONL: every assistant message carries message.usage (output_tokens, input_tokens, cache_creation_input_tokens, cache_read_input_tokens).

So real per-session token economics are recoverable: main-loop output tokens = Σ usage.output_tokens over the parent file's assistant lines; sidechain output tokens = Σ over */subagents/agent-*.jsonl; main-loop share = main ÷ (main + sidechain).

Why it matters

Any audit or eval that claims to measure delegated-vs-direct token spend from transcripts alone will wrongly conclude subagent spend is unmeasurable if it only looks at the parent file (the cc-os 2026-07-08 Fable economics mini-audit initially did, falling back to a lossy chars÷4 proxy of returned payloads). The subagents/ sibling directory is the primary source. This is what the os-orchestration eval harness A-econ axis is built on (WS4, 2026-07-08).

Caveats:

  • The harness-reported <usage><subagent_tokens> figure in task-notifications can differ substantially from the Σ output_tokens of the subagent transcript (observed 89,246 vs 18,038 on the same agent — the notification figure appears to count more than final-output tokens). For internally consistent comparisons, compute both sides from transcript usage.output_tokens.
  • Directory layout is an undocumented implementation detail — re-verify path pattern after major Claude Code upgrades (last_reviewed above).

Related