Make token-waste governance first-class in Claude Code

Problem Statement

Claude Code is very capable, but on real projects I repeatedly see token-wasting behavior patterns that are not isolated bugs:

• Re-reading the same files in one session even when the content is already in context
• Dumping huge shell output into the conversation instead of using rg, head, tail, or narrower selectors
• Retrying the exact same failed command without first changing strategy
• Rewriting large files instead of applying targeted edits
• Reading generated/dependency/cache/lock/media files that should usually be ignored or summarized first

These behaviors make Claude Code more expensive and less reliable, especially on longer codebase tasks. They also create a feedback gap: users can see the waste after the fact in JSONL logs, but Claude Code does not currently provide a first-class loop for turning those observations into future runtime guidance.

Related Existing Issues

This request is related to, but broader than:

• #11008: exposing token usage and cost data in hook inputs
• #15664: additionalContext support for PreToolUse hooks

Those issues focus on hook data and hook context injection. This request is about making token-waste governance a first-class workflow: audit completed sessions, compile recurring waste patterns, and enforce learned guidance in future sessions.

What I Built as a Workaround

I built two local-first projects to study and mitigate this:

1. AIEA

https://github.com/jes614753-sketch/aiea

AIEA audits Claude Code JSONL logs from local projects/**/*.jsonl sessions. It detects patterns like repeated reads, toxic file reads, huge shell output, command death loops, and large edit/write inputs.

1. cc-token-governor

https://github.com/jes614753-sketch/cc-token-governor

cc-token-governor turns audit findings and learned corrections into Claude Code hooks. It uses:

• PreToolUse to warn via hookSpecificOutput.additionalContext or deny repeated failed-command loops
• PostToolUse to track command outcomes
• UserPromptSubmit to inject learned project rules before future prompts
• SQLite state for repeated reads, failed commands, and learned corrections
• Compiled policies such as avoid-repeated-read, stop-death-loop, avoid-large-edit, cap-bash-output, and avoid-toxic-files

The latest version fixes hook shape compatibility and policy runtime behavior:

• v2.0.1: uses hookSpecificOutput.permissionDecision instead of a non-standard decision: "warn"
• v2.0.2: makes compiled toxic-file policies actually receive a runtime toxic_file_path signal

Suggested Workflow

Users can currently combine these tools like this:

1. Run Claude Code normally.
2. Use AIEA to audit the local Claude Code JSONL logs.
3. Compile the findings into .contextignore, CLAUDE.md, and governor-policy.json.
4. Install cc-token-governor hooks.
5. Let Claude Code receive lightweight runtime feedback before it wastes more context.
6. Feed corrected behavior back into the learner so future sessions become smoother.

Product-Level Request

It would be valuable if Claude Code supported this workflow natively:

• Built-in token-waste diagnostics from session logs
• First-class repeated-read, death-loop, huge-output, large-edit, and generated-file detection
• A supported way to compile audit findings into hook policies or project rules
• Hook dry-run/validation tooling so users can test hookSpecificOutput shapes before relying on them
• Better examples for permissionDecision, permissionDecisionReason, and additionalContext
• Optional learned project rules that can be inspected, edited, and applied in future sessions

Why This Matters

Claude Code already has the raw ingredients: JSONL transcripts, hooks, additionalContext, permission decisions, and project-level instructions. What is missing is a polished feedback loop.

If Claude Code can learn from its own prior waste patterns, it can finish tasks more elegantly while reducing token usage and user cost.

The hooks system is powerful, but users currently have to build this governance layer themselves. Making this a native or officially documented workflow would help advanced users and teams run Claude Code more safely, predictably, and cheaply.