muonroi-cli 1.8.4 → 1.9.0

package/dist/src/tools/registry.js

@@ -6,15 +6,20 @@
  * is sent to the API for all providers (including DeepSeek, Gemini, etc.).
  */
 import { dynamicTool, jsonSchema } from "ai";
+import { registerGsdWorkflowTools } from "../gsd/workflow-tools.js";
+import { requestProactiveCompact } from "../orchestrator/compact-request.js";
+import { requestCouncilConvene } from "../orchestrator/council-request.js";
 import { canonicalizeBashCommand } from "../orchestrator/tool-args-hash.js";
 import { analyzeImageFromSource, askVisionProxy, listCachedImages } from "../providers/mcp-vision-bridge.js";
 import { needsVisionProxy } from "../providers/vision-proxy.js";
+import { loadMcpServers } from "../utils/settings.js";
 import { getBashRun, sliceBashOutput } from "./bash-output-cache.js";
-import { editFile, readFile, writeFile } from "./file.js";
+import { editFile, readFile, readFiles, writeFile } from "./file.js";
 import { FileTracker } from "./file-tracker.js";
-import { analyzeGitCommand, checkPushGate, checkSensitiveStaging, commitBlockedMessage, pushBlockedMessage, recordCommandOutcome, } from "./git-safety.js";
+import { analyzeGitCommand, checkDestructiveOp, checkPushGate, checkSensitiveStaging, commitBlockedMessage, pushBlockedMessage, recordCommandOutcome, } from "./git-safety.js";
 import { executeGrep } from "./grep.js";
 import { registerNativeMuonroiTools } from "./native-tools.js";
+import { registerNativeResearchTools } from "./research.js";
 import { VISION_TOOL_NAMES } from "./vision-gate.js";
 function getSafetyApprovedMap() {
     if (!globalThis.__muonroiSafetyApproved) {
@@ -84,20 +89,38 @@ export function createBuiltinTools(bash, mode, opts) {
     // One tracker per tool registry instance — shared across read/write/edit
     // calls in the same session. Enforces "must read before edit/overwrite".
     const fileTracker = new FileTracker();
+    // Native research tools (fetch_url, web_search) — always available.
+    // These are the in-process replacements for the old external MCP research servers.
+    registerNativeResearchTools(tools);
     // read_file
     tools.read_file = dynamicTool({
-        description: "Read file contents. For large files, you MUST use start_line and end_line to extract only the needed sections (e.g. specific functions). Reading full large files will quickly exhaust your context budget. Use grep or lsp first to find line numbers.",
+        description: "Read file contents. To read SEVERAL files, pass them ALL in one call via file_paths (array) — STRONGLY PREFERRED over issuing separate read_file calls: each extra call re-sends the whole conversation as input, so N single reads cost O(N²) tokens while one batched read costs O(N). For a large SINGLE file, use start_line/end_line to extract only the needed section (start_line/end_line apply to file_path only; file_paths reads whole files). Use grep or lsp first to find line numbers.",
         inputSchema: jsonSchema({
             type: "object",
             properties: {
-                file_path: { type: "string", description: "Path to the file to read" },
-                start_line: { type: "number", description: "First line to read (1-based)" },
-                end_line: { type: "number", description: "Last line to read (1-based)" },
+                file_path: { type: "string", description: "Path to a single file to read (supports start_line/end_line)." },
+                file_paths: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Read MULTIPLE files in ONE call (preferred when you need 2+ files). Each is returned with its own header; each is capped independently so none is dropped. Best for small-to-medium files; for a large file use file_path + line range.",
+                },
+                start_line: { type: "number", description: "First line to read (1-based). Applies to file_path only." },
+                end_line: { type: "number", description: "Last line to read (1-based). Applies to file_path only." },
             },
-            required: ["file_path"],
         }),
         execute: async (input) => {
-            const result = readFile(input.file_path, bash.getCwd(), input.start_line, input.end_line, fileTracker);
+            const batch = Array.isArray(input.file_paths) && input.file_paths.length > 0
+                ? input.file_paths.filter((p) => typeof p === "string" && p.trim() !== "")
+                : [];
+            if (batch.length > 1) {
+                // Per-file fair-share of the output cap so the concatenated result
+                // stays under MAX_TOOL_OUTPUT_CHARS and every file survives (no silent
+                // head/tail drop of whole files). Floor keeps each file legible.
+                const perFileCap = Math.max(4_000, Math.floor(MAX_TOOL_OUTPUT_CHARS / batch.length));
+                return formatResult(readFiles(batch, bash.getCwd(), fileTracker, perFileCap));
+            }
+            const single = batch.length === 1 ? batch[0] : input.file_path;
+            const result = readFile(single, bash.getCwd(), input.start_line, input.end_line, fileTracker);
             return formatResult(result);
         },
     });
@@ -118,6 +141,137 @@ export function createBuiltinTools(bash, mode, opts) {
             return formatResult(result);
         },
     });
