ck_budget
Estimate, commit, or check agent operation costs against session budgets. Use before expensive multi-agent work or large model calls to control spending.
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. |