@saccolabs/pi-claude-cli 0.4.2 → 0.4.3

package/README.md

@@ -49,6 +49,38 @@ Requires the `claude` binary on your login-shell PATH (`npm install -g @anthropi
 - Cross-platform subprocess management (Windows, macOS, Linux)
 - Inactivity timeout and process registry for cleanup
 
+## Architecture
+
+`docs/ARCHITECTURE.md` covers the turn lifecycle, the three-way tool split,
+the two-ledger session model, error recovery, and the CLI compatibility
+notes (including the 2.x control-protocol shape).
+
+## What your Claude environment contributes
+
+Each turn runs a real `claude -p` subprocess in your workspace, so your
+Claude Code environment participates through three doors:
+
+1. **Bridged tools** — the six built-ins (Read/Write/Edit/Bash/Grep/Glob)
+   and pi custom tools become pi tool calls; pi executes them.
+2. **CLI-side execution** — your personal/project MCP servers, WebSearch,
+   and sub-agents run _inside_ the CLI between cycles. They appear in the
+   transcript as one-line markers (`[Claude Code · WebSearch {…}]`) and
+   bill your plan.
+3. **Prompt-level osmosis** — the CLI auto-loads project CLAUDE.md and
+   memory, your hooks fire, and skills can load twice (natively via
+   claude, and again via pi's own `~/.claude/skills` support).
+
+### Hermetic mode
+
+Set `PI_CLAUDE_CLI_HERMETIC=1` to keep that environment out of pi turns:
+the subprocess runs with `--strict-mcp-config` (only this extension's
+schema-only custom-tools server loads) and an empty `--setting-sources`
+(no user/project/local settings — hooks, auto-memory, permission
+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).
+
 ## License
 
 MIT

package/index.ts

@@ -15,6 +15,7 @@ import {
   killAllProcesses,
 } from "./src/process-manager.js";
 import { getCustomToolDefs, writeMcpConfig } from "./src/mcp-config.js";
+import { rewriteOverflowMessage } from "./src/overflow.js";
 
 // Kill all active Claude subprocesses on process exit to prevent orphans
 process.on("exit", killAllProcesses);
@@ -120,6 +121,13 @@ export default function (pi: ExtensionAPI) {
       PROVIDER_ID,
     );
 
+    // Overflow recovery: rewrite provider-scoped context-limit errors to
+    // the prefix pi's auto-compaction recognizes (see src/overflow.ts).
+
+    (pi.on as any)("message_end", (event: any, ctx: any) => {
+      return rewriteOverflowMessage(event?.message ?? {}, ctx?.model?.provider);
+    });
+
     pi.registerProvider(PROVIDER_ID, {
       baseUrl: "pi-claude-cli",
       apiKey: "unused",

package/package.json

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

package/src/overflow.ts

@@ -0,0 +1,63 @@
+/**
+ * Context-overflow error normalization (issue #4).
+ *
+ * When a request exceeds the model's context window, pi can recover by
+ * compacting the conversation and retrying — but only if it recognizes the
+ * failure. Detection runs on the finalized assistant message: pi checks
+ * `errorMessage` against its known overflow patterns, and the generic
+ * fallback it always recognizes is a `context_length_exceeded` prefix
+ * (see pi's custom-provider docs, "Context Overflow Errors").
+ *
+ * The Claude CLI surfaces the Anthropic API's error text verbatim, which pi
+ * does not recognize. This module rewrites ONLY provider-scoped, clearly
+ * overflow-shaped errors; rate limits and transient failures must never be
+ * rewritten (that would trigger compaction instead of pi's retry/backoff).
+ */
+
+/**
+ * Anthropic API overflow phrasings, matched conservatively:
+ * - "prompt is too long: 214315 tokens > 200000 maximum"
+ * - "input length and `max_tokens` exceed context limit: ..."
+ */
+const OVERFLOW_PATTERNS: RegExp[] = [
+  /prompt is too long/i,
+  /input length and .?max_tokens.? exceed context limit/i,
+];
+
+export const OVERFLOW_PREFIX = "context_length_exceeded";
+
+/** True when the error text is an overflow pi should recover from. */
+export function isOverflowError(errorMessage: string): boolean {
+  if (errorMessage.includes(OVERFLOW_PREFIX)) return false; // already rewritten
+  return OVERFLOW_PATTERNS.some((pattern) => pattern.test(errorMessage));
+}
+
+/**
+ * `message_end` handler body: returns the rewritten assistant message when
+ * this provider produced a recognizable overflow error, undefined otherwise
+ * (pi keeps the message unchanged).
+ */
+export function rewriteOverflowMessage(
+  message: {
+    role?: string;
+    provider?: string;
+    stopReason?: string;
+    errorMessage?: string;
+  },
+  ctxProvider?: string,
+): { message: Record<string, unknown> } | undefined {
+  if (message.role !== "assistant") return undefined;
+  if (message.stopReason !== "error") return undefined;
+  if (message.provider !== "pi-claude-cli" && ctxProvider !== "pi-claude-cli")
+    return undefined;
+
+  const errorMessage = message.errorMessage ?? "";
+  if (!isOverflowError(errorMessage)) return undefined;
+
+  return {
+    message: {
+      ...message,
+      errorMessage: `${OVERFLOW_PREFIX}: ${errorMessage}`,
+    },
+  };
+}

package/src/process-manager.ts

@@ -21,6 +21,12 @@ import type { ChildProcess } from "node:child_process";
  * @param options - Optional cwd, AbortSignal, and effort level
  * @returns The spawned ChildProcess with piped stdin/stdout/stderr
  */
+/** Truthy PI_CLAUDE_CLI_HERMETIC opts in to hermetic mode (see README). */
+function isHermetic(): boolean {
+  const value = (process.env.PI_CLAUDE_CLI_HERMETIC ?? "").toLowerCase();
+  return value === "1" || value === "true" || value === "yes";
+}
+
 export function spawnClaude(
   modelId: string,
   systemPrompt?: string,
@@ -47,6 +53,16 @@ export function spawnClaude(
     "stdio",
   ];
 
+  // Hermetic mode: keep the user's Claude Code environment out of pi turns.
+  // --strict-mcp-config loads ONLY the servers from --mcp-config (our
+  // schema-only custom-tools server survives; personal/project MCP servers
+  // do not), and an empty --setting-sources skips user/project/local
+  // settings — hooks, CLAUDE.md auto-memory, permission allowlists.
+  // Both flags verified accepted on claude 2.1.237.
+  if (isHermetic()) {
+    args.push("--strict-mcp-config", "--setting-sources", "");
+  }
+
   if (options?.resumeSessionId) {
     // Resume an existing session — CLI loads prior conversation from disk
     args.push("--resume", options.resumeSessionId);