@saccolabs/pi-claude-cli 0.4.15 → 0.5.0

package/README.md

@@ -95,15 +95,54 @@ allowlists). Model access and your subscription login are unaffected.
 Related knobs: `PI_CLAUDE_CLI_TIMEOUT_MS` overrides the 300s inactivity
 timeout (CLI-side tools can be silent on stdout for minutes).
 
+### Auto-compact window
+
+The provider resumes **one** CLI session for a pi session's whole life, and
+nothing else ever shrinks it. On 1M-context models the CLI's own auto-compact
+default lets that session ratchet toward a million tokens — measured across 26
+real sessions, contexts reached 480k+, the average request carried 202k
+tokens, and every request re-reads the full context. So the provider passes
+`--autocompact 200000` **by default**: Claude Code compacts the session itself
+when its context nears 200k, keeping the cached system-prompt prefix and full
+transcript fidelity.
+
+`PI_CLAUDE_CLI_AUTOCOMPACT` configures it (read per spawn, like the flags
+above):
+
+| Value                   | Behaviour                                                                                      |
+| ----------------------- | ---------------------------------------------------------------------------------------------- |
+| _(unset)_               | `--autocompact 200000` — the 200k budget these models run under everywhere the 1M beta is off. |
+| `400k`, `400000`, `400` | Any window from 100k to 1M; bare numbers are thousands (CLI shorthand).                        |
+| `auto`                  | `--autocompact auto` — the CLI's own default (≈ the model's full window).                      |
+| `off`                   | Omit the flag entirely (use on CLIs that predate `--autocompact`).                             |
+
+The value is a token **count**, not a percentage: cache read/write bill per
+token and every request re-reads the whole context, so the sane budget is the
+same on a 200k model and a 1M one. Invalid values warn and fall back to the
+default instead of reaching the CLI, which rejects them by refusing to start.
+
+Note for pre-existing sessions: the first resumed turn of a session already
+past the window compacts immediately — one summarization pass, then the
+session continues small. That is the remediation, not a bug. pi's own
+compaction is separate (it rewrites pi's transcript, never the CLI session's)
+and with this cap it should rarely trigger.
+
 ### Which system prompt
 
 `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 +166,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 +174,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.5.0",
   "description": "Pi coding agent extension that routes LLM calls through the Claude Code CLI",
   "main": "index.ts",
   "keywords": [

package/src/autocompact.ts

@@ -0,0 +1,99 @@
+/**
+ * Auto-compact window resolution (PI_CLAUDE_CLI_AUTOCOMPACT).
+ *
+ * Claude Code compacts a session automatically when its context approaches
+ * the auto-compact window (`--autocompact <auto|tokens>`, claude 2.1.x). On
+ * 1M-context models the CLI's own default lets a long-lived session ratchet
+ * toward a million tokens, and this provider resumes ONE CLI session for a
+ * pi session's whole life — nothing else ever shrinks it. Measured across
+ * 26 real pidex sessions (2026-08-30): contexts ratcheted to 480k+, the
+ * average request carried 202k tokens, and cache reads alone were ~53% of
+ * total spend. Sessions that stayed near 100–150k did the same work at a
+ * fraction of the cost.
+ *
+ * So the provider caps the window at 200k tokens BY DEFAULT — the budget
+ * these models run under everywhere the 1M beta is not enabled — and lets
+ * the host raise, lower, or disable it:
+ *
+ *   PI_CLAUDE_CLI_AUTOCOMPACT=200k      cap at 200k (the default)
+ *   PI_CLAUDE_CLI_AUTOCOMPACT=400000    plain token counts work too
+ *   PI_CLAUDE_CLI_AUTOCOMPACT=400       bare numbers are thousands (CLI shorthand)
+ *   PI_CLAUDE_CLI_AUTOCOMPACT=auto      the CLI's own default behaviour
+ *   PI_CLAUDE_CLI_AUTOCOMPACT=off       omit the flag entirely (also: 0, none,
+ *                                       disable, disabled — for CLIs that
+ *                                       predate --autocompact)
+ *
+ * The value is a token COUNT, not a percentage of the model's window. The
+ * costs this guards against are absolute — cache read/write bill per token,
+ * and every request re-reads the whole context — so "half the window" means
+ * something completely different on a 200k model than on a 1M one, while
+ * 200k tokens costs the same everywhere.
+ *
+ * An invalid or out-of-range value falls back to the default with a warning
+ * rather than being passed through: the CLI rejects bad values by refusing
+ * to start, which would kill every turn of every session over a typo.
+ */
+
+/** Default auto-compact window, in tokens. */
+export const DEFAULT_AUTOCOMPACT_TOKENS = 200_000;
+
+/** The CLI accepts 100k–1M (claude 2.1.231: "It must be 'auto', or between 100k and 1M"). */
+const MIN_TOKENS = 100_000;
+const MAX_TOKENS = 1_000_000;
+
+const OFF_VALUES = new Set([
+  "off",
+  "0",
+  "none",
+  "disable",
+  "disabled",
+  "false",
+]);
+
+/**
+ * Parse a user-supplied window size into a token count.
+ * Mirrors the CLI's accepted forms: `500k`, `1M`, `200000`, and bare `200`
+ * meaning thousands. Returns undefined when unparseable.
+ */
+export function parseAutocompactTokens(raw: string): number | undefined {
+  const m = /^(\d+(?:\.\d+)?)\s*([km])?$/i.exec(raw.trim());
+  if (!m) return undefined;
+  const n = Number(m[1]);
+  if (!Number.isFinite(n) || n <= 0) return undefined;
+  const suffix = (m[2] ?? "").toLowerCase();
+  if (suffix === "k") return Math.round(n * 1_000);
+  if (suffix === "m") return Math.round(n * 1_000_000);
+  // Bare number: the CLI reads `200` as 200k shorthand; anything that already
+  // looks like a token count (>= 100k) is taken literally.
+  return n < MIN_TOKENS ? Math.round(n * 1_000) : Math.round(n);
+}
+
+/**
+ * Resolve the `--autocompact` argument from the environment.
+ *
+ * Returns the string to pass to the flag, or undefined to omit the flag
+ * entirely (explicit off). Unset resolves to the 200k default; `auto` is
+ * passed through so the CLI applies its own default; invalid values warn
+ * and fall back to the default.
+ */
+export function resolveAutocompact(
+  env: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+  const raw = (env.PI_CLAUDE_CLI_AUTOCOMPACT ?? "").trim();
+  if (raw === "") return String(DEFAULT_AUTOCOMPACT_TOKENS);
+
+  const lowered = raw.toLowerCase();
+  if (OFF_VALUES.has(lowered)) return undefined;
+  if (lowered === "auto") return "auto";
+
+  const tokens = parseAutocompactTokens(raw);
+  if (tokens === undefined || tokens < MIN_TOKENS || tokens > MAX_TOKENS) {
+    console.warn(
+      `[pi-claude-cli] PI_CLAUDE_CLI_AUTOCOMPACT=${JSON.stringify(raw)} is not ` +
+        `'auto', 'off', or a window between 100k and 1M — using the default ` +
+        `${DEFAULT_AUTOCOMPACT_TOKENS} tokens`,
+    );
+    return String(DEFAULT_AUTOCOMPACT_TOKENS);
+  }
+  return String(tokens);
+}

package/src/process-manager.ts

@@ -16,14 +16,16 @@ import {
   DEFAULT_SYSTEM_PROMPT_MODE,
   type SystemPromptMode,
 } from "./system-prompt-mode.js";
+import { resolveAutocompact } from "./autocompact.js";
 
 /**
  * Spawn a Claude CLI subprocess with all required flags for stream-json communication.
  *
  * @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 +100,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 +123,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,
     );
   }
@@ -134,6 +144,16 @@ export function spawnClaude(
     args.push("--mcp-config", options.mcpConfigPath);
   }
 
+  // Auto-compact window (PI_CLAUDE_CLI_AUTOCOMPACT, default 200k — see
+  // src/autocompact.ts). The CLI does not keep flags across --resume, so
+  // like the system prompt this goes on every spawn. Resolved per spawn so
+  // a host can change the setting without restarting pi; the flag is
+  // config, not context, so changing it never invalidates the prompt cache.
+  const autocompact = resolveAutocompact();
+  if (autocompact !== undefined) {
+    args.push("--autocompact", autocompact);
+  }
+
   const proc = spawn("claude", args, {
     stdio: ["pipe", "pipe", "pipe"],
     cwd: options?.cwd ?? process.cwd(),

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