Codex 0.151 Subagent Token Budget Checklist

Codex 0.151 subagent token budgets: make nested workers count toward the root goal

Quick answer

OpenAI released Codex rust-v0.151.0 on August 29, 2026. One fix changes how a persisted goal measures work: token usage from spawned descendants, including nested subagents, now rolls into the root goal's token budget.

This closes an accounting gap, not every delegation risk. A root goal still needs an explicit positive token_budget; concurrency, repeated work, tool side effects, provider billing, and account-level usage limits remain separate controls. The practical rollout is to create one bounded root goal, observe it with get_goal, and prove that child and grandchild deltas appear exactly once across active work, idle periods, runtime unloading, goal replacement, and concurrent checkpoints.

The official tag resolves to commit 78c290807ce710180111df227df3b7a4fe845452. The merged implementation PR is #41183, commit 4761851ff35c4ebdd35eb8801e1180a0a50fef60. This article separates those confirmed release facts from the operational checks you should run in your own environment.

Who this is for

This guide is for developers running multi-agent Codex tasks with a root agent that spawns reviewers, researchers, testers, or nested workers. It is especially useful when you want a task budget to cover the whole agent tree rather than only the root conversation.

If your main problem is controlling simultaneous workers, use the separate Claude Code subagent concurrency budget checklist. If your problem is assigning ownership between subagents, jobs, and workflows, see the DeepSeek Harness delegation guide. This page is specifically about Codex persisted-goal token accounting.

What 0.151 changed

Confirmed behavior	Why it matters	Verification target
Child and grandchild usage rolls up	A nested worker cannot remain invisible to the root goal ledger	Root tokens_used includes both levels
Active and idle progress both account descendants	Child work can be charged while the root is waiting	An idle checkpoint still advances usage
Goal replacement resets the descendant baseline	Work from a completed goal should not leak into the next goal	New goal starts from its own delta
Per-thread checkpoints are serialized	Two tool completions should not double-charge the same delta	Concurrent finishes preserve, but do not duplicate, usage
Parent runtime unloading does not break roll-up	A surviving grandchild still belongs to the root tree	Usage arrives after the parent runtime stops

The tagged source calculates goal usage as uncached input tokens plus output tokens. Cached input is subtracted; the goal counter is therefore not the same field as raw total tokens. The implementation stores a cumulative descendant counter, takes deltas against the last accounted baseline, and adds those deltas to root-turn progress.

Keep four budgets separate

Limit	What it governs	What 0.151 does not promise
Root goal token budget	Persisted work budget for one explicit goal	It does not exist unless a positive budget is requested
Model context window	Tokens available to a model call	It is not enlarged or replaced by goal accounting
Account or provider quota	Product-level usage allowance	The release does not redefine weekly or plan usage
Financial/tool budget	API spend and external side effects	Token accounting does not cap invoices, writes, or deployments

Treat BudgetLimited as a goal-runtime state, not proof that every already-running action was cancelled. The tagged tests show that a budget-limited goal can continue accounting usage until the turn stops. Your outer orchestrator should therefore stop new fan-out, let in-flight work reach a safe boundary, and verify the terminal state.

A six-stage rollout

1. Pin the tested build

Record the Codex version, tag commit, collaboration mode, root thread ID, worker tree, and model route. Do not compare runs that changed both the binary and the delegation topology.

2. Create one explicit root goal

Use the goal tool only when the task genuinely has a bounded objective and the user or system explicitly requested a token budget. A minimal tool payload looks like this:

{
  "objective": "Verify the multi-agent release candidate",
  "token_budget": 50000
}

Do not invent a budget for an ordinary task. create_goal rejects a second unfinished goal; complete the current goal before replacing it.

3. Capture a baseline before fan-out

Call get_goal and record the goal ID, status, budget, tokens_used, and remaining tokens. Then spawn one child with a small deterministic task. Check the goal again after a tool completion rather than relying on a UI estimate.

4. Add nesting and an idle checkpoint

