@herbertgao/pi-extensions 2026.9.2 → 2026.9.4

package/node_modules/pi-lens/dist/tools/render-compact.js

@@ -1,7 +1,7 @@
 // Compact tool-result rendering (refs #345).
 //
 // The navigable/structural tools (module_report, read_symbol, read_enclosing,
-// ast_grep_search, ast_grep_dump, ast_grep_outline) return large bodies that are
+// ast_grep_search, ast_grep_outline) return large bodies that are
 // useful to the MODEL but flood the user's terminal. The pi host renders a tool's
 // `content` verbatim only when the tool defines no `renderResult` (the
 // createResultFallback path in tool-execution.ts). By supplying a `renderResult`
@@ -19,6 +19,285 @@
 // (overrideExistingRenderers === false), so these renderers win and still coexist
 // with a globally-installed renderer extension.
 import { Text } from "../clients/deps/pi-tui.js";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+import { recordDegradationOnce } from "../clients/degradation-ledger.js";
+import { getGlobalPiLensLogDir } from "../clients/probe-home-state.js";
+/** The per-result delivery bound (#2848). Exported so surface gates and their
+ * pins assert the real budget instead of restating the literal. */
+export const MAX_RESULT_BYTES = 40 * 1024;
+// 2026-09-10: cap the complete MCP payload before it can retain or log an
+// unbounded result; ordinary results keep the complete-log contract below it.
+export const COMPLETE_MCP_RESULT_INPUT_BUDGET_BYTES = 8 * 1024 * 1024;
+// #2800 item 7: the footer is stamped AFTER the payload bound, so the
+// footer's own maximum size is reserved inside MAX_RESULT_BYTES. The reserve
+// is computed from the footer's widest literal: the `result error` verdict, a
+// bounded diag severity section, and maximum-width numeric fields with the
+// wider `truncated=false` value.
+const FOOTER_MAX_DIGITS = String(Number.MAX_SAFE_INTEGER).length;
+/** One `diag severity=` line is width-bounded so the footer's maximum size
+ * stays finite and the reserve above stays sound. */
+const FOOTER_DIAG_LINE_MAX_CHARS = 200;
+const FOOTER_DIAG_SECTION_MAX_BYTES = 1024;
+export const RESULT_FOOTER_RESERVE_BYTES = Buffer.byteLength(`\n\nresult error\n${"x".repeat(FOOTER_DIAG_SECTION_MAX_BYTES)}\nusage tokens=${"9".repeat(FOOTER_MAX_DIGITS)} elapsed-ms=${"9".repeat(FOOTER_MAX_DIGITS)} bytes=${"9".repeat(FOOTER_MAX_DIGITS)} truncated=false`, "utf8");
+// The literal reserve intentionally leaves about 1 KiB below MAX_RESULT_BYTES
+// for footer growth. Keep this conservative slack: deriving the bound by
+// iterating over a changing footer caused both overflows and repeated log writes
+// (round 2 F2/F7, refs #2862 and #2864).
+/** The payload byte budget the footer is stamped into: the delivered result
+ * budget minus the reserved footer maximum (#2800 item 7). */
+export const RESULT_PAYLOAD_BUDGET_BYTES = MAX_RESULT_BYTES - RESULT_FOOTER_RESERVE_BYTES;
+function renderHeadTail(text, maxBytes, markerFor) {
+    const render = (kept) => {
+        const head = Math.floor(kept / 2);
+        const tail = kept - head;
+        return `${text.slice(0, head)}${markerFor(head, tail)}${text.slice(text.length - tail)}`;
+    };
+    let low = 0;
+    let high = text.length;
+    while (low < high) {
+        const kept = Math.ceil((low + high) / 2);
+        if (Buffer.byteLength(render(kept), "utf8") <= maxBytes)
+            low = kept;
+        else
+            high = kept - 1;
+    }
+    return { text: render(low), keptCharacters: low };
+}
+/** Bound model-facing result text while retaining both the useful head and tail.
+ * `maxBytes` defaults to the full result budget; the footer gate passes the
+ * payload budget that leaves room for the stamped footer (#2800 item 7). */
+export function boundToolText(text, maxBytes = MAX_RESULT_BYTES) {
+    const totalBytes = Buffer.byteLength(text, "utf8");
+    if (totalBytes <= maxBytes) {
+        return { text, truncated: false, omittedCharacters: 0 };
+    }
+    const fullOutputPath = path.join(getGlobalPiLensLogDir(), `tool-result-${Date.now()}-${randomUUID()}.log`);
+    fs.mkdirSync(path.dirname(fullOutputPath), { recursive: true });
+    if (totalBytes > COMPLETE_MCP_RESULT_INPUT_BUDGET_BYTES) {
+        const omittedBytes = totalBytes - COMPLETE_MCP_RESULT_INPUT_BUDGET_BYTES;
+        recordDegradationOnce({
+            kind: "mcp-complete-result-budget-exceeded",
+            subject: "complete-result",
+            reason: `${totalBytes} input bytes exceeded ${COMPLETE_MCP_RESULT_INPUT_BUDGET_BYTES}-byte budget`,
+            metadata: {
+                totalBytes,
+                budgetBytes: COMPLETE_MCP_RESULT_INPUT_BUDGET_BYTES,
+            },
+        });
+        const logText = renderHeadTail(text, COMPLETE_MCP_RESULT_INPUT_BUDGET_BYTES, (head, tail) => {
+            const keptBytes = Buffer.byteLength(`${text.slice(0, head)}${text.slice(text.length - tail)}`, "utf8");
+            return `\n\n[incomplete: ${totalBytes - keptBytes} bytes omitted, budget ${COMPLETE_MCP_RESULT_INPUT_BUDGET_BYTES}]\n\n[Full output: ${fullOutputPath}]\n\n`;
+        });
+        fs.writeFileSync(fullOutputPath, logText.text, "utf8");
+        const output = renderHeadTail(logText.text, maxBytes, () => `\n\n[incomplete: ${omittedBytes} bytes omitted, budget ${COMPLETE_MCP_RESULT_INPUT_BUDGET_BYTES}]\n\n[Full output: ${fullOutputPath}]\n\n`);
+        return {
+            text: output.text,
+            truncated: true,
+            omittedCharacters: text.length - logText.keptCharacters,
+            fullOutputPath,
+        };
+    }
+    fs.writeFileSync(fullOutputPath, text, "utf8");
+    const output = renderHeadTail(text, maxBytes, (head, tail) => `\n\n[${text.length - head - tail} characters omitted. Full output: ${fullOutputPath}]\n\n`);
+    return {
+        text: output.text,
+        truncated: true,
+        omittedCharacters: text.length - output.keptCharacters,
+        fullOutputPath,
+    };
+}
+/** Matches an already-stamped contract footer at the end of the joined text.
+ * A result re-entering the gate must not gain a second footer (refs #2852 N4).
+ * The byte and truncated groups let the gate read the kept footer's own
+ * delivery figures on re-entry (round 2 F1). */
+const CONTRACT_FOOTER_TAIL_RE = /(?:^|\n)result (?:ok|error)\n(?:diag severity=[^\n]*\n)*usage tokens=\d+ elapsed-ms=\d+ bytes=(\d+) truncated=(true|false)$/;
+/**
+ * Add the stable, model-facing result footer shared by pi and MCP.
+ *
+ * The host adapters own transport and terminal styling; this function owns the
+ * textual contract. Defaults are deliberately deterministic because elapsed
+ * time is not a property of a projection and must not make parity tests flaky.
+ * Idempotent: a result whose text already ends with the footer is only
+ * `isError`-normalized, never stamped twice.
+ *
+ * When `delivery` is given (the gate path), `bytes=`/`truncated=` describe the
+ * already-bound payload; otherwise they describe this function's input text,
+ * which is the delivered payload because no bound has run.
+ */
+export function renderToolResultContract(result, delivery) {
+    const normalized = {
+        ...result,
+        isError: result.isError === true,
+    };
+    const content = result.content ?? [];
+    const textBlocks = content
+        .filter((block) => block.type === "text" && typeof block.text === "string")
+        .map((block) => block.text);
+    if (textBlocks.length === 0)
+        return normalized;
+    const text = textBlocks.join("\n");
+    if (CONTRACT_FOOTER_TAIL_RE.test(text))
+        return normalized;
+    const details = normalized.details;
+    // The diag section is width- and byte-bounded (#2800 item 7) so the
+    // footer's maximum size — and therefore the reserved budget above — stays
+    // finite regardless of how many diagnostics a result carries.
+    const diagLines = [];
+    let diagSectionBytes = 0;
+    if (Array.isArray(details?.diagnostics)) {
+        for (const value of details.diagnostics) {
+            if (!value || typeof value !== "object")
+                continue;
+            const severity = value.severity;
+            if (typeof severity !== "string")
+                continue;
+            const line = `diag severity=${severity.slice(0, FOOTER_DIAG_LINE_MAX_CHARS)}`;
+            const lineBytes = Buffer.byteLength(line, "utf8") + 1;
+            if (diagSectionBytes + lineBytes > FOOTER_DIAG_SECTION_MAX_BYTES)
+                break;
+            diagLines.push(line);
+            diagSectionBytes += lineBytes;
+        }
+    }
+    const tokens = normalized.usage?.tokens ?? Math.ceil(Buffer.byteLength(text, "utf8") / 4);
+    const elapsedMs = normalized.usage?.elapsedMs ?? 0;
+    const deliveredBytes = delivery?.bytes ?? Buffer.byteLength(text, "utf8");
+    const truncated = delivery?.truncated === true;
+    const contractLines = [
+        `result ${normalized.isError ? "error" : "ok"}`,
+        ...diagLines,
+        `usage tokens=${tokens} elapsed-ms=${elapsedMs} bytes=${deliveredBytes} truncated=${truncated ? "true" : "false"}`,
+    ];
+    let lastTextIndex = -1;
+    for (let index = content.length - 1; index >= 0; index--) {
+        const block = content[index];
+        if (block?.type === "text" && typeof block.text === "string") {
+            lastTextIndex = index;
+            break;
+        }
+    }
+    if (lastTextIndex < 0)
+        return normalized;
+    return {
+        ...normalized,
+        content: content.map((block, index) => index === lastTextIndex && block.type === "text"
+            ? { ...block, text: `${block.text}\n\n${contractLines.join("\n")}` }
+            : block),
+    };
+}
+/** Bound the payload text blocks so the footer stamped afterwards still fits
+ * inside MAX_RESULT_BYTES (refs #2800 item 7): each block is bounded to the
+ * result budget minus the reserved footer maximum, and the delivered byte
+ * count plus the bound's truncated flag travel with the result so the footer
+ * can report them. Per-block bounding is inherited from #2852; production
+ * results carry a single text block (renderToolText). */
+export function boundResultPayload(result) {
+    if (!result.content) {
+        return { result, deliveredBytes: 0, truncated: false };
+    }
+    const joined = fullTextOf(result);
+    // Reserve the widest footer once. This keeps the MAX_RESULT_BYTES invariant
+    // independent of payload contents and gives boundToolText one log write.
+    const bound = boundToolText(joined, RESULT_PAYLOAD_BUDGET_BYTES);
+    const firstText = result.content.findIndex((block) => block.type === "text" && typeof block.text === "string");
+    let retainedText = false;
+    const content = result.content
+        .filter((block, index) => block.type !== "text" ||
+        typeof block.text !== "string" ||
+        index === firstText)
+        .map((block) => {
+        if (block.type === "text" &&
+            typeof block.text === "string" &&
+            !retainedText) {
+            retainedText = true;
+            return { ...block, text: bound.text };
+        }
+        return block;
+    });
+    const deliveredBytes = Buffer.byteLength(fullTextOf({ content }), "utf8");
+    return {
+        result: { ...result, content },
+        deliveredBytes,
+        truncated: bound.truncated,
+    };
+}
+/** Build the raw result envelope shared by both host adapters: the summary is
+ * joined with the structured payload's fenced JSON, and the payload also rides
+ * along as `details` for surface-side consumers (pi's compact-line summarizer,
+ * the MCP gate's `diag severity=` footer lines). The contract footer and the
+ * #2848 byte bound are NOT applied here — each surface stamps them once, after
+ * the tool's own result exists (`finalizeToolResult` / the MCP dispatcher). */
+export function renderToolText(summary, structured, compact = false) {
+    const rawText = structured === undefined
+        ? summary
+        : `${summary}\n\n\`\`\`json\n${JSON.stringify(structured, compact ? undefined : null, compact ? undefined : 2)}\n\`\`\``;
+    return {
+        content: [{ type: "text", text: rawText }],
+        details: structured,
+    };
+}
+/** Drop the structured `details` field from a finished result. The MCP gate
+ * consumes `details` for the footer's `diag severity=` lines and then strips
+ * it before delivery, so the wire carries only the bounded text blocks
+ * (refs #2852 N1); pi keeps `details` for its compact-line summarizer. */
+export function stripResultDetails(result) {
+    const { details: _details, ...rest } = result;
+    return rest;
+}
+/** Finish a host-adapter result after its status and all warnings exist
+ * (#2800 item 7): the payload bound runs FIRST with the footer's own maximum
+ * size reserved inside MAX_RESULT_BYTES, then the footer is stamped LAST with
+ * the delivered payload's byte count and the bound's truncated flag. So
+ * `bytes=`/`truncated=` describe what the model actually receives, and the
+ * delivered text — footer included — never exceeds MAX_RESULT_BYTES.
+ *
+ * Re-entry (refs #2852 N4, round 2 F1): the bound still runs on an
+ * already-stamped result — master applied the bound after the stamp-skip, and
+ * the kept tail carries the footer through it — so re-entry is never delivered
+ * unbounded. A stamped result within the delivered budget is kept as-is; the
+ * figures are the kept footer's own prior values, never a footer-inclusive
+ * re-measure and never a hard-coded `false`. */
+export function finalizeToolResultWithDelivery(result) {
+    const normalized = { ...result, isError: result.isError === true };
+    const existingText = fullTextOf(normalized);
+    const existingFooter = CONTRACT_FOOTER_TAIL_RE.exec(existingText);
+    if (existingFooter &&
+        Buffer.byteLength(existingText, "utf8") <= MAX_RESULT_BYTES) {
+        return {
+            result: normalized,
+            deliveredBytes: Number(existingFooter[1]),
+            truncated: existingFooter[2] === "true",
+        };
+    }
+    const bound = boundResultPayload(normalized);
+    const text = fullTextOf(bound.result);
+    const keptFooter = CONTRACT_FOOTER_TAIL_RE.exec(text);
+    if (keptFooter) {
+        // The bound ran and the kept tail still carries the footer, so there is
+        // nothing to stamp; the kept footer's figures stay the delivery
+        // contract (row 6: prior value kept).
+        return {
+            result: bound.result,
+            deliveredBytes: Number(keptFooter[1]),
+            truncated: keptFooter[2] === "true",
+        };
+    }
+    const stamped = renderToolResultContract(bound.result, {
+        bytes: bound.deliveredBytes,
+        truncated: bound.truncated,
+    });
+    return {
+        result: stamped,
+        deliveredBytes: bound.deliveredBytes,
+        truncated: bound.truncated,
+    };
+}
+/** Finish a host-adapter result after its status and all warnings exist. */
+export function finalizeToolResult(result) {
+    return finalizeToolResultWithDelivery(result).result;
+}
 // pi-lens brand colour: blue characters on whatever background the pi tool shell
 // paints (default success/error background is left untouched). Truecolor bold
 // foreground, theme-independent so the summary reads as ours regardless of the

