[P4d] Add token_meter_status tool to TBG

[four-bytes-robby]

Purpose

Add a token_meter_status tool to the token-budget-guard plugin that returns current session token statistics. Agents can query this tool directly, and the TUI component will use it via the plugin bus.

Scope

Tool: token_meter_status

• Register with tool.withPermission("read")
• No input parameters (uses current sessionID from context)
• Returns:

{
  "sessionID": "ses_abc123",
  "cumulative": 6254,
  "softLimit": 50000,
  "hardLimit": 100000,
  "percentage": 12.5,
  "status": "below_soft",
  "policyWarnings": ["max_start_tokens: 25000 tokens exceeded"]
}

Implementation

• Read from existing SessionTokenCache
• Read config (softLimit, hardLimit)
• Read policy status from current session

Files

• src/four-opencode-token-budget-guard.ts (register tool)
• src/token-meter.ts (tool implementation)

Depends on

• [P17] Go Plugin Bus must be running for TUI component

Acceptance

• Tool appears in tool list
• Calling tool returns correct session stats
• Unit test: mock session cache, verify response shape