pi-gortex 0.3.0 → 0.4.0

package/README.md

@@ -62,7 +62,7 @@ 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. |

package/docs/architecture.md

@@ -88,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
@@ -109,11 +124,14 @@ 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
 
@@ -174,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.3.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,8 +35,8 @@
     "prepublishOnly": "npm run check"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "~1.0.2",
-    "@earendil-works/pi-tui": "^1.0.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"

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;
@@ -141,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"];

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();
+  });
+}

package/src/index.ts

@@ -3,7 +3,7 @@
 // hook bridge. See docs/architecture.md for the design.
 
 import type {
-  ContextEvent,
+  BeforeAgentStartEventResult,
   ExtensionAPI,
   ExtensionContext,
   ToolCallEvent,
@@ -12,6 +12,7 @@ import type {
 
 import { resolveConfig } from "./config.ts";
 import type { GortexConfig } from "./config.ts";
+import { watchNativeEdits } from "./diff.ts";
 import { callHook, normalizeToolCall } from "./hook.ts";
 import {
   MCPStdioClient,
@@ -32,6 +33,7 @@ import {
   supportsNativeMcp,
   waitForNativeTools,
 } from "./native.ts";
+import { nativeRenderers } from "./render.ts";
 import { nodeProcessDeps } from "./runtime.ts";
 import type { ProcessDeps } from "./runtime.ts";
 import {
@@ -47,6 +49,7 @@ import {
   setBridgeError,
   setClient,
   setVersionWarning,
+  withdrawnToolNames,
 } from "./state.ts";
 
 export type { GortexConfig, SidecarConfig } from "./config.ts";
@@ -109,6 +112,37 @@ function notifyUser(ctx: ExtensionContext | undefined, message: string): void {
   }
 }
 
+/** Marks the messages this extension stores in the session. */
+const GORTEX_MESSAGE_TYPE = "gortex";
+
+interface GortexMessageDetails {
+  /** Whether the content includes the session briefing, not only warnings. */
+  briefing: boolean;
+}
+
+/** Kept out of the transcript; Pi still sends it to the model. */
+function gortexMessage(content: string, briefing: boolean): BeforeAgentStartEventResult {
+  const details: GortexMessageDetails = { briefing };
+  return { message: { customType: GORTEX_MESSAGE_TYPE, content, display: false, details } };
+}
+
+/**
+ * Whether a briefing already sits in what the model sees: after a resume or
+ * /reload, or when compaction kept it. Answers false when Pi can't tell.
+ */
+function briefingInContext(ctx: ExtensionContext | undefined): boolean {
+  try {
+    return (ctx?.sessionManager.buildContextEntries() ?? []).some(
+      (entry) =>
+        entry.type === "custom_message" &&
+        entry.customType === GORTEX_MESSAGE_TYPE &&
+        (entry.details as GortexMessageDetails | undefined)?.briefing === true,
+    );
+  } catch {
+    return false;
+  }
+}
+
 /** Test seams. Pi itself calls the factory with the `pi` object alone. */
 export interface GortexExtensionOptions {
   /** Pre-resolved configuration; resolveConfig() runs when this is absent. */
@@ -145,10 +179,10 @@ export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensi
   // Latched for the whole session once the first turn has run the
   // session_start hook, whether or not it produced anything to inject.
   let startupHookRan = false;
-  // Orientation awaiting injection into the next LLM call, computed once per
-  // session. The `context` hook appends it as a tail user message, because a
-  // systemPrompt change sits at messages[0] and invalidates prefix caching.
-  let pendingOrientation = "";
+  // This session's briefing, kept so a compaction that summarises it away can
+  // send it again on the next turn.
+  let briefing = "";
+  let briefingCompacted = false;
 
   // Settles when the current session_start handler is done: bridge up and
   // tools registered, or the handshake failed. Never rejects.
@@ -198,7 +232,8 @@ export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensi
   // session's bridge child (if any) is stopped before a fresh handshake.
   pi.on("session_start", async (_event, ctx) => {
     startupHookRan = false;
-    pendingOrientation = "";
+    briefing = "";
+    briefingCompacted = false;
     setBridgeError("");
     setVersionWarning("");
     armSessionReady(); // no-op when a turn is already parked on this session
@@ -232,6 +267,7 @@ export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensi
     if (nativeRefusal) notifyUser(ctx, `Pi refused the gortex MCP server (${nativeRefusal}), so the extension runs its own client.`);
     ensureDaemon(config.bin, deps);
     gortexToolNames.clear();
+    withdrawnToolNames.clear();
     stopBridge();
     const c = new MCPStdioClient({ bin: config.bin, toolsPreset: config.toolsPreset, deps });
     // Claim the slot before the first await: an overlapping
@@ -258,10 +294,20 @@ 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 (_event, ctx) => {
-    if (startupHookRan) return;
+  pi.on("session_compact", () => {
+    briefingCompacted = true;
+  });
+
+  // Fires before the agent loop's first LLM call. The returned message is
+  // stored in the session after the prompt, so every later LLM call carries it
+  // and the system prompt, which prefix caching keys on, stays untouched.
+  pi.on("before_agent_start", async (_event, ctx): Promise<BeforeAgentStartEventResult | void> => {
+    if (startupHookRan) {
+      if (!briefingCompacted) return;
+      briefingCompacted = false;
+      if (!briefing || briefingInContext(ctx)) return;
+      return gortexMessage(briefing, true);
+    }
     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).
@@ -300,30 +346,15 @@ export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensi
       parts.push(versionWarning);
       setVersionWarning("");
     }
-    if (decision.orientation) parts.push(decision.orientation);
-    if (parts.length > 0) pendingOrientation = parts.join("\n\n");
-    return;
-  });
-
-  // Fires before each LLM call with a mutable message array. Appends the
-  // parked orientation once, clearing it only after the push lands so the
-  // orientation survives a context shape this hook can't append to.
-  // Pi exports ContextEvent but not its result type, so it is spelled out here.
-  pi.on("context", (event: ContextEvent): { messages?: ContextEvent["messages"] } | void => {
-    if (!pendingOrientation) return;
-    try {
-      const messages = (event as { messages?: unknown })?.messages;
-      if (Array.isArray(messages)) {
-        // Pi's AgentMessage also carries a `timestamp`; only the two fields
-        // Pi reads for a tail user turn are pushed.
-        messages.push({ role: "user", content: pendingOrientation } as ContextEvent["messages"][number]);
-        pendingOrientation = "";
-        return { messages: messages as ContextEvent["messages"] };
-      }
-    } catch {
-      // best effort; never break context assembly.
+    let briefed = false;
+    if (decision.orientation) {
+      briefing = decision.orientation;
+      // A resumed or reloaded session already holds it.
+      briefed = !briefingInContext(ctx);
+      if (briefed) parts.push(decision.orientation);
     }
-    return;
+    if (parts.length === 0) return;
+    return gortexMessage(parts.join("\n\n"), briefed);
   });
 
   // Never let the bridge child outlive the session.
@@ -331,10 +362,8 @@ export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensi
     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 enforceReadDiscipline = 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 = native ? isNativeGortexTool(piName) : gortexToolNames.has(piName);
@@ -367,5 +396,18 @@ export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensi
       }
     }
     return;
-  });
+  };
+  if (config.enforce) pi.on("tool_call", enforceReadDiscipline);
+
+  // After enforcement, so a blocked call is never snapshotted. Shell calls are
+  // tracked on both channels; edits are snapshotted on Pi's built-in MCP only.
+  watchNativeEdits(pi, () => native);
+  if (native) {
+    // Pi < 1.0.1 has no tool renderers; the diffs are still stored.
+    try {
+      (pi as Partial<Pick<ExtensionAPI, "registerToolRenderer">>).registerToolRenderer?.(nativeRenderers);
+    } catch {
+      // drawing diffs is optional
+    }
+  }
 }

