---
type: reference
subtype: api-integration
title: "Claude Code subagent transcripts persist as separate JSONL files with usage token blocks"
summary: "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."
tags:
  - type/reference
  - tool/claude-code
  - domain/llm-evaluation
  - domain/orchestration
scope: global
last_updated: 2026-07-08
date: 2026-07-08
last_reviewed: 2026-07-08
related:
  - orchestration-prompting-claude-5-era
  - running-autoresearch-skill-evals
  - os-orchestration-ws1-session-audit-results
source: 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

- [[orchestration-prompting-claude-5-era]] — why orchestrator economics need this measurement
- [[running-autoresearch-skill-evals]] — eval loops that consume transcript-derived metrics