| name | budget-gatekeeper |
| description | Token and cost tracking with model tier enforcement |
| argument-hint | <session-context> |
| user-invocable | false |
Budget Gatekeeper
Model Tier Costs
Track usage by tier to monitor cost distribution:
| Tier | Model | Relative Cost | Target Budget Share |
|---|
| heavy | Opus 4.6 | 1.0x (baseline) | ≤ 25% of session tokens |
| default | Sonnet 4.6 | ~0.2x | 60-70% of session tokens |
| fast | Haiku 4.5 | ~0.04x | 5-15% of session tokens |
Budget Tracking
Subagent delegations are automatically logged to artifacts/sessions/delegation-log.jsonl by the SubagentStart and SubagentStop hooks. At each delegation, record:
- Agent name
- Model tier used
- Estimated input/output tokens
- Cumulative session cost estimate
Soft Limits
| Metric | Warning | Hard Limit |
|---|
| Total delegations | 8 | 15 |
| Heavy-tier delegations | 4 | 8 |
| Estimated session cost | $2.00 | $5.00 |
| Single agent turns | 30 | 60 |
Team Mode Limits
When ORCH_TEAMS_ENABLED=true, additional limits apply:
| Metric | Warning | Hard Limit |
|---|
| Active teams per session | — | 1 (CC runtime enforces) |
| Tasks per team | 10 | ORCH_TEAM_MAX_TASKS (default 20) |
| Estimated team session cost | $10.00 | User-confirmed before assembly |
| Teammates per team | — | ORCH_TEAM_SIZE_MAX (default 3) |
Team sessions cost approximately 7x a single session. The team-routing skill presents a cost estimate and requires explicit user confirmation (y) before assembling any team. Log team task completions from delegation-log.jsonl (event: teammate_task_complete) to track team budget consumption.
When a soft limit is hit:
- Report usage to the conductor
- Suggest alternatives (downgrade tier, reduce scope, split into separate sessions)
When a hard limit is hit:
- Pause and present the usage report to the user
- Require explicit approval to continue
Cost Optimization Strategies
- Tier downgrade: Use
default instead of heavy when a task doesn't require deep judgment
- Scope reduction: Break large tasks into phases that can span multiple sessions
- Context management: Use
/compact at milestones to reduce token waste
- Session isolation: Use
/clear between unrelated tasks
- Fast tier routing: Route INSTANT tasks to Haiku instead of Sonnet
Budget Report Format
--- Budget Report ---
Delegations: 5 / 15
Heavy-tier: 2 / 8 (reviewer, security-reviewer)
Default-tier: 3 (implementer, researcher, doc-updater)
Fast-tier: 0
Estimated cost: ~$1.20
Recommendation: On track — no action needed