gsd-pi 2.80.0 → 2.81.0-dev.3cddbbba2

package/packages/pi-coding-agent/src/core/extensions/types.ts

@@ -9,6 +9,7 @@
  */
 
 import type {
+	AgentAbortOrigin,
 	AgentMessage,
 	AgentToolResult,
 	AgentToolUpdateCallback,
@@ -69,6 +70,7 @@ import type {
 	LsToolInput,
 	ReadToolDetails,
 	ReadToolInput,
+	WriteToolDetails,
 	WriteToolInput,
 } from "../tools/index.js";
 
@@ -289,6 +291,12 @@ export interface ExtensionContext {
 	compact(options?: CompactOptions): void;
 	/** Get the current effective system prompt. */
 	getSystemPrompt(): string;
+	/**
+	 * Set or clear an in-memory compaction threshold-percent override (0 < value < 1).
+	 * Pass `undefined` to clear. The override is not persisted; host integrations
+	 * are expected to re-apply on each session_start.
+	 */
+	setCompactionThresholdOverride(percent: number | undefined): void;
 }
 
 /**
@@ -303,10 +311,13 @@ export interface ExtensionCommandContext extends ExtensionContext {
 	newSession(options?: {
 		parentSession?: string;
 		setup?: (sessionManager: SessionManager) => Promise<void>;
+		/** Explicit workspace root for the new session/tool runtime.
+		 *  When omitted, newSession() captures process.cwd() for backwards compatibility. */
+		workspaceRoot?: string;
 		/** When aborted before the session is fully configured, newSession() returns
 		 *  early without rebuilding the tool runtime. Used by runUnit() to discard
 		 *  a late-resolving newSession() after the session-creation timeout fires,
-		 *  preventing the tool runtime from being rebuilt with the wrong cwd (#3731). */
+		 *  preventing the tool runtime from being rebuilt with a stale workspace root (#3731). */
 		abortSignal?: AbortSignal;
 	}): Promise<{ cancelled: boolean }>;
 
@@ -551,12 +562,17 @@ export interface BeforeAgentStartEvent {
 /** Fired when an agent loop starts */
 export interface AgentStartEvent {
 	type: "agent_start";
+	sessionId?: string;
+	turnId?: string;
 }
 
 /** Fired when an agent loop ends */
 export interface AgentEndEvent {
 	type: "agent_end";
 	messages: AgentMessage[];
+	sessionId?: string;
+	turnId?: string;
+	abortOrigin?: AgentAbortOrigin;
 }
 
 /**
@@ -568,6 +584,9 @@ export interface StopEvent {
 	type: "stop";
 	reason: "completed" | "cancelled" | "error" | "blocked";
 	lastMessage?: AgentMessage;
+	sessionId?: string;
+	turnId?: string;
+	abortOrigin?: AgentAbortOrigin;
 }
 
 /**
@@ -757,6 +776,8 @@ export interface TurnStartEvent {
 	type: "turn_start";
 	turnIndex: number;
 	timestamp: number;
+	sessionId?: string;
+	turnId?: string;
 }
 
 /** Fired at the end of each turn */
@@ -765,12 +786,16 @@ export interface TurnEndEvent {
 	turnIndex: number;
 	message: AgentMessage;
 	toolResults: ToolResultMessage[];
+	sessionId?: string;
+	turnId?: string;
 }
 
 /** Fired when a message starts (user, assistant, or toolResult) */
 export interface MessageStartEvent {
 	type: "message_start";
 	message: AgentMessage;
+	sessionId?: string;
+	turnId?: string;
 }
 
 /** Fired during assistant message streaming with token-by-token updates */
@@ -778,12 +803,16 @@ export interface MessageUpdateEvent {
 	type: "message_update";
 	message: AgentMessage;
 	assistantMessageEvent: AssistantMessageEvent;
+	sessionId?: string;
+	turnId?: string;
 }
 
 /** Fired when a message ends */
 export interface MessageEndEvent {
 	type: "message_end";
 	message: AgentMessage;
+	sessionId?: string;
+	turnId?: string;
 }
 
 /** Fired when a tool starts executing */
@@ -842,6 +871,13 @@ export interface BeforeModelSelectResult {
 	modelId: string;
 }
 
+export interface AdjustToolSetRequestCustomMessage {
+	/** Index in the post-transform AgentMessage context. */
+	index: number;
+	/** Custom message type only; prompt/content text is intentionally omitted. */
+	customType: string;
+}
+
 /**
  * Fired after model selection to allow extensions to adjust the active tool set (ADR-005 Phase 4).
  * Extensions can add, remove, or reorder tools based on the selected model's provider capabilities.
@@ -858,6 +894,12 @@ export interface AdjustToolSetEvent {
 	activeToolNames: string[];
 	/** Tools already filtered by provider compatibility */
 	filteredTools: string[];
+	/**
+	 * Custom message metadata in the current request tail, measured from the
+	 * latest assistant message. This is metadata-only so extensions can scope
+	 * queued custom-message turns without seeing raw prompt content.
+	 */
+	requestCustomMessages?: AdjustToolSetRequestCustomMessage[];
 }
 
 /** Result from adjust_tool_set event handler. Return { toolNames } to override tool set. */
