Skip to content

03.1

Concept explanation

In Chapter 2 we hand-waved "the harness builds a prompt and calls the model." This chapter opens that step up, because what goes into the prompt, and in what order, is one of the most consequential design decisions in the whole harness. The "Seven Pillars" breakdown calls this context engineering, and it lists it as pillar number one for a reason.

When you query a modern agent API (OpenAI's Responses API, Anthropic's Messages API), you do not hand it one big string. You hand it a structured request with a few distinct fields. Codex's request, for example, has three you really need to understand:

  • instructions: the system and developer guidance, the model's "personality" and rules.
  • tools: a list of tool definitions, each one a JSON schema describing what the tool does and what arguments it takes.
  • input: the conversation itself, as a list of typed items (user messages, assistant messages, tool calls, tool results).

The server then assembles these into the actual token sequence the model sees. Conceptually, think of the final prompt as a single ordered list of items, each tagged with a role that signals how much authority it carries. In decreasing order of priority: system, developer, user, assistant. System rules outrank user requests, which outrank the assistant's own past words.

Layered instructions

The instructions are not one block of text written by one person. They are layered, and the layering is deliberate. Reading across the Codex write-up and the "Inside the Agent Harness" deep-dive, a typical stack looks like this:

LayerSourcePurpose
Base instructionsBundled with the model (e.g. gpt-5.2-codex_prompt.md)The model's core behavior and "personality"
Developer instructionsThe user's config fileProject- or developer-level overrides
User instructionsAGENTS.md / CLAUDE.md, aggregated from several filesConventions, test commands, house style
Skills metadataConfigured skillsShort descriptions of available procedures (Chapter 10)
Environment contextComputed at runtimeCurrent working directory, shell, sandbox rules

The rule for aggregating user instructions is "more specific wins." Codex reads every AGENTS.md from the project root down to your current working directory and joins them in that order, so the file closest to where you are working comes last, and Codex's base prompt tells the model that a nested file wins a conflict. The joined text has a size limit (32 KiB by default). This is layering you will rebuild in Chapter 9.

The conversation as structured items, not a transcript

Here is a detail that separates a toy from a real harness. The history is not stored as a flat string like "User said X, then I ran Y, then I saw Z." It is stored as typed, structured items, and crucially, a tool call and its output are linked by a shared call_id.

Why does that linkage matter? Because the model needs to understand cause and effect. If you ran three shell commands in parallel and dumped three blobs of output, the model would not know which output came from which command. The call_id ties result to request, so the model reads the causal relationship correctly. The "Inside the Agent Harness" analysis flags this as one of the things that makes structured tool outputs critical: the model needs to know what happened, not just what text appeared.

Tool definitions as JSON schemas

The tools field is a list of JSON schemas. Here is Codex's shell tool, lightly trimmed:

{
  "type": "function",
  "name": "shell",
  "description": "Run a shell command and return its output",
  "parameters": {
    "type": "object",
    "properties": {
      "command":    {"type": "array", "items": {"type": "string"},
                     "description": "The command to execute"},
      "workdir":    {"type": "string", "description": "Working directory"},
      "timeout_ms": {"type": "number", "description": "Timeout in milliseconds"}
    },
    "required": ["command"]
  }
}

The model reads these schemas to know what it is allowed to ask for and how to format the request. The harness dynamically decides which tools to include based on permissions, sandbox mode, and context. For example, Codex only adds a view_image tool when an image is actually present. Fewer, well-described tools beat a giant undifferentiated pile.

03.2

Why it matters

Three reasons, each of which becomes a whole chapter later.

First, everything the model knows comes from this prompt. It has no other window into your world. The "Inside the Agent Harness" piece phrases the design rule memorably: "if you would be lost with only the last screenshot and tool output, the model will be too." Build the prompt as if you were briefing a competent colleague who just walked in.

First-cousin to that: order matters for cost. Static content (instructions, tools) goes at the front; variable content (the latest user message) goes at the end. That ordering is what makes prompt caching work, and caching is the difference between an affordable agent and a ruinous one. Chapter 5 is devoted to it; for now, just internalize "stable stuff first."

Second, structure matters for correctness. Linking tool calls to results, tagging roles, separating instructions from history: these let the model reason about authority and causality instead of guessing.

