@saccolabs/pi-claude-cli 0.4.14 → 0.4.16

package/README.md

@@ -100,10 +100,17 @@ timeout (CLI-side tools can be silent on stdout for minutes).
 `PI_CLAUDE_CLI_SYSTEM_PROMPT` chooses whose system prompt the subprocess
 runs under. It is read per spawn, so a host can change it between sessions.
 
-| Value                | Behaviour                                                                 |
-| -------------------- | ------------------------------------------------------------------------- |
-| `claude` _(default)_ | `--append-system-prompt`: pi's prompt layers on top of Claude Code's own. |
-| `pi`                 | `--system-prompt`: pi's prompt replaces Claude Code's entirely.           |
+| Value                | Behaviour                                                                      |
+| -------------------- | ------------------------------------------------------------------------------ |
+| `claude` _(default)_ | `--append-system-prompt-file`: pi's prompt layers on top of Claude Code's own. |
+| `pi`                 | `--system-prompt-file`: pi's prompt replaces Claude Code's entirely.           |
+
+The `-file` suffix matters: `--system-prompt` / `--append-system-prompt`
+(unsuffixed) take a **literal string**, not a path. Passing a temp-file path
+to the unsuffixed flag makes the path itself the prompt — pi's instructions
+never reach the model, silently, with no error. This shipped unnoticed since
+the provider's system-prompt support was first added; see the correction
+below.
 
 `minimal` is accepted as an alias for `pi`, `append` for `claude`; anything
 unrecognised falls back to the default rather than failing a session.
@@ -126,9 +133,26 @@ 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-file` 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.
+
+> **Correction (2026-08-29).** Both bullets above named the unsuffixed flags
+> until this date. They were wrong the whole time the provider has supported a
+> system prompt: `--system-prompt` / `--append-system-prompt` take a literal
+> string, and the provider was handing them a temp-file path. That path string
+> either became the entire "system prompt" (`pi` mode) or got appended as
+> noise Claude Code's model ignored (`claude` mode) — either way, pi's actual
+> instructions never reached the model, on ANY turn, since the very first spawn.
+> Fixed by switching to `--system-prompt-file` / `--append-system-prompt-file`,
+> which take a path. See
+> [pidex's write-up](https://github.com/agustinsacco/pidex/blob/main/specs/log/2026-08-29-claude-cli-lifecycle-verification.md)
+> for the live before/after.
 
 ## License
 

package/package.json

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

package/src/process-manager.ts

@@ -22,8 +22,9 @@ import {
  *
  * @param modelId - The model ID to pass via --model flag
  * @param systemPrompt - Optional system prompt. In `claude` mode it is appended
- *   to Claude Code's own via --append-system-prompt; in `pi` mode it replaces
- *   it via --system-prompt. See src/system-prompt-mode.ts.
+ *   to Claude Code's own via --append-system-prompt-file; in `pi` mode it
+ *   replaces it via --system-prompt-file. The `-file` suffix is required: the
+ *   unsuffixed flags take a literal string. See src/system-prompt-mode.ts.
  * @param options - Optional cwd, AbortSignal, effort level and prompt mode
  * @returns The spawned ChildProcess with piped stdin/stdout/stderr
  */
@@ -33,6 +34,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,
@@ -89,18 +99,30 @@ 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`,
+    // Write the system prompt to a temp file and pass the FILE flags.
+    //
+    // `--system-prompt` / `--append-system-prompt` take a literal string, NOT
+    // a path: handing them a path makes the path itself the system prompt, so
+    // pi's instructions never reach the model and the session silently runs on
+    // Claude Code's defaults. Verified on claude 2.1.231 — with a path the
+    // model denied having the codename its prompt assigned; with
+    // `--system-prompt-file` it answered correctly. The file variants also keep
+    // the prompt off the command line, which is what avoids ENAMETOOLONG on
+    // Windows.
+    //
+    // 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
     // pi's on top of it. See src/system-prompt-mode.ts for the trade-off.
     const mode = options?.systemPromptMode ?? DEFAULT_SYSTEM_PROMPT_MODE;
     args.push(
-      mode === "pi" ? "--system-prompt" : "--append-system-prompt",
+      mode === "pi" ? "--system-prompt-file" : "--append-system-prompt-file",
       tmpFile,
     );
   }
@@ -132,10 +154,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/prompt-builder.ts

@@ -409,10 +409,11 @@ export function rewritePiToolSections(systemPrompt: string): string {
  * appending AGENTS.md content if found (walking up from cwd, then global fallback).
  * Sanitizes .pi references to .claude for Claude Code compatibility.
  *
- * In `pi` mode the caller passes the prompt to `--system-prompt`, replacing
- * Claude Code's own, so pi's tool sections are rewritten into Claude Code's
- * names first. In `claude` mode the prompt is appended to Claude Code's and
- * pi's wording is left exactly as pi wrote it.
+ * In `pi` mode the caller passes the prompt to `--system-prompt-file`,
+ * replacing Claude Code's own, so pi's tool sections are rewritten into Claude
+ * Code's names first. In `claude` mode the prompt is appended to Claude
+ * Code's (`--append-system-prompt-file`) and pi's wording is left exactly as
+ * pi wrote it.
  */
 export function buildSystemPrompt(
   context: { systemPrompt?: string; messages: any[] },

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.
+  }
+}

package/src/system-prompt-mode.ts

@@ -2,12 +2,16 @@
  * Which system prompt the Claude CLI subprocess runs under.
  *
  * `claude` (the default) appends pi's prompt to Claude Code's own via
- * `--append-system-prompt`. Everything the CLI normally knows about its
+ * `--append-system-prompt-file`. Everything the CLI normally knows about its
  * built-in tools stays in place, and pi's instructions ride on top.
  *
- * `pi` replaces Claude Code's prompt outright via `--system-prompt`, leaving
- * only pi's — the point of a minimal harness being that it does not inherit
- * another agent's preamble.
+ * `pi` replaces Claude Code's prompt outright via `--system-prompt-file`,
+ * leaving only pi's — the point of a minimal harness being that it does not
+ * inherit another agent's preamble.
+ *
+ * The `-file` suffix is not optional: the unsuffixed flags take a literal
+ * string, and passing them a path (as this provider did until 2026-08-29)
+ * makes the path itself the prompt, silently. See process-manager.ts.
  *
  * Sizing, measured rather than assumed: in a real session the CLI's fixed
  * cached prefix sat at 17,475 tokens. That is Claude Code's system prompt