[FEATURE] Expose session token usage metrics to AI assistant for session documentation

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

When saving session documentation files (a common workflow pattern), there's no way for the AI assistant to include token usage and cost metrics because this data isn't exposed during the conversation.

Users currently have to:

• Run /cost manually and copy metrics
• Manually append token usage to session files
• Or simply omit this valuable metadata

Proposed Solution

Option 1: System Reminder with Running Totals
Periodically provide token metrics to the assistant via system reminder:
<system-reminder>
Session metrics (updated):

• Input tokens: 45,230
• Output tokens: 12,450
• Total cost: $0.68
• Model: claude-sonnet-4-5

</system-reminder>

Alternative Solutions

Option 2: Environment Variables
Expose metrics that tools can read:
CLAUDE_SESSION_INPUT_TOKENS=45230
CLAUDE_SESSION_OUTPUT_TOKENS=12450
CLAUDE_SESSION_COST_USD=0.68

Option 3: Dedicated Tool
Add a GetSessionMetrics tool that returns current usage data.

Priority

Medium - Would be very helpful

Feature Category

Interactive mode (TUI)

Use Case Example

Session documentation workflow:

Session: Feature Implementation

Date: 2025-11-14
Project: MyProject
Branch: feature/new-thing

Session Metrics

Input Tokens: 45,230
Output Tokens: 12,450
Total Cost: $0.68
Model: claude-sonnet-4-5

Session Summary

...

Additional Context

Benefits

• Automatic cost tracking - No manual copying from /cost
• Session-level budgeting - Track which types of work are expensive
• Workflow optimization - Identify token-heavy patterns
• Historical analysis - Review past sessions for efficiency trends
• Team transparency - Document actual resource usage per feature

Related Issues

• #8861 - Token metrics in status line (terminal display)
• #10164 - Sub-agent token visibility (CLI commands)
• #507 - Non-interactive cost reporting (implemented)

This request differs by focusing on exposing metrics to the AI assistant for documentation purposes, not just displaying them to users.

---
Sources:

• https://github.com/anthropics/claude-code/issues/1109
• https://github.com/anthropics/claude-code/issues/10388
• https://github.com/anthropics/claude-code/issues/8861
• https://github.com/anthropics/claude-code/issues/10164
• https://github.com/anthropics/claude-code/issues/507