vault: session notes 2026-07-08

journal/2026-07-08.md

@@ -11,3 +11,10 @@ tags: [scope/global, type/log]
 /home/jared/Documents/SecondBrain/reference/orchestration-prompting-claude-5-era.md
 /home/jared/Documents/SecondBrain/reference/agent-orchestration-patterns.md
 /home/jared/Documents/SecondBrain/reference/zsh-path-variable-collision.md
+
+## Session — 2026-07-08T13:50:02Z
+
+**Project:** /home/jared/dev/cc-os
+**Reason:** other
+**Vault notes touched:**
+(none)

reference/claude-code-subagent-transcripts-and-token-accounting.md

@@ -0,0 +1,66 @@
+---
+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