What Paperclip's budget caps actually stop

What Paperclip's budget caps actually stop

Paperclip's budget caps stop an agent by pausing the scope once recorded spend reaches the cap. They act on cost events that Paperclip has already written down, so a cap can only stop spend that Paperclip was able to price. This guide reads the mechanism out of the project's own docs and issue tracker as of 13 October 2026, when the newest release was v2026.1012.0 (12 October 2026), then turns the gaps into questions you can answer for your own install.

Paperclip is an open source app for running a team of AI agents with an org chart, issues, scheduled heartbeats and a budget per agent. The repository is paperclipai/paperclip. The project's homepage makes the promise in one line: monthly budgets per agent, and when they hit the limit, they stop. The README is more careful. It describes company, agent and project budgets that track reported spend, raise threshold alerts and pause work at configured limits, and under Budget & Cost Control it states the caveat this guide is about: enforcement uses recorded spend, and usage reporting and in-flight work can delay a stop. The README also describes atomic task checkout: a single assignee and execution locks prevent competing runs from claiming the same task, which is why two heartbeats cannot both start work on the same issue.

What Paperclip counts as spend

Spend reaches Paperclip as cost events. An adapter or an external reporter posts them to POST /api/companies/{COMPANY_ID}/cost-events. The budget how-to walks through posting one, and the costs API reference lists the required fields as agentId, provider, model, costCents and occurredAt, with an optional billingCode for attribution. The costs guide splits the ledger in two. Inference costs are per request and record the agent, the model, input tokens, cached input tokens, output tokens and the cache-adjusted dollar figure. Account level charges such as subscription fees, credit top-ups and refunds do not map to a single request, so they sit in a separate finance ledger.

The default budget metric is billed_cents. That single default decides everything below it: something has to put a dollar figure on a run, because a run with no dollar figure adds nothing to the total the cap is compared against. Tokens are recorded. Tokens are not the metric.

Which scopes a budget policy covers

A policy applies to one of three scopes: the company, a single agent, or a project. A plain monthly cap is a PATCH to /api/companies/{COMPANY_ID}/budgets or /api/agents/{AGENT_ID}/budgets carrying budgetMonthlyCents, in cents. The docs use 10000 for a hundred dollars a month. Richer policies go to POST /api/companies/{COMPANY_ID}/budgets/policies.

{
  "metric": "billed_cents",
  "windowKind": "calendar_month_utc",
  "warnPercent": 80,
  "hardStopEnabled": true,
  "notifyEnabled": true
}

Those are the documented defaults. Company and agent policies default to a calendar month in UTC; a project policy defaults to lifetime, which means the cap never resets on its own. Per-agent caps are enforced independently of the company cap, so an agent at 100 percent pauses even while the company still has headroom. That is the property you want, because it stops one runaway agent from eating everyone else's month.

Warning at 80 percent versus a hard stop at 100

At warnPercent Paperclip records a soft incident. Nothing stops. The agent keeps working and, with notifyEnabled, someone is told. A soft incident is a message, not a control.

The hard stop is hardStopEnabled, on by default. Turn it off and the policy becomes warn-only: it will report every threshold it crosses and prevent nothing. Decide which of the two you have configured before you trust a cap, because the failure looks identical from the dashboard until the month ends.

What happens when an agent goes over budget

When a hard incident fires, the docs describe three consequences. The affected scope is paused immediately. No further heartbeats are scheduled for it. Any in-progress run for that scope is cancelled, and the issue stays where it was rather than being marked done or failed.

Recovery is either the calendar or a human. A calendar-month policy resumes on month rollover. Otherwise you resolve the incident with POST /api/companies/{COMPANY_ID}/budget-incidents/{INCIDENT_ID}/resolve, choosing raise_budget_and_resume or keep_paused. A board operator can also override budget limits directly, which is worth knowing before you hand anyone board access.

Does the cap see a Claude Code subscription run?

A dollar cap only stops spend it can see, so ask the first gap as a question: how does Paperclip record cost for an adapter that authenticates with a subscription rather than an API key, where the provider reports usage instead of dollars? The tracker answers it, and the answers are the project's, not mine.

Issue #339, open since 8 March 2026, states that under Codex CLI subscription authentication Paperclip records cost_cents = 0 for all cost events, because the provider does not return cost for subscription usage, and that this makes budget management useless for those agents. The reporter describes 19.8 million input tokens consumed with nothing enforced.

Pull request #10871, open since 5 August 2026, reports a dashboard tile reading $0.00 with "Unlimited budget" underneath while the same period recorded 38.2M input, 990.9M cached and 8.1M output tokens across 480 runs. The PR's fix is to show weighted token usage for subscription-only periods instead of a dollar figure that cannot move.

