OpenCode 2.3.2 Tested: GPT-6.2 Doesn't Cache instructions, So the System Prompt Moves to a Leading Developer Message
Short answer: starting with GPT-6.2, the Responses API appends the top-level instructions field after input, beyond the cache breakpoints. Even when the text is identical every time, it is billed at the uncached rate.[4][5] OpenCode had always sent its system prompt in instructions, so on GPT-6.2 every step paid full price for more than ten thousand tokens of system prompt. Version 2.3.2 (released November 18, 01:35 UTC) sends it as the first developer message in input instead, which caches from the second step on. On GitHub Copilot’s gpt-6.2-sol, uncached input per step dropped from 14,163 tokens to 3.[1][3]
| Your situation | What to do |
|---|---|
| You use GPT-6.2 in OpenCode (API key, ChatGPT sign-in, Copilot, Zen, Azure, OpenRouter) | Upgrade to 2.3.2: opencode upgrade, or npm i -g @opencode/cli@latest, or curl -fsSL https://opencode.ai/v2/install | bash. No config change needed. |
You run a custom router configured with a V1 provider block and "npm": "@ai-sdk/openai-compatible" | That path goes through the AI SDK and is outside this fix. Switch to a V2 providers block with package set to @opencode/ai/providers/openai-compatible/responses.[10] |
| A gateway such as LiteLLM sits in between and turns your calls into Responses requests | The gateway needs its own fix. LiteLLM fixed it in v1.108.13, v1.110.2 and other release lines. Claude Code going through LiteLLM to GPT-6.2 was affected too.[8] |
| You call the Responses API from your own code | Put the stable system prompt in a developer message at the start of input. Keep instructions for guidance that applies to this one request, such as “summarize on the final turn”. |
| You use GPT-6.1 or older | Both shapes cache. Upgrading changes nothing for you.[2] |

Prefix caching only matches an identical beginning
When a model processes input, it computes intermediate state for every token (the KV cache). If the next request starts with exactly the same tokens, the server can reuse that state and only compute what was added. The reused part is billed at the cache rate. On GPT-6.2 Sol and Astra a cache read costs 0.05× ordinary input, and a write costs 1.25× (30-minute lifetime) or 2.5× (12 hours).[4] So the longer and steadier the opening of each request an agent sends, the smaller the bill.
“Same beginning” means the rendered token sequence matches token by token. Meaning doesn’t count. Change one character and everything after it is gone. OpenAI looks for a few lookup boundaries in the request and tries them from longest to shortest to see which prefix is already cached. In implicit mode on GPT-5.6 and later, those boundaries include the end of the latest eligible message, up to 20 earlier message endings, and the endpoint of the initial consecutive block of developer messages.[4] That last one matters most here: as long as the system prompt is the leading developer message, it can hit the cache on its own even if the whole conversation after it changes.
On GPT-6.2, instructions sits at the opposite end. The docs say models from GPT-6.2 on append it after input, so you can change it between turns without breaking the earlier cache. The price is that it always lands past the breakpoints, is billed uncached every time, and cannot carry an explicit breakpoint.[4][5] The design makes sense on its own terms. instructions was always meant for guidance that applies to a single request. The trouble is that most clients had been stuffing the entire system prompt there, and up to GPT-6.1 that cached exactly like a developer message, so nobody saw a reason to tell them apart.
Nothing fails. Requests succeed and the bill quietly grows. LiteLLM’s write-up is blunt about it: OpenAI updated its docs on November 17, none of their alerts fired, and they found out on November 18 when a customer asked why cache hits were missing.[8] One more trap: OpenAI’s cache diagnostics (prompt_cache_options.comparison_response_id) report cache_hit on instructions requests while cached_tokens and cache_write_tokens in usage are both 0.[2][9] Trust usage.
What changed in the requests between 2.3.1 and 2.3.2
With OpenCode pointed at a local mock server, model openai/gpt-6.2-sol, two turns with one tool call each, the captured requests look like this.

