fix: attribute subagent volume to the model that dispatched it

The tokens report read one model per session transcript (its head, or its tail as a fallback) and pinned every subagent in it to that model. Long sessions switch models with /model, so in a 7d sample 135 of 269 agents were attributed to a model the session was not on when it dispatched them, and the dispatch report - which stamps the model at dispatch time - disagreed with the tokens report about the same window.

Each agent now resolves its session model in this order: the assistant message carrying the tool_use id named by the agent sidecar (in the session transcript, or in the parent agent transcript for nested agents), then the model in effect at the agent transcript's first timestamp (max timestamp <= launch, since a resumed transcript is not in chronological file order), and only then the transcript head/tail as before. The --session filter for main sessions is now per line model, since a switched session no longer belongs wholly to one.

Author: AqueGen

commands/stats.md

@@ -30,14 +30,14 @@ the answer. A dispatch row is one line in a log whether it cost four
 thousand tokens or four million, and only the token report knows which
 model actually ran and how much it processed. Only the dispatch report
 knows what was asked for and what the session model was at that moment -
-it stamps the session at dispatch time, while the token side reads it from
-the parent transcript's head.
+both sides stamp the session at dispatch time - the token side matches each
+agent back to the assistant message that dispatched it.
 
 So when a dispatch-side warning names an agent - a tier leak, or a dispatch
 below its pin - carry its volume from the "By agent" block into the
 sentence. When that volume is not there, say the count overstated it and
 name why: most often an agent from another plugin pinning a model cheaper
 than the session, which the dispatch log cannot see unless that agent is in
-FOREIGN_AGENT_PINS. When the two disagree
-and the window contains a mid-session /model switch, say that instead - the
-token side attributes those subagents to the model the session started on.
+FOREIGN_AGENT_PINS. When the two disagree,
+say that instead - the token side had no sidecar for those agents, or could
+not read the parent transcript.

hooks/dispatch-counter.mjs

@@ -343,9 +343,10 @@ function readSlice(file, bytes, fromEnd) {
 }
 
 function firstModelIn(file, bytes) {
-  // Session-START model: the head of the session jsonl. Used by the tokens
-  // report, which says so in its footer - a /model switch or fallback later
-  // in the session is attributed to the start model.
+  // Session-START model: the head of the session jsonl. The tokens report uses
+  // it only as a LAST resort, when neither the dispatching assistant message
+  // nor the timeline around the agent's first timestamp could name a model -
+  // a /model switch later in the session is invisible to it.
   const m = readSlice(file, bytes, false).match(/"model":"(?:[a-z0-9-]+\.)*(claude-[a-z0-9.-]+)"/);
   return m?.[1] ?? null;
 }
@@ -733,6 +734,75 @@ if (process.argv[2] === "tokens") {
       return m && typeof m.agentType === "string" && m.agentType ? m : null;
     } catch { return null; }
   };