Issue #14548, open since 29 September 2026, states that the cost_status column is written but never selected in any read query, so an API response of costCents: 0 cannot be distinguished from an unknown cost. A proven zero and an unpriced model look the same to whatever reads the total.

There is work in flight. Pull request #13379, open since 14 September 2026, adds a subscription_percent metric over provider_session and provider_week windows. It defers queued runs until the provider's window resets instead of pausing the scope. That is a genuinely different control: it caps against the plan's own usage window rather than against dollars, which is the right shape for a flat-rate plan. It was still open on 13 October 2026. Check the metric your policy actually uses rather than assuming your version has this.

Is the budget checked during a long run, or only before it?

The second gap, again as a question the source answers. Paperclip describes the check as preflight: the v2026.626.0 release notes say heartbeats respect preflight budget caps, and the README lists budget checks among the steps of the wakeup queue, ahead of adapter invocation. The costs API reference adds that each accepted cost event triggers spend recalculation and budget policy evaluation. So the check that gates a run happens at its start, and the check that can cancel a run in progress waits for a cost event, which describes work that has already happened.

That leaves one thing to measure: how much a single run can spend between two checks. Issue #14003, open since 25 September 2026, answers part of it for one engine. It states that each heartbeat run records only the token usage of its last model request rather than the sum of all requests in the run, and reports 95 requests on the provider side against 9 cost events in Paperclip, with the fault located in cumulative_token_usage inside the ACP engine. If that is your adapter, the number the next preflight check reads is smaller than what the last run used. Run one agent on a throwaway key for a day and compare the provider's own invoice against Paperclip's total. The difference between those two numbers is the real size of the gap on your install.

What the Implicator AI test of 28 September 2026 reported

Implicator AI published a hands-on test of Paperclip's controls on 29 September 2026, Paperclip Test Finds Agents Can Hire Agents by Default, covering a test it ran on 28 September 2026. The method it describes is stand-in agents that exercised Paperclip without calling an AI model, so the findings are about the software's controls rather than about any model's behaviour.

It reported that a run Paperclip classified as Claude subscription use reported $5.00 and counted $0.00 against a $1.00 cap. It reported that a newly created agent could hire another agent until the owner changed a setting. It reported that Claude Code agents started with permission prompts switched off. Those are Implicator AI's results from a test run on 28 September 2026, and the article itself does not name the version or commit it tested; Implicator's companion Paperclip compendium says it covers stable release 2026.916.1, tested on the same date. Treat them as a prompt to check your own instance, which is the only instance whose defaults matter to you.

What the project has confirmed or fixed as of 30 September 2026

As of 30 September 2026 I found no public statement from the maintainers answering that test. What the project's own records do show is this. The v2026.916.0 changelog of 16 September 2026 records that new standard-trust agents can hire other agents by default, while low-trust agents keep the disabled default, so the hiring behaviour is a documented product decision rather than an oversight. The v2026.831.0 changelog of 31 August 2026 lists that the Grok adapter no longer defaults --permission-mode to dontAsk, which is the same class of default but a different adapter, so it does not address the Claude Code finding.

On the cost side, issues #339, #14003 and #14548 were all open, unassigned and without a maintainer reply when I checked, and pull requests #10871 and #13379 were both open. Nothing there is disputed and nothing there is fixed. Open the five links above before you rely on this section, because a tracker moves faster than a guide.

Rechecked on 13 October 2026: all five were still open, the three issues were still unassigned with no reply from a project member, and I still found no maintainer statement answering the test. Of the releases since, two bear on this guide. The v2026.1001.0 changelog of 1 October 2026 lists as a breaking change that execution harnesses now default to full auto, with native runs defaulting Claude/ACPX to approve-all and the legacy adapters following the same policy. Permission prompts switched off is therefore now the documented default, and its upgrade guide tells you to set an explicit restrictive mode on any agent that must keep provider-side approval gates. The v2026.1012.0 changelog of 12 October 2026 adds a "Check usage" action that reads current provider limits for Codex, Claude, Grok and OpenRouter accounts. That gives you a view of a subscription window, but the changelog lists no change to budget policies or cost events.

Who may create or delegate a task

The second finding is a governance question, not a budget one, and Paperclip has a switch for it. The project's hiring skill sets the requirement to hire at board access or an agent permission of can_create_agents=true. The agents guide describes two routes: a board direct hire through the UI or API, and an agent-requested hire.

