pi-gortex 0.2.0 → 0.4.0

package/README.md

@@ -62,10 +62,11 @@ environment -> `<cwd>/.pi/gortex.json` -> `<agent dir>/extensions/gortex.json`
 
 | Sidecar key    | Environment        | Default            | Meaning |
 |----------------|--------------------|--------------------|---------|
-| `bin`          | `GORTEX_BIN`       | `gortex` on `PATH` | Binary used for `daemon start`, `mcp` and `hook`. |
+| `bin`          | `GORTEX_BIN`       | `gortex` on `PATH` | Binary used for `daemon start`, `mcp` and `hook`. Read from the global sidecar only; a project file cannot set it. |
 | `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.

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
@@ -53,6 +88,21 @@ built-ins Pi may grow later as well as today's collisions. Each aliased tool
 front-loads the rename into its own description, because Gortex's guidance and
 denial messages name the bare tool and the model has to map it.
 
+### Edit diffs
+
+The daemon reports an applied edit without its content, so the bridge reads the
+files a write names before and after the call and stores their diffs in the
+result's `details`, shaped like Pi's own edit details (see `src/diff.ts`). The
+model still reads only Gortex's reply.
+
+On Pi's built-in MCP the reads ride the `tool_call` and `tool_result` events.
+Pi prepares a whole parallel batch before running it, so no lock can span a
+call; a file two calls in flight write gets no diff instead.
+
+A wrong diff is worse than none, so where one could mislead or stall Pi (a
+shell command running alongside, or a change a line diff cannot show cheaply) a
+one-line note stands in for it.
+
 ## Channel 2: read discipline over the hook bridge
 
 Every tool call Pi is about to run is forwarded to Gortex's hook with a
@@ -64,16 +114,24 @@ 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.
 
 ## Orientation injection
 
-The session briefing rides a tail user message appended during context assembly.
-Carrying it in the system prompt would place it at the head of the conversation,
-where a change invalidates prefix prompt caching on every turn. The text is
-computed once per session and cleared only once it has been appended, so a
-context shape the extension cannot append to does not silently drop it.
+The session briefing is stored once in the session history as a hidden message,
+so every LLM call carries it. It stays out of the system prompt, because a
+change there invalidates prefix prompt caching.
+
+## Withdrawn tools
+
+Pi cannot unregister a tool, so one the daemon withdraws leaves Pi's active tool
+set instead.
 
 ## The readiness barrier
 
@@ -98,9 +156,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 +172,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
@@ -124,3 +192,7 @@ Every value resolves at runtime, layered from the environment down through a
 project file and a global one to defaults. See the table in the
 [README](../README.md#configure). Runtime resolution is what lets one artifact
 serve both the npm package and a directory install.
+
+The project file sits in whatever repository Pi was opened in, so it cannot
+set `bin`. Otherwise a cloned repository could choose the executable the
+extension spawns. The binary comes from `GORTEX_BIN`, the global file or `PATH`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gortex",
-  "version": "0.2.0",
+  "version": "0.4.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,9 +35,10 @@
     "prepublishOnly": "npm run check"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "~0.87.0",
-    "@earendil-works/pi-tui": "^0.87.0",
-    "@types/node": "^26.4.1",
+    "@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

@@ -11,7 +11,7 @@ import { join } from "node:path";
 
 /** The sidecar file's on-disk shape. `gortex init` is its writer. */
 export interface SidecarConfig {
-  /** Absolute path to the gortex binary. Default: resolved from PATH. */
+  /** Absolute path to the gortex binary. Global sidecar only. Default: resolved from PATH. */
   bin?: string;
   /** Hook posture: deny | enrich | consult-unlock | nudge. */
   hook_mode?: string;
@@ -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. */
@@ -137,8 +141,9 @@ export function resolveConfig(opts: ResolveConfigOptions = {}): GortexConfig {
 
   const [project, global] = sidecarPaths(cwd, agentDir).map((path) => readSidecar(path, readFile));
 
-  // `gortex` unqualified is resolved by spawn against PATH.
-  const bin = firstString(env.GORTEX_BIN, project?.bin, global?.bin) ?? DEFAULT_BIN;
+  // A checked-out repository must never pick the executable, so the project
+  // sidecar has no say in `bin`. `gortex` unqualified is resolved against PATH.
+  const bin = firstString(env.GORTEX_BIN, global?.bin) ?? DEFAULT_BIN;
 
   const mode = normalizeMode(firstString(env.GORTEX_HOOK_MODE, project?.hook_mode, global?.hook_mode));
   const hookArgv = [bin, "hook", "--agent=pi"];
@@ -154,5 +159,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/diff.ts

@@ -0,0 +1,404 @@
+// Diffs for Gortex's file-writing tools. The daemon reports an applied edit
+// without its content, so the bridge snapshots the files a call names, runs
+// the call, and diffs what changed in Pi's own edit format.
+
+import { existsSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+
+import { generateDiffString, generateUnifiedPatch, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { bareToolName, isNativeGortexTool } from "./native.ts";
+
+export interface FileDiff {
+  /** Relative to the session's cwd. */
+  path: string;
+  /** Empty when `note` explains why the change is not drawn as a diff. */
+  diff: string;
+  patch: string;
+  firstChangedLine?: number;
+  note?: string;
+}
+
+/**
+ * A result's details: every changed file under `diffs`, plus Pi's EditToolDetails
+ * fields at the top level. `patch` covers every file; `diff` and
+ * `firstChangedLine` are set when exactly one file changed.
+ */
+export interface EditDetails {
+  diffs?: FileDiff[];
+  diff?: string;
+  patch?: string;
+  firstChangedLine?: number;
+}
+
+const MAX_FILE_BYTES = 1024 * 1024;
+// Pi's line diff costs about (lines old + new) x (changed lines) and runs on
+// the event loop; this budget keeps one diff to roughly a tenth of a second.
+const MAX_DIFF_WORK = 2_000_000;
+
+const LEGACY_EDIT_TOOLS = new Set(["edit_file", "write_file", "edit_symbol", "batch_edit"]);
+const EDIT_OPERATIONS = new Set(["file", "symbol", "write", "batch"]);
+// Argument containers the `edit` facade flattens before dispatch.
+const CONTAINERS = ["arguments", "options", "source", "context", "guard", "output"];
+const PATH_KEYS = ["path", "file", "file_path", "source", "destination"];
+const SYMBOL_KEYS = ["id", "symbol", "symbol_id"];
+// Pi's own tools that write the file named by their `path`.
+const PI_WRITE_TOOLS = new Set(["edit", "write"]);
+
+type Snapshot =
+  | { kind: "missing" }
+  | { kind: "text"; raw: Buffer; text: string }
+  /** Not diffable. `reason` is empty when the change should pass silently. */
+  | { kind: "skipped"; reason: string; size: number; mtimeMs: number };
+
+const utf8 = new TextDecoder("utf-8", { fatal: true });
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
+}
+
+/** isFileEdit reports whether a call writes files the bridge can name up front. */
+export function isFileEdit(tool: string, params: Record<string, unknown>): boolean {
+  if (LEGACY_EDIT_TOOLS.has(tool)) return !isDryRun(params);
+  return tool === "edit" && EDIT_OPERATIONS.has(String(params.operation)) && !isDryRun(params);
+}
+
+function isDryRun(params: Record<string, unknown>): boolean {
+  return flatten(params).dry_run === true;
+}
+
+function flatten(params: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const key of CONTAINERS) Object.assign(out, asRecord(params[key]));
+  for (const [key, value] of Object.entries(params)) {
+    if (key === "target" || (CONTAINERS.includes(key) && typeof value === "object")) continue;
+    out[key] = value;
+  }
+  const target = asRecord(params.target);
+  if (typeof target.file === "string") out.path = target.file;
+  if (typeof target.symbol === "string") out.id = target.symbol;
+  return out;
+}
+
+function batchItems(value: unknown): Record<string, unknown>[] {
+  let items = value;
+  if (typeof items === "string") {
+    try {
+      items = JSON.parse(items);
+    } catch {
+      return [];
+    }
+  }
+  return Array.isArray(items) ? items.map(asRecord) : [];
+}
+
+function namedPaths(entry: Record<string, unknown>): string[] {
+  const out: string[] = [];
+  for (const key of PATH_KEYS) {
+    if (typeof entry[key] === "string") out.push(entry[key]);
+  }
+  for (const key of SYMBOL_KEYS) {
+    const id = entry[key];
+    if (typeof id === "string" && id.includes("::")) out.push(id.slice(0, id.indexOf("::")));
+  }
+  return out;
+}
+
+const repoRoots = new Map<string, string>();
+
+/** The nearest directory at or above cwd holding `.git`, else cwd itself. */
+function repoRoot(cwd: string): string {
+  let root = repoRoots.get(cwd);
+  if (root !== undefined) return root;
+  root = cwd;
+  for (let dir = cwd; ; dir = dirname(dir)) {
+    if (existsSync(join(dir, ".git"))) {
+      root = dir;
+      break;
+    }
+    if (dirname(dir) === dir) break;
+  }
+  repoRoots.set(cwd, root);
+  return root;
+}
+
+/**
+ * candidatePaths lists the disk paths a call may write. Gortex paths are
+ * relative to the repo root and may carry the repo name as a first segment, so
+ * both forms are tried against cwd and the repo root; a candidate that does
+ * not exist simply never changes.
+ */
+export function candidatePaths(params: Record<string, unknown>, cwd: string): string[] {
+  const args = flatten(params);
+  const raw = [...namedPaths(args), ...batchItems(args.changes ?? args.edits).flatMap(namedPaths)];
+  const bases = [...new Set([cwd, repoRoot(cwd)])];
+  const out = new Set<string>();
+  for (const name of raw) {
+    if (!name) continue;
+    if (isAbsolute(name)) {
+      out.add(resolve(name));
+      continue;
+    }
+    const path = name.replace(/\\/g, "/");
+    const slash = path.indexOf("/");
+    for (const base of bases) {
+      out.add(resolve(base, path));
+      if (slash > 0) out.add(resolve(base, path.slice(slash + 1)));
+    }
+  }
+  return [...out].sort();
+}
+
+async function snapshot(path: string): Promise<Snapshot> {
+  try {
+    const info = await stat(path);
+    const skipped = (reason: string): Snapshot => ({ kind: "skipped", reason, size: info.size, mtimeMs: info.mtimeMs });
+    if (!info.isFile()) return skipped("");
+    if (info.size > MAX_FILE_BYTES) return skipped("over 1 MiB");
+    const raw = await readFile(path);
+    if (raw.includes(0)) return skipped("binary file");
+    let text: string;
+    try {
+      text = utf8.decode(raw);
+    } catch {
+      return skipped("not UTF-8 text");
+    }
+    return { kind: "text", raw, text: text.replace(/^/, "").replace(/\r\n/g, "\n") };
+  } catch (err) {
+    if ((err as { code?: string }).code === "ENOENT") return { kind: "missing" };
+    return { kind: "skipped", reason: "", size: -1, mtimeMs: -1 };
+  }
+}
+
+function snapshotAll(paths: string[]): Promise<Snapshot[]> {
+  return Promise.all(paths.map(snapshot));
+}
+
+function lineEnding(raw: Buffer): string {
+  return raw.includes("\r\n") ? "CRLF" : "LF";
+}
+
+function hasBom(raw: Buffer): boolean {
+  return raw[0] === 0xef && raw[1] === 0xbb && raw[2] === 0xbf;
+}
+
+/** What changed between two texts that are equal once normalized, or "" for nothing. */
+function invisibleChange(old: Buffer, now: Buffer): string {
+  if (old.equals(now)) return "";
+  const notes: string[] = [];
+  if (lineEnding(old) !== lineEnding(now)) notes.push(`line endings ${lineEnding(old)} -> ${lineEnding(now)}`);
+  if (hasBom(old) !== hasBom(now)) notes.push(hasBom(now) ? "byte order mark added" : "byte order mark removed");
+  return notes.length > 0 ? notes.join(", ") : "line endings changed";
+}
+
+/** A lower bound on the work Pi's line diff does: total lines times lines not shared. */
+function diffWork(old: string, now: string): number {
+  const a = old.split("\n");
+  const b = now.split("\n");
+  const counts = new Map<string, number>();
+  for (const line of a) counts.set(line, (counts.get(line) ?? 0) + 1);
+  let shared = 0;
+  for (const line of b) {
+    const n = counts.get(line);
+    if (n) {
+      counts.set(line, n - 1);
+      shared++;
+    }
+  }
+  return (a.length + b.length) * (a.length + b.length - 2 * shared);
+}
+
+function textOf(s: Snapshot): string | undefined {
+  if (s.kind === "missing") return "";
+  return s.kind === "text" ? s.text : undefined;
+}
+
+function diffOne(path: string, old: Snapshot, now: Snapshot): FileDiff | undefined {
+  const note = (text: string): FileDiff => ({ path, diff: "", patch: "", note: text });
+  if (old.kind === "skipped" || now.kind === "skipped") {
+    const reason = (now.kind === "skipped" ? now.reason : "") || (old.kind === "skipped" ? old.reason : "");
+    const unchanged =
+      old.kind === "skipped" && now.kind === "skipped" && old.size === now.size && old.mtimeMs === now.mtimeMs;
+    return reason && !unchanged ? note(`not diffed: ${reason}`) : undefined;
+  }
+  const before = textOf(old)!;
+  const after = textOf(now)!;
+  if (before === after) {
+    if (old.kind !== "text" || now.kind !== "text") return undefined;
+    const change = invisibleChange(old.raw, now.raw);
+    return change ? note(change) : undefined;
+  }
+  if (diffWork(before, after) > MAX_DIFF_WORK) return note("not diffed: change too large to diff quickly");
+  const { diff, firstChangedLine } = generateDiffString(before, after);
+  if (!diff) return undefined;
+  return { path, diff, patch: generateUnifiedPatch(path, before, after), firstChangedLine };
+}
+
+function diffSnapshots(paths: string[], before: Snapshot[], after: Snapshot[], cwd: string): FileDiff[] {
+  const diffs: FileDiff[] = [];
+  paths.forEach((abs, i) => {
+    const diff = diffOne(relative(cwd, abs) || abs, before[i]!, after[i]!);
+    if (diff) diffs.push(diff);
+  });
+  return diffs;
+}
+
+/** editDetails shapes diffs as a result's details; no diffs give no fields. */
+export function editDetails(diffs: FileDiff[]): EditDetails {
+  if (diffs.length === 0) return {};
+  const details: EditDetails = { diffs };
+  const patch = diffs.map((d) => d.patch).join("");
+  if (patch) details.patch = patch;
+  if (diffs.length === 1 && diffs[0]!.diff) {
+    details.diff = diffs[0]!.diff;
+    if (diffs[0]!.firstChangedLine !== undefined) details.firstChangedLine = diffs[0]!.firstChangedLine;
+  }
+  return details;
+}
+
+// A shell command can write any file, so a diff taken while one runs may
+// include its writes. Tracked on both channels through Pi's events.
+const SHELL_TOOLS = new Set(["bash", "powershell"]);
+const shellCallsRunning = new Set<string>();
+let shellCallsSeen = 0;
+
+/** Starts watching for shell calls; the result reports whether one overlapped. */
+function shellWindow(): () => boolean {
+  const busy = shellCallsRunning.size > 0;
+  const seen = shellCallsSeen;
+  return () => busy || shellCallsRunning.size > 0 || shellCallsSeen !== seen;
+}
+
+const SHELL_NOTE = "not diffed: a shell command ran at the same time";
+
+function shellNotes(diffs: FileDiff[]): FileDiff[] {
+  return diffs.map(({ path }) => ({ path, diff: "", patch: "", note: SHELL_NOTE }));
+}
+
+function withLocks<T>(paths: string[], fn: () => Promise<T>): Promise<T> {
+  return paths.reduceRight<() => Promise<T>>((next, path) => () => withFileMutationQueue(path, next), fn)();
+}
+
+/**
+ * withFileDiffs runs call while holding Pi's per-file mutation lock on every
+ * candidate path, and returns its result with a diff for each file it changed.
+ * A failed call is not diffed.
+ */
+export async function withFileDiffs<T>(
+  paths: string[],
+  cwd: string,
+  call: () => Promise<T>,
+  succeeded: (result: T) => boolean,
+): Promise<{ result: T; diffs: FileDiff[] }> {
+  return withLocks(paths, async () => {
+    const overlapped = shellWindow();
+    const before = await snapshotAll(paths);
+    const result = await call();
+    if (!succeeded(result)) return { result, diffs: [] };
+    const diffs = diffSnapshots(paths, before, await snapshotAll(paths), cwd);
+    return { result, diffs: overlapped() ? shellNotes(diffs) : diffs };
+  });
+}
+
+interface PendingEdit {
+  cwd: string;
+  paths: string[];
+  before?: Snapshot[];
+  /** Per path, the other calls in flight that also write it, so a diff could mix both. */
+  contested: Map<string, Set<string>>;
+  overlapped?: () => boolean;
+}
+
+function contest(entry: PendingEdit, path: string, by: string): void {
+  const ids = entry.contested.get(path) ?? new Set<string>();
+  ids.add(by);
+  entry.contested.set(path, ids);
+}
+
+/**
+ * watchNativeEdits diffs the gortex tools Pi's built-in MCP runs. Pi executes
+ * those, so the files are read on `tool_call` and again on `tool_result`, which
+ * stores the diffs in the result's details. Pi prepares a whole parallel batch
+ * before running any of it, so no lock can span the call; a path two calls in
+ * flight write gets no diff instead. Register it after every handler that may
+ * block, since a blocked call never reaches `tool_result`.
+ */
+export function watchNativeEdits(pi: ExtensionAPI, active: () => boolean): void {
+  const pending = new Map<string, PendingEdit>();
+
+  function claim(id: string, entry: PendingEdit): void {
+    for (const [otherId, other] of pending) {
+      for (const path of entry.paths) {
+        if (!other.paths.includes(path)) continue;
+        contest(other, path, id);
+        contest(entry, path, otherId);
+      }
+    }
+    pending.set(id, entry);
+  }
+
+  /** A call that ended without a result never ran, so it contests nothing. */
+  function release(id: string): void {
+    if (!pending.delete(id)) return;
+    for (const other of pending.values()) {
+      for (const ids of other.contested.values()) ids.delete(id);
+    }
+  }
+
+  pi.on("tool_call", async (event, ctx: ExtensionContext) => {
+    if (SHELL_TOOLS.has(event.toolName)) {
+      shellCallsRunning.add(event.toolCallId);
+      shellCallsSeen++;
+    }
+    try {
+      if (!active() || event.parentToolCallId) return;
+      const input = (event.input ?? {}) as Record<string, unknown>;
+      const cwd = ctx.cwd;
+      if (PI_WRITE_TOOLS.has(event.toolName) && typeof input.path === "string") {
+        claim(event.toolCallId, { cwd, paths: [resolve(cwd, input.path)], contested: new Map() });
+        return;
+      }
+      if (!isNativeGortexTool(event.toolName) || !isFileEdit(bareToolName(event.toolName), input)) return;
+      const paths = candidatePaths(input, cwd);
+      if (paths.length === 0) return;
+      const overlapped = shellWindow();
+      claim(event.toolCallId, { cwd, paths, before: await snapshotAll(paths), contested: new Map(), overlapped });
+    } catch {
+      // A throwing tool_call handler blocks the call.
+    }
+  });
+
+  pi.on("tool_result", async (event) => {
+    const entry = pending.get(event.toolCallId);
+    if (!entry) return;
+    pending.delete(event.toolCallId);
+    if (!entry.before || event.isError) return;
+    try {
+      const paths = entry.paths.filter((p) => !entry.contested.get(p)?.size);
+      const keep = entry.paths.map((p) => paths.includes(p));
+      const before = entry.before.filter((_, i) => keep[i]);
+      let diffs = diffSnapshots(paths, before, await snapshotAll(paths), entry.cwd);
+      if (diffs.length === 0) return;
+      if (entry.overlapped?.()) diffs = shellNotes(diffs);
+      return { details: { ...asRecord(event.details), ...editDetails(diffs) } };
+    } catch {
+      return;
+    }
+  });
+
+  // Pi emits this after tool_result, and also for a call another handler blocked.
+  pi.on("tool_execution_end", (event) => {
+    release(event.toolCallId);
+    shellCallsRunning.delete(event.toolCallId);
+  });
+  pi.on("turn_end", () => {
+    pending.clear();
+    shellCallsRunning.clear();
+  });
+  pi.on("session_shutdown", () => {
+    pending.clear();
+    shellCallsRunning.clear();
+  });
+}