@saccolabs/pi-claude-cli 0.4.7 → 0.4.9

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

package/index.ts

@@ -16,6 +16,7 @@ import {
 } from "./src/process-manager.js";
 import { getCustomToolDefs, writeMcpConfig } from "./src/mcp-config.js";
 import { rewriteOverflowMessage } from "./src/overflow.js";
+import { buildRateLimitPayload, rateLimitIdentity } from "./src/rate-limit.js";
 
 // Kill all active Claude subprocesses on process exit to prevent orphans
 process.on("exit", killAllProcesses);
@@ -40,21 +41,18 @@ let lastRateLimitJson: string | undefined;
 function publishRateLimit(info: Record<string, unknown>): void {
   const setStatus = uiContext?.ui?.setStatus;
   if (typeof setStatus !== "function") return;
-  const payload = JSON.stringify({
-    status: info.status,
-    resetsAt: info.resetsAt,
-    rateLimitType: info.rateLimitType,
-    overageStatus: info.overageStatus,
-    isUsingOverage: info.isUsingOverage === true,
-    observedAt: Math.floor(Date.now() / 1000),
-  });
+  const payload = buildRateLimitPayload(info);
   // Push only on change: the event repeats every turn, and a status that
   // rewrites itself constantly is noise for whatever renders it.
-  const withoutObservedAt = payload.replace(/,"observedAt":\d+/, "");
-  if (withoutObservedAt === lastRateLimitJson) return;
-  lastRateLimitJson = withoutObservedAt;
+  const identity = rateLimitIdentity(payload);
+  if (identity === lastRateLimitJson) return;
+  lastRateLimitJson = identity;
   try {
-    setStatus.call(uiContext!.ui, RATE_LIMIT_STATUS_KEY, payload);
+    setStatus.call(
+      uiContext!.ui,
+      RATE_LIMIT_STATUS_KEY,
+      JSON.stringify(payload),
+    );
   } catch {
     /* never break a turn over a status push */
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saccolabs/pi-claude-cli",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "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

@@ -95,6 +95,14 @@ export function spawnClaude(
     );
   }
 
+  // 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) {
     args.push("--effort", options.effort);
   }
@@ -148,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/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";
@@ -35,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
@@ -60,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
@@ -86,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,
@@ -98,30 +119,37 @@ 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);
@@ -149,9 +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
@@ -208,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) {
@@ -223,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;
 
@@ -237,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);
       });
@@ -245,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
@@ -262,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();
@@ -274,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
@@ -319,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
@@ -347,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();
@@ -418,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/rate-limit.ts

@@ -0,0 +1,64 @@
+/**
+ * Account rate-limit state, shaped for the host's status channel.
+ *
+ * The CLI emits a `rate_limit_event` per turn describing ONE window: the first
+ * one whose warning threshold has been crossed, walking
+ * `5h -> 7d -> 7d_oi -> overage`. So the reported window is the binding
+ * constraint, not an arbitrary pick — and there is no way to see all four at
+ * once from this stream. A front-end that wants "which limit will stop me, how
+ * close am I, and when does it reset" has everything it needs; one that wants
+ * a full dashboard does not, and should not pretend otherwise.
+ *
+ * Kept pure and separate from `index.ts` so the payload contract is testable
+ * without a pi runtime.
+ */
+
+/** What the host receives under the `claude-rate-limit` status key. */
+export interface RateLimitPayload {
+  status: unknown;
+  resetsAt: unknown;
+  rateLimitType: unknown;
+  overageStatus: unknown;
+  isUsingOverage: boolean;
+  /** Fraction of the window consumed: 1.01 means 101%, i.e. over. */
+  utilization: number | null;
+  /** Which warning step tripped, when one has. */
+  surpassedThreshold: number | null;
+  observedAt: number;
+}
+
+function num(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+export function buildRateLimitPayload(
+  info: Record<string, unknown>,
+  nowSeconds: number = Math.floor(Date.now() / 1000),
+): RateLimitPayload {
+  return {
+    status: info.status,
+    resetsAt: info.resetsAt,
+    rateLimitType: info.rateLimitType,
+    overageStatus: info.overageStatus,
+    isUsingOverage: info.isUsingOverage === true,
+    // The CLI has always sent these two; dropping them left front-ends able to
+    // say WHICH limit was in play and when it resets, but never how close it
+    // was — so a user could not watch themselves approach a wall, only hit it.
+    utilization: num(info.utilization),
+    surpassedThreshold: num(info.surpassedThreshold),
+    observedAt: nowSeconds,
+  };
+}
+
+/**
+ * Identity of a payload ignoring `observedAt`, for change detection.
+ *
+ * The event repeats every turn with a fresh timestamp; pushing that verbatim
+ * would rewrite the host's status constantly and make anything rendering it
+ * flicker. Comparing everything EXCEPT the timestamp is what makes the push
+ * "on change" rather than "on turn".
+ */
+export function rateLimitIdentity(payload: RateLimitPayload): string {
+  const { observedAt: _observedAt, ...rest } = payload;
+  return JSON.stringify(rest);
+}

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