03.3

How it works: assembling one request

Putting the pieces together, here is the order Codex inserts items into input before adding your actual message:

  1. A developer message describing the sandbox and permission rules (applies to the built-in shell tool).
  2. Optional developer instructions from config.
  3. A user message with the aggregated AGENTS.md / skills instructions.
  4. A user message describing the environment (<environment_context> with cwd and shell).
  5. Finally, your actual user message.

At the commit the Real code slides quote, the code keeps that shape with two changes: the developer pieces are bundled into one developer message, and the developer instructions from config now come after the AGENTS.md and environment messages. The idea is unchanged: standing instructions first, your message last.

Then on later turns, the previous turns' items (assistant messages, tool calls, tool results) are appended, along with any context section that changed (a new working directory, say), and the old prompt stays an exact prefix of the new one. That prefix property is not an accident; it is engineered, again for caching.

03.4

Code MVP: a prompt builder

This PromptBuilder assembles the three fields the way a real harness does. It is intentionally close to what the capstone uses.

"""
chapter 03: building the prompt.
Assemble layered instructions, tool schemas, and a structured history
into a single request dict. Stable content goes first (for caching, Ch 5).
"""
from dataclasses import dataclass, field

@dataclass
class PromptBuilder:
    base_instructions: str = "You are a careful coding agent."
    project_instructions: str = ""        # from AGENTS.md / CLAUDE.md (Ch 9)
    skills_summary: str = ""              # short skill descriptions (Ch 10)
    cwd: str = "."
    shell: str = "bash"
    tools: list = field(default_factory=list)   # JSON schemas (Ch 6)

    def build_instructions(self) -> str:
        # Layered, most-general first, most-specific last.
        layers = [self.base_instructions]
        if self.project_instructions:
            layers.append(f"<project_instructions>\n{self.project_instructions}\n</project_instructions>")
        if self.skills_summary:
            layers.append(f"<skills>\n{self.skills_summary}\n</skills>")
        return "\n\n".join(layers)

    def environment_item(self) -> dict:
        # A user-role item describing where the agent is running.
        return {"role": "user", "type": "message",
                "content": f"<environment_context><cwd>{self.cwd}</cwd>"
                           f"<shell>{self.shell}</shell></environment_context>"}

    def build_request(self, history: list) -> dict:
        """history is a list of structured items (see add_* helpers below)."""
        return {
            # STABLE prefix first: instructions and tools rarely change.
            "instructions": self.build_instructions(),
            "tools": self.tools,
            # VARIABLE content last: environment, then the live conversation.
            "input": [self.environment_item()] + history,
        }

# --- helpers that keep the history STRUCTURED, not a flat string ---
def user_msg(text):
    return {"role": "user", "type": "message", "content": text}

def assistant_msg(text):
    return {"role": "assistant", "type": "message", "content": text}

def tool_call(call_id, name, args):
    return {"role": "assistant", "type": "tool_call",
            "call_id": call_id, "name": name, "args": args}

def tool_result(call_id, output):
    # SAME call_id links this result to the call above, so the model
    # understands which output belongs to which command.
    return {"role": "tool", "type": "tool_result",
            "call_id": call_id, "content": output}

if __name__ == "__main__":
    pb = PromptBuilder(
        project_instructions="Run tests with `pytest -q`. Use 4-space indents.",
        tools=[{"type": "function", "name": "shell",
                "description": "Run a shell command",
                "parameters": {"type": "object",
                               "properties": {"command": {"type": "string"}},
                               "required": ["command"]}}],
        cwd="/repo", shell="zsh",
    )
    history = [
        user_msg("fix the failing test"),
        tool_call("c1", "shell", {"command": "pytest -q"}),
        tool_result("c1", "1 failed, 3 passed"),
    ]
    request = pb.build_request(history)
    import json
    print(json.dumps(request, indent=2))

This dict is the Responses-style shape from the start of the chapter: an instructions string, a tools list with name beside type, and an input list of typed items linked by call_id. The next five slides are the production versions of these fields. Each one handles a case this builder skips, including a tool list that has to be rewritten before it can go to Chat Completions or Anthropic.

03.5

Real code: the base prompt is compiled into the binary

