Experience-Driven Black-Box Cost Control for Coding Agents
Python agentic-aiagentic-codingai-codingai-coding-assistantanthropicartificial-intelligenceclaude-codecodexcoding-agentcoding-agentscost-optimizationcost-reductiondeveloper-toolsgithub-copilotllmopen-sourceopenaiproductivitytoken-optimization
"""Claude Code's session transcript: tool calls, token usage, subagents, deferred tools.
The interactive transcript uses the same `message.content[]` envelope as `stream-json`, so one
reader serves both. Usage is the difference: the transcript writes ONE ENTRY PER CONTENT BLOCK,
each repeating its message's `usage`, so summing entries over-counts by the number of blocks;
`claude_session_usage` keys by message id. Subagents write their own files under
`<session>/subagents/`, and their tool calls and tokens belong to the session that spawned them.
Only the conversation's own entries (`assistant`, `user`) carry its calls. Claude Code 2.1.300
also writes `api-request-blob` entries that repeat each request's messages, earlier tool calls
and results included; read as calls, every call counted twice.
"""
import glob
import json
import os
from .jsonl import lines as _lines
_CLAUDE_KEYS = ("input_tokens", "cache_read_input_tokens", "cache_creation_input_tokens",
"output_tokens")
CONVERSATION = ("assistant", "user")
def claude_calls(lines):
"""[(name, args, result_text, success, cwd)] for the lines of a Claude transcript: each
`tool_use` block paired with its `tool_result` by id, with the directory the shell was in."""
out, order, seen = [], [], {}
results = {}
for line in lines:
try:
ev = json.loads(line)
except Exception:
continue
if ev.get("type", "assistant") not in CONVERSATION:
continue
msg = ev.get("message") or {}
content = msg.get("content")
if not isinstance(content, list):
continue
for b in content:
if not isinstance(b, dict):
continue
if b.get("type") == "tool_use":
tid = b.get("id")
if tid in seen:
continue
seen[tid] = {"name": b.get("name"), "args": b.get("input", {}),
"cwd": ev.get("cwd") if isinstance(ev.get("cwd"), str) else None}
order.append(tid)
elif b.get("type") == "tool_result":
tid = b.get("tool_use_id")
c = b.get("content")
if isinstance(c, list):
c = " ".join(x.get("text", "") for x in c
if isinstance(x, dict))
results[tid] = (c if isinstance(c, str) else "",
not b.get("is_error", False))
for tid in order:
info = seen[tid]
res_text, ok = results.get(tid, ("", True))
out.append((info["name"], info["args"], res_text, ok, info["cwd"]))
return out
def _is_prompt(ev):
"""Is this entry a prompt the person gave, typed or as a slash command? Its own `user`
entries, less tool results, a local command's output, an interrupt marker, a compaction
summary, the meta text Claude Code adds, and a subagent's."""
if (ev.get("type") != "user" or ev.get("isMeta") or ev.get("isSidechain")
or ev.get("isCompactSummary")):
return False
content = (ev.get("message") or {}).get("content")
if isinstance(content, list):
blocks = [b for b in content if isinstance(b, dict)]
if any(b.get("type") == "tool_result" for b in blocks):
return False
content = " ".join(b.get("text") or "" for b in blocks if b.get("type") == "text")
return isinstance(content, str) and not content.startswith(("<local-command",
"[Request interrupted"))
def claude_prompt_count(transcript_path):
"""How many prompts the person gave a Claude Code session (`_is_prompt`)."""
n = 0
for line in _lines(transcript_path):
try:
ev = json.loads(line)
except ValueError:
continue
n += isinstance(ev, dict) and _is_prompt(ev)
return n
def claude_subagent_files(transcript_path):
"""Subagent transcripts of a Claude Code session: `<dir>/<session-id>/subagents/*.jsonl`."""
if not transcript_path:
return []
stem = os.path.splitext(transcript_path)[0]
return sorted(glob.glob(os.path.join(stem, "subagents", "*.jsonl")))
def claude_session_usage(transcript_path, include_subagents=True):
"""Token breakdown of a Claude Code session, de-duplicated by assistant message id.
Returns the four breakdown fields `pricing.effective_tokens` reads, plus `model` (the most
used one), `requests` (distinct assistant messages carrying usage) and `files` read."""
files = [transcript_path] + (claude_subagent_files(transcript_path)
if include_subagents else [])
by_id, models, anon = {}, {}, 0
for path in files:
for line in _lines(path):
if '"usage"' not in line:
continue
try:
ev = json.loads(line)
except ValueError:
continue
if ev.get("type") != "assistant":
continue
msg = ev.get("message") or {}
usage = msg.get("usage")
if not isinstance(usage, dict):
continue
mid = msg.get("id")
if not mid:
anon += 1
mid = f"anon-{path}-{anon}"
# Later entries of the same message carry the final counts; keep the last.
by_id[mid] = {k: int(usage.get(k) or 0) for k in _CLAUDE_KEYS}
model = msg.get("model")
if model:
models[model] = models.get(model, 0) + 1
out = {k: sum(u[k] for u in by_id.values()) for k in _CLAUDE_KEYS}
out["requests"] = len(by_id)
out["model"] = max(models, key=models.get) if models else None
out["files"] = len([f for f in files if os.path.exists(f)])
return out
def claude_tool_usage(transcript_path, include_subagents=True):
"""{tool: calls} over a session and, by default, its subagents -- a tool a subagent used is
in use, and denying it would take it from the subagent too."""
from .calls import tool_usage
counts = {}
files = [transcript_path] + (claude_subagent_files(transcript_path)
if include_subagents else [])
for path in files:
for name, n in tool_usage(path).items():
counts[name] = counts.get(name, 0) + n
return counts
def claude_deferred_tools(transcript_path):
"""Tool names the session listed as deferred (`deferred_tools_delta` attachments).
Deferred tools cost one listing line each, not a schema, so they matter little to the bill;
they are still part of what the session could call, so the pruning catalog includes them."""
names = set()
for line in _lines(transcript_path):
if '"deferred_tools_delta"' not in line:
continue
try:
att = json.loads(line).get("attachment") or {}
except ValueError:
continue
names.update(n for n in (att.get("addedNames") or []) if isinstance(n, str))
names.difference_update(n for n in (att.get("removedNames") or []) if isinstance(n, str))
return names