Cost Envelopes: The Pattern That Saved Us $40k

The Problem

Pick the version that's yours.

TEAM: You shipped an agent doing PR review across your dev team. $0.30/review in QA. The team was happy, finance was happy, you went home Friday. Tuesday morning: $11,400 on your Anthropic key in 36 hours from one tool-call loop.

SOLO: You shipped one ticket-triage agent for your two-person startup. $0.30/ticket in testing. You felt good about the math. Tuesday morning: $4,800 from a single ticket thread the agent kept “clarifying” overnight.

BOT: You shipped customer-facing AI completing invoice line items. $0.02/completion in QA. You shipped to all 12,000 users on Monday. Tuesday morning: a Substack post brought 200 new signups, three of them used your AI as a personal assistant, and your monthly margin is now -180%.

Then Monday's invoice arrived. Three modes, one failure: cost was a runtime constraint and you didn't enforce one.

The Core Insight

Cost is a runtime constraint, not a model-pick decision. The cheapest agent is the one with a hard ceiling.

Most teams treat cost as a model-selection problem (“Sonnet vs Opus”) or a context-shaping problem (“trim the prompt”). Both matter. Neither saves you when an agent loops.

The pattern that saves you is a cost envelope attached to every task: a hard token budget, a hard wall-clock budget, and an attribution tag. When the agent hits either limit, the harness kills it — before the model gets a chance to reason about whether it should keep going. The whole point is to make cost discipline a non-negotiable runtime check, not a polite suggestion the agent might honour if it remembers.

The Walkthrough

1. Define envelopes per task type

Three tiers cover most workloads. Pick the smallest tier that's plausibly enough; don't default to large. The token cap is on the sum of input + output across the whole task (every retry, every tool round-trip, every reflection step). Wall-clock is from task-start to forced-stop; the agent doesn't get to negotiate.

If a task wants more than Large, that's not a bigger envelope — that's a different shape of work. Break it up, hand each piece its own envelope, aggregate the results.

2. Track running spend in a per-task ledger

Don't trust the agent to track its own spend. Track it in your harness, in storage you control. The minimum schema:

-- one row per task, updated on every API call
CREATE TABLE agent_task_ledger (
    task_id      uuid PRIMARY KEY,
    tier         text NOT NULL,        -- 'small' | 'medium' | 'large'
    token_budget bigint NOT NULL,
    tokens_used  bigint NOT NULL DEFAULT 0,
    wall_budget  interval NOT NULL,
    started_at   timestamptz NOT NULL,
    state        text NOT NULL,        -- 'running' | 'killed' | 'done' | 'escalated'
    -- attribution
    team_slug    text NOT NULL,
    project_slug text NOT NULL,
    user_id      uuid,
    -- metadata
    cause_kind   text,                 -- 'pr_review' | 'cron' | 'webhook' | ...
    cause_id     text                  -- the PR number, cron name, webhook id
);
CREATE INDEX ON agent_task_ledger (team_slug, started_at DESC);

Every API call goes through middleware that updates tokens_used in the same transaction as the call's bookkeeping. No middleware bypass; no “just for this one call.”

3. Hard-stop when the envelope is exhausted

The middleware checks the envelope before dispatching the call and after the call returns. If either check fails, the task transitions to killed and a BudgetExceededError bubbles up to the harness. The agent doesn't get another turn.

// before each call
async function dispatch(task, request) {
    const ledger = await loadLedger(task.id);
    if (ledger.state !== 'running') {
        throw new BudgetExceededError(`task already ${ledger.state}`);
    }
    if (ledger.tokens_used >= ledger.token_budget) {
        await markKilled(task.id, 'token_cap');
        throw new BudgetExceededError('token cap hit');
    }
    if (Date.now() - ledger.started_at > ledger.wall_budget_ms) {
        await markKilled(task.id, 'wall_clock');
        throw new BudgetExceededError('wall clock hit');
    }
    const response = await anthropic.messages.create(request);
    await chargeTokens(task.id, response.usage.input_tokens + response.usage.output_tokens);
    return response;
}

