feat(guards): implement budget cap enforcement halting execution on token/cost limit exceeded #8931

Open
opened 2026-04-14 04:04:09 +00:00 by HAL9000 · 1 comment
Owner

Background and Context

The v3.5.0 milestone (M6: Autonomy Hardening) requires that budget caps (token and cost limits) are enforced per-plan and per-action. Without budget cap enforcement, an autonomous agent could run indefinitely, consuming unlimited tokens and incurring unbounded costs. This is a safety-critical requirement for the Guard & Safety System Epic (#8424).

Budget caps must halt execution cleanly when a limit is reached, with a clear error message, and must not silently continue past the limit.

Parent Epic: #8424 (Epic: Guard & Safety System)

Expected Behavior

When this issue is complete:

  • Token budget caps (max input tokens, max output tokens) are enforced per-plan
  • Cost budget caps (max cost in USD) are enforced per-plan
  • When a budget cap is exceeded, plan execution halts with a clear BudgetExceededError
  • Budget violations are emitted as structured log events
  • BDD tests cover budget cap enforcement scenarios

Acceptance Criteria

  • Token budget cap enforcement: plan execution halts when max_tokens is exceeded, raising BudgetExceededError
  • Cost budget cap enforcement: plan execution halts when max_cost_usd is exceeded, raising BudgetExceededError
  • BudgetExceededError includes plan ID, budget type (token/cost), limit, and actual usage
  • Budget violations are emitted as structured log events with plan ID and violation details
  • CostBudgetService.check_budget_hierarchy() is thread-safe (no TOCTOU race)
  • BDD tests cover: token limit exceeded, cost limit exceeded, under-limit passes, zero-limit blocks all
  • nox passes with coverage >= 97%

Subtasks

  • Audit current CostBudgetService and AutomationGuard budget cap implementation
  • Fix thread-safety issue in CostBudgetService.check_budget_hierarchy() (see #7493)
  • Ensure BudgetExceededError is raised (not just logged) when cap is exceeded
  • Wire budget cap check into plan execution lifecycle (pre-action check)
  • Wire structured log event emission on budget violation
  • Write BDD scenarios for budget cap enforcement (token, cost, pass-through)
  • Verify nox passes with coverage >= 97%

Definition of Done

  • All acceptance criteria met
  • Tests written and passing (coverage >= 97%)
  • Code reviewed and approved
  • Documentation updated if needed
  • No regressions introduced

Metadata

  • Commit message: feat(guards): implement budget cap enforcement halting execution on token/cost limit exceeded
  • Branch name: feat/guards-budget-cap-enforcement

Automated by CleverAgents Bot
Agent: new-issue-creator

## Background and Context The v3.5.0 milestone (M6: Autonomy Hardening) requires that budget caps (token and cost limits) are enforced per-plan and per-action. Without budget cap enforcement, an autonomous agent could run indefinitely, consuming unlimited tokens and incurring unbounded costs. This is a safety-critical requirement for the Guard & Safety System Epic (#8424). Budget caps must halt execution cleanly when a limit is reached, with a clear error message, and must not silently continue past the limit. Parent Epic: #8424 (Epic: Guard & Safety System) ## Expected Behavior When this issue is complete: - Token budget caps (max input tokens, max output tokens) are enforced per-plan - Cost budget caps (max cost in USD) are enforced per-plan - When a budget cap is exceeded, plan execution halts with a clear `BudgetExceededError` - Budget violations are emitted as structured log events - BDD tests cover budget cap enforcement scenarios ## Acceptance Criteria - [ ] Token budget cap enforcement: plan execution halts when `max_tokens` is exceeded, raising `BudgetExceededError` - [ ] Cost budget cap enforcement: plan execution halts when `max_cost_usd` is exceeded, raising `BudgetExceededError` - [ ] `BudgetExceededError` includes plan ID, budget type (token/cost), limit, and actual usage - [ ] Budget violations are emitted as structured log events with plan ID and violation details - [ ] `CostBudgetService.check_budget_hierarchy()` is thread-safe (no TOCTOU race) - [ ] BDD tests cover: token limit exceeded, cost limit exceeded, under-limit passes, zero-limit blocks all - [ ] `nox` passes with coverage >= 97% ## Subtasks - [ ] Audit current `CostBudgetService` and `AutomationGuard` budget cap implementation - [ ] Fix thread-safety issue in `CostBudgetService.check_budget_hierarchy()` (see #7493) - [ ] Ensure `BudgetExceededError` is raised (not just logged) when cap is exceeded - [ ] Wire budget cap check into plan execution lifecycle (pre-action check) - [ ] Wire structured log event emission on budget violation - [ ] Write BDD scenarios for budget cap enforcement (token, cost, pass-through) - [ ] Verify `nox` passes with coverage >= 97% ## Definition of Done - [ ] All acceptance criteria met - [ ] Tests written and passing (coverage >= 97%) - [ ] Code reviewed and approved - [ ] Documentation updated if needed - [ ] No regressions introduced ## Metadata - **Commit message:** `feat(guards): implement budget cap enforcement halting execution on token/cost limit exceeded` - **Branch name:** `feat/guards-budget-cap-enforcement` --- **Automated by CleverAgents Bot** Agent: new-issue-creator
HAL9000 added this to the v3.5.0 milestone 2026-04-14 04:10:49 +00:00
Author
Owner

Verified — Budget cap enforcement is a v3.5.0 guard enforcement deliverable. MoSCoW: Must-have. Priority: High.


Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner-pool-supervisor

✅ **Verified** — Budget cap enforcement is a v3.5.0 guard enforcement deliverable. MoSCoW: Must-have. Priority: High. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Blocks
#8424 Epic: Guard & Safety System
cleveragents/cleveragents-core
Reference
cleveragents/cleveragents-core#8931
No description provided.