+    // compact — agent-initiated proactive context compaction. The model calls
+    // this to shed accumulated tool/conversation history mid-task (freeing
+    // context + resetting tool-call bloat) BEFORE it hits a tool-round limit,
+    // so a long task never gets interrupted. The request is queued here and
+    // consumed by the tool-engine's prepareStep boundary, which forces a
+    // compaction pass before the next LLM step, then the turn continues. A
+    // decisions/facts snapshot is preserved and high-value tool results stay
+    // rehydratable via ee_query "tool-artifact id=…". This is the proactive
+    // counterpart to the reactive tool-limit auto-recover.
+    tools.compact = dynamicTool({
+        description: "Proactively compress THIS turn's accumulated tool/conversation history to free context and reset tool-call bloat, then CONTINUE the task automatically. Call it after a read-heavy stretch (many read_file/grep/bash results) when context feels heavy and BEFORE you approach a tool-round limit — it prevents the 'reached tool limit' interruption entirely. The compaction runs before your next step; older tool results are summarized (a decisions/facts snapshot is kept) and remain rehydratable via ee_query \"tool-artifact id=…\". Do NOT stop after calling it — keep working toward the goal.",
+        inputSchema: jsonSchema({
+            type: "object",
+            properties: {
+                focus: {
+                    type: "string",
+                    description: "Short note on what to keep in mind / preserve after compaction (e.g. the current sub-task).",
+                },
+            },
+        }),
+        execute: async (input) => {
+            requestProactiveCompact(typeof input?.focus === "string" ? input.focus : null);
+            return formatResult({
+                success: true,
+                output: 'Context compaction scheduled — older tool history will be compressed before your next step; continue the task afterward. High-value results stay rehydratable via ee_query "tool-artifact id=…".',
+            });
+        },
+    });
+    // convene_council — agent-initiated multi-model council. The model calls this
+    // when THIS request genuinely warrants a cross-provider debate (conflicting
+    // design tradeoffs, high-stakes decision). The request is queued here; the
+    // tool-engine consumes it from the outer restart loop, runs runCouncilV2 with
+    // convenePath:true (which suppresses ALL hardcoded post-debate decision
+    // surface — no card, no continuation), splices the synthesis into THIS tool's
+    // tool_result, and restarts the step so the model reads the conclusion as the
+    // result and continues. Registered only when the council is usable so the
+    // model never calls a council that cannot convene.
+    if (opts?.councilConfigured) {
+        tools.convene_council = dynamicTool({
+            description: "Convene the multi-model council to debate THIS request. Use ONLY when the task has genuinely conflicting design tradeoffs, needs a cross-provider/second-opinion review, or is a high-stakes architecture/analysis decision where a single model's view is insufficient. It runs a real multi-role debate across several models and returns a synthesized conclusion AS THIS TOOL'S RESULT. Do NOT use it for routine or low-ambiguity work — it is expensive. After calling, read the returned conclusion and continue; nothing is auto-decided for you.",
+            inputSchema: jsonSchema({
+                type: "object",
+                properties: {
+                    reason: {
+                        type: "string",
+                        description: "Why this task needs a multi-model debate (the specific tradeoff or decision at stake).",
+                    },
+                },
+            }),
+            execute: async (input, execOpts) => {
+                const reason = input && typeof input === "object" && typeof input.reason === "string"
+                    ? input.reason
+                    : null;
+                requestCouncilConvene(reason, execOpts?.toolCallId ?? null);
+                return formatResult({
+                    success: true,
+                    output: "Council convening — the multi-model debate runs now and its conclusion replaces this result before your next step. Read the conclusion, then continue.",
+                });
+            },
+        });
+    }
+    // ask_user — agent-initiated question to the human. The model calls this from
+    // its OWN judgment (e.g. after a convene_council conclusion, when it wants a
+    // go/no-go before implementing). The CLI does NOT synthesise options or decide
+    // the branch: question, options, and default all come from the model's input.
+    // execute() BLOCKS until the human answers; the answer becomes the tool result.
+    // Registered only when a UI answerer is wired (opts.askUser present).
+    if (opts?.askUser) {
+        const askUser = opts.askUser;
+        tools.ask_user = dynamicTool({
+            description: "Ask the human user a question and receive their answer AS THIS TOOL'S RESULT. Use when you need a decision, confirmation (e.g. 'proceed with implementation?'), or missing detail that only the user can provide — typically in an interactive discussion, or after a convene_council conclusion when you want a go/no-go before building. Supply the exact `question` and, optionally, `options` the user picks from (omit for a free-text answer). This BLOCKS until the user responds. Nothing is auto-decided: read their answer and continue from your own judgment. Do NOT use it to narrate or for rhetorical questions — only when you genuinely need input to proceed.",
+            inputSchema: jsonSchema({
+                type: "object",
+                properties: {
+                    question: {
+                        type: "string",
+                        description: "The exact question to put to the user.",
+                    },
+                    context: {
+                        type: "string",
+                        description: "Optional short context shown under the question.",
+                    },
+                    options: {
+                        type: "array",
+                        description: "Optional choices the user picks from. Omit for a free-text answer. These are YOUR options — the CLI adds none.",
+                        items: {
+                            type: "object",
+                            properties: {
+                                label: { type: "string", description: "The choice shown to the user." },
+                                description: { type: "string", description: "Optional one-line explanation of the choice." },
+                                value: { type: "string", description: "Optional value returned when picked (defaults to the label)." },
+                            },
+                            required: ["label"],
+                        },
+                    },
+                    defaultIndex: {
+                        type: "number",
+                        description: "Optional index into options for the pre-selected choice (defaults to 0 = first).",
+                    },
+                },
+                required: ["question"],
+            }),
+            execute: async (input) => {
+                const obj = (input && typeof input === "object" ? input : {});
+                const question = typeof obj.question === "string" ? obj.question : "";
+                if (question.trim().length === 0) {
+                    return formatResult({
+                        success: false,
+                        output: "ask_user requires a non-empty `question`.",
+                    });
+                }
+                const rawOptions = Array.isArray(obj.options) ? obj.options : [];
+                const options = rawOptions
+                    .filter((o) => !!o && typeof o === "object")
+                    .map((o) => ({
+                    label: typeof o.label === "string" ? o.label : String(o.label ?? ""),
+                    description: typeof o.description === "string" ? o.description : undefined,
+                    value: typeof o.value === "string" ? o.value : undefined,
+                }))
+                    .filter((o) => o.label.length > 0);
+                const info = {
+                    question,
+                    context: typeof obj.context === "string" ? obj.context : undefined,
+                    options: options.length > 0 ? options : undefined,
+                    defaultIndex: typeof obj.defaultIndex === "number" ? obj.defaultIndex : undefined,
+                };
+                const answer = await askUser(info);
+                return formatResult({ success: true, output: answer });
+            },
+        });
+    }
     // bash — every foreground call goes through here. We track the LAST
     // canonical command + runId in SESSION-SCOPED state so we can inject a
     // reminder when the model issues another bash call that canonicalizes to
