@vascend/talos 0.1.0

package/dist/tools/builtin.js

@@ -0,0 +1,2494 @@
+import { outputArtifact } from "./output-artifact.js";
+import { spawn } from "node:child_process";
+import { open, readFile, writeFile, readdir, stat, mkdir, realpath, lstat, readlink } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join, dirname, resolve, relative, isAbsolute, sep } from "node:path";
+import { invokeToolCall } from "../core/tool-executor.js";
+import { formatSessionHits, searchSessions } from "../vascend/session-search.js";
+import { formatUserProfile, forgetUserFact, readUserProfile, rememberUserFact } from "../vascend/user-profile.js";
+import { formatQueue, WorkQueue } from "../vascend/work-queue.js";
+import { listMemoryScopes, MemoryStore } from "../vascend/memory-store.js";
+import { RoomMemory } from "../vascend/room-memory.js";
+import { DecisionStore, decisionToRoomRecord } from "../vascend/decision-promotion.js";
+import { ContractStore, contractToRoomRecord } from "../vascend/contract-memory.js";
+import { VascendPlanStore } from "../vascend/plan-store.js";
+import { discoverSkills, findSkill } from "../skills/skills.js";
+import { backgroundManager, terminateChildProcess } from "../core/background.js";
+import { pageOf, paginate, pageStore } from "./pagination.js";
+import { missingParamError, normalizeToolInput } from "./normalize-input.js";
+import { teamTools } from "./team-tools.js";
+import { ramificationTools } from "./ramification-tools.js";
+import { kingdomBus } from "../vascend/kingdom-bus.js";
+import { resolveKingdomBus } from "../vascend/kingdom-channel.js";
+import { knowledgeBase } from "../vascend/competitor-knowledge.js";
+import { renderArchitectureMap, scanArchitectureMap } from "../vascend/architecture-map.js";
+import { compileSearchPattern } from "./regex-compat.js";
+import { toolInputSchema } from "../mcp/protocol.js";
+import { LEGACY_DISCOVERY_TOOL_NAMES, toolInventory, toolListTool } from "./discovery.js";
+import { BUILTIN_CAPABILITIES, BUILTIN_CONTINUATIONS } from "./capabilities.js";
+import { runProgramTool } from "./program.js";
+import { shellEnvironment } from "./shell-env.js";
+import { workspaceSessionsTool } from "./workspace-sessions.js";
+import { vascendStatusTool } from "./plan-status.js";
+import { askUserTool } from "./ask-user.js";
+export { askUserTool } from "./ask-user.js";
+import { hasTaskEvidence, isConcreteTaskEvidence, planBlockers, sameCastlePlan, taskTitles } from "../vascend/plan-progress.js";
+import { fileActor, formatFileConflicts } from "../core/file-coordination.js";
+// Shell per il tool bash. Su Windows `exec` userebbe cmd.exe, dove la sintassi
+// POSIX (find, sed, for f in, pipe) fallisce: se c'e' Git Bash, lo preferiamo.
+// Override esplicito con TALOS_SHELL.
+function detectBashShell() {
+    if (process.platform !== "win32")
+        return undefined; // /bin/sh va bene
+    const override = (process.env["TALOS_SHELL"] ?? "").trim();
+    if (override)
+        return override;
+    const candidates = [
+        "C:/Program Files/Git/bin/bash.exe",
+        "C:/Program Files/Git/usr/bin/bash.exe",
+        "C:/Program Files (x86)/Git/bin/bash.exe",
+        `${process.env["LOCALAPPDATA"] ?? ""}/Programs/Git/bin/bash.exe`,
+    ];
+    for (const c of candidates) {
+        if (c && existsSync(c))
+            return c;
+    }
+    return undefined; // fallback: cmd.exe (POSIX non garantito)
+}
+const BASH_SHELL = detectBashShell();
+// Timeout dei comandi bash (ms): evita che un comando lento (es. find su
+// node_modules) blocchi la sessione per minuti. Override con TALOS_BASH_TIMEOUT.
+function bashTimeout() {
+    const n = Number(process.env["TALOS_BASH_TIMEOUT"]);
+    return Number.isFinite(n) && n > 0 ? n : 120_000;
+}
+// Compatibilita' CLI: radici globali usate soltanto quando il chiamante non
+// fornisce la policy per-turn `ToolContext.fsRoots`.
+function extraRoots() {
+    return (process.env["TALOS_EXTRA_ROOTS"] ?? "")
+        .split(/[,;]/)
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .map((r) => resolve(r));
+}
+// Normalizza i path in stile Git-Bash/MSYS (/c/Users/...) verso Windows
+// (C:/Users/...). Node fs interpreterebbe /c/... come C:\c\... -> ENOENT.
+function normalizeFsPath(p) {
+    if (process.platform !== "win32")
+        return p;
+    const m = /^\/([a-zA-Z])\/(.*)$/.exec(p);
+    return m ? `${m[1].toUpperCase()}:/${m[2]}` : p;
+}
+function expandHomePath(raw) {
+    if (raw === "~")
+        return homedir();
+    if (raw.startsWith("~/") || raw.startsWith("~\\"))
+        return join(homedir(), raw.slice(2));
+    return raw;
+}
+/**
+ * Canonicalizza anche un path ancora da creare. Risolve col filesystem il suo
+ * antenato esistente piu' vicino e riappende la coda mancante: in questo modo
+ * un symlink intermedio non puo' trasformare una scrittura apparentemente
+ * interna in una scrittura fuori root.
+ */
+async function canonicalPath(abs, seenLinks = new Set()) {
+    let cursor = resolve(abs);
+    const missing = [];
+    for (;;) {
+        let info;
+        try {
+            info = await lstat(cursor);
+        }
+        catch (cause) {
+            const code = cause.code;
+            if (code !== "ENOENT" && code !== "ENOTDIR")
+                throw cause;
+            const parent = dirname(cursor);
+            if (parent === cursor)
+                throw cause;
+            missing.push(basename(cursor));
+            cursor = parent;
+            continue;
+        }
+        if (info.isSymbolicLink()) {
+            if (seenLinks.has(cursor))
+                throw new Error(`ciclo di symlink nel percorso: ${cursor}`);
+            seenLinks.add(cursor);
+            const target = await readlink(cursor);
+            return canonicalPath(resolve(dirname(cursor), target, ...missing.reverse()), seenLinks);
+        }
+        const existing = await realpath(cursor);
+        return resolve(existing, ...missing.reverse());
+    }
+}
+function isWithin(root, target) {
+    const rel = relative(root, target);
+    return rel === "" || (!isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${sep}`));
+}
+// Se fsRoots e' definito, la policy e' interamente per-turn e non dipende da
+// process.env. L'assenza mantiene il comportamento storico della CLI.
+async function safePath(cwd, raw, fsRoots) {
+    const p = normalizeFsPath(expandHomePath(raw));
+    const abs = resolve(isAbsolute(p) ? p : resolve(cwd, p));
+    const perTurn = fsRoots !== undefined;
+    if (!perTurn && process.env["TALOS_CONFINE_FS"] !== "1")
+        return abs;
+    const rawRoots = perTurn ? [cwd, ...fsRoots] : [cwd, ...extraRoots()];
+    const [target, ...roots] = await Promise.all([
+        canonicalPath(abs),
+        ...rawRoots.map((root) => canonicalPath(resolve(cwd, normalizeFsPath(expandHomePath(root))))),
+    ]);
+    if (roots.some((root) => isWithin(root, target)))
+        return abs;
+    const hint = perTurn
+        ? "La cartella deve essere autorizzata dall'host per questo turno."
+        : "Confinamento CLI attivo: configura TALOS_EXTRA_ROOTS o disattiva TALOS_CONFINE_FS.";
+    throw new Error(`percorso fuori dalle radici consentite: ${p}. ${hint}`);
+}
+function toolError(output) {
+    return { output, isError: true };
+}
+const MAX_OUTPUT = 30_000;
+function clamp(s) {
+    return s.length > MAX_OUTPUT ? s.slice(0, MAX_OUTPUT) + "\n...[troncato]" : s;
+}
+// Risolve shell + argomenti per spawn (Git Bash su Windows se presente, per la
+// sintassi POSIX; altrimenti cmd.exe; /bin/sh altrove).
+function resolveShell(command, requested) {
+    const isWin = process.platform === "win32";
+    if (requested === "powershell")
+        return { shell: isWin ? "powershell.exe" : "pwsh", args: ["-NoProfile", "-NonInteractive", "-Command", command] };
+    if (requested === "cmd" && isWin)
+        return { shell: process.env["ComSpec"] || "cmd.exe", args: ["/d", "/s", "/c", command] };
+    if (requested === "sh")
+        return { shell: "sh", args: ["-c", command] };
+    if (requested === "bash")
+        return { shell: BASH_SHELL || "bash", args: ["-c", command] };
+    if (BASH_SHELL)
+        return { shell: BASH_SHELL, args: ["-c", command] };
+    if (isWin)
+        return { shell: process.env["ComSpec"] || "cmd.exe", args: ["/d", "/s", "/c", command] };
+    return { shell: "/bin/sh", args: ["-c", command] };
+}
+export const bashTool = {
+    name: "bash",
+    description: "Esegue comandi nel workspace, inclusi rg, rg --files, git diff e letture mirate. Richiede conferma dell'utente. " +
+        `Shell predefinita: ${BASH_SHELL ? "bash" : process.platform === "win32" ? "cmd" : "sh"}; usa shell per sceglierne un'altra. ` +
+        "Per controlli brevi preferisci il primo piano. Con background=true attende fino a 1 secondo: " +
+        "se il comando finisce restituisce l'esito, altrimenti ricevi un ID e puoi " +
+        "leggere stato/output o interromperli con bash_output. Per un comando in primo piano " +
+        "puoi impostare timeout_seconds. L'utente puo' anche premere Ctrl+B per spostarlo in background.",
+    schema: {
+        type: "object",
+        properties: {
+            command: { type: "string", description: "Comando da eseguire" },
+            shell: { type: "string", enum: ["auto", "bash", "powershell", "cmd", "sh"], description: "Shell da usare; default auto. Usa sintassi e quoting della shell scelta." },
+            background: {
+                type: "boolean",
+                description: "Restituisce l'esito se pronto entro yield_time_ms, altrimenti un ID da seguire con bash_output",
+            },
+            yield_time_ms: {
+                type: "integer", minimum: 0, maximum: 10000,
+                description: "Attesa iniziale con background=true: default 1000 ms; 0 restituisce subito, utile per server persistenti",
+            },
+            timeout_seconds: {
+                type: "number",
+                minimum: 1,
+                maximum: 3600,
+                description: "Timeout del comando in primo piano; default configurato dall'ambiente",
+            },
+        },
+        required: ["command"],
+    },
+    handler: async (input, ctx) => {
+        ctx.signal.throwIfAborted();
+        const command = String(input["command"] ?? "").trim();
+        if (!command)
+            return toolError(missingParamError("command", input, '{"command":"npm test"}'));
+        const shell = String(input["shell"] ?? "auto");
+        if (!["auto", "bash", "powershell", "cmd", "sh"].includes(shell) || shell === "cmd" && process.platform !== "win32") {
+            return toolError("shell non disponibile o non valida: scegli auto, bash, powershell, sh (cmd solo su Windows)");
+        }
+        // Lavorando in squadra i collaboratori condividono la STESSA working dir/repo: se
+        // ognuno fa git che muta (add/commit/push/reset/checkout/stash...) in
+        // parallelo si sovrascrivono a vicenda (index.lock, "changes would be
+        // overwritten", un git add -A stagia il lavoro a meta' di un altro) e alla
+        // fine non resta nulla. I collaboratori MODIFICANO solo i file; il commit/push
+        // avviene una sola volta alla fine, fuori dallo swarm.
+        // Solo in modalita' CONDIVISA (collaboratore senza worktree proprio). In modalita'
+        // ISOLATA (ctx.kingdom.isolated) il collaboratore ha un worktree dedicato e usa
+        // git liberamente: i commit stanno sul suo ramo, niente race.
+        if (ctx.kingdom && !ctx.kingdom.isolated && mutatesGit(command)) {
+            return toolError("BLOCCATO mentre lavori in squadra (working dir condivisa): niente git che modifica (add/commit/push/" +
+                "pull/merge/rebase/reset/checkout/switch/restore/stash/clean/rm). I collaboratori condividono la " +
+                "stessa working dir e si sovrascriverebbero a vicenda. Modifica SOLO i file del tuo incarico: le " +
+                "modifiche restano nel working tree e verranno committate/pushate UNA volta alla fine. " +
+                "(git status/diff/log/show sono ok.)");
+        }
+        const ok = await ctx.confirm("bash", command);
+        ctx.signal.throwIfAborted();
+        if (!ok)
+            return toolError("comando rifiutato dall'utente");
+        const requestedTimeout = Number(input["timeout_seconds"]);
+        const timeoutMs = Number.isFinite(requestedTimeout) && requestedTimeout > 0
+            ? Math.min(3_600_000, Math.max(1_000, Math.round(requestedTimeout * 1000)))
+            : bashTimeout();
+        return runBashSpawn(command, ctx, {
+            background: input["background"] === true,
+            shell,
+            yieldMs: typeof input["yield_time_ms"] === "number" && Number.isFinite(input["yield_time_ms"])
+                ? Math.max(0, Math.min(10_000, Math.floor(input["yield_time_ms"]))) : 1000,
+            timeoutMs,
+        });
+    },
+};
+// True se il comando esegue un'operazione git che MUTA l'indice/working tree/
+// remoto (da vietare ai collaboratori). Le operazioni di sola lettura
+// (status/diff/log/show/blame/ls-files/rev-parse/fetch) restano permesse.
+function mutatesGit(command) {
+    return /\bgit\s+(?:-[^\s]+\s+|--[^\s]+\s+)*(add|commit|push|pull|merge|rebase|reset|checkout|switch|restore|stash|clean|cherry-pick|revert|rm|mv|am|apply|tag|gc|prune)\b/i.test(command);
+}
+function runBashSpawn(command, ctx, options) {
+    ctx.signal.throwIfAborted();
+    const mgr = backgroundManager;
+    const task = mgr.createTask(command);
+    const { shell, args } = resolveShell(command, options.shell);
+    const timeoutMs = options.timeoutMs;
+    return new Promise((resolvePromise) => {
+        let settled = false;
+        let yieldTimer;
+        const child = spawn(shell, args, { cwd: ctx.cwd, windowsHide: true, env: shellEnvironment() });
+        mgr.setChild(task.id, child);
+        const onAbort = () => {
+            terminateChildProcess(child);
+            mgr.finishTask(task.id, "killed");
+            finish("comando interrotto", true);
+        };
+        const timer = setTimeout(() => {
+            terminateChildProcess(child);
+            mgr.finishTask(task.id, "killed");
+            finish(`errore: comando interrotto dopo ${Math.round(timeoutMs / 1000)}s (timeout). ` +
+                `Per un comando lungo, lascialo girare e premi Ctrl+B per metterlo in background.`, true);
+        }, timeoutMs);
+        const cleanup = () => {
+            clearTimeout(timer);
+            if (yieldTimer)
+                clearTimeout(yieldTimer);
+            ctx.signal.removeEventListener("abort", onAbort);
+        };
+        const finish = (msg, isError = false) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            mgr.clearForeground(task.id);
+            resolvePromise(isError ? toolError(msg) : msg);
+        };
+        child.stdout?.on("data", (d) => mgr.appendOutput(task.id, d.toString("utf8")));
+        child.stderr?.on("data", (d) => mgr.appendOutput(task.id, d.toString("utf8")));
+        child.on("error", (err) => {
+            mgr.finishTask(task.id, "failed");
+            finish(`errore esecuzione: ${err.message}`, true);
+        });
+        child.on("close", (code, sig) => {
+            const status = sig ? "killed" : code === 0 ? "done" : "failed";
+            mgr.finishTask(task.id, status, code ?? undefined);
+            const t = mgr.get(task.id);
+            const body = paginate(t?.output ?? "", "output bash", ctx);
+            finish(body || (status === "done" ? "(nessun output)" : `(uscita ${code ?? sig})`), status !== "done");
+        });
+        // Foreground: Ctrl+B lo stacca (continua a girare in background).
+        const detach = () => {
+            if (settled)
+                return;
+            mgr.markDetached(task.id);
+            cleanup(); // niente piu' timeout/abort del foreground sul task staccato
+            finish(`comando in background [${task.id}]: ${command.length > 60 ? command.slice(0, 57) + "..." : command}\n` +
+                `Continua a girare. Leggi l'output con bash_output id="${task.id}".`);
+        };
+        mgr.setForeground({ taskId: task.id, background: detach });
+        // Un agente non puo' decidere di interrompere un tool mentre ne attende il
+        // risultato. Una breve attesa evita un secondo giro per i comandi rapidi;
+        // oltre il limite bash_output permette di osservare e terminare il task.
+        if (options.background) {
+            if (options.yieldMs === 0) {
+                detach();
+                return;
+            }
+            yieldTimer = setTimeout(detach, options.yieldMs);
+        }
+        if (ctx.signal.aborted)
+            onAbort();
+        else
+            ctx.signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+// bash_output: canale di controllo dei comandi che l'agente o l'utente hanno
+// mandato in background.
+export const bashOutputTool = {
+    name: "bash_output",
+    description: "Monitora e gestisce un comando shell in background. Passa `id` (es. \"bg1\") per " +
+        "leggerne stato e output; senza id elenca i task. `kill: true` interrompe il processo.",
+    schema: {
+        type: "object",
+        properties: {
+            id: { type: "string", description: "id del task (es. bg1)" },
+            kill: { type: "boolean", description: "se true termina il task" },
+        },
+    },
+    handler: async (input, ctx) => {
+        ctx.signal.throwIfAborted();
+        const mgr = backgroundManager;
+        const id = String(input["id"] ?? "").trim();
+        if (!id) {
+            const list = mgr.list();
+            if (!list.length)
+                return "nessun task in background";
+            return list.map((t) => `${t.id} [${t.status}] ${t.command}`).join("\n");
+        }
+        const t = mgr.get(id);
+        if (!t)
+            return toolError(`task non trovato: ${id}`);
+        if (input["kill"] === true)
+            return mgr.kill(id) ? `terminato ${id}` : `${id} non e' piu' in esecuzione`;
+        const head = `${t.id} [${t.status}${t.exitCode != null ? ` · uscita ${t.exitCode}` : ""}] ${t.command}`;
+        const output = `${head}\n${clamp(t.output) || "(nessun output)"}`;
+        return t.status === "failed" || t.status === "killed" ? toolError(output) : output;
+    },
+};
+// Oltre questa taglia un file non viene MAI letto integrale: leggere e
+// splittare decine di MB dentro il main di Electron e' la stessa classe di
+// saturazione della grep larga (ghost "non risponde"). Si legge a finestre.
+const READ_FINESTRA_BYTES = 2_000_000;
+// Tetto di byte scanditi per raggiungere un offset profondo: oltre, ci si
+// ferma e lo si dichiara (il rimedio e' grep per localizzare la riga).
+const READ_SCAN_MAX_BYTES = 16_000_000;
+const READ_CHUNK_BYTES = 262_144;
+// Un read senza limit su un file grande ritorna comunque una finestra finita.
+const READ_RIGHE_DEFAULT_GRANDI = 1_000;
+// Lettura incrementale per righe di un file grande: chunk da 256KB, decoder
+// streaming (i confini multi-byte non si spezzano), respiro periodico per
+// l'event loop, stop appena la finestra richiesta e' completa.
+async function leggiFinestra(abs, rel, taglia, offset, limit, ctx) {
+    const inizio = Math.max(0, offset - 1);
+    const quante = limit > 0 ? limit : READ_RIGHE_DEFAULT_GRANDI;
+    const fine = inizio + quante;
+    const decoder = new TextDecoder("utf-8");
+    const finestra = [];
+    let resto = "";
+    let riga = 0; // indice 0-based della prossima riga completa
+    let letti = 0;
+    let fermatoAlTetto = false;
+    let completa = false;
+    const fh = await open(abs, "r");
+    try {
+        const buffer = Buffer.alloc(READ_CHUNK_BYTES);
+        let fiato = Date.now();
+        while (!completa) {
+            const { bytesRead } = await fh.read(buffer, 0, READ_CHUNK_BYTES, letti);
+            if (bytesRead <= 0)
+                break;
+            letti += bytesRead;
+            const testo = resto + decoder.decode(buffer.subarray(0, bytesRead), { stream: true });
+            if (testo.includes("\u0000"))
+                throw new Error(`${rel} contiene byte NUL (binario): read_file lavora solo su testo`);
+            const pezzi = testo.split("\n");
+            resto = pezzi.pop() ?? "";
+            for (const pezzo of pezzi) {
+                if (riga >= inizio && riga < fine)
+                    finestra.push(pezzo);
+                riga += 1;
+                if (riga >= fine) {
+                    completa = true;
+                    break;
+                }
+            }
+            if (!completa && letti >= READ_SCAN_MAX_BYTES) {
+                fermatoAlTetto = true;
+                break;
+            }
+            if (Date.now() - fiato > BREATH_EVERY_MS) {
+                fiato = Date.now();
+                await respiro();
+            }
+        }
+        if (!completa && !fermatoAlTetto && resto && riga >= inizio && riga < fine) {
+            finestra.push(resto); // ultima riga senza newline finale
+            riga += 1;
+        }
+    }
+    finally {
+        await fh.close();
+    }
+    const mb = (taglia / 1_000_000).toFixed(1);
+    const da = inizio + 1;
+    const a = inizio + finestra.length;
+    const nota = fermatoAlTetto
+        ? `\n[file grande (${mb} MB): scansione fermata a ${Math.round(READ_SCAN_MAX_BYTES / 1_000_000)} MB prima di raggiungere la riga ${da}. `
+            + "Per righe cosi' profonde localizzale prima con grep (path=file) e poi rileggi con offset vicino.]"
+        : `\n[file grande (${mb} MB): righe ${da}-${a}${completa ? "" : " (fine file)"}. Naviga con offset/limit; per cercare usa grep.]`;
+    if (!finestra.length && !fermatoAlTetto) {
+        return `(nessuna riga da ${da}: il file ha ${riga} righe)` + nota;
+    }
+    return paginate(finestra.join("\n"), `file ${rel}`, ctx) + nota;
+}
+export const readTool = {
+    name: "read_file",
+    execution: "parallel",
+    description: "Legge un file di testo (path libero). Per sbirciarne solo una porzione usa " +
+        "`offset` (riga di partenza, 1-based) e `limit` (numero di righe): NON serve bash/head/cat.",
+    schema: {
+        type: "object",
+        properties: {
+            path: { type: "string" },
+            offset: { type: "number", description: "riga di partenza (1-based), default 1" },
+            limit: { type: "number", description: "numero massimo di righe da leggere" },
+        },
+        required: ["path"],
+    },
+    handler: async (input, ctx) => {
+        try {
+            const rel = String(input["path"] ?? "").trim();
+            if (!rel)
+                return toolError("errore: campo 'path' mancante o vuoto");
+            const abs = await safePath(ctx.cwd, rel, ctx.fsRoots);
+            const conflicts = ctx.fileCoordination?.hub.observe(abs, ctx.fileCoordination.actor) ?? [];
+            if (conflicts.length) {
+                ctx.fileCoordination?.emit?.({
+                    phase: "observed", path: abs, actor: ctx.fileCoordination.actor,
+                    mode: "viewing", others: conflicts, at: Date.now(),
+                });
+            }
+            const offset = typeof input["offset"] === "number" && input["offset"] > 0 ? Math.floor(input["offset"]) : 1;
+            const limit = typeof input["limit"] === "number" && input["limit"] > 0 ? Math.floor(input["limit"]) : 0;
+            // I file grandi non si leggono mai integrali: finestra incrementale.
+            const taglia = (await stat(abs)).size;
+            const notaPresenza = conflicts.length
+                ? `\n[coordinamento file: ${formatFileConflicts(conflicts)}. Leggi pure, ma non scrivere finche' la modifica e' attiva.]`
+                : "";
+            if (taglia > READ_FINESTRA_BYTES)
+                return await leggiFinestra(abs, rel, taglia, offset, limit, ctx) + notaPresenza;
+            const full = await readFile(abs, "utf8");
+            if (offset <= 1 && limit <= 0)
+                return paginate(full, `file ${rel}`, ctx) + notaPresenza;
+            // Lettura parziale per righe (stile Claude Code): porzione [offset, offset+limit).
+            const lines = full.split("\n");
+            const start = Math.min(offset - 1, lines.length);
+            const slice = limit > 0 ? lines.slice(start, start + limit) : lines.slice(start);
+            const note = start + slice.length < lines.length || start > 0
+                ? `\n[righe ${start + 1}-${start + slice.length} di ${lines.length}]`
+                : "";
+            return paginate(slice.join("\n"), `file ${rel}`, ctx) + note + notaPresenza;
+        }
+        catch (err) {
+            return toolError(`errore lettura: ${err.message}`);
+        }
+    },
+};
+function acquireFileWrite(ctx, abs) {
+    const coordination = ctx.fileCoordination;
+    if (!coordination)
+        return "";
+    const outcome = coordination.hub.acquire(abs, coordination.actor);
+    if (!outcome.ok) {
+        coordination.emit?.({
+            phase: "blocked", path: abs, actor: coordination.actor,
+            mode: "writing", others: outcome.conflicts, at: Date.now(),
+        });
+        return `conflitto file: ${formatFileConflicts(outcome.conflicts)}. `
+            + "La scrittura non e' partita: coordina il lavoro, attendi la fine della modifica e rileggi il file prima di riprovare.";
+    }
+    coordination.emit?.({
+        phase: "acquired", path: abs, actor: coordination.actor,
+        mode: "writing", others: [], at: Date.now(),
+    });
+    return outcome.lease;
+}
+function validateFileWrite(ctx, lease) {
+    if (typeof lease === "string" || !ctx.fileCoordination)
+        return null;
+    const conflicts = ctx.fileCoordination.hub.validate(lease);
+    if (!conflicts.length)
+        return null;
+    ctx.fileCoordination.emit?.({
+        phase: "blocked", path: lease.path, actor: lease.actor,
+        mode: "writing", others: conflicts, at: Date.now(),
+    });
+    return `conflitto file sopraggiunto: ${formatFileConflicts(conflicts)}. `
+        + "La scrittura e' stata annullata senza sovrascrivere il lavoro concorrente.";
+}
+function releaseFileWrite(ctx, lease) {
+    if (typeof lease === "string" || !ctx.fileCoordination)
+        return;
+    ctx.fileCoordination.hub.release(lease);
+    ctx.fileCoordination.emit?.({
+        phase: "released", path: lease.path, actor: lease.actor,
+        mode: "writing", others: [], at: Date.now(),
+    });
+}
+async function fileVersion(path) {
+    try {
+        const info = await stat(path);
+        return { exists: true, size: info.size, mtimeMs: info.mtimeMs };
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { exists: false, size: 0, mtimeMs: 0 };
+        throw error;
+    }
+}
+function sameFileVersion(a, b) {
+    return a.exists === b.exists && a.size === b.size && a.mtimeMs === b.mtimeMs;
+}
+function diskConflict(ctx, path) {
+    const actor = fileActor("external-filesystem", "Un'altra applicazione", "external");
+    const presence = { path, mode: "editing", actor, updatedAt: Date.now() };
+    ctx.fileCoordination?.emit?.({
+        phase: "blocked", path, actor: ctx.fileCoordination.actor,
+        mode: "writing", others: [presence], at: Date.now(),
+    });
+    return "conflitto file: il contenuto sul disco e' cambiato mentre l'operazione attendeva. "
+        + "La scrittura e' stata annullata; rileggi il file e integra la versione piu' recente prima di riprovare.";
+}
+// Prevenzione byte NUL: i modelli ogni tanto emettono \u0000 letterali dentro
+// content/old_string/new_string. Un NUL in un file di testo lo fa trattare da
+// binario a valle (grep lo salta, gli edit successivi falliscono "string not
+// found" in modi misteriosi): si rimuove sempre e lo si dichiara nel risultato.
+function senzaByteNul(testo) {
+    const pulito = testo.split("\u0000").join("");
+    return { testo: pulito, rimossi: testo.length - pulito.length };
+}
+export const writeTool = {
+    name: "write_file",
+    description: "Scrive un file. Con append=false (default) crea o sovrascrive; con append=true accoda. " +
+        "Per file lunghi scrivi in piu' chiamate (prima crea, poi append=true) per evitare il troncamento da limite di output. Richiede conferma.",
+    schema: {
+        type: "object",
+        properties: {
+            path: { type: "string" },
+            content: { type: "string" },
+            append: { type: "boolean", description: "se true accoda invece di sovrascrivere (default false)" },
+        },
+        required: ["path", "content"],
+    },
+    handler: async (input, ctx) => {
+        try {
+            ctx.signal.throwIfAborted();
+            const rel = String(input["path"] ?? "").trim();
+            if (!rel) {
+                return toolError("errore: campo 'path' mancante o vuoto. Se stavi scrivendo un file grande, " +
+                    "l'input potrebbe essere stato TRONCATO dal limite di output: riscrivilo in piu' chiamate " +
+                    "write_file piu' corte (la prima crea, le successive con append=true).");
+            }
+            if (input["content"] === undefined || input["content"] === null) {
+                return toolError("errore: campo 'content' mancante (passa il contenuto del file)");
+            }
+            const abs = await safePath(ctx.cwd, rel, ctx.fsRoots);
+            ctx.signal.throwIfAborted();
+            const lease = acquireFileWrite(ctx, abs);
+            if (typeof lease === "string" && lease)
+                return { output: lease, isError: true };
+            const append = input["append"] === true;
+            try {
+                const before = await fileVersion(abs);
+                ctx.signal.throwIfAborted();
+                const ok = await ctx.confirm("write_file", `${append ? "append " : ""}${rel}`);
+                ctx.signal.throwIfAborted();
+                if (!ok)
+                    return toolError("scrittura rifiutata dall'utente");
+                const conflict = validateFileWrite(ctx, lease);
+                if (conflict)
+                    return { output: conflict, isError: true };
+                if (!sameFileVersion(before, await fileVersion(abs))) {
+                    return { output: diskConflict(ctx, abs), isError: true };
+                }
+                ctx.signal.throwIfAborted();
+                await mkdir(dirname(abs), { recursive: true });
+                ctx.signal.throwIfAborted();
+                const { testo: contenuto, rimossi } = senzaByteNul(String(input["content"]));
+                await writeFile(abs, contenuto, { encoding: "utf8", flag: append ? "a" : "w" });
+                const notaNul = rimossi
+                    ? `\n[prevenzione: rimossi ${rimossi} byte NUL dal contenuto (mai legittimi in un file di testo)]`
+                    : "";
+                return `${append ? "accodato" : "scritto"}: ${rel}${notaNul}`;
+            }
+            finally {
+                releaseFileWrite(ctx, lease);
+            }
+        }
+        catch (err) {
+            return toolError(`errore scrittura: ${err.message}`);
+        }
+    },
+};
+// Rileva lo stile di fine riga dominante in un testo (CRLF se prevale, altrimenti LF).
+function dominantEol(text) {
+    let crlf = 0;
+    let lf = 0;
+    for (let i = 0; i < text.length; i += 1) {
+        if (text[i] === "\n") {
+            if (text[i - 1] === "\r")
+                crlf += 1;
+            else
+                lf += 1;
+        }
+    }
+    return crlf > lf ? "\r\n" : "\n";
+}
+// Normalizza tutte le terminazioni di riga a LF (per confronti EOL-insensibili).
+function toLF(text) {
+    return text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+// Rimuove gli spazi/tab a fine riga (per confronti trailing-ws-insensibili).
+function stripTrailingWs(text) {
+    return toLF(text).replace(/[ \t]+(?=\n)/g, "").replace(/[ \t]+$/, "");
+}
+// Costruisce una mappa: indice nella versione LF -> indice nel testo originale.
+function lfIndexToOriginal(orig) {
+    const map = [];
+    for (let i = 0; i < orig.length; i += 1) {
+        if (orig[i] === "\r" && orig[i + 1] === "\n")
+            continue;
+        map.push(i);
+    }
+    map.push(orig.length);
+    return map;
+}
+// Mappa: indice nella versione stripped (LF + no trailing ws) -> indice originale.
+function strippedIndexToOriginal(orig) {
+    const map = [];
+    for (let i = 0; i < orig.length; i += 1) {
+        const c = orig[i];
+        if (c === "\r" && orig[i + 1] === "\n")
+            continue;
+        if (c === " " || c === "\t") {
+            let j = i;
+            while (orig[j] === " " || orig[j] === "\t")
+                j += 1;
+            const atLineEnd = j >= orig.length || orig[j] === "\n" || (orig[j] === "\r" && orig[j + 1] === "\n");
+            if (atLineEnd)
+                continue;
+        }
+        map.push(i);
+    }
+    map.push(orig.length);
+    return map;
+}
+// Trova in `cur` l'unica occorrenza di `old` e ritorna il contenuto con `next`
+// al suo posto. Tollerante alle differenze che facevano fallire il match:
+// 1) esatto; 2) CRLF vs LF (il file e' CRLF ma old_string arriva con LF);
+// 3) whitespace a fine riga. L'EOL del file e' PRESERVATO nel risultato.
+export function findEditMatch(cur, old, next) {
+    if (old === "")
+        return "errore: old_string vuota";
+    {
+        const count = cur.split(old).length - 1;
+        if (count === 1) {
+            // NB: niente cur.replace(old, next): String.prototype.replace interpreta
+            // i pattern $$, $&, $`, $', $n nella stringa di sostituzione, corrompendo
+            // un new_string che contiene '$'. Usiamo slice indicizzato (letterale).
+            const idx = cur.indexOf(old);
+            const result = cur.slice(0, idx) + next + cur.slice(idx + old.length);
+            return { result, via: "exact" };
+        }
+        if (count > 1)
+            return `errore: old_string presente ${count} volte, deve essere unica`;
+    }
+    const fileEol = dominantEol(cur);
+    const nextEolFixed = toLF(next).replace(/\n/g, fileEol);
+    {
+        const curLF = toLF(cur);
+        const oldLF = toLF(old);
+        const count = curLF.split(oldLF).length - 1;
+        if (count === 1) {
+            const idxLF = curLF.indexOf(oldLF);
+            const map = lfIndexToOriginal(cur);
+            const startOrig = map[idxLF];
+            const endOrig = map[idxLF + oldLF.length];
+            const result = cur.slice(0, startOrig) + nextEolFixed + cur.slice(endOrig);
+            return { result, via: "eol" };
+        }
+        if (count > 1)
+            return `errore: old_string presente ${count} volte (ignorando CRLF/LF), deve essere unica`;
+    }
+    {
+        const curWs = stripTrailingWs(cur);
+        const oldWs = stripTrailingWs(old);
+        const count = oldWs ? curWs.split(oldWs).length - 1 : 0;
+        if (count === 1) {
+            const idxWs = curWs.indexOf(oldWs);
+            const map = strippedIndexToOriginal(cur);
+            const startOrig = map[idxWs];
+            const endOrig = map[idxWs + oldWs.length];
+            const result = cur.slice(0, startOrig) + nextEolFixed + cur.slice(endOrig);
+            return { result, via: "whitespace" };
+        }
+        if (count > 1)
+            return `errore: old_string presente ${count} volte (ignorando spazi a fine riga), deve essere unica`;
+    }
+    return ("errore: old_string non trovata. Verifica di aver copiato il testo ESATTO dal file " +
+        "(inclusa l'indentazione). Questo tool tollera gia' CRLF/LF e spazi a fine riga: " +
+        "se ancora non trova, la stringa differisce nel contenuto, non solo negli a-capo.");
+}
+export const editTool = {
+    name: "edit_file",
+    description: "Sostituisce una stringa esatta in un file. La stringa deve essere unica.",
+    schema: {
+        type: "object",
+        properties: {
+            path: { type: "string" },
+            old_string: { type: "string" },
+            new_string: { type: "string" },
+        },
+        required: ["path", "old_string", "new_string"],
+    },
+    handler: async (input, ctx) => {
+        try {
+            const rel = String(input["path"] ?? "").trim();
+            ctx.signal.throwIfAborted();
+            if (!rel)
+                return toolError("errore: campo 'path' mancante o vuoto");
+            if (input["old_string"] == null || input["new_string"] == null) {
+                return toolError("errore: old_string e new_string sono obbligatorie");
+            }
+            const abs = await safePath(ctx.cwd, rel, ctx.fsRoots);
+            ctx.signal.throwIfAborted();
+            const lease = acquireFileWrite(ctx, abs);
+            if (typeof lease === "string" && lease)
+                return { output: lease, isError: true };
+            try {
+                const pulitoOld = senzaByteNul(String(input["old_string"]));
+                const pulitoNext = senzaByteNul(String(input["new_string"]));
+                const old = pulitoOld.testo;
+                const next = pulitoNext.testo;
+                const cur = await readFile(abs, "utf8");
+                // Un NUL nel file lo rende "binario" per grep e per gli editor: un edit
+                // testuale sopra peggiora solo le cose. Errore chiaro con il rimedio.
+                if (cur.includes("\u0000")) {
+                    return toolError("errore: il file contiene byte NUL (binario o corrotto): edit_file lavora solo su testo. "
+                        + "Risana il file rimuovendo i NUL (o riscrivilo con write_file).");
+                }
+                const match = findEditMatch(cur, old, next);
+                if (typeof match === "string")
+                    return toolError(match); // messaggio d'errore (no/multi match)
+                ctx.signal.throwIfAborted();
+                const ok = await ctx.confirm("edit_file", rel);
+                ctx.signal.throwIfAborted();
+                if (!ok)
+                    return toolError("modifica rifiutata dall'utente");
+                const conflict = validateFileWrite(ctx, lease);
+                if (conflict)
+                    return { output: conflict, isError: true };
+                if (await readFile(abs, "utf8") !== cur) {
+                    return { output: diskConflict(ctx, abs), isError: true };
+                }
+                ctx.signal.throwIfAborted();
+                await writeFile(abs, match.result, "utf8");
+                const hint = match.via === "eol" ? " (match tollerante CRLF/LF)" : match.via === "whitespace" ? " (match ignorando spazi a fine riga)" : "";
+                const notaNul = pulitoOld.rimossi || pulitoNext.rimossi
+                    ? " [prevenzione: byte NUL rimossi dagli argomenti]"
+                    : "";
+                return `modificato: ${rel}${hint}${notaNul}`;
+            }
+            finally {
+                releaseFileWrite(ctx, lease);
+            }
+        }
+        catch (err) {
+            return toolError(`errore modifica: ${err.message}`);
+        }
+    },
+};
+export const fileActivityTool = {
+    name: "file_activity",
+    description: "Mostra chi sta visualizzando o modificando file nel workspace. Usalo prima di coordinare lavoro concorrente; write_file ed edit_file bloccano automaticamente le sovrascritture.",
+    schema: {
+        type: "object",
+        properties: {
+            path: { type: "string", description: "file specifico; senza path mostra tutte le presenze" },
+        },
+    },
+    handler: async (input, ctx) => {
+        const coordination = ctx.fileCoordination;
+        if (!coordination)
+            return "coordinamento file non configurato dall'host";
+        const rawPath = String(input["path"] ?? "").trim();
+        const target = rawPath ? await safePath(ctx.cwd, rawPath, ctx.fsRoots) : undefined;
+        const rows = coordination.hub.list(target, coordination.actor.id);
+        if (!rows.length)
+            return target ? "nessun altro sta lavorando su questo file" : "nessuna attivita' file concorrente";
+        return rows.map((row) => `${row.path}\t${row.mode}\t${row.actor.label}\t${row.actor.kind}`).join("\n");
+    },
+};
+export const lsTool = {
+    name: "list_dir",
+    execution: "parallel",
+    description: "Elenca file e cartelle di una directory del workspace.",
+    schema: {
+        type: "object",
+        properties: { path: { type: "string", description: "default: ." } },
+    },
+    handler: async (input, ctx) => {
+        try {
+            const rel = String(input["path"] ?? ".");
+            const abs = await safePath(ctx.cwd, rel, ctx.fsRoots);
+            const names = await readdir(abs, { withFileTypes: true });
+            // Dirent already carries the type: no per-entry stat, and symlinks are
+            // not followed outside the validated directory.
+            const entries = names.map((entry) => entry.isDirectory() ? `${entry.name}/` : entry.name);
+            return entries.length ? paginate(entries.sort().join("\n"), `directory ${rel}`, ctx) : "(vuota)";
+        }
+        catch (err) {
+            return toolError(`errore list: ${err.message}`);
+        }
+    },
+};
+// recall: cerca nella memoria delle STANZE archiviate (metodo Danilov). Il
+// contesto vivo resta compatto (solo l'indice delle stanze); con recall
+// l'agente recupera a richiesta il dettaglio di 1+ stanze, per query o per id,
+// senza inquinare il contesto con l'intero contenuto delle stanze precedenti.
+export const recallTool = {
+    name: "recall",
+    description: "Cerca nella memoria precedente: attivita archiviate, piano, note, skill, vision e decisioni. " +
+        "Usa `query` per cercare per argomento, `rooms` per id specifici (es. [\"R1\",\"R3\"]), " +
+        "oppure `files` per sapere CHI HA GIA' LAVORATO su un file (es. [\"src/auth/totp.ts\"]). " +
+        "Con `domains` restringi a rooms/plan/notes/skills/vision, oppure a `sessions` per cercare nelle CONVERSAZIONI passate (l ho gia visto, questo errore?). Senza argomenti elenca l indice. " +
+        "Le attivita sono in ORDINE CRONOLOGICO: per riprendere il lavoro del turno precedente preferisci la attivita piu' RECENTE (l'ultima dell'indice, marcata), non quelle piu' vecchie (turni gia' conclusi). " +
+        "Il contesto resta compatto: recupera solo cio' che serve.",
+    schema: {
+        type: "object",
+        properties: {
+            query: { type: "string", description: "Testo da cercare nelle attivita archiviate" },
+            rooms: { type: "array", items: { type: "string" }, description: "Id attivita da recuperare integralmente" },
+            files: { type: "array", items: { type: "string" }, description: "Path: restituisce le attivita che hanno toccato quei file (traversata del grafo)" },
+            expand: { type: "boolean", description: "Se true, apre gruppi e liste fino alle singole attivita" },
+            domains: { type: "array", items: { type: "string" }, description: "Domini memoria: rooms, plan, notes, skills, vision, assets, decisions, contracts, sessions (conversazioni passate)" },
+            mode: { type: "string", enum: ["summary", "full", "evidence"], description: "Formato eventi memoria (default evidence)" },
+            limit: { type: "number", description: "Max risultati (default 5)" },
+        },
+    },
+    handler: async (input, ctx) => {
+        if (!ctx.sessionDir || !(ctx.roomStoreId || ctx.sessionId))
+            return "memoria attivita non disponibile in questo contesto";
+        // In Kingdoms Mode si legge lo store condiviso del regno (roomStoreId).
+        const scope = ctx.roomStoreId ?? ctx.sessionId;
+        const mem = RoomMemory.open(ctx.sessionDir, scope);
+        const eventStore = MemoryStore.open(ctx.sessionDir, scope);
+        const domains = recallDomains(input["domains"]);
+        const wantsRooms = domains.length === 0 || domains.includes("rooms");
+        const eventDomains = recallEventDomains(domains);
+        const mode = recallMode(input["mode"]);
+        const projectScopes = listMemoryScopes(ctx.sessionDir, { excludeScope: scope, limit: 6 });
+        const eventStores = [
+            { scopeId: scope, store: eventStore },
+            ...projectScopes.map((scopeId) => ({ scopeId, store: MemoryStore.open(ctx.sessionDir, scopeId) })),
+        ];
+        const eventCount = eventStores.reduce((sum, s) => sum + s.store.count(), 0);
+        if (!mem.count() && !eventCount)
+            return "nessuna memoria archiviata finora";
+        const rooms = Array.isArray(input["rooms"]) ? input["rooms"].map(String) : [];
+        if (rooms.length) {
+            const found = wantsRooms && mem.count() ? input["expand"] === true ? mem.expandRooms(rooms) : mem.byRooms(rooms) : [];
+            if (!found.length)
+                return `nessuna attivita trovata per: ${rooms.join(", ")}`;
+            return paginate(found.map((r) => r.body).join("\n\n---\n\n"), "attivita", ctx);
+        }
+        // TRAVERSATA DEL GRAFO: "chi ha gia' messo le mani su questo file?".
+        // La BM25 non puo' rispondere — due stanze possono descrivere lo stesso
+        // file con parole del tutto diverse — mentre l'arco stanza->file si'.
+        const files = Array.isArray(input["files"]) ? input["files"].map(String) : [];
+        if (files.length) {
+            if (!wantsRooms || !mem.count())
+                return "memoria attivita vuota: nessun grafo da percorrere";
+            const graph = mem.graph();
+            const ids = [...new Set(files.flatMap((f) => graph.roomsTouching(f)))];
+            if (!ids.length)
+                return `nessuna attivita ha toccato: ${files.join(", ")}`;
+            const found = mem.byRooms(ids);
+            return paginate(found.map((r) => r.body).join("\n\n---\n\n"), "attivita", ctx);
+        }
+        const query = typeof input["query"] === "string" ? input["query"] : "";
+        const limit = typeof input["limit"] === "number" ? input["limit"] : 5;
+        if (!query.trim()) {
+            const blocks = [];
+            if (wantsRooms && mem.count())
+                blocks.push(mem.indexBlock());
+            const events = recentMemoryEvents(eventStores, eventDomains, limit);
+            if (events.length)
+                blocks.push(formatMemoryEvents(events, mode));
+            return clamp(blocks.filter(Boolean).join("\n\n---\n\n") || "nessuna memoria archiviata");
+        }
+        const chunks = [];
+        if (wantsRooms && mem.count()) {
+            // searchGraph: match lessicali + un hop sugli archi. Un vicino entra solo
+            // se batte una coda lessicale debole, ed e' dichiarato come tale.
+            const hits = mem.searchGraph(query, limit);
+            if (hits.length) {
+                chunks.push(hits
+                    .map((h) => h.viaGraph
+                    ? `[via grafo: condivide ${(h.via ?? []).slice(0, 3).join(", ")} con un risultato diretto]\n${h.record.body}`
+                    : h.record.body)
+                    .join("\n\n---\n\n"));
+            }
+        }
+        const eventHits = searchMemoryEvents(eventStores, query, eventDomains, limit);
+        if (eventHits.length)
+            chunks.push(formatMemoryEvents(eventHits, mode));
+        // Ricerca esplicita sulle DECISIONI promosse (dominio decisions): aggiungi
+        // l'indice dedicato DecisionStore quando la query e' sulle decisioni.
+        if (/\bdecisi|\bdecision/i.test(query)) {
+            try {
+                const dec = DecisionStore.open(ctx.sessionDir, ctx.roomStoreId ?? ctx.sessionId);
+                const decHits = dec.search(query, limit);
+                if (decHits.length) {
+                    chunks.push(decHits.map((h) => decisionToRoomRecord(h.event).body).join("\n\n---\n\n"));
+                }
+            }
+            catch {
+                // best-effort
+            }
+        }
+        // Ricerca esplicita sui CONTRATTI promossi (dominio contracts): aggiungi
+        // l'indice dedicato ContractStore quando la query e' su firma/API/callsite.
+        // E' la rete contro i callsite dimenticati dopo un cambio di firma.
+        if (/\bcontract|\bcallsite|\bcall\s*site|\bfirma|\bsignatur|\bapi\b/i.test(query)) {
+            try {
+                const con = ContractStore.open(ctx.sessionDir, ctx.roomStoreId ?? ctx.sessionId);
+                const conHits = con.search(query, limit);
+                if (conHits.length) {
+                    chunks.push(conHits.map((h) => contractToRoomRecord(h.event).body).join("\n\n---\n\n"));
+                }
+            }
+            catch {
+                // best-effort
+            }
+        }
+        // CONVERSAZIONI PASSATE. La memoria curata risponde a "cosa ho deciso"; il
+        // corpus delle sessioni risponde a "l'ho gia' incontrato, questo?". Si
+        // cerca quando il dominio e' chiesto esplicitamente, e comunque quando la
+        // memoria curata non ha trovato niente: e' il momento in cui l'alternativa
+        // sarebbe rispondere "non ricordo" con la risposta a un metro di distanza.
+        const wantsSessions = domains.includes("sessions");
+        if (wantsSessions || !chunks.length) {
+            try {
+                const hits = searchSessions(ctx.sessionDir, query, {
+                    limit: wantsSessions ? limit : 2,
+                    skipId: typeof ctx.sessionId === "string" ? ctx.sessionId : undefined,
+                });
+                const block = formatSessionHits(hits);
+                if (block)
+                    chunks.push(block);
+            }
+            catch {
+                // best-effort: l'indice e' una cache, non una dipendenza
+            }
+        }
+        if (!chunks.length)
+            return `nessuna memoria corrisponde a: ${query}`;
+        return paginate(chunks.join("\n\n---\n\n"), "memoria", ctx);
+    },
+};
+const DEFAULT_EVENT_DOMAINS = ["plan", "vision", "notes", "skills", "assets", "decisions", "contracts", "kingdom", "system"];
+function recallDomains(value) {
+    if (!Array.isArray(value))
+        return [];
+    return [...new Set(value.map(String).map((d) => d.trim().toLowerCase()).filter(Boolean))];
+}
+function recallEventDomains(domains) {
+    if (!domains.length)
+        return DEFAULT_EVENT_DOMAINS;
+    return domains.filter((d) => d !== "rooms");
+}
+function recallMode(value) {
+    return value === "summary" || value === "full" || value === "evidence" ? value : "evidence";
+}
+function recentMemoryEvents(stores, domains, limit) {
+    const pool = stores.flatMap(({ scopeId, store }) => {
+        const events = domains.length
+            ? domains.flatMap((domain) => [...store.query({ domain })])
+            : [...store.all()];
+        return events.map((event) => ({ scopeId, event, score: 0 }));
+    });
+    return pool.sort((a, b) => b.event.createdAt - a.event.createdAt || b.event.id.localeCompare(a.event.id)).slice(0, Math.max(1, limit));
+}
+function searchMemoryEvents(stores, query, domains, limit) {
+    const hits = stores.flatMap(({ scopeId, store }) => {
+        const scoped = domains.length
+            ? domains.flatMap((domain) => [...store.search(query, { domain, limit })])
+            : [...store.search(query, { limit })];
+        return scoped.map((hit) => ({ scopeId, event: hit.event, score: hit.score }));
+    });
+    const seen = new Set();
+    const out = [];
+    for (const hit of hits.sort((a, b) => b.score - a.score)) {
+        const key = `${hit.scopeId}:${hit.event.id}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(hit);
+        if (out.length >= Math.max(1, limit))
+            break;
+    }
+    return out;
+}
+function formatMemoryEvents(hits, mode) {
+    return hits.map((hit) => formatMemoryEvent(hit.scopeId, hit.event, hit.score, mode)).join("\n\n---\n\n");
+}
+function formatMemoryEvent(scopeId, event, score, mode) {
+    const head = `[MEMORIA_EVENTO ${scopeId}/${event.id}] type=${event.type} domain=${event.domain} subject=${event.subject} score=${score.toFixed(3)}`;
+    const links = event.links.length
+        ? `\nLINKS\n${event.links.map((l) => `@link[${l.rel}]: ${l.domain ? `${l.domain}:` : ""}${l.target}`).join("\n")}`
+        : "";
+    if (mode === "summary")
+        return `${head}\nSUMMARY: ${event.summary}${links}`;
+    if (mode === "full")
+        return `${head}\nSUMMARY: ${event.summary}\n\n${event.body || "(nessun body)"}${links}`;
+    return `${head}\nINDICE\n${event.terms.map((t, i) => `${i + 1} = ${t}`).join("\n") || "1 = (nessun termine)"}\n\nDEFINIZIONI\n@evento[${scopeId}/${event.id}]: type=${event.type}, domain=${event.domain}, subject=${event.subject}\n@summary[${scopeId}/${event.id}]: "${event.summary.replace(/"/g, "'")}"\n\nBODY\n${event.body || "(nessun body)"}${links}\n\nOUTPUT: evidenza memoria recuperata.`;
+}
+// image_generate: genera un'immagine via API (OpenAI o compatibile) e la salva
+// nel workspace. L'agente puo' poi mostrarla inline con ![alt](path) (parita'
+// Pi: image generation + inline rendering). Richiede conferma (ha un costo).
+export const imageGenerateTool = {
+    name: "image_generate",
+    description: "Genera un'immagine da un prompt testuale e la salva nel workspace come PNG. " +
+        "Per mostrarla inline, referenziala dopo con ![descrizione](path). Richiede conferma.",
+    schema: {
+        type: "object",
+        properties: {
+            prompt: { type: "string", description: "Descrizione dell'immagine da generare" },
+            path: { type: "string", description: "File di output (default: generated-<ts>.png)" },
+            size: { type: "string", description: "Dimensione es. 1024x1024 (default)" },
+        },
+        required: ["prompt"],
+    },
+    handler: async (input, ctx) => {
+        ctx.signal.throwIfAborted();
+        const prompt = String(input["prompt"] ?? "");
+        if (!prompt)
+            return toolError("errore: prompt vuoto");
+        const env = process.env;
+        const key = String(env["TALOS_OPENAI_API_KEY"] ?? env["OPENAI_API_KEY"] ?? "").trim();
+        if (!key)
+            return toolError("errore: nessuna chiave (imposta OPENAI_API_KEY o TALOS_OPENAI_API_KEY)");
+        const rel = String(input["path"] ?? `generated-${Date.now()}.png`);
+        let abs;
+        try {
+            abs = await safePath(ctx.cwd, rel, ctx.fsRoots);
+        }
+        catch (err) {
+            return toolError(`errore percorso: ${err.message}`);
+        }
+        ctx.signal.throwIfAborted();
+        const ok = await ctx.confirm("image_generate", `${prompt} -> ${rel}`);
+        ctx.signal.throwIfAborted();
+        if (!ok)
+            return toolError("generazione rifiutata dall'utente");
+        const baseUrl = String(env["TALOS_IMAGE_BASE_URL"] ?? "https://api.openai.com/v1").replace(/\/$/, "");
+        const model = String(env["TALOS_IMAGE_MODEL"] ?? "gpt-image-1");
+        const size = String(input["size"] ?? "1024x1024");
+        try {
+            const res = await fetch(`${baseUrl}/images/generations`, {
+                method: "POST",
+                signal: ctx.signal,
+                headers: { "content-type": "application/json", authorization: `Bearer ${key}` },
+                body: JSON.stringify({ model, prompt, size, n: 1 }),
+            });
+            if (!res.ok)
+                return toolError(`errore generazione (${res.status}): ${clamp(await res.text().catch(() => res.statusText))}`);
+            ctx.signal.throwIfAborted();
+            const json = (await res.json());
+            ctx.signal.throwIfAborted();
+            const item = json.data?.[0];
+            if (!item)
+                return toolError("errore: risposta senza immagine");
+            const bytes = item.b64_json
+                ? Buffer.from(item.b64_json, "base64")
+                : item.url
+                    ? Buffer.from(await (await fetch(item.url, { signal: ctx.signal })).arrayBuffer())
+                    : null;
+            if (!bytes)
+                return toolError("errore: nessun dato immagine");
+            ctx.signal.throwIfAborted();
+            await mkdir(dirname(abs), { recursive: true });
+            ctx.signal.throwIfAborted();
+            await writeFile(abs, bytes);
+            return `immagine generata: ${rel} (${bytes.length} byte). Mostrala con ![${prompt.slice(0, 40)}](${rel})`;
+        }
+        catch (err) {
+            return toolError(`errore generazione: ${err.message}`);
+        }
+    },
+};
+// Converte HTML in testo leggibile: rimuove script/style/head, strippa i tag,
+// decodifica le entita' di base, compatta gli spazi. Per la ricerca/documentazione.
+function htmlToText(html) {
+    let s = html;
+    s = s.replace(/<!--[\s\S]*?-->/g, " ");
+    s = s.replace(/<(script|style|head|noscript|svg)[\s\S]*?<\/\1>/gi, " ");
+    s = s.replace(/<\/(p|div|li|tr|h[1-6]|section|article|br|table|ul|ol)>/gi, "\n");
+    s = s.replace(/<li[^>]*>/gi, "\n- ");
+    s = s.replace(/<[^>]+>/g, " ");
+    s = s.replace(/&nbsp;/gi, " ").replace(/&amp;/gi, "&").replace(/&lt;/gi, "<")
+        .replace(/&gt;/gi, ">").replace(/&quot;/gi, '"').replace(/&#39;/gi, "'");
+    s = s.replace(/[ \t]+/g, " ").replace(/\n[ \t]+/g, "\n").replace(/\n{3,}/g, "\n\n");
+    return s.trim();
+}
+// web_fetch: scarica una pagina (ricerca/documentazione) e ne ritorna il testo.
+// Estensione dello "strumento fetch": read-only, fondamentale per arrivare
+// end-to-end (l'agente ricerca prima di costruire).
+export const webFetchTool = {
+    name: "web_fetch",
+    description: "Scarica una pagina web (URL http/https) e ne restituisce il testo leggibile (HTML ripulito). " +
+        "Usalo per ricerca, documentazione e riferimenti prima di implementare.",
+    schema: {
+        type: "object",
+        properties: {
+            url: { type: "string", description: "URL http(s) da scaricare" },
+            max_chars: { type: "number", description: `numero massimo di caratteri (default ${MAX_OUTPUT})` },
+        },
+        required: ["url"],
+    },
+    handler: async (input, ctx) => {
+        const url = String(input["url"] ?? "").trim();
+        if (!/^https?:\/\//i.test(url))
+            return toolError("errore: URL non valido (richiesto http/https)");
+        // Nessun cap di default: la paginazione gestisce gli output lunghi. max_chars
+        // resta come hard cap opzionale se il modello lo specifica.
+        const maxChars = typeof input["max_chars"] === "number" && input["max_chars"] > 0
+            ? input["max_chars"] : 0;
+        const timeoutMs = Number(process.env["TALOS_FETCH_TIMEOUT"]) || 20_000;
+        const signals = [ctx.signal, AbortSignal.timeout(timeoutMs)];
+        const signal = typeof AbortSignal.any === "function" ? AbortSignal.any(signals) : ctx.signal;
+        try {
+            const res = await fetch(url, {
+                signal,
+                redirect: "follow",
+                headers: {
+                    "user-agent": "Mozilla/5.0 (compatible; VascendTalos/1.0; +https://vascend.it)",
+                    accept: "text/html,application/xhtml+xml,application/json;q=0.9,*/*;q=0.8",
+                },
+            });
+            if (!res.ok)
+                return toolError(`errore http ${res.status} ${res.statusText} su ${url}`);
+            const ct = (res.headers.get("content-type") ?? "").toLowerCase();
+            const raw = await res.text();
+            const body = ct.includes("html") ? htmlToText(raw) : raw;
+            // max_chars come hard cap opzionale, poi paginazione (no troncamento secco).
+            const capped = maxChars > 0 && body.length > maxChars ? body.slice(0, maxChars) : body;
+            return `# ${url}\n${paginate(capped, url, ctx) || "(pagina vuota)"}`;
+        }
+        catch (err) {
+            const e = err;
+            if (e.name === "TimeoutError" || e.name === "AbortError")
+                return toolError(`errore: timeout/interruzione scaricando ${url}`);
+            return toolError(`errore fetch: ${e.message}`);
+        }
+    },
+};
+// Directory saltate durante glob/grep (rumore/binari).
+const SEARCH_IGNORE = new Set([
+    "node_modules", ".git", "dist", "build", ".next", ".turbo", ".cache",
+    "coverage", ".venv", "venv", "__pycache__", "target", ".idea", ".vscode",
+]);
+// Estensioni sicuramente binarie: inutile leggerle per una ricerca testuale.
+// Il controllo sul byte NUL a valle resta (per i binari senza estensione nota), ma
+// evitare la lettura INTERA di media e archivi taglia gran parte dell'I/O di
+// una ricerca larga.
+const BINARY_EXTENSIONS = new Set([
+    "png", "jpg", "jpeg", "gif", "webp", "ico", "icns", "bmp", "tiff", "psd",
+    "pdf", "zip", "gz", "tgz", "bz2", "xz", "zst", "rar", "7z", "jar",
+    "exe", "dll", "so", "dylib", "node", "wasm", "class", "pyc", "o", "a",
+    "woff", "woff2", "ttf", "otf", "eot",
+    "mp3", "mp4", "mov", "avi", "webm", "ogg", "wav", "flac",
+    "db", "sqlite", "sqlite3", "bin", "pak", "asar", "lockb", "heic",
+]);
+function estensione(nome) {
+    const dot = nome.lastIndexOf(".");
+    return dot > 0 ? nome.slice(dot + 1).toLowerCase() : "";
+}
+// Respiro per l'event loop: in Horizon questi tool girano IN-PROCESS nel main
+// di Electron. Senza pause il pump dei messaggi Windows resta a secco e il
+// sistema marchia la finestra come "non risponde" (ghost window). Un
+// setImmediate ogni ~15ms tiene la UI viva senza costo misurabile.
+const BREATH_EVERY_MS = 15;
+function respiro() {
+    return new Promise((resolve) => setImmediate(resolve));
+}
+// Concorrenza della lettura file in grep: abbastanza per saturare l'I/O del
+// disco, poco abbastanza da non accumulare burst di split+regex sulla CPU.
+const GREP_CONCURRENCY = 16;
+// Budget di tempo predefinito di una grep. Il respiro dell'event loop tiene
+// la UI viva comunque; il budget evita che un intero turno aspetti minuti una
+// ricerca fuori misura (misurato: ~42s per una grep alla radice del monorepo).
+const GREP_BUDGET_MS = 10_000;
+// Un match si cerca solo nella testa di una riga: oltre questa lunghezza e'
+// quasi certamente un bundle minificato/una sourcemap, e il backtracking del
+// regex JS su pattern tipo `a.*b.*c` diventa quadratico (stalli >1s misurati
+// per un singolo .test).
+const MAX_LINE_SCAN = 2_000;
+// Walk ricorsivo dei file sotto root, saltando le dir ignorate e quelle nascoste.
+// Ritorna quanti file ha VISITATO: e' il costo reale della ricerca, e serve a
+// dire al modello quando sta cercando troppo in largo.
+async function walkFiles(root, maxVisit, onFile) {
+    let visited = 0;
+    let fiato = Date.now();
+    const stack = [root];
+    while (stack.length) {
+        if (Date.now() - fiato > BREATH_EVERY_MS) {
+            fiato = Date.now();
+            await respiro();
+        }
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (visited >= maxVisit)
+                return visited;
+            const full = join(dir, e.name);
+            if (e.isDirectory()) {
+                if (SEARCH_IGNORE.has(e.name) || e.name.startsWith("."))
+                    continue;
+                stack.push(full);
+            }
+            else if (e.isFile()) {
+                visited += 1;
+                if (onFile(full) === false)
+                    return visited; // stop richiesto
+            }
+        }
+    }
+    return visited;
+}
+// Oltre questi file visitati la ricerca e' larga abbastanza da valere un
+// avviso: sotto, il costo e' irrilevante e la nota sarebbe rumore.
+export const WIDE_SEARCH_FILES = 3_000;
+const PROJECT_MARKERS = ["package.json", "pyproject.toml", "Cargo.toml", "go.mod", "pom.xml", "composer.json"];
+// Sottoprogetti di primo livello sotto `root`: una cartella con un marker di
+// progetto o un .git proprio. Un readdir e pochi stat, costo trascurabile.
+async function childProjects(root) {
+    let entries;
+    try {
+        entries = await readdir(root, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const e of entries) {
+        if (!e.isDirectory() || SEARCH_IGNORE.has(e.name) || e.name.startsWith("."))
+            continue;
+        const dir = join(root, e.name);
+        const markers = await Promise.all(PROJECT_MARKERS.map((m) => stat(join(dir, m)).then(() => true, () => false)));
+        const git = await stat(join(dir, ".git")).then(() => true, () => false);
+        if (markers.some(Boolean) || git)
+            found.push(e.name);
+        if (found.length >= 64)
+            break;
+    }
+    return found;
+}
+/**
+ * Nota di ampiezza da appendere al risultato di una ricerca.
+ *
+ * Perche' esiste: con la conversazione puntata alla radice di un monorepo, una
+ * grep cammina su decine di migliaia di file (misurato: 28.575 file, ~25
+ * secondi, contro 137 file della sottocartella del task) e il modello non ha
+ * modo di saperlo — vede solo un risultato lento e rumoroso, e continua a
+ * cercare in largo. Qui il costo diventa esplicito insieme al rimedio: `path`.
+ */
+export async function wideSearchNote(root, visited) {
+    if (visited < WIDE_SEARCH_FILES)
+        return "";
+    const projects = await childProjects(root);
+    if (projects.length < 3)
+        return "";
+    const shown = projects.slice(0, 12).join(", ");
+    const more = projects.length > 12 ? `, +${projects.length - 12}` : "";
+    return `\n[ricerca su ${visited} file: questa radice contiene ${projects.length} progetti (${shown}${more}). `
+        + "Per essere piu' rapido e mirato ripeti con path=<progetto> quando sai gia' dove stai lavorando.]";
+}
+// Converte un glob (*, **, ?) in RegExp ancorata.
+function globToRegExp(glob) {
+    let re = "";
+    for (let i = 0; i < glob.length; i += 1) {
+        const c = glob[i];
+        if (c === "*") {
+            if (glob[i + 1] === "*") {
+                re += ".*";
+                i += 1;
+                if (glob[i + 1] === "/")
+                    i += 1;
+            }
+            else
+                re += "[^/]*";
+        }
+        else if (c === "?")
+            re += "[^/]";
+        else if ("\\^$+.()|{}[]".includes(c))
+            re += "\\" + c;
+        else
+            re += c;
+    }
+    return new RegExp("^" + re + "$");
+}
+function relForward(cwd, abs) {
+    const r = relative(cwd, abs);
+    return (r || abs).split(/[\\/]/).join("/");
+}
+// glob: trova file per pattern di nome (es. "**/*.tsx", "*.json"). Cerca da
+// `path` (default cwd), path liberi. Sostituisce il "find" via bash.
+export const globTool = {
+    name: "glob",
+    execution: "parallel",
+    description: "Trova file per pattern di nome (glob: *, **, ?). Es. \"**/*.tsx\", \"*.json\". " +
+        "Cerca a partire da `path` (default cwd; accetta path assoluto o ../). Salta node_modules/.git ecc.",
+    schema: {
+        type: "object",
+        properties: {
+            pattern: { type: "string", description: "glob del nome file (es. **/*.ts)" },
+            path: { type: "string", description: "directory radice della ricerca (default cwd)" },
+            limit: { type: "number", description: "max risultati (default 100)" },
+        },
+        required: ["pattern"],
+    },
+    handler: async (input, ctx) => {
+        const pattern = String(input["pattern"] ?? "").trim();
+        if (!pattern)
+            return "errore: pattern vuoto";
+        let root;
+        try {
+            root = await safePath(ctx.cwd, String(input["path"] ?? "."), ctx.fsRoots);
+        }
+        catch (err) {
+            return `errore percorso: ${err.message}`;
+        }
+        const limit = typeof input["limit"] === "number" && input["limit"] > 0 ? input["limit"] : 100;
+        const re = globToRegExp(pattern);
+        const matchBase = !pattern.includes("/");
+        const hits = [];
+        const visited = await walkFiles(root, 50_000, (abs) => {
+            const rel = relForward(root, abs);
+            const target = matchBase ? (rel.split("/").pop() ?? rel) : rel;
+            if (re.test(target))
+                hits.push(relForward(ctx.cwd, abs));
+            return hits.length < limit;
+        });
+        const wide = await wideSearchNote(root, visited);
+        if (!hits.length)
+            return `nessun file per: ${pattern} (da ${relForward(ctx.cwd, root)})${wide}`;
+        const more = hits.length >= limit ? `\n…[limite ${limit}; restringi il pattern]` : "";
+        return `${hits.length} file:\n${hits.join("\n")}${more}${wide}`;
+    },
+};
+// grep: cerca un pattern (regex) nel contenuto dei file. Es. trova dove e'
+// definita una funzione. Sostituisce il "grep -r" via bash.
+export const grepTool = {
+    name: "grep",
+    execution: "parallel",
+    description: "Cerca un pattern (regex) nel CONTENUTO dei file e ritorna path:riga: testo. " +
+        "Opz. `glob` per filtrare i file, `path` radice (default cwd, path liberi), `ignore_case`. Salta node_modules/.git ecc.",
+    schema: {
+        type: "object",
+        properties: {
+            pattern: { type: "string", description: "regex da cercare nel contenuto" },
+            path: { type: "string", description: "directory/file radice (default cwd)" },
+            glob: { type: "string", description: "filtro sui nomi file (es. *.ts)" },
+            ignore_case: { type: "boolean", description: "ricerca case-insensitive" },
+            limit: { type: "number", description: "max righe risultato (default 80)" },
+        },
+        required: ["pattern"],
+    },
+    handler: async (input, ctx) => {
+        const pattern = String(input["pattern"] ?? "");
+        if (!pattern)
+            return "errore: pattern vuoto";
+        let re;
+        let patternNotes = [];
+        try {
+            // I modelli scrivono regex in stile ripgrep: le forme traducibili
+            // vengono tradotte invece di far fallire tutta la ricerca.
+            const compiled = compileSearchPattern(pattern, { ignoreCase: input["ignore_case"] === true });
+            re = compiled.regex;
+            patternNotes = compiled.notes;
+        }
+        catch (err) {
+            return toolError(`errore regex: ${err.message}`);
+        }
+        let root;
+        try {
+            root = await safePath(ctx.cwd, String(input["path"] ?? "."), ctx.fsRoots);
+        }
+        catch (err) {
+            return `errore percorso: ${err.message}`;
+        }
+        const limit = typeof input["limit"] === "number" && input["limit"] > 0 ? input["limit"] : 80;
+        const fileGlob = typeof input["glob"] === "string" && input["glob"] ? globToRegExp(input["glob"]) : null;
+        // Budget di tempo: una grep alla radice di un monorepo leggeva ~28.500
+        // file per ~42 secondi misurati, tutti dentro il main di Electron. Oltre
+        // il budget si ritorna quel che c'e', con l'indicazione per restringere.
+        // `max_ms` e' un override fuori schema (test e chiamate programmatiche).
+        const budget = typeof input["max_ms"] === "number" && input["max_ms"] > 0
+            ? Math.min(input["max_ms"], 120_000)
+            : GREP_BUDGET_MS;
+        const scadenza = Date.now() + budget;
+        const out = [];
+        let stop = false;
+        let scaduto = false;
+        const scanFile = async (abs) => {
+            try {
+                const st = await stat(abs);
+                if (st.size > 2_000_000)
+                    return; // salta file enormi
+                const text = await readFile(abs, "utf8");
+                if (text.includes("\u0000"))
+                    return; // binario
+                const rel = relForward(ctx.cwd, abs);
+                const lines = text.split("\n");
+                for (let i = 0; i < lines.length; i += 1) {
+                    const riga = lines[i] ?? "";
+                    // Sonda solo la testa delle righe fuori misura: vedi MAX_LINE_SCAN.
+                    const sonda = riga.length > MAX_LINE_SCAN ? riga.slice(0, MAX_LINE_SCAN) : riga;
+                    if (re.test(sonda)) {
+                        out.push(`${rel}:${i + 1}: ${truncateLine(riga, 200)}`);
+                        if (out.length >= limit) {
+                            stop = true;
+                            return;
+                        }
+                    }
+                }
+            }
+            catch {
+                // file illeggibile: ignora
+            }
+        };
+        // Se root e' un file singolo, scansiona solo quello.
+        let single = false;
+        let visited = 0;
+        let letti = 0;
+        try {
+            single = (await stat(root)).isFile();
+        }
+        catch { /* dir o assente */ }
+        if (single) {
+            await scanFile(root);
+        }
+        else {
+            // Prima il walk (solo readdir, economico) raccoglie i candidati; poi la
+            // lettura dei contenuti va a concorrenza limitata con respiri periodici.
+            // Il fan-out illimitato di prima accodava decine di migliaia di readFile
+            // + split + regex senza mai cedere il passo: in Horizon il main di
+            // Electron restava saturo fino al ghost "non risponde" di Windows.
+            const candidati = [];
+            visited = await walkFiles(root, 50_000, (abs) => {
+                if (stop || ctx.signal?.aborted)
+                    return false;
+                if (Date.now() > scadenza) {
+                    scaduto = true;
+                    return false;
+                }
+                const rel = relForward(root, abs);
+                const base = rel.split("/").pop() ?? rel;
+                if (fileGlob && !fileGlob.test(base) && !fileGlob.test(rel))
+                    return true;
+                if (BINARY_EXTENSIONS.has(estensione(base)))
+                    return true;
+                candidati.push(abs);
+                return true;
+            });
+            let indice = 0;
+            let fiato = Date.now();
+            const operaio = async () => {
+                while (!stop && indice < candidati.length) {
+                    if (ctx.signal?.aborted)
+                        return;
+                    if (Date.now() > scadenza) {
+                        scaduto = true;
+                        return;
+                    }
+                    const abs = candidati[indice];
+                    indice += 1;
+                    letti += 1;
+                    await scanFile(abs);
+                    if (Date.now() - fiato > BREATH_EVERY_MS) {
+                        fiato = Date.now();
+                        await respiro();
+                    }
+                }
+            };
+            await Promise.all(Array.from({ length: GREP_CONCURRENCY }, () => operaio()));
+        }
+        // Le traduzioni applicate al pattern vanno dichiarate: l'agente deve poter
+        // capire perche' una ricerca ha risposto in modo diverso da come l'ha scritta.
+        const note = patternNotes.length ? `[pattern: ${patternNotes.join("; ")}]\n` : "";
+        const wide = single ? "" : await wideSearchNote(root, visited);
+        const tempo = scaduto
+            ? `\n[budget di tempo (${Math.round(budget / 1000)}s) esaurito dopo ${letti} file letti: risultati parziali. `
+                + "Restringi con path=<cartella> e/o glob=<pattern>.]"
+            : "";
+        // La nota di ampiezza serve SOPRATTUTTO quando non si trova nulla: e' li'
+        // che il modello riprova a caso invece di restringere il campo.
+        if (!out.length)
+            return `${note}nessuna corrispondenza per: ${pattern}${tempo}${wide}`;
+        const more = out.length >= limit ? `\n\u2026[limite ${limit}; restringi pattern/glob]` : "";
+        return `${note}${out.length} righe:\n${out.slice(0, limit).join("\n")}${more}${tempo}${wide}`;
+    },
+};
+function truncateLine(s, max) {
+    const t = s.trim();
+    return t.length > max ? t.slice(0, max) + "…" : t;
+}
+// Dove vive il PIANO per questo contesto. In squadra i collaboratori hanno
+// `roomStoreId` = id del regno (memoria delle stanze condivisa), ma il piano che
+// l'utente vede sulla board e' quello della sessione che ha pianificato: senza
+// `planStoreId` le marcature di un collaboratore finivano su un file suo, e la
+// board non si muoveva mai durante un regno.
+//
+// Nessun lock: apertura, mutazione e scrittura sono sincrone dentro un solo
+// handler, quindi due collaboratori dello stesso processo non si interlacciano.
+function planScope(ctx) {
+    return ctx.planStoreId ?? ctx.roomStoreId ?? ctx.sessionId;
+}
+// vascend_plan: l'agente definisce le STANZE CUSTOM del castello per il goal
+// corrente (al posto dei 4 task default). Una stanza per bit one-hot.
+export const vascendPlanTool = {
+    name: "vascend_plan",
+    description: "Definisci i passaggi di quello che stai facendo ADESSO (attivita di un gruppo, piano di lavoro): "
+        + "compaiono sulla board mentre lavori. Se stai eseguendo un nodo di un piano a rami, questi sono i "
+        + "passaggi DI QUEL NODO — il percorso lungo sta un livello sopra e non si tocca da qui. " +
+        "Usalo per pianificare i passi reali invece dei task default. Ogni voce di `tasks` diventa una attivita T01, T02, ... " +
+        "Per piu' workstream crea PIU' gruppi chiamandolo con `group` diversi (piano multi-gruppo). " +
+        "Poi completa ogni attivita completata con vascend_mark. Usa vascend_status per riprendere; " +
+        "vascend_addtasks aggiunge passi senza perdere progressi. Ridefinire un piano diverso richiede replace=true.",
+    schema: {
+        type: "object",
+        properties: {
+            group: { type: "string", description: "slug del gruppo (default \"master\"); slug diversi = gruppi diversi" },
+            title: { type: "string", description: "Titolo del gruppo (sintesi del workstream)" },
+            tasks: {
+                type: "array",
+                minItems: 1,
+                maxItems: 16,
+                items: { type: "string" },
+                description: "Attivita in ordine (max 16), una frase ciascuna. Token inline opzionali (opzioni del piano): " +
+                    "@skill:slug1,slug2 (skill da usare), @file:path1,path2 (file da pre-caricare), @w:1-5 (peso), @compact (punto di compattazione).",
+            },
+            after: { type: "string", description: "slug di un gruppo prerequisito: questo parte dopo che quello e' completo (@after)" },
+            replace: { type: "boolean", description: "Sostituisce esplicitamente un piano diverso, azzerandone stati, note e prove. Default false." },
+        },
+        required: ["tasks"],
+    },
+    handler: async (input, ctx) => {
+        const sid = planScope(ctx);
+        if (!ctx.sessionDir || !sid)
+            return "piano non disponibile in questo contesto";
+        const tasks = taskTitles(input["tasks"]);
+        const store = VascendPlanStore.open(ctx.sessionDir, sid, { strict: true });
+        if (ctx.planCastle)
+            return { output: "il piano assegnato va conservato: usa vascend_status, vascend_mark e vascend_note; chiedi al coordinatore di ridefinirlo", isError: true };
+        const slug = String(input["group"] ?? input["castle"] ?? ctx.kingdom?.self ?? "master").trim() || "master";
+        const after = typeof input["after"] === "string" ? input["after"] : undefined;
+        const title = String(input["title"] ?? "");
+        const existing = store.castle(slug);
+        if (existing && sameCastlePlan(existing, title, tasks, after)) {
+            return `piano [${slug}] gia' presente: stati, note e prove conservati. Usa vascend_status per riprendere.`;
+        }
+        if (existing && input["replace"] !== true) {
+            return { output: `piano [${slug}] conservato: usa vascend_addtasks per aggiungere passi, un altro group per un nuovo lavoro, oppure replace=true per ridefinirlo.`, isError: true };
+        }
+        const proposal = { slug, after: after?.trim(), tasks: [] };
+        const candidate = { ...proposal, title, maskTarget: "0x0000", custom: true };
+        if (planBlockers([...store.castles().filter((castle) => castle.slug !== slug), candidate], slug).some((blocker) => blocker.reason === "cycle")) {
+            return { output: "errore: dipendenza ciclica tra gruppi; correggi after", isError: true };
+        }
+        const plan = store.setCastle(slug, title, tasks, after);
+        const rows = plan.tasks.map((t) => {
+            const tags = [
+                t.skills?.length ? `@skill:${t.skills.join(",")}` : "",
+                t.files?.length ? `@file:${t.files.join(",")}` : "",
+                t.weight ? `@w:${t.weight}` : "",
+                t.compact ? "@compact" : "",
+            ].filter(Boolean).join(" ");
+            return `  ${t.id} ${t.title}${tags ? `  ${tags}` : ""}`;
+        }).join("\n");
+        const total = store.castles().length;
+        const dep = plan.after ? ` (dopo "${plan.after}")` : "";
+        return `gruppo "${plan.title}" [${plan.slug}]${dep} pianificato (${plan.tasks.length} attivita):\n${rows}\n` +
+            `piano: ${total} grupp${total === 1 ? "o" : "i"}. completa ogni attivita con vascend_mark (indica group="${plan.slug}").`;
+    },
+};
+// vascend_note: annota una stanza o un castello (dossier Danilov). Le note
+// restano nel piano e compaiono in /regno; l'agente le usa per ricordare
+// analisi/decisioni/esiti senza inquinare il contesto vivo.
+export const vascendNoteTool = {
+    name: "vascend_note",
+    description: "Aggiungi una nota (dossier) a una attivita o a un gruppo del piano, nel piano di lavoro. " +
+        "Indica `task` (es. \"T02\") per annotare la attivita, oppure ometti `task` per annotare il gruppo. " +
+        "Usa note compatte: analisi, decisione, esito. Le note restano nel piano e si rileggono in /piano.",
+    schema: {
+        type: "object",
+        properties: {
+            group: { type: "string", description: "slug del gruppo (default \"master\")" },
+            task: { type: "string", description: "id attivita (T01) o bit; ometti per annotare il gruppo" },
+            note: { type: "string", description: "testo della nota (compatto, notazione Danilov)" },
+        },
+        required: ["note"],
+    },
+    handler: async (input, ctx) => {
+        const sid = planScope(ctx);
+        if (!ctx.sessionDir || !sid)
+            return "piano non disponibile in questo contesto";
+        const store = VascendPlanStore.open(ctx.sessionDir, sid);
+        if (!store.hasAny())
+            return "nessun gruppo pianificato: usa prima vascend_plan";
+        const slug = String(input["group"] ?? input["castle"] ?? "master");
+        const task = typeof input["task"] === "string" && input["task"] ? input["task"] : null;
+        const ok = store.addNote(slug, task, String(input["note"] ?? ""));
+        if (!ok)
+            return `destinazione non trovata: ${slug}${task ? `/${task}` : ""}`;
+        return `nota aggiunta a ${slug}${task ? `/${task}` : " (gruppo)"}`;
+    },
+};
+// vascend_skill: abbina delle skill a una stanza/castello "in anticipo".
+// Quando poi la stanza viene avviata (vascend_mark running), il contenuto delle
+// skill abbinate viene riportato cosi' l'agente le applica subito.
+export const vascendSkillTool = {
+    name: "vascend_skill",
+    description: "Abbina una o piu' skill a una attivita o gruppo IN ANTICIPO (piano di lavoro). " +
+        "Indica `task` per la attivita, oppure ometti per il gruppo. Le skill abbinate vengono " +
+        "richiamate automaticamente quando avvii la attivita con vascend_mark (status running). " +
+        "Passa `load: true` per ricevere subito il contenuto delle skill risolte.",
+    schema: {
+        type: "object",
+        properties: {
+            group: { type: "string", description: "slug del gruppo (default \"master\")" },
+            task: { type: "string", description: "id attivita (T01) o bit; ometti per il gruppo" },
+            skills: { type: "array", items: { type: "string" }, description: "slug delle skill da abbinare" },
+            load: { type: "boolean", description: "se true, restituisce subito il contenuto delle skill risolte" },
+        },
+        required: ["skills"],
+    },
+    handler: async (input, ctx) => {
+        const sid = planScope(ctx);
+        if (!ctx.sessionDir || !sid)
+            return "piano non disponibile in questo contesto";
+        const store = VascendPlanStore.open(ctx.sessionDir, sid);
+        if (!store.hasAny())
+            return "nessun gruppo pianificato: usa prima vascend_plan";
+        const slug = String(input["group"] ?? input["castle"] ?? "master");
+        const task = typeof input["task"] === "string" && input["task"] ? input["task"] : null;
+        const skills = Array.isArray(input["skills"]) ? input["skills"].map(String) : [];
+        if (!skills.length)
+            return "errore: nessuna skill indicata";
+        const ok = store.bindSkills(slug, task, skills);
+        if (!ok)
+            return `destinazione non trovata: ${slug}${task ? `/${task}` : ""}`;
+        const head = `skill abbinate a ${slug}${task ? `/${task}` : " (gruppo)"}: ${skills.join(", ")}`;
+        if (input["load"] !== true)
+            return head + "\nverranno richiamate all'avvio della attivita (vascend_mark running).";
+        const body = resolveSkillBodies(ctx.cwd, skills);
+        return body ? `${head}\n\n${body}` : `${head}\n(nessuna skill risolta sul disco: verifica gli slug)`;
+    },
+};
+// vascend_addtasks: aggiunge nuove stanze a un castello SENZA resettare quelle
+// gia' fatte. Usato dal revisore per "aggiungerne altre" in corso d'opera.
+export const vascendAddRoomsTool = {
+    name: "vascend_addtasks",
+    description: "Aggiunge nuove attivita (pending) a un gruppo esistente senza toccare quelle gia' completate. " +
+        "I bit proseguono dopo l'ultimo e MASK_TARGET si estende. Stessi token inline di vascend_plan (@skill,@file,@w,@compact).",
+    schema: {
+        type: "object",
+        properties: {
+            group: { type: "string", description: "slug del gruppo (default \"master\")" },
+            tasks: { type: "array", items: { type: "string" }, description: "nuove attivita in ordine" },
+        },
+        required: ["tasks"],
+    },
+    handler: async (input, ctx) => {
+        const sid = planScope(ctx);
+        if (!ctx.sessionDir || !sid)
+            return "piano non disponibile in questo contesto";
+        const store = VascendPlanStore.open(ctx.sessionDir, sid, { strict: true });
+        if (!store.hasAny())
+            return "nessun gruppo pianificato: usa prima vascend_plan";
+        const slug = String(input["group"] ?? input["castle"] ?? "master");
+        const current = store.castle(slug);
+        if (!current)
+            return { output: `gruppo non trovato: ${slug}`, isError: true };
+        if (ctx.planCastle)
+            return { output: "chiedi al coordinatore di estendere il piano condiviso; il tuo mandato copre le attivita gia' assegnate", isError: true };
+        const tasks = taskTitles(input["tasks"], 16 - current.tasks.length);
+        const added = store.addTasks(slug, tasks);
+        if (!added.length)
+            return `gruppo non trovato o limite attivita raggiunto: ${slug}`;
+        const castle = store.castle(slug);
+        const rows = added.map((t) => `  ${t.id} ${t.title}`).join("\n");
+        return `aggiunte ${added.length} attivita a [${slug}]:\n${rows}`;
+    },
+};
+function clampNum(v, def, min, max) {
+    const n = typeof v === "number" && Number.isFinite(v) ? v : def;
+    return Math.min(max, Math.max(min, Math.floor(n)));
+}
+// Attesa interrompibile (Esc -> ctx.signal). Rigetta se abortita.
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const onAbort = () => { cleanup(); reject(new Error("interrotto")); };
+        const cleanup = () => { clearTimeout(t); signal.removeEventListener("abort", onAbort); };
+        if (signal.aborted)
+            return reject(new Error("interrotto"));
+        const t = setTimeout(() => { cleanup(); resolve(); }, ms);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+// Esegue un comando e ritorna il solo exit code (per il polling di wait).
+function runExitCode(command, ctx) {
+    ctx.signal.throwIfAborted();
+    const { shell, args } = resolveShell(command);
+    return new Promise((resolve) => {
+        const child = spawn(shell, args, { cwd: ctx.cwd, windowsHide: true, env: shellEnvironment() });
+        const onAbort = () => { try {
+            child.kill();
+        }
+        catch { /* gia' morto */ } };
+        ctx.signal.addEventListener("abort", onAbort, { once: true });
+        const done = (code) => { ctx.signal.removeEventListener("abort", onAbort); resolve(code); };
+        child.on("error", () => done(1));
+        child.on("exit", (code) => done(code ?? 1));
+    });
+}
+// wait: attende (deploy/CI/servizi). Con `until` fa POLLING con retry: ripete un
+// comando di check a intervalli finche' non riesce (exit 0). Senza, dorme `seconds`.
+export const waitTool = {
+    name: "wait",
+    description: "Attende prima di riprovare (utile dopo un deploy/push, per CI o servizi che si avviano). " +
+        "Con `until` esegue un comando di check a intervalli finche' non riesce (exit 0): retry automatico. " +
+        "Senza `until`, attende solo `seconds`. Interrompibile con Esc.",
+    schema: {
+        type: "object",
+        properties: {
+            seconds: { type: "number", description: "secondi di attesa se non c'e' until (default 5, max 600)" },
+            until: { type: "string", description: "comando shell di check: si ripete finche' exit 0" },
+            interval: { type: "number", description: "secondi tra i tentativi (default 10, max 300)" },
+            attempts: { type: "number", description: "tentativi massimi (default 12, max 120)" },
+        },
+    },
+    handler: async (input, ctx) => {
+        if (ctx.signal.aborted)
+            return toolError("attesa interrotta");
+        const until = typeof input["until"] === "string" ? input["until"].trim() : "";
+        if (!until) {
+            const secs = clampNum(input["seconds"], 5, 1, 600);
+            try {
+                await sleep(secs * 1000, ctx.signal);
+                return `atteso ${secs}s`;
+            }
+            catch {
+                return toolError("attesa interrotta");
+            }
+        }
+        const ok = await ctx.confirm("bash", `wait until: ${until}`);
+        ctx.signal.throwIfAborted();
+        if (!ok)
+            return toolError("attesa con check rifiutata dall'utente");
+        const interval = clampNum(input["interval"], 10, 1, 300);
+        const attempts = clampNum(input["attempts"], 12, 1, 120);
+        for (let i = 1; i <= attempts; i += 1) {
+            const code = await runExitCode(until, ctx);
+            ctx.signal.throwIfAborted();
+            if (code === 0)
+                return `pronto al tentativo ${i}/${attempts} (check OK dopo ~${(i - 1) * interval}s)`;
+            if (i < attempts) {
+                try {
+                    await sleep(interval * 1000, ctx.signal);
+                }
+                catch {
+                    return toolError(`attesa interrotta al tentativo ${i}/${attempts}`);
+                }
+            }
+        }
+        return `non pronto dopo ${attempts} tentativi (~${attempts * interval}s): «${until}» non e' ancora riuscito (riprova o aumenta attempts/interval)`;
+    },
+};
+function fmtMsg(m) {
+    return `[${m.from}${m.to ? `→${m.to}` : "→tutti"}] ${m.text}`;
+}
+// Risolve il corpo di una lista di skill dal disco (parita' hook plugin che
+// inietta la skill custom al volo). Ritorna i corpi delimitati, o "" se nessuna.
+function resolveSkillBodies(cwd, slugs) {
+    const all = discoverSkills(cwd);
+    const parts = [];
+    for (const slug of slugs) {
+        const s = findSkill(all, slug);
+        if (s)
+            parts.push(`----- BEGIN SKILL ${s.name} -----\n${s.body}\n----- END SKILL ${s.name} -----`);
+    }
+    return clamp(parts.join("\n\n"));
+}
+// Pre-carica il CONTENUTO dei file abbinati a una stanza (@file): l'utente li ha
+// allegati al piano perche' servono ALLA stanza, quindi vengono iniettati come
+// se gia' letti (paginati in base al budget di contesto) invece di costringere
+// l'agente a un read_file (spreco di token). Il resto e' raggiungibile con
+// output_page senza rileggere il file.
+async function resolveFileBodies(cwd, files, fsRoots, ctx) {
+    const parts = [];
+    for (const raw of files) {
+        try {
+            const abs = await safePath(cwd, raw, fsRoots);
+            if (!existsSync(abs)) {
+                parts.push(`----- FILE ${raw} (non trovato) -----`);
+                continue;
+            }
+            const content = await readFile(abs, "utf8");
+            parts.push(`----- BEGIN FILE ${raw} -----\n${paginate(content, `file ${raw}`, ctx)}\n----- END FILE ${raw} -----`);
+        }
+        catch (err) {
+            parts.push(`----- FILE ${raw} (errore: ${err.message}) -----`);
+        }
+    }
+    return parts.join("\n\n");
+}
+// vascend_mark: illumina una stanza (o la segna fallita).
+export const vascendMarkTool = {
+    name: "vascend_mark",
+    description: "Aggiorna una attivita: running avvia/riprende, completed conclude, failed registra un blocco, pending rimette in attesa. " +
+        "Un solo running per gruppo; le dipendenze after devono essere concluse. Riaprire richiede nuove prove. " +
+        "Per completed devi allegare evidence concreta (file modificati, test/comando e risultato osservato). " +
+        "Indica la attivita per id (es. \"T02\") o numero bit (0-based), e il `group` se non e' \"master\". Richiede un piano creato con vascend_plan.",
+    schema: {
+        type: "object",
+        properties: {
+            group: { type: "string", description: "slug del gruppo (default \"master\")" },
+            task: { type: "string", description: "id attivita (T01) o numero bit (0-based)" },
+            status: { type: "string", enum: ["pending", "running", "completed", "failed"], description: "default: completed" },
+            evidence: { type: "string", description: "Prova concreta: file/path, test o comando eseguito e relativo risultato. Obbligatoria per completed." },
+        },
+        required: ["task"],
+    },
+    handler: async (input, ctx) => {
+        const sid = planScope(ctx);
+        if (!ctx.sessionDir || !sid)
+            return "piano non disponibile in questo contesto";
+        const store = VascendPlanStore.open(ctx.sessionDir, sid, { strict: true });
+        if (!store.hasAny())
+            return "nessun gruppo pianificato: usa prima vascend_plan";
+        const st = String(input["status"] ?? "completed");
+        const valid = ["pending", "running", "completed", "failed"];
+        if (!valid.includes(st))
+            return { output: "errore: status deve essere pending, running, completed o failed", isError: true };
+        const slug = String(input["group"] ?? input["castle"] ?? ctx.planCastle ?? ctx.kingdom?.self ?? "master").trim() || "master";
+        const taskRef = String(input["task"] ?? "");
+        const evidence = String(input["evidence"] ?? "").trim();
+        const existing = store.castle(slug)?.tasks.find((task) => task.id.toLowerCase() === taskRef.trim().toLowerCase() || String(task.bit) === taskRef.trim());
+        if (!existing)
+            return { output: `attivita non trovata: ${slug}/${taskRef}`, isError: true };
+        if (ctx.planCastle && (ctx.planCastle !== slug || (ctx.planTasks?.length && !ctx.planTasks.includes(existing.id)))) {
+            return { output: "attivita fuori dal mandato assegnato: coordina il cambiamento con team_say", isError: true };
+        }
+        if (st === "running" || st === "completed") {
+            const blockers = planBlockers(store.castles(), slug.trim() || "master");
+            if (blockers.length)
+                return { output: `attivita bloccata dalle dipendenze: ${blockers.map((blocker) => `${blocker.castle} (${blocker.reason})`).join(", ")}. Usa vascend_status.`, isError: true };
+        }
+        if (st === "running") {
+            const running = store.castle(slug)?.tasks.find((task) => task.status === "running" && task.id !== existing.id
+                && (!ctx.planTasks?.length || ctx.planTasks.includes(task.id)));
+            if (running)
+                return { output: `attivita ${running.id} gia' running: completala oppure rimettila pending prima di avviare ${existing.id}`, isError: true };
+        }
+        if (st === "completed" && !isConcreteTaskEvidence(evidence) && !hasTaskEvidence(existing)) {
+            return "attivita NON completata: `evidence` obbligatoria e concreta (indica file/path, test/comando e risultato osservato)";
+        }
+        const hit = store.mark(slug, taskRef, st, evidence || undefined);
+        if (!hit)
+            return `attivita non trovata: ${slug}/${taskRef}`;
+        let out = `[${slug}] ${hit.id} ${hit.mask} -> ${hit.status} (${hit.title})`;
+        // All'avvio della stanza: richiama skill abbinate (in anticipo) e file da
+        // pre-caricare, cosi' l'agente le applica subito (parita' hook plugin).
+        if (st === "running") {
+            const castle = store.castle(slug);
+            const bound = [...new Set([...(hit.skills ?? []), ...(castle?.skills ?? [])])];
+            if (bound.length) {
+                const bodies = resolveSkillBodies(ctx.cwd, bound);
+                out += `\nskill abbinate: ${bound.join(", ")}`;
+                if (bodies)
+                    out += `\n${bodies}`;
+                else
+                    out += " (non risolte sul disco: caricane il contenuto se servono)";
+            }
+            if (hit.files?.length) {
+                const bodies = await resolveFileBodies(ctx.cwd, hit.files, ctx.fsRoots, ctx);
+                out += `\nfile pre-caricati per questa attivita (GIA' in contesto qui sotto, NON rileggerli con read_file):\n${bodies}`;
+            }
+        }
+        // The runtime handles this checkpoint after the complete tool batch.
+        if (st === "completed" && hit.compact) {
+            out += "\nCheckpoint @compact raggiunto: il runtime valuta la compattazione dopo questo batch, conservando piano aperto e lavoro recente.";
+        }
+        return out;
+    },
+};
+// Ranking per keyword: punteggio = quante parole della query compaiono in
+// name+description (case-insensitive). Deterministico, zero dipendenze.
+function keywordScore(query, text) {
+    const terms = query.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 1);
+    if (!terms.length)
+        return 1;
+    const hay = text.toLowerCase();
+    let score = 0;
+    for (const t of terms)
+        if (hay.includes(t))
+            score += 1;
+    return score;
+}
+// tool_search cerca nell'inventario completo. Anche i tool diretti devono
+// risultare: il modello puo' cercare una capability gia' nel prompt per
+// verificarne il nome, e "nessun match" in quel caso sarebbe una bugia.
+// Firma leggibile: nome piu' parametri (quelli opzionali con "?"). Al modello
+// serve sapere COSA passare, non l'intero JSONSchema: quello arriva nella lista
+// strumenti dopo la promozione, dove sta nel prefisso cacheabile.
+function toolSignature(def) {
+    const schema = (def.inputSchema ?? {});
+    const required = new Set((schema.required ?? []).map(String));
+    const keys = Object.keys(schema.properties ?? {});
+    const params = keys.slice(0, 8).map((key) => (required.has(key) ? key : `${key}?`));
+    if (keys.length > params.length)
+        params.push("…");
+    return `${def.name}(${params.join(", ")})`;
+}
+function toolHeadline(def, max = 150) {
+    const text = String(def.description ?? "").replace(/\s+/g, " ").trim();
+    const sentence = text.split(/(?<=[.!?])\s/)[0] ?? text;
+    const line = sentence.length >= 24 ? sentence : text;
+    return line.length > max ? `${line.slice(0, max - 1)}…` : line;
+}
+export const toolSearchTool = {
+    name: "tool_search",
+    description: "Trova e attiva strumenti: names per nomi esatti, query per capacita'. " +
+        "Carica in una chiamata quelli che servono, poi chiamali direttamente; gli schemi " +
+        "entrano nella lista strumenti, senza richiederli di nuovo. Senza names/query elenca " +
+        "l'inventario paginato senza attivarlo; usa offset=next_offset per continuare.",
+    schema: {
+        type: "object",
+        properties: {
+            names: {
+                type: "array",
+                items: { type: "string" },
+                description: "nomi esatti da caricare in un colpo solo, se li conosci",
+            },
+            query: { type: "string", description: "cosa ti serve fare, se non conosci il nome" },
+            limit: { type: "integer", minimum: 1, description: "risultati: query default 5/max 10; elenco default 40/max 100" },
+            offset: { type: "integer", minimum: 0, description: "solo elenco: riprendi da next_offset" },
+        },
+    },
+    handler: async (input, ctx) => {
+        if (ctx.signal?.aborted)
+            return { output: "ricerca annullata", isError: true };
+        if (!ctx.tools)
+            return "catalogo non disponibile in questo contesto";
+        const inventory = toolInventory(ctx.tools);
+        const names = Array.isArray(input["names"])
+            ? [...new Set(input["names"].filter((value) => typeof value === "string")
+                    .map((value) => value.trim()).filter(Boolean))].slice(0, 24)
+            : [];
+        const query = String(input["query"] ?? "").trim();
+        if (!names.length && !query) {
+            const requested = input["limit"];
+            const limit = typeof requested === "number" && Number.isFinite(requested)
+                ? Math.max(1, Math.min(100, Math.floor(requested))) : 40;
+            return toolListTool.handler({ limit, offset: input["offset"] ?? 0 }, ctx);
+        }
+        const requested = input["limit"];
+        const limit = typeof requested === "number" && Number.isFinite(requested)
+            ? Math.max(1, Math.min(10, Math.floor(requested))) : 5;
+        const byName = new Map(inventory.map((def) => [def.name, def]));
+        const exact = names.map((name) => byName.get(name)).filter((def) => !!def);
+        const unknown = names.filter((name) => !byName.has(name));
+        const ranked = query
+            ? inventory
+                .map((def) => ({ def, score: def.name.toLowerCase() === query.toLowerCase()
+                    ? Number.MAX_SAFE_INTEGER : keywordScore(query, `${def.name} ${def.description}`) }))
+                .filter((row) => row.score > 0)
+                .sort((a, b) => b.score - a.score)
+                .slice(0, limit)
+                .map((row) => row.def)
+            : [];
+        const found = [...new Map([...exact, ...ranked].map((def) => [def.name, def])).values()].slice(0, 24);
+        if (!found.length) {
+            const what = names.length ? names.join(", ") : query;
+            return `nessuno strumento per "${what.slice(0, 400)}". `
+                + "Usa tool_search senza names/query per consultare l'inventario paginato.";
+        }
+        // Promozione: da qui in avanti sono tool come tutti gli altri. Se l'host non
+        // la supporta si torna al vecchio comportamento (schema nella risposta),
+        // altrimenti il modello non saprebbe come chiamarli.
+        const canPromote = !ctx.tools.compact && typeof ctx.tools.promote === "function";
+        const promoted = [];
+        if (canPromote) {
+            for (const def of found) {
+                if (ctx.tools.promote(def.name))
+                    promoted.push(def.name);
+            }
+        }
+        const head = canPromote
+            ? (found.length === 1
+                ? "1 strumento pronto all'uso: chiamalo direttamente per nome."
+                : `${found.length} strumenti pronti all'uso: chiamali direttamente per nome.`)
+            : `${found.length === 1 ? "1 strumento trovato" : `${found.length} strumenti trovati`}.`;
+        const lines = found.map((def) => `- ${toolSignature(def)} — ${toolHeadline(def)}`);
+        const tail = unknown.length ? [`Nomi non trovati: ${unknown.join(", ")}.`] : [];
+        if (!canPromote) {
+            return JSON.stringify(found.map((def) => ({
+                name: def.name,
+                description: def.description,
+                inputSchema: def.inputSchema,
+                ...(def.outputSchema ? { outputSchema: def.outputSchema } : {}),
+                ...(def.annotations ? { annotations: def.annotations } : {}),
+                ...(def._meta ? { _meta: def._meta } : {}),
+            })), null, 2);
+        }
+        return [head, ...lines, ...tail].join("\n");
+    },
+};
+// tool_invoke: esegue un tool del catalogo (deferred) per nome. Il tool gira con
+// lo stesso ToolContext (permessi/conferme inclusi).
+export const toolInvokeTool = {
+    name: "tool_invoke",
+    description: "Esegue uno strumento trovato con tool_search, passando i suoi argomenti. " +
+        "Usa `name` (es. \"web_fetch\") e `args` (oggetto conforme allo schema dello strumento).",
+    schema: {
+        type: "object",
+        properties: {
+            name: { type: "string", description: "nome dello strumento da eseguire" },
+            args: { type: "object", description: "argomenti dello strumento" },
+        },
+        required: ["name"],
+    },
+    handler: async (input, ctx) => {
+        if (ctx.signal.aborted)
+            return { output: "chiamata annullata prima dell'esecuzione", isError: true };
+        if (!ctx.tools)
+            return "catalogo non disponibile in questo contesto";
+        const name = String(input["name"] ?? "").trim();
+        if (!name) {
+            return toolError(missingParamError("name", input, '{"name":"read_file","args":{"path":"src/index.ts"}}'));
+        }
+        if (["tool_list", "tool_search", "tool_describe", "tool_invoke"].includes(name)) {
+            return { output: "errore: non si puo' invocare un meta-tool", isError: true };
+        }
+        const tool = ctx.tools.get(name);
+        if (!tool)
+            return { output: `strumento sconosciuto: ${name} (usa tool_search per trovarlo)`, isError: true };
+        const resolved = resolveInvokeArgs(input);
+        if (typeof resolved === "string")
+            return { output: resolved, isError: true };
+        // Gli argomenti passano dalla stessa normalizzazione del dispatch diretto:
+        // un `args` stringificato o tipi stringati non devono far fallire il tool.
+        const args = normalizeToolInput(resolved, tool.inputSchema);
+        return invokeToolCall({ type: "tool_call", id: "invoke-" + crypto.randomUUID(), name, input: args }, ctx);
+    },
+};
+// Ricava gli argomenti da passare al tool bersaglio. Accetta le tre forme che i
+// modelli producono davvero: `args` oggetto, `args` stringa JSON, e argomenti
+// PIATTI accanto a `name`. Ritorna una stringa se l'input non e' interpretabile:
+// in quel caso e' un errore che deve spiegare il formato, non un {} silenzioso
+// che porterebbe il tool a lamentare un parametro mancante.
+function resolveInvokeArgs(input) {
+    const raw = input["args"] ?? input["arguments"] ?? input["parameters"] ?? input["params"] ?? input["input"];
+    if (raw === undefined || raw === null || raw === "") {
+        const { name: _name, ...flat } = input;
+        return flat;
+    }
+    if (typeof raw === "object" && !Array.isArray(raw))
+        return raw;
+    if (typeof raw === "string") {
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                return parsed;
+            }
+        }
+        catch {
+            /* gestito sotto */
+        }
+        return ("errore: `args` deve essere un oggetto conforme allo schema dello strumento " +
+            "(o una stringa JSON valida che lo rappresenti). Ricevuto: " +
+            `${JSON.stringify(raw).slice(0, 120)}. ` +
+            'Esempio: {"name":"read_file","args":{"path":"src/index.ts"}}');
+    }
+    return `errore: \`args\` non valido (${typeof raw}): serve un oggetto con gli argomenti dello strumento.`;
+}
+// skill_search: trova le skill per query (name+description), senza caricarne il corpo.
+export const skillSearchTool = {
+    name: "skill_search",
+    description: "Cerca tra le skill disponibili (capacita' on-demand documentate). Ritorna nome e descrizione; " +
+        "carica il contenuto con skill_load quando serve.",
+    schema: {
+        type: "object",
+        properties: {
+            query: { type: "string", description: "argomento della skill" },
+            limit: { type: "number", description: "max risultati (default 5)" },
+        },
+        required: ["query"],
+    },
+    handler: async (input, ctx) => {
+        const query = String(input["query"] ?? "");
+        const limit = typeof input["limit"] === "number" && input["limit"] > 0 ? input["limit"] : 5;
+        const ranked = discoverSkills(ctx.cwd)
+            .filter((s) => !s.disableModelInvocation)
+            .map((s) => ({ s, score: keywordScore(query, `${s.name} ${s.description}`) }))
+            .filter((x) => x.score > 0)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit)
+            .map((x) => ({ name: x.s.name, description: x.s.description }));
+        if (!ranked.length)
+            return `nessuna skill per "${query}"`;
+        return JSON.stringify(ranked, null, 2);
+    },
+};
+// skill_load: carica il CORPO di una skill (markdown) on-demand.
+export const skillLoadTool = {
+    name: "skill_load",
+    description: "Carica il contenuto completo di una skill (trovata con skill_search) e applicalo.",
+    schema: {
+        type: "object",
+        properties: { name: { type: "string", description: "nome della skill" } },
+        required: ["name"],
+    },
+    handler: async (input, ctx) => {
+        const name = String(input["name"] ?? "").trim();
+        if (!name)
+            return "errore: nome skill mancante";
+        const skill = findSkill(discoverSkills(ctx.cwd), name);
+        if (!skill)
+            return `skill sconosciuta: ${name} (usa skill_search)`;
+        return clamp(`# Skill: ${skill.name}\n\n${skill.body}`);
+    },
+};
+// Tool DEFERRED: nel catalogo (scopribili via tool_search), NON nel system
+// prompt. Primitive di lavoro, domande, stato del piano e discovery restano CORE.
+export const DEFERRED_TOOLS = new Set([
+    ...LEGACY_DISCOVERY_TOOL_NAMES,
+    "web_fetch",
+    "wait",
+    "image_generate",
+    "user_profile",
+    "work_queue",
+    "architecture_map",
+    "vascend_note",
+    "vascend_skill",
+    "vascend_addtasks",
+    "market_compare",
+    // Attese/report vengono promossi dopo l'ingaggio; i piani a rami sono opzionali.
+    "team_wait",
+    "team_report",
+    "ram_plan",
+    "ram_take",
+    "ram_submit",
+    "ram_ask",
+    "ram_judge",
+    "ram_propose",
+    "ram_decide",
+    "ram_tell",
+    "ram_hear",
+]);
+// Quante volte lo STESSO recupero e' stato servito, per sessione. Rete di
+// sicurezza al ciclo: rileggere due volte e' legittimo (fra i due la finestra
+// puo' essersi compattata), dalla terza il contenuto e' certamente gia' li' e
+// ri-servirlo alimenta soltanto il giro a vuoto.
+const pageServed = new Map();
+const REPEAT_LIMIT = 2;
+function countRepeat(sessionId, id, page) {
+    const key = `${sessionId ?? "-"}|${id}|${page}`;
+    const next = (pageServed.get(key) ?? 0) + 1;
+    pageServed.set(key, next);
+    // Tetto alla mappa: e' un contatore di processo, non uno storico.
+    if (pageServed.size > 512) {
+        const oldest = pageServed.keys().next().value;
+        if (oldest !== undefined)
+            pageServed.delete(oldest);
+    }
+    return next;
+}
+// Esposto per i test: il contatore e' di processo e va azzerabile.
+export function resetOutputPageCounters() {
+    pageServed.clear();
+}
+// output_page: recupera una pagina di un output lungo paginato (invece del
+// troncamento). Sempre CORE: il marker di paginazione cita questo tool.
+export const outputPageTool = {
+    name: "output_page",
+    description: "Recupera una pagina di un output lungo (paginato invece che troncato) oppure " +
+        "il testo integrale di un risultato archiviato. Usa l'`id` indicato nel marker " +
+        "(\"pg3\" per un output paginato, \"tr7\" per un risultato archiviato) e la `page`.",
+    schema: {
+        type: "object",
+        properties: {
+            id: { type: "string", description: "id della paginazione (pg3) o dell'archivio (tr7)" },
+            page: { type: "number", description: "numero di pagina (default 2; per gli id tr* default 1)" },
+            scope: { type: "string", description: "scope dell'artefatto condiviso, indicato in team_report" },
+            query: { type: "string", description: "ricerca letterale nel testo integrale; restituisce estratti con offset" },
+            offset: { type: "number", description: "offset carattere iniziale, anche per proseguire una ricerca" },
+            limit: { type: "number", description: "caratteri massimi di testo per ricerca/slice (default 8000, max 30000)" },
+            format: { type: "string", enum: ["text", "metadata", "structured"], description: "structured espone dati originali a tools.$result; metadata espone hash e dimensione" },
+        },
+        required: ["id"],
+    },
+    handler: async (input, ctx) => {
+        const id = String(input["id"] ?? "").trim();
+        if (!id)
+            return "errore: id mancante";
+        const requested = typeof input["page"] === "number" && input["page"] > 0 ? input["page"] : 0;
+        // Gli id `tr*` sono risultati retrocessi a riferimento: il default e' la
+        // PRIMA pagina, perche' del corpo non c'e' piu' niente nel contesto.
+        if (/^tr\d+$/.test(id)) {
+            const page = requested || 1;
+            if (!input["scope"] && !input["query"] && !input["format"] && input["offset"] === undefined && input["limit"] === undefined
+                && ctx.visibleOutputPages?.has(id + ":" + page) && countRepeat(ctx.sessionId, id, page) > REPEAT_LIMIT) {
+                return `${id} pagina ${page} e' gia' stato recuperato in questa sessione e il contenuto e' piu' su `
+                    + "nella conversazione: non viene ripetuto. Se il materiale che ti serve c'e' gia', passa all'azione "
+                    + "(edit_file / write_file); se ti serve altro, leggi la fonte con read_file o grep invece di "
+                    + "rileggere l'archivio.";
+            }
+            return outputArtifact(input, ctx);
+        }
+        const page = requested || 2;
+        if (ctx.visibleOutputPages?.has(id + ":" + page) && countRepeat(ctx.sessionId, id, page) > REPEAT_LIMIT) {
+            return `${id} pagina ${page} e' gia' stato recuperato in questa sessione: il contenuto e' piu' su nella `
+                + "conversazione e non viene ripetuto. Passa all'azione, oppure rileggi la fonte con read_file/grep.";
+        }
+        const out = pageStore.page(id, page);
+        return out ?? `pagina non disponibile: ${id} (scaduta o inesistente; rigenera l'output)`;
+    },
+};
+// architecture_map: mappa architetturale del workspace, disponibile on demand.
+// con cui l'agente si orienta in un progetto sconosciuto e verifica l'impatto
+// architetturale (cicli, confini fra moduli) prima e dopo una modifica.
+export const architectureMapTool = {
+    name: "architecture_map",
+    description: "Mappa architetturale del progetto: moduli (per directory), dipendenze interne, cicli, " +
+        "entry point, hotspot e dipendenze esterne. Usala per orientarti in un codebase o per " +
+        "verificare l'impatto architetturale di una modifica (nuovi cicli, confini violati).",
+    schema: {
+        type: "object",
+        properties: {
+            path: { type: "string", description: "radice da analizzare (default cwd)" },
+            depth: { type: "number", description: "profondita' del raggruppamento in moduli (default 2)" },
+            top: { type: "number", description: "quanti hotspot/dipendenze esterne mostrare (default 10)" },
+        },
+    },
+    handler: async (input, ctx) => {
+        let root;
+        try {
+            root = await safePath(ctx.cwd, String(input["path"] ?? "."), ctx.fsRoots);
+        }
+        catch (err) {
+            return `errore percorso: ${err.message}`;
+        }
+        const depth = typeof input["depth"] === "number" && input["depth"] >= 1 ? Math.floor(input["depth"]) : undefined;
+        const top = typeof input["top"] === "number" && input["top"] >= 3 ? Math.floor(input["top"]) : undefined;
+        try {
+            const map = scanArchitectureMap(root, {
+                ...(depth !== undefined ? { moduleDepth: depth } : {}),
+                ...(top !== undefined ? { top } : {}),
+            });
+            if (!map.files)
+                return `nessun file sorgente riconosciuto sotto: ${root}`;
+            return paginate(renderArchitectureMap(map), `arch ${root}`, ctx) || "(mappa vuota)";
+        }
+        catch (err) {
+            return toolError(`errore analisi architettura: ${err.message}`);
+        }
+    },
+};
+// market_compare: confronta un output (set di feature/capabilities) con gli
+// standard di mercato e le best practice di settore per un dominio, e ritorna
+// score, gap e riferimenti ai concorrenti. DEFERRED (scopribile via
+// tool_search): non occupa il system prompt finche' non serve.
+export const marketCompareTool = {
+    name: "market_compare",
+    description: "Confronta l'output prodotto con gli standard di mercato e le best practice di settore. " +
+        "Passa `domain` (es. auth, billing, observability, saas-backend) e `features` (lista di " +
+        "capabilities/feature prodotte, per id come \"auth.oauth2\" o testo libero). " +
+        "Senza `features` ritorna lo standard del dominio (best practice + concorrenti). " +
+        "Senza `domain` elenca i domini coperti dalla knowledge base.",
+    schema: {
+        type: "object",
+        properties: {
+            domain: { type: "string", description: "dominio di mercato (es. auth, billing, observability)" },
+            features: {
+                type: "array",
+                items: { type: "string" },
+                description: "feature/capabilities prodotte da confrontare con lo standard",
+            },
+        },
+    },
+    handler: async (input) => {
+        const domain = typeof input["domain"] === "string" ? input["domain"].trim() : "";
+        if (!domain) {
+            const doms = knowledgeBase.domains();
+            return `domini coperti: ${doms.join(", ")}\n(passa { domain, features } per il confronto)`;
+        }
+        const features = Array.isArray(input["features"])
+            ? input["features"].map(String).map((s) => s.trim()).filter(Boolean)
+            : [];
+        if (!features.length) {
+            const std = knowledgeBase.marketStandard(domain);
+            if (!std.practices.length && !std.competitors.length)
+                return `nessuno standard noto per il dominio "${domain}"`;
+            const lines = [];
+            lines.push(`@standard[${domain}]: ${std.practices.length} best practice, ${std.competitors.length} concorrenti`);
+            for (const pr of std.practices)
+                lines.push(`  practice ${pr.id} (${pr.importance}) "${pr.title}" -> ${pr.expectation}`);
+            for (const c of std.competitors)
+                lines.push(`  concorrente ${c.id} "${c.name}": ${c.summary}`);
+            return lines.join("\n");
+        }
+        const v = knowledgeBase.compareToMarket(domain, features);
+        return v.summary;
+    },
+};
+// Profilo dell'utente: i fatti che non vanno riscoperti a ogni sessione. Sta nel
+// catalogo (si usa raramente) ma il nudge di persistenza lo nomina, quindi il
+// modello lo trova quando serve.
+export const userProfileTool = {
+    name: "user_profile",
+    description: "Ricorda (o dimentica) un fatto DUREVOLE sulla persona con cui lavori: preferenze di lavoro, "
+        + "decisioni gia' prese da non ridiscutere, vincoli che valgono sempre. Non usarlo per lo stato "
+        + "del progetto (quello va in vascend_note) ne' per dati sensibili. I fatti ricordati entrano "
+        + "all'inizio delle sessioni successive: scrivi frasi brevi e verificabili, non impressioni.",
+    schema: {
+        type: "object",
+        properties: {
+            action: { type: "string", enum: ["remember", "list", "forget"], description: "default remember" },
+            fact: { type: "string", description: "il fatto, in una frase (per remember)" },
+            kind: { type: "string", description: "preference | decision | constraint | context (default preference)" },
+            match: { type: "string", description: "testo o id del fatto da dimenticare (per forget)" },
+        },
+    },
+    handler: async (input, ctx) => {
+        if (!ctx.sessionDir)
+            return "profilo utente non disponibile in questo contesto";
+        const action = String(input["action"] ?? "remember").toLowerCase();
+        if (action === "list") {
+            const profile = readUserProfile(ctx.sessionDir);
+            if (!profile.facts.length)
+                return "nessun fatto ricordato sulla persona";
+            return formatUserProfile(profile, 40);
+        }
+        if (action === "forget") {
+            const match = String(input["match"] ?? input["fact"] ?? "");
+            const done = forgetUserFact(ctx.sessionDir, match);
+            if (!done.removed)
+                return `nessun fatto corrisponde a: ${match}`;
+            return `dimenticat${done.removed === 1 ? "o 1 fatto" : `i ${done.removed} fatti`}`;
+        }
+        const fact = String(input["fact"] ?? "");
+        if (!fact.trim())
+            return "indica `fact`: il fatto da ricordare, in una frase";
+        const done = rememberUserFact(ctx.sessionDir, fact, String(input["kind"] ?? "preference"));
+        if (!done.ok)
+            return "non riesco a scrivere il profilo utente";
+        return done.reinforced
+            ? `fatto rinforzato (${done.profile.facts.length} in totale)`
+            : `fatto ricordato (${done.profile.facts.length} in totale)`;
+    },
+};
+// work_queue: la coda del lavoro autonomo. Serve a due cose opposte e
+// complementari: mettere in coda cio' che emerge (una scoperta, un gate rosso,
+// una richiesta dell'utente) senza interrompere quello che si sta facendo, e
+// guardare lo stato del ciclo. Non esegue: l'esecuzione e' del runner, che apre
+// un agente nuovo per ogni unita'.
+export const workQueueTool = {
+    name: "work_queue",
+    description: "Coda del lavoro autonomo: accoda un'unita' di lavoro (`add`) o guarda lo stato (`list`). "
+        + "Ogni unita' viene eseguita da un agente NUOVO che vede solo il suo brief, quindi il brief "
+        + "deve bastare a lavorare da zero: obiettivo, file coinvolti, come si verifica. "
+        + "Usala quando trovi lavoro che non appartiene a quello che stai facendo adesso.",
+    schema: {
+        type: "object",
+        properties: {
+            action: { type: "string", enum: ["add", "list"], description: "default add" },
+            title: { type: "string", description: "titolo breve dell'unita' (per add)" },
+            brief: { type: "string", description: "briefing autosufficiente: obiettivo, contesto, criterio di verifica" },
+            after: { type: "array", items: { type: "string" }, description: "id delle unita' che devono concludersi prima" },
+            source: { type: "string", description: "da dove viene: utente, verifica, scoperta" },
+        },
+    },
+    handler: async (input, ctx) => {
+        if (!ctx.sessionDir)
+            return "coda di lavoro non disponibile in questo contesto";
+        const scope = ctx.planStoreId ?? ctx.roomStoreId ?? ctx.sessionId ?? "default";
+        const queue = WorkQueue.open(ctx.sessionDir, scope);
+        const action = String(input["action"] ?? "add").toLowerCase();
+        if (action === "list") {
+            queue.sweep();
+            return formatQueue(queue.items());
+        }
+        const title = String(input["title"] ?? "").trim();
+        const brief = String(input["brief"] ?? "").trim();
+        if (!title)
+            return "indica `title`: il titolo dell'unita' di lavoro";
+        if (brief.length < 20) {
+            return "il `brief` deve bastare a un agente che non ha visto questa conversazione: "
+                + "obiettivo, file coinvolti, come si verifica";
+        }
+        const after = Array.isArray(input["after"]) ? input["after"].map(String).slice(0, 12) : [];
+        const item = queue.add({
+            title,
+            brief,
+            ...(after.length ? { after } : {}),
+            source: String(input["source"] ?? "agente"),
+        });
+        const tally = queue.counts();
+        return `${item.id} in coda: ${item.title} (${tally.ready} pronti, ${tally.total} in totale)`;
+    },
+};
+const legacyBuiltinTools = [
+    ...teamTools,
+    ...ramificationTools,
+    userProfileTool,
+    workQueueTool,
+    toolSearchTool,
+    marketCompareTool,
+    toolInvokeTool,
+    skillSearchTool,
+    skillLoadTool,
+    outputPageTool,
+    bashTool,
+    bashOutputTool,
+    runProgramTool,
+    workspaceSessionsTool,
+    webFetchTool,
+    askUserTool,
+    waitTool,
+    globTool,
+    grepTool,
+    readTool,
+    fileActivityTool,
+    writeTool,
+    editTool,
+    lsTool,
+    recallTool,
+    architectureMapTool,
+    imageGenerateTool,
+    vascendPlanTool,
+    vascendStatusTool,
+    vascendMarkTool,
+    vascendNoteTool,
+    vascendSkillTool,
+    vascendAddRoomsTool,
+];
+// Anche l'export SDK e' MCP-native. I singoli literal mantengono `schema` per
+// compatibilita' sorgente, ma il catalogo pubblico offre sempre inputSchema.
+export const builtinTools = legacyBuiltinTools.map((tool) => {
+    const inputSchema = toolInputSchema(tool);
+    return { ...tool, inputSchema, schema: inputSchema,
+        capabilities: BUILTIN_CAPABILITIES[tool.name], continuations: BUILTIN_CONTINUATIONS[tool.name] };
+});