Kill fail-closed. If the ledger is unreachable, the task does not get to call out — you'd rather lose a task than guess at budget state. The retry path is for the harness, not the agent.

4. Attribution tags on every call

Every API call carries metadata that maps it back to a task, team, project, and human. This is non-optional — it's how you answer the “whose budget is this agent burning” question without parsing logs after the bill arrives.

// every API call attaches metadata
const response = await anthropic.messages.create({
    model: 'claude-sonnet-4-7',
    max_tokens: 4096,
    messages,
    metadata: {
        user_id: `task:${task.id}`,        // shows in Anthropic console
    },
    extra_headers: {
        'X-PB-Task':    task.id,
        'X-PB-Team':    task.team_slug,
        'X-PB-Project': task.project_slug,
        'X-PB-Tier':    task.tier,
        'X-PB-Cause':   `${task.cause_kind}:${task.cause_id}`
    }
});

The headers are for your own observability stack (you log them on every request, see Module 19). The metadata.user_id field is the one Anthropic's console actually shows — using task:<uuid> as the value lets you grep the console for a specific task without leaking real user IDs into Anthropic.

5. Escalation: the agent can ask, you decide

Some tasks legitimately need more. A migration the harness scoped as “Medium” turns out to need 8M tokens because the codebase grew. You don't want to hard-fail in that case — but you don't want the agent to silently extend itself either.

The escalation path: when the agent is within 10% of an envelope, it emits a structured request (a tool call to your harness, not a chat message to a human). The harness pages an on-call human or a team channel with one click to approve, deny, or upgrade tier. Approved escalations are logged with the approver's identity — the audit trail matters when the same agent escalates three times in a week.

Five Anti-Patterns

Each of these has cost a real team real money. Named, so they're easy to call out in code review.

The Decision Tree: When NOT to Apply This

Cost envelopes are non-negotiable for autonomous, multi-call agents. They're overkill or counter-productive in three situations:

• One-off interactive use — a developer running claude CLI by hand. The human is the budget; envelopes here just add friction. (The org-level Anthropic budget still catches genuine misuse.)
• Trusted single-shot calls — a chat-completion endpoint that takes a prompt, returns one response, has no tools, no retries, no loop. The cost is bounded by the prompt and max_tokens; an envelope adds bookkeeping with no upside.
• Local-only sandboxes — running against a local model where the “budget” is your laptop's GPU time. Different problem, different solution.

Everywhere else — anything autonomous, anything with a tool loop, anything that runs on a cron, anything that gets triggered by a webhook — envelopes are how you sleep at night.

War Story: The PR-Review Agent That Read One File 4,200 Times

The thing that makes this story unremarkable is that everyone who runs autonomous agents has a version of it. It's not a sign of bad code or bad agents — it's a sign that the failure surface for autonomous tool-using systems is wider than “is the prompt good.” Envelopes are how you contain the blast radius of bugs you haven't found yet.

What to Build First

If you're starting from zero, the order that actually ships:

1. Ledger table + middleware (1–2 days). Just the schema, just the per-task token counter, just the hard-stop on cap hit. No tiers yet, no escalation, just one fixed envelope.
2. Tier definitions (half a day). Pick three tiers, assign each existing task to one. Resist the urge to add a fourth tier; resist harder the urge to skip tiers and treat each task as bespoke.
3. Attribution headers (half a day). Tag every call. Make the headers required in the middleware — missing tag = call rejected.
4. Wall-clock cap (half a day). Add the timestamp check. This catches the loops that sip slowly enough that they evade the token cap (yes, this happens).
5. Escalation path (1 day). Slack webhook + approve/deny/upgrade buttons. Don't bother with a full UI yet; the buttons in chat are enough.
6. Dashboard (1 day). Top 10 burners last hour. Top 5 teams this week. P99 task spend. Everything else can wait.

That's a week. After that you're spending less time on cost than you were before, and you can stop watching the Anthropic console. The pattern is doing the watching.

// for customer-facing AI features where cost varies per user, see 1.3 Unit Economics for BOT mode.