@vanillagreen/pi-claude-bridge 1.1.3 → 1.1.4

package/README.md

@@ -37,7 +37,7 @@ Restart Pi after installation.
 
 Default behavior matches upstream: append `AGENTS.md` plus Pi's skills block to Claude Code's `claude_code` preset prompt.
 
-Extra Pi context is off by default. Enable per item in the extension manager when you want Claude Code to see prompt blocks that other Pi extensions add to your session.
+Extra Pi context is off by default. Enable per item in the extension manager when you want Claude Code to see prompt blocks that other Pi extensions add to your session. Forwarded blocks are wrapped in explicit XML tags so Pi 0.75+ project-context boundaries do not bleed into adjacent sections.
 
 ## Settings
 
@@ -79,3 +79,5 @@ Open `/extensions:settings`; settings appear under the **Claude Bridge** tab.
 ## Debugging
 
 Set `CLAUDE_BRIDGE_DEBUG=1` to write bridge logs to `~/.pi/agent/claude-bridge.log` and per-query Claude Code CLI logs under `~/.pi/agent/cc-cli-logs/`.
+
+Before starting Claude Code, the bridge preflights the resolved executable and working directory. Failures include the underlying `code`, `errno`, `syscall`, `path`, `cwd`, and detected executable file type so spawn issues point at the real failing path instead of the Claude Agent SDK's generic native-binary message. If Node still emits a spawn error after preflight, the bridge wraps that error with the same context before handing it back to the SDK.

package/bundle/index.js

@@ -19184,8 +19184,9 @@ function readSession(jsonlPath, projectPath) {
 }
 
 // src/index.ts
+import { spawn as spawnProcess } from "child_process";
 import { createHash } from "crypto";
-import { accessSync, appendFileSync as appendFileSync3, constants as fsConstants, mkdirSync as mkdirSync3, realpathSync as realpathSync3, statSync as statSync3 } from "fs";
+import { accessSync, appendFileSync as appendFileSync3, constants as fsConstants, mkdirSync as mkdirSync3, readFileSync as readFileSync7, realpathSync as realpathSync3, statSync as statSync3 } from "fs";
 import { resolve as pathResolve } from "path";
 import { homedir as homedir5 } from "os";
 import { delimiter, dirname as dirname5, join as join5 } from "path";
@@ -19758,8 +19759,13 @@ function extractHeadingSection(systemPrompt, headings) {
   }
   if (start < 0) return void 0;
   const rest = systemPrompt.slice(start).trim();
