What causes "cave_subagent_context_budget" in JuliusBrussee/caveman?

Reduce the task input size (reference files instead of inlining them)

cave_subagent_context_budget

cave_subagent_context_budget

Error message

cave_subagent_context_budget

What it means

After building the child agent's context from its input, the runtime sums the token counts of the child context segments and enforces runtime.maxContextTokens. If the assembled child context exceeds that ceiling, cave_subagent_context_budget is thrown before any model call, keeping a subagent from starting with a context already over its budget.

Solutions

Reduce the task input size (reference files instead of inlining them)
Raise runtime.maxContextTokens for the subagent runtime
Trim what the child context builder includes (narrow rootDir, fewer context segments)
Split the work across multiple smaller subagent calls

Example fix

// before
runtime: { kind: "subagent", maxContextTokens: 8000 }
dispatchSubagent({ task: entireLogFile });
// after
runtime: { kind: "subagent", maxContextTokens: 100000 }
dispatchSubagent({ task: "Analyze errors in " + logPath });

Defensive patterns

Strategy: validation

Validate before calling

const estTokens = Math.ceil(task.length / 4);
if (estTokens > subagentRuntime.maxContextTokens) {
  task = truncateToTokenBudget(task, subagentRuntime.maxContextTokens - baselineOverhead);
}

Try / catch

try {
  await dispatchSubagent({ task });
} catch (e) {
  if (e.message === "cave_subagent_context_budget") {
    await dispatchSubagent({ task: condense(task) });
  } else throw e;
}

Prevention

Keep task inputs well below maxContextTokens (reserve room for system/context segments)
Reference files by path instead of inlining contents
Set maxContextTokens well above the builder's baseline context size
Measure actual child context token totals and tune the limit

When it happens

Trigger: Dispatching a subagent whose task input causes childContext.ir.segments' total tokenCount to exceed runtime.maxContextTokens — typically a very large task string plus baseline context.

Common situations: Task text embedding large file contents; maxContextTokens configured below the runtime's own baseline context size; child inheriting a heavy system/context build from rootDir contents; cost-focused configs with tiny context budgets.

Understand the failure class

Background: payload too large / request exceeds maximum size: why libraries cap bytes and how to fix oversize payloads — this error's family across 50 libraries.

Related errors

AI-assisted analysis of JuliusBrussee/caveman@3ee70a1026 (2026-09-20). Data as JSON: /api/errors/e210dad86df35eb9. Report an issue: GitHub.

Appendix: source

Thrown at packages/agent/src/runtime.ts:3952

    toolDefinition,
    runtime,
    task,
    signal,
    parentOptions,
    usage,
    executionContext,
    depth,
  } = input;
  if (signal?.aborted) throw signal.reason;
  const childDefinition = runtime.definition as AgentDefinition;
  const childContext = await lowerAgentContext(childDefinition, {
    ...(parentOptions.rootDir === undefined ? {} : { rootDir: parentOptions.rootDir }),
    input: task,
  });
  const childContextTokens = childContext.ir.segments
    .reduce((total, segment) => total + segment.tokenCount, 0);
  if (childContextTokens > runtime.maxContextTokens) {
    throw new Error("cave_subagent_context_budget");
  }
  const childUsesAuto = childDefinition.model !== null &&
    typeof childDefinition.model === "object" &&
    "kind" in childDefinition.model &&
    childDefinition.model.kind === "auto";
  const childModel = childUsesAuto && parentOptions.model !== undefined
    ? parentOptions.model
    : resolveModel(
      childDefinition,
      parentOptions.models ?? builtinModels(),
      parentOptions.rootDir ?? process.cwd(),
    );
  // A carved wallet is already the child's hard economic boundary in the
  // parent's denomination. Stacking the legacy USD-only ledger on a token
  // wallet would require catalog pricing and reject otherwise valid raw-token
  // runs (including subscription/unpriced transports). Keep that ledger only
  // for standalone legacy subagents that have no carved BudgetMeter.
  let spendLedger: SpendLedger | undefined;

View on GitHub (pinned to 3ee70a1026)