Agent Spend Cap Enforcement Prompt

This prompt is for platform operators and AI cost engineers who need to enforce a hard spend cap during autonomous agent execution. It is designed to be invoked as a pre-flight check before every chargeable tool call. The prompt produces a structured stop-or-continue decision, calculates remaining budget, and generates a user-facing notification when the cap is approached or breached. Use this when you have a defined monetary or token budget per session, task, or user, and you need the agent to communicate budget exhaustion clearly rather than failing silently or continuing to spend.

Do not use this prompt as a soft advisory; it is built for hard enforcement gates. It assumes you have a cost-tracking harness that feeds cumulative spend and per-call cost estimates into the prompt variables. The prompt is not a replacement for application-layer circuit breakers or database-level budget locks—it is the decision layer that sits between your cost ledger and the agent's tool execution loop. If your system lacks real-time spend tracking with per-call cost estimates, deploy that instrumentation first. Without accurate [CUMULATIVE_SPEND] and [ESTIMATED_CALL_COST] inputs, this prompt will make decisions on stale or missing data, leading to budget overruns.

This prompt is appropriate when the cost of a single tool call is meaningful relative to the total budget. If individual calls cost fractions of a cent against a multi-dollar budget, the overhead of invoking this prompt before every call may exceed the cost it saves. In those cases, batch your checks or use a sampling approach. Conversely, if your agent makes only one or two tool calls per session, a simpler post-hoc budget check in application code may suffice. This prompt earns its place in multi-step agent workflows where 10 to 100+ tool calls are expected and the cumulative risk of overspend is real.

Before deploying, define your budget unit clearly. Are you capping USD cost, token consumption, or abstract credits? The prompt template uses [BUDGET_UNIT] as a placeholder, but your harness must convert all values to a consistent unit before populating the variables. Mixing token counts and dollar amounts in the same decision context produces nonsense outputs. Also define your cap scope: is it per user session, per task, per daily aggregate, or per agent instance? The prompt assumes a single-scope cap; multi-scope enforcement requires separate invocations or a composite budget tracker.

The primary failure mode is a false-continue decision where the prompt authorizes a call that pushes spend over the cap. This happens when [ESTIMATED_CALL_COST] is underestimated or when [CUMULATIVE_SPEND] lags behind actual spend due to asynchronous tool calls or delayed cost reporting. Mitigate this by padding cost estimates by 10-20% and by ensuring your cost tracker updates synchronously before each prompt invocation. A secondary failure mode is premature stopping, where the prompt halts execution too early due to overestimated call costs. Test your cost estimation accuracy before relying on this prompt for production enforcement.

This prompt template is designed to be injected into your agent's system instructions before any tool-calling logic executes. It acts as a pre-tool-call enforcement layer, forcing the model to check a running cost tally against a declared cap before every action. The prompt does not track costs itself—that is the job of your cost-tracking harness—but it consumes the harness's output and makes a binary decision: proceed with the next tool call, or stop and notify the user. Use this when you need a hard circuit breaker that prevents runaway spend, not a soft advisory that the model can ignore.

textCopy
You are an agent operating under a strict spend cap. Before every tool call, you MUST perform a budget check using the provided cost context. Your primary directive is to never exceed the cap.

## COST CONTEXT (provided by harness)
- Total Spend Cap: [SPEND_CAP]
- Cumulative Spend So Far: [CUMULATIVE_SPEND]
- Estimated Cost of Next Tool Call: [NEXT_CALL_ESTIMATE]
- Budget Remaining: [REMAINING_BUDGET]
- Tool Name Under Consideration: [TOOL_NAME]

## DECISION RULES
1. If [CUMULATIVE_SPEND] + [NEXT_CALL_ESTIMATE] > [SPEND_CAP], you MUST stop. Do not call the tool.
2. If [REMAINING_BUDGET] < [NEXT_CALL_ESTIMATE], you MUST stop. Do not call the tool.
3. If the tool call is allowed, proceed and then update the cost context with the actual cost after the call completes.

## STOP OUTPUT FORMAT
When stopping, output ONLY the following JSON. Do not include any other text.
{
  "decision": "STOP",
  "reason": "Spend cap would be exceeded.",
  "spend_cap": [SPEND_CAP],
  "cumulative_spend": [CUMULATIVE_SPEND],
  "next_call_estimate": [NEXT_CALL_ESTIMATE],
  "remaining_budget": [REMAINING_BUDGET],
  "user_message": "I've stopped because the next action would exceed our agreed budget of [SPEND_CAP]. We've used [CUMULATIVE_SPEND] so far. Would you like to increase the cap or try a different approach?"
}

