67 lines
3.3 KiB
Markdown
67 lines
3.3 KiB
Markdown
|
---
|
||
|
|
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
|