pi-gortex 0.1.0 → 0.3.0

package/README.md

@@ -66,6 +66,7 @@ environment -> `<cwd>/.pi/gortex.json` -> `<agent dir>/extensions/gortex.json`
 | `hook_mode`    | `GORTEX_HOOK_MODE` | `deny`             | Posture: `deny`, `enrich`, `consult-unlock`, `nudge`. |
 | `enforce`      | `GORTEX_ENFORCE`   | `true`             | `false` keeps the graph tools and the briefing, and wires no enforcement. |
 | `tools_preset` | `GORTEX_TOOLS`     | `core`             | Eager MCP surface. `core`/`full` use the daemon's default; `edit`/`nav`/`readonly` narrow it. |
+| `native_mcp`   | `GORTEX_NATIVE_MCP` | `true`            | On Pi 0.99+, register `gortex mcp` with Pi's built-in MCP. `false` keeps the extension's own client. |
 
 ```json
 {
@@ -75,6 +76,17 @@ environment -> `<cwd>/.pi/gortex.json` -> `<agent dir>/extensions/gortex.json`
 }
 ```
 
+The extension reads its configuration when Pi loads it, so a change takes
+effect after `/reload`.
+
+**Pi's own `mcp.json` wins.** With `native_mcp` on, the extension registers a
+server named `gortex`. A `gortex` entry in `~/.pi/agent/mcp.json` or
+`.pi/mcp.json` replaces it, including its exposure, and Pi's default exposure
+there is `codemode`, which keeps the tools out of the model's tool list. Leave
+Gortex out of `mcp.json`, or set `"exposure": "direct"` on that entry. A
+Gortex server configured under another name runs as a second connection, and
+read discipline treats its tools as non-graph calls.
+
 **If the graph tools go missing**, the first turn of the session says so and
 names `/reload` as the retry. The bridge fails open, always: an absent binary or
 a daemon that is down costs the session its graph tools, never the session.