+  // Which model DISPATCHED an agent. Every agent sidecar names the toolUseId of
+  // the Agent tool_use block that spawned it, and that block lives on an
+  // assistant line of the parent transcript whose message.model is the model the
+  // session was on at that moment. Reading it there is what makes this report
+  // agree with the dispatch log, which stamps the model at dispatch time: the
+  // session head answered a different question, and in a 7d sample it gave 135
+  // of 269 agents a model the session was no longer on when it dispatched them.
+  // One read per parent transcript, memoized by path - the walk reaches a
+  // subagents dir BEFORE the parent transcript beside it, and every agent in
+  // that dir shares the same parent, so the index has to be built lazily.
+  const dispatchCache = new Map(); // path -> { ids: Map(toolUseId -> model), timeline: [ts, model][] }
+  const dispatchIndexOf = (file) => {
+    const hit = dispatchCache.get(file);
+    if (hit) return hit;
+    const idx = { ids: new Map(), timeline: [] };
+    dispatchCache.set(file, idx);
+    let text;
+    try { text = readFileSync(file, "utf-8"); } catch { return idx; }
+    for (const line of text.split("\n")) {
+      if (!line.includes('"assistant"')) continue;
+      try {
+        const obj = JSON.parse(line);
+        if (obj.type !== "assistant") continue;
+        const model = obj.message?.model;
+        if (!model) continue;
+        const ts = obj.timestamp ? Date.parse(obj.timestamp) : NaN;
+        if (Number.isFinite(ts)) idx.timeline.push([ts, model]);
+        if (!Array.isArray(obj.message.content)) continue;
+        for (const b of obj.message.content) {
+          if (b?.type === "tool_use" && b.id) idx.ids.set(b.id, model);
+        }
+      } catch {}
+    }
+    return idx;
+  };
+  // The agent transcript's own first timestamp - when it was launched.
+  const launchedAt = (file) => {
+    const m = readSlice(file, 8192, false).split("\n", 1)[0].match(/"timestamp":"([^"]+)"/);
+    const ts = m ? Date.parse(m[1]) : NaN;
+    return Number.isFinite(ts) ? ts : null;
+  };
+  const dispatchModelOf = (p, meta, sessionJsonl) => {
+    if (!sessionJsonl) return null;
+    const idx = dispatchIndexOf(sessionJsonl);
+    if (meta?.toolUseId) {
+      const own = idx.ids.get(meta.toolUseId);
+      if (own) return own;
+      // A nested agent (spawnDepth 2) was dispatched by another AGENT, so its
+      // tool_use line sits in that agent's transcript, not the session's.
+      if (meta.parentAgentId) {
+        const up = dispatchIndexOf(join(dirname(p), `agent-${meta.parentAgentId}.jsonl`)).ids.get(meta.toolUseId);
+        if (up) return up;
+      }
+    }
+    // No sidecar, or a dispatch line this read could not see: the model in
+    // effect when the agent started. MAX timestamp <= launch, not the last
+    // assistant line in FILE order - a resumed session re-appends its history,
+    // so file order is not chronological.
+    const launch = launchedAt(p);
+    if (launch != null) {
+      let best = null, bestTs = -Infinity;
+      for (const [ts, model] of idx.timeline) {
+        if (ts <= launch && ts > bestTs) { bestTs = ts; best = model; }
+      }
+      if (best) return best;
+    }
+    if (!sessionModelCache.has(sessionJsonl)) sessionModelCache.set(sessionJsonl, sessionModelOf(sessionJsonl));
+    return sessionModelCache.get(sessionJsonl);
+  };
   const walk = (dir, depth) => {
     let entries;
     try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
@@ -770,27 +840,29 @@ if (process.argv[2] === "tokens") {
       if (!fileVols.size) continue;
       if (isMainSession) {
         // Scoped by the same --session filter as the agents, so the denominator
-        // always describes the same population as the headline above it.
-        if (!sessionModelCache.has(p)) sessionModelCache.set(p, sessionModelOf(p));
-        const sessionModel = sessionModelCache.get(p);
-        if (sf && !(sessionModel && shortModel(sessionModel).toLowerCase().includes(sf))) continue;
-        mainSessions++;
+        // always describes the same population as the headline above it. Per
+        // LINE model, not per file: agents are attributed at dispatch time now,
+        // so a session that switched mid-way contributes only the volume that
+        // actually ran on the filtered model, and counts as a session only if
+        // any of it did.
+        let matched = false;
         for (const [model, v] of fileVols) {
+          if (sf && !shortModel(model).toLowerCase().includes(sf)) continue;
+          matched = true;
           mainPerModel.set(model, (mainPerModel.get(model) ?? 0) + volOf(v));
           const c = costOf(model, v, priceAt);
           if (c == null) mainUnpricedVol += volOf(v); else mainCost += c;
         }
+        if (matched) mainSessions++;
         continue;
       }
       // The parent session transcript is <session-id>.jsonl, sibling of the
       // first "subagents" dir on the path - one level up for plain Agent
       // dispatches, further up for Workflow agents nested in workflows/<wf>/.
       const anchored = p.match(/^(.*?)[\\/]subagents[\\/]/);
       const sessionJsonl = anchored ? anchored[1] + ".jsonl" : null;
-      if (sessionJsonl && !sessionModelCache.has(sessionJsonl)) {
-        sessionModelCache.set(sessionJsonl, sessionModelOf(sessionJsonl));
-      }
-      const sessionModel = sessionJsonl ? sessionModelCache.get(sessionJsonl) : null;
+      const meta = readMeta(p);
+      const sessionModel = dispatchModelOf(p, meta, sessionJsonl);
       const tsess = tierOf(sessionModel);
       // Accumulated BEFORE the filter returns: --session narrows to the sessions
       // where routing has the most room, so the scoped share is printed next to
@@ -813,7 +885,6 @@ if (process.argv[2] === "tokens") {
       const ss = perSession.get(sessKey) ?? { agents: 0, vol: 0, cmpVol: 0, downVol: 0 };
       ss.agents++;
       perSession.set(sessKey, ss);
-      const meta = readMeta(p);
       if (!meta) metaless++;
       // One transcript is one agent, counted here for the same reason ss.agents
       // is counted outside the per-model loop: a mid-run fallback splits the
@@ -1046,7 +1117,7 @@ if (process.argv[2] === "tokens") {
     ] : []),
     "",
     "Volume = tokens the subagent processed; cache reads are billed at the subagent's model rate, which is where routing saves.",
-    "Session model is read from the head of each session transcript - the model it started on - so a mid-session /model switch or fallback attributes later subagents to the start model (the dispatch report does not have this limit). In a session long enough that its head names no model at all, the tail is read instead and that session is attributed to its LAST model, which is the opposite bias for those sessions.",
+    "Session model is the model of the assistant message that DISPATCHED the agent, matched through the toolUseId in the agent's sidecar - the same instant the dispatch report stamps, so a mid-session /model switch moves both reports together. Without a usable sidecar the model in effect at the agent's first timestamp is used, and failing that the head of the session transcript (or its tail, when the head names no model at all).",
   ];
   process.stdout.write(out.join("\n"));
   process.exit(0);

hooks/dispatch-counter.test.mjs

@@ -975,9 +975,9 @@ test("tokens falls back to the transcript tail when the head names no model", ()
     const out = run(["tokens"], cfg);
     assert.match(out, /opus-5: 1k across 1 agents - 100% below session tier/);
     assert.doesNotMatch(out, /session unknown/);
-    // The footer must admit the tail case: for these sessions the attribution
-    // is the LAST model, the opposite bias from the start-model promise.
-    assert.match(out, /the tail is read instead and that session is attributed to its LAST model/);
+    // The footer must name the fallback ladder that got there: no sidecar, no
+    // usable timestamp, so the transcript head - and here its tail.
+    assert.match(out, /or its tail, when the head names no model at all/);
   } finally { rmSync(cfg, { recursive: true, force: true }); }
 });
 
