pi-gortex 0.4.0 → 0.4.1

package/README.md

@@ -13,13 +13,16 @@ need instead of reading whole files around it, which is where the token
 savings come from. It is a single static binary with no dependency chain,
 and it covers 257 languages through tree-sitter.
 
-Pi has no MCP support by design, so this extension is the bridge.
+This extension connects the two. It hands `gortex mcp` to Pi's built-in MCP,
+or runs its own MCP client with `native_mcp` off. Read discipline goes through
+`gortex hook` on both.
 
 ## What it does
 
-- **Registers Gortex's graph tools as native Pi tools**, over a persistent
-  `gortex mcp` child per session. The deferred catalogue is reached through the
-  daemon's own `tools_search`, and promoted tools appear in Pi's registry.
+- **Registers Gortex's graph tools as native Pi tools**, through Pi's
+  built-in MCP or over the extension's own `gortex mcp` child per session. The
+  deferred catalogue is reached through the daemon's own `tools_search`, and
+  promoted tools appear in Pi's registry.
 - **Applies read discipline.** Pi's tool calls are forwarded to
   `gortex hook --agent=pi`, which answers block / soft guidance / nothing
   according to the posture you configured. Gortex owns that logic, so the
@@ -31,7 +34,7 @@ See [docs/architecture.md](docs/architecture.md) for how it works.
 
 ## Requirements
 
