@saccolabs/pi-claude-cli 0.4.15 → 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.
@@ -127,7 +134,7 @@ restyles its prompt so the `Available tools:` / `Guidelines:` anchors are
 missing, the prompt passes through untouched rather than being mangled.
 
 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
+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
@@ -135,6 +142,18 @@ the prompt a session was created with is stored in the sidecar
 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
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saccolabs/pi-claude-cli",
-  "version": "0.4.15",
+  "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
  */
@@ -98,8 +99,16 @@ 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.
+    // 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 —
@@ -113,7 +122,7 @@ export function spawnClaude(
     // 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,
     );
   }

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/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