The PromptBuilder you just built takes base_instructions as one string you pass in. Codex has to find that string, and it has to sit in front of the saved conversation. The fallback text is compiled into the program.

pub const BASE_INSTRUCTIONS: &str = include_str!("../prompt.md"); // [1]
const PERSONALITY_SECTION_HEADER: &str = "# Personality";
// ... (context-window and token-limit overrides on the model record)
    if let Some(base_instructions) = &config.base_instructions { // [2]
        let model_messages = model.model_messages.get_or_insert_default();
        model_messages.instructions_template = Some(base_instructions.clone());
    } else if config.personality == Some(Personality::None)
        && let Some(instructions_template) = model
            .model_messages
            .as_mut()
            .and_then(|messages| messages.instructions_template.as_mut())
    {
        *instructions_template = strip_personality_section(std::mem::take(instructions_template)); // [3]
    }
// ... (the fallback record used when the model slug is unknown)
fn local_model_messages() -> ModelMessages {
    ModelMessages {
        instructions_template: Some(BASE_INSTRUCTIONS.to_string()),
        ..Default::default()
    }
}

Source: openai/codex, codex-rs/models-manager/src/model_info.rs (Apache-2.0)

On the way into the request, that string becomes a conversation item and is inserted at the front of input.

        // These prompt-only items are rebuilt on every request. Hash their visible payloads
        // within the thread so retries and resumed sessions preserve their identity.
        let prefix_namespace = Uuid::new_v5(
            &Uuid::NAMESPACE_OID,
            self.state.thread_id.to_string().as_bytes(),
        );
        let mut prefix = Vec::new();
        // ... (on the responses-lite path, a tools item is pushed onto prefix first)
        if !prompt.base_instructions.text.is_empty() {
            let mut instructions = ContextualUserFragment::into(BaseInstructionsFragment(
                prompt.base_instructions.text.clone(),
            ));
            instructions.set_id(Some(ResponseItemId::with_suffix(
                "msg",
                Uuid::new_v5(&prefix_namespace, prompt.base_instructions.text.as_bytes()), // [4]
            )));
            prefix.push(instructions);
        }
        input.splice(0..0, prefix); // [5]

Source: openai/codex, codex-rs/core/src/client.rs (Apache-2.0)

What to notice

  1. [1] include_str! pastes prompt.md into the binary at compile time. An unknown model slug gets that string as its instructions_template inside local_model_messages.
  2. [2] If the user set config.base_instructions, that string replaces the template on the model record. Your PromptBuilder has one base_instructions string and nowhere to put a second source that overrides it.
  3. [3] With personality set to none, and no custom template, strip_personality_section deletes from a line that is exactly # Personality through the next h1, or through the end of the string when no later h1 exists. Catalog templates in models.json contain that h1, so they lose the section. The compiled prompt.md used for an unknown slug has ## Personality, and the same function leaves that file unchanged. Your builder always sends the whole string, so it cannot turn that voice off.
  4. [4] BaseInstructionsFragment wraps the string as a developer item (that role outranks user) and adds no tags around the text. The id is msg_ plus a version-5 UUID of the thread id and the exact instruction bytes. The same text keeps the same id across retries.
  5. [5] splice(0..0, prefix) inserts the prefix at the start of input. The base text is rebuilt on every request. When incremental tools are on, build_prompt passes an empty string, so this splice does not add a second copy. That mode records the base text in history instead.

Session startup picks the config override if one is set, otherwise the text saved on the conversation, otherwise render_model_instructions for the current model. With no config override, a resumed session keeps that saved text. Your PromptBuilder never chooses among a config override, a saved session, and a model template.

Read it yourself: Open prompt.md and confirm the heading is ## Personality. Then in session/mod.rs, confirm the config override wins over the saved conversation and the model template.

03.6

Real code: AGENTS.md is collected from the root down

Your PromptBuilder keeps project_instructions as one string. Codex searches the disk for it. From the working directory it walks up to the project root (the nearest directory with a configured marker, .git by default), then flips the list so the root comes first.

    let search_dirs = if let Some(root) = project_root {
        let mut dirs = Vec::new();
        let mut cursor = dir.clone();
        loop {
            dirs.push(cursor.clone());
            if cursor == root {
                break;
            }
            let Some(parent) = cursor.parent() else {
                break;
            };
            cursor = parent;
        }
        dirs.reverse(); // [1]
        dirs
    } else {
        vec![dir] // [2]
    };

