エージェントの「出力」コストを正しく測る（usage 複製の二重計上と、thinking が7割という現実）

会話ログを JSONL で保存する AI コーディングエージェント（Claude Code など）で、 出力トークンのコストを集計するときに必ず踏む2つの罠と、そこから導かれる 「品質を落とさない唯一の削減レバー」をまとめた指示書。

実測して分かったこと（ある1台・7日分）:

• 自作のコストダッシュボードが出力トークンを 2.27倍に水増ししていた（19,770k → 実際は 8,834k）
• そのため委譲率が 21.7% と表示されていたが実際は 35.9%
• 出力の 70% が extended thinking（ログに本文が保存されないので按分では見えない）
• 独立したツール呼び出しを2個以上まとめられていたのは 6.1% だけ

---

0. 結論から

1. usage はレコードごとに複製される。message.id で束ねないと出力トークンが2倍以上に膨らむ。
2. thinking は本文が保存されない。按分ではなく「実出力 − 可視ブロック推定」の残差で測る。
3. thinking が7割なら、削るべきは「思考の深さ」ではなく「思考の回数」＝レスポンス数。

---

1. 罠その1: usage がレコードごとに複製される

多くのエージェントは1回のAPIレスポンスを content ブロックごとに複数レコード（行）へ分割して書く。 このとき message.usage を各レコードに丸ごと複製する実装がある。

# まず実物を確認する。message.id ごとの行数と、その中の output_tokens を並べる
cat <ログ.jsonl> | jq -c 'select(.message.usage) | {id:.message.id, out:.message.usage.output_tokens}' \
  | sort | uniq -c | sort -rn | head

実測の分布（7日・1モデル）:

1つの message.id が持つレコード数	件数
1	3,623
2	4,315
3	2,393
4以上	211

そして 複数レコードを持つ 6,980件のうち 6,906件(99%)で output_tokens が全レコード同一だった。 つまり for (row of records) total += row.usage.output_tokens と書くと 2.27倍になる。

検証コード（これを最初に走らせる）

// 同一 message.id 内で output_tokens が同じか違うかを数える
const g = new Map();
for (const row of records) {
  const id = row.message?.id; if (!id || !row.message?.usage) continue;
  if (!g.has(id)) g.set(id, []);
  g.get(id).push(Number(row.message.usage.output_tokens) || 0);
}
let same = 0, distinct = 0, sumAll = 0, sumOnce = 0;
for (const outs of g.values()) {
  sumAll += outs.reduce((a, b) => a + b, 0);
  sumOnce += Math.max(...outs);
  if (outs.length > 1) (new Set(outs).size === 1 ? same++ : distinct++);
}
console.log({ same, distinct, sumAll, sumOnce, inflation: sumAll / sumOnce });

inflation が 1.0 より大きければ、あなたの集計は水増しされている。

正しい集計ルール

• 出力トークン / モデル別内訳 / キャッシュ統計は message.id ごとに1回だけ数える。 同一 id 内で値が食い違う場合（実測1%）は最大値を採る。
• uuid は重複除去に使えない（レコードごとに一意なので全件通ってしまう）。
• ブロックから導く値（編集行数など）は合算のままでよい。 ブロックは複製ではなく 分割されているため、行数は重複しない。ここを一緒に dedupe すると今度は過少になる。

さらに踏みやすい派生の罠

ツール呼び出しの個数もレコード単位で数えてはいけない。 分割されているので どのレコードも tool_use を1個しか持たず、「並列呼び出しは常に0件」と誤判定する。 実際にこれを踏んで「バッチ率0%」という誤った結論を出した。正しくは id で束ねてから数えると 6.1% だった。

---

2. 罠その2: thinking は本文が保存されない

拡張思考（extended thinking）を使うエージェントでは、thinking ブロックがログに 署名だけ、または空文字で保存されることがある。すると:

• ブロックの文字数で出力トークンを按分すると、thinking の取り分がほぼ0になる
• 逆に「thinking しか無いレコード」に出会うと、そのレスポンスの出力を丸ごと thinking に計上してしまう

どちらも実態と合わない。実測では、可視ブロック（text と tool_use の input JSON）から 推定できるトークンは実出力の 28% しかなく、残り72%が本文の無い思考だった。

