Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(claude-cli): a tool loop turn reads the previous turn's prompt cache

garrytan54b9d2ada609
diff --git a/src/core/ai/providers/claude-cli-language-model.ts b/src/core/ai/providers/claude-cli-language-model.ts
index 2bf3f97587..8037f23428 100644
--- a/src/core/ai/providers/claude-cli-language-model.ts
+++ b/src/core/ai/providers/claude-cli-language-model.ts
@@ -107,7 +107,7 @@ export function resolveHermeticConfigDir(
return v;
}
-/** Parsed shape of `claude --print --output-format json`. */
+/** Parsed shape of the result event `claude --print` emits. */
interface ClaudeJsonResult {
type: 'result';
subtype: 'success' | string;
@@ -153,18 +153,25 @@ type EnvelopeParse =
| { ok: false; reason: 'no-result-event' };
/**
- * Unwrap `--output-format json` stdout into the result envelope and the event
- * array it came in. `runClaude` passes `--verbose` (#6791), so the CLI emits
- * [{type:"system",subtype:"init",...}, ..., {type:"result",...}]; the bare
- * result object (events null) is still accepted. The array shape was verified on
- * CLI 2.1.145; that it carries every assistant message, in the 2.1.296 bundle.
+ * Unwrap the CLI's stdout into the result envelope and the event array it came
+ * in. `runClaude` passes `--output-format stream-json --verbose` (#7352,
+ * #6791), so the CLI prints one event per line: {type:"system",...}, the
+ * assistant messages, then {type:"result",...}; verified on CLI 2.0.60 and
+ * 2.1.319. A single JSON document (the `--output-format json` event array, or
+ * a bare result object with events null) is still accepted.
*/
function parseResultEnvelope(stdout: string): EnvelopeParse {
let parsed: unknown;
try {
parsed = JSON.parse(stdout);
} catch (error) {
- return { ok: false, reason: 'not-json', error };
+ try {
+ const lines = stdout.split('\n').filter(line => line.trim().length > 0);
+ if (lines.length < 2) return { ok: false, reason: 'not-json', error };
+ parsed = lines.map(line => JSON.parse(line));
+ } catch {
+ return { ok: false, reason: 'not-json', error };
+ }
}
const events = Array.isArray(parsed) ? parsed : null;
if (Array.isArray(parsed)) {
@@ -279,13 +286,15 @@ function buildToolUseInstructions(
}
/**
- * Render the ai-sdk message array into a single text prompt for `claude --print`
- * stdin. System messages are extracted up-front and concatenated into the
- * `--system-prompt` flag value. Tool calls and tool results are rendered as
+ * Render the ai-sdk message array into one text block per conversation message
+ * for `claude --print` stdin (#7352: the CLI's prompt cache matches at block
+ * boundaries, so a tool loop's next turn reads this turn's cache only when this
+ * turn's blocks are an unchanged prefix of it). System messages are extracted
+ * up-front and concatenated into the `--system-prompt` flag value. Tool calls and tool results are rendered as
* placeholders so the model sees the conversation in a coherent shape even
* though the adapter does not natively round-trip tool calls through claude-cli.
*/
-function renderPrompt(prompt: LanguageModelV2Prompt): { systemText: string; userPrompt: string } {
+function renderPrompt(prompt: LanguageModelV2Prompt): { systemText: string; userBlocks: string[] } {
const systemParts: string[] = [];
const convo: string[] = [];
@@ -339,7 +348,7 @@ function renderPrompt(prompt: LanguageModelV2Prompt): { systemText: string; user
}
}
- return { systemText: systemParts.join('\n'), userPrompt: convo.join('\n\n') };
+ return { systemText: systemParts.join('\n'), userBlocks: convo };
}
/** Oldest claude CLI that accepts every flag `runClaude` passes (probed:
@@ -376,12 +385,12 @@ export function thinkingDisabledBelowFloor(maxOutputTokens: number | undefined):
/**
* Spawn `claude --print` with the contamination-suppression flags and return
- * the parsed `--output-format json` envelope. Aborts propagate to SIGTERM on
+ * the parsed result envelope. Aborts propagate to SIGTERM on
* the child.
*/
function runClaude(
systemPrompt: string,
- userPrompt: string,
+ userBlocks: string[],
model: string,
signal?: AbortSignal,
maxOutputTokens?: number,
@@ -398,10 +407,13 @@ function runClaude(
: '{"disableAllHooks":true}';
const args = [
'--print',
- // #6791: --verbose turns the json output into the session's event
- // array, the only record of the segments before an automatic
- // continuation (the envelope's result holds the last one).
- '--output-format', 'json', '--verbose',
+ // #7352: one user message whose content blocks are the conversation's
+ // messages, read as stream-json; the CLI then answers in stream-json.
+ // #6791: --verbose keeps the session's events in that output, the only
+ // record of the segments before an automatic continuation (the
+ // envelope's result holds the last one).
+ '--input-format', 'stream-json',
+ '--output-format', 'stream-json', '--verbose',
'--model', model,
'--disable-slash-commands',
// Agent isolation: this subprocess must behave like a raw LLM, not a
@@ -542,7 +554,7 @@ function runClaude(
// error itself is safe to swallow.
child.stdin.on('error', () => { /* surfaced via child 'error'/'close' */ });
try {
- child.stdin.write(userPrompt);
+ child.stdin.write(JSON.stringify({ type: 'user', message: { role: 'user', content: userBlocks.map(text => ({ type: 'text', text: text.toWellFormed() })) } }) + '\n');
child.stdin.end();
} catch (e) {
if (signal) signal.removeEventListener('abort', onAbort);
@@ -728,11 +740,11 @@ export class ClaudeCliLanguageModel implements LanguageModelV2 {
providerMetadata?: SharedV2ProviderMetadata;
warnings: never[];
}> {
- const { systemText, userPrompt } = renderPrompt(options.prompt);
+ const { systemText, userBlocks } = renderPrompt(options.prompt);
const toolInstructions = buildToolUseInstructions(options.tools);
const systemPrompt = [systemText, toolInstructions].filter(s => s.length > 0).join('\n');
- const result = await runClaude(systemPrompt, userPrompt, this.modelId, options.abortSignal, options.maxOutputTokens);
+ const result = await runClaude(systemPrompt, userBlocks, this.modelId, options.abortSignal, options.maxOutputTokens);
// The CLI reports Anthropic's separate buckets; LanguageModelV2Usage wants
// the TOTAL input with the cache read as a subset (what every SDK provider
// reports), so the gateway prices cache tokens once. Cache creation has no
diff --git a/test/claude-cli-prompt-cache-7352.test.ts b/test/claude-cli-prompt-cache-7352.test.ts
new file mode 100644
index 0000000000..b25ecafa7b
--- /dev/null
+++ b/test/claude-cli-prompt-cache-7352.test.ts
@@ -0,0 +1,114 @@
+/**
+ * #7352 — a claude-cli tool loop must let turn N+1 read turn N's prompt
+ * cache. The CLI caches at content-block boundaries, so a prompt sent as one
+ * growing text block never shares a boundary with the previous turn and every
+ * turn re-writes the whole transcript to the cache. The adapter sends one
+ * block per conversation message (`--input-format stream-json`), so turn N's
+ * blocks are an unchanged prefix of turn N+1's, and reads the CLI's
+ * stream-json (NDJSON) output. Hermetic: a stub binary records stdin and argv.
+ */
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import { writeFileSync, chmodSync, mkdirSync, rmSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import type { LanguageModelV2CallOptions } from '@ai-sdk/provider';
+import { withEnv } from './helpers/with-env.ts';
+
+const stubDir = join(tmpdir(), `claude-cli-cache-stub-${process.pid}`);
+const stubBin = join(stubDir, 'claude');
+const stdinLog = join(stubDir, 'stdin.log');
+const argvLog = join(stubDir, 'argv.log');
+const responsePath = join(stubDir, 'response.txt');
+
+beforeAll(() => {
+ mkdirSync(stubDir, { recursive: true });
+ writeFileSync(stubBin, ['#!/bin/sh', `cat > "${stdinLog}"`, `printf "%s\\n" "$@" > "${argvLog}"`, `cat "${responsePath}"`].join('\n'));
+ chmodSync(stubBin, 0o755);
+});
+
+afterAll(() => rmSync(stubDir, { recursive: true, force: true }));
+
+const result = (text: string) => ({
+ type: 'result', subtype: 'success', is_error: false, result: text, stop_reason: 'end_turn',
+ session_id: 's', num_turns: 1, usage: { input_tokens: 10, output_tokens: 2, cache_read_input_tokens: 900, cache_creation_input_tokens: 20 },
+});
+
+/** What the real CLI prints under --output-format stream-json --verbose: one event per line. */
+function streamJson(text: string): string {
+ return [
+ { type: 'system', subtype: 'init', session_id: 's' },
+ { type: 'assistant', message: { id: 'msg_1', type: 'message', role: 'assistant', model: 'claude-sonnet-5-5', content: [{ type: 'text', text }], stop_reason: null }, parent_tool_use_id: null, session_id: 's' },
+ result(text),
+ ].map(e => JSON.stringify(e)).join('\n') + '\n';
+}
+
+async function generate(prompt: LanguageModelV2CallOptions['prompt']) {
+ const { ClaudeCliLanguageModel } = await import('../src/core/ai/providers/claude-cli-language-model.ts');
+ return new ClaudeCliLanguageModel('claude-sonnet-5-5').doGenerate({ prompt } as LanguageModelV2CallOptions);
+}
+
+function sentBlocks(): string[] {
+ const lines = readFileSync(stdinLog, 'utf8').split('\n').filter(Boolean);
+ expect(lines).toHaveLength(1);
+ const msg = JSON.parse(lines[0]!);
+ expect(msg).toMatchObject({ type: 'user', message: { role: 'user' } });
+ return msg.message.content.map((b: { type: string; text: string }) => { expect(b.type).toBe('text'); return b.text; });
+}
+
+const turnN: LanguageModelV2CallOptions['prompt'] = [
+ { role: 'system', content: 'You are a test agent.' },
+ { role: 'user', content: [{ type: 'text', text: 'Find the page.' }] },
+ { role: 'assistant', content: [{ type: 'tool-call', toolCallId: 't1', toolName: 'search', input: { query: 'acme-example' } }] },
+ { role: 'tool', content: [{ type: 'tool-result', toolCallId: 't1', toolName: 'search', output: { type: 'text', value: 'companies/acme-example' } }] },
+] as LanguageModelV2CallOptions['prompt'];
+const turnN1 = [...turnN,
+ { role: 'assistant', content: [{ type: 'tool-call', toolCallId: 't2', toolName: 'get_page', input: { slug: 'companies/acme-example' } }] },
+ { role: 'tool', content: [{ type: 'tool-result', toolCallId: 't2', toolName: 'get_page', output: { type: 'text', value: 'Acme Example page' } }] },
+] as LanguageModelV2CallOptions['prompt'];
+
+describe('claude-cli tool loops reuse the previous turn prompt cache (#7352)', () => {
+ test('one block per message; turn N is an unchanged prefix of turn N+1', async () => {
+ await withEnv({ GBRAIN_CLAUDE_CLI_BIN: stubBin }, async () => {
+ writeFileSync(responsePath, streamJson('ok'));
+ await generate(turnN);
+ const first = sentBlocks();
+ await generate(turnN1);
+ const second = sentBlocks();
+ expect(first.length).toBe(3);
+ expect(second.length).toBe(5);
+ expect(second.slice(0, first.length)).toEqual(first);
+ expect(first[0]).toBe('User: Find the page.');
+ const argv = readFileSync(argvLog, 'utf8').split('\n');
+ expect(argv[argv.indexOf('--input-format') + 1]).toBe('stream-json');
+ expect(argv[argv.indexOf('--output-format') + 1]).toBe('stream-json');
+ expect(argv).toContain('--verbose');
+ });
+ });
+
+ test('the stream-json result event is read: text and cache usage', async () => {
+ await withEnv({ GBRAIN_CLAUDE_CLI_BIN: stubBin }, async () => {
+ writeFileSync(responsePath, streamJson('the answer'));
+ const res = await generate(turnN);
+ expect(res.content).toEqual([{ type: 'text', text: 'the answer' }]);
+ expect(res.usage.cachedInputTokens).toBe(900);
+ expect(res.usage.inputTokens).toBe(930);
+ });
+ });
+
+ test('a lone surrogate (a page cut mid-emoji) reaches the CLI as U+FFFD, as the raw stdin write did', async () => {
+ await withEnv({ GBRAIN_CLAUDE_CLI_BIN: stubBin }, async () => {
+ writeFileSync(responsePath, streamJson('ok'));
+ await generate([{ role: 'user', content: [{ type: 'text', text: 'ship it \ud83d' }] }] as LanguageModelV2CallOptions['prompt']);
+ expect(sentBlocks()).toEqual(['User: ship it \ufffd']);
+ expect(readFileSync(stdinLog, 'utf8')).not.toContain('\\ud83d');
+ });
+ });
+
+ test('an error result in the stream still surfaces as a typed error', async () => {
+ await withEnv({ GBRAIN_CLAUDE_CLI_BIN: stubBin }, async () => {
+ writeFileSync(responsePath, JSON.stringify({ type: 'system', subtype: 'init' }) + '\n'
+ + JSON.stringify({ ...result('API Error: rate limited'), is_error: true, subtype: 'error', api_error_status: 429 }) + '\n');
+ await expect(generate(turnN)).rejects.toMatchObject({ name: 'ClaudeCliProcessError', apiErrorStatus: 429 });
+ });
+ });
+});
diff --git a/test/claude-cli-recipe.test.ts b/test/claude-cli-recipe.test.ts
index 0c92235616..10a6380ef4 100644
--- a/test/claude-cli-recipe.test.ts
+++ b/test/claude-cli-recipe.test.ts
@@ -766,8 +766,9 @@ describe('claude-cli LanguageModel — context isolation', () => {
const cwd = fs.readFileSync(cwdLog, 'utf8').trim();
expect(argv).toContain('--print');
- expect(argv).toContain('--output-format');
- expect(argv).toContain('json');
+ expect(argv[argv.indexOf('--input-format') + 1]).toBe('stream-json');
+ expect(argv[argv.indexOf('--output-format') + 1]).toBe('stream-json');
+ expect(argv).toContain('--verbose');
expect(argv).toContain('--disable-slash-commands');
// Agent-isolation hardening: no built-in tools, no inherited MCP servers.
expect(argv).toContain('--tools');
diff --git a/test/claude-cli-stop-reason.test.ts b/test/claude-cli-stop-reason.test.ts
index 0d5520b2a3..b91ec5ec49 100644
--- a/test/claude-cli-stop-reason.test.ts
+++ b/test/claude-cli-stop-reason.test.ts
@@ -72,7 +72,7 @@ describe('claude-cli replays earlier tool calls with their arguments (#6236)', (
],
} as LanguageModelV2CallOptions);
});
- const sent = readFileSync(stdinPath, 'utf8');
+ const sent = (JSON.parse(readFileSync(stdinPath, 'utf8')).message.content as Array<{ text: string }>).map(b => b.text).join('\n');
expect(sent).toContain('[tool_use brain_get_page({"slug":"wiki/personal/patterns/x"})]');
expect(sent).not.toContain('[object Object]');
});