The gate is in Settings, then Company, then Hiring: the toggle named "Require board approval for new hires", documented in the hire approvals how-to. With the policy off, an agent-initiated hire goes through immediately. With it on, every hire request from a manager agent creates an agent record in pending_approval plus a hire_agent approval in the queue, carrying the proposed name, role, capabilities, adapter config and budget. Read those four fields before approving. A hire is a new budget scope and a new set of credentials, so it is the cheapest moment to say no.

Spend has a matching gate. An agent posts request_board_approval to POST /api/companies/{companyId}/approvals with a title, a summary, a recommendedAction, a risks array and the issueIds it came from, sets the source issue to blocked, and stops. On resolution the agent is woken with PAPERCLIP_APPROVAL_ID and PAPERCLIP_APPROVAL_STATUS set to approved or rejected. A revision_requested verdict does not fire that wake: the board's note is stored, and the agent only learns of it on its next normal heartbeat, or sooner if someone comments on the source issue. That is the correct default for a spend gate and a nasty surprise for anyone expecting an immediate retry. The general pattern, an action that pauses at a named boundary and resumes only on a recorded human verdict, is worth understanding on its own, and approval gates that make an agent wait for a person before it acts covers how to choose the boundaries so the queue stays small enough that people actually read it.

A board operator can also pause or resume any agent, terminate one, reassign its tasks and override a budget limit. Those powers are the reason board access is not something to hand out to keep a queue moving.

The defences you control outside Paperclip

A cap inside the orchestrator is one layer. Build the others outside it, in this order, because each one holds when the layer above it misreads a number.

1. Set a spend limit in the provider's own console. It is the only cap that sits on the billing account itself, so it holds no matter what any adapter reports or fails to report.
2. Issue one API key per agent. Revoking a single agent then costs one click and does not interrupt the rest, and it is the difference between stopping an agent and stopping the company. The same split applies to every other credential an agent touches, which is the subject of keeping credentials out of an agent's reach in the first place.
3. If you are running agents on a plan rather than on API billing, the plan's own usage window is your real ceiling, and it is measured in usage rather than dollars. Work out which billing mode you are in first with what Claude Code costs on API billing compared with a plan, then read how the two Max tiers differ in the usage each window allows before you assume an agent fleet fits inside one seat.
4. Put limits on the box itself. CPU, memory and process limits stop a loop that no dollar figure has caught yet, and OS level controls for an agent running on your own VPS walks through the ones worth setting.

One closing point on the shape of all this. Paperclip's caps are real controls with a clear mechanism, and the mechanism has one dependency: a priced cost event. When that dependency is met the cap does exactly what the README says. When it is not met, the dashboard shows a confident zero. If you are still choosing a platform, compare how each one meters an agent it did not price, which is the angle a survey of self-hosted agent platforms and a head to head between two agent runtimes are both useful for.

FAQ

Does a Paperclip budget cap stop a Claude Code agent on a Max plan?

Only if something gives that run a dollar figure. Paperclip's default budget metric is billed_cents and it compares the cap against cost events. Issue #339 states that subscription-authenticated runs record cost_cents = 0 because the provider returns usage rather than cost, and it was still open on 13 October 2026. The pending pull request #13379 proposes a subscription_percent metric over the provider's session and weekly windows instead. Check which metric your policy uses, and compare the provider's invoice against Paperclip's monthly total before trusting the cap.

What does Paperclip count against a budget?

Cost events posted to POST /api/companies/{COMPANY_ID}/cost-events, each carrying agentId, provider, model, costCents and occurredAt. Token counts are recorded alongside, but the default policy metric is billed_cents, so a run with tokens and no cost contributes nothing to the total. Subscription fees and credit top-ups are tracked separately in the finance ledger and are not per-request inference cost.

What happens to work in progress when an agent hits its cap?

A hard incident pauses the scope immediately, stops any further heartbeats being scheduled for it, and cancels the in-progress run. The issue stays in the state it was in rather than being closed or failed. A calendar-month policy resumes at month rollover; otherwise resolve the incident with raise_budget_and_resume or keep_paused. A warn-only policy, meaning hardStopEnabled set to false, records the threshold and cancels nothing.

Can a Paperclip agent hire another agent without asking me?

By default in recent releases, yes for a standard-trust agent. The v2026.916.0 changelog of 16 September 2026 records that new standard-trust agents can hire other agents by default, and that low-trust agents keep the disabled default. Turn on "Require board approval for new hires" under Settings, Company, Hiring. Every agent-initiated hire then creates a pending_approval agent record and a hire_agent approval showing the proposed role, capabilities, adapter config and budget before anything runs.