package/src/render.ts

@@ -1,18 +1,25 @@
 // 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.
+// an edit's diff, 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 { createReadToolDefinition, renderDiff } from "@earendil-works/pi-coding-agent";
+import type { Theme, ToolDefinition, ToolRenderers } from "@earendil-works/pi-coding-agent";
+import { Container, Spacer, Text, truncateToWidth } from "@earendil-works/pi-tui";
 import type { Component } from "@earendil-works/pi-tui";
 
+import type { EditDetails } from "./diff.ts";
 import { textFromResult } from "./mcp-client.ts";
+import { isNativeGortexTool } from "./native.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;
+export type RenderResult = (
+  result: unknown,
+  options: { expanded?: boolean },
+  theme?: Theme,
+  context?: ToolRenderContext,
+) => Component;
 
 const OPERATION_ARGS = ["operation", "kind"];
 const SUBJECT_ARGS = ["target", "query", "question", "task", "path"];
@@ -144,6 +151,56 @@ export function resultText(result: unknown): string {
   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);
+/** diffView draws each file an edit changed with Pi's diff renderer, or nothing when the result has none. */
+function diffView(result: unknown, theme: Theme | undefined, context: ToolRenderContext | undefined): Container | undefined {
+  const diffs = (result as { details?: EditDetails })?.details?.diffs;
+  if (!diffs?.length || !theme || context?.isError) return undefined;
+  const view = new Container();
+  for (const { path, diff, note } of diffs) {
+    view.addChild(new Spacer(1));
+    if (note) {
+      view.addChild(new Text(`${theme.fg("accent", path)} ${theme.fg("muted", note)}`, 1, 0));
+      continue;
+    }
+    if (diffs.length > 1) view.addChild(new Text(theme.fg("accent", path), 1, 0));
+    view.addChild(new Text(renderDiff(diff, { filePath: path }), 1, 0));
+  }
+  return view;
+}
+
+/**
+ * renderResult shows the diff of every file an edit changed, the way Pi's own
+ * edit does. Gortex's text reply stays collapsed until the user expands it
+ * with ctrl+o.
+ */
+export const renderResult: RenderResult = (result, options, theme, context) => {
+  const text = new Text(options?.expanded ? resultText(result) : "", 0, 0);
+  const view = diffView(result, theme, context);
+  if (!view) return text;
+  if (options?.expanded) view.addChild(text);
+  return view;
+};
+
+/**
+ * nativeRenderers draws the diffs watchNativeEdits stores above Pi's own MCP
+ * result, which shows once expanded or on an error. Every other tool keeps its
+ * renderers.
+ */
+export function nativeRenderers(toolName: string, next: () => ToolRenderers | undefined): ToolRenderers | undefined {
+  const base = next();
+  // Without a base, Pi's MCP extension fills in its own renderers.
+  if (!base || !isNativeGortexTool(toolName)) return base;
+  const baseResult = base.renderResult;
+  return {
+    ...base,
+    renderResult(result, options, theme, context) {
+      // Pi's renderer reuses lastComponent as its own and clears it.
+      const own = () => baseResult?.(result, options, theme, { ...context, lastComponent: undefined });
+      const rest = options.expanded || context.isError ? own() : undefined;
+      const view = diffView(result, theme, context);
+      if (!view) return rest ?? new Text("", 0, 0);
+      if (rest) view.addChild(rest);
+      return view;
+    },
+  };
+}