-- **Node 24+**, **Pi 0.85+**
+- **Node 24+**, **Pi 1.0+**
 - **The `gortex` binary** on `PATH`, **v0.61.2 or newer**. See
   [Gortex installation](https://github.com/zzet/gortex/blob/main/docs/installation.md).
   The extension starts the shared daemon itself and never blocks Pi's startup
@@ -57,16 +60,16 @@ the absolute path, or a single run with `pi -e /path/to/pi-gortex`.
 ## Configure
 
 Zero configuration required. Every value resolves at runtime, first hit wins:
-environment -> `<cwd>/.pi/gortex.json` -> `<agent dir>/extensions/gortex.json`
+environment -> `<session cwd>/.pi/gortex.json` -> `<agent dir>/extensions/gortex.json`
 (agent dir is `$PI_CODING_AGENT_DIR`, else `~/.pi/agent`) -> defaults.
 
 | Sidecar key    | Environment        | Default            | Meaning |
 |----------------|--------------------|--------------------|---------|
-| `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`. |
+| `bin`          | `GORTEX_BIN`       | `gortex` on `PATH` | The gortex binary. Read from the global sidecar only; a project file cannot set it. `~` expands, and a relative path resolves against the sidecar's directory (the launch directory for `GORTEX_BIN`). |
+| `hook_mode`    | `GORTEX_HOOK_MODE` | `deny`             | Posture: `deny`, `enrich`, `consult-unlock`, `nudge` (`adaptive-nudge` is an alias). |
 | `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. |
+| `tools_preset` | `GORTEX_TOOLS`     | daemon's default   | Eager MCP surface: a Gortex preset (`core`, `full`, `agent`, `edit`, `nav`, `readonly`, `localization`), optionally followed by comma-separated tool names and `+tool`/`-tool` changes, e.g. `nav,+edit_file`. A value that does not open with a preset is ignored. |
+| `native_mcp`   | `GORTEX_NATIVE_MCP` | `true`            | Register `gortex mcp` with Pi's built-in MCP. `false` keeps the extension's own client. |
 
 ```json
 {
@@ -76,8 +79,8 @@ 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`.
+The extension reads its configuration at every session start, from the
+directory the session runs in, so a change takes effect on `/reload` or `/new`.
 
 **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

package/docs/architecture.md

@@ -68,15 +68,15 @@ implementation forwards the call down that channel.
   arrive in bursts, so the re-sync is debounced; a search call awaits its own
   re-sync directly, so every tool its reply names is callable by the time the
   model reads it.
-- **Framing.** Reads are incremental. The scan for a frame boundary resumes
-  where the previous chunk ended, so one large frame split across many chunks
-  does not re-scan a growing buffer each time. A frame past a generous size cap
-  kills the child, because a stream cannot be resynced mid-frame, and the next
-  call respawns it.
+- **Framing.** Frames are cut at the newline byte and decoded whole, so a
+  character split across chunks arrives intact. A frame past a generous byte
+  cap kills the child, because a stream cannot be resynced mid-frame, and the
+  next call respawns it.
 - **Timeouts.** Every request is bounded: a short cap for ordinary requests, a
   longer one for the handshake, the longest for tool calls. The last is generous
   enough for analyzers that legitimately run for minutes, and finite so a wedged
-  daemon cannot hang an agent turn forever.
+  daemon cannot hang an agent turn forever. A call dropped on timeout or on
+  Pi's abort tells the daemon to cancel it.
 
 ### Tool-name aliasing
 
@@ -115,7 +115,8 @@ 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
+own tool name, which is what the postures key off. On Pi's built-in MCP that
+means the `mcp__gortex__` prefix is stripped. 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.
 
@@ -193,6 +194,20 @@ 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
+Resolution runs on every `session_start`, against the session's own directory.
+A resumed session runs where it was created, which need not be where Pi was
+launched. So the native server is registered on `session_start` rather than
+when Pi loads the extension, and again only when the session's preset or
+channel differ, since Pi reconnects a re-registered server. Pi reads a
+registration made before its own `session_start` handler and connects one made
+after it. The extension's own `gortex mcp` is spawned in the session's
+directory, which is what the proxy scopes the graph to.
+
+A tool preset reaches `gortex mcp` only when it opens with a preset Gortex
+knows. Gortex reads anything else as a bare allow-list, so a typo would strand
+the session; it falls through to the next layer instead. The resolved value
+always overrides an inherited `GORTEX_TOOLS`.
+
+The project file sits in whatever repository the session runs 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/docs/tests.md

@@ -88,15 +88,15 @@ point in the directory when the manifest resolves to nothing.
 ## Where the double stops
 
 The double models what the suites need and no more. Behaviour past that edge,
-such as promotion re-sync under real notification traffic, frame splitting, the
-frame size cap, a real model turn or a live daemon, is unverified here. A change
+such as promotion re-sync under real notification traffic, a real model turn or
+a live daemon, is unverified here. A change
 in that territory is verified by hand against a running Gortex, and the suite
 says as much rather than implying coverage it does not have.
 
 ## Pinning
 
-The Pi devDependency is pinned tight on purpose. Pi is pre-1.0 and its runner's
-method surface has been renamed without a changelog entry before, so a tight pin
+The Pi devDependency is pinned tight on purpose. Pi's runner's method surface
+has been renamed without a changelog entry before, so a tight pin
 turns that into a red build rather than a silently skipped suite. The runtime
 peer dependency stays wide.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gortex",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "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",

package/src/config.ts

@@ -7,17 +7,17 @@
 
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 
 /** The sidecar file's on-disk shape. `gortex init` is its writer. */
 export interface SidecarConfig {
-  /** Absolute path to the gortex binary. Global sidecar only. Default: resolved from PATH. */
+  /** The gortex binary. Global sidecar only; relative to the sidecar's directory. Default: resolved from PATH. */
   bin?: string;
   /** Hook posture: deny | enrich | consult-unlock | nudge. */
   hook_mode?: string;
   /** false mirrors `gortex init --no-hooks`: orientation only, no enforcement. */
   enforce?: boolean;
-  /** Eager MCP tool preset: core | full | edit | nav | readonly. */
+  /** Eager MCP tool preset (core | full | agent | edit | nav | readonly | localization) or a tool spec. */
   tools_preset?: string;
   /** false keeps the extension's own MCP client on a Pi that has built-in MCP. */
   native_mcp?: boolean;
@@ -31,7 +31,7 @@ export interface GortexConfig {
   hookArgv: string[];
   /** Whether to wire read-discipline enforcement onto tool_call. */
   enforce: boolean;
-  /** Eager tool preset; the daemon's default applies when this is core/full. */
+  /** GORTEX_TOOLS for `gortex mcp`; empty leaves the daemon's default surface. */
   toolsPreset: string;
   /** Whether to hand the tool channel to Pi's built-in MCP when Pi has one. */
   nativeMcp: boolean;
@@ -47,7 +47,15 @@ export interface ResolveConfigOptions {
 }
 
 export const DEFAULT_BIN = "gortex";
-export const DEFAULT_TOOLS_PRESET = "core";
+/** No preset: `gortex mcp` serves the daemon's default surface. */
+export const DEFAULT_TOOLS_PRESET = "";
+
+/** Expands a leading `~`, `~/` or `~\` to the home directory. */
+export function expandHome(path: string, home: string = homedir()): string {
+  if (path === "~") return home;
+  if (path.startsWith("~/") || path.startsWith("~\\")) return join(home, path.slice(2));
+  return path;
+}
 
 /**
  * Pi's agent directory, resolved the way Pi itself resolves it
@@ -59,15 +67,46 @@ export const DEFAULT_TOOLS_PRESET = "core";
  */
 export function defaultAgentDir(env: Record<string, string | undefined> = process.env): string {
   const override = env.PI_CODING_AGENT_DIR;
-  if (override && override.trim() !== "") {
-    const path = override.trim();
-    if (path === "~") return homedir();
-    if (path.startsWith("~/")) return join(homedir(), path.slice(2));
-    return path;
-  }
+  if (override && override.trim() !== "") return expandHome(override.trim());
   return join(homedir(), ".pi", "agent");
 }
 
+/**
+ * A `bin` setting as spawn needs it: `~` expanded, a relative path anchored at
+ * `baseDir`, a bare name left for PATH lookup.
+ */
+export function resolveBin(bin: string, baseDir: string): string {
+  const expanded = expandHome(bin);
+  if (!/[\\/]/.test(expanded) || isAbsolute(expanded)) return expanded;
+  return resolve(baseDir, expanded);
+}
+
+// Preset names and aliases Gortex accepts (internal/mcp/tool_presets.go).
+const KNOWN_PRESETS = new Set([
+  "full", "all",
+  "core", "default", "classic",
+  "agent", "coding-agent",
+  "facade-v1", "agent-v2", "compact", "facade",
+  "readonly", "read-only", "read_only",
+  "edit", "editor", "edit-harness",
+  "nav", "navigate", "explore",
+  "localization", "locate", "find",
+]);
+
+/**
+ * A tools_preset / GORTEX_TOOLS value Gortex should see, or undefined. Gortex
+ * reads a spec that does not open with a preset as a bare allow-list, so a
+ * typo (or `+tool` alone) would strip the session down to a tool or two. Only
+ * a spec opening with a known preset passes, optionally followed by
+ * comma-separated tool names and `+tool`/`-tool` changes.
+ */
+export function toolsSpec(value: string | undefined): string | undefined {
+  const tokens = (value ?? "").split(",").map((token) => token.trim()).filter(Boolean);
+  const preset = tokens[0]?.toLowerCase();
+  if (preset === undefined || !KNOWN_PRESETS.has(preset)) return undefined;
+  return [preset, ...tokens.slice(1)].join(",");
+}
+
 /** Sidecar paths, nearest first. A project file wins over the global one. */
 export function sidecarPaths(cwd: string, agentDir: string): string[] {
   return [join(cwd, ".pi", "gortex.json"), join(agentDir, "extensions", "gortex.json")];
@@ -139,30 +178,41 @@ export function resolveConfig(opts: ResolveConfigOptions = {}): GortexConfig {
   const agentDir = opts.agentDir ?? defaultAgentDir(env);
   const readFile = opts.readFile ?? ((path: string) => readFileSync(path, "utf8"));
 
-  const [project, global] = sidecarPaths(cwd, agentDir).map((path) => readSidecar(path, readFile));
+  const [projectPath, globalPath] = sidecarPaths(cwd, agentDir) as [string, string];
+  const project = readSidecar(projectPath, readFile);
+  const global = readSidecar(globalPath, readFile);
 
   // 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 envBin = firstString(env.GORTEX_BIN);
+  const globalBin = firstString(global.bin);
+  const bin = envBin
+    ? resolveBin(envBin, process.cwd())
+    : globalBin
+      ? resolveBin(globalBin, dirname(globalPath))
+      : DEFAULT_BIN;
+
+  const mode = normalizeMode(firstString(env.GORTEX_HOOK_MODE, project.hook_mode, global.hook_mode));
   const hookArgv = [bin, "hook", "--agent=pi"];
   // "deny" is the hook's own default, so it rides as an absent flag.
   if (mode !== "deny") hookArgv.push(`--mode=${mode}`);
 
   const enforce =
     parseBoolean(env.GORTEX_ENFORCE) ??
-    (typeof project?.enforce === "boolean" ? project.enforce : undefined) ??
-    (typeof global?.enforce === "boolean" ? global.enforce : undefined) ??
+    (typeof project.enforce === "boolean" ? project.enforce : undefined) ??
+    (typeof global.enforce === "boolean" ? global.enforce : undefined) ??
     true;
 
   const toolsPreset =
-    firstString(env.GORTEX_TOOLS, project?.tools_preset, global?.tools_preset) ?? DEFAULT_TOOLS_PRESET;
+    toolsSpec(env.GORTEX_TOOLS) ??
+    toolsSpec(firstString(project.tools_preset)) ??
+    toolsSpec(firstString(global.tools_preset)) ??
+    DEFAULT_TOOLS_PRESET;
 
   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) ??
+    (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/hook.ts

@@ -26,6 +26,7 @@ const HOOK_EXEC_OPTS: ExecFileSyncOpts = {
   encoding: "utf8",
   maxBuffer: 16 * 1024 * 1024,
   timeout: 5_000,
+  windowsHide: true,
 };
 
 /**
@@ -55,9 +56,9 @@ export function callHook(argv: string[], deps: ProcessDeps, envelope: PiEnvelope
 // The Go classifier switches on Claude-Code tool names and canonical input
 // keys ("file_path"/"pattern"/"command"), so the translation lives here.
 //
-// NOTE: Pi is pre-1.0. The built-in tool names mapped here are pinned to Pi's
-// documented API (packages/coding-agent/docs/extensions.md); if an upgrade
-// renames one, adjust this small map; the Go wire contract stays unchanged.
+// The built-in tool names mapped here are pinned to Pi's documented API
+// (packages/coding-agent/docs/extensions.md); if an upgrade renames one, adjust
+// this small map; the Go wire contract stays unchanged.
 export const toolNameMap: Record<string, string> = {
   read: "Read",
   grep: "Grep",

package/src/index.ts

@@ -11,7 +11,7 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 
 import { resolveConfig } from "./config.ts";
-import type { GortexConfig } from "./config.ts";
+import type { GortexConfig, ResolveConfigOptions } from "./config.ts";
 import { watchNativeEdits } from "./diff.ts";
 import { callHook, normalizeToolCall } from "./hook.ts";
 import {
@@ -145,22 +145,29 @@ function briefingInContext(ctx: ExtensionContext | undefined): boolean {
 
 /** Test seams. Pi itself calls the factory with the `pi` object alone. */
 export interface GortexExtensionOptions {
-  /** Pre-resolved configuration; resolveConfig() runs when this is absent. */
+  /** Fixed configuration; resolveConfig() runs per session when this is absent. */
   config?: GortexConfig;
+  /** resolveConfig() seams; `cwd` stands in for the process cwd until a session supplies one. */
+  resolve?: ResolveConfigOptions;
   /** Process seam for spawn/execFileSync. */
   deps?: ProcessDeps;
   /** Readiness cap override. */
   readyWaitMs?: number;
   /** Override for the wait on Pi's built-in MCP connecting the gortex server. */
   nativeReadyWaitMs?: number;
+  /** tools/call timeout override for the extension's own client. */
+  callTimeoutMs?: number;
+  /** Frame size cap override for the extension's own client. */
+  maxFrameBytes?: number;
 }
 
 export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensionOptions = {}): void {
-  const config = options.config ?? resolveConfig();
-  // Pi 0.85's ExtensionAPI declares no `cwd`, so the hook envelope reads it
-  // defensively and falls back to the process cwd. A Pi version that grows the
-  // field is picked up when it exists.
-  const piCwd = (): string => (pi as { cwd?: string })?.cwd ?? process.cwd();
+  // Resolved again on every session_start from ctx.cwd, the directory the
+  // session runs in. The factory has no session, so this first resolution only
+  // serves a turn that outruns session_start.
+  const configFor = (cwd?: string): GortexConfig =>
+    options.config ?? resolveConfig({ ...options.resolve, cwd: cwd ?? options.resolve?.cwd });
+  let config = configFor();
   const deps = options.deps ?? nodeProcessDeps;
   const readyWaitMs = options.readyWaitMs ?? READY_WAIT_MS;
   const nativeReadyWaitMs = options.nativeReadyWaitMs ?? NATIVE_READY_WAIT_MS;
@@ -169,12 +176,27 @@ export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensi
   // (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.
+  // Registered on session_start only, once the session's config is known: Pi
+  // reads a registration made before its own session_start handler, and
+  // connects one made after it.
   let nativeRefusal = "";
-  let native = ((): boolean => {
-    if (!config.nativeMcp || !supportsNativeMcp(pi) || !binaryResolves(config.bin)) return false;
+  let native = false;
+  let registered: GortexConfig | null = null;
+  function registerNative(connector: boolean): void {
+    if (native) unregisterNativeServer(pi);
+    native = false;
+    registered = config;
+    nativeRefusal = "";
+    if (!connector || !config.nativeMcp || !supportsNativeMcp(pi) || !binaryResolves(config.bin)) return;
     nativeRefusal = registerNativeServer(pi, config);
-    return nativeRefusal === "";
-  })();
+    native = nativeRefusal === "";
+  }
+
+  // Re-registering an unchanged server would make Pi reconnect it.
+  const channelChanged = (): boolean =>
+    registered === null ||
+    registered.nativeMcp !== config.nativeMcp ||
+    registered.toolsPreset !== config.toolsPreset;
 
   // Latched for the whole session once the first turn has run the
   // session_start hook, whether or not it produced anything to inject.
@@ -259,7 +281,10 @@ 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> {
-    if (native && !mcpConnectorLoaded(pi)) {
+    config = configFor(ctx?.cwd);
+    const connector = mcpConnectorLoaded(pi);
+    if (channelChanged()) registerNative(connector);
+    if (native && !connector) {
       unregisterNativeServer(pi);
       native = false;
     }
@@ -269,7 +294,14 @@ export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensi
     gortexToolNames.clear();
     withdrawnToolNames.clear();
     stopBridge();
-    const c = new MCPStdioClient({ bin: config.bin, toolsPreset: config.toolsPreset, deps });
+    const c = new MCPStdioClient({
+      bin: config.bin,
+      toolsPreset: config.toolsPreset,
+      cwd: ctx?.cwd,
+      deps,
+      callTimeoutMs: options.callTimeoutMs,
+      maxFrameBytes: options.maxFrameBytes,
+    });
     // Claim the slot before the first await: an overlapping
     // session_start (rapid /new or /reload) then sees and stops THIS
     // bridge instead of leaking its child mid-handshake.
@@ -316,7 +348,7 @@ export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensi
     const ready = native ? await waitForNativeTools(pi, nativeReadyWaitMs) : sessionDone;
     const decision = callHook(config.hookArgv, deps, {
       event: "session_start",
-      cwd: ctx?.cwd ?? piCwd(),
+      cwd: ctx?.cwd ?? process.cwd(),
     });
     // Pi's MCP keeps the handshake to itself, so the version comes from the briefing.
     if (native && decision.orientation) {
@@ -376,7 +408,7 @@ export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensi
       event: "tool_call",
       tool_name: norm.tool_name,
       tool_input: norm.tool_input,
-      cwd: ctx?.cwd ?? piCwd(),
+      cwd: ctx?.cwd ?? process.cwd(),
       session_id: (ctx as { sessionManager?: { sessionId?: string } })?.sessionManager?.sessionId ?? "",
       is_gortex_tool: isGortexTool,
     });
@@ -397,12 +429,13 @@ export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensi
     }
     return;
   };
-  if (config.enforce) pi.on("tool_call", enforceReadDiscipline);
+  // Registered unconditionally, since a session's own sidecar can turn enforcement on.
+  pi.on("tool_call", (event, ctx) => (config.enforce ? enforceReadDiscipline(event, ctx) : undefined));
 
   // 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) {
+  if (supportsNativeMcp(pi)) {
     // Pi < 1.0.1 has no tool renderers; the diffs are still stored.
     try {
       (pi as Partial<Pick<ExtensionAPI, "registerToolRenderer">>).registerToolRenderer?.(nativeRenderers);

package/src/mcp-client.ts

@@ -46,36 +46,30 @@ export function isBelowVersion(actual: string, floor: string): boolean {
   return false;
 }
 
-// Presets the proxy has to be told about. The daemon's own default surface
-// already IS core/defer, so those pass nothing. Anything unrecognised (a typo,
-// a stale sidecar value) is NOT forwarded: server-side it would parse as a
-// one-tool allow-list and silently filter every promoted tool out of the
-// 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.
+ * The variables `gortex mcp` needs on top of `env` to serve `toolsPreset`, the
+ * spec resolveConfig validated (it already folds in the user's GORTEX_TOOLS).
+ * Both are always set, so an inherited value resolveConfig rejected never
+ * reaches the child; empty leaves the daemon's default surface.
  */
 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;
+  if (toolsPreset === "") return { GORTEX_TOOLS: "", GORTEX_TOOLS_MODE: "" };
   // 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;
+  return { GORTEX_TOOLS: toolsPreset, GORTEX_TOOLS_MODE: env.GORTEX_TOOLS_MODE?.trim() || "defer" };
 }
 
 export interface MCPStdioClientOptions {
   bin: string;
   toolsPreset: string;
+  /** The session's directory, which `gortex mcp` scopes the graph to. Default: the process cwd. */
+  cwd?: string;
   deps: ProcessDeps;
   env?: Record<string, string | undefined>;
+  callTimeoutMs?: number;
+  maxFrameBytes?: number;
 }
 
 interface PendingRequest {
@@ -84,6 +78,25 @@ interface PendingRequest {
   timer?: ReturnType<typeof setTimeout>;
 }
 
+/** A JSON-RPC error reply, with the server's code and data kept for the model. */
+export class JsonRpcError extends Error {
+  readonly code: number | undefined;
+  readonly data: unknown;
+
+  constructor(error: { code?: unknown; message?: unknown; data?: unknown }) {
+    const code = typeof error.code === "number" ? error.code : undefined;
+    let message = typeof error.message === "string" && error.message ? error.message : "JSON-RPC error";
+    if (code !== undefined) message += ` (${code})`;
+    if (error.data !== undefined) {
+      message += `: ${typeof error.data === "string" ? error.data : JSON.stringify(error.data)}`;
+    }
+    super(message);
+    this.name = "JsonRpcError";
+    this.code = code;
+    this.data = error.data;
+  }
+}
+
 export interface ToolDescriptor {
   name: string;
   description?: string;
@@ -102,6 +115,7 @@ export function ensureDaemon(bin: string, deps: ProcessDeps): void {
     const child = deps.spawn(bin, ["daemon", "start", "--detach"], {
       stdio: "ignore",
       detached: true,
+      windowsHide: true,
     });
     child.on("error", () => {}); // binary missing / spawn failure: swallow
     // No teardown counterpart, by design: the daemon is shared, long-lived
@@ -127,8 +141,10 @@ export function textFromResult(result: unknown): string {
 
 export class MCPStdioClient {
   private child: BridgeChild | null = null;
-  private buffer = "";
-  private searchStart = 0;
+  // Raw bytes of the frame still being read. Frames are cut at the 0x0A byte
+  // and decoded whole, so a character split across chunks survives.
+  private chunks: Buffer[] = [];
+  private bufferedBytes = 0;
   private nextId = 1;
   private pending = new Map<number, PendingRequest>();
   private exited = true;
@@ -136,8 +152,11 @@ export class MCPStdioClient {
 
   private readonly bin: string;
   private readonly toolsPreset: string;
+  private readonly cwd: string | undefined;
   private readonly deps: ProcessDeps;
   private readonly env: Record<string, string | undefined>;
+  private readonly callTimeoutMs: number;
+  private readonly maxFrameBytes: number;
 
   // Fired on notifications/tools/list_changed (server-side promotion).
   onToolsListChanged: (() => void) | null = null;
@@ -150,8 +169,11 @@ export class MCPStdioClient {
   constructor(options: MCPStdioClientOptions) {
     this.bin = options.bin;
     this.toolsPreset = options.toolsPreset;
+    this.cwd = options.cwd;
     this.deps = options.deps;
     this.env = options.env ?? process.env;
+    this.callTimeoutMs = options.callTimeoutMs ?? CALL_TIMEOUT_MS;
+    this.maxFrameBytes = options.maxFrameBytes ?? MAX_BUFFER_BYTES;
   }
 
   private childEnv(): Record<string, string | undefined> {
@@ -161,11 +183,13 @@ export class MCPStdioClient {
   private spawnChild(): void {
     const child = this.deps.spawn(this.bin, ["mcp"], {
       stdio: ["pipe", "pipe", "pipe"],
+      cwd: this.cwd,
       env: this.childEnv(),
+      windowsHide: true,
     });
     this.child = child;
-    this.buffer = "";
-    this.searchStart = 0;
+    this.chunks = [];
+    this.bufferedBytes = 0;
     this.exited = false;
     child.stdout?.on("data", (chunk: unknown) => this.onData(chunk as Buffer));
     // Consume stderr so the child never blocks on a full pipe; routing it
@@ -185,68 +209,93 @@ export class MCPStdioClient {
     if (this.exited && this.pending.size === 0) return;
     this.exited = true;
     this.child = null;
-    for (const [, p] of this.pending) {
-      if (p.timer) clearTimeout(p.timer);
-      p.reject(err);
-    }
+    const pending = [...this.pending.values()];
     this.pending.clear();
+    for (const p of pending) p.reject(err);
   }
 
   private onData(chunk: Buffer): void {
-    this.buffer += chunk.toString("utf8");
+    let start = 0;
     let nl: number;
-    // Resume the newline scan where the previous chunk left off, so a
-    // large frame split across many chunks does not re-scan the whole
-    // growing buffer from index 0 on every data event.
-    while ((nl = this.buffer.indexOf("\n", this.searchStart)) >= 0) {
-      const line = this.buffer.slice(0, nl).trim();
-      this.buffer = this.buffer.slice(nl + 1);
-      this.searchStart = 0;
-      if (!line) continue;
-      let msg: unknown;
-      try {
-        msg = JSON.parse(line);
-      } catch {
-        continue; // non-JSON noise, ignore
-      }
-      this.dispatch(msg);
+    while ((nl = chunk.indexOf(0x0a, start)) >= 0) {
+      if (this.bufferedBytes + nl - start > this.maxFrameBytes) return this.overflow();
+      const tail = chunk.subarray(start, nl);
+      const frame = this.chunks.length > 0 ? Buffer.concat([...this.chunks, tail]) : tail;
+      this.chunks = [];
+      this.bufferedBytes = 0;
+      start = nl + 1;
+      this.onFrame(frame.toString("utf8").trim());
     }
-    this.searchStart = this.buffer.length;
-    if (this.buffer.length > MAX_BUFFER_BYTES) {
-      // One frame past the cap is fatal for this child (no way to
-      // resync mid-frame): pending requests reject, the next call
-      // respawns a fresh child.
-      this.buffer = "";
-      this.searchStart = 0;
-      const child = this.child;
-      this.markExited(new Error(`gortex mcp frame exceeded ${MAX_BUFFER_BYTES} bytes`));
-      try {
-        child?.kill();
-      } catch {
-        // already gone
-      }
+    if (start >= chunk.length) return;
+    this.chunks.push(start === 0 ? chunk : chunk.subarray(start));
+    this.bufferedBytes += chunk.length - start;
+    if (this.bufferedBytes > this.maxFrameBytes) this.overflow();
+  }
+
+  // One frame past the cap is fatal for this child (no way to resync
+  // mid-frame): pending requests reject, the next call respawns a fresh child.
+  private overflow(): void {
+    this.chunks = [];
+    this.bufferedBytes = 0;
+    const child = this.child;
+    this.markExited(new Error(`gortex mcp frame exceeded ${this.maxFrameBytes} bytes`));
+    try {
+      child?.kill();
+    } catch {
+      // already gone
     }
   }
 
-  private dispatch(msg: unknown): void {
-    const frame = msg as { id?: unknown; error?: { code?: number; message?: string }; result?: unknown; method?: unknown };
-    if (frame && typeof frame.id === "number" && this.pending.has(frame.id)) {
-      const p = this.pending.get(frame.id)!;
-      this.pending.delete(frame.id);
-      if (p.timer) clearTimeout(p.timer);
-      if (frame.error) {
-        p.reject(new Error(frame.error.message || `JSON-RPC error ${frame.error.code}`));
-      } else {
-        p.resolve(frame.result);
+  private onFrame(line: string): void {
+    if (!line) return;
+    let msg: unknown;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      return; // non-JSON noise, ignore
+    }
+    if (msg && typeof msg === "object") this.dispatch(msg as Record<string, unknown>);
+  }
+
+  private dispatch(frame: Record<string, unknown>): void {
+    const { id, method } = frame;
+    if (typeof method === "string") {
+      if (typeof id === "number" || typeof id === "string") this.answerServerRequest(id, method);
+      else if (method === "notifications/tools/list_changed") {
+        try {
+          this.onToolsListChanged?.();
+        } catch {
+          // best effort; never break the read loop.
+        }
       }
       return;
     }
-    if (frame && frame.method === "notifications/tools/list_changed") {
-      try {
-        this.onToolsListChanged?.();
-      } catch {
-        // best effort; never break the read loop.
-      }
+    const error = frame.error as Record<string, unknown> | undefined;
+    if (id === null && error) {
+      // The server could not tell which request this answers, so none of
+      // them will get a reply.
+      const pending = [...this.pending.values()];
+      this.pending.clear();
+      for (const p of pending) p.reject(new JsonRpcError(error));
+      return;
+    }
+    if (typeof id !== "number") return;
+    const p = this.pending.get(id);
+    if (!p) return;
+    this.pending.delete(id);
+    if (error) p.reject(new JsonRpcError(error));
+    else p.resolve(frame.result);
+  }
+
+  private answerServerRequest(id: number | string, method: string): void {
+    const reply =
+      method === "ping"
+        ? { jsonrpc: "2.0", id, result: {} }
+        : { jsonrpc: "2.0", id, error: { code: -32601, message: `Method not found: ${method}` } };
+    try {
+      this.send(reply);
+    } catch {
+      // the child is gone; nothing is waiting on the answer.
     }
   }
 
@@ -270,24 +319,54 @@ export class MCPStdioClient {
     return this.respawnPromise;
   }
 
-  async request(method: string, params: unknown, timeoutMs: number = RPC_TIMEOUT_MS): Promise<unknown> {
+  /**
+   * Sends one request. On abort or timeout the call is dropped and the server
+   * is sent notifications/cancelled, so a late reply is ignored.
+   */
+  async request(
+    method: string,
+    params: unknown,
+    timeoutMs: number = RPC_TIMEOUT_MS,
+    signal?: AbortSignal,
+  ): Promise<unknown> {
+    const aborted = () => new Error(`${method} aborted`);
+    if (signal?.aborted) throw aborted();
     if (this.exited) await this.respawn();
+    if (signal?.aborted) throw aborted();
     const id = this.nextId++;
     return new Promise((resolve, reject) => {
-      const entry: PendingRequest = { resolve, reject };
+      const onAbort = () => abandon(aborted());
+      const settled = () => {
+        if (entry.timer) clearTimeout(entry.timer);
+        signal?.removeEventListener("abort", onAbort);
+      };
+      const entry: PendingRequest = {
+        resolve: (value) => {
+          settled();
+          resolve(value);
+        },
+        reject: (err) => {
+          settled();
+          reject(err);
+        },
+      };
+      const abandon = (err: Error) => {
+        if (this.pending.get(id) !== entry) return;
+        this.pending.delete(id);
+        entry.reject(err);
+        // The MCP spec forbids cancelling initialize.
+        if (method !== "initialize") this.notify("notifications/cancelled", { requestId: id, reason: err.message });
+      };
       if (Number.isFinite(timeoutMs)) {
-        entry.timer = setTimeout(() => {
-          this.pending.delete(id);
-          reject(new Error(`${method} timed out after ${timeoutMs}ms`));
-        }, timeoutMs);
+        entry.timer = setTimeout(() => abandon(new Error(`${method} timed out after ${timeoutMs}ms`)), timeoutMs);
       }
+      signal?.addEventListener("abort", onAbort, { once: true });
       this.pending.set(id, entry);
       try {
         this.send({ jsonrpc: "2.0", id, method, params });
       } catch (err) {
         this.pending.delete(id);
-        if (entry.timer) clearTimeout(entry.timer);
-        reject(err instanceof Error ? err : new Error(String(err)));
+        entry.reject(err instanceof Error ? err : new Error(String(err)));
       }
     });
   }
@@ -336,8 +415,8 @@ export class MCPStdioClient {
     return Array.isArray(res?.tools) ? (res.tools as ToolDescriptor[]) : [];
   }
 
-  async callTool(name: string, args: Record<string, unknown>): Promise<unknown> {
-    return this.request("tools/call", { name, arguments: args ?? {} }, CALL_TIMEOUT_MS);
+  async callTool(name: string, args: Record<string, unknown>, signal?: AbortSignal): Promise<unknown> {
+    return this.request("tools/call", { name, arguments: args ?? {} }, this.callTimeoutMs, signal);
   }
 
   stop(): void {

package/src/native.ts

@@ -18,7 +18,7 @@ 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.
+// Read structurally, since a Pi before 0.99 has none of these members.
 type NativeMcpApi = Pick<ExtensionAPI, "registerMcpServer" | "unregisterMcpServer" | "getAllTools" | "getCommands">;
 
 export function supportsNativeMcp(pi: ExtensionAPI): boolean {

package/src/runtime.ts

@@ -32,7 +32,9 @@ export interface BridgeChild {
 export interface SpawnOpts {
   stdio?: "ignore" | ("pipe" | "ignore")[];
   detached?: boolean;
+  cwd?: string;
   env?: Record<string, string | undefined>;
+  windowsHide?: boolean;
 }
 
 export interface ExecFileSyncOpts {
@@ -40,6 +42,7 @@ export interface ExecFileSyncOpts {
   encoding?: "utf8";
   maxBuffer?: number;
   timeout?: number;
+  windowsHide?: boolean;
 }
 
 export interface ProcessDeps {

package/src/tools.ts

@@ -95,11 +95,11 @@ export function registerOneTool(pi: ExtensionAPI, desc: ToolDescriptor): void {
     label: name,
     description: piAliasedDescription(name, piAliasName(name), (desc.description || name).trim()),
     parameters,
-    async execute(_id, params, _signal, _onUpdate, ctx) {
+    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);
+      const callTool = () => client.callTool(name, args, signal);
       let result: unknown;
       let diffs: FileDiff[] = [];
       try {