Development record

Agents abcd starts on your API key stay within the budget you set

intentdraftsmajoritd-2611011230226453

Press Release

When abcd starts agents on your own API key, it spends only what your budget allows, and it pauses rather than surprising you. Before their first build on a key, Maya sets what abcd may spend in a day, a week and a month, with a command only they can run. Each of their sessions names the one key it uses by the name they gave it in the credential store, and abcd resolves it from the home they chose for it there (the keychain is the one abcd suggests), never from a repository file and never from a value typed into a command. Every agent abcd launches is limited to what is left of their budget, each step shows what each role has spent against each cap, and when a cap is reached the work pauses until the cap resets or they raise it, unless they have chosen to move to a second key they named for that purpose. "I left a drain running overnight on my key," said Maya, an autonomous-development practitioner. "In the morning it had paused at my daily figure and told me which cap it hit. No surprise on the bill, and nothing ran on my subscription instead."

Why This Matters

The first live run of abcd's claude runner on a person's own key (2026-11-01) spent 0.97 USD on one review and 0.33 USD on another, while the run's budget check reported itself skipped because no runner reports a quota. Every route already records the cost it reported (itd-166), but nothing reads it back as a limit, and the runner discards the reported cost of any launch that did not succeed (internal/core/runner/claude.go: a non-success result returns an empty answer), so the launch most likely to overspend is the one whose spend is lost. Today the key reaches the runner only by a person typing it into each command's environment. The product thinker ruled the same day that abcd's agents run on the person's API key by default where a repository is set to that route, so a budget the person sets, and abcd keeps, is the precondition for leaving any work running on a key.

Mechanism

We expect spend to stay within the budget because Claude Code's print mode takes --max-budget-usd and ends an agent whose spend reaches it, and abcd bounds every launch, running ones included, against what remains of the key's caps: each launch's --max-budget-usd is reserved against every cap before it starts, so the bounds handed out never together exceed what remains less a headroom kept for the response that can cross a bound, and a launch held back by reservations is told so, distinct from a cap reached. The spec sets the arithmetic and must bound, and name where it cannot, three residuals, each named in the record when it happens and the first flagged for the product thinker: a response larger than any launch cost recorded before it, a launch whose cost cannot be read, and how many launches may run on one key at once; and a fourth no machine can see when it happens, the same key used by abcd on a second machine, since the store of totals is per machine and each machine's store counts only its own launches, so one key spends up to the cap on each. It would be shown wrong by a period whose recorded spend passes its cap other than through one of those named residuals.

Scope Conditions

Agents abcd launches through the claude runner on the key route, each on a key profile (itd-2611040344170206): a login-less profile with abcd's hooks on, so the guard holds and every such launch is billed per token to the key it is handed. The bare launch adr-2610222222326104 names for the key route gives way for stages (dcn-2611041550129278).
Repositories set to the API route by the person's own setting, and the key a subscription-route repository moves to when a usage window reaches its mark (dcn-2611041550135566): a repository on the subscription route spends no money abcd can see while its stages stay on subscriptions, and the key it names as its fallback is a budgeted key like any other, so naming one needs its budget.
Claude Code versions whose print mode accepts --max-budget-usd and reports total_cost_usd in its result, error results included; an older harness is refused for a budgeted launch rather than run unbounded.
The opencode runner is out of scope here: its cost is summed from its own events and its provider's billing is the person's own arrangement.
Costs are the figures the harness reports, its own estimate of the provider's price; the provider's invoice is the final figure, and abcd says so wherever it shows a budget.
The person's key is a named credential in the credential store, in whichever of its homes they chose for it (adr-2609221017021499): a setup outside abcd the store points at, abcd's own owner-only file, or the platform keychain. The keychain is the home abcd suggests, never a requirement, so a machine with no keychain tool is offered the API route like any other (dcn-2611041550126639).
A cap counts the key across the sessions of one machine: the store of totals is per machine, so the same key used by abcd on a second machine spends up to the cap there too, one of the exceptions the product thinker admitted (dcn-2611041550126639), covered by the provider's own console limit.

Acceptance Criteria