package/src/state.ts

@@ -33,6 +33,13 @@ let versionWarning = "";
  */
 export const gortexToolNames = new Set<string>();
 
+/**
+ * Registered names the daemon has since dropped from its list. Pi cannot
+ * unregister a tool, so these are switched off in the active set instead, and
+ * back on if the daemon lists them again.
+ */
+export const withdrawnToolNames = new Set<string>();
+
 export function getClient(): MCPStdioClient | null {
   return client;
 }

package/src/tools.ts

@@ -1,12 +1,15 @@
 // Tool registration: each tool the bridge lists becomes a native Pi tool whose
 // execute() forwards to tools/call.
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { candidatePaths, editDetails, isFileEdit, withFileDiffs } from "./diff.ts";
+import type { FileDiff } from "./diff.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 { getClient, gortexToolNames, withdrawnToolNames } from "./state.ts";
 import { toolNameMap } from "./hook.ts";
 
 // Pi's reserved built-in names (mirrors toolNameMap's keys). A bridge tool that
@@ -44,7 +47,13 @@ interface BridgeToolDefinition {
   label: string;
   description: string;
   parameters: unknown;
-  execute(toolCallId: string, params: Record<string, unknown>): Promise<unknown>;
+  execute(
+    toolCallId: string,
+    params: Record<string, unknown>,
+    signal: AbortSignal | undefined,
+    onUpdate: unknown,
+    ctx: ExtensionContext | undefined,
+  ): Promise<unknown>;
   renderCall: RenderCall;
   renderResult: RenderResult;
 }
