@tekmidian/pai 0.42.0 → 0.42.2

package/src/hooks/ts/lib/mcp-deferred-gate.ts

@@ -0,0 +1,261 @@
+/**
+ * mcp-deferred-gate.ts — pure pieces of the deferred MCP tool gate.
+ *
+ * Claude Code defers MCP tool schemas: an mcp__server__tool call fails input
+ * validation unless the session surfaced the schema via ToolSearch first.
+ * Sessions misread that error as "MCP server disconnected" and report an
+ * outage that never happened (observed with a rename tool while every server
+ * was connected).
+ *
+ * A second failure shape: when an MCP server re-registers mid-session, the
+ * session's deferred tool handles are invalidated and calls fail with the
+ * harness text "N deferred tools are no longer available" (observed 2026-09-18,
+ * N=411, a rename tool). Sessions misread that as a disconnect too. The gate
+ * denies that shape with the same ToolSearch remedy; a ToolSearch that
+ * surfaces the tool after the last invalidation re-arms the pass-through.
+ *
+ * The decision is evidence-based: the session transcript either shows the tool
+ * was surfaced (a ToolSearch mentioning it) or already ran successfully — in
+ * which case the schema is loaded and the call passes through untouched — or
+ * it shows neither, in which case the call is about to hit the gate (or is a
+ * retry that just did) and gets the corrective instruction.
+ *
+ * Split out of the pre-tool-use entrypoint (which calls main() at import
+ * time) so the decision is testable without spawning a hook process, per the
+ * transcript-text.ts precedent.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface GateHookInput {
+  session_id?: string;
+  transcript_path?: string;
+  cwd?: string;
+  tool_name?: string;
+  tool_input?: unknown;
+}
+
+export interface GateEvidence {
+  /** A ToolSearch call in the transcript mentions this tool by full name. */
+  surfacedByToolSearch: boolean;
+  /** This tool already ran successfully — its schema must be loaded. */
+  succeededBefore: boolean;
+}
+
+export interface GateObservation {
+  type: "decision";
+  title: string;
+  narrative: string;
+  tool_name: string;
+  tool_input_summary: string;
+  files_read: string[];
+  files_modified: string[];
+  concepts: string[];
+}
+
+export interface GateDecision {
+  action: "pass" | "correct";
+  /** The JSON string to write to stdout, same shape as sibling PreToolUse hooks. */
+  output: string;
+  /** Observation payload for the daemon when a correction fired, else null. */
+  observation: GateObservation | null;
+}
+
+// ---------------------------------------------------------------------------
+// Decision
+// ---------------------------------------------------------------------------
+
+export const PASS_OUTPUT = JSON.stringify({
+  hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow" },
+});
+
+/**
+ * Harness text emitted when a mid-session MCP server re-registration
+ * invalidates the session's deferred tool handles.
+ */
+export const STALE_HANDLE_MARKER = "deferred tools are no longer available";
+
+/** True for MCP tool names (`mcp__<server>__<tool>`), false for everything else. */
+export function isMcpTool(name: string): boolean {
+  return name.startsWith("mcp__") && name.split("__").length >= 3 && !!name.split("__")[2];
+}
+
+/**
+ * Scan transcript text (JSONL, one entry per line, tolerant of junk) for
+ * evidence that `toolName` is loadable in this session.
+ */
+export function scanTranscriptEvidence(transcriptText: string, toolName: string): GateEvidence {
+  const toolUseIds = new Set<string>();
+  let surfacedByToolSearch = false;
+  let succeededBefore = false;
+
+  for (const line of transcriptText.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let entry: unknown;
+    try {
+      entry = JSON.parse(trimmed);
+    } catch {
+      continue;
+    }
+    const message = (entry as { message?: { content?: unknown } })?.message;
+    const content = message?.content;
+    if (!Array.isArray(content)) continue;
+
+    for (const block of content as Array<Record<string, unknown>>) {
+      if (!block || typeof block !== "object") continue;
+      if (block.type === "tool_use" && typeof block.name === "string") {
+        if (block.name === toolName && typeof block.id === "string") {
+          toolUseIds.add(block.id);
+        } else if (block.name === "ToolSearch") {
+          // Liberal match: the query may be "select:<tool>" or a keyword list.
+          if (JSON.stringify(block.input ?? "").includes(toolName)) {
+            surfacedByToolSearch = true;
+          }
+        }
+      } else if (
+        block.type === "tool_result" &&
+        typeof block.tool_use_id === "string" &&
+        toolUseIds.has(block.tool_use_id) &&
+        !block.is_error
+      ) {
+        succeededBefore = true;
+      }
+    }
+  }
+
+  return { surfacedByToolSearch, succeededBefore };
+}
+
+/**
+ * Byte index of the last transcript line where a ToolSearch call surfaced
+ * `toolName` (same liberal match as scanTranscriptEvidence), or -1 if never.
+ * Used to order the stale-handle remedy against the last invalidation.
+ */
+export function lastToolSearchSurfacingIndex(
+  transcriptText: string,
+  toolName: string,
+): number {
+  let last = -1;
+  let offset = 0;
+  for (const line of transcriptText.split("\n")) {
+    const start = offset;
+    offset += line.length + 1;
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let entry: unknown;
+    try {
+      entry = JSON.parse(trimmed);
+    } catch {
+      continue;
+    }
+    const content = (entry as { message?: { content?: unknown } })?.message?.content;
+    if (!Array.isArray(content)) continue;
+    for (const block of content as Array<Record<string, unknown>>) {
+      if (
+        block?.type === "tool_use" &&
+        block.name === "ToolSearch" &&
+        JSON.stringify(block.input ?? "").includes(toolName)
+      ) {
+        last = start;
+      }
+    }
+  }
+  return last;
+}
+
+/** The ToolSearch remedy shared by both correction shapes. */
+function buildRemedy(toolName: string): string {
+  return (
+    `Remedy: call ToolSearch with query "select:${toolName}" to load the fresh registry ` +
+    `entry, then call ${toolName} again with the same arguments.`
+  );
+}
+
+/** The corrective instruction fed back to the session on a deny. */
+export function buildCorrection(toolName: string): string {
+  return (
+    `${toolName} is a deferred MCP tool: its schema is not loaded in this session yet, so this ` +
+    `call would fail input validation. The MCP server is NOT disconnected — do not report an ` +
+    `outage and do not retry the call unchanged. ${buildRemedy(toolName)}`
+  );
+}
+
+/** Same remedy for the stale-handle shape: a re-registration invalidated a loaded schema. */
+export function buildStaleHandleCorrection(toolName: string): string {
+  return (
+    `${toolName}'s deferred tool handle is stale: the MCP server re-registered mid-session, ` +
+    `invalidating the schema this session had loaded ("${STALE_HANDLE_MARKER}"). The MCP ` +
+    `server is NOT disconnected — do not report an outage and do not retry the call ` +
+    `unchanged. ${buildRemedy(toolName)}`
+  );
+}
+
+/** The deny decision shared by both failure shapes. */
+function correctDecision(toolName: string, reason: string, narrative: string): GateDecision {
+  return {
+    action: "correct",
+    output: JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: reason,
+      },
+    }),
+    observation: {
+      type: "decision",
+      title: `MCP deferred-tool gate corrected: ${toolName}`,
+      narrative,
+      tool_name: toolName,
+      tool_input_summary: toolName,
+      files_read: [],
+      files_modified: [],
+      concepts: ["mcp", "deferred", "toolsearch"],
+    },
+  };
+}
+
+/**
+ * The whole gate: given hook input and the session transcript, decide whether
+ * this mcp__ call passes through or gets the deferred-schema correction.
+ */
+export function decideMcpGate(input: GateHookInput, transcriptText: string): GateDecision {
+  const toolName = typeof input.tool_name === "string" ? input.tool_name : "";
+  if (!isMcpTool(toolName)) {
+    return { action: "pass", output: PASS_OUTPUT, observation: null };
+  }
+
+  // Stale-handle shape: a mid-session re-registration invalidated loaded
+  // schemas. Overrides the normal evidence pass-through, because a tool that
+  // was surfaced (or even ran) earlier can still have a dead handle now. The
+  // gate re-arms to pass-through only once a ToolSearch re-surfaced the tool
+  // after the last invalidation.
+  const toolInputText = JSON.stringify(input.tool_input ?? "");
+  const lastStale = transcriptText.lastIndexOf(STALE_HANDLE_MARKER);
+  if (toolInputText.includes(STALE_HANDLE_MARKER) || lastStale !== -1) {
+    const remedyAt = lastToolSearchSurfacingIndex(transcriptText, toolName);
+    if (remedyAt === -1 || remedyAt <= lastStale) {
+      return correctDecision(
+        toolName,
+        buildStaleHandleCorrection(toolName),
+        `Blocked a retry against a stale deferred-tool handle for ${toolName} and issued ` +
+          "the ToolSearch remedy (server not disconnected)",
+      );
+    }
+    return { action: "pass", output: PASS_OUTPUT, observation: null };
+  }
+
+  const evidence = scanTranscriptEvidence(transcriptText, toolName);
+  if (evidence.surfacedByToolSearch || evidence.succeededBefore) {
+    return { action: "pass", output: PASS_OUTPUT, observation: null };
+  }
+
+  return correctDecision(
+    toolName,
+    buildCorrection(toolName),
+    `Blocked a call to deferred MCP tool ${toolName} and issued the ToolSearch remedy ` +
+      "(server not disconnected)",
+  );
+}

