Chapter 5: Budgeting Optional Context

Reading Contract: Use this chapter to budget optional planes. Track skills, plugins, memory, tool output, and images as candidates that must earn space in the model window.

Chapter 4 explained how required runtime facts become typed fragments and diffs. This chapter turns to optional context: skills, plugins, apps, memory summaries, tool outputs, images, and hook additions. Optional does not mean unimportant. It means the system should be able to drop, shorten, select, or defer it without breaking the core turn contract.

Codex’s context management is strongest when it treats optional material as a budgeted plane. A skill description can help the model, but every token spent on skills is a token not spent on the user’s code, previous tool outputs, or the current task. The design question is not “can we include it?” The question is “what budget and ownership make inclusion safe?”

By the end of this chapter, you should be able to recognize the optional-context pattern across several subsystems.

Optional Planes

Codex has several optional context planes:

The common pattern is “select, budget, then inject.” Optional context never gets to assume the whole window is available.

Warnings are part of the design. If Codex shortens skill descriptions or omits some skill metadata, the user-visible runtime can explain that the model saw a reduced capability list. Silent omission would be cheaper but harder to debug.

How the Window Is Sliced

The effective context window is shared between several consumers. A rough allocation model keeps the relationships visible: required history and current task context come first, optional planes compete for a bounded middle slice, and the answer keeps a reserved tail. Exact numbers shift with model and configuration.

The reserved tail on the right is what makes optional planes really optional. If the model has no room left to answer, every clever skill description was wasted. Budgeting respects that asymmetry: the answer always wins.

Skills: Budgeted Discovery

The skill renderer defaults to a fixed character budget when no context window is known, otherwise it budgets a small percentage of the effective context window. It first tries absolute-path skill lines; if that is too expensive, it can prefer aliased paths because shorter paths preserve more semantic description text. If needed, it truncates descriptions before omitting whole skills.

That sequence is opinionated. It preserves breadth before depth: Codex would rather show every skill with shorter descriptions than hide capabilities early. Only after descriptions are exhausted does it omit skills.

// Pseudocode -- illustrates optional skill budgeting.
budget = contextWindow ? percent(contextWindow) : defaultChars
rendered = renderWithFullPaths(skills, budget)
if rendered.omitsOrTruncates:
    rendered = betterOf(
      rendered,
      renderWithAliases(skills, budget),
    )
emitWarnings(rendered.report)

The transferable idea is not the exact percentage. It is that optional capability discovery has a budget owner and emits diagnostics.

A useful way to remember the breadth-before-depth strategy is: shorten every skill first, then omit only when the shared budget is still exhausted.

Hooks and Memory Are Side Channels

Hooks can add context during prompt submission or stop-hook continuation. Memory can add summarized user-level state through developer instructions. These are side channels because they are not the user’s immediate message and not ordinary tool observations. Codex makes them explicit: hook outcomes produce additional contexts that are recorded, and memory summaries pass through template rendering and truncation.

The danger with side channels is authority confusion. A hook-added note may be important policy context; a memory summary may be helpful personalization. Both must enter the same governed context pipeline instead of silently modifying the base prompt.

The four side channels and how they are bounded:

The point is not that side channels are bad; it is that they must be enumerated and bounded. Codex treats every additional injection path as a first-class plane with the same selection / budget / inject discipline.

Tool Outputs and Images

Tool output is optional in a different sense: the observation may be necessary for the current task, but its raw form is not necessarily suitable for the model. Codex applies truncation policy when recording items, and it can sanitize or replace invalid image content if the model rejects an image request. The history ledger remains structured enough to remove or replace the problematic turn output and retry.

That is a better failure mode than treating tool output as raw transcript text. The output has a protocol identity, so Codex can reason about it.

The simplest-looking edge, “tool output —> history,” is actually four different cases under the hood. Naming them is half the design.

Apply This

1. Optional Context Plane -> separate helpful context from required context, adapt it by giving every plane a selection and budget rule, and watch for optional material that can crowd out core task evidence.
2. Breadth Before Depth -> preserve capability coverage before long descriptions, adapt it by shortening metadata before omitting entries, and watch for hidden capabilities caused by early omission.
3. Budget Diagnostics -> warn when context is shortened or omitted, adapt it by emitting user-visible or telemetry-visible reports, and watch for silent budget cuts that make behavior mysterious.
4. Side-Channel Routing -> route hooks and memory through the same context ledger, adapt it by recording their additions as explicit items, and watch for prompt mutation outside the runtime.
5. Modality Projection -> keep rich evidence durable but project only what the model supports, adapt it by stripping unsupported modalities at prompt time, and watch for provider assumptions leaking into stored history.