In 2.3.1, instructions holds an 11,325-character system prompt and input[0] is the user message. In 2.3.2 there is no instructions. input[0] is a developer message with the same 11,325 characters and the same hash. The 12 tool declarations (14,976 characters) are identical in both versions and still sit in top-level tools. Every step is the previous request plus new items. Concatenate tools, system prompt and input in that order, and each step’s full text is the start of the next one, in both versions.
So 2.3.2 changes exactly one thing: where the system prompt goes. Not a byte of the text changed. On GPT-6.1 the two requests cache the same way. On GPT-6.2 the first one pays full price for those 11k characters on every step.
The same comparison on xai/grok-4.7 and on a custom router (V2 providers block, package set to @opencode/ai/providers/openai-compatible/responses) gives the same result: 2.3.1 uses instructions, 2.3.2 uses a leading developer message. That matches how the two PRs split the work. #64542 changed OpenAI’s own Responses route first. #64544 moved the change down into OpenResponses.lowerConversation, which every Responses route shares, so Copilot, xAI, OpenRouter, Vercel AI Gateway and custom OpenAI-compatible servers all follow.[2][3]
A mock can’t show real billing, so the numbers come from the PR author’s measurements. With ChatGPT sign-in, gpt-6.2-sol, and three short prompts in one session, uncached input per step went from 16,969, 16,992 and 14,457 to 16,969, 352 and 121.[2] With raw API-key requests, the instructions shape cached 0 tokens on all four steps. The developer-message shape cached 9,632, 9,660 and 9,691 tokens from the second step on.[2]
Two configurations gain nothing from the upgrade. One is a V1 provider block with "npm": "@ai-sdk/openai-compatible". That path calls /chat/completions with the system prompt as messages[0], so instructions never comes into it. The other is a V1 block that sets package but keeps npm: V2 takes the runtime only from npm and ignores package. That was the case in #64783. The user still saw 10k to 20k uncached tokens per round on 2.3.2, and after switching to the V2 syntax it dropped to about 6k.[10]
{
"providers": {
"myrouter": {
"package": "@opencode/ai/providers/openai-compatible/responses",
"settings": { "baseURL": "https://router.example.com/v1", "apiKey": "{env:ROUTER_KEY}" },
"models": { "gpt-sol": { "limit": { "context": 1050000, "output": 128000 }, "body": { "store": false } } }
}
}
}
How much of the prefix survives compaction
Compaction is the natural enemy of caching. OpenAI’s docs say so directly: summarization, compaction or truncation can change the prefix and reset cache reuse.[4] The best a client can do is rewrite only the history and leave the system prompt and tools in front alone.

With 2.3.2’s context window set to 20,000 and the mock reporting a growing token count, auto compaction kicks in. With compaction.type set to native, OpenCode doesn’t open a separate request. It appends a compaction_trigger item to the normal /responses request and keeps everything before it, so that step still extends the previous one. The request after compaction is [developer, first user, user, compaction]: the system prompt, the tools and the first user message are all still there, and the difference starts at input[2]. Typing /compact in the TUI takes the same path.
With summary, the request that writes the summary is the full prefix plus a user message starting “You MUST summarize the conversation above…”, so it can reuse the cache. What’s left afterwards is [developer, user "<conversation-checkpoint>…"], with the system prompt and tools unchanged. In 2.3.1 both modes have the same shape, just with the system prompt still in instructions.
The release notes say /responses/compact now reads the same cached prefix too.[1] #64544 reports that on gpt-6.2-sol a compact request with instructions read 0 cached tokens, while one with the developer message read 2,962 of 3,190.[3] None of the local compaction runs reached that endpoint, so this part wasn’t observed directly.
How the others order their prefixes
The same mock also served Codex CLI 0.171.0, Claude Code 2.1.330, Gemini CLI 0.70.0 and Qwen Code 0.28.3. None of them put the system prompt in instructions, but each lays out the prefix differently.
| Protocol | System prompt | Tool declarations | Cache markers | Prefix after compaction | |
|---|---|---|---|---|---|
| OpenCode 2.3.2 | Responses | input[0] developer (11,325 chars) | top-level tools (12) | none, implicit boundaries | system and tools unchanged, history rewritten |
| Codex 0.171.0 | Responses | four developer messages at input[1..4] | additional_tools item at input[0] | none | same content, every item id regenerated |
| Claude Code 2.1.330 | Messages | top-level system, three blocks | top-level tools (12) | system[1], system[2], last message | billing header in system[0] changes, rest unchanged |
| Gemini CLI 0.70.0 | generateContent | top-level systemInstruction (30,747 chars) | top-level tools | none, no cachedContent | not tested |
| Qwen Code 0.28.3 | Chat Completions | messages[0] system (22,432 chars) | top-level tools (10) | none | not tested |
Codex never sends instructions and has no top-level tools. With incremental_tools on, tool declarations go into an additional_tools item at input[0], in three groups (functions, clock, collaboration) totaling 26,071 characters. Four developer messages follow (the first is 26,194 characters), then a user message with environment context, and only then the user’s prompt. This is the layout #64542 describes: when tools are declared in a leading additional_tools item, the system prompt goes right after it.[2] Every step, and codex exec resume, appends to the previous request. 0.170.0 turned incremental tool declarations on by default for GCP and 0.171.0 did the same for Bedrock. 0.171.0 also keeps active additional context across compaction.[11][12]