@@ -215,6 +369,17 @@ export function createBuiltinTools(bash, mode, opts) {
             // motivation (session 18285908637a). gitSafetyKey is STABLE per process
             // (or the real sessionId) — unlike repeatKey, whose anon fallback changes
             // on every registry rebuild and would silently drop the gate across turns.
+            // Destructive-op guard (pre-execution, any permission mode): block a
+            // command that would irreversibly discard uncommitted work (git
+            // checkout --/restore/reset --hard/clean, git stash drop/clear, or rm of
+            // a tracked file) when there is actually work at risk. Routed as
+            // `destructive-revert` so the tool-engine shows the safety askcard
+            // interactively and hard-blocks headless (autonomous sub-agents) — the
+            // fix for the /ideal plan-adherence agent silently reverting user files.
+            const destructive = checkDestructiveOp(cmd, bash.getCwd());
+            if (destructive.blocked) {
+                return _prefixBlock("destructive-revert", destructive.message);
+            }
             const gitShape = analyzeGitCommand(cmd);
             // Hard-block broad staging when sensitive files are present.
             // This runs PRE-EXECUTION (before bash.execute) regardless of permission mode.
@@ -253,7 +418,20 @@ export function createBuiltinTools(bash, mode, opts) {
                     }
                 }
             }