@@ -88,7 +100,8 @@ npm run typecheck
 npm run check    # both
 ```
 
-Zero runtime dependencies. Pi's types are imported as types only and erased, so
+Zero runtime dependencies. Pi's extension loader resolves Pi's own packages to
+the running Pi, so they are imported freely and kept in `devDependencies`, and
 the package also loads as a bare directory extension with no `node_modules`
 beside it.
 

package/docs/architecture.md

@@ -4,20 +4,55 @@ How the bridge is built, and why each piece is shaped the way it is.
 
 ## The problem
 
-Pi has no MCP support, by design; its extension API covers the ground MCP would.
 Gortex speaks MCP and owns a hook protocol that every agent it integrates with
-shares. This extension is the adapter between the two, and it does two separate
-jobs over two separate channels.
-
-## Channel 1: graph tools over an MCP stdio bridge
+shares. Pi 0.99 added built-in MCP support; earlier Pi has none. This extension
+is the adapter between the two, and it does two separate jobs over two separate
+channels.
+
+## Channel 1 on Pi 0.99+: Pi's built-in MCP
+
+On a Pi that offers `pi.registerMcpServer()`, the extension registers
+`gortex mcp` as a stdio server named `gortex` and leaves the tool channel to Pi.
+Pi spawns and connects the server, registers its tools as `mcp__gortex__<tool>`,
+follows `tools/list_changed`, renders the calls and stops the child on reload
+and quit. `gortex mcp` starts the shared daemon itself, so the extension starts
+nothing.
+
+- **Exposure.** The server is registered with `direct` exposure, so its tools
+  are declared to the model like built-in tools and Pi holds the first prompt
+  until the server connects. Pi's default, codemode, would hand scripts the
+  compact text results to parse.
+- **Timeout.** The per-request timeout matches the tool-call cap of the
+  extension's own client. Pi's default is a minute, short for some analyzers.
+- **Wire format.** Pi's client identifies itself as `pi` and declares no
+  capabilities the extension can extend. The daemon picks the compact format
+  from that client name.
+- **Readiness.** Pi reports neither a connection nor a failure to extensions. The
+  first turn waits briefly beyond Pi's own wait for an `mcp__gortex__` tool to
+  appear, and a binary that does not resolve is caught before registering,
+  because it would otherwise read as a server still connecting.
+- **Version skew.** Pi keeps the handshake to itself, so the daemon version is
+  read from the readiness line of the session briefing and checked against the
+  same floor.
+- **Precedence.** A `gortex` entry in Pi's own `mcp.json` replaces the
+  extension's registration, exposure included.
+
+The extension keeps its own client below when Pi lacks `registerMcpServer`, when
+the binary does not resolve (its spawn failure is what reaches the model), when
+Pi refuses the registration (the user is warned with Pi's reason), and when
+`native_mcp` is off. It also switches to it on session start when no loaded
+extension connects MCP servers, as with `--no-mcp`: it withdraws the
+registration then. Pi's MCP extension and the extensions that replace it
+register the `/mcp` command, which is what the check looks for.
+
+## Channel 1 on older Pi: the extension's own MCP client
 
 One Gortex MCP child process per session, spoken to over newline-delimited
 JSON-RPC on stdio. Every tool the daemon offers becomes a native Pi tool whose
 implementation forwards the call down that channel.
 
-- **Handshake.** The client identifies itself as Pi and advertises which compact
-  wire formats it can decode, so list-shaped results arrive compact without the
-  daemon needing a per-client allowlist entry. One retry after a short backoff
+- **Handshake.** The client identifies itself as Pi, which is the name the
+  daemon picks the compact wire format from. One retry after a short backoff
   absorbs a daemon that is still warming up.
 - **Version skew.** The handshake reply carries `serverInfo.version` and the
   protocol the daemon settled on. A daemon below the supported floor, or one
@@ -64,6 +99,11 @@ own way, while Gortex's classifier switches on canonical tool names and input
 keys. That translation lives on this side of the bridge, so the Go side keeps
 one vocabulary for every agent it serves.
 
+A call to a Gortex tool is flagged as a graph call and sent under the daemon's
+own tool name, which is what the postures key off. It skips the translation, so
+Gortex's `read` never passes for Pi's. On Pi's built-in MCP the same hook also
+sees each tool a codemode script calls.
+
 Postures are resolved by Gortex. Keeping that decision there is what keeps the
 behaviour identical across hosts.
 
@@ -98,9 +138,13 @@ matter:
 If the cap expires first, that turn is told the tools may not be callable yet
 and pointed at a reload. Exactly one turn reports it.
 
+On Pi's built-in MCP the session hook registers nothing, and the turn waits for
+the server's tools instead (see Channel 1 on Pi 0.99+).
+
 ## Session state
 
-The live bridge, the last bridge error and the registered tool names live at
+This applies to the extension's own client; on Pi's built-in MCP, Pi owns the
+child. The live bridge, the last bridge error and the registered tool names live at
 module scope, and that is load bearing. A reload re-imports the module, so the
 state resets with it. A new session, a resume and a fork re-invoke the extension
 factory against the cached module, and the new invocation stops the previous
@@ -110,6 +154,12 @@ invocation that overlaps it stops that bridge instead of leaving the child
 behind. State held per instance would leak a Gortex child on every new
 session.
 
+Process exit has no next invocation, so the extension also stops the bridge
+from Pi's `session_shutdown` event, which fires on quit and on every
+replacement path. The child is spawned unref'd, pipes included: they must
+never be what holds the host's event loop open, or a print or JSON run that
+finished its work hangs at exit instead of draining.
+
 ## Failure posture
 
 Fail open, everywhere. A missing binary, a daemon that is down, a handshake that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gortex",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Gortex for Pi: high-performance code-intelligence engine for AI agents, based on graph. Exposes only the information the agent needs, cutting token usage up to 50x. 100% local.",
   "keywords": [
     "pi-package",
@@ -35,8 +35,10 @@
     "prepublishOnly": "npm run check"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "~0.85.1",
-    "@types/node": "^26.6.2",
+    "@earendil-works/pi-coding-agent": "~1.0.2",
+    "@earendil-works/pi-tui": "^1.0.2",
+    "@types/node": "^24.19.1",
+    "jiti": "^2.7.0",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {

package/src/config.ts

@@ -19,6 +19,8 @@ export interface SidecarConfig {
   enforce?: boolean;
   /** Eager MCP tool preset: core | full | edit | nav | readonly. */
   tools_preset?: string;
+  /** false keeps the extension's own MCP client on a Pi that has built-in MCP. */
+  native_mcp?: boolean;
 }
 
 /** Everything the extension needs to run, fully resolved. */
@@ -31,6 +33,8 @@ export interface GortexConfig {
   enforce: boolean;
   /** Eager tool preset; the daemon's default applies when this is core/full. */
   toolsPreset: string;
+  /** Whether to hand the tool channel to Pi's built-in MCP when Pi has one. */
+  nativeMcp: boolean;
 }
 
 /** Seams for tests; every one defaults to the real environment. */
@@ -154,5 +158,11 @@ export function resolveConfig(opts: ResolveConfigOptions = {}): GortexConfig {
   const toolsPreset =
     firstString(env.GORTEX_TOOLS, project?.tools_preset, global?.tools_preset) ?? DEFAULT_TOOLS_PRESET;
 
-  return { bin, hookArgv, enforce, toolsPreset };
+  const nativeMcp =
+    parseBoolean(env.GORTEX_NATIVE_MCP) ??
+    (typeof project?.native_mcp === "boolean" ? project.native_mcp : undefined) ??
+    (typeof global?.native_mcp === "boolean" ? global.native_mcp : undefined) ??
+    true;
+
+  return { bin, hookArgv, enforce, toolsPreset, nativeMcp };
 }

package/src/index.ts

@@ -20,6 +20,18 @@ import {
   ensureDaemon,
   isBelowVersion,
 } from "./mcp-client.ts";
+import {
+  NATIVE_READY_WAIT_MS,
+  bareToolName,
+  binaryResolves,
+  daemonVersionFromBriefing,
+  isNativeGortexTool,
+  mcpConnectorLoaded,
+  registerNativeServer,
+  unregisterNativeServer,
+  supportsNativeMcp,
+  waitForNativeTools,
+} from "./native.ts";
 import { nodeProcessDeps } from "./runtime.ts";
 import type { ProcessDeps } from "./runtime.ts";
 import {
@@ -82,12 +94,18 @@ function reportVersionSkew(
         `run \`gortex upgrade\`.`,
   );
 
