@inceptionstack/pi-hard-no 1.0.0

package/reviewer.ts

@@ -0,0 +1,433 @@
+/**
+ * reviewer.ts — Review session runner
+ *
+ * The reviewer gets:
+ * - Per-file git diffs and recent commit messages
+ * - Full paths of changed files
+ * - Read-only tools to read files and explore the codebase
+ * - Live status updates shown in the main pi status bar
+ *
+ * The reviewer reads each file itself via read(path) tool calls.
+ * Uses the standardized file logger for all diagnostic output.
+ */
+
+import {
+  createAgentSession,
+  SessionManager,
+  AuthStorage,
+  ModelRegistry,
+  type AgentSessionEvent,
+} from "@mariozechner/pi-coding-agent";
+
+import { log, logReview, safeStringify, type ReviewToolCall } from "./logger";
+
+export interface ReviewResult {
+  /** Cleaned review text shown to the user. */
+  text: string;
+  /** Raw LLM output before cleanup (for debugging / structured log). */
+  rawText: string;
+  isLgtm: boolean;
+  durationMs: number;
+  /** Every tool call the reviewer made during exploration. */
+  toolCalls: ReviewToolCall[];
+  /** Effective model used for the review. */
+  model: string;
+  /** Effective thinking level used. */
+  thinkingLevel: string;
+}
+
+export interface ReviewOptions {
+  signal: AbortSignal;
+  cwd: string;
+  /** "provider/model-id" to use for the reviewer */
+  model?: string;
+  /** Thinking level: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" */
+  thinkingLevel?: string;
+  /** Max wall-clock for main prompt (ms). Default 120000. */
+  timeoutMs?: number;
+  /** Files being reviewed (used in the structured log record). */
+  filesReviewed?: string[];
+  /** Unique id for this review cycle — used as a log prefix and embedded in the structured record. */
+  reviewId?: string;
+  /** Called when the reviewer uses tools — for status bar updates */
+  onActivity?: (description: string) => void;
+  /** Called with structured tool call info — for display widget */
+  onToolCall?: (toolName: string, targetPath: string | null) => void;
+}
+
+export type ReviewRunner = (prompt: string, opts: ReviewOptions) => Promise<ReviewResult>;
+
+/** Review text markers that indicate where the actual review findings start. */
+const REVIEW_MARKERS = [
+  /\n##\s*Review/i,
+  /\n##\s*Issues/i,
+  /\n##\s*Findings/i,
+  /\nHere'?s my review/i,
+  /\nHere are the issues/i,
+  /\n-\s*\*\*(High|Medium|Low)/i,
+  /\n-\s*\[(High|Medium|Low)/i,
+  /\n\*\*Issues found/i,
+  /No issues found\./i,
+];
+
+/**
+ * Strip tool-call noise from raw review text.
+ * Order: strip verdict tags → find review start marker → strip XML tags.
+ */
+export function cleanReviewText(raw: string): string {
+  // Strip verdict tags FIRST so they don't interfere with marker detection
+  let text = stripVerdict(raw);
+
+  // Find where the actual review findings start
+  for (const marker of REVIEW_MARKERS) {
+    const match = text.match(marker);
+    if (match?.index !== undefined && match.index > 0) {
+      text = text.slice(match.index).trim();
+      break;
+    }
+  }
+
+  // Strip XML-style tool tags
+  text = text.replace(/<(bash|read_file|grep|find|ls)[^>]*>[\s\S]*?<\/\1>/g, "");
+  text = text.replace(/<(bash|read_file|grep|find|ls)[^>]*\/>/g, "");
+  return text.trim();
+}
+
+/**
+ * Severity markers that indicate the reviewer found issues.
+ * If any of these appear in the review text, it is NOT LGTM.
+ */
+const ISSUE_MARKERS = [
+  /\bHigh\s*(?:severity|—|-|:)/i,
+  /\bMedium\s*(?:severity|—|-|:)/i,
+  /\bLow\s*(?:severity|—|-|:)/i,
+  /-\s*\*\*(High|Medium|Low)/i,
+  /^###?\s*(High|Medium|Low)/im,
+  /\*\*Issues found/i,
+];
+
+/**
+ * Parse the verdict tag from the reviewer's response.
+ * Returns "lgtm" if <verdict>LGTM</verdict>, "issues" if <verdict>ISSUES_FOUND</verdict>,
+ * or null if no verdict tag is present (requires retry).
+ */
+export function parseVerdict(text: string): "lgtm" | "issues" | null {
+  const match = text.match(/<verdict>\s*(LGTM|ISSUES_FOUND)\s*<\/verdict>/i);
+  if (!match) return null;
+  return match[1].toUpperCase() === "LGTM" ? "lgtm" : "issues";
+}
+
+/**
+ * Strip the verdict tag from the cleaned review text.
+ * The verdict is metadata; the user shouldn't see it in the rendered message.
+ */
+export function stripVerdict(text: string): string {
+  return text.replace(/<verdict>\s*(LGTM|ISSUES_FOUND)\s*<\/verdict>/gi, "").trim();
+}
+
+/**
+ * Check if cleaned review text indicates LGTM (no issues).
+ * Prefer parseVerdict() for explicit verdict tags; this is a fallback heuristic.
+ */
+export function isLgtmResult(cleanedText: string): boolean {
+  const text = cleanedText.trim();
+  if (!text) return true;
+
+  // Any severity marker = issues were found, regardless of LGTM mention
+  for (const marker of ISSUE_MARKERS) {
+    if (marker.test(text)) return false;
+  }
+
+  // Explicit LGTM at start of response (after optional "Review:" or "-" prefix)
+  if (/^[-\s]*(?:Review:\s*)?LGTM\b/i.test(text)) return true;
+
+  // No severity markers and no clear LGTM — default to NOT LGTM.
+  // Safer to show the text than silently swallow it.
+  return false;
+}
+
+/** Format a tool call event as a short activity string for the status bar. */
+function formatActivity(name: string, args: any): string {
+  if (name === "read") return `reading ${args?.path ?? "file"}`;
+  if (name === "bash") return `$ ${(args?.command ?? "").slice(0, 50)}`;
+  if (name === "find" || name === "grep" || name === "ls") {
+    return `${name} ${(args?.path ?? args?.pattern ?? "").slice(0, 40)}`;
+  }
+  return `${name}…`;
+}
+
+/**
+ * Spawn a fresh pi reviewer instance with tools, send a prompt,
+ * collect the response. The reviewer can read files and explore
+ * the codebase as needed.
+ */
+export async function runReviewSession(prompt: string, opts: ReviewOptions): Promise<ReviewResult> {
+  const startTime = Date.now();
+  const startedAt = new Date().toISOString();
+  const idPrefix = opts.reviewId ? `[${opts.reviewId}] ` : "";
+  // Use safeStringify (same circular-ref-safe serializer as log()) so rlog matches
+  // log()'s safety contract even for non-string arguments.
+  const rlog = (...args: any[]) => log(idPrefix + args.map(safeStringify).join(" "));
+  rlog(`reviewer: starting (prompt=${(prompt.length / 1000).toFixed(1)}k chars, cwd=${opts.cwd})`);
+
+  let authStorage: ReturnType<typeof AuthStorage.create>;
+  let modelRegistry: ReturnType<typeof ModelRegistry.create>;
+  try {
+    authStorage = AuthStorage.create();
+    modelRegistry = ModelRegistry.create(authStorage);
+  } catch (err: any) {
+    rlog(`reviewer: failed to create auth/model registry: ${err?.message ?? err}`);
+    rlog(`reviewer: stack: ${err?.stack ?? "(no stack)"}`);
+    throw err;
+  }
+
+  let session: Awaited<ReturnType<typeof createAgentSession>>["session"];
+  try {
+    const result = await createAgentSession({
+      cwd: opts.cwd,
+      sessionManager: SessionManager.inMemory(),
+      authStorage,
+      modelRegistry,
+      // Allowlist only read-only tools + bash; no write/edit for the reviewer
+      tools: ["read", "bash", "grep", "find", "ls"],
+    });
+    session = result.session;
+  } catch (err: any) {
+    rlog(`reviewer: createAgentSession failed: ${err?.message ?? err}`);
+    rlog(`reviewer: stack: ${err?.stack ?? "(no stack)"}`);
+    throw err;
+  }
+  rlog(`reviewer: session created, initial model=${session.model?.provider}/${session.model?.id}`);
+
+  // Set the reviewer model if specified
+  const sessionModelName = session.model
+    ? `${session.model.provider}/${session.model.id}`
+    : "unknown";
+  let effectiveModel = opts.model ?? sessionModelName;
+  if (opts.model) {
+    const [provider, modelId] = opts.model.split("/", 2);
+    if (provider && modelId) {
+      const model = modelRegistry.find(provider, modelId);
+      if (model) {
+        try {
+          await session.setModel(model);
+          rlog(`reviewer: using model ${opts.model}`);
+        } catch {
+          const defaultName = session.model
+            ? `${session.model.provider}/${session.model.id}`
+            : "unknown";
+          rlog(`reviewer: model ${opts.model} has no API key. Falling back to ${defaultName}`);
+          effectiveModel = defaultName;
+          opts.onActivity?.(`default model: ${defaultName}`);
+        }
+      } else {
+        const defaultName = session.model
+          ? `${session.model.provider}/${session.model.id}`
+          : "unknown";
+        rlog(`reviewer: model ${opts.model} not found. Falling back to ${defaultName}`);
+        effectiveModel = defaultName;
+        opts.onActivity?.(`default model: ${defaultName}`);
+      }
+    }
+  }
+
+  // Set thinking level (default: off for fast reviews)
+  type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+  const thinkingLevel = (opts.thinkingLevel ?? "off") as ThinkingLevel;
+  session.setThinkingLevel(thinkingLevel);
+  rlog(`reviewer: thinking level = ${thinkingLevel}`);
+
+  let currentText = ""; // always holds the latest assistant message (reset on message_start)
+  let reviewText = ""; // set once after main sendPrompt completes; preserved through retries
+  const toolCalls: ReviewToolCall[] = [];
+
+  const unsub = session.subscribe((ev: AgentSessionEvent) => {
+    // Reset on each new assistant message so we only keep the latest response.
+    // (Agent loop may emit multiple messages within one prompt: reasoning, tool calls, final answer.)
+    if (ev.type === "message_start" && (ev.message as any)?.role === "assistant") {
+      currentText = "";
+    }
+    if (ev.type === "message_update" && ev.assistantMessageEvent.type === "text_delta") {
+      currentText += ev.assistantMessageEvent.delta;
+    }
+
+    // Track + log every tool call the reviewer makes
+    if (ev.type === "tool_execution_start") {
+      const name = ev.toolName;
+      const args = ev.args as any;
+      const call: ReviewToolCall = {
+        name,
+        args,
+        timestamp: new Date().toISOString(),
+      };
+      toolCalls.push(call);
+      const activity = formatActivity(name, args);
+      rlog(`reviewer tool: ${activity}`);
+      opts.onActivity?.(activity);
+      // Emit structured tool call for display widget
+      const targetPath =
+        name === "read"
+          ? (args?.path ?? null)
+          : name === "bash"
+            ? (args?.command ?? null)
+            : (args?.path ?? args?.pattern ?? null);
+      opts.onToolCall?.(name, targetPath);
+    }
+    if (ev.type === "tool_execution_end") {
+      opts.onActivity?.("analyzing…");
+    }
+  });
+
+  // Helper: send a prompt to the existing session, wait for completion.
+  // Respects the outer abort signal and has its own timeout.
+  async function sendPrompt(text: string, timeoutMs: number): Promise<void> {
+    await new Promise<void>((resolve, reject) => {
+      let settled = false;
+      // eslint-disable-next-line prefer-const
+      let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+      const onAbort = () => {
+        if (settled) return;
+        settled = true;
+        if (timeoutId) clearTimeout(timeoutId);
+        // Await session.abort() so the reviewer agent actually stops
+        // before we reject. dispose() alone only disconnects listeners.
+        session.abort().then(
+          () => reject(new Error("Review cancelled")),
+          () => reject(new Error("Review cancelled")),
+        );
+      };
+
+      if (opts.signal.aborted) {
+        onAbort();
+        return;
+      }
+
+      opts.signal.addEventListener("abort", onAbort, { once: true });
+
+      timeoutId = setTimeout(() => {
+        if (settled) return;
+        rlog(`reviewer: timed out after ${timeoutMs / 1000}s`);
+        settled = true;
+        session.abort().then(
+          () => reject(new Error("Review timed out")),
+          () => reject(new Error("Review timed out")),
+        );
+      }, timeoutMs);
+
+      session.prompt(text).then(
+        () => {
+          settled = true;
+          clearTimeout(timeoutId);
+          opts.signal.removeEventListener("abort", onAbort);
+          resolve();
+        },
+        (err) => {
+          settled = true;
+          clearTimeout(timeoutId);
+          opts.signal.removeEventListener("abort", onAbort);
+          reject(err);
+        },
+      );
+    });
+  }
+
+  const MAIN_TIMEOUT_MS = opts.timeoutMs ?? 120 * 1000;
+  const RETRY_TIMEOUT_MS = 20 * 1000;
+  const MAX_VERDICT_RETRIES = 2;
+
+  let verdict: "lgtm" | "issues" | null = null;
+  try {
+    rlog(`reviewer: session.prompt() starting`);
+    try {
+      await sendPrompt(prompt, MAIN_TIMEOUT_MS);
+      rlog(`reviewer: session.prompt() resolved`);
+    } catch (err) {
+      // Preserve any partial text we streamed before the failure so the
+      // structured log still captures it. Re-throw so caller sees the error.
+      reviewText = currentText;
+      throw err;
+    }
+
+    // Snapshot the main review (the final assistant message of the main prompt's agent loop).
+    // Retry prompts will overwrite currentText but reviewText stays fixed on the real findings.
+    reviewText = currentText;
+
+    // Verdict lives in either the main response or a retry response
+    verdict = parseVerdict(currentText);
+    let retries = 0;
+    while (!verdict && retries < MAX_VERDICT_RETRIES) {
+      retries++;
+      rlog(`reviewer: no verdict tag found, retry ${retries}/${MAX_VERDICT_RETRIES}`);
+      opts.onActivity?.(`retry ${retries}: asking for verdict`);
+      const followUp =
+        `Your previous response did not include a verdict tag. ` +
+        `Please respond with ONLY the final verdict on a single line:\n\n` +
+        `<verdict>LGTM</verdict>\n\n` +
+        `if no real bugs were found in your previous analysis, OR:\n\n` +
+        `<verdict>ISSUES_FOUND</verdict>\n\n` +
+        `if you found issues. Do not repeat the review, just output the verdict tag.`;
+      try {
+        await sendPrompt(followUp, RETRY_TIMEOUT_MS);
+      } catch (err: any) {
+        // Propagate cancellation — don't silently swallow user intent
+        if (err?.message === "Review cancelled") throw err;
+        // Other retry failures: keep reviewText (from main prompt) and fall back to default verdict
+        rlog(
+          `reviewer: retry ${retries} failed (${err?.message ?? err}), using current reviewText`,
+        );
+        break;
+      }
+      verdict = parseVerdict(currentText);
+    }
+
+    if (!verdict) {
+      // After all retries, default to ISSUES_FOUND (safer to show findings than swallow them)
+      rlog(`reviewer: no verdict after ${MAX_VERDICT_RETRIES} retries, defaulting to ISSUES_FOUND`);
+      verdict = "issues";
+    }
+  } finally {
+    unsub();
+    session.dispose();
+  }
+
+  const cleanedText = cleanReviewText(reviewText);
+  const isLgtm = verdict === "lgtm";
+  const durationMs = Date.now() - startTime;
+
+  rlog(
+    `reviewer: done in ${(durationMs / 1000).toFixed(1)}s | ` +
+      `prompt=${(prompt.length / 1000).toFixed(1)}k | ` +
+      `raw=${reviewText.length}c | ` +
+      `cleaned=${cleanedText.length}c | ` +
+      `tools=${toolCalls.length} | ` +
+      `lgtm=${isLgtm}`,
+  );
+  rlog(`reviewer raw response:\n${reviewText}`);
+
+  // Structured review record
+  const reviewPath = logReview({
+    timestamp: startedAt,
+    reviewId: opts.reviewId,
+    durationMs,
+    model: effectiveModel,
+    thinkingLevel,
+    isLgtm,
+    promptLength: prompt.length,
+    rawText: reviewText,
+    cleanedText,
+    filesReviewed: opts.filesReviewed ?? [],
+    toolCalls,
+  });
+  if (reviewPath) rlog(`reviewer: wrote structured record ${reviewPath}`);
+
+  return {
+    text: cleanedText,
+    rawText: reviewText,
+    isLgtm,
+    durationMs,
+    toolCalls,
+    model: effectiveModel,
+    thinkingLevel,
+  };
+}

package/scaffold.ts

@@ -0,0 +1,120 @@
+/**
+ * scaffold.ts — Template content for /scaffold-review-files
+ *
+ * Contains the actual default prompts used by the extension so users
+ * can see and customise exactly what the reviewer sees.
+ *
+ * The default review rules live in default-review-rules.md (plain markdown,
+ * no code). scaffold.ts reads that file at import time so the content is
+ * available as SCAFFOLD_REVIEW_RULES for copying into the user's config dir.
+ */
+
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { DEFAULT_AUTO_REVIEW_RULES } from "./prompt";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// ── auto-review.md ───────────────────────────────────
+// The review criteria: what to look for and what to skip.
+// This is the ONLY part of the review prompt that users override directly.
+// The surrounding prompt (tools, budget, workflow, response format) is always
+// included automatically and cannot be changed.
+
+export const SCAFFOLD_AUTO_REVIEW = `${DEFAULT_AUTO_REVIEW_RULES}
+`;
+
+// ── review-rules.md ──────────────────────────────────
+// Loaded from default-review-rules.md — pure review criteria, no operational instructions.
+// The markdown file is the single source of truth; scaffold copies it to the user's config dir.
+
+let _scaffoldReviewRules: string;
+try {
+  _scaffoldReviewRules = readFileSync(join(__dirname, "default-review-rules.md"), "utf8");
+} catch (err: any) {
+  console.error(
+    `[hard-no] Failed to read default-review-rules.md: ${err?.message ?? err}. ` +
+      `Scaffold will create an empty review-rules.md. ` +
+      `Expected at: ${join(__dirname, "default-review-rules.md")}`,
+  );
+  _scaffoldReviewRules = "";
+}
+export const SCAFFOLD_REVIEW_RULES: string = _scaffoldReviewRules;
+
+// ── architect.md ─────────────────────────────────────
+
+export const SCAFFOLD_ARCHITECT_RULES = `## Architecture
+
+- Verify the module dependency graph has no unexpected cycles
+- Check that layering is respected (e.g. UI → Service → Repository → Database)
+- Flag any god-objects or god-modules that accumulated too many responsibilities
+
+## Cross-cutting concerns
+
+- Error handling strategy consistent across all modules
+- Logging follows the same patterns everywhere
+- Configuration accessed the same way in all files
+
+## Technical debt
+
+- Flag any TODO/FIXME/HACK comments that were added
+- Identify code that was clearly written in haste during fix loops
+- Check for dead code or unused imports that accumulated
+
+## Documentation
+
+- README still accurate after all changes
+- Architecture docs reflect current state
+- Changed public APIs have updated JSDoc/comments
+`;
+
+// ── ignore ───────────────────────────────────────────
+
+export const SCAFFOLD_IGNORE = `# Files to skip during review (gitignore syntax)
+# Blank lines and lines starting with # are ignored.
+# Patterns follow .gitignore rules: *, **, ?, !, trailing /
+
+# Dependencies & lock files
+package-lock.json
+yarn.lock
+pnpm-lock.yaml
+bun.lockb
+
+# Build output
+dist/**
+build/**
+out/**
+*.min.js
+*.min.css
+
+# Generated files
+*.generated.ts
+*.d.ts
+
+# Snapshots
+*.snap
+
+# Large data / assets
+*.csv
+*.parquet
+`;
+
+// ── settings.json ────────────────────────────────────
+
+export const SCAFFOLD_SETTINGS = JSON.stringify(
+  {
+    maxReviewLoops: 100,
+    model: "amazon-bedrock/us.anthropic.claude-opus-4-6-v1",
+    thinkingLevel: "off",
+    architectEnabled: true,
+    reviewTimeoutMs: 120000,
+    toggleShortcut: "alt+r",
+    cancelShortcut: "",
+    judgeEnabled: false,
+    judgeModel: "amazon-bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0",
+    judgeTimeoutMs: 10000,
+  },
+  null,
+  2,
+);

package/session-kind.ts

@@ -0,0 +1,139 @@
+/**
+ * session-kind.ts — detect whether pi-hard-no is loaded into the *main* agent
+ * session or into a spawned *sub-session* (e.g. the reviewer session created
+ * by `runReviewSession` in reviewer.ts).
+ *
+ * WHY THIS EXISTS
+ * ───────────────
+ * pi's extension loader calls our factory fresh for every session it creates.
+ * `reviewer.ts` calls `createAgentSession({...})` to spawn a separate reviewer
+ * pi instance; that triggers `DefaultResourceLoader.reload()` which calls
+ * `loadExtensions()` which calls our factory again with a new `pi`. So
+ * pi-hard-no is loaded twice per review: once in the main session, once inside
+ * each reviewer session.
+ *
+ * Without a guard, the reviewer-instance's `agent_end` handler fires when
+ * the reviewer's one-shot prompt finishes, tries to recursively review that
+ * session, then crashes with "ctx is stale after session replacement or
+ * reload" when `reviewer.ts:391 finally { session.dispose() }` invalidates
+ * the reviewer's runtime. Beyond the error, that recursion would double-review
+ * every turn — a real functional bug, not just noise.
+ *
+ * DETECTION
+ * ─────────
+ * `reviewer.ts` creates the reviewer session with a restricted tool set
+ * (`["read", "bash", "grep", "find", "ls"]`, no `write` / `edit`). pi's SDK
+ * passes this through as `allowedToolNames` which filters
+ * `AgentSession._toolDefinitions`, so `pi.getAllTools()` on the reviewer
+ * session returns those 5 tools and nothing else. The main interactive
+ * session always has `write` and `edit` available.
+ *
+ * "No write AND no edit" → definitely not a session we want to auto-review
+ * for. This is a stable invariant: a session without write/edit cannot be
+ * producing file changes that warrant review. Safe to no-op there.
+ *
+ * TIMING
+ * ──────
+ * `runtime.getAllTools` is bound during the `AgentSession` constructor,
+ * which runs AFTER the extension factory. So we cannot detect at activation
+ * time — we detect lazily on the first call and cache the result per-`pi`.
+ *
+ * FAIL-SAFE
+ * ─────────
+ * If the probe itself throws (runtime not yet bound, or ctx already stale
+ * at the instant we check), we default to `false` (main session) so the
+ * normal path still runs. Worst case is one extra stale-ctx log line — no
+ * worse than pre-fix behavior, and much rarer.
+ *
+ * TESTING
+ * ───────
+ * Pure TS. `pi` is passed as a parameter so tests can inject mocks without
+ * spinning up a real session. Cache is per-`pi` via `WeakMap` so tests
+ * using distinct mock objects stay isolated without an explicit reset.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+import { log } from "./logger";
+
+/**
+ * Per-`pi` cache. The first successful probe is remembered for the life of
+ * that extension instance. WeakMap so GC'd pi instances (e.g. disposed
+ * reviewer sessions) don't leak.
+ */
+const cache = new WeakMap<object, boolean>();
+
+/**
+ * Tool names whose presence marks a session as "main" (capable of producing
+ * file changes we want to auto-review). If ALL of these are missing, the
+ * session is treated as a spawned sub-session and pi-hard-no no-ops.
+ */
+const MAIN_SESSION_WRITE_TOOLS = ["write", "edit"] as const;
+
+/**
+ * Returns `true` if the current pi-hard-no instance is running inside a
+ * spawned sub-session (e.g. a reviewer session) rather than the main agent
+ * session.
+ *
+ * Callers should short-circuit work (e.g. skip triggering reviews, skip
+ * updating status bar) when this returns `true`.
+ *
+ * Idempotent and cheap after the first call.
+ */
+export function isSpawnedSubSession(pi: ExtensionAPI): boolean {
+  const cached = cache.get(pi);
+  if (cached !== undefined) return cached;
+
+  const result = probeIsSpawned(pi);
+  cache.set(pi, result);
+  return result;
+}
+
+/**
+ * One-shot probe — separated so the cache-management wrapper above stays
+ * trivially readable. Never throws; failures collapse to `false`.
+ */
+function probeIsSpawned(pi: ExtensionAPI): boolean {
+  try {
+    // Explicit fail-safe: if `pi.getAllTools` isn't a function, the runtime
+    // isn't bound yet (shouldn't happen in practice once events fire) or the
+    // mock/environment is malformed. Defaulting to "main session" keeps the
+    // main path alive; treating this as "empty tool list = spawned" would
+    // wrongly no-op the real main session on an early call.
+    if (typeof pi.getAllTools !== "function") {
+      log(
+        `session-kind: pi.getAllTools unavailable — defaulting to main session (no-op guard disabled for this instance)`,
+      );
+      return false;
+    }
+    const raw = pi.getAllTools();
+    if (!Array.isArray(raw)) {
+      log(
+        `session-kind: pi.getAllTools() returned non-array (${typeof raw}) — defaulting to main session (no-op guard disabled for this instance)`,
+      );
+      return false;
+    }
+    const tools = raw;
+    const names = new Set(
+      tools
+        .map((t) => (t as { name?: unknown })?.name)
+        .filter((n): n is string => typeof n === "string"),
+    );
+    const hasAnyWriteTool = MAIN_SESSION_WRITE_TOOLS.some((t) => names.has(t));
+    const isSpawned = !hasAnyWriteTool;
+    if (isSpawned) {
+      log(
+        `session-kind: spawned sub-session detected (tools=[${[...names].join(",")}]) — pi-hard-no hooks will no-op for this instance`,
+      );
+    }
+    return isSpawned;
+  } catch (err: any) {
+    // Probe failing means runtime/ctx isn't healthy right now. Defaulting
+    // to "main session" keeps the normal path alive; the worst that can
+    // happen is one stale-ctx log line later, which is the pre-fix baseline.
+    log(
+      `session-kind: probe failed (${err?.message ?? err}) — defaulting to main session (no-op guard disabled for this instance)`,
+    );
+    return false;
+  }
+}