---
cluster: Grid Evolution Swarm
block: 02
subsystem: budget-metering
requires: []
provides:
  - "Budget command spec (/grid:budget)"
  - "Grid Accountant agent"
  - "Budget system technical design"
affects:
  - mc.md (budget gate integration needed)
  - All agent spawns (pre-spawn budget check)
tech-stack:
  added: []
  patterns: ["estimation-based metering", "tiered enforcement", "cost profiles"]
key-files:
  created:
    - commands/grid/budget.md
    - agents/grid-accountant.md
    - docs/BUDGET_SYSTEM.md
  modified: []
commits: []

# WARMTH - knowledge that survives
lessons_learned:
  codebase_patterns:
    - "Commands follow markdown spec format with YAML frontmatter"
    - "Agents have MISSION, RULES, COMPLETION FORMAT sections"
    - "Grid uses .grid/ directory for state and config"
    - "Model tier config stored in .grid/config.json"
  gotchas:
    - "No direct API access in Claude Code - must estimate costs"
    - "Token estimation ~4 chars/token is approximate"
    - "MC has hard context budget of 50% - budget system must be lightweight"
  user_preferences:
    - "TRON-themed visual displays preferred"
    - "End of Line signature on important outputs"
    - "Version locked at 1.7.x"
  almost_did:
    - "Considered direct API metering - rejected because no API access from Claude Code"
    - "Considered per-request billing integration - too complex, estimation works"
---

# Block 02: Budget/Metering System Summary

**One-liner:** Estimation-based cost tracking with configurable budget limits, enforcement thresholds, and usage reporting via Grid Accountant agent.

## Tasks Completed

| Thread | Name | Commit | Files |
|--------|------|--------|-------|
| 2.1 | Research pricing and patterns | - | Web search results |
| 2.2 | Create budget command spec | - | commands/grid/budget.md |
| 2.3 | Create Grid Accountant agent | - | agents/grid-accountant.md |
| 2.4 | Create technical design doc | - | docs/BUDGET_SYSTEM.md |

## What Was Built

### 1. Budget Command (`/grid:budget`)

Full command spec with:
- Status display showing budget limit, usage, and remaining
- `set <amount>` to configure budget limits
- `estimate` for pre-execution cost estimation
- `report` for detailed usage analysis
- `reset` to clear session counters
- `unlimited` to remove limits (with warning)

### 2. Grid Accountant Agent

New agent type that handles:
- **Cost Estimation** - Pre-spawn cost calculation from prompt size and agent profiles
- **Usage Tracking** - Recording spawns and reconciling estimates with actuals
- **Budget Enforcement** - Checking thresholds and blocking/warning as configured
- **Reporting** - Session, historical, and optimization reports

### 3. Technical Design Document

Comprehensive design covering:
- Architecture overview with ASCII diagram
- Estimation algorithms (token estimation, agent profiles, cost calculation)
- Budget enforcement model (thresholds, gates, MC integration)
- Data structures (budget.json schema, spawn records, sessions)
- Reporting formats (session, historical, optimization)
- Integration points (model tier, planning, quick mode, refinement)
- Future enhancements roadmap

## Key Design Decisions

### Estimation-Based Metering

Since The Grid runs within Claude Code without direct API access, we cannot get actual token usage. Instead:

- **Input estimation:** `prompt_chars / 4` (average ~4 chars/token)
- **Output estimation:** Agent type profiles with characteristic ratios
- **Cost calculation:** Published API rates applied to estimates

This provides ~85-90% accuracy for budgeting purposes.

### Tiered Enforcement

| Threshold | Action |
|-----------|--------|
| 0-75% | Normal operation |
| 75-90% | Warning displayed |
| 90-100% | Confirmation required |
| 100%+ | Hard stop (if enforcement=hard) |

### Agent Cost Profiles

Each agent type has characteristic output ratios:

| Agent | Output Ratio | Typical Cost (Opus) |
|-------|--------------|---------------------|
| Planner | 1.3x | ~$1.60 |
| Executor | 1.5x | ~$2.10 |
| Recognizer | 0.6x | ~$1.45 |
| Visual Inspector | 1.25x | ~$1.45 |
| Persona Simulator | 1.4x | ~$1.60 |

### Model Tier Impact

| Tier | Relative Cost | Best For |
|------|---------------|----------|
| Quality (Opus) | 100% | Production, complex work |
| Balanced (Sonnet) | ~60% | Most projects |
| Budget (Haiku) | ~20% | Prototypes, simple tasks |

## Integration Requirements

For full integration, MC needs:

1. **Pre-Spawn Budget Gate** - Check budget before EVERY Task() spawn
2. **Post-Spawn Recording** - Track actual output sizes
3. **Cost Display** - Show estimates during cluster planning
4. **Refinement Integration** - Budget check before spawning swarm

## Deviations from Plan

None - plan executed as specified.

## Next Block Readiness

Budget system is ready for MC integration. Program 6 (updating mc.md) should add:

1. Budget gate check in spawn protocol
2. Cost estimation during planning
3. Budget-aware refinement swarm

## Files Created

1. `/Users/jacweath/grid/commands/grid/budget.md` - Command specification
2. `/Users/jacweath/grid/agents/grid-accountant.md` - Accountant agent
3. `/Users/jacweath/grid/docs/BUDGET_SYSTEM.md` - Technical design document

End of Line.