@saccolabs/pi-claude-cli 0.4.5 → 0.4.7

package/README.md

@@ -81,6 +81,41 @@ 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).
 
+### 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.           |
+
+`minimal` is accepted as an alias for `pi`, `append` for `claude`; anything
+unrecognised falls back to the default rather than failing a session.
+
+**Why you might want `pi`.** The point of a minimal harness is not inheriting
+another agent's preamble. Measured on a real session, the CLI's fixed cached
+prefix was 17,475 tokens; the tool schemas (~4.3k) stay either way, but the
+rest is Claude Code's prompt, and pi's own — after the tool-section rewrite
+below — is ~674 tokens. That frees roughly 12k tokens of context window per
+call. It is a window win, not a cost win: the prefix is cached and bills at
+0.1x.
+
+**Why the default is still `claude`.** Claude Code's prompt carries operating
+guidance for its own tools. Replacing it leaves the model with pi's
+instructions plus the raw tool schemas. To stop that being actively
+misleading, `pi` mode rewrites pi's tool sections — which name pi's tools
+(`read`, `edit`, `grep`, `find`, `ls`) and pi's parameters (`path`,
+`oldText`, `newText`) — into Claude Code's vocabulary (`Read`, `Edit`,
+`Grep`, `Glob`, with `file_path`, `old_string`, `new_string`). If pi ever
+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.
+
 ## License
 
 MIT

package/package.json

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

package/src/process-manager.ts