With model_auto_compact_token_limit set to 9,000 to force auto compaction, Codex rebuilt the initial context. The text of the tools and developer messages is identical, but every item id (at_…, msg_…) is freshly generated. Ignoring ids, the first 7 items match exactly. Whether item ids end up in the token sequence the model sees can’t be judged locally. If they don’t, the post-compaction prefix stays reusable. Also note that OpenAI’s docs say additional_tools items don’t accept prompt_cache_breakpoint, so an explicit breakpoint for tools has to go on the developer message after them.[4]
Claude Code speaks Anthropic Messages. Anthropic’s cache prefix order is fixed as tools, system, messages, with up to 4 breakpoints and a 20-block lookback from each.[6] Claude Code’s system has three blocks: a 74-character x-anthropic-billing-header: cc_version=2.1.330.581; cc_entrypoint=sdk-cli;, a 62-character identity line, and the 7,077-character body. cache_control is set on the second and third blocks and on the last message, not on the tools. Environment details are not in system. They go in a message with role system (9.4k characters) inserted after the first user message, and the request carries beta flags such as mid-conversation-tool-changes. That keeps the working directory, platform and similar details away from the system prompt in front.

On a manual /compact, the summary request appends “CRITICAL: Respond with TEXT ONLY…” to the last user message and keeps the full prefix. After compaction the tools and the system body are unchanged. The only difference is the number in the first block’s billing header, which went from .581 to .232, the same pair of values in two separate sessions. Auto compaction behaves the same way: 2.1.328 fixed auto compaction reusing the old system prompt, and it now rebuilds the system prompt the way /compact does.[13] That billing header sits at the very front of system. Whether it counts toward the cached prefix can only be seen with a real account.

Testing auto compaction also surfaced a warning. With the mock reporting 150,000 input tokens on every step and CLAUDE_AUTOCOMPACT_PCT_OVERRIDE set to 10, Claude Code compacted a few times in a row and then stopped with “Autocompact is thrashing: the context refilled to the limit within 3 turns of the previous compact, 3 times in a row”. If you see that in real use, a file or tool output is probably too large.
Gemini CLI keeps a 30,747-character systemInstruction and 16,002 characters of tool declarations as top-level fields. They stay the same on every step and after --resume latest, contents only grows, and there’s no explicit cachedContent. It relies on the implicit caching that’s on by default from Gemini 2.5. Google’s docs recommend putting large common content at the start, which is what it does.[7] Before each turn it also runs two routing calls on gemini-3.5-flash-lite with a 2,346-character system prompt and no tools, a separate prefix of its own.
Qwen Code uses Chat Completions. The system prompt is messages[0] (22,432 characters), 10 tools sit at the top level, and there’s no cache_control anywhere, so caching depends entirely on the backend. The main loop keeps appending after --continue. But after each turn it runs a “managed memory extraction” subagent with a different 14,683-character system prompt and only 5 tools. That call starts from scratch every time and doesn’t share the main loop’s cache. The inject mode added in 0.28.3 delivers new messages into the running turn, read at the next tool-batch boundary, which also appends rather than rewrites.[14]