package/src/hooks/ts/lib/mcp-deferred-reminder.test.ts

@@ -0,0 +1,90 @@
+import { describe, it, expect } from "vitest";
+import { execFileSync } from "node:child_process";
+import {
+  buildReminder,
+  decideMcpDeferredReminder,
+  REMINDER_SOURCES,
+  type ReminderHookInput,
+} from "./mcp-deferred-reminder.js";
+import { STALE_HANDLE_MARKER } from "./mcp-deferred-gate.js";
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+function hookInput(source?: string): ReminderHookInput {
+  return { source };
+}
+
+// ---------------------------------------------------------------------------
+// Decision
+// ---------------------------------------------------------------------------
+
+describe("decideMcpDeferredReminder", () => {
+  it("emits the reminder for source resume", () => {
+    const out = decideMcpDeferredReminder(hookInput("resume"));
+    expect(out).not.toBeNull();
+    expect(out).toContain("ToolSearch");
+    expect(out).toContain("retry once");
+    expect(out).toContain(STALE_HANDLE_MARKER);
+  });
+
+  it("emits the reminder for source compact", () => {
+    expect(decideMcpDeferredReminder(hookInput("compact"))).not.toBeNull();
+  });
+
+  it("reminder stays consistent with the gate's shared stale-handle marker", () => {
+    expect(buildReminder()).toContain(`"${STALE_HANDLE_MARKER}"`);
+    expect(REMINDER_SOURCES).toEqual(new Set(["resume", "compact"]));
+  });
+
+  it("stays silent for source startup", () => {
+    expect(decideMcpDeferredReminder(hookInput("startup"))).toBeNull();
+  });
+
+  it("stays silent for source clear", () => {
+    expect(decideMcpDeferredReminder(hookInput("clear"))).toBeNull();
+  });
+
+  it("stays silent for missing or junk source", () => {
+    expect(decideMcpDeferredReminder({})).toBeNull();
+    expect(decideMcpDeferredReminder(hookInput("nonsense"))).toBeNull();
+    expect(decideMcpDeferredReminder(hookInput("RESUME"))).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Entrypoint — junk input must exit 0 with nothing on stdout
+// ---------------------------------------------------------------------------
+
+describe("session-start/mcp-deferred-reminder entrypoint", () => {
+  const ENTRYPOINT = "src/hooks/ts/session-start/mcp-deferred-reminder.ts";
+
+  function runHook(stdin: string): { status: number; stdout: string } {
+    const stdout = execFileSync("bun", [ENTRYPOINT], {
+      input: stdin,
+      encoding: "utf8",
+      timeout: 15_000,
+    });
+    return { status: 0, stdout };
+  }
+
+  it("junk input exits 0 silent", () => {
+    const { status, stdout } = runHook("this is not json {{{");
+    expect(status).toBe(0);
+    expect(stdout).toBe("");
+  });
+
+  it("resume input exits 0 with the reminder on stdout", () => {
+    const { status, stdout } = runHook(JSON.stringify({ source: "resume" }));
+    expect(status).toBe(0);
+    expect(stdout).toContain("ToolSearch");
+    expect(stdout).toContain("retry once");
+  });
+
+  it("startup input exits 0 silent", () => {
+    const { status, stdout } = runHook(JSON.stringify({ source: "startup" }));
+    expect(status).toBe(0);
+    expect(stdout).toBe("");
+  });
+});

package/src/hooks/ts/lib/mcp-deferred-reminder.ts

@@ -0,0 +1,66 @@
+/**
+ * mcp-deferred-reminder.ts — pure pieces of the session-start deferred-handle reminder.
+ *
+ * A resumed session inherits its transcript, and a transcript can contain a
+ * mid-session MCP re-registration: the deferred tool handles the session held
+ * are stale from then on ("deferred tools are no longer available"). The
+ * call-time gate (../pre-tool-use/mcp-deferred-gate.ts) can only correct a call
+ * that is still ATTEMPTED — but a resumed session that already concluded once
+ * that "the MCP server is disconnected" never retries, so the gate never fires
+ * (observed 2026-09-18: 37s of thinking, then a skip on "aibroker is down
+ * right now"). The cure has to arrive before the first tool call, at session
+ * start: a fresh claim that stale history is not evidence, so the model
+ * attempts the call and lands in the gate if the handle really is stale.
+ *
+ * Fired for sources "resume" and "compact" only — fresh sessions have no
+ * stale handles and no stale conclusions to unlearn.
+ *
+ * Split out of the session-start entrypoint so the decision is testable
+ * without spawning a hook process, per the mcp-deferred-gate.ts precedent.
+ */
+
+// Reused so reminder and gate corrections read as one instrument.
+import { STALE_HANDLE_MARKER } from "./mcp-deferred-gate.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ReminderHookInput {
+  source?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Decision
+// ---------------------------------------------------------------------------
+
+/**
+ * SessionStart sources the reminder applies to. "startup" and "clear" begin
+ * with an empty session state — nothing to heal there.
+ */
+export const REMINDER_SOURCES = new Set(["resume", "compact"]);
+
+/** The exact reminder text; exported so tests can match against the real thing. */
+export function buildReminder(): string {
+  return (
+    `<system-reminder>\n` +
+    `Resumed sessions keep stale deferred MCP tool handles: a mid-session MCP server ` +
+    `re-registration invalidates every loaded mcp__ schema ("${STALE_HANDLE_MARKER}"). ` +
+    `If any mcp__ tool call fails or a tool seems unavailable: run ToolSearch with query ` +
+    `"select:<full tool name>" and retry once. A prior "the MCP server is disconnected" ` +
+    `conclusion in this history is stale evidence — do not skip the retry; only a call ` +
+    `failing after a fresh ToolSearch proves an outage.\n` +
+    `</system-reminder>`
+  );
+}
+
+/**
+ * The whole reminder: given hook input, return the stdout payload for sources
+ * resume/compact, or null for every other (silent exit 0).
+ */
+export function decideMcpDeferredReminder(input: ReminderHookInput): string | null {
+  if (typeof input.source !== "string" || !REMINDER_SOURCES.has(input.source)) {
+    return null;
+  }
+  return buildReminder();
+}

package/src/hooks/ts/pre-tool-use/mcp-deferred-gate.ts

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+
+/**
+ * mcp-deferred-gate.ts — PreToolUse hook on mcp__* tools.
+ *
+ * Claude Code defers MCP tool schemas: calling a deferred mcp__server__tool
+ * without surfacing it via ToolSearch fails input validation, and sessions
+ * misread that as "MCP server disconnected" — as they do the stale handles a
+ * mid-session server re-registration leaves behind ("deferred tools are no
+ * longer available"). PreToolUse is the only event on
+ * the attempt path — when the schema gate rejects the call the tool never
+ * runs, so no PostToolUse fires to correct it. A deny here lands the remedy
+ * in the same channel the model already reads (same mechanism as
+ * route-agents-to-worker), and the transcript evidence check in
+ * ../lib/mcp-deferred-gate.ts keeps already-loaded tools passing through
+ * untouched.
+ *
+ * Every correction is appended to the observation store via daemon IPC (same
+ * fire-and-forget path as observe.ts), so false-outage reports are countable.
+ * Never blocks Claude Code: always exits 0, tolerant of missing transcript.
+ */
+
+import { closeSync, fstatSync, openSync, readSync } from "node:fs";
+import { connect } from "node:net";
+import { decideMcpGate, PASS_OUTPUT, type GateHookInput } from "../lib/mcp-deferred-gate.js";
+import { isProbeSession } from "../lib/project-utils.js";
+
+/** Enough transcript to see the whole recent tool history; transcripts can be huge. */
+const TRANSCRIPT_TAIL_BYTES = 512 * 1024;
+
+// ---------------------------------------------------------------------------
+// Transcript tail — bounded read, never loads the whole file
+// ---------------------------------------------------------------------------
+
+function readTranscriptTail(path: string): string {
+  try {
+    const fd = openSync(path, "r");
+    try {
+      const size = fstatSync(fd).size;
+      const length = Math.min(size, TRANSCRIPT_TAIL_BYTES);
+      const buffer = Buffer.alloc(length);
+      readSync(fd, buffer, 0, length, size - length);
+      return buffer.toString("utf-8");
+    } finally {
+      closeSync(fd);
+    }
+  } catch {
+    return "";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Inline IPC sender — avoids importing src/daemon/ipc-client.ts at build time
+// ---------------------------------------------------------------------------
+
+function sendToDaemon(method: string, params: Record<string, unknown>): Promise<void> {
+  return new Promise((resolve) => {
+    const timeout = setTimeout(() => {
+      resolve();
+    }, 5000);
+    try {
+      const socket = connect("/tmp/pai.sock", () => {
+        const req = JSON.stringify({ id: Date.now().toString(), method, params }) + "\n";
+        socket.write(req);
+        socket.on("data", () => {
+          clearTimeout(timeout);
+          socket.destroy();
+          resolve();
+        });
+        socket.on("error", () => {
+          clearTimeout(timeout);
+          resolve();
+        });
+      });
+      socket.on("error", () => {
+        clearTimeout(timeout);
+        resolve();
+      });
+    } catch {
+      clearTimeout(timeout);
+      resolve();
+    }
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main(): Promise<void> {
+  let text = "";
+  try {
+    for await (const chunk of process.stdin) text += chunk;
+  } catch {
+    process.stdout.write(PASS_OUTPUT);
+    return;
+  }
+  if (!text.trim()) {
+    process.stdout.write(PASS_OUTPUT);
+    return;
+  }
+
+  let input: GateHookInput;
+  try {
+    input = JSON.parse(text) as GateHookInput;
+  } catch {
+    process.stdout.write(PASS_OUTPUT);
+    return;
+  }
+
+  const transcript =
+    typeof input.transcript_path === "string" ? readTranscriptTail(input.transcript_path) : "";
+  const decision = decideMcpGate(input, transcript);
+  process.stdout.write(decision.output);
+
+  if (decision.observation && !isProbeSession(input.cwd)) {
+    await sendToDaemon("observation_store", {
+      session_id: input.session_id ?? "",
+      ...decision.observation,
+      content_hash: "",
+      cwd: input.cwd ?? "",
+    });
+  }
+}
+
+main().catch(() => process.stdout.write(PASS_OUTPUT));

package/src/hooks/ts/pre-tool-use/route-agents-to-worker.ts

@@ -17,7 +17,7 @@
  * Every decision is appended to the routing ledger read by `pai worker log`.
  */
 
-import { readWorkersSection } from "../../../workers/config.js";
+import { readWorkersSection, ANTHROPIC_NATIVE } from "../../../workers/config.js";
 import { workersLogDir, ledgerPath } from "../../../workers/paths.js";
 import { appendLedger } from "../../../workers/ledger.js";
 
@@ -102,7 +102,11 @@ async function main(): Promise<void> {
     process.stdout.write(ALLOW);
     return;
   }
-  if (!workers.enabled || Object.keys(workers.providers).length === 0) {
+  if (
+    !workers.enabled ||
+    Object.keys(workers.providers).length === 0 ||
+    workers.active === ANTHROPIC_NATIVE
+  ) {
     process.stdout.write(ALLOW);
     return;
   }

package/src/hooks/ts/session-start/mcp-deferred-reminder.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+/**
+ * mcp-deferred-reminder.ts — SessionStart hook (matchers: resume, compact)
+ *
+ * Resumed sessions can inherit stale deferred MCP tool handles (a mid-session
+ * server re-registration) together with a stale "the MCP server is
+ * disconnected" conclusion from before the restart — a combination that makes
+ * the session skip the retry the call-time gate would need in order to fire.
+ * This hook injects the counter-instruction at session start, before any tool
+ * call: see ../lib/mcp-deferred-reminder.ts for the rationale and text.
+ *
+ * stdout is captured by Claude Code and injected into the session context,
+ * same channel as session-commands/inject-observations. Never blocks session
+ * start: always exits 0.
+ */
+
+import { decideMcpDeferredReminder, type ReminderHookInput } from "../lib/mcp-deferred-reminder.js";
+
+async function main() {
+  let input: ReminderHookInput = {};
+
+  try {
+    const decoder = new TextDecoder();
+    let raw = '';
+    const timeoutPromise = new Promise<void>((resolve) => { setTimeout(resolve, 500); });
+    const readPromise = (async () => {
+      for await (const chunk of process.stdin) {
+        raw += decoder.decode(chunk, { stream: true });
+      }
+    })();
+    await Promise.race([readPromise, timeoutPromise]);
+    if (raw.trim()) {
+      input = JSON.parse(raw) as ReminderHookInput;
+    }
+  } catch {
+    // Junk input: stay silent, exit 0
+    process.exit(0);
+  }
+
+  const reminder = decideMcpDeferredReminder(input);
+  if (reminder) {
+    console.log(reminder);
+    console.error(`mcp-deferred-reminder: injected reminder for source=${input.source}`);
+  }
+
+  process.exit(0);
+}
+
+main().catch(() => {
+  process.exit(0);
+});