feat(prompt): split static system prompt from dynamic env reminder for cache hits

Pi-ai applies Anthropic-style cache_control to our entire system prompt,
but it was one block — date / cwd / git status all baked in. Every git
edit or day rollover blew the cache, costing full input tokens on every
turn.

Move the dynamic environment block out of the system prompt entirely:

- buildSystemPrompt() now produces only static content (identity, tone,
  anti-patterns, verification, conversation conventions, task checklist,
  available tools). Byte-stable across sessions for the same tool set.

- buildEnvironmentReminder() produces a <system-reminder> block with
  cwd, platform, host, date, and git branch + dirty file summary.

- App.tsx prepends the env reminder to the user's text on the first
  agent turn of each session (detected by zero assistant messages in the
  transcript). Subsequent turns inherit it via cached conversation
  history. Resumed sessions skip injection — the saved env from the
  previous session is already in the loaded transcript.

- runPlanFlow accepts an optional envReminderForFirstTurn that gets
  glued onto the buildAgentPrompt() output before bundle.agent.prompt(),
  same shape as the direct path.

Cache impact: on a long coding session the system prompt was rebuilt
into the request every turn but cache-broken whenever git status
changed. Now it stays in cache for the full 5-minute ephemeral TTL
across every turn AND across sessions if the user reopens within the
window. Estimated 30-50% reduction in billed input tokens on long
sessions per our cost projections.