Goose 1.60.1 changed its compaction prompt to drop the <analysis> scratchpad that Claude models refuse.[15] It wasn’t tested this time.
What to copy when you build an agent
Put the five side by side and they follow the same idea: stable things go first, things that change go later, and compaction rewrites only the history. OpenCode 2.3.2 and Codex use a leading developer message, Claude Code uses system blocks with explicit breakpoints, Gemini uses top-level fields. They’re all protecting the same stretch of prefix with whatever their API offers.
If you’re writing your own agent, three things carry over directly. First, on GPT-6.2 stop putting a long system prompt in instructions. It’s a regression that raises no error, and you’ll only catch it by watching usage.cached_tokens. Second, keep the date, working directory, git status and anything else that can change per request out of the system prompt. Claude Code puts it in a system message after the first user message, Codex in a separate user message, both so the part in front stays untouched. Third, side calls such as title generation, routing and memory extraction each carry their own prefix. When they run often, they’re a line item worth checking on their own.
The previous issue covered OpenCode 2.3 moving subagents, timed-out commands and compaction to the background. Whether compaction saves money at all can be worked out with the Claude Haiku 5.5 subagent and compaction cost model. For keeping coding-agent spend in check at the team level, see enterprise coding-agent routing and governance. For the overall structure of Claude Code’s core loop, see the Agent Harness pattern.
What was tested and what wasn’t
Tested (Linux x64, every CLI pointed at a local mock server, no real accounts):

- OpenCode 2.3.1 and 2.3.2: system prompt placement and per-step prefixes on
openai/gpt-6.2-sol,xai/grok-4.7and a custom Responses router. Also the V1providerblock and OpenRouter going through Chat Completions,nativeandsummaryauto compaction, and manual/compactin the TUI. - Codex CLI 0.171.0: a custom provider (
wire_api = "responses"),exec,exec resumeand one auto compaction. - Claude Code 2.1.330: two turns, manual
/compact, auto compaction. - Gemini CLI 0.70.0 and Qwen Code 0.28.3: one turn plus a resumed session.
Not tested:
- Any real billing or cache hits. The mock only shows what requests look like. Every token and cache-hit number in this post comes from PRs, issues and official docs.
- The
/responses/compactendpoint, and the real Copilot, Zen and Azure routes. OpenCode’s built-in OpenRouter provider went through Chat Completions locally, and whether it normally uses Responses wasn’t confirmed. - Codex incremental tool declarations on GCP and Bedrock, and whether Codex item ids affect caching.
- Whether Claude Code’s billing header counts toward the cached prefix.
- Compaction in Gemini CLI and Qwen Code, and Qwen’s inject mode.
- Goose 1.60.2, Aider 0.86.0, Kimi CLI 1.52.0, Cursor CLI and Amp were not run this time.
References
- OpenCode v2.3.2 changelog: https://opencode.ai/changelog/v2.3.2, GitHub release: https://github.com/anomalyco/opencode/releases/tag/v2.3.2 ↩
- OpenCode PR #64542, send the OpenAI system prompt as a developer message: https://github.com/anomalyco/opencode/pull/64542 ↩
- OpenCode PR #64544, send the system prompt as a developer message on every Responses route: https://github.com/anomalyco/opencode/pull/64544 ↩
- OpenAI docs, Prompt caching: https://developers.openai.com/api/docs/guides/prompt-caching ↩
- OpenAI docs, Using GPT-6.2: https://developers.openai.com/api/docs/guides/latest-model ↩
- Anthropic docs, Prompt caching: https://platform.claude.com/docs/en/build-with-claude/prompt-caching ↩
- Google docs, Gemini API context caching: https://ai.google.dev/gemini-api/docs/caching ↩
- LiteLLM, Cost Update: OpenAI’s GPT-6.2 caching change may increase input costs: https://docs.litellm.ai/blog/gpt-6-2-instructions-caching-incident ↩
- openai/codex issue #62312: https://github.com/openai/codex/issues/62312 ↩
- OpenCode issue #64783: https://github.com/anomalyco/opencode/issues/64783 ↩
- Codex rust-v0.170.0 release notes: https://github.com/openai/codex/releases/tag/rust-v0.170.0 ↩
- Codex rust-v0.171.0 release notes: https://github.com/openai/codex/releases/tag/rust-v0.171.0 ↩
- Claude Code v2.1.328 to v2.1.330 release notes: https://github.com/anthropics/claude-code/releases/tag/v2.1.328, https://github.com/anthropics/claude-code/releases/tag/v2.1.330 ↩
- Qwen Code v0.28.3 release notes: https://github.com/QwenLM/qwen-code/releases/tag/v0.28.3 ↩
- Goose v1.60.1 release notes: https://github.com/block/goose/releases/tag/v1.60.1 ↩