Source: openai/codex, codex-rs/core/src/agents_md.rs (Apache-2.0)

Those files are then read in that order, root first, and cut off when a byte budget runs out.

    for p in paths {
        if remaining == 0 { // [3]
            break;
        }
        // ...
        let mut data = match fs.read_file(&p, ReadFileOptions::default(), sandbox).await {
            Ok(data) => data,
            Err(err) if err.kind() == io::ErrorKind::NotFound => continue,
            Err(err) => return Err(err),
        };
        let size = data.len() as u64;
        if size > remaining {
            data.truncate(remaining as usize); // [4]
        }
        // ... (a warning when the file was cut)
        let text = String::from_utf8_lossy(&data).to_string();

Source: openai/codex, codex-rs/core/src/agents_md.rs (Apache-2.0)

What to notice

  1. [1] The loop collects directories from the working directory up to the root. reverse puts the root first and your current directory last. Codex concatenates every file it found. It does not delete the parent. The closer file comes later, so it can restate a parent rule, but the parent text is still in the prompt.
  2. [2] With no project root, only the current directory is searched. The walk does not continue to the top of the filesystem.
  3. [3] remaining starts at project_doc_max_bytes, which defaults to 32 KiB (DEFAULT_PROJECT_DOC_MAX_BYTES in config_toml.rs). At zero the loop stops. Because the root was read first, the files that get skipped are the ones closest to you.
  4. [4] A file bigger than the bytes left is cut in place with truncate. Your builder would paste the whole file.

Two more cases your builder has no room for. In one directory, candidate_filenames tries AGENTS.override.md before AGENTS.md, and the first file that exists is the one that counts. If the project is untrusted, load_project_instructions returns before the walk, so project files are never read. The joined text is then sent as a user message, wrapped with # AGENTS.md instructions and <INSTRUCTIONS>, not mixed into the developer base prompt the way build_instructions mixes your project string in.

pi's loadContextFileFromDir tries AGENTS.override.md, AGENTS.md, AGENTS.MD, CLAUDE.md, and CLAUDE.MD. loadProjectContextFiles also reads the global agent directory first, then climbs parents until the filesystem root. Codex stops at .git by default and does not hardcode the .MD or CLAUDE.md names.

Read it yourself: In agents_md.rs, search for is_untrusted and for AGENTS_MD_SEPARATOR. An untrusted project should skip the files, and the separator --- project-doc --- should appear only where user-level text switches to project text. Then open resource-loader.ts and compare loadContextFileFromDir with candidate_filenames.

03.7

Real code: the environment is resent only when it changes

The PromptBuilder you just built puts a fresh environment string at the front of input on every call, and that string only knows the working directory and the shell. Codex writes an <environment_context> user message into the conversation. The first turn injects the full context. A later turn adds another message only when a value changed.

        let turn_context_values_changed = current.shell_version != previous.shell_version
            || current.current_date != previous.current_date
            || current.timezone != previous.timezone
            || current.network != previous.network
            || current.filesystem != previous.filesystem;
        // ... (which environments were added, removed, or edited)
        let fragment = (!updates.is_empty() || turn_context_values_changed).then(|| {
            Box::new(RenderedEnvironments {
                // ... (the changed environments, plus network and filesystem)
            }) as Box<dyn ContextualUserFragment>
        });
        (
            Some(current),
            WorldStateUpdate::optional_boxed_fragment(fragment), // [1]
        )

Source: openai/codex, codex-rs/core/src/context/world_state/environment.rs (Apache-2.0)

When a message is sent, the directory and the shell are written as XML, with the characters escaped.

fn push_environment_values(rendered: &mut String, environment: &EnvironmentState, indent: &str) {
    rendered.push_str(indent);
    rendered.push_str("<cwd>");
    push_xml_escaped_text(rendered, &environment.cwd.inferred_native_path_string()); // [2]
    rendered.push_str("</cwd>\n");
    if environment.status == EnvironmentStatus::Starting {
        rendered.push_str(indent);
        rendered.push_str("<status>starting</status>\n");
    }
    if environment.status == EnvironmentStatus::Failed { // [3]
        rendered.push_str(indent);
        rendered.push_str("<status>failed</status>\n");
    }
    if let Some(error) = &environment.error {
        rendered.push_str(indent);
        rendered.push_str("<error>");
        push_xml_escaped_text(rendered, error);
        rendered.push_str("</error>\n");
    }
    if let Some(shell) = &environment.shell {
        rendered.push_str(indent);
        rendered.push_str("<shell>");
        push_xml_escaped_text(rendered, shell);
        rendered.push_str("</shell>\n");
    }
}

Source: openai/codex, codex-rs/core/src/context/world_state/environment.rs (Apache-2.0)

What to notice

  1. [1] optional_boxed_fragment turns a missing fragment into no update at all. If no environment was added, removed, or edited, and the shell version, date, timezone, network rules, and filesystem rules are the same, this section adds nothing. The old message stays where it was. record_context_updates_and_set_reference_context_item records new items onto the conversation only when that list is non-empty. The PromptBuilder you just built rebuilds the environment string at the front of input on every call. Change the directory and those bytes move, so the prefix the cache depends on changes with them.
  2. [2] <cwd> is the working directory in the platform's path spelling, passed through push_xml_escaped_text (&, <, >, quotes). A folder named a<b cannot close the tag early. The f-string in your PromptBuilder pastes the raw characters.
  3. [3] The same block can say the environment is still starting or has failed, and it can include a short <error>. The shell line is the shell's name, such as zsh, not a full path. Network allow and deny lists, and the filesystem permission profile, are copied onto this same update and rendered as their own tags. Your builder has nowhere to put any of that.

The whole message is role user, between <environment_context> and </environment_context>. One available environment is written as bare <cwd> and <shell>. Two or more environments are wrapped in <environment id="...">. The first ready environment for the turn is marked primary="true". A failed environment is stored with is_primary false, so that attribute is primary="false" when the wrapper includes one.

Read it yourself: In environment.rs, search for push_optional_element and list the extra tags (shell_version, current_date, timezone). Then open session/mod.rs at emits only context diffs. A later turn should add a message only for what changed, leaving the earlier items in place.

03.8

Real code: the tool schema is rewritten per provider

The tools list in the PromptBuilder you just built is already the JSON you want to send. pi keeps one Tool and rewrites it for each provider, because the JSON on the wire is not the same shape.

function convertTools(
  tools: Tool[],
  compat: ResolvedOpenAICompletionsCompat,
): OpenAI.Chat.Completions.ChatCompletionTool[] {
  return tools.map((tool) => {
    const grammar = resolveGrammarConstrainedSampling(tool, compat.supportsOpenAIGrammarTools);
    if (grammar) {
      return {
        type: "custom",
        // ... (a grammar-constrained tool, not a JSON schema)
      };
    }

    const strict = resolveJsonSchemaStrictSampling(tool, compat.supportsStrictMode !== false); // [1]
    return {
      type: "function", // [2]
      function: {
        name: tool.name,
        description: tool.description,
        parameters: getJsonSchemaToolParameters(tool, strict) as Record<string, unknown>,
        // Only include strict if provider supports it. Some reject unknown fields.
        ...(compat.supportsStrictMode !== false && { strict: strict ?? false }), // [3]
      },
    };
  });
}

Source: earendil-works/pi, packages/ai/src/api/openai-completions.ts (MIT)

Anthropic's Messages API gets a different object from the same Tool.

function convertTools(
  tools: Tool[],
  isOAuthToken: boolean,
  supportsEagerToolInputStreaming: boolean,
  supportsStrictTools: boolean,
  cacheControl?: CacheControlEphemeral,
  disablePreferredStrictTools = false,
): BetaTool[] {
  // ... (an empty-tools guard)
  return tools.map((tool, index) => {
    // ... (decide strict mode, then build the schema this provider accepts)
    return {
      name: isOAuthToken ? toClaudeCodeName(tool.name) : tool.name, // [4]
      description: tool.description,
      ...(supportsEagerToolInputStreaming ? { eager_input_streaming: true } : {}),
      ...(strict === true ? { strict: true } : {}),
      input_schema: inputSchema, // [5]
      // ... (a cache marker on the last tool only)
    };
  });

Source: earendil-works/pi, packages/ai/src/api/anthropic-messages.ts (MIT)

What to notice

  1. [1] resolveJsonSchemaStrictSampling returns true only when this tool asked for JSON-schema sampling, this provider supports it, and makeStrictJsonSchema can rewrite the schema. That rewrite puts every property name in required and sets additionalProperties to false. An optional property that does not already allow null is wrapped as anyOf with {type: "null"}. If the tool said require and that rewrite is impossible, or this provider cannot do strict sampling, the call throws. A prefer tool that cannot be rewritten sends the original schema.
  2. [2] The tool is nested under type: "function" and a function object. Your builder puts name beside type, which is the Responses API shape. Chat Completions wants the extra nesting.
  3. [3] strict is added only when the provider accepts it. The comment on the previous line says some servers reject fields they do not know.
  4. [4] convertTools maps each Tool to one BetaTool. The object in the excerpt is the per-tool return, and the function returns that array. When the call uses an OAuth token, pi also sends the Claude Code betas claude-code-20250219 and oauth-2025-04-20, and toClaudeCodeName renames a tool to Claude Code's spelling when the lowercased name matches that list (read becomes Read). The comment on that lookup calls this stealth mode. Any other name is left as it is.
  5. [5] The field this converter fills is input_schema. Unless strict mode is on, that value is only type, properties, and required. Copying tool.parameters across under the old name parameters leaves input_schema unset.

Codex's ToolSpec type tag can also be namespace, tool_search, web_search, or custom. Your builder lists only functions.

Read it yourself: Open google-shared.ts and find export function convertTools. The comment above it says useParameters is for Cloud Code Assist with Claude models, where that API translates parameters into Anthropic's input_schema. Then read the serde rename on each variant in tool_spec.rs. You should see kinds your builder never constructs, starting with web_search.

03.9

Real code: the call_id is copied, not invented

The tool_call and tool_result helpers you just wrote share a call_id because you type the same string in both. Codex copies the string the model already sent.

    pub fn build_tool_call(item: ResponseItem) -> Result<Option<ToolCall>, FunctionCallError> {
        match item {
            ResponseItem::FunctionCall {
                name,
                namespace,
                arguments, // [1]
                encrypted_function_args,
                call_id,
                ..
            } => {
                let tool_name = ToolName::new(namespace, name).with_default_namespace(); // [2]
                Ok(Some(ToolCall {
                    tool_name,
                    call_id, // [3]
                    payload: ToolPayload::Function { arguments },
                    encrypted_function_args,
                }))
            }

Source: openai/codex, codex-rs/core/src/tools/router.rs (Apache-2.0)

After the tool runs, the result is a new history item that carries that same id.

fn function_tool_response(
    call_id: &str,
    payload: &ToolPayload,
    body: Vec<FunctionCallOutputContentItem>,
    success: Option<bool>,
) -> ResponseInputItem {
    let body = match body.as_slice() {
        [FunctionCallOutputContentItem::InputText { text }] => {
            FunctionCallOutputBody::Text(text.clone()) // [4]
        }
        _ => FunctionCallOutputBody::ContentItems(body),
    };

    if matches!(payload, ToolPayload::Custom { .. }) {
        return ResponseInputItem::CustomToolCallOutput {
            call_id: call_id.to_string(), // [5]
            name: None,
            output: FunctionCallOutputPayload { body, success },
        };
    }

    ResponseInputItem::FunctionCallOutput {
        call_id: call_id.to_string(),
        output: FunctionCallOutputPayload { body, success },
    }
}

Source: openai/codex, codex-rs/core/src/tools/context.rs (Apache-2.0)

What to notice

  1. [1] ResponseItem is the enum of history items, and FunctionCall is the variant for a normal tool call. arguments is still a string of JSON here. build_tool_call does not parse it. It moves the string onto ToolCall, the harness's internal request to run one tool. On FunctionCall in protocol/src/models.rs, that field is documented as a string of JSON, parsed by a later step, not by this function.
  2. [2] with_default_namespace fills in "functions" when the model left the namespace empty, so the registry looks up the tool you actually registered. Dropping the namespace would make a namespaced tool look like a different name.
  3. [3] call_id is moved across, not replaced with a new id. Your helpers match because the example passes "c1" twice. Nothing in the builder checks that you did.
  4. [4] A single text chunk is stored as plain text. Any other body, including several chunks or one non-text chunk, stays a list. Either shape is still tied to the call by the id, not by position in the list. That is the three-parallel-shell-commands case from the start of the chapter.
  5. [5] A freeform (custom) payload is answered with CustomToolCallOutput, and a normal payload with FunctionCallOutput. Both copy call_id. Using one output type for every call would record a result whose type does not match the call that asked for it.

Read it yourself: In models.rs, find the FunctionCall and FunctionCallOutput variants. Compare the type of call_id on each (a String on the call, an Option<String> on the stored output). Then search stream_events_utils.rs for response_input_to_response_item and see the Some(call_id.clone()) that fills the output. The line that would break the link is the one that would write None there.

03.10

Read the source yourself

Five stops, in the order a request is assembled. Every link is pinned to the commit this chapter quotes.

  1. Codex base text. Find BASE_INSTRUCTIONS in model_info.rs, open prompt.md, and notice the personality heading is ## Personality. strip_personality_section only deletes a line that is exactly # Personality, so this file loses nothing. The h1 it does delete is in the catalog instructions_template strings in models.json.
  2. Project files. In agents_md.rs, find dirs.reverse. The byte budget is project_doc_max_bytes a little earlier in load_project_instructions. Then open config_toml.rs and confirm DEFAULT_PROJECT_DOC_MAX_BYTES is 32 * 1024.
  3. Environment. In environment.rs, find render_diff and write down which fields count as a change. The session that records those messages is record_context_updates_and_set_reference_context_item in session/mod.rs.
  4. pi's prompt and pi's tools. In system-prompt.ts, read buildSystemPromptSections. The preamble is plain text. Every other section is wrapped in a tag of the same name. <project_context> holds the AGENTS.md and CLAUDE.md files, and renderProjectContext wraps each file in <project_instructions>. <cwd> is the working directory with backslashes flipped to forward slashes. Then in openai-completions.ts, convertTools is the function from the tool-schema slide.
  5. OpenCode's prompt, chosen by model family. In optimize.ts, OpenAIPlugin returns the GPT text only when the model id contains gpt, and the Astra variant when it also contains astra. That plugin's mode is override, so the text replaces the default system prompt. AnthropicPlugin returns the Claude text when the id contains claude, and its mode is append, so the text is added after the default. Both plugins leave the prompt alone when the agent already has a system prompt of its own. SessionSystemPrompt.render fills ${OPENCODE_TOOL_GUIDANCE} from the tool names present (shell, write, edit). The environment block is a different mechanism: builtins.ts builds a <env> string (working directory, workspace root, whether this is a git repo, platform, and a note to prefer the app temp directory over /tmp). Its changed renderer says the environment is now the new value, and Instructions.diff skips any key whose hash did not change.

Exercise: clone pi at the commit in those links, open openai-completions.ts, and find the line that adds strict only when the provider supports it. The comment above that line tells you what always sending the field would do. Do not leave the edit in place.

03.11

Connecting to the bigger picture

Chapter 2 called the model with a vague history; this chapter makes that call precise and well-ordered. The "stable content first" rule we followed sets up Chapter 5's caching. The project_instructions slot is filled by Chapter 9's memory loader. The skills_summary slot is filled by Chapter 10. The tools list is built by Chapter 6's registry. In other words, this PromptBuilder is the socket that almost every later component plugs into.

03.12

Key takeaways

  • A model request has three parts worth knowing: layered instructions, a list of tools (JSON schemas), and an input list of structured conversation items.
  • Roles carry authority, in order: system, developer, user, assistant.
  • Store history as typed items, and link each tool call to its result with a shared call_id so the model understands cause and effect.
  • Put stable content (instructions, tools) first and variable content (the latest message) last. This is what makes caching possible.
  • The model only knows what is in the prompt. Brief it like a sharp colleague who just walked into the room.

Original sources: OpenAI's Unrolling the Codex agent loop and Jonathan Fulton's "Inside the Agent Harness" analysis of the Codex codebase.


0 of 12 slides completed

Your learning progress stays in this browser.

Self-check · 5 questions

01 / 05

What is the correct authority ordering for roles in a model request?

Related chapters