@nxuss/lemma 1.11.0 → 1.12.0

package/dist/esm/mcp/tools.js

@@ -92,9 +92,55 @@ const PRO_GATE_MESSAGE = [
     "🚀 Get Lemma Pro:",
     "  https://lemma.nxus.studio/upgrade",
 ].join("\n");
+// ── Elicitation (spec 2026-07-28's recommended pattern for destructive actions) ────
+//
+// Set once by setupToolsHandlers so the standalone handler functions below — which don't
+// otherwise see the Server instance — can ask the connected client to confirm before a
+// mutating tool runs.
+let mcpServerRef = null;
+/**
+ * Ask the client to confirm a destructive action before it happens.
+ *
+ * Mirrors the defensive shape of trySamplingContext() in src/mcp/index.ts: most clients
+ * today don't support elicitation, so any failure (unsupported capability, timeout,
+ * malformed response) must fall back to "proceed without confirmation" rather than block
+ * or error out the tool. This is a courtesy prompt for clients that support it, not a
+ * security boundary — the allowlist/path-safety checks each handler already does are that.
+ */
+async function tryElicitConfirmation(summary) {
+    if (!mcpServerRef)
+        return { supported: false, confirmed: true };
+    try {
+        const result = await mcpServerRef.elicitInput({
+            message: summary,
+            requestedSchema: {
+                type: "object",
+                properties: {
+                    confirm: {
+                        type: "boolean",
+                        title: "Proceed?",
+                        description: "Confirm this action should be applied.",
+                    },
+                },
+                required: ["confirm"],
+            },
+        });
+        if (result.action !== "accept") {
+            // "decline" or "cancel" — the user (or client policy) said no.
+            return { supported: true, confirmed: false };
+        }
+        const confirmed = result.content?.confirm !== false;
+        return { supported: true, confirmed };
+    }
+    catch (err) {
+        logWarn("elicitation", "Client does not support elicitation (or the request failed) — proceeding without confirmation");
+        return { supported: false, confirmed: true };
+    }
+}
 const toolDefinitions = [
     {
         name: "scrub_privacy",
+        annotations: { readOnlyHint: true, openWorldHint: false },
         description: "Mask sensitive data (PII, API Keys, Credentials) from a text block using Lemma's Privacy Firewall.",
         inputSchema: {
             type: "object",
@@ -106,6 +152,7 @@ const toolDefinitions = [
     },
     {
         name: "search_memory",
+        annotations: { readOnlyHint: true, openWorldHint: false },
         description: "Search Lemma's semantic memory (The Brain) before investigating something from scratch — retrieves past solutions, fixes, and context from ALL your projects globally. Results are split into 'fresh' (safe to reuse — either untracked general knowledge, or every file it depended on still hashes the same) and 'stale' (a similar question was answered before, but a tracked file changed since — re-verify against current state before reusing). Never treat a stale result as current.",
         inputSchema: {
             type: "object",
@@ -123,6 +170,7 @@ const toolDefinitions = [
     },
     {
         name: "store_memory",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
         description: "Persist a technical solution, bug fix, architecture decision, or key fact into Lemma's Brain — so future questions on the same topic (even phrased differently) don't require re-investigating the repo. Pass filePaths for anything derived from specific files (e.g. 'where is X implemented', 'how does Y work') so the memory auto-invalidates the moment those files change, instead of risking a stale answer being reused. If the answer is really about one function/class rather than the whole file, pass `symbols` instead (or in addition) so an unrelated edit elsewhere in that file doesn't stale it out. Pass outcome='failed' for an approach that was tried and did NOT work — that's just as worth remembering as a fix, so the Brain can warn 'already tried, didn't work' instead of only ever suggesting reuse.",
         inputSchema: {
             type: "object",
@@ -174,6 +222,7 @@ const toolDefinitions = [
     },
     {
         name: "get_routing_advice",
+        annotations: { readOnlyHint: true, openWorldHint: false },
         description: "Analyzes a prompt and suggests the best model based on Lemma's Complexity Router.",
         inputSchema: {
             type: "object",
@@ -183,9 +232,20 @@ const toolDefinitions = [
             },
             required: ["prompt"],
         },
+        outputSchema: {
+            type: "object",
+            properties: {
+                recommendedModel: { type: "string", description: "The model the router recommends" },
+                complexity: { type: "string", enum: ["low", "high"], description: "Estimated complexity of the prompt" },
+                intendedModel: { type: ["string", "null"], description: "The model passed in intended_model, or null if omitted" },
+                switched: { type: "boolean", description: "true if recommendedModel differs from intendedModel" },
+            },
+            required: ["recommendedModel", "complexity", "switched"],
+        },
     },
     {
         name: "auto_heal",
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
         description: "Diagnose and auto-heal the latest local server crash registered in Lemma's context logs.",
         inputSchema: {
             type: "object",
@@ -196,6 +256,7 @@ const toolDefinitions = [
     },
     {
         name: "read_workspace_file",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Read a file inside the workspace. Compresses comments/whitespace and scrubs API keys. Every line carries its REAL line number in the original file (compression removes lines, it never renumbers them), so you can cite file:line and patch precisely without re-reading. The header lists which imports were compressed away. Use offset/limit to read a line range of a large file. If this exact view was already read this session and hasn't changed on disk, returns an UNCHANGED marker plus a symbol outline. If it changed only slightly, returns a CHANGED marker with a unified diff to apply to the copy you already hold. Either way, pass force:true to get the full file when it is no longer in your context.",
         inputSchema: {
             type: "object",
@@ -212,6 +273,7 @@ const toolDefinitions = [
     },
     {
         name: "write_workspace_file",
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
         description: "Write full contents to a file inside the workspace. Creates parent directories automatically.",
         inputSchema: {
             type: "object",
@@ -224,6 +286,7 @@ const toolDefinitions = [
     },
     {
         name: "create_workspace_file",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
         description: "Create a NEW file in the workspace. Fails immediately if the file already exists — use write_workspace_file or apply_workspace_patch to modify existing files. Creates parent directories automatically. Returns a minimal token-free ACK: no file content is echoed back, saving provider output tokens.",
         inputSchema: {
             type: "object",
@@ -236,6 +299,7 @@ const toolDefinitions = [
     },
     {
         name: "apply_workspace_patch",
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
         description: "Apply a smart search-and-replace patch to an existing file. Falls back through whitespace-normalized, indent-anchored, and fuzzy matching if the exact block isn't found — so a searchContent built from a compacted read still applies. Safe against duplicate matches. On total failure, the error includes a diff against the closest candidate block.",
         inputSchema: {
             type: "object",
@@ -249,6 +313,7 @@ const toolDefinitions = [
     },
     {
         name: "run_workspace_command",
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
         description: "Execute a bash command in the workspace root. Default timeout 120s — raise it with timeoutMs for a full test or build run (max 600s). Captures both stdout and stderr, and returns whatever was produced even if the command times out. Long test/build/lint output is distilled deterministically — for jest, vitest and tsc it returns the failing tests or diagnostics with their locations and reasons, dropping code frames and node_modules stack frames; anything else falls back to head/tail plus error-matching lines. The complete output is always stored first and the reply carries a handle: nothing is lost, use output_region to retrieve any part verbatim. Pass raw:true to skip distillation.",
         inputSchema: {
             type: "object",
@@ -270,6 +335,7 @@ const toolDefinitions = [
     },
     {
         name: "output_region",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Retrieve any part of a command output previously stored by run_workspace_command, verbatim. This is what makes distillation lossless — use it when the distilled view isn't enough. Pass all:true for the whole output, section for one named block (a failing test title or a file path, as listed in the distilled view), or startLine/endLine for a range.",
         inputSchema: {
             type: "object",
@@ -285,6 +351,7 @@ const toolDefinitions = [
     },
     {
         name: "list_workspace_dir",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "List files and subdirectories recursively to navigate the repository structure.",
         inputSchema: {
             type: "object",
@@ -296,6 +363,7 @@ const toolDefinitions = [
     },
     {
         name: "search_workspace",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Perform a fast local text search (grep) across all files in the project workspace. Respects .gitignore, skips binaries and files over 500KB, groups results by file (capped per file), and stops at maxResults. For code files (.ts/.tsx/.js/.jsx), matches inside the same function/class/method are collapsed into one entry with its signature and line range instead of raw duplicate lines. Repeating an identical query while the workspace is unchanged returns the cached result instantly instead of re-scanning.",
         inputSchema: {
             type: "object",
@@ -309,6 +377,7 @@ const toolDefinitions = [
     },
     {
         name: "squeeze_prompt",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Compress code blocks, comments, and boilerplate in any prompt. Saves up to 80% tokens.",
         inputSchema: {
             type: "object",
@@ -321,6 +390,7 @@ const toolDefinitions = [
     },
     {
         name: "get_project_onboarding",
+        annotations: { readOnlyHint: true, openWorldHint: false },
         description: "Fetch dynamic architectural and stack overview of the current project in markdown.",
         inputSchema: {
             type: "object",
@@ -329,6 +399,7 @@ const toolDefinitions = [
     },
     {
         name: "get_project_history",
+        annotations: { readOnlyHint: true, openWorldHint: false },
         description: "Answers 'what have we done in this project': merges recent git commits, session checkpoints, and The Brain's memories (decisions, fixes, prior PR reviews) for the current project into one narrative. Use this instead of piecing the same picture together from search_memory + git log + reading checkpoint files separately.",
         inputSchema: {
             type: "object",
@@ -339,6 +410,7 @@ const toolDefinitions = [
     },
     {
         name: "get_ast_hologram",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Generate a dense, token-efficient Holographic AST Map of the workspace using the TypeScript compiler. Returns structured JSON of all exported symbols with file paths and line numbers.",
         inputSchema: {
             type: "object",
@@ -355,6 +427,7 @@ const toolDefinitions = [
     },
     {
         name: "validate_patch_sandbox",
+        annotations: { readOnlyHint: true, openWorldHint: false },
         description: "Validate proposed code in isolated sandbox via tsc + syntax check before applying.",
         inputSchema: {
             type: "object",
@@ -367,6 +440,7 @@ const toolDefinitions = [
     },
     {
         name: "query_hybrid_consensus",
+        annotations: { readOnlyHint: true, openWorldHint: false },
         description: "Search The Brain before reasoning. Brain HIT returns cached answer instantly. Brain MISS proceeds to cloud.",
         inputSchema: {
             type: "object",
@@ -380,6 +454,7 @@ const toolDefinitions = [
     },
     {
         name: "get_telepathic_hints",
+        annotations: { readOnlyHint: true, openWorldHint: false },
         description: "Surface relevant past solutions from The Brain based on the active file path.",
         inputSchema: {
             type: "object",
@@ -392,6 +467,7 @@ const toolDefinitions = [
     },
     {
         name: "summarize_long_text",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Summarize long text locally using Ollama. Compresses verbose content into concise summaries, saving context window for subsequent turns.",
         inputSchema: {
             type: "object",
@@ -404,6 +480,7 @@ const toolDefinitions = [
     },
     {
         name: "prune_conversation_history",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Compress conversation history by decimating old turns and compacting large code blocks in historical messages. Keeps recent context intact. Refuses to mutate anything by default because pruning invalidates the prompt-cache prefix, which is usually a net loss — pass force:true to actually apply it, or call without force to just get the estimated cache-invalidation cost back.",
         inputSchema: {
             type: "object",
@@ -424,6 +501,7 @@ const toolDefinitions = [
     },
     {
         name: "diff_only",
+        annotations: { readOnlyHint: true, idempotentHint: false, openWorldHint: false },
         description: "Compute a compact line-by-line diff between the last known state of a file and its current content. Tracks file state in memory per session.",
         inputSchema: {
             type: "object",
@@ -436,6 +514,7 @@ const toolDefinitions = [
     },
     {
         name: "batch_tool_calls",
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
         description: "Execute multiple tools in a single MCP call. Accepts an array of { tool, args } and runs them in parallel via Promise.all. Results include per-tool success/error status.",
         inputSchema: {
             type: "object",
@@ -458,6 +537,7 @@ const toolDefinitions = [
     },
     {
         name: "turbosqueeze",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "COMPRIME prompts hasta 90%. Elimina comentarios, imports redundantes, whitespace excesivo, y compacta JSON. Usar ANTES de enviar código largo al LLM para maximizar ahorro de tokens.",
         inputSchema: {
             type: "object",
@@ -472,6 +552,7 @@ const toolDefinitions = [
     },
     {
         name: "get_symbol_surgical_context",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Extrae quirúrgicamente la implementación de un símbolo específico (clase, función, interfaz) y las firmas (pero no la implementación completa) de todas sus dependencias locales del workspace. Ahorra hasta 90% de tokens.",
         inputSchema: {
             type: "object",
@@ -484,6 +565,7 @@ const toolDefinitions = [
     },
     {
         name: "wormhole_squeeze",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Comprime código a formato WORMHOLE súper denso usando tokens de palabra clave y abreviación de variables reversible. Ideal para alimentar contextos de lectura al LLM.",
         inputSchema: {
             type: "object",
@@ -495,6 +577,7 @@ const toolDefinitions = [
     },
     {
         name: "generate_executive_roi_report",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
         description: "Genera un reporte ejecutivo en formato Markdown de Retorno de Inversión (ROI), dinero ahorrado en API, horas de desarrollo recuperadas y proyecciones de escala para la gerencia.",
         inputSchema: {
             type: "object",
@@ -507,6 +590,7 @@ const toolDefinitions = [
     },
     {
         name: "surgical_ast_insert",
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
         description: "Inserta quirúrgicamente código (métodos, propiedades, funciones) en una clase, interfaz o ámbito de archivo de TypeScript utilizando el AST Compiler. Evita escribir diffs de búsqueda y reemplazo grandes o reescribir todo el archivo. Ahorra 95% de tokens de salida.",
         inputSchema: {
             type: "object",
@@ -522,6 +606,7 @@ const toolDefinitions = [
     },
     {
         name: "local_semantic_autofix",
+        annotations: { readOnlyHint: true, openWorldHint: false },
         description: "Intenta resolver errores de compilación o ejecución localmente consultando The Brain por tracebacks/mensajes similares. Si hay coincidencia, devuelve la solución/parche instantáneamente sin gastar tokens de LLM.",
         inputSchema: {
             type: "object",
@@ -533,6 +618,7 @@ const toolDefinitions = [
     },
     {
         name: "compress_context",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Comprime el historial de conversación: resume turns antiguos vía Ollama, mantiene solo los últimos N intactos. Reduce contexto 70-80%. USAR antes de cada turno extendido.",
         inputSchema: {
             type: "object",
@@ -549,6 +635,7 @@ const toolDefinitions = [
     },
     {
         name: "smarter_cache",
+        annotations: { readOnlyHint: true, openWorldHint: false },
         description: "Cache predictivo con threshold bajo (75%). Busca en The Brain antes de cualquier razonamiento. Si hay hit >= 75%, devuelve respuesta instantánea sin gastar tokens en LLM.",
         inputSchema: {
             type: "object",
@@ -559,9 +646,25 @@ const toolDefinitions = [
             },
             required: ["query"],
         },
+        outputSchema: {
+            type: "object",
+            properties: {
+                hit: { type: "boolean", description: "true si hubo un hit por encima del threshold" },
+                source: { type: "string", enum: ["lemma-brain", "llm-call-required", "cache-unavailable"], description: "De dónde salió (o no) la respuesta" },
+                similarity: { type: "number", description: "Similitud del mejor match (0.0-1.0). Ausente en la rama de error." },
+                threshold: { type: "number", description: "Threshold usado. Ausente en la rama de error." },
+                answer: { type: ["string", "null"], description: "Respuesta cacheada si hit=true; null si no. Ausente en la rama de error." },
+                tokensSaved: { type: "number", description: "Solo presente cuando hit=true" },
+                tokensSavedFormatted: { type: "string", description: "Solo presente cuando hit=true" },
+                hint: { type: "string", description: "Sugerencia de siguiente paso; presente en miss y en error" },
+                error: { type: "string", description: "Mensaje de error; solo presente si el brain local falló" },
+            },
+            required: ["hit", "source"],
+        },
     },
     {
         name: "state_hash_cache",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
         description: "Cache de razonamiento con invalidación EXACTA (no probabilística): la respuesta queda atada al sha256 del contenido de los archivos de los que depende. Si esos archivos no cambiaron, el hit es matemáticamente válido, no una adivinanza por similitud. Usa action='lookup' antes de razonar sobre una pregunta que dependa de archivos específicos, y action='store' después de responder para cachearla.",
         inputSchema: {
             type: "object",
@@ -573,9 +676,24 @@ const toolDefinitions = [
             },
             required: ["action", "query", "filePaths"],
         },
+        outputSchema: {
+            type: "object",
+            properties: {
+                status: { type: "string", enum: ["hit", "miss", "stored"], description: "Resultado de lookup (hit/miss) o de store (stored)" },
+                answer: { type: "string", description: "Solo presente cuando status='hit'" },
+                note: { type: "string", description: "Solo presente cuando status='hit'" },
+                tokensSaved: { type: "number", description: "Solo presente cuando status='hit'" },
+                reason: { type: "string", description: "Solo presente cuando status='miss'" },
+                hint: { type: "string", description: "Solo presente cuando status='miss'" },
+                id: { type: "string", description: "Solo presente cuando status='stored'" },
+                filesTracked: { type: "array", items: { type: "string" }, description: "Solo presente cuando status='stored'" },
+            },
+            required: ["status"],
+        },
     },
     {
         name: "token_receipt",
+        annotations: { readOnlyHint: true, openWorldHint: false },
         description: "Recibo auditable de la sesión: de dónde vino cada respuesta (cache exacto, cache semántico, lectura de archivo, o razonamiento fresco). No es una estadística de 'ahorro' — es una bitácora verificable para que el usuario pueda comprobar que no se le está mintiendo con un cache hit inventado. Llamar con action='summary' para ver el reporte.",
         inputSchema: {
             type: "object",
@@ -584,9 +702,42 @@ const toolDefinitions = [
                 limit: { type: "number", description: "Cuántos eventos recientes incluir en el detalle", default: 20 },
             },
         },
+        outputSchema: {
+            type: "object",
+            properties: {
+                totalEvents: { type: "number", description: "Total de eventos registrados en la sesión" },
+                byType: {
+                    type: "object",
+                    properties: {
+                        exact_cache_hit: { type: "number" },
+                        semantic_cache_hit: { type: "number" },
+                        file_read: { type: "number" },
+                        reasoning: { type: "number" },
+                        tool_call: { type: "number" },
+                    },
+                    description: "Conteo de eventos por tipo de origen",
+                },
+                recentEvents: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            type: { type: "string" },
+                            label: { type: "string" },
+                            timestamp: { type: "number" },
+                            meta: { type: "object" },
+                        },
+                    },
+                    description: "Últimos `limit` eventos, en orden cronológico",
+                },
+                note: { type: "string" },
+            },
+            required: ["totalEvents", "byType", "recentEvents"],
+        },
     },
     {
         name: "token_budget",
+        annotations: { readOnlyHint: true, openWorldHint: false },
         description: "Muestra el dashboard de consumo: multiplicador actual de membresía, tokens ahorrados, tools usadas, y recomendaciones para optimizar más. Consultar periódicamente para auto-regular consumo.",
         inputSchema: {
             type: "object",
@@ -595,6 +746,7 @@ const toolDefinitions = [
     },
     {
         name: "entropy_score",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Calcula la entropía matemática (complejidad) de uno o más archivos usando el TypeScript Compiler API. Sin LLM. Sin tokens. Devuelve: cyclomatic complexity, nesting depth, ratio de 'any', tamaño de funciones, y un score compuesto 0-100 (0=limpio, 100=caos puro). Usa esto para identificar qué archivos necesitan refactor ANTES de tocarlos.",
         inputSchema: {
             type: "object",
@@ -606,6 +758,7 @@ const toolDefinitions = [
     },
     {
         name: "coupling_radar",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Construye un grafo de acoplamiento entre módulos analizando imports/exports con el TypeScript Compiler. Sin LLM. Sin tokens. Detecta: ciclos de dependencia, módulos 'dios' (importados por todo), islas muertas (nadie los importa), y fan-in/fan-out por módulo. Esencial antes de refactors grandes.",
         inputSchema: {
             type: "object",
@@ -617,6 +770,7 @@ const toolDefinitions = [
     },
     {
         name: "pattern_fossil",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Detecta código zombie: patrones que ya fueron reemplazados en la mayoría del codebase pero siguen vivos en archivos viejos. Sin LLM. Sin tokens. Detecta: callbacks vs async/await, var vs let/const, require() vs import, any vs generics. Devuelve porcentaje de adopción del patrón nuevo vs. los fósiles que quedan.",
         inputSchema: {
             type: "object",
@@ -627,6 +781,7 @@ const toolDefinitions = [
     },
     {
         name: "git_heatmap_risk",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Analiza el historial de git para identificar zonas de alto riesgo. Sin LLM. Sin tokens. Calcula: churn rate (frecuencia de cambios), co-edición oculta (archivos que siempre cambian juntos = acoplamiento implícito), y un risk score compuesto por archivo. Detecta los archivos que estadísticamente tienen más probabilidad de tener un bug.",
         inputSchema: {
             type: "object",
@@ -638,6 +793,7 @@ const toolDefinitions = [
     },
     {
         name: "precrime_static",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "MINORITY REPORT para tu código. Combina entropy_score + coupling_radar + git_heatmap_risk en un predictor de riesgo compuesto. Sin LLM. Sin tokens. Devuelve un ranking de archivos y funciones con mayor probabilidad de causar un bug, con justificación matemática de cada factor. Úsalo antes de un deploy o un PR review.",
         inputSchema: {
             type: "object",
@@ -650,6 +806,7 @@ const toolDefinitions = [
     },
     {
         name: "semantic_dedup_guard",
+        annotations: { readOnlyHint: true, openWorldHint: false },
         description: "Firewall anti-redundancia para The Brain. Antes de hacer store_memory, pasa el contenido por aquí. Consulta ChromaDB localmente sin gastar tokens. Si hay un hit >= 92% → rechaza el store y devuelve el duplicado. Si 75-91% → advierte y muestra el similar. Mantiene The Brain denso y limpio.",
         inputSchema: {
             type: "object",
@@ -663,6 +820,7 @@ const toolDefinitions = [
     },
     {
         name: "dead_export_necromancer",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Resucita el código muerto. Usa el TypeScript Compiler para mapear TODOS los exports del workspace y los cruza contra TODOS los imports. Lo que se exporta pero nadie importa = código zombie que está inflando tu contexto y desperdiciando tokens. Sin LLM. Sin tokens. Devuelve lista de exports muertos con estimación de tokens desperdiciados.",
         inputSchema: {
             type: "object",
@@ -673,6 +831,7 @@ const toolDefinitions = [
     },
     {
         name: "review_diff",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Analyze a raw git diff locally for regressions, security issues, code quality, and static analysis. Zero-cost static analysis using local TypeScript compiler API — no LLM calls. Returns score, verdict, and detailed findings with suggestions.",
         inputSchema: {
             type: "object",
@@ -686,6 +845,7 @@ const toolDefinitions = [
     },
     {
         name: "review_pr",
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
         description: "Analyze a Pull Request via GitHub, Azure DevOps, or GitLab API. Detects regressions, security issues, code quality problems, and breaking changes. Posts results as PR comments and can auto-approve if quality threshold is met. Pro license required.",
         inputSchema: {
             type: "object",
@@ -702,6 +862,7 @@ const toolDefinitions = [
     },
     {
         name: "pr_status",
+        annotations: { readOnlyHint: true, openWorldHint: true },
         description: "Get the status and detailed results of a previously reviewed PR. Returns score, verdict, findings, and approval status.",
         inputSchema: {
             type: "object",
@@ -715,6 +876,7 @@ const toolDefinitions = [
     },
     {
         name: "generate_pr_workflow",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
         description: "Generate a CI/CD workflow file (GitHub Actions or Azure Pipelines) that runs Lemma PR Review on every pull request. Writes the file to the workspace.",
         inputSchema: {
             type: "object",
@@ -729,6 +891,7 @@ const toolDefinitions = [
     },
     {
         name: "depgraph",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Builds a real-time dependency graph for any file in the workspace using the TypeScript Compiler API. Shows what a file imports, what imports it (reverse deps), and what it exports. Zero LLM calls. Essential before any refactor to understand blast radius.",
         inputSchema: {
             type: "object",
@@ -745,6 +908,7 @@ const toolDefinitions = [
     },
     {
         name: "affected_tests",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Given the current diff (or an explicit file list), returns only the test files that transitively import the changed code, plus the exact command to run just those. Uses the TypeScript import graph — zero LLM calls. Run this instead of the full suite after an edit: fewer minutes, and far less test output in context. Reports honestly when the full suite is the right answer (unbounded change, runtime-only coupling, most of the suite affected).",
         inputSchema: {
             type: "object",
@@ -753,9 +917,24 @@ const toolDefinitions = [
                 baseRef: { type: "string", description: "Additional git ref to diff against, e.g. 'main'. The working tree is always included." },
             },
         },
+        outputSchema: {
+            type: "object",
+            properties: {
+                changed: { type: "array", items: { type: "string" }, description: "Files the diff touched, repo-relative" },
+                directTests: { type: "array", items: { type: "string" }, description: "Changed files that are themselves tests" },
+                affected: { type: "array", items: { type: "string" }, description: "Test files that transitively import a changed file" },
+                totalTests: { type: "number", description: "Total test files in the repo" },
+                runner: { type: "string", enum: ["jest", "vitest", "unknown"] },
+                command: { type: ["string", "null"], description: "Command to run just the affected tests, or null if the full suite is recommended" },
+                fullSuiteReason: { type: ["string", "null"], description: "Why the full suite is recommended instead, when command is null" },
+                ungraphed: { type: "array", items: { type: "string" }, description: "Changed files absent from the import graph — blast radius unknown" },
+            },
+            required: ["changed", "directTests", "affected", "totalTests", "runner", "command", "fullSuiteReason", "ungraphed"],
+        },
     },
     {
         name: "refactor",
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
         description: "Declarative multi-file codemod engine. Rename symbols across the entire workspace or move files updating all imports. Uses TypeScript Compiler API — zero LLM calls. Supports dry-run diff preview and post-refactor tsc verification.",
         inputSchema: {
             type: "object",
@@ -773,6 +952,7 @@ const toolDefinitions = [
     },
     {
         name: "smart_file_slice",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Read only the lines semánticamente relevantes around a search query in a file, avoiding sending the entire file context. Returns lines around the matches.",
         inputSchema: {
             type: "object",
@@ -786,6 +966,7 @@ const toolDefinitions = [
     },
     {
         name: "test_oracle",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
         description: "Execute unit tests locally and output ONLY the failing tests and compressed stack traces, keeping context clean.",
         inputSchema: {
             type: "object",
@@ -796,6 +977,7 @@ const toolDefinitions = [
     },
     {
         name: "schema_extract",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Extract high-level schemas, Zod types, interfaces, or database models from a file using the TypeScript AST, removing all implementation code.",
         inputSchema: {
             type: "object",
@@ -807,6 +989,7 @@ const toolDefinitions = [
     },
     {
         name: "changelog_auto",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Generate a clean, token-efficient changelog summary from git logs based on Conventional Commits.",
         inputSchema: {
             type: "object",
@@ -817,6 +1000,7 @@ const toolDefinitions = [
     },
     {
         name: "spec_to_stub",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Parse a TypeScript interface/type definition from a file and output a template mock/stub object configuration using pure AST analysis.",
         inputSchema: {
             type: "object",
@@ -829,6 +1013,7 @@ const toolDefinitions = [
     },
     {
         name: "env_snapshot",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Capture environmental state like Node version, dependencies in package.json, and variables declared in .env files (hiding actual values/credentials).",
         inputSchema: {
             type: "object",
@@ -837,6 +1022,7 @@ const toolDefinitions = [
     },
     {
         name: "migration_tracer",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Inspect changes in database schemas (tables, columns) across local migrations (e.g. Prisma migration directories).",
         inputSchema: {
             type: "object",
@@ -847,6 +1033,7 @@ const toolDefinitions = [
     },
     {
         name: "multi_file_patch",
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
         description: "Apply search-and-replace patches to multiple workspace files in a single turn. Decreases round-trips for multi-file refactoring.",
         inputSchema: {
             type: "object",
@@ -871,6 +1058,7 @@ const toolDefinitions = [
     },
     {
         name: "file_intent_index",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Map and index files inside the workspace by domain intent (e.g., auth, billing, routes, config) to speed up navigation.",
         inputSchema: {
             type: "object",
@@ -881,6 +1069,7 @@ const toolDefinitions = [
     },
     {
         name: "cognitive_map",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
         description: "Access and interact with the Auto-Cognitive Mind Map of the workspace (persisted globally). Holds structured high-level system domains, patterns, decisions, and bugs.",
         inputSchema: {
             type: "object",
@@ -903,6 +1092,7 @@ const toolDefinitions = [
     },
     {
         name: "semantic_grep",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Search the codebase for conceptual terms using natural language and BM25 token relevance instead of exact substring matching.",
         inputSchema: {
             type: "object",
@@ -916,6 +1106,7 @@ const toolDefinitions = [
     },
     {
         name: "imports_skeleton_resolver",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Resolve all imported local files inside a file and print only their signatures (classes, functions, interfaces) in a consolidated view.",
         inputSchema: {
             type: "object",
@@ -927,6 +1118,7 @@ const toolDefinitions = [
     },
     {
         name: "ast_flow_visualizer",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Analyze a function's control flow statements (ifs, loops, try/catch) inside a file using AST compilation and output a visual flowchart in Mermaid syntax.",
         inputSchema: {
             type: "object",
@@ -939,6 +1131,7 @@ const toolDefinitions = [
     },
     {
         name: "file_fingerprint",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Compute SHA256 fingerprint of a file. Returns 'unchanged' if hash matches cache, avoiding full re-reads. Saves 60-70% tokens on repeated file access.",
         inputSchema: {
             type: "object",
@@ -951,6 +1144,7 @@ const toolDefinitions = [
     },
     {
         name: "git_blame_heat",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Analyze git blame history to identify high-risk lines and authors. Zero LLM cost. Returns risk scores per line, hotspots, and top contributors by risk.",
         inputSchema: {
             type: "object",
@@ -962,6 +1156,7 @@ const toolDefinitions = [
     },
     {
         name: "type_coverage_report",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Analyze TypeScript type coverage of a file using AST. Returns declaration count, typed vs untyped ratio, any-usage count, and a safety score 0-100. Zero LLM cost.",
         inputSchema: {
             type: "object",
@@ -973,6 +1168,7 @@ const toolDefinitions = [
     },
     {
         name: "import_tree_context",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Build a bidirectional import graph for a file. Shows what it imports, what imports it, and external dependencies. Zero LLM cost. Essential before refactors.",
         inputSchema: {
             type: "object",
@@ -985,6 +1181,7 @@ const toolDefinitions = [
     },
     {
         name: "read_token_budgeted",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Read a file with a hard token budget. Returns only the most relevant sections up to maxTokens. Saves 70-90% vs full reads.",
         inputSchema: {
             type: "object",
@@ -998,6 +1195,7 @@ const toolDefinitions = [
     },
     {
         name: "bulk_file_digest",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Read multiple files in one call and return a compressed digest. Saves 80% round-trips vs reading files individually.",
         inputSchema: {
             type: "object",
@@ -1015,6 +1213,7 @@ const toolDefinitions = [
     },
     {
         name: "auto_context_bundle",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         description: "Get everything about a file in one call: compressed content, import graph, schema types, and telepathic hints from The Brain. Replaces 4-5 separate tool calls.",
         inputSchema: {
             type: "object",
@@ -1026,6 +1225,7 @@ const toolDefinitions = [
     },
     {
         name: "repeat_guard",
+        annotations: { readOnlyHint: true, openWorldHint: false },
         description: "Check if a draft output is repetitive compared to recent responses. Returns similarity score and suggestion. Prevents duplicate explanations.",
         inputSchema: {
             type: "object",
@@ -1038,6 +1238,7 @@ const toolDefinitions = [
     },
     {
         name: "conversation_checkpoint",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
         description: "Save or load session state. Prevents re-explaining context across turns. Save current progress or load last checkpoint.",
         inputSchema: {
             type: "object",
@@ -1053,6 +1254,7 @@ const toolDefinitions = [
     },
     {
         name: "test_autofix_interceptor",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
         description: "Run tests and auto-search The Brain for fixes to failures. Returns failure list with suggested fixes from past sessions. Saves 4-5 turns of debugging.",
         inputSchema: {
             type: "object",
@@ -1063,6 +1265,7 @@ const toolDefinitions = [
     },
     {
         name: "prompt_pattern_cache",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
         description: "Find or store optimized prompt templates. Reuses past prompt patterns to save 20-30% tokens on repetitive operations.",
         inputSchema: {
             type: "object",
@@ -1082,6 +1285,7 @@ const _infraToolDefs = getInfraToolDefinitions();
 // than in the main array because it must never itself be hidden.
 const TOOLBOX_TOOL_DEFINITION = {
     name: "lemma_toolbox",
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
     description: "Discover and invoke Lemma tools whose schemas are not loaded this session. Use action='list' (optionally with a query) to see what exists, 'schema' to read one tool's inputs, and 'call' to run it. Every Lemma capability is reachable here.",
     inputSchema: {
         type: "object",
@@ -1287,6 +1491,7 @@ function receiptLabelMeta(name, args) {
     return meta;
 }
 export function setupToolsHandlers(server, onToolCall) {
+    mcpServerRef = server;
     registerSymbolExtractor(extractSymbolsWithTsCompiler);
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: toolDefinitionsArray,
@@ -1483,7 +1688,8 @@ async function handleGetRoutingAdvice(args) {
     const intendedModel = args?.intended_model;
     const router = new ComplexityRouter();
     const decision = router.evaluate(prompt, intendedModel);
-    if (decision.complexity === "low" && intendedModel && decision.model !== intendedModel) {
+    const switched = !!intendedModel && decision.model !== intendedModel;
+    if (decision.complexity === "low" && switched) {
         const estimatedPromptTokens = Math.floor((prompt?.length || 0) / 4);
         reportSavings({
             source: "complexityRouting",
@@ -1492,6 +1698,12 @@ async function handleGetRoutingAdvice(args) {
             query: prompt?.substring(0, 100),
         });
     }
+    const structured = {
+        recommendedModel: decision.model,
+        complexity: decision.complexity,
+        intendedModel: intendedModel || null,
+        switched,
+    };
     return {
         content: [
             {
@@ -1499,6 +1711,7 @@ async function handleGetRoutingAdvice(args) {
                 text: `Lemma Routing Advice: Use ${decision.model}. Reason: Complexity is ${decision.complexity}.`,
             },
         ],
+        structuredContent: structured,
     };
 }
 async function handleAutoHeal(args) {
@@ -1771,6 +1984,11 @@ async function handleApplyWorkspacePatch(args) {
             const updatedLines = [...contentLines.slice(0, match.startLine), ...finalReplace.split("\n"), ...contentLines.slice(match.endLine + 1)];
             updatedContent = updatedLines.join("\n");
         }
+        const elicited = await tryElicitConfirmation(`Apply a patch to ${filePath}? This replaces ${searchContent.length} char(s) with ${replaceContent.length} char(s) ` +
+            `starting at line ${match.startLine + 1}.`);
+        if (elicited.supported && !elicited.confirmed) {
+            return { content: [{ type: "text", text: `Patch to ${filePath} was not applied: declined during confirmation.` }] };
+        }
         fs.writeFileSync(resolved, updatedContent, "utf8");
         const note = match.strategy === "exact" ? "" : ` (matched via ${match.strategy}, score ${match.score.toFixed(2)})`;
         return { content: [{ type: "text", text: `Success: Patch successfully applied to ${filePath}${note}` }] };
@@ -1820,6 +2038,10 @@ async function handleRunWorkspaceCommand(args) {
         const MAX_TIMEOUT_MS = 600000;
         const requested = typeof args?.timeoutMs === "number" && args.timeoutMs > 0 ? args.timeoutMs : DEFAULT_TIMEOUT_MS;
         const timeoutMs = Math.min(Math.floor(requested), MAX_TIMEOUT_MS);
+        const elicited = await tryElicitConfirmation(`Run this command in the workspace root?\n\n${command}`);
+        if (elicited.supported && !elicited.confirmed) {
+            return { content: [{ type: "text", text: `Command was not run: declined during confirmation.\n\nCommand: ${command}` }] };
+        }
         const result = spawnSync(command, {
             cwd: workspaceRoot,
             shell: true,
@@ -2842,47 +3064,44 @@ async function handleSmarterCache(args) {
                 reportSavings({ source: "cache", tokens: tokensSaved, toolName: "smarter_cache", query: query.substring(0, 100) });
             }
             catch { }
+            const structured = {
+                hit: true,
+                similarity: topHit.similarity,
+                threshold,
+                answer: responseText,
+                source: "lemma-brain",
+                tokensSaved,
+                tokensSavedFormatted: `~${tokensSaved.toLocaleString()} tokens`,
+            };
             return {
-                content: [{
-                        type: "text",
-                        text: JSON.stringify({
-                            hit: true,
-                            similarity: topHit.similarity,
-                            threshold,
-                            answer: responseText,
-                            source: "lemma-brain",
-                            tokensSaved,
-                            tokensSavedFormatted: `~${tokensSaved.toLocaleString()} tokens`,
-                        }, null, 2),
-                    }],
+                content: [{ type: "text", text: JSON.stringify(structured, null, 2) }],
+                structuredContent: structured,
             };
         }
+        const structured = {
+            hit: false,
+            similarity: topHit?.similarity || 0,
+            threshold,
+            answer: null,
+            source: "llm-call-required",
+            hint: "Después de resolver, llama store_memory para cachear y no gastar tokens en esto otra vez.",
+        };
         return {
-            content: [{
-                    type: "text",
-                    text: JSON.stringify({
-                        hit: false,
-                        similarity: topHit?.similarity || 0,
-                        threshold,
-                        answer: null,
-                        source: "llm-call-required",
-                        hint: "Después de resolver, llama store_memory para cachear y no gastar tokens en esto otra vez.",
-                    }, null, 2),
-                }],
+            content: [{ type: "text", text: JSON.stringify(structured, null, 2) }],
+            structuredContent: structured,
         };
     }
     catch (e) {
         logError("smarter_cache", e);
+        const structured = {
+            hit: false,
+            error: e.message,
+            source: "cache-unavailable",
+            hint: "El cache local del brain falló. El LLM funcionará normalmente sin cache.",
+        };
         return {
-            content: [{
-                    type: "text",
-                    text: JSON.stringify({
-                        hit: false,
-                        error: e.message,
-                        source: "cache-unavailable",
-                        hint: "El cache local del brain falló. El LLM funcionará normalmente sin cache.",
-                    }, null, 2),
-                }],
+            content: [{ type: "text", text: JSON.stringify(structured, null, 2) }],
+            structuredContent: structured,
         };
     }
 }
@@ -2903,23 +3122,21 @@ async function handleStateHashCache(args) {
                 reportSavings({ source: "cache", tokens: tokensSaved, toolName: "state_hash_cache", query: query.substring(0, 100) });
             }
             catch { }
+            const structured = {
+                status: "hit",
+                answer: result.entry.answer,
+                note: "Respuesta desde caché exacto (hash de archivos sin cambios) — no necesita re-razonar.",
+                tokensSaved,
+            };
             return {
-                content: [{
-                        type: "text",
-                        text: JSON.stringify({
-                            status: "hit",
-                            answer: result.entry.answer,
-                            note: "Respuesta desde caché exacto (hash de archivos sin cambios) — no necesita re-razonar.",
-                            tokensSaved,
-                        }, null, 2),
-                    }],
+                content: [{ type: "text", text: JSON.stringify(structured, null, 2) }],
+                structuredContent: structured,
             };
         }
+        const structured = { status: "miss", reason: result.reason, hint: "Razona normalmente y luego llama action='store' con la respuesta." };
         return {
-            content: [{
-                    type: "text",
-                    text: JSON.stringify({ status: "miss", reason: result.reason, hint: "Razona normalmente y luego llama action='store' con la respuesta." }, null, 2),
-                }],
+            content: [{ type: "text", text: JSON.stringify(structured, null, 2) }],
+            structuredContent: structured,
         };
     }
     if (action === "store") {
@@ -2927,8 +3144,10 @@ async function handleStateHashCache(args) {
         if (!answer)
             throw new Error("answer is required for action='store'");
         const entry = storeStateHash(workspaceRoot, query, answer, filePaths);
+        const structured = { status: "stored", id: entry.id, filesTracked: Object.keys(entry.fileHashes) };
         return {
-            content: [{ type: "text", text: JSON.stringify({ status: "stored", id: entry.id, filesTracked: Object.keys(entry.fileHashes) }, null, 2) }],
+            content: [{ type: "text", text: JSON.stringify(structured, null, 2) }],
+            structuredContent: structured,
         };
     }
     throw new Error(`Unknown action: ${action}. Use 'lookup' or 'store'.`);
@@ -2937,16 +3156,15 @@ async function handleStateHashCache(args) {
 async function handleTokenReceipt(args) {
     const limit = typeof args?.limit === "number" ? args.limit : 20;
     const summary = getReceiptSummary(limit);
+    const structured = {
+        totalEvents: summary.totalEvents,
+        byType: summary.byType,
+        recentEvents: summary.recent,
+        note: "Esto es una bitácora real de esta sesión, no una proyección de ahorro. Si byType.reasoning es alto, no hubo mucho cache — y está bien, es honesto.",
+    };
     return {
-        content: [{
-                type: "text",
-                text: JSON.stringify({
-                    totalEvents: summary.totalEvents,
-                    byType: summary.byType,
-                    recentEvents: summary.recent,
-                    note: "Esto es una bitácora real de esta sesión, no una proyección de ahorro. Si byType.reasoning es alto, no hubo mucho cache — y está bien, es honesto.",
-                }, null, 2),
-            }],
+        content: [{ type: "text", text: JSON.stringify(structured, null, 2) }],
+        structuredContent: structured,
     };
 }
 // ── Token Budget ─────────────────────────────────────────────────
@@ -4230,7 +4448,17 @@ async function handleAffectedTests(args) {
             totalTests: result.totalTests,
             narrowed: result.command !== null,
         });
-        return { content: [{ type: "text", text }] };
+        const structured = {
+            changed: result.changed,
+            directTests: result.directTests,
+            affected: result.affected,
+            totalTests: result.totalTests,
+            runner: result.runner,
+            command: result.command,
+            fullSuiteReason: result.fullSuiteReason,
+            ungraphed: result.ungraphed,
+        };
+        return { content: [{ type: "text", text }], structuredContent: structured };
     }
     catch (err) {
         logError("affected_tests", err);