docs(agent): document cumulative-snapshot contract on CalculateTotalTokenUsage

364689f→main·

suhaanthayyil·3d ago·3 files·+27 added/-21 removed

Lift the cumulative-since-session-start subagent contract onto the SubagentAwareExtractor.CalculateTotalTokenUsage interface doc: SubagentTokens is cumulative (agent IDs from the full transcript, each subagent re-read from line 0), not a delta scoped to fromOffset, and callers must replace rather than sum and rescope windows via a baseline. A per-window-delta implementation would silently break the accounting. Shrink the claudecode/factoryaidroid NOTE blocks to one-line pointers at the interface contract, fixing their stale reference to SubagentTokensBaseline (it lives on session.State, not the strategy package).

Changes

3

• cmd/entire/cli/agent

• Magent.go+19/-1

• claudecode

• Mtranscript.go+4/-11

• factoryaidroid

• Mtranscript.go+4/-9

360 unmodified lines

ExtractAllModifiedFiles(transcriptData []byte, fromOffset int, subagentsDir string) ([]string, error)

// CalculateTotalTokenUsage computes token usage including all spawned subagents.
// The subagentsDir parameter specifies where subagent transcripts are stored.
// The subagentsDir parameter specifies where subagent transcripts are stored
// (an empty subagentsDir skips subagent accounting and leaves SubagentTokens nil).
//
// CONTRACT — the returned SubagentTokens is a CUMULATIVE-SINCE-SESSION-START
// snapshot, NOT a delta scoped to fromOffset like the main-agent fields
// (InputTokens/OutputTokens/...). Implementations MUST discover spawned agent
// IDs from the FULL transcript prefix [0,end) — so a subagent spawned before\
// fromOffset is still found (#329) — and re-read each subagent transcript from\
// line 0 on every call. Consequently a subagent's full total repeats on every\
// call after it is first discovered.\
//\
// Callers that accumulate across checkpoints/turns therefore MUST NOT sum\
// SubagentTokens across calls: replace the running total with the latest\
// snapshot, and rescope any window delta by subtracting a previously captured\
// baseline (see accumulateTokenUsage / resetCheckpointWindow and\
// session.State.SubagentTokensBaseline in cmd/entire/cli/strategy, and\
// rescopeSubagentTokensToDeltas in cmd/entire/cli/agentimport for the import\
// path). An implementation that instead returned per-window deltas would\
// silently break that accounting with no compile-time or test signal.\
CalculateTotalTokenUsage(transcriptData []byte, fromOffset int, subagentsDir string) (*TokenUsage, error)\n}

Mcmd/entire/cli/agent/agent.go+19/-1

agentIDs := ExtractSpawnedAgentIDs(fullParsed)\n// Calculate subagent token usage.\n// NOTE: each subagent transcript is re-read from line 0 on every call, so\n// mainUsage.SubagentTokens below is a CUMULATIVE-since-session-start total,\n// not a delta scoped to [startLine, end) like mainUsage's own fields.\n// Callers that invoke this repeatedly across checkpoints/turns (accumulating\n// a running total) MUST NOT sum SubagentTokens across calls or a subagent's\n// full usage gets re-added every time it stays discoverable — replace the\n// running total with the latest snapshot instead, and rescope any\n// checkpoint-window delta by subtracting a previously captured baseline.\n// See accumulateTokenUsage and SessionState.SubagentTokensBaseline in\n// cmd/entire/cli/strategy for the caller-side fix.\n} \n```\n

Mcmd/entire/cli/agent/claudecode/transcript.go+4/-11\n
```\n386 unmodified lines\n\n} 
agentIDs := ExtractSpawnedAgentIDs(fullParsed)\n// NOTE: each subagent transcript is re-read from line 0 on every call\n// below, so mainUsage.SubagentTokens ends up CUMULATIVE-since-session-start\n// rather than a delta scoped to [startLine, end) like mainUsage's own\n// fields. Callers that invoke this repeatedly across checkpoints/turns\n// MUST NOT sum SubagentTokens across calls — replace the running total\n// with the latest snapshot instead, and rescope any checkpoint-window\n// delta by subtracting a previously captured baseline. See\n// accumulateTokenUsage and SessionState.SubagentTokensBaseline in\n// cmd/entire/cli/strategy for the caller-side fix.\n} \n```

Mcmd/entire/cli/agent/factoryaidroid/transcript.go+4/-9