package/node_modules/pi-lens/dist/tools/symbol-search.js

@@ -23,8 +23,8 @@ export function createSymbolSearchTool(getProjectRoot) {
     return {
         name: "symbol_search",
         label: "Symbol Search",
-        description: "Ranked identifier search over the persisted word index (BM25 + priors demoting tests/vendor/docs) — answers 'which files are most relevant to <query>' by identifier. First step of the discovery funnel: symbol_search finds candidates, module_report explains the file, read_symbol reads the body. Complements grep (raw substrings) and lsp_navigation (exact references). Each hit's startLine/endLine mark its best-matching line (offset=startLine, limit=endLine-startLine+1 for a one-line peek); use module_report on `file` for the real outline. Returns available:false with a retry hint if the index isn't built yet — it self-builds in the background (never blocks this call).",
-        promptSnippet: "Ranked identifier search — find relevant files by name/usage",
+        description: "Find relevant files by ranked identifier search. On a cold cache, project_report and symbol_search return available: false with a retry hint and start a non-blocking background build; module_report degrades to outline-only with cache freshness explicit. Example: search `authenticate user` before module_report.",
+        promptSnippet: "Find files by identifier",
         renderResult: compactRenderResult(({ details, isError }) => {
             if (isError || details?.available === false) {
                 return `symbol_search "${details?.query ?? ""}" — unavailable${details?.hint ? `: ${details.hint}` : ""}`;

package/node_modules/pi-lens/docs/agent-guide.md

@@ -278,8 +278,7 @@ Registered as pi agent tools. Verified names:
 
 | Tool | What it does | Use it to… |
 |---|---|---|
-| `lens_diagnostics` | Query pi-lens diagnostic state. `mode=delta` (default, this turn) / `mode=all` (cache-wide) / `mode=full` (fresh whole-project scan). Optional `paths` scope. | Check what pi-lens found; confirm clean before "done" (use `mode=full`). |
-| `lsp_diagnostics` | LSP diagnostics for explicit files/dirs (per-file `clean`/`unavailable`/`unconfirmed`/… outcomes). | Targeted LSP check on specific files. |
+| `lens_diagnostics` | Session-cache or LSP-probe diagnostics with `source` and `scope` selectors. | Use `source=lsp` with `scope=paths` for targeted checks; an empty cache is not proof of clean. |
 | `lsp_navigation` | LSP navigation (definition/references/etc.). | Trace symbols semantically. |
 | `symbol_search` | Ranked identifier search over the warm word index (BM25 + priors). | Entry point of the discovery funnel. |
 | `module_report` | Navigable outline + signatures + decorators + imports + callbacks for a file; optional `blastRadius`. | Understand a module without reading the whole body. |
@@ -287,7 +286,7 @@ Registered as pi agent tools. Verified names:
 | `read_enclosing` | Smallest enclosing symbol/callback body for a file+line (records coverage). | Bridge a diagnostic location → exact body. |
 | `project_report` | Project-level structural report. | Orient in an unfamiliar project. |
 | `ast_grep_search` / `ast_grep_replace` | Structural AST search / replace. | Find or rewrite by code shape, not regex. |
-| `ast_grep_outline` / `ast_grep_dump` | Outline / AST dump. | Inspect structure. |
+| `ast_grep_outline` / `ast_grep_search` (`dump=true`) | Outline / AST dump. | Inspect structure. |
 | `lens_diagnostic_mark` | Mark a finding false-positive / suppressed / deferred / flagged-to-fix (honored across surfaces). | Triage a finding you've judged. |
 
 Funnel discipline: **`symbol_search` → `module_report` → `read_symbol`/`read_enclosing`**
@@ -315,7 +314,7 @@ pi-lens is also an MCP server. The same capabilities are mirrored under a `pilen
 prefix: `pilens_diagnostics`, `pilens_analyze`, `pilens_module_report`,
 `pilens_symbol_search`, `pilens_read_symbol`, `pilens_read_enclosing`,
 `pilens_project_report`, `pilens_project_scan`, `pilens_lsp_navigation`,
-`pilens_lsp_diagnostics`, `pilens_ast_grep_search`/`pilens_ast_grep_replace`,
+`pilens_ast_grep_search`/`pilens_ast_grep_replace`,
 `pilens_session_start`/`pilens_turn_end`, `pilens_health`, `pilens_latency`,
 `pilens_rebuild` (source checkouts only). Note MCP has **no read-guard** — mirror reads
 don't record edit coverage. Prefer the **warm** review path; MCP `fresh` mode

package/node_modules/pi-lens/docs/agent-tools.md

@@ -2,43 +2,67 @@
 
 pi-lens registers the following tools with the pi agent. Most are also exposed
 through the MCP mirror (`clients/lens-engine.ts` is the seam both adapters
-share) — current exceptions: `ast_grep_outline` and `ast_grep_dump`
+share) — current exception: `ast_grep_outline`
 (module_report supersedes them for discovery), and `lens_diagnostic_mark`
 (pi-lens-internal for now). `read_enclosing` gained MCP parity
-(`pilens_read_enclosing`) as of #536, closing #522 item 1.
+(`pilens_read_enclosing`) as of #536, closing #522 item 1. The standalone
+`lsp_diagnostics` tool was folded into `lens_diagnostics` (`source=lsp`,
+#2860). The retired MCP name remains a one-release compatibility redirect to
+`pilens_diagnostics` with `source=lsp` and `scope=paths` (`mcp/server.ts`),
+logging one `lsp-diagnostics-compatibility` degradation per session. Callers
+should move to `pilens_diagnostics`.
 
-**Dynamic tooling.** Six tools stay always-active: `lens_diagnostics`,
-`lsp_diagnostics`, `module_report`, `read_symbol`, `read_enclosing`,
-`symbol_search`. Six situational tools — `ast_grep_search`, `ast_grep_replace`,
-`ast_grep_outline`, `ast_grep_dump`, `lsp_navigation`, `lens_diagnostic_mark` —
+
+**Dynamic tooling.** Five tools stay always-active: `lens_diagnostics`,
+	`module_report`, `read_symbol`, `read_enclosing`,
+`symbol_search`. Five situational tools — `ast_grep_search`, `ast_grep_replace`,
+`ast_grep_outline`, `lsp_navigation`, `lens_diagnostic_mark` —
 are registered but
 inactive by default; the model activates the ones it needs via the always-active
 loader tool `pi_lens_activate_tools`, per pi's dynamic-tool-loading API
 (`pi.setActiveTools`/`pi.getActiveTools`). The loader explicitly reports
 "Available starting next turn"; do not retry the tool in the same turn.
-Feature-detected: on hosts without that API, the six situational tools fall back
+Feature-detected: on hosts without that API, the five situational tools fall back
 to being statically active, exactly as before (`tools/activate-tools.ts`, wired
 in `index.ts`).
 
+Tool descriptions contain the contract sentence and one example. Operational
+guidance, including cache state, scan scope, safety details, and lifecycle
+results, belongs in the returned result so it is paid only when the tool runs.
+
+**Result contract.** One post-result gate per surface — `finalizeToolResult` /
+`finalizeToolResultWithDelivery` in `tools/render-compact.ts`, wired into every
+pi tool's `execute` wrapper in `index.ts` and into the MCP `tools/call`
+dispatcher in `mcp/server.ts` — bounds every delivered result to 40 KiB
+(`MAX_RESULT_BYTES`) and stamps a trailing usage footer describing what was
+actually sent: `usage tokens=<n> elapsed-ms=<n> bytes=<n> truncated=<true|false>`.
+A rejected call (e.g. MCP's "Unknown or disabled tool") is rendered through the
+same gate rather than bypassing it.
+
 ## Per-edit
 
-- **`lens_diagnostics`** — Cached diagnostic state for the current session.
-  Modes: `delta` (current turn), `all` (resurfaces stale blockers dropped from
-  turn context), `full` (project-wide scan).
+- **`lens_diagnostics`** — Session-cache or LSP-probe diagnostic state, selected
+  by `source` (`session` default, or `lsp`) and `scope` (`paths` or
+  `workspace`; explicit `paths` always win over `scope`). `severity` is a
+  threshold, not an exact filter: `error` shows only errors; `warning` adds
+  warnings; `information` adds information; `hint`/`all` (default) show every
+  tier. Legacy `mode`: `delta` (current turn), `all` (resurfaces stale
+  blockers dropped from turn context), `full` (project-wide scan).
 - **`lens_diagnostic_mark`** — Triage a diagnostic: `false-positive` /
   `suppress` (writes an inline `pi-lens-ignore` comment) / `defer`
   (session-only) / `flagged` (persists, rendered `📌 flagged-to-fix`).
   Content-anchored so marks survive edits; every mark is logged and published
   on the bus. See [dispositions.md](dispositions.md).
-- **`lsp_diagnostics`** — File- or directory-scoped LSP diagnostics via the
-  active language server.
-- **`lsp_navigation`** — IDE-style navigation: `definition`, `references`,
-  `implementation`, `typeDefinition`, `declaration`, `rename`, `rename_file`,
-  `hover`, `documentSymbol`, `workspaceSymbol`, `signatureHelp`,
-  `prepareCallHierarchy`, `incomingCalls`, `outgoingCalls`, `executeCommand`,
-  and `capabilities`. Position-based operations accept a `path`/`line`/`character`
-  triple. `documentSymbol` accepts a `kinds` filter (e.g. `function`, `class`)
-  and a `maxResults` cap (default 20, max 100) to keep large files bounded.
+- **`lsp_navigation`** — IDE-style navigation, 19 operations: `definition`,
+  `typeDefinition`, `declaration`, `references`, `hover`, `signatureHelp`,
+  `documentSymbol`, `findSymbol`, `workspaceSymbol`, `codeAction`, `rename`,
+  `rename_file`, `implementation`, `prepareCallHierarchy`, `incomingCalls`,
+  `outgoingCalls`, `executeCommand`, `workspaceDiagnostics`, and `capabilities`
+  (`tools/lsp-navigation.ts` operation description). Position-based operations
+  accept a `path`/`line`/`character` triple. `documentSymbol` accepts a `kinds`
+  filter (e.g. `function`, `class`) and a `maxResults` cap (default 20, max 100)
+  to keep large files bounded. Full per-operation parameter reference:
+  [skills/pi-lens-lsp-navigation/SKILL.md](../skills/pi-lens-lsp-navigation/SKILL.md).
 - **`ast_grep_search`** — AST-aware structural search across ~40 languages via
   the `sg` CLI. Supports metavariables (`$VAR`, `$$$ARGS`), `strictness`
   modes (`smart`, `relaxed`, `ast`, `cst`, `signature`, `template`), structural
@@ -48,7 +72,7 @@ in `index.ts`).
   (per-call cap, default 50, max 200; also sets the pagination step).
   `nodeKind` is an expert grammar-specific escape hatch: it finds every node of
   the exact kind used by the target grammar. Node kinds are not universal across
-  languages; use `ast_grep_dump` to discover the kind in the target language. It is mutually exclusive with `pattern` and `rule`.
+  languages; use `dump=true` with the representative snippet in `pattern` to discover the kind in the target language. It is mutually exclusive with `rule`.
   `hasKind` retains ast-grep's immediate-child semantics; use
   `hasDescendantKind` for an explicit recursive descendant search. A future
   canonical `find`/`query` facade (call/function/import/etc.) should map to
@@ -60,11 +84,11 @@ in `index.ts`).
   searches. `pattern` is optional when a `rule` or `nodeKind` is given.
   Results include `details.matchLocations[]` — each hit carries a ready
   `readSlice` (`path`/`offset`/`limit`) for a bounded context read; zero-match
-  results include a `suggestedDump` hint pointing at `ast_grep_dump`.
+  results include a `suggestedDump` hint pointing at `ast_grep_search` with `dump=true`.
 - **`ast_grep_replace`** — AST-aware structural replace. Re-validates the pattern
   against the current file before writing and reports a clear error if the
   file changed since the preview.
-- **`ast_grep_dump`** — Dumps the raw tree-sitter AST for a source snippet. Use
+- **`ast_grep_search` with `dump=true`** — Dumps the raw tree-sitter AST for a source snippet. Use
   this when an `ast_grep_search` or `ast_grep_replace` pattern returns zero
   matches and the correct node kind or field name is unknown. `includeAnonymous`
   shows punctuation/CST nodes.

package/node_modules/pi-lens/docs/configuration.md

@@ -36,6 +36,15 @@ everything LSP-related lives under an `lsp` namespace inside them.
 }
 ```
 
+Each model-facing tool accepts `tools.<name>.enabled` in the config file. Valid
+names include `ast_grep_search`, `ast_grep_replace`, `ast_grep_outline`,
+`lsp_navigation`, `lens_diagnostics`,
+`lens_diagnostic_mark`, `symbol_search`, `module_report`, `project_report`,
+`read_symbol`, `read_enclosing`, `effective_config`, `analyze`, `health`,
+`latency`, `project_scan`, and `rebuild`. The activation loader and MCP
+lifecycle tools `session_start`, `turn_end`, and `session_end` remain enabled
+because their host protocols require them.
+
 **Some settings are global-only.** A handful of switches — `lsp.enabled`
 (`--no-lsp`), `tests.enabled`, `delta.enabled` and the other session-wide
 toggles — are decided once for the machine, not per project, so writing one in a

package/node_modules/pi-lens/docs/environment-variables.md

@@ -123,11 +123,6 @@ the `dispatch.runnerTimeoutFloorMs` config key, which wins when both are set.
 
 ## Install control
 
-### `PI_LENS_AUTO_INSTALL`
-
-Set to `1` to auto-approve tool installs non-interactively (same as
-`--auto-install`). Off by default — installs prompt interactively.
-
 ### `PI_LENS_DISABLE_LSP_INSTALL`
 
 Set to `1` to skip auto-installing language servers. Off by default.

package/node_modules/pi-lens/docs/features.md

@@ -12,20 +12,20 @@ pi-lens includes **45 language server definitions** (including four cross-cuttin
 { "warmFiles": ["src/main.cpp", "src/lib.cpp"] }
 ```
 
-**Agent LSP tools:** `lsp_diagnostics` can check one file, a directory, or an explicit `filePaths` batch with bounded concurrency. `lsp_navigation` provides definitions, references, hover, workspace symbols, call hierarchy, rename edits, and `findSymbol` for filtered document-symbol lookup. Key operations:
+**Agent LSP tools:** `lens_diagnostics` with `source=lsp` can check one file, a directory, or explicit paths with bounded concurrency. `lsp_navigation` provides definitions, references, hover, workspace symbols, call hierarchy, rename edits, and `findSymbol` for filtered document-symbol lookup. Key operations:
 
 - **`rename`** — renames a symbol across all references; `apply: true` writes workspace edits to disk with per-file LSP re-sync.
 - **`rename_file`** — LSP-aware file rename: sends `workspace/willRenameFiles` to collect import-path rewrites, applies them, renames the file on disk, and notifies servers via `workspace/didRenameFiles`. `apply: false` previews the workspace edits without touching the filesystem.
 - **`capabilities`** — shows which operations are supported by the active LSP server(s) for a file, read directly from the cached `initialize` response (no round-trip).
 - **Symbol column resolution** — passing `symbol: "myFunc"` instead of an exact `character` position resolves the correct column automatically. Use `symbol: "foo#2"` for the second occurrence of `foo` on the line.
 
-LSP servers for: TypeScript, Deno, Python (pyright/basedpyright + jedi), Go, Rust, Ruby (ruby-lsp + solargraph), PHP, C# (omnisharp), F#, Java (JDT LS, with Lombok javaagent support when a Lombok jar is available), Kotlin, Swift, Dart, Lua, C/C++, Zig, Haskell, Elixir, Gleam, OCaml, Clojure, CUE (syntax and parse diagnostics; evaluation errors via the cue-vet auxiliary runner), Terraform, Nix, Bash, Docker, YAML, JSON, HTML, TOML, Prisma, Vue, Svelte, CSS.
+LSP servers for: TypeScript, Deno, Python (pyright/basedpyright + jedi), Go, Rust, Ruby (ruby-lsp + solargraph), PHP, PowerShell, C# (omnisharp), F#, Java (JDT LS, with Lombok javaagent support when a Lombok jar is available), Kotlin, Swift, Dart, Lua, C/C++, Zig, Haskell, Elixir, Gleam, Markdown (marksman), OCaml, Clojure, CUE (syntax and parse diagnostics; evaluation errors via the cue-vet auxiliary runner), Terraform, Nix, Bash, Fish, CMake, Docker, YAML, JSON, HTML, TOML, Prisma, Vue, Svelte, CSS.
 
 ### Formatters
 
 pi-lens auto-detects and runs **34 formatters** based on project config:
 
-biome, prettier, oxfmt, ruff, black, sqlfluff, gofmt, rustfmt, zig fmt, dart format, shfmt, nixfmt, mix format, ocamlformat, clang-format, ktlint, rubocop, standardrb, gleam format, terraform fmt, php-cs-fixer, csharpier, fantomas, swiftformat, stylua, ormolu, taplo, fish_indent, google-java-format, cljfmt, cmake-format, cue fmt, psscriptanalyzer-format
+biome, prettier, oxfmt, ruff, black, sqlfluff, gofmt, rustfmt, zig fmt, dart format, shfmt, nixfmt, mix format, ocamlformat, clang-format, ktlint, ktfmt, rubocop, standardrb, gleam format, terraform fmt, terragrunt-hcl, php-cs-fixer, csharpier, fantomas, swiftformat, stylua, ormolu, taplo, google-java-format, cljfmt, cmake-format, cue fmt, psscriptanalyzer-format
 
 Detection rules:
 
@@ -310,7 +310,7 @@ Covers JavaScript/TypeScript, Python, Go, Rust, Ruby, Shell, and CMake. A TypeSc
 - **Strictness modes** — `strictness: "relaxed"` ignores optional punctuation (trailing commas, semicolons) that causes zero matches in `smart` mode. Also supports `ast`, `cst`, `signature`, `template`.
 - **Pagination** — `skip: N` offsets into large result sets; truncated results include a next-page hint.
 - **Stale-preview detection** — `ast_grep_replace` re-validates the pattern before writing; returns a clear error if files changed since the preview instead of applying against wrong content.
-- **`ast_grep_dump`** — dumps the full tree-sitter AST for a source snippet. Use this when a pattern returns zero matches and the correct node kind or field name is unknown.
+- **`ast_grep_search` with `dump=true`** — dumps the full tree-sitter AST for a source snippet. Use this when a pattern returns zero matches and the correct node kind or field name is unknown.
 
 ### Tree-sitter Rules
 
@@ -397,7 +397,7 @@ pi-lens ships an MCP (Model Context Protocol) server so Claude Code — or any M
 
 | Layer | MCP tools | What they expose |
 |---|---|---|
-| **Per-edit** | `pilens_analyze`, `pilens_lsp_diagnostics`, `pilens_lsp_navigation`, `pilens_ast_grep_search`, `pilens_ast_grep_replace`, `pilens_module_report`, `pilens_read_symbol`, `pilens_read_enclosing` | The fast pipeline (format → autofix → LSP diagnostics → parallel runners) plus the structured read-substitute pair. `analyze` accepts `mode: warm \| fresh` — `warm` reuses the server's in-process LSP, `fresh` forks a worker that loads freshly-built code from disk so the result reflects the latest commit. |
+| **Per-edit** | `pilens_analyze`, `pilens_lsp_navigation`, `pilens_ast_grep_search`, `pilens_ast_grep_replace`, `pilens_module_report`, `pilens_read_symbol`, `pilens_read_enclosing` | The fast pipeline (format → autofix → LSP diagnostics → parallel runners) plus the structured read-substitute pair. `analyze` accepts `mode: warm \| fresh` — `warm` reuses the server's in-process LSP, `fresh` forks a worker that loads freshly-built code from disk so the result reflects the latest commit. |
 | **Per-turn** | `pilens_turn_end` | Drives the **real** `handleTurnEnd` (knip incremental, dep-circular, cascade, tests, actionable+code-quality warnings) — not a re-implementation. Caller-supplied edited files are auto-registered into turn-state via `addModifiedRange`. |
 | **Per-session** | `pilens_session_start` | Drives the **real** `handleSessionStart` — full jscpd/knip/madge/govulncheck/gitleaks/trivy scans + complexity baselines + LSP warm. The error-debt baseline is not currently populated by the production session-start path. |
 | **Project / observability** | `pilens_project_scan`, `pilens_project_report`, `pilens_diagnostics`, `pilens_health`, `pilens_latency`, `pilens_symbol_search`, `pilens_effective_config` | Cheap project-wide scans, cached diagnostic state, latency telemetry, ranked identifier search (BM25 over the persisted word index — see [docs/word-index.md](word-index.md)). Cross-file blast radius now lives in `pilens_module_report`'s `blastRadius` option. `pilens_health` (and its pi-side `/lens-health` counterpart) also reports a bounded, process-local **degradation ledger** — trust refusals, mode suppressions, LSP breaker trips, formatter skips/failures, TypeScript/word-index/review-graph/project-snapshot idle evictions, WASM aborts, and diagnostics-timeout tallies — so silently degraded behavior stays visible instead of vanishing into a log. `pilens_effective_config` answers **“why is X running / why is X not running”** from one query — the resolved configuration with the provenance of every setting, and for a file you name, its language plus every LSP server with the reason it was selected or denied and the runners that would dispatch. It reports sources, never values. |

package/node_modules/pi-lens/docs/globalconfig.md

@@ -18,6 +18,7 @@ Each runtime toggle is settable from the CLI *and* from `config.json`. The two a
 | `--no-autofix` | `autofix.enabled` | `true` |
 | `--no-lens-context` | `contextInjection.enabled` | `true` |
 | `--lens-guard` | `guard.enabled` | `false` |
+| `--lens-checkout-guard` | `guard.sharedCheckout` | `false` |
 | `--immediate-format` | `format.mode` (`"immediate"`) | `"deferred"` |
 | `--lens-turn-summary` | `turnSummary.enabled` | `false` |
 | `--lens-actionable-warnings` | `actionableWarnings.enabled` | `false` |
@@ -42,7 +43,7 @@ Each runtime toggle is settable from the CLI *and* from `config.json`. The two a
 | `startup.mode` | `full` | `quick`, `full`, or `minimal`; `PI_LENS_STARTUP_MODE` wins |
 | `startup.scans.enabled` | `true` | `true` or `false` |
 
-By default pi-lens registers six situational tools (the `ast_grep_*` family,
+By default pi-lens registers five situational tools (the `ast_grep_*` family,
 `lsp_navigation`, `lens_diagnostic_mark`) inactive and exposes a small loader,
 `pi_lens_activate_tools`, that the model calls to activate the ones it needs.
 `--no-lazy-tools` turns that off: every pi-lens tool is active from the first
@@ -123,6 +124,15 @@ Turn subsystems off globally instead of retyping flags every session:
 
 `lens.enabled: false` starts every session with pi-lens off (the `--no-lens` equivalent); `/lens-toggle` still re-enables it for one session. `lsp.enabled: false` falls back to language-specific checkers such as pyright. `tests.enabled: false` skips the on-write test runner. `delta.enabled: false` reports every diagnostic rather than only ones introduced this turn. `opengrep.enabled: false` detaches the Opengrep security scanner. `readGuard.enabled: false` turns off the read-before-edit monitor. `guard.enabled: true` opts into the experimental commit/push blocker.
 
+The `tools.<name>.enabled` setting controls each model-facing tool. Valid names
+include `ast_grep_search`, `ast_grep_replace`, `ast_grep_outline`,
+`lsp_navigation`, `lens_diagnostics`,
+`lens_diagnostic_mark`, `symbol_search`, `module_report`, `project_report`,
+`read_symbol`, `read_enclosing`, `effective_config`, `analyze`, `health`,
+`latency`, `project_scan`, and `rebuild`. The activation loader and MCP
+lifecycle tools `session_start`, `turn_end`, and `session_end` cannot be
+disabled.
+
 ## Project Config
 
 In addition to the user-level `~/.pi-lens/config.json` above, pi-lens reads a per-project `.pi-lens.json` (or `pi-lens.json`) at the project root. Walked upward from the cwd, so a monorepo can keep the config at the repo root and have every subdir pick it up. The schema is intentionally small — only fields pi-lens actually honors:

package/node_modules/pi-lens/docs/mcp.md

@@ -113,11 +113,23 @@ New files:
 | tool | maps to | purpose |
 |------|---------|---------|
 | `pilens_analyze` | `analyzeFile` (warm) / worker (fresh) | run the per-edit pipeline on a file; returns diagnostics + timing. `mode: warm\|fresh`. **Correctness + mechanism probe.** |
-| `pilens_diagnostics` | lens-diagnostics formatters | delta/all/full project/session diagnostic state. |
+| `pilens_ast_grep_search` | `ast_grep_search` | AST-aware structural search. |
+| `pilens_ast_grep_replace` | `ast_grep_replace` | AST-aware structural replace. |
+| `pilens_diagnostics` | `lens_diagnostics` | session or LSP diagnostics, selected by `source`, `scope`, and `severity`. |
+| `pilens_effective_config` | `effective_config` | resolved configuration and provenance. |
 | `pilens_project_scan` | `scanProjectDiagnostics` | project-wide cheap scan. |
 | `pilens_latency` | `getLatencyReports` | latency records (latency.log schema). **Review-loop measurement.** |
 | `pilens_health` | `/lens-health` internals | runtime health snapshot. |
+| `pilens_lsp_navigation` | `lsp_navigation` | IDE-style LSP navigation. |
+| `pilens_module_report` | `module_report` | navigable module outline and dependents. |
+| `pilens_project_report` | `project_report` | project-level structure and diagnostics report. |
+| `pilens_read_enclosing` | `read_enclosing` | read the smallest enclosing symbol or callback. |
+| `pilens_read_symbol` | `read_symbol` | read one symbol body. |
 | `pilens_rebuild` | `npm run build:dist` | rebuild dist so `fresh` reflects the latest commit. Makes the loop self-contained. |
+| `pilens_session_end` | session lifecycle | close the MCP session and flush lifecycle state. |
+| `pilens_session_start` | session lifecycle | initialize session state and caches. |
+| `pilens_symbol_search` | `symbol_search` | search the persisted symbol index. |
+| `pilens_turn_end` | turn lifecycle | settle turn-end work and return findings. |
 
 ## Packaging / wiring