@@ -1009,7 +1051,7 @@ export interface EditToolResultEvent extends ToolResultEventBase {
 
 export interface WriteToolResultEvent extends ToolResultEventBase {
 	toolName: "write";
-	details: undefined;
+	details: WriteToolDetails | undefined;
 }
 
 export interface GrepToolResultEvent extends ToolResultEventBase {
@@ -1480,6 +1522,20 @@ export interface ExtensionAPI {
 	/** Set the active tools by name. */
 	setActiveTools(toolNames: string[]): void;
 
+	/**
+	 * Get the prompt-only skill catalog filter, if one is active.
+	 * Undefined means all loaded skills remain visible in <available_skills>.
+	 */
+	getVisibleSkills(): string[] | undefined;
+
+	/**
+	 * Set or clear the prompt-only skill catalog filter.
+	 *
+	 * This changes which loaded skills are advertised in <available_skills>;
+	 * it does not unload skills or disable the Skill tool.
+	 */
+	setVisibleSkills(skillNames: string[] | undefined): void;
+
 	/** Get available slash commands in the current session. */
 	getCommands(): SlashCommandInfo[];
 
@@ -1721,6 +1777,8 @@ export interface ExtensionActions {
 	getActiveTools: () => string[];
 	getAllTools: () => ToolInfo[];
 	setActiveTools: (toolNames: string[]) => void;
+	getVisibleSkills: () => string[] | undefined;
+	setVisibleSkills: (skillNames: string[] | undefined) => void;
 	refreshTools: () => void;
 	getCommands: () => SlashCommandInfo[];
 	setModel: (model: Model<any>, options?: { persist?: boolean }) => Promise<boolean>;
@@ -1741,6 +1799,7 @@ export interface ExtensionContextActions {
 	getContextUsage: () => ContextUsage | undefined;
 	compact: (options?: CompactOptions) => void;
 	getSystemPrompt: () => string;
+	setCompactionThresholdOverride: (percent: number | undefined) => void;
 }
 
 /**
@@ -1752,6 +1811,8 @@ export interface ExtensionCommandContextActions {
 	newSession: (options?: {
 		parentSession?: string;
 		setup?: (sessionManager: SessionManager) => Promise<void>;
+		/** See ExtensionCommandContext.newSession for docs. */
+		workspaceRoot?: string;
 		/** See ExtensionCommandContext.newSession for docs (#3731). */
 		abortSignal?: AbortSignal;
 	}) => Promise<{ cancelled: boolean }>;

package/packages/pi-coding-agent/src/core/hooks-runner.test.ts

@@ -38,6 +38,8 @@ function stubRuntime(): ExtensionRuntime {
     getActiveTools: () => [],
     getAllTools: () => [],
     setActiveTools: () => {},
+    getVisibleSkills: () => undefined,
+    setVisibleSkills: () => {},
     refreshTools: () => {},
     getCommands: () => [],
     setModel: async () => false,

package/packages/pi-coding-agent/src/core/model-registry.ts

@@ -578,6 +578,10 @@ export class ModelRegistry {
 	 * Defaults to "apiKey" for built-ins and providers without explicit mode.
 	 */
 	getProviderAuthMode(provider: string): ProviderAuthMode {
+		// E2E-test-only: the fake provider is keyless. Sentinel is project-
+		// internal ("gsd-fake") so it cannot collide with a real provider.
+		// See packages/pi-ai/src/providers/fake.ts.
+		if (provider === "gsd-fake") return "none";
 		const config = this.registeredProviders.get(provider);
 		if (!config) return "apiKey";
 		if (config.authMode) return config.authMode;

package/packages/pi-coding-agent/src/core/sdk-tool-filter.test.ts

@@ -0,0 +1,60 @@
+// Project/App: GSD-2
+// File Purpose: Tests final provider request-time tool compatibility filtering.
+
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Type } from "@sinclair/typebox";
+import type { AgentTool } from "@gsd/pi-agent-core";
+import { filterToolsForProviderRequest, getAdjustToolSetRequestCustomMessages } from "./sdk.js";
+import { registerToolCompatibility, resetToolCompatibilityRegistry } from "./tools/tool-compatibility-registry.js";
+
+function tool(name: string): AgentTool {
+	return {
+		name,
+		label: name,
+		description: name,
+		parameters: Type.Object({}),
+		execute: async () => ({ content: [], details: undefined }),
+	};
+}
+
+test("filterToolsForProviderRequest removes provider-incompatible tools", () => {
+	resetToolCompatibilityRegistry();
+	try {
+		registerToolCompatibility("image_result_tool", { producesImages: true });
+		registerToolCompatibility("complex_schema_tool", { schemaFeatures: ["patternProperties"] });
+
+		const result = filterToolsForProviderRequest(
+			[tool("bash"), tool("image_result_tool"), tool("complex_schema_tool")],
+			{ api: "google-generative-ai", provider: "google" },
+		);
+
+		assert.deepEqual(result.compatible.map((entry) => entry.name), ["bash", "image_result_tool"]);
+		assert.deepEqual(result.filtered.map((entry) => entry.name), ["complex_schema_tool"]);
+	} finally {
+		resetToolCompatibilityRegistry();
+	}
+});
+
+test("filterToolsForProviderRequest enforces provider-specific hard caps at send time", () => {
+	const result = filterToolsForProviderRequest(
+		Array.from({ length: 130 }, (_, index) => tool(`tool_${index}`)),
+		{ api: "openai-completions", provider: "groq" },
+	);
+
+	assert.equal(result.compatible.length, 128);
+	assert.deepEqual(result.filtered.map((entry) => entry.name), ["tool_128", "tool_129"]);
+});
+
+test("getAdjustToolSetRequestCustomMessages only reports custom messages in the current request tail", () => {
+	const messages = [
+		{ role: "custom", customType: "gsd-run", content: "old workflow", display: false, timestamp: 1 },
+		{ role: "assistant", content: [{ type: "text", text: "done" }], timestamp: 2 },
+		{ role: "user", content: [{ type: "text", text: "normal prompt" }], timestamp: 3 },
+		{ role: "custom", customType: "gsd-doctor-heal", content: "current workflow", display: false, timestamp: 4 },
+	] as any[];
+
+	assert.deepEqual(getAdjustToolSetRequestCustomMessages(messages), [
+		{ index: 3, customType: "gsd-doctor-heal" },
+	]);
+});

package/packages/pi-coding-agent/src/core/sdk.ts

@@ -1,3 +1,4 @@
+// GSD2 - Coding agent session factory and runtime wiring
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 
@@ -38,8 +39,53 @@ export function canRestoreSessionModel(
 ): boolean {
 	return modelRegistry.isProviderRequestReady(model.provider);
 }
-import { Agent, type AgentMessage, type ThinkingLevel } from "@gsd/pi-agent-core";
-import type { Message, Model } from "@gsd/pi-ai";
+
+const PROVIDER_TOOL_LIMITS: Record<string, number> = {
+	groq: 128,
+};
+
+function resolveProviderToolLimit(
+	providerCaps: ReturnType<typeof getProviderCapabilities>,
+	provider: string | undefined,
+): number {
+	if (provider && PROVIDER_TOOL_LIMITS[provider]) {
+		return PROVIDER_TOOL_LIMITS[provider];
+	}
+	return providerCaps.maxTools > 0 ? providerCaps.maxTools : 0;
+}
+
+export function filterToolsForProviderRequest(
+	tools: AgentTool[],
+	model: Pick<Model<any>, "api" | "provider">,
+): { compatible: AgentTool[]; filtered: AgentTool[] } {
+	const providerCaps = getProviderCapabilities(model.api);
+	if (!providerCaps.toolCalling) {
+		return { compatible: [], filtered: tools };
+	}
+
+	const compatible: AgentTool[] = [];
+	const filtered: AgentTool[] = [];
+	for (const tool of tools) {
+		const compat = getToolCompatibility(tool.name);
+		if (
+			(compat?.producesImages && !providerCaps.imageToolResults) ||
+			compat?.schemaFeatures?.some((feature) => providerCaps.unsupportedSchemaFeatures.includes(feature))
+		) {
+			filtered.push(tool);
+		} else {
+			compatible.push(tool);
+		}
+	}
+
+	const toolLimit = resolveProviderToolLimit(providerCaps, model.provider);
+	if (toolLimit > 0 && compatible.length > toolLimit) {
+		filtered.push(...compatible.splice(toolLimit));
+	}
+
+	return { compatible, filtered };
+}
+import { Agent, maybeLogProviderPayloadAudit, type AgentMessage, type AgentTool, type ThinkingLevel } from "@gsd/pi-agent-core";
+import { getProviderCapabilities, type Message, type Model } from "@gsd/pi-ai";
 import { getAgentDir, getDocsPath } from "../config.js";
 import { AgentSession } from "./agent-session.js";
 import { AuthStorage } from "./auth-storage.js";
@@ -82,6 +128,22 @@ import {
 	type ToolName,
 	writeTool,
 } from "./tools/index.js";
+import { getToolCompatibility } from "./tools/tool-compatibility-registry.js";
+
+export function getAdjustToolSetRequestCustomMessages(
+	messages: readonly AgentMessage[] | undefined,
+): Array<{ index: number; customType: string }> {
+	if (!messages) return [];
+	const requestMessages: Array<{ index: number; customType: string }> = [];
+	for (let index = messages.length - 1; index >= 0; index--) {
+		const message = messages[index] as { role?: unknown; customType?: unknown };
+		if (message?.role === "assistant") break;
+		if (message?.role === "custom" && typeof message.customType === "string") {
+			requestMessages.push({ index, customType: message.customType });
+		}
+	}
+	return requestMessages.reverse();
+}
 
 export interface CreateAgentSessionOptions {
 	/** Working directory for project-local discovery. Default: process.cwd() */
@@ -378,6 +440,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	};
 
 	const extensionRunnerRef: { current?: ExtensionRunner } = {};
+	const workspaceRootRef: { current: string } = { current: cwd };
 
 	agent = new Agent({
 		initialState: {
@@ -390,9 +453,12 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		onPayload: async (payload, currentModel) => {
 			const runner = extensionRunnerRef.current;
 			if (!runner?.hasHandlers("before_provider_request")) {
+				maybeLogProviderPayloadAudit(payload, "before_provider_request:unchanged");
 				return payload;
 			}
-			return runner.emitBeforeProviderRequest(payload, currentModel);
+			const nextPayload = await runner.emitBeforeProviderRequest(payload, currentModel);
+			maybeLogProviderPayloadAudit(nextPayload, "before_provider_request:after");
+			return nextPayload;
 		},
 		sessionId: sessionManager.getSessionId(),
 		transformContext: async (messages) => {
@@ -400,6 +466,24 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			if (!runner) return messages;
 			return runner.emitContext(messages);
 		},
+		filterTools: async (tools, _signal, messages) => {
+			const currentModel = agent.state.activeInferenceModel ?? agent.state.model ?? model;
+			if (!currentModel) return tools;
+			const providerFiltered = filterToolsForProviderRequest(tools, currentModel);
+			const runner = extensionRunnerRef.current;
+			if (!runner?.hasHandlers("adjust_tool_set")) return providerFiltered.compatible;
+			const result = await runner.emitAdjustToolSet({
+				selectedModelApi: currentModel.api,
+				selectedModelProvider: currentModel.provider,
+				selectedModelId: currentModel.id,
+				activeToolNames: providerFiltered.compatible.map((tool) => tool.name),
+				filteredTools: providerFiltered.filtered.map((tool) => tool.name),
+				requestCustomMessages: getAdjustToolSetRequestCustomMessages(messages),
+			});
+			if (!result?.toolNames) return providerFiltered.compatible;
+			const allowedNames = new Set(result.toolNames);
+			return providerFiltered.compatible.filter((tool) => allowedNames.has(tool.name));
+		},
 		steeringMode: settingsManager.getSteeringMode(),
 		followUpMode: settingsManager.getFollowUpMode(),
 		transport: settingsManager.getTransport(),
@@ -409,8 +493,11 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		getProviderOptions: async (currentModel) => {
 			if (currentModel.provider !== "claude-code") return undefined;
 			const runner = extensionRunnerRef.current;
-			if (!runner?.hasUI()) return undefined;
+			if (!runner?.hasUI()) {
+				return { cwd: workspaceRootRef.current };
+			}
 			return {
+				cwd: workspaceRootRef.current,
 				extensionUIContext: runner.getUIContext(),
 			};
 		},
@@ -554,6 +641,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		modelRegistry,
 		initialActiveToolNames,
 		extensionRunnerRef,
+		workspaceRootRef,
 		isClaudeCodeReady: options.isClaudeCodeReady,
 	});
 	const extensionsResult = resourceLoader.getExtensions();

package/packages/pi-coding-agent/src/core/settings-manager.ts

@@ -15,6 +15,13 @@ export interface CompactionSettings {
 	enabled?: boolean; // default: true
 	reserveTokens?: number; // default: 16384
 	keepRecentTokens?: number; // default: 20000
+	/**
+	 * Optional percent-of-context-window trigger (0 < value < 1). When set,
+	 * compaction fires at `contextWindow * thresholdPercent` and overrides
+	 * `reserveTokens`. Typically set as a runtime override by host integrations
+	 * (see `setCompactionThresholdOverride`) and not persisted by users directly.
+	 */
+	thresholdPercent?: number;
 }
 
 export interface BranchSummarySettings {
@@ -32,6 +39,7 @@ export interface RetrySettings {
 export interface TerminalSettings {
 	showImages?: boolean; // default: true (only relevant if terminal supports images)
 	clearOnShrink?: boolean; // default: false (clear empty rows when content shrinks)
+	adaptiveMode?: AdaptiveTuiMode; // default: "auto"
 }
 
 export interface ImageSettings {
@@ -149,6 +157,7 @@ export interface HooksSettings {
 }
 
 export type TransportSetting = Transport;
+export type AdaptiveTuiMode = "auto" | "chat" | "workflow" | "validation" | "debug" | "compact";
 
 /**
  * Package source for npm/git packages.
@@ -810,11 +819,42 @@ export class SettingsManager {
 		return this.settings.compaction?.keepRecentTokens ?? COMPACTION_KEEP_RECENT_TOKENS;
 	}
 
-	getCompactionSettings(): { enabled: boolean; reserveTokens: number; keepRecentTokens: number } {
+	getCompactionThresholdPercent(): number | undefined {
+		return this.settings.compaction?.thresholdPercent;
+	}
+
+	/**
+	 * Set or clear an in-memory compaction threshold-percent override.
+	 *
+	 * Applied to `this.settings` only; never persisted to disk. Pass `undefined`
+	 * to clear a previously set override (necessary for idempotent re-sync from
+	 * host integrations whose preference may have been removed).
+	 *
+	 * Direct mutation is used instead of `applyOverrides()` because deep-merge
+	 * semantics skip `undefined` values, which would prevent clearing.
+	 */
+	setCompactionThresholdOverride(percent: number | undefined): void {
+		if (!this.settings.compaction) {
+			this.settings.compaction = {};
+		}
+		if (percent === undefined) {
+			delete this.settings.compaction.thresholdPercent;
+		} else {
+			this.settings.compaction.thresholdPercent = percent;
+		}
+	}
+
+	getCompactionSettings(): {
+		enabled: boolean;
+		reserveTokens: number;
+		keepRecentTokens: number;
+		thresholdPercent?: number;
+	} {
 		return {
 			enabled: this.getCompactionEnabled(),
 			reserveTokens: this.getCompactionReserveTokens(),
 			keepRecentTokens: this.getCompactionKeepRecentTokens(),
+			thresholdPercent: this.getCompactionThresholdPercent(),
 		};
 	}
 
@@ -978,6 +1018,16 @@ export class SettingsManager {
 		this.setNestedGlobalSetting("terminal", "clearOnShrink", enabled);
 	}
 
+	getAdaptiveMode(): AdaptiveTuiMode {
+		const mode = this.settings.terminal?.adaptiveMode;
+		const valid: AdaptiveTuiMode[] = ["auto", "chat", "workflow", "validation", "debug", "compact"];
+		return mode && valid.includes(mode) ? mode : "auto";
+	}
+
+	setAdaptiveMode(mode: AdaptiveTuiMode): void {
+		this.setNestedGlobalSetting("terminal", "adaptiveMode", mode);
+	}
+
 	getImageAutoResize(): boolean {
 		return this.settings.images?.autoResize ?? true;
 	}

package/packages/pi-coding-agent/src/core/skill-tool.test.ts

@@ -1,3 +1,6 @@
+// Project/App: GSD-2
+// File Purpose: Tests skill invocation and prompt-only skill visibility behavior.
+
 import assert from "node:assert/strict";
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -86,4 +89,29 @@ describe("Skill tool", () => {
 		assert.match(message, /^Skill "nonexistent" not found\. Available skills: /);
 		assert.match(message, /swift-testing/);
 	});
+
+	it("filters skill catalog without unloading skills or disabling Skill tool", async () => {
+		writeSkill(testDir, "alpha", "Use alpha.");
+		writeSkill(testDir, "beta", "Use beta.");
+		const session = await createSession();
+
+		assert.match(session.systemPrompt, /<name>alpha<\/name>/);
+		assert.match(session.systemPrompt, /<name>beta<\/name>/);
+
+		session.setVisibleSkillsByName(["alpha"]);
+		assert.deepEqual(session.getVisibleSkillNames(), ["alpha"]);
+		assert.match(session.systemPrompt, /<name>alpha<\/name>/);
+		assert.doesNotMatch(session.systemPrompt, /<name>beta<\/name>/);
+
+		const tool = session.state.tools.find((entry) => entry.name === "Skill");
+		assert.ok(tool, "Skill tool should remain active");
+		const result = await tool.execute("call-3", { skill: "beta" });
+		const text = result.content[0]?.type === "text" ? result.content[0].text : "";
+		assert.match(text, /<skill name="beta"/);
+
+		session.setVisibleSkillsByName(undefined);
+		assert.equal(session.getVisibleSkillNames(), undefined);
+		assert.match(session.systemPrompt, /<name>alpha<\/name>/);
+		assert.match(session.systemPrompt, /<name>beta<\/name>/);
+	});
 });

package/packages/pi-coding-agent/src/core/slash-commands.ts

@@ -38,5 +38,6 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 	{ name: "thinking", description: "Set thinking level (off/minimal/low/medium/high/xhigh)" },
 	{ name: "edit-mode", description: "Toggle edit mode (standard/hashline)" },
 	{ name: "terminal", description: "Run a shell command directly (e.g. /terminal ping -c3 1.1.1.1)" },
+	{ name: "tui", description: "Configure TUI layout mode (e.g. /tui mode workflow)" },
 	{ name: "quit", description: "Quit pi" },
 ];

package/packages/pi-coding-agent/src/core/system-prompt.ts

@@ -59,13 +59,12 @@ export interface BuildSystemPromptOptions {
 	 * Append a `Current date and time: <toLocaleString>` line to the system
 	 * prompt. Default: `false`.
 	 *
-	 * Anthropic prompt caching matches on byte-for-byte prefix equality.
-	 * Embedding a per-call timestamp in the system prompt invalidates the
-	 * cache on every request, forcing a full re-write that costs *more*
-	 * than an uncached call (cache-write premium). Most agentic flows do
-	 * not need wall-clock awareness in the system prompt — opt in only
-	 * when the consumer genuinely needs it (e.g. a clock-sensitive agent),
-	 * and inject it via a non-cached channel (user message) when possible.
+	 * Provider prompt caches generally depend on stable prompt prefixes.
+	 * Embedding a per-call timestamp in the system prompt invalidates that
+	 * stability on every request, often forcing full prompt reprocessing.
+	 * Most agentic flows do not need wall-clock awareness in the system
+	 * prompt — opt in only when the consumer genuinely needs it, and inject
+	 * it via a non-cached channel (user message) when possible.
 	 */
 	includeDateTime?: boolean;
 }
@@ -86,9 +85,8 @@ export function buildSystemPrompt(options: BuildSystemPromptOptions = {}): strin
 	} = options;
 	const resolvedCwd = toPosixPath(cwd ?? process.cwd());
 
-	// Per-call timestamps invalidate Anthropic prompt caching (the cache
-	// matches on byte-for-byte prefix equality). Compute lazily and only
-	// when explicitly opted in via `includeDateTime`.
+	// Per-call timestamps invalidate provider prompt cache stability. Compute
+	// lazily and only when explicitly opted in via `includeDateTime`.
 	const dateTimeLine = includeDateTime
 		? `\nCurrent date and time: ${new Date().toLocaleString("en-US", {
 			weekday: "long",