-  // A Pi build without a UI (print/JSON mode) or without notify must not take
-  // the session down over an advisory message.
+  notifyUser(ctx, user);
+}
+
+/**
+ * A warning for the user only. A Pi build without a UI (print/JSON mode) or
+ * without notify must not take the session down over an advisory message.
+ */
+function notifyUser(ctx: ExtensionContext | undefined, message: string): void {
   try {
-    if (ctx?.hasUI) ctx.ui.notify(user, "warning");
+    if (ctx?.hasUI) ctx.ui.notify(message, "warning");
   } catch {
-    // the model still gets the orientation line above
+    // advisory only
   }
 }
 
@@ -99,6 +117,8 @@ export interface GortexExtensionOptions {
   deps?: ProcessDeps;
   /** Readiness cap override. */
   readyWaitMs?: number;
+  /** Override for the wait on Pi's built-in MCP connecting the gortex server. */
+  nativeReadyWaitMs?: number;
 }
 
 export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensionOptions = {}): void {
@@ -109,6 +129,18 @@ export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensi
   const piCwd = (): string => (pi as { cwd?: string })?.cwd ?? process.cwd();
   const deps = options.deps ?? nodeProcessDeps;
   const readyWaitMs = options.readyWaitMs ?? READY_WAIT_MS;
+  const nativeReadyWaitMs = options.nativeReadyWaitMs ?? NATIVE_READY_WAIT_MS;
+
+  // On a Pi with built-in MCP, Pi owns the tool channel: it spawns `gortex mcp`
+  // (which starts the daemon itself), registers the tools and renders them.
+  // A binary that does not resolve, or a registration Pi refuses, falls back to
+  // the extension's own client, which reports its failure to the model.
+  let nativeRefusal = "";
+  let native = ((): boolean => {
+    if (!config.nativeMcp || !supportsNativeMcp(pi) || !binaryResolves(config.bin)) return false;
+    nativeRefusal = registerNativeServer(pi, config);
+    return nativeRefusal === "";
+  })();
 
   // Latched for the whole session once the first turn has run the
   // session_start hook, whether or not it produced anything to inject.
@@ -178,17 +210,29 @@ export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensi
     }
   });
 