Author: halfaipg

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "codebase-cli",
-	"version": "2.0.0-pre.47",
+	"version": "2.0.0-pre.48",
 	"description": "Codebase CLI — a TypeScript coding agent on the pi-mono runtime. OAuth-aware, any LLM provider, single install.",
 	"keywords": [
 		"ai",

src/agent/agent.ts

@@ -180,7 +180,6 @@ export function createAgent(opts: CreateAgentOptions = {}): AgentBundle {
 	const systemPrompt =
 		opts.systemPrompt ??
 		buildSystemPrompt({
-			cwd,
 			tools: tools.map((t) => ({ name: t.name, description: t.description })),
 		});
 

src/agent/system-prompt.test.ts

@@ -2,44 +2,42 @@ import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { describe, expect, it } from "vitest";
-import { buildSystemPrompt } from "./system-prompt.js";
+import { buildEnvironmentReminder, buildSystemPrompt } from "./system-prompt.js";
 
 describe("buildSystemPrompt", () => {
 	it("includes the identity sentence at the top", () => {
-		const out = buildSystemPrompt({ cwd: "/tmp" });
+		const out = buildSystemPrompt();
 		expect(out.startsWith("You are codebase")).toBe(true);
 	});
 
 	it("includes a 'What NOT to do' anti-pattern section", () => {
-		const out = buildSystemPrompt({ cwd: "/tmp" });
+		const out = buildSystemPrompt();
 		expect(out).toContain("# What NOT to do");
-		// The specific bullets that should be present:
 		expect(out).toMatch(/Don't add features.*beyond what was asked/);
 		expect(out).toMatch(/Don't add error handling.*can't actually occur/);
 		expect(out).toMatch(/Default to no comments/);
 	});
 
 	it("includes the verification rule", () => {
-		const out = buildSystemPrompt({ cwd: "/tmp" });
+		const out = buildSystemPrompt();
 		expect(out).toContain("# Verifying your work");
 		expect(out).toMatch(/never characterize unverified work as complete/i);
 	});
 
 	it("explains system-reminder semantics so the model knows they're from the runtime", () => {
-		const out = buildSystemPrompt({ cwd: "/tmp" });
+		const out = buildSystemPrompt();
 		expect(out).toContain("<system-reminder>");
 		expect(out).toMatch(/aren't typed by the user/i);
 	});
 
 	it("includes the task-checklist policy", () => {
-		const out = buildSystemPrompt({ cwd: "/tmp" });
+		const out = buildSystemPrompt();
 		expect(out).toContain("Task checklist");
 		expect(out).toMatch(/Exactly ONE task is in_progress/);
 	});
 
 	it("inlines an 'Available tools' section when tools are passed", () => {
 		const out = buildSystemPrompt({
-			cwd: "/tmp",
 			tools: [
 				{ name: "read_file", description: "Read a file from disk." },
 				{ name: "shell", description: "Run a shell command.\n\nMore detail follows on later lines." },
@@ -53,38 +51,64 @@ describe("buildSystemPrompt", () => {
 	});
 
 	it("omits the 'Available tools' section when no tools are passed", () => {
-		const out = buildSystemPrompt({ cwd: "/tmp" });
+		const out = buildSystemPrompt();
 		expect(out).not.toContain("# Available tools");
 	});
 
-	it("includes an Environment block with cwd / platform / date", () => {
-		const out = buildSystemPrompt({ cwd: "/home/test" });
-		expect(out).toContain("# Environment");
+	it("does NOT include cwd/platform/host/date/git — those live in the env reminder now", () => {
+		const out = buildSystemPrompt();
+		expect(out).not.toMatch(/^- cwd:/m);
+		expect(out).not.toMatch(/^- platform:/m);
+		expect(out).not.toMatch(/^- date:/m);
+		expect(out).not.toMatch(/^- git branch:/m);
+	});
+
+	it("is byte-stable across calls with the same tool list (essential for prompt-cache hits)", () => {
+		const tools = [
+			{ name: "read_file", description: "Read." },
+			{ name: "shell", description: "Run." },
+		];
+		const a = buildSystemPrompt({ tools });
+		const b = buildSystemPrompt({ tools });
+		expect(a).toBe(b);
+	});
+
+	it("is byte-stable independent of cwd / date — those are no longer baked in", () => {
+		const a = buildSystemPrompt();
+		const b = buildSystemPrompt();
+		expect(a).toBe(b);
+	});
+});
+
+describe("buildEnvironmentReminder", () => {
+	it("wraps the env block in <system-reminder> tags", () => {
+		const out = buildEnvironmentReminder("/tmp");
+		expect(out.startsWith("<system-reminder>")).toBe(true);
+		expect(out.endsWith("</system-reminder>")).toBe(true);
+	});
+
+	it("includes cwd, platform, host, date", () => {
+		const out = buildEnvironmentReminder("/home/test");
 		expect(out).toContain("- cwd: /home/test");
+		expect(out).toMatch(/- platform: /);
+		expect(out).toMatch(/- host: /);
 		expect(out).toMatch(/- date: \d{4}-\d{2}-\d{2}/);
 	});
 
-	it("accepts a bare cwd string for backward compatibility", () => {
-		const out = buildSystemPrompt("/legacy/cwd");
-		expect(out).toContain("- cwd: /legacy/cwd");
+	it("includes git summary when cwd is a git repo", () => {
+		const out = buildEnvironmentReminder(process.cwd());
+		expect(out).toMatch(/- git branch: \S/);
+		expect(out).toMatch(/- git status: (clean|\d+ uncommitted)/);
 	});
 
-	it("does NOT include git lines when cwd is not a git repo", () => {
+	it("omits git lines when cwd is not a git repo", () => {
 		const tmp = mkdtempSync(join(tmpdir(), "no-git-"));
 		try {
-			const out = buildSystemPrompt({ cwd: tmp });
-			expect(out).not.toMatch(/^- git branch:/m);
-			expect(out).not.toMatch(/^- git status:/m);
+			const out = buildEnvironmentReminder(tmp);
+			expect(out).not.toMatch(/- git branch:/);
+			expect(out).not.toMatch(/- git status:/);
 		} finally {
 			rmSync(tmp, { recursive: true, force: true });
 		}
 	});
-
-	it("includes git branch + status when cwd is this repo", () => {
-		// This test repo IS a git repo, so the helper should find it.
-		const out = buildSystemPrompt({ cwd: process.cwd() });
-		expect(out).toMatch(/^- git branch: \S/m);
-		// status is either "clean" or "N uncommitted changes"
-		expect(out).toMatch(/^- git status: (clean|\d+ uncommitted)/m);
-	});
 });

src/agent/system-prompt.ts

@@ -2,7 +2,6 @@ import { spawnSync } from "node:child_process";
 import { hostname, platform } from "node:os";
 
 export interface BuildSystemPromptOptions {
-	cwd?: string;
 	/**
 	 * Active tool list. When provided, an "Available tools" section is
 	 * inlined so the model doesn't have to discover tool surface area
@@ -12,24 +11,24 @@ export interface BuildSystemPromptOptions {
 }
 
 /**
- * Top-level system prompt for the main agent. Layered as:
+ * Static system prompt for the main agent. Deliberately omits every
+ * session-specific value (cwd, date, git status, platform) so the
+ * prompt is byte-stable across sessions for the same tool set — that's
+ * what lets Anthropic's prompt cache hit between turns AND between
+ * sessions. Dynamic environment context is delivered separately via
+ * buildEnvironmentReminder() and prepended to the user's first turn.
+ *
+ * Layered as:
  *   1. Identity + verbs the agent can perform
- *   2. Behavior rules (anti-patterns to avoid, verification, system-reminder
- *      semantics)
+ *   2. Behavior rules (anti-patterns, verification, system-reminder semantics)
  *   3. Task-checklist policy when create_task/update_task are available
  *   4. Available tools, auto-built from the registered tool set
- *   5. Environment block (cwd, platform, date, optional git summary)
  *
- * Deliberately short — most agents on this codebase will see ~600-1000
- * tokens of prompt, not 6000+. The bullets are concrete things-to-avoid
- * rather than vibes-prompts; concrete rules bind model behavior, vague
- * ones don't.
+ * Deliberately short — most agents see ~600-1000 tokens of prompt, not
+ * 6000+. The bullets are concrete things-to-avoid rather than
+ * vibes-prompts; concrete rules bind model behavior, vague ones don't.
  */
-export function buildSystemPrompt(opts: BuildSystemPromptOptions | string = {}): string {
-	// Back-compat: callers used to pass `cwd: string` directly. Accept that
-	// shape and lift it into the options object.
-	const options: BuildSystemPromptOptions = typeof opts === "string" ? { cwd: opts } : opts;
-	const cwd = options.cwd ?? process.cwd();
+export function buildSystemPrompt(opts: BuildSystemPromptOptions = {}): string {
 	const lines: string[] = [];
 
 	lines.push("You are codebase, a CLI coding agent. You help with software engineering tasks in the user's terminal.");
@@ -95,25 +94,36 @@ export function buildSystemPrompt(opts: BuildSystemPromptOptions | string = {}):
 	);
 	lines.push("  - Append new tasks if you discover work mid-stream; cancel tasks that turned out to be unnecessary.");
 
-	if (options.tools && options.tools.length > 0) {
+	if (opts.tools && opts.tools.length > 0) {
 		lines.push("");
 		lines.push("# Available tools");
-		for (const t of options.tools) {
+		for (const t of opts.tools) {
 			lines.push(`- ${t.name} — ${firstLine(t.description)}`);
 		}
 	}
 
-	lines.push("");
-	lines.push("# Environment");
+	return lines.join("\n");
+}
+
+/**
+ * Per-session environment context, delivered as a `<system-reminder>`
+ * block at the front of the user's first turn rather than baked into
+ * the system prompt. Keeping these values out of the system prompt is
+ * what lets the prompt cache hit across sessions for the same tool set
+ * — cwd, date, and git status all vary in ways that would otherwise
+ * blow the cache every turn.
+ */
+export function buildEnvironmentReminder(cwd: string = process.cwd()): string {
+	const lines: string[] = [];
+	lines.push("<system-reminder>");
+	lines.push("Environment:");
 	lines.push(`- cwd: ${cwd}`);
 	lines.push(`- platform: ${platform()}`);
 	lines.push(`- host: ${hostname()}`);
 	lines.push(`- date: ${new Date().toISOString().slice(0, 10)}`);
-	const gitSummary = readGitSummary(cwd);
-	if (gitSummary) {
-		for (const line of gitSummary) lines.push(line);
-	}
-
+	const git = readGitSummary(cwd);
+	if (git) for (const line of git) lines.push(line);
+	lines.push("</system-reminder>");
 	return lines.join("\n");
 }
 

src/plan/run-flow.ts

@@ -8,6 +8,13 @@ export interface PlanFlowHandlers {
 	onReply: (text: string) => void;
 	/** Surface a plan-flow failure to the user. */
 	onError: (message: string) => void;
+	/**
+	 * Environment block to prepend to the final agent prompt when this is
+	 * the first agent invocation of the session. Lets the agent see cwd /
+	 * date / git status without baking those into the cacheable system
+	 * prompt. Undefined when the session already has prior assistant turns.
+	 */
+	envReminderForFirstTurn?: string;
 }
 
 /**
@@ -25,7 +32,7 @@ export async function runPlanFlow(
 	originalPrompt: string,
 	handlers: PlanFlowHandlers,
 ): Promise<void> {
-	const { onReply, onError } = handlers;
+	const { onReply, onError, envReminderForFirstTurn } = handlers;
 	const qaHistory: QAPair[] = [];
 	try {
 		for (let i = 0; i < MAX_QUESTIONS; i++) {
@@ -54,7 +61,8 @@ export async function runPlanFlow(
 			const choice = matchOption(decision, ["Yes — run it", "Revise", "Cancel"]);
 			if (choice === "Yes — run it") {
 				const finalPrompt = buildAgentPrompt(originalPrompt, plan, qaHistory);
-				bundle.agent.prompt(finalPrompt).catch((err: unknown) => {
+				const withEnv = envReminderForFirstTurn ? `${envReminderForFirstTurn}\n\n${finalPrompt}` : finalPrompt;
+				bundle.agent.prompt(withEnv).catch((err: unknown) => {
 					onError(err instanceof Error ? err.message : String(err));
 				});
 				return;

src/ui/App.tsx

@@ -4,6 +4,7 @@ import { type AgentBundle, createAgent } from "../agent/agent.js";
 import { ConfigError } from "../agent/config.js";
 import { initialState, reducer } from "../agent/events.js";
 import { routeUserInput } from "../agent/router.js";
+import { buildEnvironmentReminder } from "../agent/system-prompt.js";
 import { BUILTIN_COMMANDS } from "../commands/builtins.js";
 import { CommandRegistry } from "../commands/registry.js";
 import { ConfigStore } from "../config/store.js";
@@ -217,6 +218,9 @@ function ChatApp({ initialBundle, onExit }: ChatAppProps) {
 				await runPlanFlow(bundle, text, {
 					onReply: (replyText) => dispatch({ type: "chat-reply", text: replyText }),
 					onError: (message) => dispatch({ type: "error", message }),
+					envReminderForFirstTurn: shouldInjectEnv(state.messages)
+						? buildEnvironmentReminder(bundle.toolContext.cwd)
+						: undefined,
 				});
 				return;
 			}
@@ -226,7 +230,14 @@ function ChatApp({ initialBundle, onExit }: ChatAppProps) {
 			appendStatus(`(router fell back to agent: ${err instanceof Error ? err.message : err})`);
 		}
 
-		bundle.agent.prompt(augmentedText).catch((err: unknown) => {
+		// First turn of a fresh (non-resumed) session carries the env block as
+		// a system-reminder. Subsequent turns inherit it via cached transcript;
+		// the system prompt itself stays byte-stable so the prompt cache hits
+		// across sessions for the same tool set.
+		const promptText = shouldInjectEnv(state.messages)
+			? `${buildEnvironmentReminder(bundle.toolContext.cwd)}\n\n${augmentedText}`
+			: augmentedText;
+		bundle.agent.prompt(promptText).catch((err: unknown) => {
 			dispatch({ type: "error", message: err instanceof Error ? err.message : String(err) });
 		});
 	};
@@ -405,6 +416,17 @@ function ChatApp({ initialBundle, onExit }: ChatAppProps) {
 	);
 }
 
+/**
+ * True if the env reminder should be prepended to the user's next agent
+ * prompt. We inject on the first user→agent interaction of a session
+ * (no assistant messages in the transcript yet). For resumed sessions
+ * the saved env from the prior run is already in the transcript, so we
+ * skip — re-injection would just waste tokens and confuse the model.
+ */
+function shouldInjectEnv(messages: readonly { role: string }[]): boolean {
+	return !messages.some((m) => m.role === "assistant");
+}
+
 /**
  * Fetch the user's available models from the inference proxy. Used by
  * the ModelPicker overlay. Throws on auth / network / non-2xx so the