ck_budget
Estimate, commit, or track AI operation costs against session and daily spend budgets to prevent budget overruns.
Instructions
Estimate, record, or check the cost of an agent operation against session and daily spend budgets. Three modes: estimate (read-only, returns headroom and projected cost); commit (write — deducts estimated_cost_cents from the session budget); status (read-only, returns remaining budget). For commit mode: pass session_id, estimated_cost_cents, provider, model, input_tokens, and output_tokens. Pass include_token_overhead: true with project_root to attach a token overhead audit (rule files, skill duplicates, tool schemas) to the response. Check ck_budget before expensive multi-agent work or large model calls. Use ck_cost_optimizer for model price comparisons without recording spend.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cached_input_tokens | No | Number of tokens served from cache. | |
| estimated_cost_cents | No | Estimated cost of the operation in US cents. | |
| include_token_overhead | No | When true, attach a token overhead summary (rule files, skill duplicates, tool schemas) to the response. | |
| input_tokens | No | Number of input (prompt) tokens consumed. | |
| metadata | No | Arbitrary key-value metadata for extensibility and audit context. | |
| mode | No | Operation mode that determines the tool behavior and return shape. | |
| model | No | AI model identifier (e.g., gpt-4, claude-sonnet-4.6). | |
| output_tokens | No | Number of output (completion) tokens generated. | |
| project_root | No | Absolute path to project root. Required when include_token_overhead is true. | |
| provider | No | AI provider name (e.g., openai, anthropic, ollama). | |
| session_id | Yes | Unique session identifier for correlating findings, proofs, budget, and audit trail. | |
| source | No | Source system or component that triggered the cost. | |
| task_id | No | Task identifier within the session for scoped operations. | |
| tool | No | Specific tool or operation that incurred the cost. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| decision | No | ||
| headroom_cents | No | ||
| mode | No | ||
| projected_cost_cents | No | ||
| remaining_daily_cents | No | ||
| remaining_session_cents | No | ||
| session_id | No | ||
| token_overhead | No |