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. Before sampling, for_prompt prepares history against the active model modalities; image content can remain part of durable history while the model-facing projection omits it when the active model path cannot accept images. A separate recovery hook can replace image content in the last tool-output turn after an image request is rejected. 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 from tool output to 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. Give every plane a selection and budget rule, and keep optional material from crowding out core task evidence.
2. Breadth Before Depth. Preserve capability coverage before long descriptions. Shorten metadata before omitting entries, and avoid hiding capabilities through early omission.
3. Budget Diagnostics. Warn when context is shortened or omitted. Emit user-visible or telemetry-visible reports, and do not let silent budget cuts make behavior mysterious.
4. Side-Channel Routing. Route hooks and memory through the same context ledger. Record their additions as explicit items, and reject prompt mutation outside the runtime.
5. Modality Projection. Keep rich evidence durable, but project only what the active model path supports. Strip or replace unsupported modalities at prompt time, and keep provider assumptions out of stored history.