-  // startSession holds the body of session_start so the readiness promise
-  // above settles on every exit path, early returns included.
-  async function startSession(ctx?: ExtensionContext): Promise<void> {
-    ensureDaemon(config.bin, deps);
-    gortexToolNames.clear();
+  // Stops the live bridge, if any, and clears the slot. Shared by
+  // session_start and session_shutdown so both paths stay in sync.
+  function stopBridge(): void {
     clearSyncTimer();
     const previous = getClient();
     if (previous) {
       previous.stop();
       setClient(null);
     }
+  }
+
+  // startSession holds the body of session_start so the readiness promise
+  // above settles on every exit path, early returns included.
+  async function startSession(ctx?: ExtensionContext): Promise<void> {
+    if (native && !mcpConnectorLoaded(pi)) {
+      unregisterNativeServer(pi);
+      native = false;
+    }
+    if (native) return;
+    if (nativeRefusal) notifyUser(ctx, `Pi refused the gortex MCP server (${nativeRefusal}), so the extension runs its own client.`);
+    ensureDaemon(config.bin, deps);
+    gortexToolNames.clear();
+    stopBridge();
     const c = new MCPStdioClient({ bin: config.bin, toolsPreset: config.toolsPreset, deps });
     // Claim the slot before the first await: an overlapping
     // session_start (rapid /new or /reload) then sees and stops THIS
@@ -216,16 +260,22 @@ export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensi
 
   // Fires before the agent loop's first LLM call. It can't mutate messages
   // itself, so it just parks the orientation for the `context` hook.
-  pi.on("before_agent_start", async () => {
+  pi.on("before_agent_start", async (_event, ctx) => {
     if (startupHookRan) return;
     startupHookRan = true; // before the first await, so a second turn can't race in
     // Pi awaits each listener, so this holds the turn until the tools are
     // registered and bridgeError reflects the handshake (or the cap expires).
-    const ready = await waitForSession(readyWaitMs);
+    // session_start settles `native` first: it falls back when nothing connects MCP.
+    const sessionDone = await waitForSession(readyWaitMs);
+    const ready = native ? await waitForNativeTools(pi, nativeReadyWaitMs) : sessionDone;
     const decision = callHook(config.hookArgv, deps, {
       event: "session_start",
-      cwd: piCwd(),
+      cwd: ctx?.cwd ?? piCwd(),
     });
+    // Pi's MCP keeps the handshake to itself, so the version comes from the briefing.
+    if (native && decision.orientation) {
+      reportVersionSkew(ctx, daemonVersionFromBriefing(decision.orientation), "");
+    }
     const parts: string[] = [];
     const bridgeError = getBridgeError();
     if (bridgeError) {
@@ -276,15 +326,23 @@ export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensi
     return;
   });
 
+  // Never let the bridge child outlive the session.
+  pi.on("session_shutdown", async () => {
+    stopBridge();
+  });
+
   if (!config.enforce) return;
 
   // Enforcement: every non-Gortex tool call is checked against the Go hook.
   pi.on("tool_call", async (event: ToolCallEvent, ctx: ExtensionContext): Promise<ToolCallEventResult | void> => {
     const piName: string = (event as { toolName?: string })?.toolName ?? "";
     const piInput: Record<string, unknown> = (event?.input as Record<string, unknown>) ?? {};
-    const isGortexTool = gortexToolNames.has(piName);
+    const isGortexTool = native ? isNativeGortexTool(piName) : gortexToolNames.has(piName);
 
-    const norm = normalizeToolCall(piName, piInput);
+    // A graph tool keeps its own name: Gortex's `read` is no Pi `read`.
+    const norm = isGortexTool
+      ? { tool_name: bareToolName(piName), tool_input: piInput }
+      : normalizeToolCall(piName, piInput);
     const decision = callHook(config.hookArgv, deps, {
       event: "tool_call",
       tool_name: norm.tool_name,

package/src/mcp-client.ts

@@ -53,6 +53,24 @@ export function isBelowVersion(actual: string, floor: string): boolean {
 // session. Fail open to the daemon's default surface instead.
 const FORWARDED_PRESETS = new Set(["edit", "nav", "readonly"]);
 
+/**
+ * The variables `gortex mcp` needs on top of `env` to serve `toolsPreset`.
+ * The daemon's own default surface already IS core/defer; only a recognised
+ * non-default preset needs the proxy-side narrowing.
+ */
+export function presetEnv(
+  toolsPreset: string,
+  env: Record<string, string | undefined>,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  const preset = toolsPreset.trim().toLowerCase();
+  const tools = env.GORTEX_TOOLS || (FORWARDED_PRESETS.has(preset) ? preset : "");
+  if (tools && !env.GORTEX_TOOLS) out.GORTEX_TOOLS = tools;
+  // Never let a preset hide-block tools promoted later by tools_search.
+  if (tools && !env.GORTEX_TOOLS_MODE) out.GORTEX_TOOLS_MODE = "defer";
+  return out;
+}
+
 export interface MCPStdioClientOptions {
   bin: string;
   toolsPreset: string;
@@ -137,16 +155,7 @@ export class MCPStdioClient {
   }
 
   private childEnv(): Record<string, string | undefined> {
-    const env: Record<string, string | undefined> = { ...this.env };
-    const preset = this.toolsPreset.trim().toLowerCase();
-    // The daemon's own default surface already IS core/defer; only a
-    // recognised non-default preset needs the proxy-side narrowing.
-    if (!env.GORTEX_TOOLS && FORWARDED_PRESETS.has(preset)) {
-      env.GORTEX_TOOLS = preset;
-    }
-    // Never let a preset hide-block tools promoted later by tools_search.
-    if (env.GORTEX_TOOLS && !env.GORTEX_TOOLS_MODE) env.GORTEX_TOOLS_MODE = "defer";
-    return env;
+    return { ...this.env, ...presetEnv(this.toolsPreset, this.env) };
   }
 
   private spawnChild(): void {
@@ -165,6 +174,11 @@ export class MCPStdioClient {
     child.stdin?.on("error", () => {}); // EPIPE race: child may exit before stdin.write() finishes
     child.on("error", () => this.markExited(new Error("gortex mcp spawn failed")));
     child.on("exit", () => this.markExited(new Error("gortex mcp exited")));
+    // The child and its pipes must never keep the event loop alive.
+    child.unref?.();
+    child.stdin?.unref?.();
+    child.stdout?.unref?.();
+    child.stderr?.unref?.();
   }
 
   private markExited(err: Error): void {

package/src/native.ts

@@ -0,0 +1,141 @@
+// The tool channel on Pi's built-in MCP (Pi >= 0.99): the extension registers
+// `gortex mcp` with pi.registerMcpServer() and Pi owns the connection, the tool
+// registry and the rendering. See docs/architecture.md.
+
+import { accessSync, constants, statSync } from "node:fs";
+import { delimiter, join } from "node:path";
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import type { GortexConfig } from "./config.ts";
+import { CALL_TIMEOUT_MS, presetEnv } from "./mcp-client.ts";
+
+export const MCP_SERVER_NAME = "gortex";
+/** Pi names a server's tools `mcp__<server>__<tool>`. */
+export const MCP_TOOL_PREFIX = `mcp__${MCP_SERVER_NAME}__`;
+
+const SERVER_DESCRIPTION =
+  "Gortex code graph of the indexed repositories: symbol search, source reads, usages, " +
+  "call chains, change impact and graph-aware edits.";
+
+// Pi 0.87 declares none of the MCP members, so they are read structurally.
+type NativeMcpApi = Pick<ExtensionAPI, "registerMcpServer" | "unregisterMcpServer" | "getAllTools" | "getCommands">;
+
+export function supportsNativeMcp(pi: ExtensionAPI): boolean {
+  return typeof (pi as Partial<NativeMcpApi>).registerMcpServer === "function";
+}
+
+export function nativeServerConfig(
+  config: GortexConfig,
+  env: Record<string, string | undefined> = process.env,
+): Parameters<ExtensionAPI["registerMcpServer"]>[1] {
+  return {
+    command: config.bin,
+    args: ["mcp"],
+    env: presetEnv(config.toolsPreset, env),
+    // Declared to the model like built-in tools, and the first prompt waits
+    // for the connection. Codemode would hand scripts gcx text to parse.
+    exposure: "direct",
+    timeout: CALL_TIMEOUT_MS / 1000,
+    description: SERVER_DESCRIPTION,
+  };
+}
+
+/** Registers the server; returns why it failed, or "" on success. */
+export function registerNativeServer(pi: ExtensionAPI, config: GortexConfig): string {
+  try {
+    (pi as NativeMcpApi).registerMcpServer(MCP_SERVER_NAME, nativeServerConfig(config));
+    return "";
+  } catch (err) {
+    return err instanceof Error ? err.message : String(err);
+  }
+}
+
+/**
+ * Whether `bin` names an executable file, directly or through PATH. Pi reports
+ * no connection failure to extensions, so a server that cannot spawn would
+ * read as one still connecting.
+ */
+export function binaryResolves(bin: string, env: Record<string, string | undefined> = process.env): boolean {
+  const exts = process.platform === "win32" ? ["", ...(env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";")] : [""];
+  const candidates = /[\\/]/.test(bin)
+    ? [bin]
+    : (env.PATH ?? "").split(delimiter).filter(Boolean).map((dir) => join(dir, bin));
+  return candidates.some((path) =>
+    exts.some((ext) => {
+      try {
+        accessSync(path + ext, constants.X_OK);
+        return statSync(path + ext).isFile();
+      } catch {
+        return false;
+      }
+    }),
+  );
+}
+
+/**
+ * The daemon version the session_start briefing reports, or "" when it names
+ * none. The briefing is the only place it reaches the extension on Pi's MCP.
+ */
+export function daemonVersionFromBriefing(briefing: string): string {
+  return /Gortex daemon [^(\n]*\(v(\d[^,\s)]*)/.exec(briefing)?.[1] ?? "";
+}
+
+/**
+ * Whether an extension that connects MCP servers is loaded. Pi's own MCP
+ * extension and the ones that replace it register `/mcp`; `--no-mcp` and
+ * `-ne` without `builtin:mcp` leave a registration with nothing to connect it.
+ * Read on session_start, once every extension has loaded. A Pi that cannot
+ * list commands is trusted to connect the server.
+ */
+export function mcpConnectorLoaded(pi: ExtensionAPI): boolean {
+  try {
+    return (pi as NativeMcpApi).getCommands().some((command) => command.name === "mcp");
+  } catch {
+    return true;
+  }
+}
+
+/** Withdraws the registration, which also keeps Pi from reporting it as unconnected. */
+export function unregisterNativeServer(pi: ExtensionAPI): void {
+  try {
+    (pi as NativeMcpApi).unregisterMcpServer(MCP_SERVER_NAME);
+  } catch {
+    // already gone, or this instance has been invalidated
+  }
+}
+
+export function isNativeGortexTool(name: string): boolean {
+  return name.startsWith(MCP_TOOL_PREFIX);
+}
+
+/** The daemon's own name for a native tool, as Gortex guidance spells it. */
+export function bareToolName(name: string): string {
+  return isNativeGortexTool(name) ? name.slice(MCP_TOOL_PREFIX.length) : name;
+}
+
+/** True once Pi has registered at least one tool from the gortex server. */
+export function nativeToolsReady(pi: ExtensionAPI): boolean {
+  try {
+    return (pi as NativeMcpApi).getAllTools().some((tool) => isNativeGortexTool(tool.name));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * How long the first turn waits for the gortex tools on top of Pi's own wait.
+ * Pi's MCP extension already holds the first prompt for up to 10s on a direct
+ * server, so this only covers a daemon still warming up after that.
+ */
+export const NATIVE_READY_WAIT_MS = 5_000;
+
+/** Resolves true once the gortex tools are registered, false when `ms` passes first. */
+export async function waitForNativeTools(pi: ExtensionAPI, ms: number, pollMs = 100): Promise<boolean> {
+  const deadline = Date.now() + ms;
+  while (!nativeToolsReady(pi)) {
+    if (Date.now() >= deadline) return false;
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+  }
+  return true;
+}

package/src/render.ts

@@ -0,0 +1,149 @@
+// TUI rendering for bridged tools: a call line read off Gortex's argument
+// shape (operation, target, options), Pi's own read renderer for a file read,
+// and a result collapsed until the user expands it.
+
+import { createReadToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { Theme, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Text, truncateToWidth } from "@earendil-works/pi-tui";
+import type { Component } from "@earendil-works/pi-tui";
+
+import { textFromResult } from "./mcp-client.ts";
+
+type ToolRenderContext = Parameters<NonNullable<ToolDefinition["renderCall"]>>[2];
+
+export type RenderCall = (args: Record<string, unknown>, theme: Theme, context: ToolRenderContext) => Component;
+export type RenderResult = (result: unknown, options: { expanded?: boolean }) => Component;
+
+const OPERATION_ARGS = ["operation", "kind"];
+const SUBJECT_ARGS = ["target", "query", "question", "task", "path"];
+const HIDDEN_ARGS = new Set(["output", "view", "context", "to"]);
+const NESTED_ARGS = new Set(["options", "arguments"]);
+const HIDDEN_OPTIONS = new Set(["new_user_task"]);
+const SCOPE_OPTIONS = ["repo", "project", "path", "scope", "kind", "lang"];
+const MAX_VALUE_CHARS = 60;
+
+/** CallLine renders on one row cut to the terminal width, unlike Text which wraps. */
+class CallLine implements Component {
+  text = "";
+  setText(text: string): void {
+    this.text = text;
+  }
+  invalidate(): void {}
+  render(width: number): string[] {
+    return [truncateToWidth(this.text, width)];
+  }
+}
+
+function isSet(value: unknown): boolean {
+  if (value === undefined || value === null || value === "") return false;
+  if (typeof value === "object" && !Array.isArray(value)) return Object.keys(value).length > 0;
+  return true;
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
+}
+
+/** selector unwraps a target-shaped object ({file}, {symbol}, ...) to the value it selects. */
+function selector(value: unknown): unknown {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+  const entry = Object.values(value).find(isSet);
+  return entry ?? value;
+}
+
+/** lineNumber keeps a positive finite number; Gortex reads 0 as unset. */
+function lineNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;
+}
+
+function formatValue(value: unknown, full: boolean): string {
+  let s: string;
+  if (typeof value === "string") s = value;
+  else if (Array.isArray(value) && value.every((v) => typeof v !== "object")) s = value.join(",");
+  else if (typeof value === "object") s = JSON.stringify(value);
+  else s = String(value);
+  s = s.replace(/\s+/g, " ").trim();
+  return !full && s.length > MAX_VALUE_CHARS ? s.slice(0, MAX_VALUE_CHARS - 1) + "…" : s;
+}
+
+/**
+ * callRenderer renders `<tool> <operation> <subject> to <other> key=value...`.
+ * Scope options come first so they survive the cut to the terminal width;
+ * expanded, the line wraps with every value in full.
+ */
+export function callRenderer(name: string): RenderCall {
+  return (rawArgs, theme, context) => {
+    const args = asRecord(rawArgs);
+    const full = context.expanded;
+    const parts = [theme.fg("toolTitle", theme.bold(name))];
+    const operationKey = OPERATION_ARGS.find((k) => isSet(args[k]));
+    if (operationKey) parts.push(theme.fg("toolTitle", formatValue(args[operationKey], full)));
+    const subjectKey = SUBJECT_ARGS.find((k) => isSet(args[k]));
+    if (subjectKey) parts.push(theme.fg("accent", formatValue(selector(args[subjectKey]), full)));
+    if (isSet(args.to)) parts.push(theme.fg("dim", "to"), theme.fg("accent", formatValue(selector(args.to), full)));
+
+    const pairs: [string, unknown][] = [];
+    for (const [k, v] of Object.entries(args)) {
+      if (HIDDEN_ARGS.has(k) || k === operationKey || k === subjectKey) continue;
+      if (NESTED_ARGS.has(k)) {
+        const nested = Object.entries(asRecord(v)).filter(([nk]) => !HIDDEN_OPTIONS.has(nk));
+        const rank = ([nk]: [string, unknown]) => (SCOPE_OPTIONS.includes(nk) ? 0 : 1);
+        pairs.push(...nested.sort((a, b) => rank(a) - rank(b)));
+      } else {
+        pairs.push([k, v]);
+      }
+    }
+    for (const [k, v] of pairs) {
+      if (isSet(v)) parts.push(theme.fg("dim", `${k}=`) + theme.fg("muted", formatValue(v, full)));
+    }
+
+    const line = full ? new Text("", 0, 0) : new CallLine();
+    line.setText(parts.join(" "));
+    return line;
+  };
+}
+
+/** GortexText marks a line rendered by Pi's own renderer as Gortex's. */
+class GortexText extends Text {
+  theme: Theme | undefined;
+  override setText(text: string): void {
+    super.setText(this.theme ? this.theme.fg("dim", "gortex ") + text : text);
+  }
+}
+
+let piRead: ReturnType<typeof createReadToolDefinition> | undefined;
+
+/**
+ * readCallRenderer hands a file read to Pi's read renderer, so it shows the
+ * same path, line range and skill / docs / resource labels as Pi's own read.
+ * Any other read operation falls through to the generic call line.
+ */
+export function readCallRenderer(name: string): RenderCall {
+  const generic = callRenderer(name);
+  return (rawArgs, theme, context) => {
+    const args = asRecord(rawArgs);
+    const file = asRecord(args.target).file;
+    if (typeof file !== "string" || (args.operation !== undefined && args.operation !== "file")) {
+      return generic(rawArgs, theme, context);
+    }
+    piRead ??= createReadToolDefinition(context.cwd);
+    const text = context.lastComponent instanceof GortexText ? context.lastComponent : new GortexText("", 0, 0);
+    text.theme = theme;
+    const options = asRecord(args.options);
+    const readArgs = {
+      path: file,
+      offset: lineNumber(options.offset),
+      limit: lineNumber(options.limit),
+    };
+    return piRead.renderCall!(readArgs, theme, { ...context, args: readArgs, lastComponent: text });
+  };
+}
+
+export function resultText(result: unknown): string {
+  const structured = (result as { structuredContent?: unknown })?.structuredContent;
+  return textFromResult(result) || JSON.stringify(structured ?? result ?? {});
+}
+
+/** renderResult collapses the result to nothing until the user expands it with ctrl+o. */
+export const renderResult: RenderResult = (result, options) =>
+  new Text(options?.expanded ? resultText(result) : "", 0, 0);

package/src/runtime.ts

@@ -8,11 +8,15 @@ import type { SpawnOptions } from "node:child_process";
 
 export interface ChildStream {
   on(event: string, listener: (chunk: unknown) => void): unknown;
+  /** Drops the event-loop reference; I/O keeps working. */
+  unref?(): unknown;
 }
 
 export interface ChildStdin {
   on(event: string, listener: (err: unknown) => void): unknown;
   write(chunk: string): unknown;
+  /** Drops the event-loop reference; I/O keeps working. */
+  unref?(): unknown;
 }
 
 /** The subset of ChildProcess the MCP bridge and the daemon launcher touch. */

package/src/state.ts

@@ -3,7 +3,9 @@
 // Shared at module level on purpose: a new invocation's session_start stops the
 // previous invocation's bridge child, which works only while both invocations
 // see the same `client`. Move this into the factory closure and every `/new`
-// leaks a `gortex mcp` process.
+// leaks a `gortex mcp` process. Reload is the exception: Pi re-imports the
+// extension with a fresh module graph, so there the old instance's
+// session_shutdown handler is what stops its bridge.
 
 import type { MCPStdioClient } from "./mcp-client.ts";
 

package/src/tools.ts

@@ -1,12 +1,11 @@
 // Tool registration: each tool the bridge lists becomes a native Pi tool whose
 // execute() forwards to tools/call.
 
-import { createRequire } from "node:module";
-
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-import { textFromResult } from "./mcp-client.ts";
 import type { ToolDescriptor } from "./mcp-client.ts";
+import { callRenderer, readCallRenderer, renderResult, resultText } from "./render.ts";
+import type { RenderCall, RenderResult } from "./render.ts";
 import { getClient, gortexToolNames } from "./state.ts";
 import { toolNameMap } from "./hook.ts";
 
@@ -46,7 +45,8 @@ interface BridgeToolDefinition {
   description: string;
   parameters: unknown;
   execute(toolCallId: string, params: Record<string, unknown>): Promise<unknown>;
-  renderResult?: (result: unknown, options: { expanded?: boolean }) => unknown;
+  renderCall: RenderCall;
+  renderResult: RenderResult;
 }
 
 /**
@@ -67,33 +67,11 @@ export function safeRegister(pi: ExtensionAPI, def: BridgeToolDefinition): strin
   return def.name;
 }
 
-// Lazily resolved TUI Text component, used only to collapse a gortex tool's
-// result to nothing until the user expands it (ctrl+o). Resolved through
-// createRequire rather than a static import so a Pi packaging that can't
-// provide @earendil-works/pi-tui degrades to Pi's default renderer instead of
-// throwing at load and taking tool registration down with it.
-type TextComponent = new (text: string, x: number, y: number) => unknown;
-let TuiText: TextComponent | undefined;
-try {
-  const require = createRequire(import.meta.url);
-  TuiText = (require("@earendil-works/pi-tui") as { Text: TextComponent }).Text;
-} catch {
-  TuiText = undefined;
-}
-
-function resultText(result: unknown): string {
-  const structured = (result as { structuredContent?: unknown })?.structuredContent;
-  return textFromResult(result) || JSON.stringify(structured ?? result ?? {});
-}
-
 /**
  * Registers one Gortex tool under its bare daemon name (or its alias).
  * Idempotent: a name already registered is skipped. Adds the name to
  * gortexToolNames so the read-discipline postures treat a call to it as a graph
  * query.
- *
- * renderResult collapses the result to nothing until the user expands it with
- * ctrl+o; Pi's fallback renderCall already shows the tool name.
  */
 export function registerOneTool(pi: ExtensionAPI, desc: ToolDescriptor): void {
   const name = desc.name;
@@ -127,14 +105,9 @@ export function registerOneTool(pi: ExtensionAPI, desc: ToolDescriptor): void {
       if ((result as { isError?: boolean })?.isError) throw new Error(text || `gortex ${name} failed`);
       return { content: [{ type: "text", text }], details: {} };
     },
+    renderCall: (name === "read" ? readCallRenderer : callRenderer)(piAliasName(name)),
+    renderResult,
   };
-  if (TuiText) {
-    const Text = TuiText;
-    def.renderResult = (result: unknown, options: { expanded?: boolean }) => {
-      if (!options?.expanded) return new Text("", 0, 0);
-      return new Text(resultText(result), 0, 0);
-    };
-  }
   gortexToolNames.add(safeRegister(pi, def));
 }