JuliusBrussee/caveman · error

cave_subagent_context_budget

cave_subagent_context_budget

Error message

cave_subagent_context_budget

What it means

Before a subagent runs, its agent definition is lowered to Context IR (system prompt plus the task text) and the token counts of those static segments are summed. If that sum already exceeds the child runtime's maxContextTokens, dispatch throws immediately: the child's own prompt+task cannot fit its declared context window, so any provider call would be wasted. This is the pre-flight (estimated) check, distinct from the post-run actual check at line 4057.

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 766dce6b13)

Solutions

1. Raise the child's maxContextTokens above prompt+task with headroom for output and tool results
2. Shorten the task string passed to the subagent (summarize, chunk, or reference instead of inlining)
3. Shrink the child's system prompt or move boilerplate into a file the child reads via a tool
4. Point the child at a model with a larger context window

Example fix

// before: 4k window child receives a huge task
const researcher = parent.subagent({ model: smallCtxModel, maxContextTokens: 4096 });
await researcher(task: entireCodebaseDump);

// after: trim input and raise the cap
await researcher({ task: 'Summarize the top 3 findings from these notes: ' + notes.slice(0, 2000) });
// and set maxContextTokens to at least prompt+task+output headroom, e.g. 32_768

// Rough pre-flight: static prompt + task must fit the child window (chars/4 estimate)
const estimateTokens = (s: string) => Math.ceil(s.length / 4);
const childStatic = estimateTokens(childDefinition.systemPrompt ?? '') + estimateTokens(task);
const OUTPUT_HEADROOM = estimateTokens(childDefinition.systemPrompt ?? '') + 8_192; // conservative
if (childStatic + OUTPUT_HEADROOM > childMaxContextTokens) {
  task = task.slice(0, (childMaxContextTokens - OUTPUT_HEADROOM) * 2); // trim before dispatch
}

try {
  return await dispatchSubagent(task);
} catch (error) {
  if (error instanceof Error && error.message === 'cave_subagent_context_budget') {
    throw new Error(`task too large for subagent window (${task.length} chars); trim or raise maxContextTokens`);
  }
  throw error;
}

When it happens

Trigger: A subagent definition with a large system prompt and a long task string while its runtime maxContextTokens is smaller than prompt+task; explicitly setting maxContextTokens low (e.g., 8k) on a verbose agent; passing a whole document as the task payload to a small-window child; child model resolution falling back to a small-context model.

Common situations: Copy-pasting a big prompt template into a subagent configured for a small-window model; mistaking the model's max output tokens for its context window; escalating task payloads (full file contents, logs) into a child without trimming; inheriting parent prompt scaffolding into the child definition.

Related errors

• caveman agent: subagent maxTokens must be a positive integer
• caveman agent: subagent maxContextTokens must be a positive
• cave_transform_trace_basis_mixed
• cave_agent_definition_invalid
• cave_subagent_depth_limit

AI-assisted analysis of JuliusBrussee/caveman@766dce6b13 (2026-08-18). Data as JSON: /api/errors/e210dad86df35eb9. Report an issue: GitHub.