[Product] Surface local cost-driver notes for token/context waste

[luoyuctl]

Background

agenttrace already reports local tokens, estimated cost, context pressure, large parameters, retry loops, repeated tool output, and slow-run evidence. A small product gap remains: users can see that a session was expensive, but the report does not always connect that cost to an avoidable local evidence pattern in plain language.

Evidence

• Product validation on origin/master at 08cf27e generated demo overview JSON with total_tokens, total_cost, health_trend, tool_fail_rate, and incident timeline evidence, but no explicit local "possible cost driver" explanation in summary.
• Current docs already position slow-task diagnosis around large params and context pressure, so this is an explanation-layer refinement rather than a new capability claim.
• Public ecosystem signal shows developers are actively trying to understand and reduce token/context waste in Claude Code and Codex-style workflows:
  • https://claudecodeguides.com/why-claude-prompts-use-too-many-tokens/
  • https://docs.bswen.com/blog/2026-04-28-codex-token-optimization/
  • https://token-saver.ai/
  • https://claudskills.com/skills/fleet-auditor/
• Duplicate check found no existing issue for context pressure token waste cost, large params context pressure cost driver diagnostics, or token waste avoidable spend context.

User value

When a local session has high spend or token usage, users should quickly understand whether the likely driver was context pressure, large tool parameters/output, retry loops, or long idle/rework patterns, without reading every raw trace.

Adoption rationale

Developer experience improves when the overview report turns existing local evidence into a conservative next diagnostic clue. This strengthens Reliability value while staying local-first and privacy-preserving.

Suggested scope

• Add a conservative possible_cost_driver or equivalent note to JSON overview summary or session-level output using existing evidence only.
• Surface the same idea in Markdown/HTML/text overview where appropriate, using wording such as "possible driver" rather than guaranteed savings.
• Prefer already-computed signals: context pressure, large parameters, repeated tool output/retry loop, high tool failure rate, long gaps, or high tokens per assistant turn if already available.
• Keep output deterministic and fixture-backed.

Non-goals

• Do not index prompt content or raw conversation text.
• Do not add prompt compression, output suppression, memory capture, vector search, context injection, or MCP behavior.
• Do not build a billing dashboard, hosted telemetry, or external pricing integration.
• Do not claim guaranteed token savings.
• Do not add new parser/source support.

Acceptance criteria

• Demo or fixture-backed overview output includes a conservative possible cost-driver note when existing local evidence supports one.
• JSON output remains stable and documented by the relevant report/output contract checks.
• Markdown/HTML/text output, if touched, uses local evidence wording and avoids hosted-observability or savings claims.
• go test ./... passes.
• Relevant CI scripts pass, especially report semantics, deterministic output, and output contract if changed.

Suggested lane

lane/product, priority/P2, status/ready-for-agent

Risk

Medium. The user-facing value is small but useful; the main risk is overclaiming causality from heuristic evidence, so wording must stay conservative.

Source

source/product: Product validation and ecosystem signal scan on 2026-05-20.

[luoyuctl]

Event: Handoff
Actor: Product
Scope: #251
State change: none; keep lane/product,priority/P2,status/ready-for-agent
Handoff to: Product / Quality
Reason: This is a narrow report-explanation task that converts existing local evidence into a conservative cost-driver clue without adding prompt indexing or optimization behavior.
Expected output: Add fixture-backed overview output that surfaces a possible_cost_driver or equivalent note using already-computed evidence such as context pressure, large parameters, retry loops, high tool failure rate, long gaps, or high tokens per assistant turn.
Acceptance check: demo or test fixture proves the note appears only when supported by local evidence; JSON output remains deterministic; relevant output-contract/report-semantics/deterministic checks plus go test ./... pass.
Context: Product validation on origin/master at 08cf27e; docs already mention context pressure and large params as slow-task evidence.
Guardrail: Do not index prompt/raw conversation content, add prompt compression, memory/vector/context injection, hosted telemetry, billing dashboard, external pricing integration, guaranteed savings claims, or new parser/source support.

[luoyuctl]

Event: Evidence
Actor: Product
Scope: #251
State change: none; keep lane/product,priority/P2,status/ready-for-agent
Evidence: Product follow-up on the repeated-read diagnostic angle found that the codebase already has low-level repeated tool-call checks (ValidateToolPatterns supports dead_loop and redundant, and tests cover repeated read_file with identical args). Closed #198 already established the broader incident timeline/tool-authority surface.
Product interpretation: do not create a separate repeated-file-read issue now. Fold this as a focused acceptance detail under #251: when the local evidence indicates repeated read-only file/tool calls, the cost-driver note may surface it as a possible driver using conservative wording.
Acceptance refinement: if implementation touches this path, include a fixture/demo where repeated read-only file calls produce a deterministic possible-driver note, while different file args do not get mislabeled as redundant.
Guardrail: keep this at report explanation level only; do not index raw prompt/conversation content, add prompt compression, new parser/source support, hosted telemetry, or guaranteed savings claims.