-  const nextHeading = rest.slice(1).search(/\n##\s+/);
-  return (nextHeading >= 0 ? rest.slice(0, nextHeading + 1) : rest).trim();
+  const endCandidates = [
+    rest.slice(1).search(/\n##\s+/),
+    rest.search(/\n<\/project_instructions>/),
+    rest.search(/\n<\/project_context>/)
+  ].map((index, offset) => index >= 0 && offset === 0 ? index + 1 : index).filter((index) => index >= 0);
+  const end = endCandidates.length > 0 ? Math.min(...endCandidates) : -1;
+  return (end >= 0 ? rest.slice(0, end) : rest).trim();
 }
 function extractBlockByMarkers(systemPrompt, markers) {
   for (const block of splitPromptBlocks(systemPrompt)) {
@@ -19772,48 +19778,57 @@ function buildPromptContextAppend(systemPrompt, cwd, settings) {
   const labels = [];
   if (settings.includeAppendSystemPromptMd) {
     for (const file2 of readAppendSystemPromptFiles(cwd)) {
-      parts.push(`### ${file2.label}
-
-${file2.content}`);
+      parts.push(xmlBlock("append_system_prompt", { label: file2.label }, file2.content));
       labels.push(file2.label);
     }
   }
   if (settings.includeProjectAgentsHook) {
     const projectAgents = extractHeadingSection(systemPrompt, ["## Project Agents", "## Project Subagents"]);
     if (projectAgents) {
-      parts.push(`### before_agent_start: project agents
-
-${projectAgents}`);
+      parts.push(xmlBlock("before_agent_start", { source: "project-agents" }, projectAgents));
       labels.push("project agents hook");
     }
   }
   if (settings.includeTaskPanelHook) {
     const taskReminder = extractBlockByMarkers(systemPrompt, [/^Task workflow reminder:/]);
     if (taskReminder) {
-      parts.push(`### before_agent_start: task panel
-
-${taskReminder}`);
+      parts.push(xmlBlock("before_agent_start", { source: "task-panel" }, taskReminder));
       labels.push("task panel hook");
     }
   }
   if (settings.includeCavemanHook) {
     const caveman = extractBlockByMarkers(systemPrompt, [/^You MUST respond in caveman /m]);
     if (caveman) {
-      parts.push(`### before_agent_start: caveman
-
-${caveman}`);
+      parts.push(xmlBlock("before_agent_start", { source: "caveman" }, caveman));
       labels.push("caveman hook");
     }
   }
   if (parts.length === 0) return { labels };
   return {
     labels,
-    text: [
-      "## Forwarded Pi Context",
-      "The following content was explicitly enabled in pi-claude-bridge settings and comes from Pi prompt files or before_agent_start prompt hooks.",
-      ...parts
-    ].join("\n\n")
-  };
+    text: xmlBlock(
+      "forwarded_pi_context",
+      {},
+      [
+        "The following content was explicitly enabled in pi-claude-bridge settings and comes from Pi prompt files or before_agent_start prompt hooks.",
+        ...parts
+      ].join("\n\n"),
+      false
+    )
+  };
+}
+function escapeXmlAttr(value) {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function escapeXmlText(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function xmlBlock(tag, attrs, content, escapeContent = true) {
+  const attrText = Object.entries(attrs).map(([key, value]) => ` ${key}="${escapeXmlAttr(value)}"`).join("");
+  const body = escapeContent ? escapeXmlText(content.trim()) : content.trim();
+  return `<${tag}${attrText}>
+${body}
+</${tag}>`;
 }
 
 // node_modules/zod/v4/classic/external.js
@@ -34423,6 +34438,199 @@ function resolveClaudeExecutable(configured) {
   if (trimmed) return trimmed;
   return executableFromPath("claude") ?? executableFromPath("claude-code");
 }
+function errnoValue(err) {
+  return typeof err?.errno === "number" ? err.errno : void 0;
+}
+function syscallValue(err) {
+  return typeof err?.syscall === "string" ? err.syscall : void 0;
+}
+function pathValue(err) {
+  const value = err?.path;
+  return typeof value === "string" ? value : void 0;
+}
+function codeValue(err, fallback) {
+  const value = err?.code;
+  return typeof value === "string" ? value : fallback;
+}
+function displayValue(value) {
+  return value === void 0 || value === null || value === "" ? "<none>" : String(value);
+}
+function makeClaudePreflightError(summary, details) {
+  const detail = [
+    `code=${details.code}`,
+    `errno=${displayValue(details.errno)}`,
+    `syscall=${displayValue(details.syscall)}`,
+    `path=${details.path}`,
+    `cwd=${details.cwd}`,
+    ...details.fileType ? [`fileType=${details.fileType}`] : [],
+    ...details.realPath ? [`realPath=${details.realPath}`] : []
+  ].join(" ");
+  const error51 = new Error(`${summary} (${detail})`);
+  error51.name = "ClaudeExecutablePreflightError";
+  error51.code = details.code;
+  if (details.errno !== void 0) error51.errno = typeof details.errno === "number" ? details.errno : Number(details.errno);
+  if (details.syscall) error51.syscall = details.syscall;
+  error51.path = details.path;
+  error51.cwd = details.cwd;
+  if (details.fileType) error51.fileType = details.fileType;
+  if (details.realPath) error51.realPath = details.realPath;
+  if (details.cause !== void 0) error51.cause = details.cause;
+  return error51;
+}
+function classifyClaudeExecutableBytes(bytes) {
+  if (bytes.length === 0) return "empty";
+  if (bytes.length >= 2 && bytes[0] === 35 && bytes[1] === 33) return "shebang-script";
+  if (bytes.length >= 4 && bytes[0] === 127 && bytes[1] === 69 && bytes[2] === 76 && bytes[3] === 70) return "elf";
+  if (bytes.length >= 2 && bytes[0] === 77 && bytes[1] === 90) return "pe";
+  if (bytes.length >= 4) {
+    const magic = bytes[0] * 16777216 + bytes[1] * 65536 + bytes[2] * 256 + bytes[3];
+    if (magic === 4277009102 || magic === 4277009103 || magic === 3472551422 || magic === 3489328638 || magic === 3405691582 || magic === 3199925962) return "mach-o";
+  }
+  return "unknown";
+}
+function preflightClaudeExecutable(path, cwd) {
+  let realCwd = cwd;
+  try {
+    const cwdStat = statSync3(cwd);
+    if (!cwdStat.isDirectory()) {
+      throw makeClaudePreflightError("Claude Code spawn cwd preflight failed: cwd is not a directory.", {
+        code: "ENOTDIR",
+        syscall: "chdir",
+        path: cwd,
+        cwd
+      });
+    }
+    accessSync(cwd, fsConstants.X_OK);
+    realCwd = realpathSync3(cwd);
+  } catch (err) {
+    if (err.name === "ClaudeExecutablePreflightError") throw err;
+    throw makeClaudePreflightError("Claude Code spawn cwd preflight failed: cwd is not reachable before spawning Claude Code.", {
+      code: codeValue(err, "EACCES"),
+      errno: errnoValue(err),
+      syscall: syscallValue(err),
+      path: pathValue(err) ?? cwd,
+      cwd,
+      cause: err
+    });
+  }
+  let realPath = path;
+  try {
+    const stat = statSync3(path);
+    if (!stat.isFile()) {
+      throw makeClaudePreflightError("Claude Code executable preflight failed: resolved path is not a file.", {
+        code: "EACCES",
+        syscall: "exec",
+        path,
+        cwd
+      });
+    }
+    accessSync(path, fsConstants.X_OK);
+    realPath = realpathSync3(path);
+  } catch (err) {
+    if (err.name === "ClaudeExecutablePreflightError") throw err;
+    throw makeClaudePreflightError("Claude Code executable preflight failed: cannot access resolved executable before spawning Claude Code.", {
+      code: codeValue(err, "ENOENT"),
+      errno: errnoValue(err),
+      syscall: syscallValue(err),
+      path: pathValue(err) ?? path,
+      cwd,
+      cause: err
+    });
+  }
+  let fileType;
+  try {
+    fileType = classifyClaudeExecutableBytes(readFileSync7(realPath).subarray(0, 16));
+  } catch (err) {
+    throw makeClaudePreflightError("Claude Code executable preflight failed: cannot read executable header before spawning Claude Code.", {
+      code: codeValue(err, "EACCES"),
+      errno: errnoValue(err),
+      syscall: syscallValue(err),
+      path: pathValue(err) ?? realPath,
+      cwd,
+      realPath,
+      cause: err
+    });
+  }
+  if (!["elf", "mach-o", "pe", "shebang-script"].includes(fileType)) {
+    throw makeClaudePreflightError("Claude Code executable preflight failed: executable header is not an ELF, Mach-O, PE, or shebang script.", {
+      code: "ENOEXEC",
+      syscall: "exec",
+      path,
+      cwd,
+      fileType,
+      realPath
+    });
+  }
+  return { path, realPath, cwd, realCwd, fileType };
+}
+function envFlagEnabled(value) {
+  return value === "1" || value?.toLowerCase() === "true";
+}
+function wrapClaudeSpawnErrorForSdk(err, options) {
+  const originalCode = codeValue(err, "SPAWN_ERROR");
+  const originalMessage = err.message;
+  const spawnPath = pathValue(err) ?? options.command;
+  const cwd = options.cwd ?? process.cwd();
+  const detail = [
+    `code=${originalCode}`,
+    `errno=${displayValue(errnoValue(err))}`,
+    `syscall=${displayValue(syscallValue(err))}`,
+    `path=${spawnPath}`,
+    `cwd=${cwd}`,
+    `command=${options.command}`
+  ].join(" ");
+  const wrapped = new Error(`Claude Code spawn failed: ${originalMessage} (${detail})`);
+  wrapped.name = "ClaudeSpawnDiagnosticError";
+  wrapped.code = originalCode === "ENOENT" ? "CLAUDE_BRIDGE_SPAWN_FAILED" : originalCode;
+  wrapped.originalCode = originalCode;
+  wrapped.originalMessage = originalMessage;
+  const errno = errnoValue(err);
+  if (errno !== void 0) wrapped.errno = typeof errno === "number" ? errno : Number(errno);
+  const syscall = syscallValue(err);
+  if (syscall) wrapped.syscall = syscall;
+  wrapped.path = spawnPath;
+  wrapped.cwd = cwd;
+  return wrapped;
+}
+function spawnClaudeCodeWithDiagnostics(options) {
+  const pipeStderr = DEBUG || envFlagEnabled(options.env.DEBUG_CLAUDE_AGENT_SDK);
+  const child = spawnProcess(options.command, options.args, {
+    cwd: options.cwd,
+    env: options.env,
+    signal: options.signal,
+    stdio: ["pipe", "pipe", pipeStderr ? "pipe" : "ignore"],
+    windowsHide: true
+  });
+  if (pipeStderr) {
+    child.stderr?.on("data", (data) => {
+      for (const line of data.toString().split(/\r?\n/)) {
+        if (line) debug(`[cli-stderr spawn] ${line}`);
+      }
+    });
+  }
+  child.prependListener("error", (err) => {
+    const originalStack = err.stack;
+    const wrapped = wrapClaudeSpawnErrorForSdk(err, options);
+    Object.assign(err, wrapped);
+    err.name = wrapped.name;
+    err.message = wrapped.message;
+    if (originalStack) err.stack = originalStack;
+  });
+  return {
+    stdin: child.stdin,
+    stdout: child.stdout,
+    get killed() {
+      return child.killed;
+    },
+    get exitCode() {
+      return child.exitCode;
+    },
+    kill: child.kill.bind(child),
+    on: child.on.bind(child),
+    once: child.once.bind(child),
+    off: child.off.bind(child)
+  };
+}
 var nextCliDebugSeq = 1;
 function makeCliDebugOptions(tag) {
   if (!DEBUG) return {};
@@ -35150,7 +35358,6 @@ function streamClaudeAgentSdk(model, context, options) {
   ctx().latestCursor = 0;
   const { mcpTools, customToolNameToSdk, customToolNameToPi } = resolveMcpTools(context);
   const cwd = options?.cwd ?? process.cwd();
-  const { sessionId: resumeSessionId } = syncSharedSession(context.messages, cwd, customToolNameToSdk, model.id);
   const promptBlocks = extractUserPromptBlocks(context.messages);
   let promptText = extractUserPrompt(context.messages) ?? "";
   if (!promptText && !promptBlocks) {
@@ -35178,6 +35385,8 @@ function streamClaudeAgentSdk(model, context, options) {
   const settingSources = appendSystemPrompt ? void 0 : providerSettings.settingSources ?? ["user", "project"];
   const strictMcpConfigEnabled = !appendSystemPrompt && providerSettings.strictMcpConfig !== false;
   const claudeExecutable = resolveClaudeExecutable(providerSettings.pathToClaudeCodeExecutable);
+  const claudeExecutablePreflight = claudeExecutable ? preflightClaudeExecutable(claudeExecutable, cwd) : void 0;
+  const { sessionId: resumeSessionId } = syncSharedSession(context.messages, cwd, customToolNameToSdk, model.id);
   const effort = options?.reasoning ? model.thinkingLevelMap?.[options.reasoning] ?? REASONING_TO_EFFORT[options.reasoning] : void 0;
   const extraArgs = { model: model.id };
   if (strictMcpConfigEnabled) extraArgs["strict-mcp-config"] = null;
@@ -35200,6 +35409,7 @@ function streamClaudeAgentSdk(model, context, options) {
     ...mcpServers ? { mcpServers } : {},
     ...resumeSessionId ? { resume: resumeSessionId } : {},
     ...claudeExecutable ? { pathToClaudeCodeExecutable: claudeExecutable } : {},
+    spawnClaudeCodeProcess: spawnClaudeCodeWithDiagnostics,
     ...makeCliDebugOptions("provider")
   };
   debug(
@@ -35207,6 +35417,7 @@ function streamClaudeAgentSdk(model, context, options) {
     `model=${model.id} msgs=${context.messages.length} tools=${mcpTools.length}`,
     `resume=${resumeSessionId?.slice(0, 8) ?? "none"} effort=${effort ?? "default"}`,
     `appendSys=${appendSystemPrompt} promptCtx=${promptContextAppend.labels.join(",") || "none"} strictMcp=${strictMcpConfigEnabled}`,
+    `claudeExec=${claudeExecutablePreflight ? `${claudeExecutablePreflight.fileType}:${claudeExecutablePreflight.path}` : "sdk-default"}`,
     `prompt=${promptText.slice(0, 60)}${promptBlocks ? " [+images]" : ""}`
   );
   let wasAborted = false;
@@ -35376,8 +35587,12 @@ function index_default(pi) {
 export {
   CLAUDE_BRIDGE_TOOL_ISOLATION,
   DISALLOWED_BUILTIN_TOOLS,
+  classifyClaudeExecutableBytes,
   index_default as default,
   mapToolName,
+  preflightClaudeExecutable,
   restoreSharedSessionFromPi,
-  shouldRestorePersistedBridgeEntry
+  shouldRestorePersistedBridgeEntry,
+  spawnClaudeCodeWithDiagnostics,
+  wrapClaudeSpawnErrorForSdk
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vanillagreen/pi-claude-bridge",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "description": "Pi provider bridge that runs Claude Code through the Claude Agent SDK, with opt-in forwarding for Pi prompt context.",
   "type": "module",
   "keywords": [
@@ -108,15 +108,15 @@
     "@earendil-works/pi-coding-agent": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.74.0",
-    "@earendil-works/pi-coding-agent": "^0.74.0",
+    "@earendil-works/pi-ai": "^0.75.0",
+    "@earendil-works/pi-coding-agent": "^0.75.0",
     "@types/node": "^24.3.0",
     "esbuild": "^0.28.0",
     "tsx": "^4.21.0",
     "typescript": "^6.0.3"
   },
   "scripts": {
-    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node20 --outfile=bundle/index.js --external:@earendil-works/pi-ai --external:@earendil-works/pi-coding-agent",
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node22 --outfile=bundle/index.js --external:@earendil-works/pi-ai --external:@earendil-works/pi-coding-agent",
     "prepack": "npm run build",
     "test:unit": "node --import tsx --test tests/unit-*.mjs",
     "test": "set -a && [ -f .env.test ] && . ./.env.test; set +a && npm run test:unit && tests/int-smoke.sh && tests/int-multi-turn.sh && tests/int-cache.sh && node --import tsx --test tests/int-*.mjs",
@@ -145,6 +145,14 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22.19.0"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
   }
 }

package/src/index.ts

@@ -1,11 +1,12 @@
 import { calculateCost, getModels, type AssistantMessage, type AssistantMessageEventStream, type Context, type Model, type SimpleStreamOptions, type Tool } from "@earendil-works/pi-ai";
 import * as piAi from "@earendil-works/pi-ai";
 import { type ExtensionAPI, type ExtensionUIContext } from "@earendil-works/pi-coding-agent";
-import { createSdkMcpServer, query, type EffortLevel, type SDKMessage, type SDKUserMessage, type SettingSource } from "@anthropic-ai/claude-agent-sdk";
+import { createSdkMcpServer, query, type EffortLevel, type SDKMessage, type SDKUserMessage, type SettingSource, type SpawnOptions, type SpawnedProcess } from "@anthropic-ai/claude-agent-sdk";
 import type { Base64ImageSource, ContentBlockParam, MessageParam } from "@anthropic-ai/sdk/resources";
 import { createSession, deleteSession, openSession, repairToolPairing } from "cc-session-io";
+import { spawn as spawnProcess } from "child_process";
 import { createHash } from "crypto";
-import { accessSync, appendFileSync, constants as fsConstants, mkdirSync, realpathSync, statSync } from "fs";
+import { accessSync, appendFileSync, constants as fsConstants, mkdirSync, readFileSync, realpathSync, statSync } from "fs";
 import { resolve as pathResolve } from "path";
 import { homedir } from "os";
 import { delimiter, dirname, join } from "path";
@@ -79,6 +80,240 @@ function resolveClaudeExecutable(configured?: string): string | undefined {
 	return executableFromPath("claude") ?? executableFromPath("claude-code");
 }
 
+export type ClaudeExecutableFileType = "elf" | "mach-o" | "pe" | "shebang-script" | "empty" | "unknown";
+
+export interface ClaudeExecutablePreflightResult {
+	path: string;
+	realPath: string;
+	cwd: string;
+	realCwd: string;
+	fileType: ClaudeExecutableFileType;
+}
+
+function errnoValue(err: unknown): string | number | undefined {
+	return typeof (err as NodeJS.ErrnoException)?.errno === "number" ? (err as NodeJS.ErrnoException).errno : undefined;
+}
+
+function syscallValue(err: unknown): string | undefined {
+	return typeof (err as NodeJS.ErrnoException)?.syscall === "string" ? (err as NodeJS.ErrnoException).syscall : undefined;
+}
+
+function pathValue(err: unknown): string | undefined {
+	const value = (err as NodeJS.ErrnoException)?.path;
+	return typeof value === "string" ? value : undefined;
+}
+
+function codeValue(err: unknown, fallback: string): string {
+	const value = (err as NodeJS.ErrnoException)?.code;
+	return typeof value === "string" ? value : fallback;
+}
+
+function displayValue(value: unknown): string {
+	return value === undefined || value === null || value === "" ? "<none>" : String(value);
+}
+
+function makeClaudePreflightError(
+	summary: string,
+	details: { code: string; errno?: string | number; syscall?: string; path: string; cwd: string; fileType?: ClaudeExecutableFileType; realPath?: string; cause?: unknown },
+): Error & NodeJS.ErrnoException & { cwd: string; fileType?: ClaudeExecutableFileType; realPath?: string } {
+	const detail = [
+		`code=${details.code}`,
+		`errno=${displayValue(details.errno)}`,
+		`syscall=${displayValue(details.syscall)}`,
+		`path=${details.path}`,
+		`cwd=${details.cwd}`,
+		...(details.fileType ? [`fileType=${details.fileType}`] : []),
+		...(details.realPath ? [`realPath=${details.realPath}`] : []),
+	].join(" ");
+	const error = new Error(`${summary} (${detail})`) as Error & NodeJS.ErrnoException & { cwd: string; fileType?: ClaudeExecutableFileType; realPath?: string };
+	error.name = "ClaudeExecutablePreflightError";
+	error.code = details.code;
+	if (details.errno !== undefined) error.errno = typeof details.errno === "number" ? details.errno : Number(details.errno);
+	if (details.syscall) error.syscall = details.syscall;
+	error.path = details.path;
+	error.cwd = details.cwd;
+	if (details.fileType) error.fileType = details.fileType;
+	if (details.realPath) error.realPath = details.realPath;
+	if (details.cause !== undefined) (error as Error & { cause?: unknown }).cause = details.cause;
+	return error;
+}
+
+export function classifyClaudeExecutableBytes(bytes: Uint8Array): ClaudeExecutableFileType {
+	if (bytes.length === 0) return "empty";
+	if (bytes.length >= 2 && bytes[0] === 0x23 && bytes[1] === 0x21) return "shebang-script";
+	if (bytes.length >= 4 && bytes[0] === 0x7f && bytes[1] === 0x45 && bytes[2] === 0x4c && bytes[3] === 0x46) return "elf";
+	if (bytes.length >= 2 && bytes[0] === 0x4d && bytes[1] === 0x5a) return "pe";
+	if (bytes.length >= 4) {
+		const magic = bytes[0] * 0x1000000 + bytes[1] * 0x10000 + bytes[2] * 0x100 + bytes[3];
+		if (
+			magic === 0xfeedface ||
+			magic === 0xfeedfacf ||
+			magic === 0xcefaedfe ||
+			magic === 0xcffaedfe ||
+			magic === 0xcafebabe ||
+			magic === 0xbebafeca
+		) return "mach-o";
+	}
+	return "unknown";
+}
+
+export function preflightClaudeExecutable(path: string, cwd: string): ClaudeExecutablePreflightResult {
+	let realCwd = cwd;
+	try {
+		const cwdStat = statSync(cwd);
+		if (!cwdStat.isDirectory()) {
+			throw makeClaudePreflightError("Claude Code spawn cwd preflight failed: cwd is not a directory.", {
+				code: "ENOTDIR",
+				syscall: "chdir",
+				path: cwd,
+				cwd,
+			});
+		}
+		accessSync(cwd, fsConstants.X_OK);
+		realCwd = realpathSync(cwd);
+	} catch (err) {
+		if ((err as Error).name === "ClaudeExecutablePreflightError") throw err;
+		throw makeClaudePreflightError("Claude Code spawn cwd preflight failed: cwd is not reachable before spawning Claude Code.", {
+			code: codeValue(err, "EACCES"),
+			errno: errnoValue(err),
+			syscall: syscallValue(err),
+			path: pathValue(err) ?? cwd,
+			cwd,
+			cause: err,
+		});
+	}
+
+	let realPath = path;
+	try {
+		const stat = statSync(path);
+		if (!stat.isFile()) {
+			throw makeClaudePreflightError("Claude Code executable preflight failed: resolved path is not a file.", {
+				code: "EACCES",
+				syscall: "exec",
+				path,
+				cwd,
+			});
+		}
+		accessSync(path, fsConstants.X_OK);
+		realPath = realpathSync(path);
+	} catch (err) {
+		if ((err as Error).name === "ClaudeExecutablePreflightError") throw err;
+		throw makeClaudePreflightError("Claude Code executable preflight failed: cannot access resolved executable before spawning Claude Code.", {
+			code: codeValue(err, "ENOENT"),
+			errno: errnoValue(err),
+			syscall: syscallValue(err),
+			path: pathValue(err) ?? path,
+			cwd,
+			cause: err,
+		});
+	}
+
+	let fileType: ClaudeExecutableFileType;
+	try {
+		fileType = classifyClaudeExecutableBytes(readFileSync(realPath).subarray(0, 16));
+	} catch (err) {
+		throw makeClaudePreflightError("Claude Code executable preflight failed: cannot read executable header before spawning Claude Code.", {
+			code: codeValue(err, "EACCES"),
+			errno: errnoValue(err),
+			syscall: syscallValue(err),
+			path: pathValue(err) ?? realPath,
+			cwd,
+			realPath,
+			cause: err,
+		});
+	}
+
+	if (!["elf", "mach-o", "pe", "shebang-script"].includes(fileType)) {
+		throw makeClaudePreflightError("Claude Code executable preflight failed: executable header is not an ELF, Mach-O, PE, or shebang script.", {
+			code: "ENOEXEC",
+			syscall: "exec",
+			path,
+			cwd,
+			fileType,
+			realPath,
+		});
+	}
+
+	return { path, realPath, cwd, realCwd, fileType };
+}
+
+function envFlagEnabled(value: string | undefined): boolean {
+	return value === "1" || value?.toLowerCase() === "true";
+}
+
+export function wrapClaudeSpawnErrorForSdk(err: Error, options: SpawnOptions): Error & NodeJS.ErrnoException & { cwd: string; originalCode?: string; originalMessage?: string } {
+	const originalCode = codeValue(err, "SPAWN_ERROR");
+	const originalMessage = err.message;
+	const spawnPath = pathValue(err) ?? options.command;
+	const cwd = options.cwd ?? process.cwd();
+	const detail = [
+		`code=${originalCode}`,
+		`errno=${displayValue(errnoValue(err))}`,
+		`syscall=${displayValue(syscallValue(err))}`,
+		`path=${spawnPath}`,
+		`cwd=${cwd}`,
+		`command=${options.command}`,
+	].join(" ");
+	const wrapped = new Error(`Claude Code spawn failed: ${originalMessage} (${detail})`) as Error & NodeJS.ErrnoException & { cwd: string; originalCode?: string; originalMessage?: string };
+	wrapped.name = "ClaudeSpawnDiagnosticError";
+	// The SDK special-cases code === ENOENT and replaces the message with its
+	// generic "native binary not found" text. Preserve the original code in the
+	// message/originalCode while using a bridge code so the SDK surfaces context.
+	wrapped.code = originalCode === "ENOENT" ? "CLAUDE_BRIDGE_SPAWN_FAILED" : originalCode;
+	wrapped.originalCode = originalCode;
+	wrapped.originalMessage = originalMessage;
+	const errno = errnoValue(err);
+	if (errno !== undefined) wrapped.errno = typeof errno === "number" ? errno : Number(errno);
+	const syscall = syscallValue(err);
+	if (syscall) wrapped.syscall = syscall;
+	wrapped.path = spawnPath;
+	wrapped.cwd = cwd;
+	// Do not set `cause` here: the listener copies these structured fields back
+	// onto the original Error. A cause reference to that same object would become
+	// `err.cause === err`, making JSON.stringify throw on a circular structure.
+	// originalMessage plus code/errno/syscall/path/cwd preserve the useful data.
+	return wrapped;
+}
+
+export function spawnClaudeCodeWithDiagnostics(options: SpawnOptions): SpawnedProcess {
+	const pipeStderr = DEBUG || envFlagEnabled(options.env.DEBUG_CLAUDE_AGENT_SDK);
+	const child = spawnProcess(options.command, options.args, {
+		cwd: options.cwd,
+		env: options.env,
+		signal: options.signal,
+		stdio: ["pipe", "pipe", pipeStderr ? "pipe" : "ignore"],
+		windowsHide: true,
+	});
+	if (pipeStderr) {
+		child.stderr?.on("data", (data) => {
+			for (const line of data.toString().split(/\r?\n/)) {
+				if (line) debug(`[cli-stderr spawn] ${line}`);
+			}
+		});
+	}
+	child.prependListener("error", (err) => {
+		const originalStack = err.stack;
+		const wrapped = wrapClaudeSpawnErrorForSdk(err, options);
+		Object.assign(err, wrapped);
+		err.name = wrapped.name;
+		err.message = wrapped.message;
+		// Keep V8's stack from the actual Node spawn failure, not the wrapper
+		// construction site. Diagnostic fields above remain enumerable and
+		// JSON-serializable; stack stays the spawn-time breadcrumb for operators.
+		if (originalStack) err.stack = originalStack;
+	});
+	return {
+		stdin: child.stdin,
+		stdout: child.stdout,
+		get killed() { return child.killed; },
+		get exitCode() { return child.exitCode; },
+		kill: child.kill.bind(child),
+		on: child.on.bind(child),
+		once: child.once.bind(child),
+		off: child.off.bind(child),
+	};
+}
+
 // Per-query CLI debug capture. When CLAUDE_BRIDGE_DEBUG=1, ask the Claude Code
 // CLI subprocess to write its own debug log to a file we choose, and also
 // forward its stderr into our debug stream. Drops straight into the real SDK's
@@ -1072,7 +1307,6 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 
 	const { mcpTools, customToolNameToSdk, customToolNameToPi } = resolveMcpTools(context);
 	const cwd = (options as { cwd?: string } | undefined)?.cwd ?? process.cwd();
-	const { sessionId: resumeSessionId } = syncSharedSession(context.messages, cwd, customToolNameToSdk, model.id);
 	const promptBlocks = extractUserPromptBlocks(context.messages);
 	let promptText = extractUserPrompt(context.messages) ?? "";
 
@@ -1114,6 +1348,8 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 		: providerSettings.settingSources ?? ["user", "project"];
 	const strictMcpConfigEnabled = !appendSystemPrompt && providerSettings.strictMcpConfig !== false;
 	const claudeExecutable = resolveClaudeExecutable(providerSettings.pathToClaudeCodeExecutable);
+	const claudeExecutablePreflight = claudeExecutable ? preflightClaudeExecutable(claudeExecutable, cwd) : undefined;
+	const { sessionId: resumeSessionId } = syncSharedSession(context.messages, cwd, customToolNameToSdk, model.id);
 
 	// Prefer the model's own thinkingLevelMap when present (pi-ai 0.72+ ships
 	// per-model overrides — e.g. opus-4-7 wants xhigh→xhigh, not xhigh→max).
@@ -1156,6 +1392,7 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 		...(mcpServers ? { mcpServers } : {}),
 		...(resumeSessionId ? { resume: resumeSessionId } : {}),
 		...(claudeExecutable ? { pathToClaudeCodeExecutable: claudeExecutable } : {}),
+		spawnClaudeCodeProcess: spawnClaudeCodeWithDiagnostics,
 		...makeCliDebugOptions("provider"),
 	};
 
@@ -1163,6 +1400,7 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 		`model=${model.id} msgs=${context.messages.length} tools=${mcpTools.length}`,
 		`resume=${resumeSessionId?.slice(0, 8) ?? "none"} effort=${effort ?? "default"}`,
 		`appendSys=${appendSystemPrompt} promptCtx=${promptContextAppend.labels.join(",") || "none"} strictMcp=${strictMcpConfigEnabled}`,
+		`claudeExec=${claudeExecutablePreflight ? `${claudeExecutablePreflight.fileType}:${claudeExecutablePreflight.path}` : "sdk-default"}`,
 		`prompt=${promptText.slice(0, 60)}${promptBlocks ? " [+images]" : ""}`);
 
 	// 3. Start SDK query and claim it for this context

package/src/prompt-context.ts

@@ -76,8 +76,15 @@ function extractHeadingSection(systemPrompt: string | undefined, headings: strin
 	}
 	if (start < 0) return undefined;
 	const rest = systemPrompt.slice(start).trim();
-	const nextHeading = rest.slice(1).search(/\n##\s+/);
-	return (nextHeading >= 0 ? rest.slice(0, nextHeading + 1) : rest).trim();
+	const endCandidates = [
+		rest.slice(1).search(/\n##\s+/),
+		rest.search(/\n<\/project_instructions>/),
+		rest.search(/\n<\/project_context>/),
+	]
+		.map((index, offset) => (index >= 0 && offset === 0 ? index + 1 : index))
+		.filter((index) => index >= 0);
+	const end = endCandidates.length > 0 ? Math.min(...endCandidates) : -1;
+	return (end >= 0 ? rest.slice(0, end) : rest).trim();
 }
 
 function extractBlockByMarkers(systemPrompt: string | undefined, markers: RegExp[]): string | undefined {
@@ -93,7 +100,7 @@ export function buildPromptContextAppend(systemPrompt: string | undefined, cwd:
 
 	if (settings.includeAppendSystemPromptMd) {
 		for (const file of readAppendSystemPromptFiles(cwd)) {
-			parts.push(`### ${file.label}\n\n${file.content}`);
+			parts.push(xmlBlock("append_system_prompt", { label: file.label }, file.content));
 			labels.push(file.label);
 		}
 	}
@@ -101,7 +108,7 @@ export function buildPromptContextAppend(systemPrompt: string | undefined, cwd:
 	if (settings.includeProjectAgentsHook) {
 		const projectAgents = extractHeadingSection(systemPrompt, ["## Project Agents", "## Project Subagents"]);
 		if (projectAgents) {
-			parts.push(`### before_agent_start: project agents\n\n${projectAgents}`);
+			parts.push(xmlBlock("before_agent_start", { source: "project-agents" }, projectAgents));
 			labels.push("project agents hook");
 		}
 	}
@@ -109,7 +116,7 @@ export function buildPromptContextAppend(systemPrompt: string | undefined, cwd:
 	if (settings.includeTaskPanelHook) {
 		const taskReminder = extractBlockByMarkers(systemPrompt, [/^Task workflow reminder:/]);
 		if (taskReminder) {
-			parts.push(`### before_agent_start: task panel\n\n${taskReminder}`);
+			parts.push(xmlBlock("before_agent_start", { source: "task-panel" }, taskReminder));
 			labels.push("task panel hook");
 		}
 	}
@@ -117,7 +124,7 @@ export function buildPromptContextAppend(systemPrompt: string | undefined, cwd:
 	if (settings.includeCavemanHook) {
 		const caveman = extractBlockByMarkers(systemPrompt, [/^You MUST respond in caveman /m]);
 		if (caveman) {
-			parts.push(`### before_agent_start: caveman\n\n${caveman}`);
+			parts.push(xmlBlock("before_agent_start", { source: "caveman" }, caveman));
 			labels.push("caveman hook");
 		}
 	}
@@ -125,10 +132,37 @@ export function buildPromptContextAppend(systemPrompt: string | undefined, cwd:
 	if (parts.length === 0) return { labels };
 	return {
 		labels,
-		text: [
-			"## Forwarded Pi Context",
-			"The following content was explicitly enabled in pi-claude-bridge settings and comes from Pi prompt files or before_agent_start prompt hooks.",
-			...parts,
-		].join("\n\n"),
+		text: xmlBlock(
+			"forwarded_pi_context",
+			{},
+			[
+				"The following content was explicitly enabled in pi-claude-bridge settings and comes from Pi prompt files or before_agent_start prompt hooks.",
+				...parts,
+			].join("\n\n"),
+			false,
+		),
 	};
 }
+
+function escapeXmlAttr(value: string): string {
+	return value
+		.replace(/&/g, "&amp;")
+		.replace(/"/g, "&quot;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;");
+}
+
+function escapeXmlText(value: string): string {
+	return value
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;");
+}
+
+function xmlBlock(tag: string, attrs: Record<string, string>, content: string, escapeContent = true): string {
+	const attrText = Object.entries(attrs)
+		.map(([key, value]) => ` ${key}="${escapeXmlAttr(value)}"`)
+		.join("");
+	const body = escapeContent ? escapeXmlText(content.trim()) : content.trim();
+	return `<${tag}${attrText}>\n${body}\n</${tag}>`;
+}