@@ -1502,3 +1502,87 @@ test("the env-override caveat prints only in a window that contains one", () =>
     assert.match(run(["tokens", "--session", "opus"], cfg), /1 dispatch in it ran under CLAUDE_CODE_SUBAGENT_MODEL/);
   } finally { rmSync(cfg, { recursive: true, force: true }); }
 });
+
+// --- Dispatch-time attribution (sidecar toolUseId -> assistant message) -----
+
+const assistantLine = (model, ts, content, input = 0) =>
+  JSON.stringify({
+    type: "assistant",
+    timestamp: ts,
+    message: { model, content, usage: { input_tokens: input, output_tokens: 10, cache_read_input_tokens: 0, cache_creation_input_tokens: 0 } },
+  });
+const agentUsageLine = (model, ts, input) =>
+  JSON.stringify({ type: "assistant", timestamp: ts, message: { model, usage: { input_tokens: input, output_tokens: 10, cache_read_input_tokens: 0, cache_creation_input_tokens: 0 } } });
+const iso = (msAgo) => new Date(Date.now() - msAgo).toISOString();
+
+test("an agent is attributed to the model that dispatched it, not the session head", () => {
+  const cfg = freshConfigDir();
+  const dir = join(cfg, "projects", "proj", "sess-1", "subagents");
+  mkdirSync(dir, { recursive: true });
+  // The session STARTED on opus and switched to fable before dispatching, the
+  // exact shape that used to send half a real 7d sample to the wrong model.
+  writeFileSync(join(cfg, "projects", "proj", "sess-1.jsonl"),
+    assistantLine("claude-opus-5", iso(3600e3), [{ type: "text", text: "x" }], 5000) + "\n"
+    + assistantLine("claude-fable-5-1", iso(1800e3), [{ type: "tool_use", id: "toolu_1", name: "Agent", input: {} }], 100) + "\n");
+  writeFileSync(join(dir, "agent-a.jsonl"), usageLine("claude-sonnet-5", 1000) + "\n");
+  writeFileSync(join(dir, "agent-a.meta.json"), JSON.stringify({ agentType: "model-routing:scout", toolUseId: "toolu_1", spawnDepth: 1 }));
+  try {
+    const out = run(["tokens"], cfg);
+    assert.match(out, /fable-5-1: 1k across 1 agents/);
+    assert.doesNotMatch(out, /opus-5: \S+ across \d+ agents/);
+  } finally { rmSync(cfg, { recursive: true, force: true }); }
+});
+
+test("a nested agent is attributed through its parent agent's transcript", () => {
+  const cfg = freshConfigDir();
+  const dir = join(cfg, "projects", "proj", "sess-1", "subagents");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(cfg, "projects", "proj", "sess-1.jsonl"),
+    assistantLine("claude-fable-5-1", iso(3600e3), [{ type: "tool_use", id: "toolu_1", name: "Agent", input: {} }], 100) + "\n");
+  // The dispatching tool_use for a spawnDepth-2 agent lives in the DISPATCHING
+  // AGENT's transcript, so the session index alone can never resolve it.
+  writeFileSync(join(dir, "agent-a.jsonl"),
+    assistantLine("claude-sonnet-5", iso(1800e3), [{ type: "tool_use", id: "toolu_2", name: "Agent", input: {} }], 1000) + "\n");
+  writeFileSync(join(dir, "agent-a.meta.json"), JSON.stringify({ agentType: "model-routing:scout", toolUseId: "toolu_1", spawnDepth: 1 }));
+  writeFileSync(join(dir, "agent-b.jsonl"), usageLine("claude-haiku-4-5", 2000) + "\n");
+  writeFileSync(join(dir, "agent-b.meta.json"), JSON.stringify({ agentType: "model-routing:test-runner", toolUseId: "toolu_2", parentAgentId: "a", spawnDepth: 2 }));
+  try {
+    const out = run(["tokens"], cfg);
+    assert.match(out, /sonnet-5: 2k across 1 agents/);
+  } finally { rmSync(cfg, { recursive: true, force: true }); }
+});
+
+test("without a sidecar match, the model in effect at the agent's first timestamp wins", () => {
+  const cfg = freshConfigDir();
+  const dir = join(cfg, "projects", "proj", "sess-1", "subagents");
+  mkdirSync(dir, { recursive: true });
+  // opus first, fable later, and the agent starts between them: the switch
+  // happened AFTER this dispatch, so the tail model must not claim it.
+  writeFileSync(join(cfg, "projects", "proj", "sess-1.jsonl"),
+    assistantLine("claude-opus-5", iso(3600e3), [{ type: "text", text: "x" }], 100) + "\n"
+    + assistantLine("claude-fable-5-1", iso(600e3), [{ type: "text", text: "y" }], 100) + "\n");
+  writeFileSync(join(dir, "agent-a.jsonl"), agentUsageLine("claude-sonnet-5", iso(1800e3), 1000) + "\n");
+  try {
+    const out = run(["tokens"], cfg);
+    assert.match(out, /opus-5: 1k across 1 agents/);
+    assert.doesNotMatch(out, /fable-5-1: \S+ across \d+ agents/);
+  } finally { rmSync(cfg, { recursive: true, force: true }); }
+});
+
+test("--session scopes the main-session denominator per line model", () => {
+  const cfg = freshConfigDir();
+  const dir = join(cfg, "projects", "proj", "sess-1", "subagents");
+  mkdirSync(dir, { recursive: true });
+  // One transcript, two models: attributing agents at dispatch time means the
+  // filter can no longer take or drop a whole switched session at once.
+  writeFileSync(join(cfg, "projects", "proj", "sess-1.jsonl"),
+    assistantLine("claude-fable-5-1", iso(3600e3), [{ type: "tool_use", id: "toolu_1", name: "Agent", input: {} }], 4000) + "\n"
+    + usageLine("claude-opus-5", 8000) + "\n");
+  writeFileSync(join(dir, "agent-a.jsonl"), usageLine("claude-sonnet-5", 1000) + "\n");
+  writeFileSync(join(dir, "agent-a.meta.json"), JSON.stringify({ agentType: "model-routing:scout", toolUseId: "toolu_1", spawnDepth: 1 }));
+  try {
+    const out = run(["tokens", "--session", "fable"], cfg);
+    assert.match(out, /Main sessions \(not routable\): 4k across 1 sessions/);
+    assert.doesNotMatch(out, /opus-5\s+8k/);
+  } finally { rmSync(cfg, { recursive: true, force: true }); }
+});