@saccolabs/pi-claude-cli 0.4.6 → 0.4.8

package/README.md

@@ -12,7 +12,7 @@ A [pi](https://github.com/earendil-works/pi) extension that routes LLM calls thr
 
 ## How it works
 
-The extension registers as a custom pi provider exposing all Claude models. Each request spawns a `claude -p` subprocess using the stream-json wire protocol, with `--resume` on follow-up turns to reuse the CLI's session state instead of replaying full history. Claude proposes tool calls, pi executes them natively. Custom pi tools are exposed to Claude via a schema-only MCP server.
+The extension registers as a custom pi provider exposing all Claude models. It runs in **observer mode**: the Claude Code CLI is a first-class agent that owns its loop, its tools and its session — pi is the system of record and observes the stream. One CLI session per pi session, resumed with `--resume` on every follow-up turn, so token use matches using the CLI directly. Built-in tools (Read, Bash, …) execute natively inside the CLI and surface to pi as `[Claude Code · Name]` activity markers. Custom pi tools are advertised via a schema-only MCP server and **handed off**: the provider interrupts the turn cleanly, pi executes the tool (all pi hooks fire), and the next turn resumes with the result.
 
 ## Requirements
 
@@ -44,7 +44,10 @@ Requires the `claude` binary on your login-shell PATH (`npm install -g @anthropi
 - Maps tool names and arguments bidirectionally between Claude and pi
 - Exposes custom pi tools to Claude via MCP (schema-only, no execution)
 - Break-early pattern prevents Claude CLI from auto-executing tools
-- Session resume via `--resume` eliminates history replay on follow-up turns
+- One CLI session per pi session (sidecar-mapped), resumed on every follow-up turn — native caching, no history replay
+- Native tool execution: the CLI runs its own tools; guards are injected as Claude Code PreToolUse hooks via `PI_CLAUDE_CLI_SETTINGS`
+- Reports account rate-limit state (window, reset, overage) to the front-end
+  on the `claude-rate-limit` status key — never mixed into turn content
 - Configurable thinking effort across the full ladder (low to max) for all models, with elevated mapping for Opus
 - Cross-platform subprocess management (Windows, macOS, Linux)
 - Inactivity timeout and process registry for cleanup
@@ -55,6 +58,11 @@ Requires the `claude` binary on your login-shell PATH (`npm install -g @anthropi
 the two-ledger session model, error recovery, and the CLI compatibility
 notes (including the 2.x control-protocol shape).
 
+Two of its sections are **contracts a front-end can depend on**, so read
+them before changing what this extension emits: the
+`[Claude Code · Tool {args}]` marker string, and the `claude-rate-limit`
+status key.
+
 ## What your Claude environment contributes
 
 Each turn runs a real `claude -p` subprocess in your workspace, so your
@@ -81,6 +89,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.6",
+  "version": "0.4.8",
   "description": "Pi coding agent extension that routes LLM calls through the Claude Code CLI",
   "main": "index.ts",
   "keywords": [

package/src/event-bridge.ts

@@ -17,7 +17,7 @@ import type {
 import {
   mapClaudeToolNameToPi,
   translateClaudeArgsToPi,
-  isPiKnownClaudeTool,
+  isHandoffClaudeTool,
 } from "./tool-mapping.js";
 
 /**
@@ -267,9 +267,11 @@ export function createEventBridge(
     } else if (blockType === "tool_use") {
       const claudeName = event.content_block!.name!;
 
-      // Skip internal Claude Code tools (ToolSearch, Task, Agent, etc.)
-      // that pi cannot execute — only emit pi-known tools
-      if (!isPiKnownClaudeTool(claudeName)) {
+      // Observer mode: the CLI executes its own tools (built-ins, WebSearch,
+      // user MCP, Task). Those surface as marker text via the envelope path,
+      // never as pi toolCall blocks. Only HANDOFF tools — custom pi tools
+      // behind the schema-only MCP server — become toolCalls for pi's loop.
+      if (!isHandoffClaudeTool(claudeName)) {
         return;
       }
 
@@ -501,9 +503,10 @@ export function createEventBridge(
     if (envelope.parent_tool_use_id) return;
     for (const block of envelope.message?.content ?? []) {
       if (block.type !== "tool_use" || !block.name || !block.id) continue;
-      // Pi-known tools already streamed through the SSE path as real pi
-      // tool calls — markers are only for tools the CLI executes itself.
-      if (isPiKnownClaudeTool(block.name)) continue;
+      // Handoff tools already streamed through the SSE path as real pi
+      // tool calls — markers are for everything the CLI executes itself,
+      // which in observer mode includes the built-in file tools.
+      if (isHandoffClaudeTool(block.name)) continue;
       if (markedToolIds.has(block.id)) continue;
       markedToolIds.add(block.id);
 

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,27 @@ 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,
+    );
+  }
+
+  // Host-supplied Claude Code settings (hooks, permissions). This is how a
+  // host injects PreToolUse guards — e.g. pidex's worktree-paths guard —
+  // without pi intercepting the CLI's native tool execution.
+  const settingsPath = process.env.PI_CLAUDE_CLI_SETTINGS;
+  if (settingsPath) {
+    args.push("--settings", settingsPath);
   }
 
   if (options?.effort) {
@@ -135,6 +156,29 @@ export function writeUserMessage(
   proc.stdin!.write(JSON.stringify(message) + "\n");
 }
 
+/**
+ * Ask the CLI to end the current turn cleanly — the same interrupt a human
+ * Esc produces. Unlike SIGKILL this lets the CLI persist the turn, so the
+ * session stays resumable without transcript corruption. The turn then ends
+ * with a `result` of subtype `error_during_execution`, which callers must
+ * treat as expected.
+ */
+export function sendInterrupt(proc: ChildProcess): void {
+  // `exitCode != null` (loose): undefined means "has not exited" on mocks and
+  // some stream wrappers, and must count as alive.
+  if (proc.killed || proc.exitCode != null || !proc.stdin) return;
+  const request = {
+    type: "control_request",
+    request_id: `int-${Date.now().toString(36)}-${Math.floor(Math.random() * 1e6).toString(36)}`,
+    request: { subtype: "interrupt" },
+  };
+  try {
+    proc.stdin.write(JSON.stringify(request) + "\n");
+  } catch {
+    // stdin already closed — the force-kill fallback will handle it.
+  }
+}
+
 /**
  * Force-kill a subprocess immediately via SIGKILL.
  * No-ops if the process is already dead (killed or exited).

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,
@@ -343,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

@@ -1,17 +1,18 @@
 /**
- * Provider orchestration for bridging pi requests to the Claude CLI subprocess.
+ * Provider orchestration — observer mode (docs/SPEC-observer-mode.md).
  *
- * streamViaCli is the core function that:
- * 1. Builds the prompt from conversation context
- * 2. Spawns a Claude CLI subprocess with correct flags
- * 3. Writes the user message to stdin as NDJSON
- * 4. Reads stdout line-by-line, parsing NDJSON
- * 5. Routes stream events through the event bridge to pi's stream
- * 6. Handles result/error messages and cleans up the subprocess
- * 7. Implements break-early: kills subprocess at message_stop when
- *    built-in or custom-tools MCP tool_use blocks are seen
- * 8. Hardened lifecycle: inactivity timeout, subprocess exit handler,
- *    streamEnded guard, abort via SIGKILL, process registry
+ * The Claude CLI owns its loop, its tools, and its session. streamViaCli:
+ * 1. Resolves the pi session's CLI session (session-map) — resume, or
+ *    create/import a fresh one from pi's full history
+ * 2. Spawns `claude -p`, writes the turn's prompt to stdin as NDJSON
+ * 3. Streams events to pi: prose/thinking verbatim; the CLI's own tool
+ *    executions as `[Claude Code · Name]` markers; HANDOFF tools (custom pi
+ *    tools) as real pi toolCall blocks
+ * 4. On a handoff tool at message_stop: sends a clean `interrupt` (never a
+ *    kill — a SIGKILL mid-turn corrupts the CLI transcript and poisons every
+ *    later resume) and ends the stream stopReason=toolUse so pi executes
+ * 5. Hardened lifecycle: inactivity timeout, exit handler, streamEnded
+ *    guard, abort = interrupt + delayed SIGKILL backstop, process registry
  */
 
 import { createInterface } from "node:readline";
@@ -26,6 +27,7 @@ import {
   buildSystemPrompt,
   buildResumePrompt,
 } from "./prompt-builder.js";
+import { resolveSystemPromptMode } from "./system-prompt-mode.js";
 import {
   spawnClaude,
   writeUserMessage,
@@ -34,12 +36,19 @@ import {
   forceKillProcess,
   registerProcess,
   cleanupSystemPromptFile,
+  sendInterrupt,
 } from "./process-manager.js";
 import { parseLine } from "./stream-parser.js";
 import { createEventBridge } from "./event-bridge.js";
 import { handleControlRequest } from "./control-handler.js";
 import { mapThinkingEffort } from "./thinking-config.js";
-import { isPiKnownClaudeTool } from "./tool-mapping.js";
+import { isHandoffClaudeTool } from "./tool-mapping.js";
+import {
+  getCliSession,
+  setCliSession,
+  clearCliSession,
+} from "./session-map.js";
+import { randomUUID } from "node:crypto";
 /** Inactivity timeout: kill subprocess if no stdout for 180 seconds (3 minutes). */
 /**
  * Inactivity timeout. CLI-side tool executions (web search, user MCP
@@ -59,17 +68,32 @@ type StreamViaCLiOptions = SimpleStreamOptions & {
   onRateLimit?: (info: Record<string, unknown>) => void;
 };
 
+/**
+ * The mapped CLI session is stale when pi's history moved on without it:
+ * an assistant turn from another provider (model switch) after — or with no —
+ * pi-claude-cli turn means the CLI never saw that exchange. Resuming would
+ * answer from a conversation missing turns, so reimport instead.
+ */
+function cliSessionIsStale(messages: any[]): boolean {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (m?.role !== "assistant") continue;
+    return !(m?.provider === "pi-claude-cli" || m?.api === "pi-claude-cli");
+  }
+  return false; // no assistant turns at all: nothing to be behind
+}
+
 /**
  * Stream a response from Claude CLI as an AssistantMessageEventStream.
  *
- * Orchestrates the full subprocess lifecycle: spawn, write prompt, parse NDJSON,
- * bridge events, handle result, and clean up. Implements break-early pattern:
- * at message_stop, if any built-in or custom-tools MCP tool was seen, kills
- * the subprocess before Claude CLI can auto-execute the tools.
+ * Orchestrates the full subprocess lifecycle: resolve/resume the CLI session,
+ * spawn, write prompt, parse NDJSON, bridge events, handle result, clean up.
+ * The CLI executes its own tools; only handoff (custom pi) tools end the turn
+ * early, via a clean interrupt at message_stop.
  *
- * Hardened with: inactivity timeout (180s), subprocess exit handler with stderr
- * surfacing, streamEnded guard against double errors, abort via SIGKILL, and
- * process registry integration for teardown cleanup.
+ * Hardened with: inactivity timeout, subprocess exit handler with stderr
+ * surfacing, streamEnded guard against double errors, abort via interrupt with
+ * a SIGKILL backstop, and process registry integration for teardown cleanup.
  *
  * @param model - The model to use (from pi's model catalog)
  * @param context - The conversation context with messages and system prompt
@@ -85,11 +109,9 @@ export function streamViaCli(
 
   /**
    * One subprocess attempt. Returns "resume-miss" (without touching the
-   * stream) when a --resume pointed at a CLI session that does not exist —
-   * forks copy pi history into a NEW session id, so the prior-provider-turn
-   * heuristic says resume while the CLI cache is keyed to the old id (#2).
-   * The driver below retries once with a full-history replay, which also
-   * re-registers the CLI cache under the current session id.
+   * stream) when the sidecar pointed --resume at a CLI session that no longer
+   * exists on disk. The driver below retries once with a fresh session
+   * imported from pi's full history, re-recording the mapping.
    */
   async function runOnce(
     forceFullReplay: boolean,
@@ -97,36 +119,49 @@ export function streamViaCli(
     let proc: ReturnType<typeof spawnClaude> | undefined;
     let abortHandler: (() => void) | undefined;
     let resumeMiss = false;
+    // Track HANDOFF tool_use blocks (custom pi tools) for the interrupt
+    // decision at message_stop. Built-ins run natively and never interrupt.
+    let sawHandoffTool = false;
+    // Set once we have asked the CLI to end the turn (handoff or abort):
+    // stream content is frozen and only the result envelope is awaited.
+    let selfInterrupted = false;
+    // Set on pi-initiated abort so the turn ends quietly, not as an error.
+    let aborted = false;
 
     try {
       const cwd = options?.cwd ?? process.cwd();
 
-      // Resume only when this conversation already contains a prior assistant
-      // turn produced by pi-claude-cli (which means a CLI session has been
-      // established under this session id). Otherwise — e.g. when the user
-      // just switched to pi-claude-cli from another provider mid session, or
-      // when this is the first turn — start a fresh CLI session via
-      // --session-id. Using --resume against an unknown id fails silently
-      // with "No conversation found with session ID" and produces an empty
-      // assistant message.
-      const hasPriorCliTurn = (context.messages as any[]).some(
-        (m) =>
-          m?.role === "assistant" &&
-          (m?.provider === "pi-claude-cli" || m?.api === "pi-claude-cli"),
-      );
+      // One CLI session per pi session, resumed across turns and restarts.
+      // Resume only when a mapping exists AND the CLI session is not behind
+      // pi's history (a foreign-provider turn after our last one means the
+      // CLI never saw that exchange). Anything else — first turn, fork,
+      // model switch, lost sidecar, resume miss — is one reimport.
+      const piSessionId = options?.sessionId;
+      const mappedCliId = piSessionId ? getCliSession(piSessionId) : undefined;
       const resumeSessionId =
-        !forceFullReplay && options?.sessionId && hasPriorCliTurn
-          ? options.sessionId
+        !forceFullReplay &&
+        mappedCliId &&
+        !cliSessionIsStale(context.messages as any[])
+          ? mappedCliId
           : undefined;
+      // 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();
 
-      // Build prompt: if resuming, only send the latest user turn;
-      // otherwise build the full flattened conversation history
+      // Resume sends only the delta since the last assistant turn (new user
+      // text, handoff tool results). Create/import sends the full history.
       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(
@@ -142,8 +177,12 @@ export function streamViaCli(
         effort,
         mcpConfigPath: options?.mcpConfigPath,
         resumeSessionId,
-        newSessionId: !resumeSessionId ? options?.sessionId : undefined,
+        newSessionId: newCliId,
+        systemPromptMode,
       });
+      // 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);
       const getStderr = captureStderr(proc);
 
       // Register in global process registry for teardown cleanup
@@ -200,12 +239,16 @@ export function streamViaCli(
         }, INACTIVITY_TIMEOUT_MS);
       }
 
-      // Set up abort signal handler -- uses SIGKILL for immediate force-kill
+      // Abort = the CLI's own interrupt (keeps the session resumable), with a
+      // SIGKILL backstop in case the CLI is wedged and never emits a result.
       if (options?.signal) {
         abortHandler = () => {
-          if (proc) {
-            forceKillProcess(proc);
-          }
+          if (!proc) return;
+          aborted = true;
+          selfInterrupted = true;
+          sendInterrupt(proc);
+          const backstop = setTimeout(() => forceKillProcess(proc!), 2000);
+          proc.once("close", () => clearTimeout(backstop));
         };
 
         if (options.signal.aborted) {
@@ -215,8 +258,6 @@ export function streamViaCli(
         options.signal.addEventListener("abort", abortHandler, { once: true });
       }
 
-      // Track tool_use blocks for break-early decision at message_stop
-      let sawBuiltInOrCustomTool = false;
       // Guard against buffered readline lines firing after rl.close()
       let broken = false;
 
@@ -229,7 +270,7 @@ export function streamViaCli(
 
       // Handle process error -- use endStreamWithError for guard
       proc.on("error", (err: Error) => {
-        if (broken) return; // Break-early killed the process intentionally
+        if (broken) return; // resume-miss retry owns the stream
         const stderr = getStderr();
         endStreamWithError(stderr || err.message);
       });
@@ -237,7 +278,7 @@ export function streamViaCli(
       // Handle subprocess close -- surface crashes with stderr and exit code
       proc.on("close", (code: number | null, _signal: string | null) => {
         clearTimeout(inactivityTimer);
-        if (broken) return; // Break-early kill, expected
+        if (broken) return; // resume-miss retry owns the stream
         if (code !== 0 && code !== null) {
           const stderr = getStderr();
           const message = stderr
@@ -254,7 +295,7 @@ export function streamViaCli(
       // NOTE: Using 'line' event instead of `for await` because the async
       // iterator batches lines, breaking real-time streaming to pi.
       rl.on("line", (line: string) => {
-        if (broken) return; // Guard: ignore buffered lines after break-early
+        if (broken) return; // Guard: ignore buffered lines after a resume miss
 
         // Reset inactivity timer on each line of output
         resetInactivityTimer();
@@ -266,37 +307,38 @@ export function streamViaCli(
           // Only forward top-level events to pi's event bridge.
           // Sub-agent events (parent_tool_use_id !== null) are internal to the CLI.
           const isTopLevel = !(msg as any).parent_tool_use_id;
-          if (isTopLevel) {
+          if (isTopLevel && !selfInterrupted) {
             bridge.handleEvent(msg.event);
           }
 
-          // Track tool_use blocks for break-early decision (top-level only)
+          // Track handoff tool_use blocks (top-level only). Built-ins and
+          // CLI-internal tools execute natively and must not interrupt.
           if (
             isTopLevel &&
             msg.event.type === "content_block_start" &&
             msg.event.content_block?.type === "tool_use"
           ) {
             const toolName = msg.event.content_block.name;
-            if (toolName && isPiKnownClaudeTool(toolName)) {
-              // Built-in tool (Read/Write/etc.) OR custom MCP tool (mcp__custom-tools__*)
-              // Internal Claude Code tools (ToolSearch, Task, etc.) are excluded
-              sawBuiltInOrCustomTool = true;
+            if (toolName && isHandoffClaudeTool(toolName)) {
+              sawHandoffTool = true;
             }
           }
 
-          // Break-early at message_stop: kill subprocess before CLI auto-executes tools
-          // Only on top-level message_stop — sub-agent message_stop is internal
+          // Handoff at message_stop: ask the CLI to end the turn CLEANLY so
+          // the session file stays truthful and resumable, then wait for the
+          // result envelope. Never SIGKILL here — a kill truncates the
+          // transcript before the assistant turn is written, and every later
+          // --resume then splices in synthetic "No response requested."
+          // filler that the model eventually imitates.
           if (
             isTopLevel &&
             msg.event.type === "message_stop" &&
-            sawBuiltInOrCustomTool
+            sawHandoffTool &&
+            !selfInterrupted
           ) {
-            broken = true; // Set guard BEFORE rl.close() to prevent buffered lines
-            clearTimeout(inactivityTimer);
-            // Pi will execute these tools. Kill subprocess to prevent CLI from executing them.
-            forceKillProcess(proc!);
-            rl.close();
-            return; // Don't process further -- done event already pushed by event bridge
+            selfInterrupted = true;
+            sendInterrupt(proc!);
+            return;
           }
         } else if (msg.type === "rate_limit_event") {
           // Account-level state, not turn content: hand it to the host so a
@@ -311,25 +353,22 @@ export function streamViaCli(
             }
           }
         } else if (msg.type === "assistant") {
-          // Complete-block envelopes: marker text for CLI-side tools that
-          // would otherwise be invisible between cycles.
-          bridge.handleAssistantEnvelope(msg as any);
+          // Complete-block envelopes: marker text for the CLI's own tool
+          // executions (built-ins, WebSearch, user MCP, …), which in observer
+          // mode is every tool except handoffs.
+          if (!selfInterrupted) bridge.handleAssistantEnvelope(msg as any);
         } else if (msg.type === "user") {
           // Tool results the CLI feeds back between cycles — internal.
         } else if (msg.type === "control_request") {
           handleControlRequest(msg, proc!.stdin!);
         } else if (msg.type === "result") {
-          // Surface every non-success result as an error so silent failures
-          // (e.g. subtype "error_during_execution" from --resume against an
-          // unknown session id, or any future error variant) don't get
-          // swallowed into an empty assistant message.
           const r: any = msg as any;
           const isError =
             r.subtype !== "success" ||
             r.is_error === true ||
             typeof r.error === "string" ||
             (Array.isArray(r.errors) && r.errors.length > 0);
-          if (isError) {
+          if (isError && !selfInterrupted && !aborted) {
             const errMsg =
               r.error ??
               (Array.isArray(r.errors) && r.errors.length > 0
@@ -339,20 +378,25 @@ export function streamViaCli(
               resumeSessionId &&
               /No conversation found with session ID/i.test(errMsg)
             ) {
-              // Recoverable: the driver replays full history once. The CLI
-              // also exits non-zero after this result — silence this
-              // attempt's close/error handlers so the retry owns the stream.
+              // Recoverable: the sidecar pointed at a CLI session that no
+              // longer exists. Clear it; the driver reimports once.
+              if (piSessionId) clearCliSession(piSessionId);
               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);
               endStreamWithError(errMsg);
             }
           }
-          if (!isError) {
-            // Authoritative episode usage + final-answer safety net.
+          if (!isError || selfInterrupted || aborted) {
+            // Authoritative episode usage. After a self-interrupt the result
+            // is `error_during_execution` BY DESIGN — the turn content (the
+            // handoff toolCall) is already accumulated; usage still applies.
             bridge.applyResult(r);
           }
-          // For both success and error: clean up the subprocess
+          // For success, handoff and error alike: clean up the subprocess
           clearTimeout(inactivityTimer);
           cleanupProcess(proc!);
           rl.close();
@@ -410,7 +454,7 @@ export function streamViaCli(
       const outcome = await runOnce(false);
       if (outcome === "resume-miss") {
         console.error(
-          "[pi-claude-cli] CLI session missing for --resume — replaying full history under the current session id",
+          "[pi-claude-cli] CLI session missing for --resume — importing pi history into a fresh CLI session",
         );
         await runOnce(true);
       }

package/src/session-map.ts

@@ -0,0 +1,67 @@
+/**
+ * pi session → Claude CLI session mapping.
+ *
+ * Observer mode keeps ONE CLI session per pi session and resumes it across
+ * turns and pi restarts. pi stays the system of record: this sidecar is
+ * derived state, and losing it only costs one full-history reimport.
+ *
+ * A flat JSON file rather than per-session files: entries are tiny, writes
+ * are rare (one per created CLI session), and a single pi process owns a
+ * given pi session at a time.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+function stateDir(): string {
+  return (
+    process.env.PI_CLAUDE_CLI_STATE_DIR ||
+    join(homedir(), ".pi", "agent", "pi-claude-cli")
+  );
+}
+
+function mapPath(): string {
+  return join(stateDir(), "session-map.json");
+}
+
+function readMap(): Record<string, string> {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(mapPath(), "utf-8"));
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed as Record<string, string>;
+    }
+  } catch {
+    // Missing or corrupt — both mean "no mappings", which is always safe.
+  }
+  return {};
+}
+
+function writeMap(map: Record<string, string>): void {
+  try {
+    mkdirSync(stateDir(), { recursive: true });
+    writeFileSync(mapPath(), JSON.stringify(map, null, 2), "utf-8");
+  } catch {
+    // Best effort: an unwritable sidecar degrades to reimport-per-restart.
+  }
+}
+
+/** CLI session id for a pi session, if one was created and recorded. */
+export function getCliSession(piSessionId: string): string | undefined {
+  return readMap()[piSessionId];
+}
+
+export function setCliSession(piSessionId: string, cliSessionId: string): void {
+  const map = readMap();
+  map[piSessionId] = cliSessionId;
+  writeMap(map);
+}
+
+/** Forget a mapping so the next turn reimports from pi history. */
+export function clearCliSession(piSessionId: string): void {
+  const map = readMap();
+  if (piSessionId in map) {
+    delete map[piSessionId];
+    writeMap(map);
+  }
+}

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

package/src/tool-mapping.ts

@@ -49,14 +49,23 @@ export function isCustomToolName(piName: string): boolean {
 /**
  * Check if a Claude tool name maps to a pi-known tool.
  * Returns true for built-in tools (Read, Write, etc.) and custom MCP tools (mcp__custom-tools__*).
- * Returns false for internal Claude Code tools (ToolSearch, Task, Agent, etc.) that pi cannot execute.
- * Used by event bridge to filter out internal tool calls.
+ * Returns false for internal Claude Code tools (ToolSearch, Task, Agent, etc.).
  */
 export function isPiKnownClaudeTool(claudeName: string): boolean {
   if (claudeName.startsWith(CUSTOM_TOOLS_MCP_PREFIX)) return true;
   return claudeName.toLowerCase() in CLAUDE_TO_PI_NAME;
 }
 
+/**
+ * Handoff tools are the ONLY tools pi executes in observer mode: custom pi
+ * tools exposed through the schema-only MCP server. Built-ins run natively in
+ * the CLI. This is the gate for interrupt-at-message_stop and for emitting pi
+ * toolCall blocks — see docs/SPEC-observer-mode.md.
+ */
+export function isHandoffClaudeTool(claudeName: string): boolean {
+  return claudeName.startsWith(CUSTOM_TOOLS_MCP_PREFIX);
+}
+
 // Derived lookup maps
 
 /** Lowercase Claude name -> pi name */