@@ -157,8 +157,41 @@ function finalizeAgentBlocks(blocks) {
  *          onToolStart?:(name:string)=>void}} opts
  * @returns {Promise<{content:any[], stop_reason:string}>}
  */
+/**
+ * [LevelCode] Return a shallow copy of the transcript with a cache_control breakpoint on the LAST
+ * message's last content block. Combined with the cached system block below, this caches the whole
+ * growing transcript: turn N writes it, turn N+1 reads it (cached input bills ~0.1x). Anthropic allows
+ * 4 breakpoints; we use 2 (system + this). Messages with empty content are skipped.
+ */
+function withRollingCacheBreakpoint(messages) {
+	const arr = Array.isArray(messages) ? messages.slice() : [];
+	for (let i = arr.length - 1; i >= 0; i--) {
+		const m = arr[i];
+		if (!m) { continue; }
+		let content = m.content;
+		if (typeof content === 'string') {
+			if (!content) { continue; }
+			content = [{ type: 'text', text: content, cache_control: { type: 'ephemeral' } }];
+		} else if (Array.isArray(content) && content.length) {
+			content = content.slice();
+			content[content.length - 1] = { ...content[content.length - 1], cache_control: { type: 'ephemeral' } };
+		} else {
+			continue;
+		}
+		arr[i] = { ...m, content };
+		break;
+	}
+	return arr;
+}
+
 async function streamClaudeAgentTurn(opts) {
-	const body = { model: opts.model, max_tokens: opts.maxTokens, system: opts.system, messages: opts.messages, stream: true };
+	// [LevelCode] Prompt caching — the real token/$ saver. tools + system are byte-identical every turn
+	// and the transcript only grows, so cache them: a breakpoint on the system block caches tools+system;
+	// a rolling breakpoint on the last message caches the prior transcript. Cached input bills ~0.1x vs
+	// full price. Without this an agent loop re-pays FULL input for the entire prefix on every turn.
+	const system = [{ type: 'text', text: String(opts.system || ''), cache_control: { type: 'ephemeral' } }];
+	const messages = withRollingCacheBreakpoint(opts.messages);
+	const body = { model: opts.model, max_tokens: opts.maxTokens, system, messages, stream: true };
 	if (opts.tools && opts.tools.length) { body.tools = opts.tools; }
 	const res = await fetch(ANTHROPIC_URL, {
 		method: 'POST',
 
@@ -19,6 +19,14 @@ const translate = require('./translate');
 /** Trim a trailing slash so `${base}/chat/completions` is always well-formed. */
 function baseUrl(opts) { return String(opts.baseURL || '').replace(/\/+$/, ''); }
 
+/**
+ * [LevelCode] Is this an Anthropic/Claude model reached through an OpenAI-shaped endpoint (OpenRouter
+ * `anthropic/claude-…`, the LevelCode Cloud gateway, or a bare `claude-…`)? Only these honor an explicit
+ * cache_control breakpoint; every other provider auto-caches and would ignore or reject the field, so we
+ * gate the prefix-caching write on this. Cache-hit READ accounting (cached_tokens) is done regardless.
+ */
+function isAnthropicFamily(model) { return /(?:^|\/)claude|(?:^|\/)anthropic\//i.test(String(model || '')); }
+
 /** Auth + content-type + any per-provider headers (e.g. OpenRouter's HTTP-Referer / X-Title). */
 function authHeaders(opts) {
 	const h = Object.assign({ 'content-type': 'application/json' }, opts.headers || {});
@@ -154,7 +162,10 @@ async function listOpenAIModels(opts) {
  */
 async function streamOpenAIAgentTurn(opts) {
 	const label = opts.label || 'OpenAI-compatible';
-	const messages = translate.toOpenAIMessages(opts.system, opts.messages);
+	// [LevelCode] Prompt caching. Only Claude-family upstreams honor cache_control (via OpenRouter / the
+	// LevelCode Cloud gateway); GPT/Gemini/DeepSeek/etc. auto-cache server-side and would ignore or reject
+	// the field, so we gate it strictly on the model id. cached_tokens is still read for ALL providers below.
+	const messages = translate.toOpenAIMessages(opts.system, opts.messages, { cache: isAnthropicFamily(opts.model) });
 	const tools = translate.toOpenAITools(opts.tools);
 	const body = buildChatBody({ model: opts.model, messages, maxTokens: opts.maxTokens, stream: true });
 	if (tools) { body.tools = tools; }
@@ -186,7 +197,14 @@ async function streamOpenAIAgentTurn(opts) {
 		try { ev = JSON.parse(data); } catch { return; }
 		if (ev.error) { const _e = new Error((ev.error && ev.error.message) ? ev.error.message : (label + ' stream error')); if (ev.error && ev.error.code) { _e.code = ev.error.code; } throw _e; }
 		if (ev.usage) {   // opportunistic — only some providers include usage in the stream
-			if (ev.usage.prompt_tokens) { usage.input_tokens = ev.usage.prompt_tokens; }
+			// [LevelCode] Surface prompt caching. OpenAI-shaped providers (OpenAI auto-cache, Claude/Gemini
+			// via OpenRouter, the LevelCode Cloud gateway) report cache hits under prompt_tokens_details.
+			// cached_tokens, and it is INCLUDED in prompt_tokens — so split it out (fresh = prompt - cached)
+			// to mirror Anthropic's disjoint fields and keep the context meter's input+cache_read total exact.
+			const det = ev.usage.prompt_tokens_details || {};
+			const cached = det.cached_tokens || 0;
+			if (ev.usage.prompt_tokens) { usage.input_tokens = Math.max(0, ev.usage.prompt_tokens - cached); }
+			if (cached) { usage.cache_read_input_tokens = cached; }
 			if (ev.usage.completion_tokens) { usage.output_tokens = ev.usage.completion_tokens; }
 		}
 		const c = ev.choices && ev.choices[0];
@@ -203,4 +221,4 @@ async function streamOpenAIAgentTurn(opts) {
 	return { content, stop_reason: stopReason, usage, malformed };
 }
 
-module.exports = { streamOpenAI, completeOpenAI, listOpenAIModels, streamOpenAIAgentTurn, buildChatBody, deltaFromEvent, isReasoningModel };
+module.exports = { streamOpenAI, completeOpenAI, listOpenAIModels, streamOpenAIAgentTurn, buildChatBody, deltaFromEvent, isReasoningModel, isAnthropicFamily };
@@ -54,9 +54,17 @@ function toolResultText(content) {
  * (OpenAI requires the tool responses to immediately follow the assistant's tool_calls), then a
  * trailing {role:'user'} for any plain text in the same message.
  */
-function toOpenAIMessages(system, messages) {
+function toOpenAIMessages(system, messages, opts) {
+	// [LevelCode] opts.cache adds Anthropic-style cache_control breakpoints (system + last message). Only
+	// set for Anthropic-family upstreams (see openaiCompat.isAnthropicFamily) — OpenRouter/the gateway
+	// forward it to Claude; other providers auto-cache and would ignore or reject it.
+	const cache = !!(opts && opts.cache);
 	const out = [];
-	if (system) { out.push({ role: 'system', content: system }); }
+	if (system) {
+		out.push(cache
+			? { role: 'system', content: [{ type: 'text', text: String(system), cache_control: { type: 'ephemeral' } }] }
+			: { role: 'system', content: system });
+	}
 	for (const m of (messages || [])) {
 		if (!m) { continue; }
 		if (m.role === 'assistant') {
@@ -94,9 +102,32 @@ function toOpenAIMessages(system, messages) {
 		}
 		if (trailingText) { out.push({ role: 'user', content: trailingText }); }
 	}
+	if (cache) { markLastOpenAICacheable(out); }
 	return out;
 }
 
+/**
+ * [LevelCode] Put a cache_control breakpoint on the last cacheable message so the transcript prefix is
+ * cached on the next turn. Converts string content to a single text block; skips assistant messages that
+ * carry only tool_calls (content:null). Mutates `out` (freshly built here, so safe).
+ */
+function markLastOpenAICacheable(out) {
+	for (let i = out.length - 1; i >= 0; i--) {
+		const m = out[i];
+		if (!m) { continue; }
+		if (typeof m.content === 'string' && m.content) {
+			m.content = [{ type: 'text', text: m.content, cache_control: { type: 'ephemeral' } }];
+			return;
+		}
+		if (Array.isArray(m.content) && m.content.length) {
+			const last = m.content.length - 1;
+			m.content[last] = { ...m.content[last], cache_control: { type: 'ephemeral' } };
+			return;
+		}
+		// content:null (assistant tool_calls-only) → fall through to the previous message
+	}
+}
+
 /** OpenAI finish_reason → Anthropic stop_reason. */
 function fromOpenAIFinishReason(reason) {
 	if (reason === 'tool_calls' || reason === 'function_call') { return 'tool_use'; }
 
@@ -222,4 +222,43 @@ test('end-to-end: streamed edit_file call assembles into a canonical tool_use bl
 	assert.strictEqual(content[1].id, 'call_9');
 });
 
+// ---- [LevelCode] prompt-caching breakpoints (opts.cache) ----
+test('toOpenAIMessages: no cache opt → system stays a plain string (legacy shape unchanged)', () => {
+	const out = T.toOpenAIMessages('SYS', [{ role: 'user', content: 'hi' }]);
+	assert.strictEqual(out[0].content, 'SYS');
+	assert.strictEqual(out[1].content, 'hi');
+});
+
+test('toOpenAIMessages: cache:true → cache_control on the system block AND the last message', () => {
+	const out = T.toOpenAIMessages('SYS', [{ role: 'user', content: 'hi' }], { cache: true });
+	assert.ok(Array.isArray(out[0].content));                                  // system → block form
+	assert.strictEqual(out[0].content[0].text, 'SYS');
+	assert.deepStrictEqual(out[0].content[0].cache_control, { type: 'ephemeral' });   // caches tools+system upstream
+	const last = out[out.length - 1];
+	assert.ok(Array.isArray(last.content));
+	assert.deepStrictEqual(last.content[last.content.length - 1].cache_control, { type: 'ephemeral' }); // rolling transcript breakpoint
+});
+
+test('toOpenAIMessages: cache:true → rolling breakpoint lands on the last tool_result message', () => {
+	const msgs = [
+		{ role: 'user', content: 'do it' },
+		{ role: 'assistant', content: [{ type: 'tool_use', id: 'call_1', name: 'read_file', input: { path: 'x' } }] },
+		{ role: 'user', content: [{ type: 'tool_result', tool_use_id: 'call_1', content: 'file body' }] }
+	];
+	const out = T.toOpenAIMessages('SYS', msgs, { cache: true });
+	const last = out[out.length - 1];
+	assert.strictEqual(last.role, 'tool');                                     // tool_result → {role:'tool'}
+	assert.deepStrictEqual(last.content[0].cache_control, { type: 'ephemeral' });
+});
+
+test('isAnthropicFamily: gates cache_control writes to Claude upstreams only', () => {
+	const O = require('../providers/openaiCompat');
+	assert.strictEqual(O.isAnthropicFamily('anthropic/claude-sonnet-4-6'), true);
+	assert.strictEqual(O.isAnthropicFamily('claude-opus-4-8'), true);
+	assert.strictEqual(O.isAnthropicFamily('openai/gpt-4o'), false);
+	assert.strictEqual(O.isAnthropicFamily('deepseek/deepseek-chat'), false);
+	assert.strictEqual(O.isAnthropicFamily('moonshotai/kimi-k2.7-code'), false);
+	assert.strictEqual(O.isAnthropicFamily(''), false);
+});
+
 console.log('\ntranslate: ' + n + ' tests passed.');