Shared Budgets and Pools
Let many agents share one budget: a family cap over delegated grants, model calls held at worst case, and pools that buy once.
On this page
A team of agents can share money only if one ledger counts every unit any of them spends. In Chio that ledger is the kernel's hold ledger, the single consumption authority for every budget a grant carries. A coordinator, its delegates, their model calls, and a fleet's purchases all draw down the same durable counter, and every other number an application shows, a swarm pool's allocation table or a dashboard's running total, is a commitment entry or a view computed from it.
The examples continue the Quickstart project. The fixer holds a USD 2.00 grant and delegates model access to the tester, triage, and the reviewer while it works on issue #417.
One hold, written against two ceilings
A model call by the tester reserves its worst case, USD 0.80, in one atomic write: against the tester's own USD 1.00 ceiling and, as a co-debit, against the family's USD 2.00 cap. The call dispatches only after both entries are recorded. Family caps.
A family cap bounds what siblings spend together
Attenuation checks each child against its own parent, one link at a time. Three helpers capped at USD 1.00 under a USD 2.00 parent each pass that check, yet together they promise USD 3.00. The family monetary cap closes the gap: every hold a descendant takes is written against its own ceiling and co-debited against the family cap in the same atomic store write. Reconciliation lowers both entries together, and a reversal before dispatch reverses both.
const authority = fork.grant({
to: fixer,
resources: { "/workspace": ["read", "write"], "/models/default": ["invoke"] },
budget: USD(2),
delegation: { depth: 1, fanout: 3 },
expiresIn: "30m",
});
for (const name of ["tester", "triage", "reviewer"]) {
const helper = await project.agent(name);
authority.delegate({ to: helper, resources: { "/models/default": ["invoke"] }, budget: USD(1), expiresIn: "20m" });
}
const run = await fixer.run("fix issue #417", { on: fork, authority });
for await (const event of run.events()) console.log(event.summary);00:00 admitted fixer runs "fix issue #417" on fork 51c07ae
00:01 delegate tester, triage, reviewer: USD 1.00 each, held from the fixer's USD 2.00
00:04 hold tester model.invoke USD 0.80 worst case, family 0.80 of 2.00
00:09 charged tester USD 0.21, released 0.59, family 0.21 of 2.00
11 more model calls by tester and triage
02:37 refused reviewer model.invoke USD 0.40: family cap, 1.70 + 0.40 > 2.00
spent USD 1.70 of 2.00 across 2 of 3 helpersauthority = fork.grant(
to=fixer,
resources={"/workspace": ["read", "write"], "/models/default": ["invoke"]},
budget=USD(2),
delegation=Delegation(depth=1, fanout=3),
expires_in="30m",
)
for name in ["tester", "triage", "reviewer"]:
helper = project.agent(name)
authority.delegate(to=helper, resources={"/models/default": ["invoke"]}, budget=USD(1), expires_in="20m")
run = fixer.run("fix issue #417", on=fork, authority=authority)
for event in run.events():
print(event.summary)00:00 admitted fixer runs "fix issue #417" on fork 51c07ae
00:01 delegate tester, triage, reviewer: USD 1.00 each, held from the fixer's USD 2.00
00:04 hold tester model.invoke USD 0.80 worst case, family 0.80 of 2.00
00:09 charged tester USD 0.21, released 0.59, family 0.21 of 2.00
11 more model calls by tester and triage
02:37 refused reviewer model.invoke USD 0.40: family cap, 1.70 + 0.40 > 2.00
spent USD 1.70 of 2.00 across 2 of 3 helperslet authority = fork.grant(
Grant::to(&fixer)
.resource("/workspace", ["read", "write"])
.resource("/models/default", ["invoke"])
.budget(USD(2))
.delegation(Delegation::depth(1).fanout(3))
.expires_in("30m"),
)?;
for name in ["tester", "triage", "reviewer"] {
let helper = project.agent(name).await?;
let budget = Grant::to(&helper).resource("/models/default", ["invoke"]).budget(USD(1));
authority.delegate(budget.expires_in("20m"))?;
}
let mut run = fixer.run("fix issue #417").on(&fork).authority(authority).start().await?;
let mut events = run.events();
while let Some(event) = events.next().await {
println!("{}", event?.summary());
}00:00 admitted fixer runs "fix issue #417" on fork 51c07ae
00:01 delegate tester, triage, reviewer: USD 1.00 each, held from the fixer's USD 2.00
00:04 hold tester model.invoke USD 0.80 worst case, family 0.80 of 2.00
00:09 charged tester USD 0.21, released 0.59, family 0.21 of 2.00
11 more model calls by tester and triage
02:37 refused reviewer model.invoke USD 0.40: family cap, 1.70 + 0.40 > 2.00
spent USD 1.70 of 2.00 across 2 of 3 helpersThe reviewer's USD 0.40 fit inside its own USD 1.00, and the kernel still refused it before dispatch, because the tester and triage had already spent USD 1.70 of the family's USD 2.00. Once siblings exhaust the family cap, every descendant is refused, whatever its own ceiling says. Holds and caps are durable, so a kernel restart replenishes neither.
A grant can also divide capacity by share. A child's budget_share_bps is admitted only while its share plus the admitted siblings' shares stays within the parent's 10,000 basis points, a share above 10,000 fails closed, and the sibling registry that tracks admitted shares survives a restart.
Read more in Capabilities and Sub-agent budgets.
A model call holds its worst case and reconciles down
A model call is a priced call like any other and takes the same path. Each call routes through the broker's provider adapter, which reserves the call's worst case (its token limit at the route's price) in the hold ledger before the provider sees the request, then reconciles the hold to the reported usage.
The worst case is held before dispatch
Before a model call leaves the kernel, the hold ledger reserves its worst case against the grant’s USD 2.00 budget: the quoted cost when a quote is present, otherwise max_cost_per_invocation. The call dispatches only after the hold is recorded. Authoritative spend.
USD 2.00 budget, step by step. Amounts are illustrative. Token quotas for subscription harnesses and the provider’s own billing are left out.Budgets and meteringA lost model reply keeps its reservation, and the kernel never sends the request again. Subscription harnesses that bill in tokens instead of dollars draw on a token quota that refuses at exhaustion. Every session of an agent profile draws down one counter, so restarting a harness or opening a second session never issues fresh budget.
Read more in Authoritative Spend and Budgets & Metering.
A fleet buys a finding once, from a signed pool allocation
A swarm working one problem should not buy the same verified fix once per worker. Pool purchasing lets a fleet buy findings under one governed budget. The allocation authority signs a chio.finding.pool-allocation.v1 record that binds the pool, one qualified ledger and its concrete store, one purchaser and key, the currency, a hard amount, a nonce, and a validity window. The kernel verifies the allocation against the installed ledger's binding before it constructs the debit:
chio finding buy --id fnd-01c4…9e17 --max-price 150 --currency USD \
--pool-allocation ./pool-allocation.jsonallocation chio.finding.pool-allocation.v1, USD 4.00 signed for one purchaser ledger qualified sqlite ledger, binding matches the allocation bought fnd-01c4…9e17 at USD 1.20, delivered digest matches the commitment pool USD 1.20 debited, USD 2.80 left in the allocation
The qualifying ledger is durable SQLite. Its binding combines the database's identity with a live proof from a signing identity stored outside it, so a copied database cannot spend the same allocation twice, and two disjoint ledgers derive different bindings. One purchaser per pool and never exceeding the signed amount are hard invariants, and a repeated purchase id returns the original purchase. An in-memory store or an eventually consistent remote view carries no qualifying binding, so no allocation can name it.
Inside the pool, the planner deduplicates requests, buys a finding once, and distributes it to the workers through governed memory writes. The allocation bounds what the pool spends; a purchase made outside the allocation is outside its ledger. Parallel specialists can also split one budget as a swarm pool, whose reservations never exceed its total.
Read more in Cognition Market and Cross-Org Swarms.