正しい帰属方法（残差方式）

// message.id 単位で全ブロックを結合したあとに計算する
const visibleEst =
    toolUseBlocks.reduce((s, b) => s + JSON.stringify(b.input ?? '').length / 3.2, 0)
  + textBlocks.reduce((s, b) => s + String(b.text ?? '').length / 3.6, 0);

const thinking = Math.max(0, out - visibleEst);          // ← 保存されない思考の実測推定
const scale = visibleEst > out ? out / visibleEst : 1;    // 推定が実出力を超えたら比例縮小
// text / tool_use にはそれぞれの推定 × scale を割り当てる

これで初めて「thinking が出力の何%か」が言える。実測は 70%（従来の按分表示は34%だった）。

---

3. ここから導かれる削減レバー

thinking が7割を占めるなら、コストは概ね 「1回の思考の深さ」×「思考の回数」 で決まる。そして重要なのは:

thinking は1レスポンスにつき1パス課金される。

だから選択肢は2つある。

手段	コスト	品質
思考の深さを削る（reasoning effort を下げる）	下がる	下がる
思考の回数を削る（レスポンス数を減らす）	下がる	変わらない（往復が減る分むしろ有利）

回数を削る方を選ぶ。 具体的には:

1. 依存関係のないツール呼び出しを1レスポンスにまとめる。 「まず A を見て、次に B を見て」と刻むと、刻んだ回数だけ思考パスが課金される。 実測でまとめられていたのは 6.1% だけだった＝ここに大きな余地がある。
2. まとまった探索は専任のサブエージェントに委譲し、親は1レスポンスで結果を受け取る。 「結果は200字以内・コード本体は含めない」のように返す量を指定するのが要点 （指定しないと親の context が太って [別の指示書のテーマである入力コスト] が悪化する）。
3. 実装本体は定額枠のコード生成 CLI へ出す。 監督役は設計・分解・指示・レビュー・検証に絞る。

計測して続ける

削減を主張する前に、次の2つを定点観測する。

responses        : message.id のユニーク数
batchRate        : ツール呼び出しが2個以上のレスポンス ÷ responses
readOnlyStreaks  : read-only ツール呼び出しが連続した鎖の長さの分布

batchRate が上がり responses が下がっていれば、深さを削らずにコストが下がっている。

自動で気づかせる（任意）

read-only の調査コマンドがN回連続したら警告を出すフックを入れると、刻み癖が可視化される。 実測の鎖の分布は「2回が133本 / 3〜4回が47本 / 5回以上が17本」だったので、 4連続で発火させると週17回程度＝鬱陶しくない頻度になった。

フックを書くときの注意:

• ブロック（deny）ではなく警告に留める。 調査自体は正当な作業なので止めてはいけない。
• 一度警告したらカウンタを0に戻す（毎回出ると読まれなくなる）。
• 状態ファイルはセッションIDをキーにし、古いキーを読み込み時に掃除する。
• 例外時は必ず正常終了させる（フックの失敗でユーザー操作を止めない）。

---

4. 指標を「達成不能な目標」にしない

このやり方で測り直すと、トークン比の委譲率には構造的な上限があることが分かる。 可視の成果物が出力の3割弱しかないなら、実装を100%外部へ出しても トークン比は4割程度で止まる。ここに「50%」という目標を置くと、 達成する唯一の道が 「思考を削る」＝品質を落とす ことになってしまう。

指標は「測りたい行動」と一致させる。 「実装を自分で手打ちしていないか」を見たいなら、トークンではなく 追加・削除された行数の比（外部CLIが書いた行 ÷ 全実装行）で測る方が素直で、 実測でも 64% と現実的な値になった。トークン比は併記して可視化するだけにし、 強制判定には使わない。

---

チェックリスト

• message.id で束ねてから出力トークンを数えているか（inflation を測ったか）
• uuid を重複除去に使っていないか
• 行数などブロック由来の値を誤って dedupe していないか
• ツール呼び出しの個数を id で束ねてから数えているか
• thinking を按分ではなく残差で測っているか
• 削減策が「深さ」ではなく「回数」を狙っているか
• 指標の理論上限を確認し、達成不能な目標を掲げていないか