feat(templates): add budget tracking templates (Paperclip pattern)

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>

scripts/templates/budget/README.md

@@ -0,0 +1,46 @@
+# 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"}]
+    }]
+  }
+}
+```