Have the child spawn one grandchild. Let the root wait while the descendant completes a bounded step. The next goal snapshot should include new descendant usage even if the root produced no new model work during that interval.

5. Exercise lifecycle boundaries

Unload the parent worker runtime while a grandchild remains active, then verify roll-up. Complete the first goal, create a replacement goal, and confirm that usage recorded before the replacement does not become the new goal's opening balance.

6. Stop fan-out at the boundary

When the root goal reaches its budget, stop admitting new workers. Reconcile any usage that arrived between a checkpoint snapshot and its write, wait for in-flight work to stop safely, then capture the terminal goal record. Do not translate BudgetLimited into “subscription quota exhausted” or “all costs stopped.”

Eight accounting canaries

Canary	Expected evidence
Root only	Root work advances tokens_used once
Child roll-up	One child delta appears in the root goal
Grandchild roll-up	A nested descendant also appears in the same goal
Idle root	Descendant progress is recorded while the root waits
Parent unload	Grandchild usage still arrives after its parent runtime stops
Concurrent checkpoint	Usage recorded during a checkpoint remains pending for the next one, with no loss or duplicate
Goal replacement	The new goal excludes the previous goal's descendant baseline
Budget boundary	Status becomes BudgetLimited, new fan-out stops, and final usage is reconciled once

The official test suite includes a compact arithmetic example: 14 uncached-input-plus-output tokens from the root, 36 from a child, and 12 from a grandchild produce 62 tokens on the root goal and reach a 62-token budget. Use larger values in production, but keep this deterministic shape in CI.

Decision tree

Is there an explicit root goal with a positive token budget?
  no  -> do not claim a hard goal-token limit
  yes -> does child usage appear in get_goal?
           no  -> verify Codex >= 0.151, the root/descendant relationship, and checkpoint completion
           yes -> does grandchild usage appear after the parent unloads?
                    no  -> stop rollout and preserve the tree/lifecycle trace
                    yes -> run concurrent-checkpoint and goal-replacement canaries
                             -> any loss, duplication, or baseline leak?
                                  yes -> stop rollout with the accounting record
                                  no  -> enable bounded fan-out and monitor the terminal goal state

Common mistakes

• Treating the goal token budget as the model context window.
• Claiming it fixes account-level or weekly quota reporting.
• Setting a budget but never checking get_goal after descendant work.
• Testing only direct children and missing a grandchild path.
• Assuming a budget crossing instantly cancels every in-flight tool call.
• Replacing a goal without checking that the descendant baseline reset.
• Combining a concurrency change with the accounting rollout, making regressions hard to locate.
• Presenting community reports of runaway delegation as verified platform-wide behavior.

Copyable acceptance record

date / operator / Codex version / tag commit:
root thread / goal ID / objective / token budget:
model route / collaboration mode / worker topology:
baseline tokens_used / remaining:
root-only / child / grandchild deltas:
idle / parent-unload / concurrent-checkpoint results:
replacement-goal opening balance:
budget-limited status / in-flight reconciliation / terminal usage:
provider quota and tool-spend checks kept separate:

Building something? Take a 60-sec game break. Score to rank your product or profile on tapto.top and get more exposure—free, no signup.

FAQ

Does Codex 0.151 cap all subagent costs automatically?

No. The release makes descendant usage count toward an explicit persisted root goal budget. It does not create a budget when none was requested, nor does it replace account quota, API billing, tool-spend, or side-effect controls.

What exactly is counted by the goal ledger?

In the tagged implementation, the delta is uncached input tokens plus output tokens. Cached input is subtracted. That is why the goal ledger should be compared with its own get_goal fields, not with a raw total-token counter from another surface.

Can I assume workers stop the moment the goal reaches its budget?

No. Treat the state as an admission boundary: stop new fan-out and reconcile work already in flight. The official tests explicitly preserve later accounting on a budget-limited goal until the turn stops.

Sources

• Codex rust-v0.151.0 release
• PR #41183: account subagent token usage toward root goals
• Tagged goal accounting source
• Tagged goal tool specification
• Tagged goal accounting integration tests

Originally published at IndieSeek.