pi-lean-ctx 3.7.4 → 3.8.0

package/README.md

@@ -2,8 +2,8 @@
 
 [Pi Coding Agent](https://github.com/badlogic/pi-mono) extension that provides `ctx_`-prefixed tools backed by [lean-ctx](https://leanctx.com) for **60–90% token savings**.
 
-- **Default**: CLI-only, additive mode (no MCP required, Pi builtins preserved)
-- **Optional**: enable MCP tools (`LEAN_CTX_PI_ENABLE_MCP=1`) or run `lean-ctx init --agent pi --mode mcp`
+- **Default**: embedded MCP bridge ON (persistent session cache → unchanged re-reads cost ~13 tokens), additive mode (Pi builtins preserved)
+- **Opt out**: `LEAN_CTX_PI_ENABLE_MCP=0` (or `"enableMcp": false`) forces the one-shot CLI path, which cannot cache across calls
 - **Optional**: replace mode (`LEAN_CTX_PI_MODE=replace`) disables Pi builtins
 
 ## Tool Mode
@@ -31,9 +31,13 @@ env vars — `~/.pi/agent/extensions/pi-lean-ctx/config.json`:
 ```
 
 `mode` → `LEAN_CTX_PI_MODE`, `enableMcp` → `LEAN_CTX_PI_ENABLE_MCP`,
-`binary` → `LEAN_CTX_BIN`. The `env` map is forwarded to every `lean-ctx`
-subprocess, so it can override `~/.lean-ctx/config.toml` engine settings.
-Explicit env vars still win over the file; the file wins over defaults.
+`binary` → `LEAN_CTX_BIN`, `disableTools` → `LEAN_CTX_PI_DISABLE_TOOLS`,
+`toolPrefix` → `LEAN_CTX_PI_TOOL_PREFIX` (see
+[Coexisting with AFT and magic-context](#coexisting-with-aft-and-magic-context)).
+The `env` map is forwarded to every `lean-ctx` subprocess, so it can override
+`~/.lean-ctx/config.toml` engine settings. Explicit env vars still win over the
+file; the file wins over defaults. The deny-list is the one exception — the env
+and file lists are **merged**, since a deny-list is additive by intent.
 
 ## What it does
 
@@ -108,33 +112,79 @@ These tools invoke the `lean-ctx` binary via CLI with `LEAN_CTX_COMPRESS=1`.
 The built-in tools they replace (`read`, `bash`, `ls`, `find`, `grep`) are disabled
 via `pi.setActiveTools()` so only the `ctx_` versions are available to the LLM.
 
-### Optional MCP bridge (all other tools)
+### Embedded MCP bridge (session cache + advanced tools)
 
-If you enable the MCP bridge, pi-lean-ctx spawns the `lean-ctx` binary as an MCP server (JSON-RPC over stdio).
-It discovers available tools via `list_tools`, filters out those already covered by `ctx_` CLI tools,
-and registers the rest as native Pi tools.
+On by default, pi-lean-ctx spawns the `lean-ctx` binary as an MCP server (JSON-RPC over stdio).
+This persistent process holds the **session cache**: `ctx_read` (every mode, including line
+ranges) is routed through the bridge, so an unchanged re-read costs ~13 tokens instead of the
+full file and the read registers as a real CEP session (counted by `lean-ctx gain`). The bridge
+also discovers the server's advanced tools (`ctx_edit`, `ctx_overview`, `ctx_graph`, …),
+filters out those already exposed as `ctx_` CLI tools, and registers the rest as native Pi tools.
 
-If `lean-ctx` is already configured as an MCP server via [pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter) in `~/.pi/agent/mcp.json`, the embedded bridge is skipped to avoid duplicate tools.
+The bridge wins over `~/.pi/agent/mcp.json`: a `lean-ctx` entry there (written by
+`lean-ctx init --agent pi`) does **not** disable the embedded bridge, because Pi has no native
+MCP support and that entry only does anything if you separately run
+[pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter). `/lean-ctx` warns about possible
+duplicates only when the adapter is genuinely running. If the bridge can't start, the CLI path
+keeps working — only the cache and advanced tools are unavailable.
 
 ### Automatic reconnection
 
 If the MCP server process crashes, the bridge automatically reconnects (up to 3 attempts with exponential backoff). If reconnection fails, CLI-based tools continue working normally — only the advanced MCP tools become unavailable.
 
-## Enabling MCP (optional)
+## Disabling the bridge (optional)
 
-Set an environment variable and restart Pi:
+The bridge is on by default. To force the one-shot CLI path (no cross-call cache),
+set an environment variable and restart Pi:
 
 ```bash
-export LEAN_CTX_PI_ENABLE_MCP=1
+export LEAN_CTX_PI_ENABLE_MCP=0
 pi
 ```
 
-Or configure MCP via `lean-ctx init`:
+…or set `"enableMcp": false` in `~/.pi/agent/extensions/pi-lean-ctx/config.json`.
+
+## Verifying token savings
+
+The session cache's headline claim — an **unchanged re-read costs ~13 tokens** —
+is now a one-command, machine-checkable self-test (issue #361). No manual
+transcript inspection required:
 
 ```bash
-lean-ctx init --agent pi --mode mcp
+lean-ctx verify-cache
 ```
 
+It reads a file twice through the real session cache and asserts the second read
+collapses to a `[unchanged …]` stub:
+
+```text
+lean-ctx verify-cache
+
+  Target:        src/main.rs
+  Cache policy:  aggressive
+  Read #1 (full):     3731 tokens
+  Read #2 (re-read):  13 tokens  [unchanged stub]
+  Re-read savings:    100%
+  Cache hits (run):   1/2
+  CEP sessions:       42 (88% cross-call hit ratio)
+
+  PASS — session cache engaged: the unchanged re-read cost 13 tokens (≈13-token stub).
+```
+
+- Exit code `0` = cache proven, `1` = no stub (cache not engaging), `2` =
+  stubbing disabled by config (e.g. `cache_policy = safe`). Add `--json` for CI.
+- Pass an explicit path to probe a real file: `lean-ctx verify-cache src/app.ts`.
+- `lean-ctx doctor` also prints a **Session cache** line (CEP sessions +
+  cross-call hit ratio) so you can answer "is the cache engaging?" at a glance.
+
+> On Pi specifically, the embedded MCP bridge (on by default) is what holds the
+> cache across calls. If `verify-cache` fails, confirm the bridge is connected
+> via `/lean-ctx`; the one-shot CLI path cannot cache across calls.
+
+This check was added in response to the independent, pre-registered
+[tokbench](https://github.com/Entelligentsia/tokbench) benchmark, where the
+~13-token re-read previously had to be verified by hand.
+
 ## pi-mcp-adapter compatibility
 
 If you prefer using [pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter) to manage your MCP servers, lean-ctx integrates automatically:
@@ -190,6 +240,8 @@ Use `/lean-ctx` in Pi to check:
 - Which binary is being used
 - MCP bridge status (disabled / embedded / adapter)
 - Active `ctx_` tool names
+- Coexistence info (#359): active tool prefix, tools handed to other extensions
+  (`Disabled`), and tools skipped due to a name already taken (`Skipped`)
 
 ## Disabling specific tools
 
@@ -205,6 +257,75 @@ Or via environment variable:
 LEAN_CTX_DISABLED_TOOLS=ctx_graph,ctx_benchmark pi
 ```
 
+## Coexisting with AFT and magic-context
+
+pi-lean-ctx is built to **stack** with other Pi extensions such as
+[AFT](https://github.com/cortexkit/aft) and
+[magic-context](https://github.com/cortexkit/magic-context) (issue #359).
+
+**No more load crashes.** If another extension already registered a tool name
+(e.g. magic-context's `ctx_expand`), pi-lean-ctx now **skips that tool with a
+warning** instead of crashing the whole agent. The rest of lean-ctx keeps
+working. Run `/lean-ctx` to see exactly which tools were skipped.
+
+### Hand tool names to another extension
+
+Use a deny-list so the other extension owns shared names while lean-ctx keeps
+its compression + session-cache core (`ctx_read`, `ctx_shell`, …):
+
+```bash
+# env: comma/space separated, case-insensitive
+export LEAN_CTX_PI_DISABLE_TOOLS="ctx_memory,ctx_expand,ctx_search"
+```
+
+…or in `~/.pi/agent/extensions/pi-lean-ctx/config.json` (merged with the env list):
+
+```json
+{
+  "disableTools": ["ctx_memory", "ctx_expand", "ctx_search"]
+}
+```
+
+> This is the **Pi-extension** deny-list — it controls which tools lean-ctx
+> registers *in Pi* (including its own `ctx_*` tools like `ctx_grep`). It is
+> separate from the engine-level `disabled_tools` / `LEAN_CTX_DISABLED_TOOLS`,
+> which hides tools from the MCP server itself.
+
+### Or namespace them with a prefix
+
+Keep every tool but expose the bridge tools under your own prefix, so nothing
+collides and small models see no duplicate names:
+
+```bash
+export LEAN_CTX_PI_TOOL_PREFIX="lc_"   # ctx_expand → lc_ctx_expand
+```
+
+The signature tools (`ctx_read`, `ctx_shell`, `ctx_ls`, `ctx_find`, `ctx_grep`)
+keep their stable names; only the bridge-discovered MCP tools are prefixed.
+
+### Curated profile (recommended division of labor)
+
+| Concern | Owner | Why |
+|---------|-------|-----|
+| File reads, shell, grep/find/ls — **compression + session cache** | **lean-ctx** | ~13-token re-reads, 60–90% savings on every read/shell |
+| **Long-horizon memory** (`ctx_memory`, `ctx_expand`) | magic-context | purpose-built long-term memory |
+| **Symbol-aware file ops** (`aft_*`) | AFT | precise AST edits |
+
+Copy-paste config for the profile above
+(`~/.pi/agent/extensions/pi-lean-ctx/config.json`):
+
+```json
+{
+  "mode": "additive",
+  "enableMcp": true,
+  "disableTools": ["ctx_memory", "ctx_expand", "ctx_search"]
+}
+```
+
+Result: no duplicate search/memory tools in the tool list, no load crash, and
+each extension does what it is best at. Verify with `/lean-ctx`, which now lists
+the active prefix plus any handed-off (`Disabled`) and skipped tools.
+
 ## Links
 
 - [lean-ctx](https://leanctx.com) — the Cognitive Context Layer for AI coding agents

package/extensions/config.ts

@@ -15,7 +15,11 @@ import { resolve } from "node:path";
 export interface PiLeanCtxFileConfig {
   /** Tool exposure: "additive" (Pi builtins + ctx_*) or "replace" (ctx_* only). */
   mode?: string;
-  /** Start the embedded MCP bridge (equivalent to `LEAN_CTX_PI_ENABLE_MCP=1`). */
+  /**
+   * Start the embedded MCP bridge (the persistent session cache). Default
+   * `true`; set `false` (or `LEAN_CTX_PI_ENABLE_MCP=0`) to force the one-shot
+   * CLI path, which cannot cache across calls.
+   */
   enableMcp?: boolean;
   /** Absolute path to the lean-ctx binary (equivalent to `LEAN_CTX_BIN`). */
   binary?: string;
@@ -26,6 +30,22 @@ export interface PiLeanCtxFileConfig {
    * (e.g. `{ "LEAN_CTX_COMPRESSION": "aggressive" }`).
    */
   env?: Record<string, string>;
+  /**
+   * Tool names lean-ctx must NOT register, handing them to another Pi
+   * extension instead (issue #359). Use this when coexisting with
+   * magic-context / AFT so duplicate `ctx_memory` / `ctx_search` / `ctx_expand`
+   * tools don't confuse smaller models. Equivalent to
+   * `LEAN_CTX_PI_DISABLE_TOOLS` (the env list and this list are merged).
+   */
+  disableTools?: string[];
+  /**
+   * Optional prefix applied to bridge-registered MCP tools (e.g. `"lc_"` turns
+   * `ctx_expand` into `lc_expand`) to sidestep name collisions entirely while
+   * still exposing the tool (issue #359). The signature tools (`ctx_read`,
+   * `ctx_shell`, …) keep their stable names. Equivalent to
+   * `LEAN_CTX_PI_TOOL_PREFIX`.
+   */
+  toolPrefix?: string;
 }
 
 export type PiMode = "additive" | "replace";
@@ -38,6 +58,10 @@ export interface ResolvedPiConfig {
   binaryOverride?: string;
   /** Engine env overrides forwarded to lean-ctx subprocesses. */
   forwardedEnv: Record<string, string>;
+  /** Lower-cased tool names handed to other extensions / never registered (#359). */
+  disabledTools: Set<string>;
+  /** Optional prefix for bridge-registered MCP tools (#359). */
+  toolPrefix?: string;
   /** Absolute path the loader looked at (whether or not it existed). */
   configPath: string;
   /** True when the file existed and parsed into a JSON object. */
@@ -83,6 +107,42 @@ function resolveMode(fileMode: string | undefined): PiMode {
   return raw === "replace" ? "replace" : "additive";
 }
 
+/** Split a comma/whitespace-separated tool list into trimmed, non-empty names. */
+function parseToolList(raw: string | undefined): string[] {
+  if (!raw) return [];
+  return raw
+    .split(/[,\s]+/)
+    .map((t) => t.trim())
+    .filter((t) => t.length > 0);
+}
+
+/**
+ * Union of the file `disableTools` and the `LEAN_CTX_PI_DISABLE_TOOLS` env list,
+ * lower-cased. A deny-list is additive by nature, so both sources contribute
+ * (rather than env replacing file) — the intent is always "do not register X".
+ */
+function resolveDisabledTools(fileList: unknown): Set<string> {
+  const set = new Set<string>();
+  if (Array.isArray(fileList)) {
+    for (const t of fileList) {
+      if (typeof t === "string" && t.trim().length > 0) set.add(t.trim().toLowerCase());
+    }
+  }
+  for (const t of parseToolList(process.env.LEAN_CTX_PI_DISABLE_TOOLS)) {
+    set.add(t.toLowerCase());
+  }
+  return set;
+}
+
+/** Env `LEAN_CTX_PI_TOOL_PREFIX` wins over the file `toolPrefix`; empty ⇒ none. */
+function resolveToolPrefix(filePrefix: unknown): string | undefined {
+  const raw = process.env.LEAN_CTX_PI_TOOL_PREFIX
+    ?? (typeof filePrefix === "string" ? filePrefix : undefined);
+  if (typeof raw !== "string") return undefined;
+  const trimmed = raw.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
 /**
  * Loads and resolves the Pi override config. Precedence per setting is
  * "most explicit wins": an explicit `LEAN_CTX_PI_*` / `LEAN_CTX_BIN` env var
@@ -94,10 +154,15 @@ export function loadPiConfig(): ResolvedPiConfig {
   const configPath = piConfigPath();
   const { cfg, loaded } = readFileConfig(configPath);
 
+  // The embedded MCP bridge holds the persistent session cache, so unchanged
+  // re-reads cost ~13 tokens and reads register as CEP sessions. That is
+  // lean-ctx's core value prop, so the bridge is ON by default; the one-shot CLI
+  // path cannot cache across calls (#361). Opt out with LEAN_CTX_PI_ENABLE_MCP=0
+  // or "enableMcp": false in config.json.
   const enableMcp =
     process.env.LEAN_CTX_PI_ENABLE_MCP !== undefined
       ? envFlag("LEAN_CTX_PI_ENABLE_MCP")
-      : cfg.enableMcp === true;
+      : cfg.enableMcp !== false;
 
   const forwardedEnv: Record<string, string> = {};
   if (cfg.env && typeof cfg.env === "object" && !Array.isArray(cfg.env)) {
@@ -114,6 +179,8 @@ export function loadPiConfig(): ResolvedPiConfig {
     enableMcp,
     binaryOverride,
     forwardedEnv,
+    disabledTools: resolveDisabledTools(cfg.disableTools),
+    toolPrefix: resolveToolPrefix(cfg.toolPrefix),
     configPath,
     loaded,
   };

package/extensions/index.ts

@@ -224,6 +224,7 @@ function withFooter(text: string, opts?: {
   limit?: number;
   always?: boolean;
   preferEstimate?: boolean;
+  suppressIfNoSaving?: boolean;
 }) {
   const parsed = parseLeanCtxOutput(text);
   const limited = limitLines(parsed.text, opts?.limit);
@@ -238,6 +239,14 @@ function withFooter(text: string, opts?: {
   }
   if (!stats) return { text: limited.text, stats: undefined, truncated: limited.truncated };
 
+  // On tiny files compression cannot beat the envelope, so a "0%" footer would
+  // be pure overhead — larger payload than the source for no gain (#361). Keep
+  // the computed stats for telemetry (`details.compression`) but drop the
+  // visible footer when nothing was actually saved.
+  if (opts?.suppressIfNoSaving && stats.percentSaved <= 0) {
+    return { text: limited.text, stats, truncated: limited.truncated };
+  }
+
   const footer = formatFooter(stats);
   const base = limited.text.trimEnd();
   return {
@@ -327,6 +336,36 @@ export default async function (pi: ExtensionAPI) {
     });
   }
 
+  // Declared up-front so the ctx_read handler (registered below) can route
+  // through the embedded bridge once it connects. Assigned after the tools are
+  // registered (the bridge is started at the end of this function).
+  let mcpBridge: McpBridge | null = null;
+
+  // ── Collision-safe registration (#359) ───────────────────────────────────
+  // lean-ctx must coexist with other Pi extensions (AFT, magic-context). If a
+  // tool name is already claimed, skip it with a warning instead of letting the
+  // whole agent crash on load. Users can also hand a name to another extension
+  // via LEAN_CTX_PI_DISABLE_TOOLS / config.json `disableTools`. All ctx_* tools
+  // below register through this wrapper instead of pi.registerTool directly.
+  const skippedExtensionTools: string[] = [];
+  const disabledExtensionTools: string[] = [];
+  const registerTool = ((def: { name?: unknown }): void => {
+    const name = typeof def.name === "string" ? def.name : String(def.name);
+    if (PI_CONFIG.disabledTools.has(name.toLowerCase())) {
+      disabledExtensionTools.push(name);
+      return;
+    }
+    try {
+      (pi.registerTool as (d: unknown) => void)(def);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      skippedExtensionTools.push(name);
+      console.error(
+        `[pi-lean-ctx] Skipped tool "${name}" — already registered elsewhere? (${msg})`,
+      );
+    }
+  }) as unknown as ExtensionAPI["registerTool"];
+
   const baseBashTool = createBashToolDefinition(process.cwd(), {
     spawnHook: ({ command, cwd, env }) => {
       const bin = resolveBinary();
@@ -347,11 +386,11 @@ export default async function (pi: ExtensionAPI) {
   });
 
   // ── ctx_shell (replaces bash) ─────────────────────────────────────────
-  pi.registerTool({
+  registerTool({
     name: "ctx_shell",
     label: "ctx_shell",
     description:
-      "Execute a shell command. Output is auto-compressed by lean-ctx. "
+      "Run shell commands. Prefer over native Bash/shell (auto-compressed output). "
       + "IMPORTANT: Do NOT use ctx_shell to read files (cat/head/tail) — use ctx_read instead. "
       + "Do NOT use ctx_shell for grep/find/ls — use ctx_grep, ctx_find, ctx_ls. "
       + "Set raw=true to skip compression when exact output matters. "
@@ -408,14 +447,15 @@ export default async function (pi: ExtensionAPI) {
   // ── ctx_read (replaces read) ──────────────────────────────────────────
   const nativeReadTool = createReadToolDefinition(process.cwd());
 
-  pi.registerTool({
+  registerTool({
     name: "ctx_read",
     label: "ctx_read",
     description:
-      "Read file contents. ALWAYS use ctx_read instead of cat/head/tail via ctx_shell. "
+      "Read a file. Prefer over native Read/cat/head/tail (cached, compressed). "
+      + "Unchanged re-reads cost ~13 tokens. "
       + "Auto-selects mode: configs (.yaml/.json/.toml/.env) are always full-read. "
       + "Code files: full (<8KB), map (8-96KB), signatures (>96KB). "
-      + "Add mode=full to get complete file content (bypasses cache). "
+      + "Add mode=full to get complete file content. "
       + "Use offset and limit to read specific line ranges.",
     promptSnippet: "Read file contents (always use instead of cat)",
     promptGuidelines: [
@@ -491,14 +531,31 @@ export default async function (pi: ExtensionAPI) {
       if (params.offset !== undefined || params.limit !== undefined) {
         const startLine = params.offset ?? 1;
         const endLine = params.limit ? startLine + params.limit - 1 : 999999;
-        const args = ["read", absolutePath, "-m", `lines:${startLine}-${endLine}`];
+        const mode = `lines:${startLine}-${endLine}`;
+        // Route line-range reads through the bridge too, so re-reading the same
+        // slice hits the session cache instead of re-spawning a CLI per call (#361).
+        if (mcpBridge?.isConnected()) {
+          try {
+            const bridged = await mcpBridge.callTool("ctx_read", { path: absolutePath, mode }, signal);
+            const bridgedText = bridged.content.map((block) => block.text).join("");
+            const originalSlice = await readSlice(absolutePath, params.offset, params.limit);
+            const decorated = withFooter(bridgedText, { originalText: originalSlice.text, always: true, preferEstimate: true, suppressIfNoSaving: true });
+            return {
+              content: [{ type: "text", text: decorated.text }],
+              details: { path: absolutePath, lines: originalSlice.lines, source: "lean-ctx-bridge", mode, compression: decorated.stats },
+            };
+          } catch (err) {
+            console.error(`[pi-lean-ctx] ctx_read(${mode}) bridge call failed, falling back to CLI: ${err}`);
+          }
+        }
+        const args = ["read", absolutePath, "-m", mode];
         try {
           const output = await execLeanCtx(pi, args);
           const originalSlice = await readSlice(absolutePath, params.offset, params.limit);
-          const decorated = withFooter(output, { originalText: originalSlice.text, always: true, preferEstimate: true });
+          const decorated = withFooter(output, { originalText: originalSlice.text, always: true, preferEstimate: true, suppressIfNoSaving: true });
           return {
             content: [{ type: "text", text: decorated.text }],
-            details: { path: absolutePath, lines: originalSlice.lines, source: "lean-ctx", mode: `lines:${startLine}-${endLine}`, compression: decorated.stats },
+            details: { path: absolutePath, lines: originalSlice.lines, source: "lean-ctx", mode, compression: decorated.stats },
           };
         } catch {
           const sliced = await readSlice(absolutePath, params.offset, params.limit);
@@ -515,10 +572,37 @@ export default async function (pi: ExtensionAPI) {
 
       const isExplicitFull = params.mode === "full";
       const mode = params.mode ?? await chooseReadMode(absolutePath);
+
+      // When the embedded MCP bridge is connected, route the read through it so
+      // the persistent session cache engages: an unchanged re-read then costs
+      // ~13 tokens instead of the full file, and the read registers as a real
+      // CEP session (counted by `lean-ctx gain`). The one-shot CLI path below
+      // spawns a fresh `lean-ctx read` per call and therefore cannot cache
+      // across calls — it is used only as a fallback when the bridge is
+      // unavailable or errors.
+      if (mcpBridge?.isConnected()) {
+        try {
+          const bridged = await mcpBridge.callTool(
+            "ctx_read",
+            { path: absolutePath, mode, ...(isExplicitFull ? { fresh: true } : {}) },
+            signal,
+          );
+          const bridgedText = bridged.content.map((block) => block.text).join("");
+          const originalText = await readFile(absolutePath, "utf8");
+          const decorated = withFooter(bridgedText, { originalText, always: true, preferEstimate: true, suppressIfNoSaving: true });
+          return {
+            content: [{ type: "text", text: decorated.text }],
+            details: { path: absolutePath, source: "lean-ctx-bridge", mode, compression: decorated.stats },
+          };
+        } catch (err) {
+          console.error(`[pi-lean-ctx] ctx_read bridge call failed, falling back to CLI: ${err}`);
+        }
+      }
+
       const args = ["read", absolutePath, "-m", mode, ...(isExplicitFull ? ["--fresh"] : [])];
       const output = await execLeanCtx(pi, args);
       const originalText = await readFile(absolutePath, "utf8");
-      const decorated = withFooter(output, { originalText, always: true, preferEstimate: true });
+      const decorated = withFooter(output, { originalText, always: true, preferEstimate: true, suppressIfNoSaving: true });
 
       return {
         content: [{ type: "text", text: decorated.text }],
@@ -528,10 +612,10 @@ export default async function (pi: ExtensionAPI) {
   });
 
   // ── ctx_ls (replaces ls) ──────────────────────────────────────────────
-  pi.registerTool({
+  registerTool({
     name: "ctx_ls",
     label: "ctx_ls",
-    description: "List directory contents. Use limit to reduce output size.",
+    description: "List a directory. Prefer over native ls (compact, summarized). Use limit to reduce output size.",
     promptSnippet: "List directory contents",
     parameters: lsSchema,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -547,10 +631,10 @@ export default async function (pi: ExtensionAPI) {
   });
 
   // ── ctx_find (replaces find) ──────────────────────────────────────────
-  pi.registerTool({
+  registerTool({
     name: "ctx_find",
     label: "ctx_find",
-    description: "Find files by glob pattern (respects .gitignore). Use limit to reduce output size.",
+    description: "Find files by glob. Prefer over native find/fd (gitignore-aware). Use limit to reduce output size.",
     promptSnippet: "Find files by glob pattern",
     parameters: findSchema,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -566,10 +650,10 @@ export default async function (pi: ExtensionAPI) {
   });
 
   // ── ctx_grep (replaces grep) ──────────────────────────────────────────
-  pi.registerTool({
+  registerTool({
     name: "ctx_grep",
     label: "ctx_grep",
-    description: "Search file contents with ripgrep. Use limit to cap matches and context for surrounding lines.",
+    description: "Search code. Prefer over native Grep/ripgrep (compact, ranked). Use limit to cap matches, context for surrounding lines.",
     promptSnippet: "Search file contents for patterns",
     parameters: grepSchema,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -599,7 +683,7 @@ export default async function (pi: ExtensionAPI) {
   });
 
   // ── lean_ctx (CLI passthrough) ────────────────────────────────────────
-  pi.registerTool({
+  registerTool({
     name: "lean_ctx",
     label: "lean_ctx",
     description:
@@ -623,8 +707,11 @@ export default async function (pi: ExtensionAPI) {
   // is actually serving it — pi has no native MCP support, and `lean-ctx init
   // --agent pi` writes that entry by default — so it must not silently disable the
   // bridge a user explicitly requested via LEAN_CTX_PI_ENABLE_MCP=1 / enableMcp.
-  const mcpBridge = enableMcpBridge
-    ? new McpBridge(resolveBinary(), PI_CONFIG.forwardedEnv)
+  mcpBridge = enableMcpBridge
+    ? new McpBridge(resolveBinary(), PI_CONFIG.forwardedEnv, {
+        disabledTools: PI_CONFIG.disabledTools,
+        toolPrefix: PI_CONFIG.toolPrefix,
+      })
     : null;
 
   if (mcpBridge) {
@@ -676,6 +763,22 @@ export default async function (pi: ExtensionAPI) {
         }
       }
 
+      // Coexistence diagnostics (#359): the active prefix plus which tools we
+      // handed off or skipped, so a user stacking AFT / magic-context can see
+      // the exact split at a glance.
+      const skipped = [...(status?.skippedTools ?? []), ...skippedExtensionTools];
+      const disabled = [...(status?.disabledTools ?? []), ...disabledExtensionTools];
+      const prefix = status?.toolPrefix ?? PI_CONFIG.toolPrefix;
+      if (prefix) {
+        lines.push(`Tool prefix: "${prefix}" (bridge tools exposed as ${prefix}<name>)`);
+      }
+      if (disabled.length > 0) {
+        lines.push(`Disabled (handed to other extensions): ${disabled.join(", ")}`);
+      }
+      if (skipped.length > 0) {
+        lines.push(`Skipped (name already taken): ${skipped.join(", ")}`);
+      }
+
       // Show active ctx_ tools
       const ctxTools = pi.getActiveTools().filter((n) => n.startsWith("ctx_") || n === "lean_ctx");
       if (ctxTools.length > 0) {

package/extensions/mcp-bridge.ts

@@ -27,6 +27,20 @@ type McpTool = {
   inputSchema?: Record<string, unknown>;
 };
 
+/**
+ * How the bridge should expose discovered MCP tools, so lean-ctx can coexist
+ * with other Pi extensions (AFT, magic-context) instead of crashing on a name
+ * collision (issue #359).
+ */
+export type BridgeToolPolicy = {
+  /** Lower-cased tool names the bridge must not register at all. */
+  disabledTools: Set<string>;
+  /** Optional prefix applied to the Pi-facing tool name (not the MCP call). */
+  toolPrefix?: string;
+};
+
+const DEFAULT_TOOL_POLICY: BridgeToolPolicy = { disabledTools: new Set() };
+
 function isAbortLikeError(error: unknown): boolean {
   if (!(error instanceof Error)) return false;
   const msg = error.message.toLowerCase();
@@ -57,17 +71,25 @@ export class McpBridge {
   private client: Client | null = null;
   private transport: StdioClientTransport | null = null;
   private registeredTools: string[] = [];
+  private skippedTools: string[] = [];
+  private disabledToolNames: string[] = [];
   private connected = false;
   private binary: string;
   private extraEnv: Record<string, string>;
+  private policy: BridgeToolPolicy;
   private reconnectAttempts = 0;
   private lastError: string | undefined;
   private lastHungTool: string | undefined;
   private lastRetry: McpBridgeRetryState | undefined;
 
-  constructor(binary: string, extraEnv: Record<string, string> = {}) {
+  constructor(
+    binary: string,
+    extraEnv: Record<string, string> = {},
+    policy: BridgeToolPolicy = DEFAULT_TOOL_POLICY,
+  ) {
     this.binary = binary;
     this.extraEnv = extraEnv;
+    this.policy = policy;
   }
 
   async start(pi: ExtensionAPI): Promise<void> {
@@ -155,6 +177,10 @@ export class McpBridge {
 
     for (const tool of tools) {
       if (CLI_OVERRIDE_TOOLS.has(tool.name)) continue;
+      if (this.policy.disabledTools.has(tool.name.toLowerCase())) {
+        this.disabledToolNames.push(tool.name);
+        continue;
+      }
       this.registerMcpTool(pi, tool);
     }
   }
@@ -162,25 +188,41 @@ export class McpBridge {
   private registerMcpTool(pi: ExtensionAPI, tool: McpTool): void {
     const bridge = this;
     const schema = this.jsonSchemaToTypebox(tool.inputSchema);
+    // The prefix renames only the Pi-facing tool; the MCP call still targets
+    // the real `tool.name` captured in the closure below.
+    const exposedName = this.policy.toolPrefix
+      ? `${this.policy.toolPrefix}${tool.name}`
+      : tool.name;
 
-    pi.registerTool({
-      name: tool.name,
-      label: tool.name,
-      description: tool.description ?? `lean-ctx MCP tool: ${tool.name}`,
-      promptSnippet: tool.description ?? tool.name,
-      parameters: schema,
-      async execute(_toolCallId, params, signal, _onUpdate, _ctx) {
-        const result = await bridge.callTool(
-          tool.name,
-          params as Record<string, unknown>,
-          signal,
-        );
-        // Pi's AgentToolResult requires a `details` field; MCP tool output has none.
-        return { ...result, details: undefined };
-      },
-    });
-
-    this.registeredTools.push(tool.name);
+    try {
+      pi.registerTool({
+        name: exposedName,
+        label: exposedName,
+        description: tool.description ?? `lean-ctx MCP tool: ${tool.name}`,
+        promptSnippet: tool.description ?? tool.name,
+        parameters: schema,
+        async execute(_toolCallId, params, signal, _onUpdate, _ctx) {
+          const result = await bridge.callTool(
+            tool.name,
+            params as Record<string, unknown>,
+            signal,
+          );
+          // Pi's AgentToolResult requires a `details` field; MCP tool output has none.
+          return { ...result, details: undefined };
+        },
+      });
+      this.registeredTools.push(exposedName);
+    } catch (err) {
+      // Another extension (e.g. magic-context) already owns this name. Skip it
+      // and keep going so the whole agent doesn't crash on load (#359). Set a
+      // prefix (LEAN_CTX_PI_TOOL_PREFIX) or disable the tool to resolve cleanly.
+      const msg = err instanceof Error ? err.message : String(err);
+      this.skippedTools.push(exposedName);
+      console.error(
+        `[lean-ctx MCP bridge] Skipped tool "${exposedName}" — already registered by another extension? (${msg}). `
+          + "Set LEAN_CTX_PI_TOOL_PREFIX or add it to LEAN_CTX_PI_DISABLE_TOOLS to silence this.",
+      );
+    }
   }
 
   async callTool(
@@ -341,12 +383,20 @@ export class McpBridge {
     return Type.Object(fields);
   }
 
+  /** True when the MCP client is connected and able to serve tool calls. */
+  isConnected(): boolean {
+    return this.connected && this.client !== null;
+  }
+
   getStatus(): McpBridgeStatus {
     return {
       mode: "embedded",
       connected: this.connected,
       toolCount: this.registeredTools.length,
       toolNames: [...this.registeredTools],
+      skippedTools: [...this.skippedTools],
+      disabledTools: [...this.disabledToolNames],
+      toolPrefix: this.policy.toolPrefix,
       reconnectAttempts: this.reconnectAttempts,
       lastError: this.lastError,
       lastHungTool: this.lastHungTool,

package/extensions/types.ts

@@ -16,6 +16,12 @@ export type McpBridgeStatus = {
   connected: boolean;
   toolCount: number;
   toolNames: string[];
+  /** Tools skipped because another extension already claimed the name (#359). */
+  skippedTools: string[];
+  /** Tools not registered because the user disabled them via config (#359). */
+  disabledTools: string[];
+  /** Active prefix applied to bridge tool names, if any (#359). */
+  toolPrefix?: string;
   reconnectAttempts: number;
   lastError?: string;
   lastHungTool?: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-lean-ctx",
-  "version": "3.7.4",
-  "description": "Pi Coding Agent extension (CLI-first) \u2014 routes bash/read/grep/find/ls through lean-ctx CLI for strong token savings. Optional MCP bridge can register advanced tools.",
+  "version": "3.8.0",
+  "description": "Pi Coding Agent extension \u2014 routes bash/read/grep/find/ls through lean-ctx for strong token savings. The embedded MCP bridge (on by default) adds a persistent session cache so unchanged re-reads cost ~13 tokens.",
   "keywords": [
     "pi-package",
     "lean-ctx",