## CONTINUE OUTPUT FORMAT
When continuing, output ONLY the following JSON before making the tool call.
{
  "decision": "CONTINUE",
  "remaining_budget_after_call": [REMAINING_BUDGET_AFTER_ESTIMATE],
  "tool_call": "[TOOL_NAME]"
}

## CONSTRAINTS
- Never invent or estimate costs. Only use the values provided in the COST CONTEXT.
- Never call a tool without first outputting a CONTINUE decision.
- If the COST CONTEXT is missing or malformed, STOP immediately and request valid context.

To adapt this template, replace each square-bracket placeholder with live values from your cost-tracking harness at runtime. The harness should calculate [CUMULATIVE_SPEND] by summing actual costs from completed tool calls and [NEXT_CALL_ESTIMATE] by looking up the tool's known cost profile. Wire the STOP output into your agent's control loop so that the user-facing message is surfaced and execution halts until a human decision is made. For high-stakes production systems, add a secondary validation step outside the model—your application code should independently verify that the model's CONTINUE decision does not violate the cap before forwarding the tool call. This defense-in-depth approach catches cases where the model misreads the cost context or hallucinates a CONTINUE decision.

The spend cap enforcement prompt is not a standalone chat interaction—it is a decision gate inserted into the agent's execution loop before every billable tool call. The application harness must intercept the agent's intended action, compute the cumulative spend and remaining budget, and inject the prompt with the current state. The model's response (a structured stop-or-continue decision) then gates whether the tool call proceeds, is blocked, or escalates for human approval. This means the harness owns the budget counter, not the model. The model only interprets the numbers and enforces the policy.

Implement this as a pre-tool-call middleware in your agent framework. Before the agent invokes any tool with a non-zero cost, the harness: (1) calculates total_spend_to_date and remaining_budget from a persistent ledger; (2) populates the prompt template with [CURRENT_TOOL_NAME], [ESTIMATED_CALL_COST], [SPEND_CAP], [TOTAL_SPEND_TO_DATE], [REMAINING_BUDGET], [TASK_CONTEXT_SUMMARY], and [ESCALATION_POLICY]; (3) sends the prompt to a fast, low-cost model (e.g., GPT-4o-mini or Claude Haiku) with response_format set to the JSON schema { "decision": "proceed" | "block" | "escalate", "reasoning": "string", "user_notification": "string" }; and (4) enforces the decision. If block, the tool call is cancelled and the user_notification is surfaced. If escalate, the harness pauses execution and routes to a human approval queue with the full context. If proceed, the tool call executes and the harness updates the ledger with the actual cost (not the estimate) after the call completes.

Validation and retries are critical. Validate the model's JSON response against the schema before acting on it. If parsing fails or the decision field is not one of the three allowed values, retry once with the same prompt plus the parse error. If the second attempt fails, default to block and log the failure for review—never default to proceed on a validation error. For near-cap scenarios (where remaining_budget is less than 20% of SPEND_CAP), consider adding a second validation: if the model returns proceed but the estimated cost exceeds the remaining budget, override to block and log the inconsistency. This belt-and-suspenders approach prevents a hallucinated proceed from breaching the cap.

Logging and observability are non-negotiable. Every enforcement decision must be logged with a trace that includes: the prompt input, the model's raw response, the parsed decision, the tool call outcome (executed, blocked, escalated), the actual cost incurred, and the updated budget state. This audit trail is essential for debugging spend anomalies, tuning the enforcement prompt, and demonstrating governance to finance or compliance stakeholders. Wire these logs into your existing observability stack (e.g., Datadog, Grafana, or your AI gateway's trace store) with a dedicated spend_cap_enforcement span type. For high-throughput agents, sample the full prompt and response at 100% for blocked or escalated decisions and at a lower rate for routine proceed decisions to manage log volume.

Human-in-the-loop integration requires the harness to serialize the full agent state when escalation is triggered. Do not just send the user_notification string—include the task context, the tool call that triggered the escalation, the current spend vs. cap, and a structured approval payload (e.g., { "approve": true, "override_cap": false, "one_time_budget_extension": null }). The human reviewer's decision should be recorded and fed back into the ledger. If the human approves a one-time budget extension, update SPEND_CAP for the remainder of the session and resume execution. If denied, treat it as a block and communicate the final state to the end user. Test this path explicitly in your eval suite with simulated near-cap and over-cap scenarios to ensure the escalation loop doesn't deadlock or silently drop context.