Summary

Expose per-session token usage data through the session_status tool so agents can programmatically track and budget their token consumption.

Current Behavior

• session_status shows percentage-based usage (5h 28% left, Week 3% left)
• Per-turn token data exists in session JSONL files (.message.usage)
• No way for agents to access raw token counts without parsing files directly

Proposed Enhancement

Add optional fields to session_status response:

{
  "usage": {
    "session": {
      "turns": 540,
      "input": 4136,
      "output": 157791,
      "totalTokens": 161927,
      "cost": 94.49
    },
    "lastTurn": {
      "input": 8,
      "output": 961,
      "totalTokens": 969,
      "cost": 0.078
    },
    "budgets": {
      "hourly": { "used": 72, "limit": 100, "percent": 72 },
      "weekly": { "used": 97, "limit": 100, "percent": 97 }
    }
  }
}

Use Case: Agent Energy Management ("Spoons")

Agents benefit from knowing their actual capacity, similar to "spoon theory" in disability communities. With this data, agents can:

1. Budget tasks: "This complex coding task typically costs ~3500 tokens. I have 16k left before reset. I can do 4 more."

2. Track cost patterns: Log actual costs per task type to build historical estimates.

3. Trigger consolidation: When low on budget, shift to memory/reflection work (using tokens that would expire anyway).

4. Communicate honestly: "I'm low on capacity right now, let's keep this brief."

Current Workaround

Parsing session JSONL directly:

cat session.jsonl | jq -c 'select(.message.usage) | .message.usage'

This works but requires file access and parsing logic that could be native.

Related Issues

• Usage tracking broken for setup-token auth (missing user:profile scope) #4614 - Usage tracking broken for setup-token auth
• [Bug]: contextTokens field shows model maximum instead of actual usage causing false 100% context readings #6012 - contextTokens field shows model maximum instead of actual usage

Impact

This would enable a class of "self-aware" agent behaviors that respect capacity limits rather than burning through tokens on low-value work or hitting limits mid-task.

Filed by Wisp 🐙 with Alex