-            if (input.background) {
+            const isLongRunning = (c) => {
+                const lower = c.toLowerCase().trim();
+                return (/\bvite\b/.test(lower) ||
+                    /\bnodemon\b/.test(lower) ||
+                    /\bwebpack-dev-server\b/.test(lower) ||
+                    /\bnext\s+dev\b/.test(lower) ||
+                    /\bwatch\b/.test(lower) ||
+                    /--watch\b/.test(lower) ||
+                    /\b-w\b/.test(lower) ||
+                    /\bdev-server\b/.test(lower) ||
+                    /\blive-server\b/.test(lower) ||
+                    /\bhttp-server\b/.test(lower));
+            };
+            if (input.background || isLongRunning(cmd)) {
                 const result = await bash.startBackground(input.command);
                 return formatResult(result);
             }
@@ -378,6 +556,9 @@ export function createBuiltinTools(bash, mode, opts) {
     });
     // Agent mode gets write/edit/task/delegate tools
     if (mode === "agent") {
+        // Capture delegation functions for auto-routing logic below
+        const runTaskFn = opts?.runTask;
+        const runDelegationFn = opts?.runDelegation;
         // write_file
         tools.write_file = dynamicTool({
             description: "Create a new file or overwrite an existing file with full content. SAFETY: overwriting an existing file requires you to call read_file on it first in the same session. New-file creation does not.",
@@ -390,6 +571,13 @@ export function createBuiltinTools(bash, mode, opts) {
                 required: ["file_path", "content"],
             }),
             execute: async (input) => {
+                if (!input?.file_path?.trim() || input.content === undefined || input.content === null) {
+                    return {
+                        success: false,
+                        output: 'BLOCKED (empty-write_file): write_file requires non-empty "file_path" and "content". ' +
+                            'Example: {"file_path":"src/foo.ts","content":"export const x = 1;\\n"}',
+                    };
+                }
                 const result = await writeFile(input.file_path, input.content, bash.getCwd(), fileTracker);
                 return {
                     success: result.success,
@@ -412,6 +600,17 @@ export function createBuiltinTools(bash, mode, opts) {
                 required: ["file_path", "old_string", "new_string"],
             }),
             execute: async (input) => {
+                if (!input?.file_path?.trim() ||
+                    input.old_string === undefined ||
+                    input.old_string === null ||
+                    input.new_string === undefined ||
+                    input.new_string === null) {
+                    return {
+                        success: false,
+                        output: "BLOCKED (empty-edit_file): edit_file requires file_path, old_string, and new_string. " +
+                            'Example: {"file_path":"src/foo.ts","old_string":"a","new_string":"b"}',
+                    };
+                }
                 const result = await editFile(input.file_path, input.old_string, input.new_string, bash.getCwd(), fileTracker);
                 return {
                     success: result.success,
@@ -475,9 +674,11 @@ export function createBuiltinTools(bash, mode, opts) {
         });
         // task
         if (opts?.runTask) {
-            const runTask = opts.runTask;
             tools.task = dynamicTool({
-                description: "Delegate a focused foreground task to a sub-agent. Types: general (edit/execute), explore (read-only research), verify (sandbox validation), computer (desktop interaction).",
+                description: "Delegate a FOCUSED, SHORT foreground task to a sub-agent that blocks the current turn until complete. " +
+                    "Use ONLY for quick edit/execute/verify work (default max ~12 rounds). " +
+                    "For long research, exploration, or anything that may take many steps (explore agent), you MUST use the 'delegate' tool instead — it runs in true background and does not block. " +
+                    "Using task for long work will cause stalls and timeouts.",
                 inputSchema: jsonSchema({
                     type: "object",
                     properties: {
@@ -489,13 +690,20 @@ export function createBuiltinTools(bash, mode, opts) {
                         prompt: { type: "string", description: "Detailed instructions for the sub-agent" },
                         maxToolRounds: {
                             type: "number",
-                            description: "Optional maximum tool execution rounds (default is 12 for foreground tasks)",
+                            description: "Optional maximum tool execution rounds. For research/explore use delegate + higher values (default 60); low values (≤20) only for task.",
                         },
                     },
                     required: ["agent", "description", "prompt"],
                 }),
                 execute: async (input) => {
-                    const result = await runTask({
+                    // Auto-route long research (explore agent or high round count) to true background delegation
+                    // to prevent blocking the main turn and causing stall timeouts.
+                    const isLongResearch = input.agent === "explore" || (typeof input.maxToolRounds === "number" && input.maxToolRounds > 25);
+                    const executor = isLongResearch && runDelegationFn ? runDelegationFn : runTaskFn;
+                    if (!executor) {
+                        return { success: false, output: "No delegation executor available." };
+                    }
+                    const result = await executor({
                         agent: input.agent,
                         description: input.description,
                         prompt: input.prompt,
@@ -530,7 +738,10 @@ export function createBuiltinTools(bash, mode, opts) {
         if (opts?.runDelegation) {
             const runDelegation = opts.runDelegation;
             tools.delegate = dynamicTool({
-                description: "Launch a read-only background agent for longer research while you continue working.",
+                description: "Launch a read-only BACKGROUND research agent (usually 'explore') that runs independently in a separate process. " +
+                    "Use this for ANY long-running research, codebase exploration, analysis, or tasks with high maxToolRounds. " +
+                    "Main session continues working immediately. Results are delivered later via notifications or delegation_read. " +
+                    "This is the PREFERRED tool over 'task' for explore/research to avoid blocking and timeouts.",
                 inputSchema: jsonSchema({
                     type: "object",
                     properties: {
@@ -539,7 +750,7 @@ export function createBuiltinTools(bash, mode, opts) {
                         prompt: { type: "string", description: "Detailed research instructions" },
                         maxToolRounds: {
                             type: "number",
-                            description: "Optional maximum tool execution rounds (default is 60 for explore delegations)",
+                            description: "Optional maximum tool execution rounds (high values like 60+ expected for background research; do not use task for high values).",
                         },
                     },
                     required: ["agent", "description", "prompt"],
@@ -652,7 +863,7 @@ export function createBuiltinTools(bash, mode, opts) {
                         // output in-process by toolCallId. For an exact "tool-artifact id=X"
                         // lookup this is the authoritative full content for THIS session and
                         // works even when EE is down — the failure window long sessions hit.
-                        const { findArtifactByQuery, findArtifactOnDisk } = await import("../ee/artifact-cache.js");
+                        const { findArtifactByQuery, findArtifactByHint, findArtifactOnDisk } = await import("../ee/artifact-cache.js");
                         // Lived-experience telemetry: record where the rehydrate came from so
                         // a "cảm nhận trong CLI" question (and the measure-first instrumentation)
                         // sees cache vs disk vs ee vs needed-but-unavailable.
@@ -664,6 +875,15 @@ export function createBuiltinTools(bash, mode, opts) {
                             recordRehydration(mem ? "cache" : "disk");
                             return truncateOutput(`[tool-artifact id=${local.toolCallId} tool=${local.toolName} — rehydrated from ${src}]\n${local.content}`);
                         }
+                        // B (cheap-model anti-mù) — the exact id missed locally. Cheap models
+                        // often pass FILE PATHS instead of the opaque toolCallId, which
+                        // extractArtifactId can't parse. Try a path match against the local
+                        // cache before the EE round-trip so a botched id still recovers.
+                        const fuzzy = findArtifactByHint(query);
+                        if (fuzzy) {
+                            recordRehydration("cache");
+                            return truncateOutput(`[tool-artifact id=${fuzzy.toolCallId} tool=${fuzzy.toolName} — rehydrated by path match; your id was malformed (pass the exact id from the "[… elided id=X …]" stub next time)]\n${fuzzy.content}`);
+                        }
                         // EE fallback (cross-session / post-restart) → raw /api/search exact lookup.
                         const { searchEE } = await import("../ee/search.js");
                         const resp = await searchEE(query, {
@@ -721,6 +941,204 @@ export function createBuiltinTools(bash, mode, opts) {
                 }
             },
         });
+        tools.retrieve_tool_result = dynamicTool({
+            description: "Retrieve the full output of a previous tool call by its tool_call_id. " +
+                "Searches local cache, disk cache, database history (including parent sessions), and remote Experience Engine. " +
+                "Use this to rehydrate elided tool outputs. Optional max_chars and chunk_index allow paginated retrieval.",
+            inputSchema: jsonSchema({
+                type: "object",
+                properties: {
+                    tool_call_id: { type: "string", description: "The unique ID of the tool call (e.g. 'call_123')." },
+                    max_chars: {
+                        type: "number",
+                        description: "Optional character limit for the returned chunk (useful for very large outputs).",
+                    },
+                    chunk_index: {
+                        type: "number",
+                        description: "Optional chunk index if splitting the output by max_chars (0-based, default 0).",
+                    },
+                },
+                required: ["tool_call_id"],
+            }),
+            execute: async (input) => {
+                const toolCallId = typeof input.tool_call_id === "string" ? input.tool_call_id.trim() : "";
+                if (!toolCallId) {
+                    return "ERROR: tool_call_id is required.";
+                }
+                const maxChars = typeof input.max_chars === "number" ? input.max_chars : undefined;
+                const chunkIndex = typeof input.chunk_index === "number" ? input.chunk_index : 0;
+                let content = null;
+                let source = "";
+                // Tier 1: LRU cache
+                try {
+                    const { getArtifact } = await import("../ee/artifact-cache.js");
+                    const tier1 = getArtifact(toolCallId);
+                    if (tier1) {
+                        content = tier1.content;
+                        source = "Tier 1 LRU cache";
+                    }
+                }
+                catch (err) {
+                    console.error(`[tools:retrieve_tool_result] Tier 1 LRU check failed: ${err.message}`);
+                }
+                // Tier 2: Disk cache
+                if (!content) {
+                    try {
+                        const { findArtifactOnDisk } = await import("../ee/artifact-cache.js");
+                        const tier2 = await findArtifactOnDisk(`id=${toolCallId}`);
+                        if (tier2) {
+                            content = tier2.content;
+                            source = "Tier 2 disk cache";
+                        }
+                    }
+                    catch (err) {
+                        console.error(`[tools:retrieve_tool_result] Tier 2 disk check failed: ${err.message}`);
+                    }
+                }
+                // Tier 3: SQLite database
+                if (!content && opts?.sessionId) {
+                    try {
+                        const { getSessionChain } = await import("../storage/index.js");
+                        const { getDatabase } = await import("../storage/db.js");
+                        const chain = getSessionChain(opts.sessionId);
+                        const db = getDatabase();
+                        for (let i = chain.length - 1; i >= 0; i--) {
+                            const row = db
+                                .prepare(`
+                SELECT tr.output_json
+                FROM tool_results tr
+                JOIN tool_calls tc ON tc.id = tr.tool_call_row_id
+                WHERE tc.tool_call_id = ? AND tc.session_id = ?
+                LIMIT 1
+              `)
+                                .get(toolCallId, chain[i]);
+                            if (row?.output_json) {
+                                const parsed = JSON.parse(row.output_json);
+                                if (parsed && typeof parsed === "object") {
+                                    if ("output" in parsed && typeof parsed.output === "string") {
+                                        content = parsed.output;
+                                    }
+                                    else if ("error" in parsed && typeof parsed.error === "string") {
+                                        content = `ERROR: ${parsed.error}`;
+                                    }
+                                    else {
+                                        content = JSON.stringify(parsed);
+                                    }
+                                }
+                                else {
+                                    content = String(parsed);
+                                }
+                                source = `Tier 3 SQLite database (session ${chain[i]})`;
+                                break;
+                            }
+                        }
+                    }
+                    catch (err) {
+                        console.error(`[tools:retrieve_tool_result] Tier 3 DB check failed: ${err.message}`);
+                    }
+                }
+                // Tier 4: Remote EE (behavioral collection only)
+                if (!content) {
+                    try {
+                        const { searchEE } = await import("../ee/search.js");
+                        const resp = await searchEE(`tool-artifact id=${toolCallId}`, {
+                            collections: ["experience-behavioral"],
+                            limit: 1,
+                        });
+                        const bestHit = resp?.points?.[0];
+                        if (bestHit?.text) {
+                            content = bestHit.text;
+                            source = "Tier 4 remote EE (behavioral collection)";
+                        }
+                    }
+                    catch (err) {
+                        console.error(`[tools:retrieve_tool_result] Tier 4 EE check failed: ${err.message}`);
+                    }
+                }
+                if (content === null) {
+                    return `ERROR: Tool result not found for tool_call_id: ${toolCallId} in any tier.`;
+                }
+                const totalLength = content.length;
+                if (maxChars !== undefined && maxChars > 0) {
+                    const totalChunks = Math.ceil(totalLength / maxChars);
+                    const start = chunkIndex * maxChars;
+                    const end = Math.min(start + maxChars, totalLength);
+                    if (start >= totalLength) {
+                        return `ERROR: chunk_index ${chunkIndex} is out of bounds. Total chunks available: ${totalChunks} (max_chars: ${maxChars}, total length: ${totalLength}).`;
+                    }
+                    const chunk = content.slice(start, end);
+                    return JSON.stringify({
+                        tool_call_id: toolCallId,
+                        source,
+                        chunk_index: chunkIndex,
+                        total_chunks: totalChunks,
+                        chunk_length: chunk.length,
+                        total_length: totalLength,
+                        content: chunk,
+                    }, null, 2);
+                }
+                return JSON.stringify({
+                    tool_call_id: toolCallId,
+                    source,
+                    total_length: totalLength,
+                    content,
+                }, null, 2);
+            },
+        });
+        tools.search_session_history = dynamicTool({
+            description: "Search the full message history across all sessions using an FTS5 MATCH expression. " +
+                "Useful to locate past questions, answers, and context across the session lineage.",
+            inputSchema: jsonSchema({
+                type: "object",
+                properties: {
+                    query: {
+                        type: "string",
+                        description: "FTS5 MATCH expression query (e.g. 'compaction AND error' or 'content:Vitest').",
+                    },
+                },
+                required: ["query"],
+            }),
+            execute: async (input) => {
+                const query = typeof input.query === "string" ? input.query.trim() : "";
+                if (!query) {
+                    return "ERROR: query MATCH expression is required.";
+                }
+                try {
+                    const { getDatabase } = await import("../storage/db.js");
+                    const db = getDatabase();
+                    // Wrap FTS search query execution in try-catch to prevent malformed FTS syntax crashes (fixing GAP-03)
+                    const rows = db
+                        .prepare(`
+            SELECT session_id, seq, role, tool_name, content, tool_args, tool_output
+            FROM session_history_fts
+            WHERE session_history_fts MATCH ?
+            ORDER BY rank
+            LIMIT 50
+          `)
+                        .all(query);
+                    if (rows.length === 0) {
+                        return `No session history matched the query: "${query}"`;
+                    }
+                    const results = rows.map((row) => ({
+                        session_id: row.session_id,
+                        seq: row.seq,
+                        role: row.role,
+                        tool_name: row.tool_name ?? undefined,
+                        content: row.content ?? undefined,
+                        tool_args: row.tool_args ?? undefined,
+                        tool_output: row.tool_output ?? undefined,
+                    }));
+                    return JSON.stringify({
+                        query,
+                        match_count: results.length,
+                        results,
+                    }, null, 2);
+                }
+                catch (err) {
+                    return `ERROR: FTS MATCH query failed. The FTS syntax might be malformed: ${err.message}`;
+                }
+            },
+        });
         // Native muonroi-tools builtins — ee_health, ee_feedback, usage_forensics,
         // lsp_query, setup_guide, selfverify_*. These run IN-PROCESS; the CLI no
         // longer self-spawns itself as an MCP server to expose them to its own inner
@@ -728,16 +1146,25 @@ export function createBuiltinTools(bash, mode, opts) {
         // and a seed-time bug once persisted a crashing vitest-worker command). The
         // muonroi-tools MCP server stays only for EXTERNAL agents. See native-tools.ts.
         registerNativeMuonroiTools(tools, { cwd: bash.getCwd() });
+        registerGsdWorkflowTools(tools, {
+            cwd: bash.getCwd(),
+            sessionModelId: opts?.modelId ?? "unknown",
+            sessionId: opts?.sessionId,
+            depth: opts?.depthTier ?? "standard",
+            runTask: opts?.runTask,
+            runDebate: opts?.runDebate,
+        });
     }
     // Vision proxy tools — only for text-only models (DeepSeek, etc.)
     if (opts?.modelId && needsVisionProxy(opts.modelId)) {
         const cwd = bash.getCwd();
         tools.analyze_image = dynamicTool({
-            description: "Proactively analyze an image file via the vision proxy. " +
-                "Use this IMMEDIATELY when you encounter any image file (.png, .jpg, .gif, .webp, .svg, etc.) " +
-                "or when the user references an image. You CANNOT see images — this tool is your eyes. " +
+            description: "Inspect an image and receive a <vision-observation> block — treat the result as your direct sight. " +
+                "Use IMMEDIATELY when you encounter any image file (.png, .jpg, .gif, .webp, .svg, etc.) " +
+                "or when the user references an image. Do not guess visual content. " +
                 "Accepts file paths, data URIs, or base64 strings. " +
-                "Optionally provide a question to focus the analysis.",
+                "Optionally provide a question to focus the analysis (OCR, layout, specific UI element). " +
+                "If details remain unclear, call ask_vision_proxy or ask the user for another screenshot.",
             inputSchema: jsonSchema({
                 type: "object",
                 properties: {
@@ -757,9 +1184,10 @@ export function createBuiltinTools(bash, mode, opts) {
             },
         });
         tools.ask_vision_proxy = dynamicTool({
-            description: "Ask a follow-up question about a previously analyzed image, or analyze a new image with a specific question. " +
-                "Use this when you need to clarify visual details, compare elements, check colors, read text, etc. " +
-                "You can reference a cached image by ID, or provide a file path to analyze a new image.",
+            description: "Ask a follow-up about an image you are viewing (cached ID) or analyze a new file with a specific question. " +
+                "Returns a <vision-observation> — respond as if you saw it yourself. " +
+                "Use when any detail in a prior observation is unclear: zoom on a region, read text, compare colors, verify UI state. " +
+                "Reference a cached image by ID (from list_vision_cache) or provide a file path for a new image.",
             inputSchema: jsonSchema({
                 type: "object",
                 properties: {
@@ -854,6 +1282,131 @@ export function createBuiltinTools(bash, mode, opts) {
         for (const name of VISION_TOOL_NAMES)
             delete tools[name];
     }
+    // ── Agent introspection tools: help the inner agent discover capabilities ──
+    // These are always added last (after all filtering) so list_tools reflects reality.
+    tools.list_mcp_servers = dynamicTool({
+        description: "List every MCP server in the current user config (enabled or not). Returns id, label, enabled, transport, endpoint, and recommended_native (if any). " +
+            "Use this to discover exactly what MCPs you have right now. For each MCP, see if there is a preferred native replacement (e.g. fetch_url instead of legacy fetch). " +
+            "Memory, playwright, figma removed from defaults. Only enabled servers contribute tools this turn.",
+        inputSchema: jsonSchema({
+            type: "object",
+            properties: {},
+            additionalProperties: false,
+        }),
+        execute: async () => {
+            const servers = loadMcpServers();
+            // Native replacement recommendations (helps agent choose better tools)
+            const RECOMMENDATIONS = {
+                fetch: "Prefer native fetch_url (faster, always available, no external spawn).",
+                tavily: "Prefer native web_search (direct Tavily API call, same results).",
+                context7: "Consider keeping for library docs, or cache important docs into Experience Engine for offline use.",
+                "muonroi-docs": null, // already our own controlled service
+                playwright: "Use for full browser interaction/screenshots only; fetch_url sufficient for most content needs.",
+                memory: "Use native ee_query / ee_write (Experience Engine) instead.",
+                figma: "Add manually only if needed; no native equivalent yet.",
+            };
+            const summary = servers.map((s) => {
+                const rec = RECOMMENDATIONS[s.id] ?? null;
+                return {
+                    id: s.id,
+                    label: s.label,
+                    enabled: s.enabled,
+                    transport: s.transport,
+                    endpoint: s.url || (s.command ? `${s.command} ${(s.args || []).join(" ")}` : undefined),
+                    recommended_native: rec,
+                };
+            });
+            return JSON.stringify({ count: summary.length, servers: summary }, null, 2);
+        },
+    });
+    tools.list_tools = dynamicTool({
+        description: "Compact grouped summary of every tool available this turn. " +
+            "native = always-on builtins (fetch_url, web_search, bash, read_file, grep, ee_query, list_mcp_servers, list_tools, ...). " +
+            "mcp = tools from your enabled MCP servers (prefixed mcp_<server-id>__). " +
+            "Each line: name + short description (tells you purpose and rough usage). " +
+            "Call list_mcp_servers() to see your MCP sources, then this to see concrete tools + how to use them. Full parameter schemas are in the system tool list this turn.",
+        inputSchema: jsonSchema({
+            type: "object",
+            properties: {
+                category: {
+                    type: "string",
+                    enum: ["all", "native", "mcp"],
+                    description: "Optional filter.",
+                },
+            },
+            additionalProperties: false,
+        }),
+        execute: async (input) => {
+            const cat = input?.category || "all";
+            const grouped = { native: [], mcp: [] };
+            for (const [name, tool] of Object.entries(tools)) {
+                const t = tool;
+                const shortDesc = (t.description || "").split("\n")[0].slice(0, 140);
+                const entry = `${name}: ${shortDesc}`;
+                if (name.startsWith("mcp_")) {
+                    if (cat === "all" || cat === "mcp")
+                        grouped.mcp.push(entry);
+                }
+                else {
+                    if (cat === "all" || cat === "native")
+                        grouped.native.push(entry);
+                }
+            }
+            grouped.native.sort();
+            grouped.mcp.sort();
+            return JSON.stringify({
+                total: Object.keys(tools).length,
+                native_count: grouped.native.length,
+                mcp_count: grouped.mcp.length,
+                ...grouped,
+                note: "Native tools are always preferred. MCP tools only from servers where enabled=true (see list_mcp_servers).",
+            }, null, 2);
+        },
+    });
+    tools.describe_tool = dynamicTool({
+        description: "Get detailed usage information for a specific tool by name. Returns description, full input schema (parameters), and a short usage example or note. " +
+            "Call this when you need precise 'how to use' details for a tool (e.g. describe_tool with name='fetch_url' or name='mcp_context7__something'). " +
+            "This complements list_tools and list_mcp_servers.",
+        inputSchema: jsonSchema({
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Exact tool name (e.g. 'fetch_url', 'web_search', 'mcp_context7__search' or any from list_tools)",
+                },
+            },
+            required: ["name"],
+            additionalProperties: false,
+        }),
+        execute: async (input) => {
+            const name = typeof input?.name === "string" ? input.name.trim() : "";
+            if (!name)
+                return "ERROR: name is required";
+            const tool = tools[name];
+            if (!tool) {
+                return JSON.stringify({
+                    name,
+                    error: "Tool not found in current tool set. Use list_tools to see available names.",
+                }, null, 2);
+            }
+            const t = tool;
+            const schema = t.inputSchema || tool.parameters || null;
+            // Provide a minimal example note for common tools
+            const examples = {
+                fetch_url: 'Example: {"url": "https://example.com/docs", "format": "markdown"}',
+                web_search: 'Example: {"query": "muonroi building block best practices", "maxResults": 5}',
+                list_mcp_servers: "Call with no args: {}",
+                list_tools: 'Example: {"category": "native"}',
+            };
+            return JSON.stringify({
+                name,
+                description: t.description,
+                inputSchema: schema,
+                example: examples[name] || "See inputSchema above. Call with correct parameters.",
+                note: "Use the exact parameters from inputSchema when calling this tool.",
+            }, null, 2);
+        },
+    });
     return tools;
 }
 //# sourceMappingURL=registry.js.map