@@ -12,13 +12,19 @@ import { writeFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import type { ChildProcess } from "node:child_process";
+import {
+  DEFAULT_SYSTEM_PROMPT_MODE,
+  type SystemPromptMode,
+} from "./system-prompt-mode.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 appended via --append-system-prompt
- * @param options - Optional cwd, AbortSignal, and effort level
+ * @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.
+ * @param options - Optional cwd, AbortSignal, effort level and prompt mode
  * @returns The spawned ChildProcess with piped stdin/stdout/stderr
  */
 /** Truthy PI_CLAUDE_CLI_HERMETIC opts in to hermetic mode (see README). */
@@ -37,6 +43,7 @@ export function spawnClaude(
     mcpConfigPath?: string;
     resumeSessionId?: string;
     newSessionId?: string;
+    systemPromptMode?: SystemPromptMode;
   },
 ): ChildProcess {
   const args = [
@@ -73,13 +80,19 @@ export function spawnClaude(
 
   if (systemPrompt) {
     // Write system prompt to a temp file to avoid ENAMETOOLONG on Windows.
-    // Claude CLI's --append-system-prompt accepts a file path or literal text.
+    // Both flags accept a file path or literal text.
     const tmpFile = join(
       tmpdir(),
       `pi-claude-cli-sysprompt-${process.pid}.txt`,
     );
     writeFileSync(tmpFile, systemPrompt, "utf-8");
-    args.push("--append-system-prompt", tmpFile);
+    // `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",
+      tmpFile,
+    );
   }
 
   if (options?.effort) {

package/src/prompt-builder.ts

@@ -11,6 +11,10 @@
 import { existsSync, readFileSync } from "node:fs";
 import { resolve, join, dirname } from "node:path";
 import { homedir } from "node:os";
+import {
+  DEFAULT_SYSTEM_PROMPT_MODE,
+  type SystemPromptMode,
+} from "./system-prompt-mode.js";
 import {
   mapPiToolNameToClaude,
   translatePiArgsToClaude,
@@ -140,15 +144,22 @@ function buildCustomToolResultPrompt(messages: any[]): string | null {
 /**
  * Build a prompt for a resumed session.
  *
- * When resuming via --resume, the CLI already has the full conversation history.
- * We only need to send the new content since the last turn: the last assistant
- * response's tool results (if any) followed by the latest user message.
+ * When resuming via --resume, the CLI already has the full conversation history
+ * up through the most recent assistant turn it produced. We only need to send
+ * the delta since that turn: trailing tool results for the last assistant
+ * tool_use, and/or a new user message.
  *
- * For tool_use flows: pi sends [user, assistant(toolCall), toolResult, ...]
- * We need to include tool results so the resumed session sees them, plus the
- * final user message.
+ * Why anchor on the last assistant message rather than the last user message?
+ * Pi's tool loop appends [user, assistant(toolUse), toolResult,
+ * assistant(toolUse), toolResult, ...] — the only `user` entry stays at index 0
+ * across many provider invocations. Anchoring there made every iteration replay
+ * the entire transcript, and when that first user message carried an image the
+ * image branch below returned early with just the image, so tool results never
+ * reached the model at all. The model then re-issued the same tool call
+ * indefinitely while each turn re-billed the whole accumulated context.
  *
- * Falls back to full prompt if the message structure is unexpected.
+ * Returns "" when there's nothing new to send (e.g. only an assistant message
+ * exists in the context — can happen mid-shutdown).
  */
 export function buildResumePrompt(context: {
   messages: any[];
@@ -156,28 +167,16 @@ export function buildResumePrompt(context: {
   const messages = context.messages;
   if (messages.length === 0) return "";
 
-  // Find the last user message
-  const finalUserIndex = findFinalUserMessageIndex(messages);
-  if (finalUserIndex < 0) return "";
-
-  // Collect new messages: everything from the last assistant turn onwards
-  // (tool results from the last assistant + the new user message)
-  const newMessages: any[] = [];
-
-  // Walk backwards from finalUserIndex to find where new content starts.
-  // Include trailing toolResult messages that follow the last assistant turn.
-  let startIdx = finalUserIndex;
-  for (let i = finalUserIndex - 1; i >= 0; i--) {
-    if (messages[i].role === "toolResult") {
-      startIdx = i;
-    } else {
+  let lastAssistantIdx = -1;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i].role === "assistant") {
+      lastAssistantIdx = i;
       break;
     }
   }
 
-  for (let i = startIdx; i < messages.length; i++) {
-    newMessages.push(messages[i]);
-  }
+  const newMessages = messages.slice(lastAssistantIdx + 1);
+  if (newMessages.length === 0) return "";
 
   // If there are only tool results + one user message, build a combined prompt
   const parts: string[] = [];
@@ -348,19 +347,86 @@ function findFinalUserMessageIndex(messages: any[]): number {
   return -1;
 }
 
+/**
+ * Tool guidance in Claude Code's vocabulary, used only in `pi` prompt mode.
+ *
+ * Replacing Claude Code's system prompt means the model still receives its
+ * tool *schemas* from the API but loses the prose about when and how to use
+ * them. Pi's own prose can't stand in unedited: it names pi's tools
+ * (`read`, `edit`, `grep`, `find`, `ls`) and pi's parameters (`path`,
+ * `oldText`, `newText`), none of which match what the model is actually
+ * handed (`Read`, `Edit`, `Grep`, `Glob`, with `file_path`, `old_string`,
+ * `new_string`). Left in place it is not merely useless but actively
+ * misleading, so it is swapped for this.
+ */
+const CLAUDE_CODE_TOOLS_SECTION = `Available tools:
+- Read: Read file contents (key param: file_path)
+- Write: Create or overwrite files (key params: file_path, content)
+- Edit: Make precise edits with exact text replacement (key params: file_path, old_string, new_string)
+- Bash: Execute bash commands (key param: command)
+- Grep: Search file contents for patterns (key params: pattern, path)
+- Glob: Find files by glob pattern (key params: pattern, path)
+
+In addition to the tools above, you may have access to other custom tools depending on the project.
+
+Guidelines:
+- Prefer Grep and Glob over Bash for file exploration (faster, respects .gitignore)
+- Use Read to examine files before editing
+- Use Edit for precise changes (old_string must match exactly)
+- Use Write only for new files or complete rewrites
+- When summarizing your actions, output plain text directly — do NOT use Bash to display what you did
+- Be concise in your responses
+- Show file paths clearly when working with files`;
+
+/**
+ * Swap pi's tool documentation for Claude Code's.
+ *
+ * Pi's prompt is a sequence of blank-line-separated blocks; the tool material
+ * runs from the `Available tools:` block through the `Guidelines:` block
+ * (verified against pi 0.84.2, where those are blocks 1 and 3 of 5). Both
+ * anchors must be present and in order, otherwise the prompt is returned
+ * untouched — if pi restyles its prompt the failure mode should be "kept the
+ * original", never a mangled one.
+ *
+ * Exported for tests.
+ */
+export function rewritePiToolSections(systemPrompt: string): string {
+  const blocks = systemPrompt.split("\n\n");
+
+  const start = blocks.findIndex((b) => b.startsWith("Available tools:"));
+  const end = blocks.findIndex((b) => b.startsWith("Guidelines:"));
+  if (start === -1 || end === -1 || end < start) return systemPrompt;
+
+  const kept = blocks.filter((_, i) => i < start || i > end);
+  // Reinstate the replacement where the originals were, so the intro still
+  // reads into it and anything after (pi's docs section) still follows.
+  kept.splice(start, 0, CLAUDE_CODE_TOOLS_SECTION);
+  return kept.join("\n\n");
+}
+
 /**
  * Builds the system prompt from the context's systemPrompt field,
  * 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.
  */
 export function buildSystemPrompt(
   context: { systemPrompt?: string; messages: any[] },
   cwd: string,
+  mode: SystemPromptMode = DEFAULT_SYSTEM_PROMPT_MODE,
 ): string {
   const parts: string[] = [];
 
   if (context.systemPrompt) {
-    parts.push(context.systemPrompt);
+    parts.push(
+      mode === "pi"
+        ? rewritePiToolSections(context.systemPrompt)
+        : context.systemPrompt,
+    );
   }
 
   // Look for AGENTS.md

package/src/provider.ts

@@ -26,6 +26,7 @@ import {
   buildSystemPrompt,
   buildResumePrompt,
 } from "./prompt-builder.js";
+import { resolveSystemPromptMode } from "./system-prompt-mode.js";
 import {
   spawnClaude,
   writeUserMessage,
@@ -124,9 +125,15 @@ export function streamViaCli(
       const prompt = resumeSessionId
         ? 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.
+      const systemPromptMode = resolveSystemPromptMode();
       const systemPrompt = resumeSessionId
         ? undefined
-        : buildSystemPrompt(context, cwd);
+        : buildSystemPrompt(context, cwd, systemPromptMode);
 
       // Compute effort level from reasoning options
       const effort = mapThinkingEffort(
@@ -143,6 +150,7 @@ export function streamViaCli(
         mcpConfigPath: options?.mcpConfigPath,
         resumeSessionId,
         newSessionId: !resumeSessionId ? options?.sessionId : undefined,
+        systemPromptMode,
       });
       const getStderr = captureStderr(proc);
 

package/src/system-prompt-mode.ts

@@ -0,0 +1,45 @@
+/**
+ * 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
+ * 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.
+ *
+ * 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
+ * *plus* the tool schemas, and the schemas (~4.3k, per pi's own breakdown)
+ * stay either way — only the prompt is replaceable. Pi's prompt after the
+ * tool-section rewrite is ~674 tokens, so the realistic saving is roughly
+ * 12k tokens of context per call, not the full difference. It is a
+ * context-window win rather than a cost win: that prefix is cached and bills
+ * at 0.1x, so it was never a meaningful part of a runaway bill.
+ *
+ * The trade is real, which is why this is a choice and not a default flip:
+ * Claude Code's prompt carries operating guidance for its own tools, so
+ * dropping it means the model works from pi's instructions plus the tool
+ * schemas alone. `rewritePiToolSections` compensates by restating pi's tool
+ * documentation in Claude Code's names, but a model may still behave
+ * differently. Default stays `claude`.
+ */
+export type SystemPromptMode = "claude" | "pi";
+
+export const DEFAULT_SYSTEM_PROMPT_MODE: SystemPromptMode = "claude";
+
+/**
+ * Resolve the mode from the environment.
+ *
+ * Unset or unrecognised values fall back to the default rather than throwing:
+ * a typo in a launcher's env should not stop a session from starting.
+ */
+export function resolveSystemPromptMode(
+  env: NodeJS.ProcessEnv = process.env,
+): SystemPromptMode {
+  const raw = (env.PI_CLAUDE_CLI_SYSTEM_PROMPT ?? "").trim().toLowerCase();
+  if (raw === "pi" || raw === "minimal") return "pi";
+  if (raw === "claude" || raw === "append") return "claude";
+  return DEFAULT_SYSTEM_PROMPT_MODE;
+}