docs(session): record subagent "latest snapshot wins" tradeoff

ee55b68→main·

suhaanthayyil·4d ago·1 file·+16 added/-1 removed

Document that TokenUsage.SubagentTokens is replaced (not summed): a mid-session main-transcript reset or rotation can make a later cumulative snapshot smaller than an earlier one, so the session-wide subagent total regresses (undercounts) for the rest of the session. This is accepted over the prior multiplicative overcount, and checkpoint deltas are unaffected because CheckpointTokenUsage.SubagentTokens is (cumulative - baseline) floored at zero by clampSubtract.

Changes

1

• cmd/entire/cli/session

• Mstate.go+16/-1

275 unmodified lines

276
277
278
279
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297

275 unmodified lines

// Set from hook data when the agent provides it.
    ModelName string `json:"model_name,omitempty"`

// Token usage tracking (accumulated across all checkpoints in this session)
    // Token usage tracking (accumulated across all checkpoints in this session).
    //
    // DECISION: SubagentTokens is "latest snapshot wins", not summed. Subagent
    // usage arrives as a cumulative-since-session-start total (each subagent
    // transcript is re-read from line 0 every call), so accumulateTokenUsage
    // replaces rather than adds it (see cmd/entire/cli/strategy). Tradeoff: if
    // the main transcript resets or rotates mid-session (compaction writing a
    // fresh file, or a resume that truncates), a subsequent snapshot can be
    // SMALLER than a previous one, so this session-wide total regresses
    // (undercounts) for the rest of the session. This is accepted: undercounting
    // after a transcript reset is preferable to the multiplicative overcount the
    // summing approach produced, and the alternative (a session-wide high-water
    // mark) would mask genuine subagent-transcript cleanup. Checkpoint deltas do
    // not share this exposure — CheckpointTokenUsage.SubagentTokens is derived as
    // (this total - SubagentTokensBaseline) and floored at 0 by clampSubtract, so
    // a shrunk snapshot yields 0, never a negative or stale delta.
    TokenUsage *agent.TokenUsage `json:"token_usage,omitempty"`

// CheckpointTokenUsage tracks hook-provided token usage since the last condensation.

Mcmd/entire/cli/session/state.go+16/-1