@saccolabs/pi-claude-cli 0.4.14 → 0.4.15

package/README.md

@@ -126,9 +126,14 @@ misleading, `pi` mode rewrites pi's tool sections — which name pi's tools
 restyles its prompt so the `Available tools:` / `Guidelines:` anchors are
 missing, the prompt passes through untouched rather than being mangled.
 
-Only the session-creating turn sends a system prompt — the CLI keeps it for
-the life of the session — so a change takes effect on the next new session,
-not the current one.
+The system prompt goes on **every** spawn, not just the session-creating one:
+the CLI does not keep `--system-prompt` across `--resume`, and a resumed
+session without it silently reverts to Claude Code's default prompt from turn
+2 onwards. Because an identical prefix is what keeps the prompt cache warm,
+the prompt a session was created with is stored in the sidecar
+(`~/.pi/agent/pi-claude-cli/sysprompt/<cli-session-id>.txt`) and replayed
+verbatim rather than rebuilt. A change to the mode therefore takes effect on
+the next new session, not the current one.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saccolabs/pi-claude-cli",
-  "version": "0.4.14",
+  "version": "0.4.15",
   "description": "Pi coding agent extension that routes LLM calls through the Claude Code CLI",
   "main": "index.ts",
   "keywords": [

package/src/process-manager.ts

@@ -33,6 +33,15 @@ function isHermetic(): boolean {
   return value === "1" || value === "true" || value === "yes";
 }
 
+/**
+ * Where a spawn's system prompt is staged. Scoped to the CLI session so
+ * concurrent turns in one pi process cannot clobber each other.
+ */
+function systemPromptFilePath(sessionKey?: string): string {
+  const suffix = sessionKey ? `-${sessionKey}` : "";
+  return join(tmpdir(), `pi-claude-cli-sysprompt-${process.pid}${suffix}.txt`);
+}
+
 export function spawnClaude(
   modelId: string,
   systemPrompt?: string,
@@ -91,9 +100,13 @@ export function spawnClaude(
   if (systemPrompt) {
     // Write system prompt to a temp file to avoid ENAMETOOLONG on Windows.
     // Both flags accept a file path or literal text.
-    const tmpFile = join(
-      tmpdir(),
-      `pi-claude-cli-sysprompt-${process.pid}.txt`,
+    //
+    // Keyed by CLI session, not just pid: the prompt goes on every spawn
+    // (see provider.ts), and pi can run two turns of one process at once —
+    // its own sub-agents do. A shared per-pid path would let one turn
+    // overwrite the prompt another turn is about to read.
+    const tmpFile = systemPromptFilePath(
+      options?.resumeSessionId ?? options?.newSessionId,
     );
     writeFileSync(tmpFile, systemPrompt, "utf-8");
     // `pi` mode replaces Claude Code's prompt outright; `claude` mode layers
@@ -132,10 +145,13 @@ export function spawnClaude(
 /**
  * Clean up the temp system prompt file created by spawnClaude.
  * Safe to call multiple times or when no file exists.
+ *
+ * Pass the same CLI session key the spawn used; omitting it cleans the
+ * unscoped path, which is all a spawn without a session id creates.
  */
-export function cleanupSystemPromptFile(): void {
+export function cleanupSystemPromptFile(sessionKey?: string): void {
   try {
-    unlinkSync(join(tmpdir(), `pi-claude-cli-sysprompt-${process.pid}.txt`));
+    unlinkSync(systemPromptFilePath(sessionKey));
   } catch {
     // File doesn't exist or already deleted — ignore
   }

package/src/provider.ts

@@ -49,6 +49,9 @@ import {
   getCliSession,
   setCliSession,
   clearCliSession,
+  getSystemPrompt,
+  setSystemPrompt,
+  clearSystemPrompt,
 } from "./session-map.js";
 import { randomUUID } from "node:crypto";
 /** Inactivity timeout: kill subprocess if no stdout for 180 seconds (3 minutes). */
@@ -178,6 +181,9 @@ export function streamViaCli(
     let selfInterrupted = false;
     // Set on pi-initiated abort so the turn ends quietly, not as an error.
     let aborted = false;
+    // CLI session this attempt staged its system prompt under, so the finally
+    // below can remove the right file. Set once the ids are resolved.
+    let promptFileKey: string | undefined;
 
     try {
       const cwd = options?.cwd ?? process.cwd();
@@ -198,6 +204,7 @@ export function streamViaCli(
       // Fresh sessions get a provider-minted id, never pi's: the CLI refuses
       // a --session-id it has already seen, and forks reuse pi ids.
       const newCliId = resumeSessionId ? undefined : randomUUID();
+      promptFileKey = resumeSessionId ?? newCliId;
 
       // Resume sends only the delta since the last assistant turn (new user
       // text, handoff tool results). Create/import sends the full history.
@@ -205,14 +212,19 @@ export function streamViaCli(
         ? buildResumePrompt(context)
         : buildPrompt(context);
       // Resolved per spawn rather than once at module load so a host can flip
-      // the setting between sessions without restarting pi. Only the
-      // session-creating turn carries a system prompt — the CLI keeps it for
-      // the life of the session — so switching mid-session takes effect on
-      // the next new session, not this one.
+      // the setting between sessions without restarting pi. Switching
+      // mid-session takes effect on the next NEW session, not this one: a
+      // resumed session replays the prompt it was created with (below).
       const systemPromptMode = resolveSystemPromptMode();
-      const systemPrompt = resumeSessionId
-        ? undefined
-        : buildSystemPrompt(context, cwd, systemPromptMode);
+      // The CLI does not keep --system-prompt across --resume, so it goes on
+      // EVERY spawn. On resume, replay the stored bytes rather than rebuilding
+      // them: an identical prompt keeps the cached prefix, a drifted one
+      // re-bills the whole transcript as cache write. See src/session-map.ts.
+      const storedSystemPrompt = resumeSessionId
+        ? getSystemPrompt(resumeSessionId)
+        : undefined;
+      const systemPrompt =
+        storedSystemPrompt ?? buildSystemPrompt(context, cwd, systemPromptMode);
 
       // Compute effort level from reasoning options
       const effort = mapThinkingEffort(
@@ -234,6 +246,9 @@ export function streamViaCli(
       // Record the mapping as soon as the session exists on disk. On a turn
       // that later errors, the mapping is cleared so the next turn reimports.
       if (piSessionId && newCliId) setCliSession(piSessionId, newCliId);
+      // Store the created prompt so every later turn re-passes these exact
+      // bytes. Without it, resume falls back to a rebuild that can drift.
+      if (newCliId && systemPrompt) setSystemPrompt(newCliId, systemPrompt);
       const getStderr = captureStderr(proc);
 
       // Register in global process registry for teardown cleanup
@@ -485,12 +500,17 @@ export function streamViaCli(
               // Recoverable: the sidecar pointed at a CLI session that no
               // longer exists. Clear it; the driver reimports once.
               if (piSessionId) clearCliSession(piSessionId);
+              clearSystemPrompt(resumeSessionId);
               resumeMiss = true;
               broken = true;
             } else {
               // A failed turn may leave the CLI session ending on a user
               // entry; resuming that would splice filler. Reimport next turn.
               if (piSessionId) clearCliSession(piSessionId);
+              // This CLI session will never be resumed, so its stored prompt
+              // is dead weight.
+              const deadCliId = resumeSessionId ?? newCliId;
+              if (deadCliId) clearSystemPrompt(deadCliId);
               endStreamWithError(errMsg);
             }
           }
@@ -581,6 +601,9 @@ export function streamViaCli(
       if (options?.signal && abortHandler) {
         options.signal.removeEventListener("abort", abortHandler);
       }
+      // Staged prompt file is per CLI session, so it is removed here where
+      // the ids are in scope — a resume-miss retry stages a second one.
+      cleanupSystemPromptFile(promptFileKey);
     }
   }
 
@@ -601,7 +624,6 @@ export function streamViaCli(
       } as any);
       stream.end();
     } finally {
-      cleanupSystemPromptFile();
       // The sub-agent channel is state ABOUT a turn, so it must not outlive
       // one. Left standing, the last snapshot pins whatever the agents were
       // doing when the episode ended — a host then shows "running" for

package/src/session-map.ts

@@ -10,7 +10,7 @@
  * given pi session at a time.
  */
 
-import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 
@@ -65,3 +65,61 @@ export function clearCliSession(piSessionId: string): void {
     writeMap(map);
   }
 }
+
+// ---------------------------------------------------------------------------
+// Per-CLI-session system prompt.
+//
+// The CLI does NOT persist --system-prompt across --resume: a resumed session
+// runs under Claude Code's DEFAULT prompt unless the flag is passed again.
+// That is both a correctness bug (pi's instructions vanish from turn 2 on) and
+// the single largest token cost in a pi session, because swapping the prompt
+// invalidates the cached prefix and re-bills the whole transcript as cache
+// WRITE. Verified 2026-08-29 with a shimmed `claude`: re-passing the same
+// prompt on resume cost 112 tokens where dropping it cost 9,761.
+//
+// Re-passing is only cheap when the bytes are IDENTICAL, and rebuilding is not
+// byte-stable — buildSystemPrompt() appends a tool-results paragraph the
+// moment history contains a toolResult, and pi may restyle its own prompt
+// between turns. So the prompt the session was CREATED with is stored here and
+// replayed verbatim for the life of that CLI session.
+//
+// One file per session rather than a field in session-map.json: prompts run to
+// tens of kilobytes, and the map is read on every spawn.
+// ---------------------------------------------------------------------------
+
+function systemPromptPath(cliSessionId: string): string {
+  return join(stateDir(), "sysprompt", `${cliSessionId}.txt`);
+}
+
+/**
+ * The system prompt a CLI session was created with, if it was recorded.
+ *
+ * Undefined for sessions created before this was stored, which correctly falls
+ * back to rebuilding: less cache-stable than a verbatim replay, still far
+ * better than sending no prompt at all.
+ */
+export function getSystemPrompt(cliSessionId: string): string | undefined {
+  try {
+    return readFileSync(systemPromptPath(cliSessionId), "utf-8");
+  } catch {
+    return undefined;
+  }
+}
+
+export function setSystemPrompt(cliSessionId: string, prompt: string): void {
+  try {
+    mkdirSync(join(stateDir(), "sysprompt"), { recursive: true });
+    writeFileSync(systemPromptPath(cliSessionId), prompt, "utf-8");
+  } catch {
+    // Best effort: an unwritable sidecar degrades to rebuilding the prompt.
+  }
+}
+
+/** Drop a stored prompt. Paired with clearCliSession on a resume miss. */
+export function clearSystemPrompt(cliSessionId: string): void {
+  try {
+    rmSync(systemPromptPath(cliSessionId), { force: true });
+  } catch {
+    // Already gone, or unwritable — both are fine.
+  }
+}