Given a repository on the API route and a session that names a key in the person's machine configuration, when abcd starts a routed role, then it resolves that key by name through the credential store, from the home the person chose for it, and hands it to that launch alone; after the launch no environment variable, argument, file or helper exposes the key, to the agent's own shell included, and nothing else abcd starts carries it. This does not stop an agent spending through the harness itself, which is what the caps bound (dcn-2611041550126639).
Given a session that names no key, or a name the credential store does not resolve, when a routed role is handed out, then nothing is launched on a key, and abcd names the key it looked for, the home it looked in, and the walkthrough that sets it.
Given a launch, when it ends, then the run record names the key it was handed by its configured name (never its value) and the credential source the harness reported.
Given a repository on the API route with no budget set, when a run would start a routed role, then it refuses to start and names the command that sets the budget.
Given day, week and month caps set by the person, when abcd starts a launch, then abcd bounds every launch, running ones included, against what remains of the key's caps: each launch's --max-budget-usd is reserved against every cap before it starts, so the bounds handed out never together exceed what remains less a headroom kept for the response that can cross a bound, and a launch held back by reservations is told so, distinct from a cap reached. The spec sets the arithmetic and must bound, and name where it cannot, three residuals, each named in the record when it happens and the first flagged for the product thinker: a response larger than any launch cost recorded before it, a launch whose cost cannot be read, and how many launches may run on one key at once.
Given a launch that ends, successfully or not, when its result reports total_cost_usd, then that figure is added to the day, week and month totals, which are summed from the launch ledger (itd-2611031342011261), whose retention never falls below the longest cap period plus one day; and given a launch whose cost cannot be read, then it is charged the whole --max-budget-usd it was handed.
Given a cap reached during a run, when the next role is due, then the repository's at-cap setting decides: by default the run waits, resuming when the period resets or the person raises the cap; set to move, it continues on a second key the person named for that purpose; it never hands the role to the host session or the subscription.
Given an agent's session, when it runs the command that sets or raises a budget, sets the at-cap behaviour, or names the second key, then abcd refuses it, and the person's own run of the same command sets it; all three are kept in the person's own machine configuration under ~/.abcd.noindex/, never in a repository file an agent's change can reach, with the same residual as the totals: they are writable by the person's own account.
Given a run, when each step reports, then it shows what each role has spent against each cap, by the key's configured name.
Given several sessions on one machine using the same key, when any of them launches on it, then its spend is added to that key's day, week and month totals in one store every session on the machine reads, so a cap counts the whole key across the sessions of that machine; reaching it pauses every session on that key on that machine together.
Given a key's spend reaching three quarters of any of its caps, when a session using that key next launches or steps, then that session is told from the shared store, naming the cap, the spend and what is left, so every session on the key hears it at its next move.
Given how many launches may run on one key at once, when the person has set no figure, then one launch at a time is the shipped default and the person raises it in their own machine configuration, never a repository file; a key route with a budget set and no figure set is never refused for the figure's absence. (The drafter's own, from the landing reviews of 2026-11-02, under the standing stance that abcd ships a sensible default the person configures, dcn-2611041550129278.)
Given a remainder above zero but below the headroom with nothing running on the key, when a launch is due, then abcd names that state apart from a cap reached and from a launch held back by reservations, says the remainder and the headroom, and says what lifts it: the period's reset, a raised cap, or a smaller largest-recorded response. (The drafter's own, from the same reviews.)
Given any launch abcd makes on a key (a build or drain role, the planning interviewer, the drain's judge, a review abcd starts), when it ends, then its cost is added to the key's totals, so no launch abcd makes goes uncounted; spend on the same key outside abcd's launches (a command a person or an agent runs by hand) is neither counted nor bounded, and the record of totals is writable by the person's own account, which is the residual the person's own console limit covers.

Open Questions

None open. The rulings of 2026-11-01 and 2026-11-02 and the planning interview's two rulings of 2026-11-04 are in the Decisions section.

Decisions

2026-11-01, the product thinker (dcn-2611012123470476): each session names the one key it uses, by the name in the machine configuration, never from a per-command variable. The reading that the key lives in the operating system's secret store alone is replaced by the ruling of 2026-11-04 below.
2026-11-01, the product thinker (dcn-2611012123470476): caps are configurable per day, per week and per month; reaching any one pauses the work and waits, never falls back to the host or the subscription.
2026-11-01, the product thinker (dcn-2611012123470476): a key route with no cap set refuses to start.
2026-11-01, the product thinker (dcn-2611012123470476): a cap is set or raised through a command abcd refuses to agents; a touch to raise it is a later intent.
2026-11-01, the product thinker (dcn-2611012102280663, recorded by another session): every agent abcd hands out runs on the person's API key where the repository is set to the API route, the route being a per-repository choice of the person's with the subscription as the shipped default.
2026-11-02, the product thinker (dcn-2611020715491928): a key's caps count the whole key; every session on that key pauses together at a cap, and spend never passes it. This replaces the 2026-11-01 reading that a limit stops only the session that hit it (dcn-2611012123470476). Because the harness can overshoot its own limit by the response that crosses it, 'never passes' is kept by refusing a launch whose remainder is not above a headroom sized from the largest response recorded on the key; a response larger than any before it is the residual, flagged for the product thinker; the spec keeps this residual and sizes the headroom from recorded launch costs, the only cost the harness reports.
2026-11-02, the product thinker (dcn-2611020715491928): what happens at a cap is a per-repository setting, kept in the person's machine configuration keyed by repository, pausing by default, with moving to a second key named for that purpose as the alternative, and the subscription never (settles iss-2611012148181861).
2026-11-01, the product thinker (dcn-2611012137380016): this draft may be planned unattended overnight through abcd build --auto-plan, after its two plan reviews, and reviewed by them in the morning.
2026-11-04, the product thinker (dcn-2611041550126639): the key is a named credential resolved through the credential store from whichever of its homes the person chose (adr-2609221017021499); the keychain is suggested, not required. The press release, the scope conditions and the first two criteria read so.
2026-11-04, the product thinker (dcn-2611041550126639): spend never passing a cap admits the exceptions the record names (a response larger than any recorded before it, a launch whose cost cannot be read, several launches sharing one key at once, and the same key used by abcd on a second machine); an overrun abcd can see is recorded against the key and named in the run's record, and the provider's console limit is the outer stop. On that ruling adr-2611011231015519 is accepted, and its refinement of decisions 17 and 34 of itd-2610161733316518 is no longer advisory.
2026-11-04, the product thinker (dcn-2611041550126639): the key route and the subscription route compose by one rule. A key at its cap pauses or moves to a second key the person named and never falls to a subscription; a subscription at its usage mark never opens a route the person has not named; both out at once is a wait, never a third route.
2026-11-04, the product thinker (dcn-2611041550126639): the key reaches the harness by a channel the agent's own shell cannot read, proved to work with the harness first; that proof is the plan's first step. Criterion 1 carries it.
2026-11-04, the product thinker (dcn-2611041550129278): a stage on the key route runs on a key profile with abcd's hooks on (itd-2611040344170206), so the first scope condition no longer names the bare launch.

Evidence

2026-11-01, the night run by hand (reported by the session that ran on the second key): the product thinker set a per-key ceiling for the night, with work moving to the second key when the first reached it. Three sessions spent concurrently, two on the main key and one on the second, so one key's cap was shared across sessions and a total kept per session undercounted it. Before moving keys a session had to ask the others what was left, since nothing shared held the figure. Sessions warned each other at about three quarters of the ceiling. Each session tallied cost from its own run states by a hand-written script, so spend outside the build loop went uncounted: the planning interviewer's launch on the main key, and review pairs run by hand through claude --bare in text output, which reports no cost. The per-key store, the warning and the every-launch count above come from this evidence; moving to a second named key at a cap, which the night practised, is captured separately for the product thinker, since their ruling for this intent then was one key per session and a pause at the cap; the at-cap setting ruled on 2026-11-02 now admits it.

Inputs for the spec

The plan's first step proves, with the harness itself, that the key reaches it by a channel the agent's own shell cannot read; nothing else in the plan starts before that proof (the product thinker, 2026-11-04).

The landing reviews of 2026-11-02 tried several exact budget models and found constraints the spec must meet (the two that name a user-visible state or a refusal are criteria above, as the drafter's own, since the reviews are no record):

The harness reports cost once per launch (total_cost_usd on the result), not per response, so any headroom is sized from launch costs, which only makes it more conservative.
A headroom fixed per key and multiplied by the number of launches allowed at once admits only one launch at a time once a cost is recorded; letting several run needs the remainder divided among them, rechecked so the bounds plus their crossing responses stay within the cap.
A launch whose cost cannot be read is charged its whole bound, and the overshoot it may still hide is named as a residual.
The spec says whether a run paused through a weekly or monthly reset stays alive or hands back with its resume time, within adr-2610222222326104's rule for lanes abcd launches, and names the marker that tells an agent's session from the person's for the refusal in criterion 8.

Decomposition

Hand-run four-piece table, 2026-11-01, revised the same evening after two pre-interview reviews (design and feasibility; record discipline) and the product thinker's six rulings on keys and budgets; revised again on 2026-11-04 after the two plan reviews and the planning interview (dcn-2611041550126639).

Part	Kind	Home
resolving the session's named key through the credential store, the budget per day, week and month, the reserved bound of each launch, the pause, the spend shown per role	capability	this intent
abcd's launches spend a person's money only within the budget they set, past it only through the exceptions the record names, and reaching a cap pauses rather than falls back to the host or the subscription	trust rule	adr-2611011231015519 (accepted, dcn-2611041550126639); a brief invariant owed in a change of its own
keeping a failed launch's reported cost, the remainder arithmetic, the key's credential source in the run record, the channel the key reaches the harness by	plumbing	the runner and the build and drain brief chapters
raising a budget only with the person's touch	capability	itd-2611012123486967, a later intent

Verdict: FILE-AS-IS after the revision. Typed links: builds_on itd-166; related_issues iss-2610100913096346 (the budget check that always skips); the ADR refines decisions 17 and 34 of itd-2610161733316518 (confirmed, dcn-2611041550126639); the pause honours adr-2610222222326104's rule that a role with no host to take it is handed back, never run elsewhere. The live proof, every role of a build on the key under a real budget and one step under a deliberately low one, is this intent's grounds, not a criterion.

Audit Notes

Empty. Populated by intent-auditor when intent moves to shipped/.

Grounds

pursued: the product thinker's first priority is efficiency, which asks for far more agents than today running together on keys held under caps (dcn-2611031549087617), and the rulings that bound a key's spend (dcn-2611012123470476, dcn-2611020715491928, dcn-2611041550126639) make the cap abcd's to keep; we expect a run's spend on a key to stay within what its caps allow, and a key's billed spend passing a cap other than through a named exception, or a run stalling at a cap with budget left, would show it wrong

Frontmatter

id	itd-2611011230226453
type	intent
lifecycle	drafts
severity	major

.abcd/development/intents/drafts/itd-2611011230226453-when-abcd-starts-agents-on-your-own-api.md
open on GitHub ↗ · commit history ↗

References1

itd-166A run records what it was actually run withbuilds on

Referenced by4

adr-2611011231015519The launches abcd makes spend a person's money only within the budget they set, past it only through named residualsrelated
iss-2610100913096346The run-start budget check never compares anything today: no shipped runner implements QuotaReporter, so every real run skips the check, and the estimate leaves out fix rounds, so it is a lower bound.related
itd-2611031342011261abcd keeps a per-session ledger of every agent it launchesbuilt on by
itd-2611040344170206Unattended work runs on a named profile, one per way of payingbuilt on by

mentions20

adr-2609221017021499Every external credential abcd holds is named in configuration and kept in one store the person chose; never the harness, never the repository
adr-2610222222326104abcd drives agents with no host session only on the person's own invocation, on the person's own account behind a wall, and hands back what it cannot finish
dcn-26110121022806632026-11-01 — Which route the agents abcd hands out (the implementer, both reviewers, the intent auditor, the drain judge and the planning interviewer) bill is a per-repository choice between the person's subscription and their API key, and the subscription is the default abcd ships. The subscription route is the person's own claude on their subscription: the host session's agents today, and the walled claude CLI dcn-2611011332308128 describes once that is built. The choice is the person's own per-repository setting, in the git-ignored local layer of the configuration order, never a committed repository file, which is still refused a runner route so a clone can never spend the person's key; the machine layer may set it for every repository. abcd offers and explains the choice rather than leaving the person to hand-write a roles block, and writes it only on their yes, so host delegation stays the written default of AGENTS.md's Boundaries. This keeps dcn-2611011332308128's subscription default and adds the per-repository choice; the terminal drive's own route keeps its subscription default (dcn-2611012105401437). While the subscription's weekly budget is near its limit, this repository's own work runs on the API key. It answers the routing default iss-2611012054262885 asks for; how the subscription route itself is walled stays open in iss-2610230716454430.
dcn-26110121234704762026-11-01 — The product thinker ruled on 2026-11-01, for the agents abcd starts on a person's API key: each session names the one key it uses, so spend is attributed per session and a limit stops only that session; abcd finds a named key in the operating system's own secret store (the login keychain on macOS, the Secret Service on Linux); spending caps are configurable per day, per week and per month, and when any one is reached abcd pauses and waits rather than falling back to another route or surprising the person; a key route with no cap set refuses to start, so a budget is always set before money is spent; and a cap is set or raised through a command abcd refuses to agents, with a security-key or fingerprint touch to raise it left to a later intent. These settle the open questions of itd-2611011230226453 and its key-supply rework.
dcn-26110121373800162026-11-01 — The product thinker asked on the night of 2026-11-01 for the key-supply draft itd-2611011230226453 (the person's keys read from the operating system's secret store, one named key per session, and the day, week and month caps ruled the same day) to be planned unattended overnight through abcd build --auto-plan, after its two plan reviews and with every decision recorded, and to be reviewed by them in the morning. The same evening they set a per-key spending ceiling for the night, counted per key across every session from the runner's route receipts: work runs on the main key until its total reaches the ceiling, then the session that passes it switches to the second key and tells the others.
dcn-26110207154919282026-11-02 — The product thinker ruled on the morning of 2026-11-02, in an interview another session relayed and one question put here: the test stages run from one fixed check directory per repository, ~/.abcd.noindex/tests/<root-sha>/, used by one check at a time, so results carry over between worktrees and criterion 1 of itd-2611011325421304 holds for tests that read the tree; a key's budget caps count the whole key, every session on that key pauses together at a cap, and spend never passes it, which replaces the 2026-11-01 reading in dcn-2611012123470476 that a limit stops only the session that hit it; what happens at a cap is a per-repository setting, pausing by default, with moving to a second key the person named for that purpose as the alternative and the subscription never; the terminal interview fix iss-2611011402496418 is lowered to minor so the build loop takes it on the API key, a ruling the product thinker gave directly to the session that records it, in answer to a question it put, which that session's transcript in the person's transcript store carries; and a command agents cannot run that admits one named issue above minor to the build loop is to be built next (iss-2611020305525945). The same morning they confirmed the edited wording of itd-2611011325421304's press release, that a test declared as reading what abcd cannot see always runs, in place of the wording confirmed at its interview.
dcn-26110315490876172026-11-03 — Priorities ruled by the product thinker on 2026-11-03: efficiency comes first, lowering the time, cost and effort it takes to see a pull request through, so that many more agents can work at once on capped API keys. After it, in order of need: work run from the CLI alone; work across several accounts; API work with a way to manage several APIs and routes, one per model if need be; and work with stakeholders, such as live brief editing. Building continues while a release is cut, its pull requests waiting behind the release reservation.
dcn-26110415501266392026-11-04 — The product thinker's rulings on the per-key budget draft itd-2611011230226453, at its planning interview. The API key a session names is a named credential, resolved through the credential store by name from whichever of its homes the person chose (adr-2609221017021499); the keychain is the suggested home, never a required one, so a machine without a keychain tool is offered the key route like any other, and the draft is reworded to say so. Spend never passing a cap admits the exceptions the record names: a response larger than any launch cost recorded on the key before it, a launch whose cost cannot be read, several launches sharing one key at once, and the same key used by abcd on a second machine; an overrun abcd can see is recorded against the key and named in the run's record, and the provider's own console limit is the outer stop past every one of them. On that ruling adr-2611011231015519 is accepted, and its refinement of decisions 17 and 34 of itd-2610161733316518 is no longer advisory. The key route and the subscription route compose by one rule: a key at its cap pauses or moves to a second key the person named and never falls to a subscription, a subscription at its usage mark never opens a route the person has not named, and both out at once is a wait, never a third route. The key reaches the harness by a channel the agent's own shell cannot read, proved to work with the harness first, and that proof is the plan's first step; this binds how the key is handed over and not what an agent spends through the harness, which the caps bound.
dcn-26110415501292782026-11-04 — The product thinker's rulings on the profiles draft itd-2611040344170206, at its planning interview. Every agent abcd starts unattended carries abcd's guard whichever way its work is paid for: a stage on the key route runs on a profile with hooks on, and the bare launch adr-2610222222326104 names for the key route gives way for stages. Each way of paying, a subscription or a named key, is one profile with its own login and its own bare settings; a worktree is where the files are, a profile is who pays and what an agent can reach, and abcd pairs one of each per agent. A subscription's profile needs one login by the person; a key's profile needs none. A session the person starts that runs work unattended off a profile is warned in a line that cannot be missed, never refused. Whether an agent on a profile may reach the machine's other sessions is a setting, off by default. A profile's name is a readable one, never a random string: abcd ships a neutral list, a themed one such as a television series' characters is the person's own in their machine configuration, and a name is fixed at creation and retired once used; this replaces the random names of the draft's fourth decision, and the registry records the name, the tool and the date. abcd ships a sensible default allow-list of tools and a repository configures it within one bound: a repository file may narrow the list, only the person's own machine configuration may widen it, and an agent can never widen it. The same stance settles every open question of that kind, those of the ledger draft itd-2611031342011261 among them: abcd ships a sensible default and the person configures it per repository. The draft's title and scope widen to every way of paying, keys included.
dcn-26110415501355662026-11-04 — The product thinker's rulings on usage windows for unattended work on a subscription, at the planning interview of itd-2611040344170206. An agent already running when a subscription's window crosses 95 per cent finishes its stage there; no stage is checkpointed for the crossing. Either window a tool reports reaching 95 per cent, the short one or the long one, moves the next stage off that subscription. A tool that reports no usage window is used unattended only when no subscription that reports one is free.
iss-2609301519558538Deferred, owed to a person: the live proof of the command-line runner (itd-2609201916056194). Phase 1 and 2 prove every criterion on fake harness binaries only; no ruling admits a live check of the runner (ruling L names the site setup, the API adapter and the decision adapter; H8 lists the three paid-service checks and itd-6's RepoPrompt run), so the intent cannot close. What a person must run: (1) the intent's first proof, criterion 7 live: a ruthless review of a real lane routed roles.ruthless-reviewer.runner=opencode, from a lane the host drives, its return recorded beside a host-run review's and differing only in the route; (2) the claude runner under --bare with --permission-mode dontAsk and --allowedTools, confirming a nested claude does not refuse under an inherited CLAUDECODE, and noting that the headless page (read 2026-09-30) says bare mode never reads OAuth or the keychain, so the claude runner needs ANTHROPIC_API_KEY, a paid API key rather than the person's subscription; (3) opencode run --format json --pure: the event shape (the CLI page does not document it; the adapter assumes step_start/text/step_finish with a sessionID and a part) and whether run mode prompts for a permission, which the timeout bounds and records as a fallback.
iss-2611012148181861On the night of 2026-11-01 the product thinker set a per-key ceiling for the night and had work move to their second key when the first reached it, so three sessions could keep working through the night. Their ruling for the budget intent itd-2611011230226453 the same evening is one named key per session and a pause when a cap is reached. Moving to a second key at a cap is therefore practised but not ruled on as abcd behaviour, and nothing in the record says whether abcd should do it itself.
itd-2610161733316518One task done across a model matrix, re-runnably
itd-2610222215485265abcd drain --drive works through the ledger from a plain terminal
itd-2611011325403127Every landing shows what it cost and the next run's estimate
itd-2611012123486967Raising a spending cap needs the person's touch
spc-2610230813348813abcd-drain-run-from-a-plain-terminal
spc-2611041701500441abcd keeps a per-session ledger of every agent it launches
spc-2611050023402644The launch ledger reaches the status line and a run's own summary
spc-2611051628562376drain-drive-live-proof-and-key-route