ec6f7c150e
Session 4 step 16 — post-hoc enforcement via PostToolUse hook with PAUSED flag, budget-report.sh aggregates spend against window limit. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
46 lines
1.5 KiB
Markdown
46 lines
1.5 KiB
Markdown
# Budget Tracking
|
|
|
|
Post-hoc budget enforcement inspired by Paperclip's budget system.
|
|
|
|
## How it works
|
|
|
|
1. `budget-hook.sh` runs as a PostToolUse hook after every tool call
|
|
2. Each call is logged to `budget/cost-events.jsonl`
|
|
3. After logging, cumulative cost is compared against `BUDGET.md` policy
|
|
4. If soft threshold (default 80%) exceeded: warning to stderr
|
|
5. If hard threshold (100%) exceeded and hard_stop=true: creates `budget/PAUSED`
|
|
flag file, subsequent tool calls are blocked (exit 2)
|
|
|
|
## Why post-hoc, not pre-run?
|
|
|
|
Paperclip uses the same approach. Pre-run budget reservation requires a
|
|
persistent service or lock file coordination. Post-hoc checking is simpler
|
|
and robust enough in practice — the worst case is one extra run before pause.
|
|
|
|
## Cost estimation
|
|
|
|
The current implementation counts events as a rough proxy for cost. For
|
|
accurate cost tracking, you have two options:
|
|
|
|
1. **Admin API** (org accounts only): Query `/v1/organizations/cost_report`
|
|
with an Admin API key (`sk-ant-admin...`). This gives actual USD costs.
|
|
2. **Token estimation**: Parse token counts from Claude's responses and
|
|
multiply by published per-token prices. More accurate than event counting
|
|
but still an estimate.
|
|
|
|
For headless runs, `claude -p --max-budget-usd N` provides a per-run
|
|
budget cap directly in the CLI.
|
|
|
|
## Integration
|
|
|
|
Add to `.claude/settings.json`:
|
|
```json
|
|
{
|
|
"hooks": {
|
|
"PostToolUse": [{
|
|
"matcher": "*",
|
|
"hooks": [{"type": "command", "command": "bash budget/budget-hook.sh"}]
|
|
}]
|
|
}
|
|
}
|
|
```
|