fix: use originalWorkdir for Primary working directory to preserve prompt cache

Use immutable originalWorkdir instead of dynamic workdir (which tracks
cd changes) for the Primary working directory field in the system prompt
<env> section. This prevents CWD changes from invalidating the cached
system prompt prefix.

Changes:
- buildSystemPrompt: add originalWorkdir option, use it for Primary
  working directory field (renamed from Working directory)
- enhanceSystemPromptWithEnvDetails: add originalWorkdir parameter
- aiManager: pass originalWorkdir at buildSystemPrompt call site
- Remove [Working Directory] section from buildPostCompactContext
  (Claude Code doesn't include it; redundant with system prompt)
- Update spec 021 FR-002, User Story 5, and edge cases
- Add research documentation for CWD stability decision

Author: lewis617

packages/agent-sdk/src/managers/aiManager.ts

@@ -613,12 +613,7 @@ export class AIManager {
       if (usedTokens >= POST_COMPACT_TOKEN_BUDGET) break;
     }
 
-    // 2. Working directory
-    contextParts.push(
-      `\n\n[Working Directory]\nCurrent working directory: ${this.getWorkdir()}`,
-    );
-
-    // 3. Plan mode context
+    // 2. Plan mode context
     const currentMode = this.permissionManager?.getCurrentEffectiveMode(
       this.getModelConfig().permissionMode,
     );
@@ -894,6 +889,7 @@ export class AIManager {
           filteredToolPlugins,
           {
             workdir: this.getWorkdir(),
+            originalWorkdir: this.getOriginalWorkdir(),
             memory: combinedMemory,
             language: this.getLanguage(),
             isSubagent: !!this.subagentType,

packages/agent-sdk/src/prompts/index.ts

@@ -236,6 +236,7 @@ export function buildSystemPrompt(
   tools: ToolPlugin[],
   options: {
     workdir?: string;
+    originalWorkdir?: string;
     memory?: string;
     language?: string;
     isSubagent?: boolean;
@@ -283,7 +284,7 @@ export function buildSystemPrompt(
 
 Here is useful information about the environment you are running in:
 <env>
-Working directory: ${options.workdir}${worktreeSession ? `\nThis is a git worktree — an isolated copy of the repository. Run all commands from this directory. Do NOT \`cd\` to the original repository root at ${worktreeSession.originalCwd}.` : ""}
+Primary working directory: ${options.originalWorkdir ?? options.workdir}${worktreeSession ? `\nThis is a git worktree — an isolated copy of the repository. Run all commands from this directory. Do NOT \`cd\` to the original repository root at ${worktreeSession.originalCwd}.` : ""}
 Is directory a git repo: ${isGitRepo}
 Platform: ${platform}
 Shell: ${shellName}
@@ -310,6 +311,7 @@ Today's date: ${today}
 export function enhanceSystemPromptWithEnvDetails(
   existingSystemPrompt: string,
   workdir: string,
+  originalWorkdir?: string,
 ): string {
   const isGitRepo = isGitRepository(workdir);
   const platform = os.platform();
@@ -336,7 +338,7 @@ ${notes}
 
 Here is useful information about the environment you are running in:
 <env>
-Working directory: ${workdir}${worktreeSession ? `\nThis is a git worktree — an isolated copy of the repository. Run all commands from this directory. Do NOT \`cd\` to the original repository root at ${worktreeSession.originalCwd}.` : ""}
+Primary working directory: ${originalWorkdir ?? workdir}${worktreeSession ? `\nThis is a git worktree — an isolated copy of the repository. Run all commands from this directory. Do NOT \`cd\` to the original repository root at ${worktreeSession.originalCwd}.` : ""}
 Is directory a git repo: ${isGitRepo}
 Platform: ${platform}
 Shell: ${shellName}

packages/agent-sdk/tests/prompts/prompts.test.ts

@@ -98,12 +98,32 @@ describe("prompts", () => {
       });
 
       expect(result).toContain("Shell: zsh");
-      expect(result).toContain("Working directory: /some/path");
+      expect(result).toContain("Primary working directory: /some/path");
       expect(result).toContain("Is directory a git repo: Yes");
 
       process.env.SHELL = originalShell;
     });
 
+    it("should use originalWorkdir for Primary working directory when provided", () => {
+      const result = buildSystemPrompt(DEFAULT_SYSTEM_PROMPT, [], {
+        workdir: "/some/path/subdir",
+        originalWorkdir: "/some/path",
+      });
+
+      expect(result).toContain("Primary working directory: /some/path");
+      expect(result).not.toContain(
+        "Primary working directory: /some/path/subdir",
+      );
+    });
+
+    it("should fall back to workdir when originalWorkdir is not provided", () => {
+      const result = buildSystemPrompt(DEFAULT_SYSTEM_PROMPT, [], {
+        workdir: "/some/path",
+      });
+
+      expect(result).toContain("Primary working directory: /some/path");
+    });
+
     it("should handle bash shell in buildSystemPrompt", () => {
       const originalShell = process.env.SHELL;
       process.env.SHELL = "/bin/bash";

specs/021-prompt-cache-control/research.md

@@ -114,6 +114,31 @@ interface ClaudeUsage extends CompletionUsage {
 - Simplified cache metrics: Rejected due to insufficient cost tracking granularity
 - Breaking usage interface changes: Rejected for backward compatibility requirements
 
+## System Prompt Stability: CWD Changes
+
+**Decision**: Use `originalWorkdir` (immutable) instead of `workdir` (dynamic, tracks `cd`) for the `Primary working directory` field in the system prompt's `<env>` section.
+
+**Rationale**:
+- The system prompt is rebuilt every AI turn with `this.getWorkdir()` (current CWD from DI container)
+- When an agent runs `cd subdir` in Bash, `workdir` updates, causing the `<env>` section to change
+- This invalidates the entire cached system prompt prefix, negating cache benefits
+- Claude Code accidentally avoids this by caching/freezing the env section at first computation
+- Using `originalWorkdir` (set once at session start, never updated) keeps the `<env>` section stable
+- The model still learns about CWD changes from the Bash tool's `"Shell working directory changed to X"` output
+- The `buildPostCompactContext` `[Working Directory]` section was removed since it's redundant (system prompt already shows `Primary working directory`) and could vary across compactions
+
+**Implementation**:
+- `buildSystemPrompt` options: added `originalWorkdir?: string` field
+- `<env>` section: `Working directory: ${options.workdir}` → `Primary working directory: ${options.originalWorkdir ?? options.workdir}`
+- `enhanceSystemPromptWithEnvDetails`: added `originalWorkdir` parameter, same change
+- `aiManager.ts` call site: pass `originalWorkdir: this.getOriginalWorkdir()`
+- `buildPostCompactContext`: removed `[Working Directory]` section (Claude Code doesn't include it)
+
+**Alternatives considered**:
+- Show both `Primary working directory` and `Current shell directory`: Rejected because adding a varying field to the `<env>` section would still break prompt cache
+- Reset CWD after every bash command (like Claude Code's opt-in `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR`): Rejected as too disruptive to agent workflow; the model may legitimately need to run commands in a subdirectory
+- Freeze/cached the env section like Claude Code: Rejected because Wave rebuilds the system prompt every turn (intentionally, for freshness of other fields like date); the better fix is to make the env section content stable
+
 ## Type Safety Strategy
 
 **Decision**: Create Claude-specific type extensions without breaking existing contracts

specs/021-prompt-cache-control/spec.md

@@ -86,6 +86,7 @@ As a user who switches between permission modes (e.g., default → plan → acce
 2. **Given** plan mode is active, **When** the system sends the next API request, **Then** plan mode instructions MUST appear as `<system-reminder>` wrapped user messages in the messages array, not in the system prompt.
 3. **Given** the user exits plan mode, **When** the next API request is made, **Then** the system prompt MUST remain unchanged and usage tracking SHOULD show cache_read_input_tokens indicating a cache hit on the system message.
 4. **Given** a non-Claude model is configured, **When** the user enters plan mode, **Then** plan mode instructions still appear as `<system-reminder>` user messages (the injection pattern is model-agnostic, but caching benefits only apply to Claude models).
+5. **Given** a Claude model is configured and the system prompt has been cached, **When** the agent changes CWD via `cd subdir` in the Bash tool, **Then** the system prompt's `Primary working directory` field MUST remain unchanged (showing the original project root), and usage tracking SHOULD show cache_read_input_tokens indicating a cache hit on the system message.
 
 ---
 
@@ -96,13 +97,14 @@ As a user who switches between permission modes (e.g., default → plan → acce
 - **Edge Case 3**: Empty conversation history MUST skip user message caching, apply system message caching only
 - **Edge Case 4**: Streaming and non-streaming requests MUST apply identical cache_control transformation logic
 - **Edge Case 5**: Token tracking MUST handle missing cache token fields gracefully (treat undefined as 0)
+- **Edge Case 6**: CWD changes via `cd` in Bash MUST NOT change the system prompt's `Primary working directory` field (it uses immutable `originalWorkdir`), preserving the cached system prompt prefix
 
 ## Requirements *(mandatory)*
 
 ### Functional Requirements
 
 - **FR-001**: System MUST detect cache-supporting models using the `WAVE_PROMPT_CACHE_REGEX` environment variable (default: "claude"), which allows configurable regex patterns for model matching
-- **FR-002**: System MUST add cache_control markers with type "ephemeral" to the first system message when using Claude models. This ensures core instructions are always cached even if reminders are added later. The system prompt MUST remain constant across plan mode transitions — plan mode instructions are injected as `<system-reminder>` user messages rather than system prompt changes to preserve the cached system prompt prefix.
+- **FR-002**: System MUST add cache_control markers with type "ephemeral" to the first system message when using Claude models. This ensures core instructions are always cached even if reminders are added later. The system prompt MUST remain constant across plan mode transitions — plan mode instructions are injected as `<system-reminder>` user messages rather than system prompt changes to preserve the cached system prompt prefix. The `<env>` section's `Primary working directory` field MUST use the immutable `originalWorkdir` (set once at session start) rather than the dynamic `workdir` (which tracks `cd` changes), so that CWD changes do not invalidate the cached system prompt.
 - **FR-003**: System MUST create a cache marker when total message count reaches multiples of 20 (20, 40, 60, etc.)
 - **FR-004**: System MUST NOT create cache markers when total message count is below 20 or not a multiple of 20
 - **FR-005**: System MUST maintain cache markers at the most recent multiple-of-20 message position (sliding window)