@@ -86,12 +95,20 @@ export function registerOneTool(pi: ExtensionAPI, desc: ToolDescriptor): void {
     label: name,
     description: piAliasedDescription(name, piAliasName(name), (desc.description || name).trim()),
     parameters,
-    async execute(_id: string, params: Record<string, unknown>) {
+    async execute(_id, params, _signal, _onUpdate, ctx) {
       const client = getClient();
       if (!client) throw new Error(`gortex ${name}: MCP bridge is not connected`);
+      const args = params ?? {};
+      const callTool = () => client.callTool(name, args);
       let result: unknown;
+      let diffs: FileDiff[] = [];
       try {
-        result = await client.callTool(name, params ?? {});
+        if (ctx && isFileEdit(name, args)) {
+          const paths = candidatePaths(args, ctx.cwd);
+          ({ result, diffs } = await withFileDiffs(paths, ctx.cwd, callTool, (r) => !(r as { isError?: boolean })?.isError));
+        } else {
+          result = await callTool();
+        }
       } catch (err) {
         throw new Error(`gortex ${name} failed: ${err instanceof Error ? err.message : String(err)}`);
       }
@@ -103,7 +120,7 @@ export function registerOneTool(pi: ExtensionAPI, desc: ToolDescriptor): void {
       }
       const text = resultText(result);
       if ((result as { isError?: boolean })?.isError) throw new Error(text || `gortex ${name} failed`);
-      return { content: [{ type: "text", text }], details: {} };
+      return { content: [{ type: "text", text }], details: editDetails(diffs) };
     },
     renderCall: (name === "read" ? readCallRenderer : callRenderer)(piAliasName(name)),
     renderResult,
@@ -115,13 +132,36 @@ export function registerOneTool(pi: ExtensionAPI, desc: ToolDescriptor): void {
 export async function registerGortexTools(pi: ExtensionAPI): Promise<void> {
   const client = getClient();
   if (!client) return;
+  const listed = new Set<string>();
   for (const desc of await client.listTools()) {
-    if (!desc) continue;
+    if (!desc?.name) continue;
     registerOneTool(pi, desc);
+    listed.add(piAliasName(desc.name));
+  }
+  matchActiveTools(pi, listed);
+}
+
+/** Keeps the tools offered to the model in step with the daemon's list. */
+function matchActiveTools(pi: ExtensionAPI, listed: Set<string>): void {
+  const dropped = [...gortexToolNames].filter((name) => !listed.has(name));
+  const relisted = [...withdrawnToolNames].filter((name) => listed.has(name));
+  if (dropped.length === 0 && relisted.length === 0) return;
+  for (const name of dropped) {
+    gortexToolNames.delete(name);
+    withdrawnToolNames.add(name);
+  }
+  for (const name of relisted) withdrawnToolNames.delete(name);
+  try {
+    const active = new Set(pi.getActiveTools());
+    for (const name of dropped) active.delete(name);
+    for (const name of relisted) active.add(name);
+    pi.setActiveTools([...active]);
+  } catch {
+    // an invalidated instance keeps its last tool set.
   }
 }
 
-/** Re-fetches the tool list after a list_changed and registers anything new. */
+/** Re-fetches the tool list after a list_changed and applies the difference. */
 export async function syncTools(pi: ExtensionAPI): Promise<void> {
   try {
     await registerGortexTools(pi);