@j0hanz/filesystem-mcp 1.11.0 → 1.12.0

package/dist/lib/fs-helpers.js

@@ -1,15 +1,66 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
 import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
 import { isUtf8 } from 'node:buffer';
 import { randomUUID } from 'node:crypto';
-import { Writable } from 'node:stream';
-import { pipeline } from 'node:stream/promises';
 import { BINARY_CHECK_BUFFER_SIZE, KNOWN_BINARY_EXTENSIONS, MAX_TEXT_FILE_SIZE, PARALLEL_CONCURRENCY, } from './constants.js';
 import { ErrorCode, McpError, normalizeUnknownError } from './errors.js';
 import { assertAllowedFileAccess, validateExistingPath } from './paths.js';
 function createAbortError(message = 'Operation aborted') {
     return new DOMException(message, 'AbortError');
 }
+const READ_ONLY_FILE_FLAG = 'r';
 const SHARED_NOOP_SIGNAL = new AbortController().signal;
 function normalizeAbortReason(reason, message) {
     if (reason instanceof Error)
@@ -55,39 +106,22 @@ function getAbortError(signal, message) {
 export function withAbort(promise, signal) {
     if (!signal)
         return promise;
-    assertNotAborted(signal);
+    signal.throwIfAborted();
     return new Promise((resolve, reject) => {
-        let settled = false;
-        const finish = (run) => {
-            if (settled)
-                return;
-            settled = true;
-            signal.removeEventListener('abort', onAbort);
-            run();
-        };
         const onAbort = () => {
-            finish(() => {
-                reject(getAbortError(signal));
-            });
+            reject(getAbortError(signal));
         };
-        signal.addEventListener('abort', onAbort, { once: true });
-        try {
-            signal.throwIfAborted();
-        }
-        catch {
+        if (signal.aborted) {
             onAbort();
             return;
         }
-        promise
-            .then((value) => {
-            finish(() => {
-                resolve(value);
-            });
-        })
-            .catch((error) => {
-            finish(() => {
-                reject(normalizeUnknownError(error));
-            });
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener('abort', onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener('abort', onAbort);
+            reject(normalizeUnknownError(error));
         });
     });
 }
@@ -102,12 +136,12 @@ export function createTimedAbortSignal(baseSignal, timeoutMs) {
         };
     }
     if (baseSignal) {
-        return createForwardedSignal(baseSignal);
+        return { signal: baseSignal, cleanup: () => { } };
     }
     if (timeoutSignal) {
         return { signal: timeoutSignal, cleanup: () => { } };
     }
-    return createNoopSignal();
+    return { signal: SHARED_NOOP_SIGNAL, cleanup: () => { } };
 }
 export async function withTimedAbortSignal(baseSignal, timeoutMs, run) {
     const { signal, cleanup } = createTimedAbortSignal(baseSignal, timeoutMs);
@@ -118,12 +152,6 @@ export async function withTimedAbortSignal(baseSignal, timeoutMs, run) {
         cleanup();
     }
 }
-function createNoopSignal() {
-    return { signal: SHARED_NOOP_SIGNAL, cleanup: () => { } };
-}
-function createForwardedSignal(baseSignal) {
-    return { signal: baseSignal, cleanup: () => { } };
-}
 function createParallelAbortError() {
     return createAbortError();
 }
@@ -193,20 +221,8 @@ function hasKnownBinaryExtension(filePath) {
     const ext = path.extname(filePath).toLowerCase();
     return KNOWN_BINARY_EXTENSIONS.has(ext);
 }
-async function withFileHandle(filePath, fn, existingHandle, signal) {
-    if (existingHandle) {
-        return fn(existingHandle);
-    }
-    const effectivePath = await validateExistingPath(filePath, signal);
-    const handle = await withAbort(fsp.open(effectivePath, 'r'), signal);
-    try {
-        return await fn(handle);
-    }
-    finally {
-        await handle.close().catch((error) => {
-            console.error('Failed to close file handle:', error);
-        });
-    }
+async function openReadableFileHandle(filePath, signal) {
+    return withAbort(fsp.open(filePath, READ_ONLY_FILE_FLAG), signal);
 }
 async function readProbe(handle, signal) {
     const buffer = Buffer.alloc(BINARY_CHECK_BUFFER_SIZE);
@@ -222,13 +238,29 @@ function hasUtf16Bom(slice) {
             (slice[0] === 0xfe && slice[1] === 0xff)));
 }
 export async function isProbablyBinary(filePath, existingHandle, signal) {
-    if (hasKnownBinaryExtension(filePath)) {
-        return true;
-    }
-    return withFileHandle(filePath, async (handle) => {
+    const env_1 = { stack: [], error: void 0, hasError: false };
+    try {
+        if (hasKnownBinaryExtension(filePath)) {
+            return true;
+        }
+        if (existingHandle) {
+            const slice = await readProbe(existingHandle, signal);
+            return isBinarySlice(slice);
+        }
+        const effectivePath = await validateExistingPath(filePath, signal);
+        const handle = __addDisposableResource(env_1, await openReadableFileHandle(effectivePath, signal), true);
         const slice = await readProbe(handle, signal);
         return isBinarySlice(slice);
-    }, existingHandle, signal);
+    }
+    catch (e_1) {
+        env_1.error = e_1;
+        env_1.hasError = true;
+    }
+    finally {
+        const result_1 = __disposeResources(env_1);
+        if (result_1)
+            await result_1;
+    }
 }
 function isBinarySlice(slice) {
     if (slice.length === 0)
@@ -316,42 +348,35 @@ const STREAM_CHUNK_SIZE = 64 * 1024;
 function createTooLargeError(bytesRead, maxSize, requestedPath) {
     return new McpError(ErrorCode.E_TOO_LARGE, `File exceeds maximum size (${bytesRead} > ${maxSize}): ${requestedPath}`, requestedPath, { size: bytesRead, maxSize });
 }
-class BufferCollector extends Writable {
-    #chunks = [];
-    #totalSize = 0;
-    #maxSize;
-    #requestedPath;
-    constructor(maxSize, requestedPath) {
-        super({ autoDestroy: true });
-        this.#maxSize = maxSize;
-        this.#requestedPath = requestedPath;
-    }
-    _write(chunk, _encoding, callback) {
-        const buffer = Buffer.isBuffer(chunk)
-            ? chunk
-            : Buffer.from(chunk, _encoding);
-        this.#totalSize += buffer.length;
-        if (this.#totalSize > this.#maxSize) {
-            callback(createTooLargeError(this.#totalSize, this.#maxSize, this.#requestedPath));
-            return;
-        }
-        this.#chunks.push(buffer);
-        callback();
-    }
-    getResult() {
-        return Buffer.concat(this.#chunks, this.#totalSize);
-    }
-}
 async function readFileBufferWithLimit(handle, maxSize, requestedPath, signal) {
     const stream = handle.createReadStream({
         start: 0,
         highWaterMark: STREAM_CHUNK_SIZE,
         autoClose: false,
         emitClose: false,
+        signal,
     });
-    const collector = new BufferCollector(maxSize, requestedPath);
-    await pipeline(stream, collector, { signal });
-    return collector.getResult();
+    const chunks = [];
+    let totalSize = 0;
+    try {
+        for await (const chunk of stream) {
+            const buffer = Buffer.isBuffer(chunk)
+                ? chunk
+                : Buffer.from(chunk);
+            totalSize += buffer.length;
+            if (totalSize > maxSize) {
+                stream.destroy();
+                throw createTooLargeError(totalSize, maxSize, requestedPath);
+            }
+            chunks.push(buffer);
+        }
+    }
+    finally {
+        if (!stream.destroyed) {
+            stream.destroy();
+        }
+    }
+    return Buffer.concat(chunks, totalSize);
 }
 async function headFile(handle, numLines, encoding = 'utf-8', maxBytesRead, signal) {
     assertNotAborted(signal);
@@ -499,15 +524,24 @@ async function assertNotBinary(validPath, filePath, normalized) {
         return;
     throw new McpError(ErrorCode.E_INVALID_INPUT, `Binary file detected: ${filePath}. Refusing to read as text.`, filePath);
 }
-function requireHead(normalized, filePath) {
-    if (normalized.head === undefined) {
-        throw new McpError(ErrorCode.E_INVALID_INPUT, 'Missing head option', filePath);
+function assertSizeWithinLimit(size, maxSize, filePath) {
+    if (size <= maxSize)
+        return;
+    throw new McpError(ErrorCode.E_TOO_LARGE, `File too large: ${size} bytes (max: ${maxSize} bytes). Use head parameter to preview the first N lines.`, filePath, { size, maxSize });
+}
+function requireReadOption(normalized, key, filePath) {
+    const value = normalized[key];
+    if (value !== undefined) {
+        return value;
     }
-    return normalized.head;
+    throw new McpError(ErrorCode.E_INVALID_INPUT, `Missing ${key} option`, filePath);
 }
-function buildHeadResult(validPath, content, truncated, head, linesRead, hasMoreLines) {
+async function executeHeadRead(context) {
+    const head = requireReadOption(context.normalized, 'head', context.filePath);
+    const readOptions = buildReadContentOptions(context.normalized);
+    const { content, truncated, linesRead, hasMoreLines } = await readHeadContent(context.handle, head, readOptions);
     return {
-        path: validPath,
+        path: context.validPath,
         content,
         truncated,
         readMode: 'head',
@@ -516,24 +550,27 @@ function buildHeadResult(validPath, content, truncated, head, linesRead, hasMore
         hasMoreLines,
     };
 }
-function buildRangeResult(validPath, content, truncated, startLine, endLine, linesRead, hasMoreLines) {
-    const result = {
-        path: validPath,
+async function executeRangeRead(context) {
+    const startLine = requireReadOption(context.normalized, 'startLine', context.filePath);
+    const { endLine } = context.normalized;
+    const readOptions = buildReadContentOptions(context.normalized);
+    const { content, truncated, linesRead, hasMoreLines } = await readRangeContent(context.handle, startLine, endLine, readOptions);
+    return {
+        path: context.validPath,
         content,
         truncated,
         readMode: 'range',
         startLine,
+        ...(endLine !== undefined ? { endLine } : {}),
         linesRead,
         hasMoreLines,
     };
-    if (endLine !== undefined) {
-        result.endLine = endLine;
-    }
-    return result;
 }
-function buildFullResult(validPath, content, totalLines) {
+async function executeFullRead(context) {
+    assertSizeWithinLimit(context.stats.size, context.normalized.maxSize, context.filePath);
+    const { content, totalLines } = await readFullContent(context.handle, context.normalized.encoding, context.normalized.maxSize, context.filePath, context.normalized.signal);
     return {
-        path: validPath,
+        path: context.validPath,
         content,
         truncated: false,
         totalLines,
@@ -542,9 +579,12 @@ function buildFullResult(validPath, content, totalLines) {
         hasMoreLines: false,
     };
 }
-function buildTailResult(validPath, content, truncated, tail, linesRead, hasMoreLines) {
+async function executeTailRead(context) {
+    const tail = requireReadOption(context.normalized, 'tail', context.filePath);
+    const readOptions = buildReadContentOptions(context.normalized);
+    const { content, truncated, linesRead, hasMoreLines } = await readTailContent(context.handle, tail, readOptions);
     return {
-        path: validPath,
+        path: context.validPath,
         content,
         truncated,
         readMode: 'tail',
@@ -553,51 +593,15 @@ function buildTailResult(validPath, content, truncated, tail, linesRead, hasMore
         hasMoreLines,
     };
 }
-function assertSizeWithinLimit(size, maxSize, filePath) {
-    if (size <= maxSize)
-        return;
-    throw new McpError(ErrorCode.E_TOO_LARGE, `File too large: ${size} bytes (max: ${maxSize} bytes). Use head parameter to preview the first N lines.`, filePath, { size, maxSize });
-}
-async function readHeadResult(handle, validPath, filePath, normalized) {
-    const head = requireHead(normalized, filePath);
-    const readOptions = buildReadContentOptions(normalized);
-    const { content, truncated, linesRead, hasMoreLines } = await readHeadContent(handle, head, readOptions);
-    return buildHeadResult(validPath, content, truncated, head, linesRead, hasMoreLines);
-}
-async function readRangeResult(handle, validPath, filePath, normalized) {
-    const { startLine, endLine } = normalized;
-    if (startLine === undefined) {
-        throw new McpError(ErrorCode.E_INVALID_INPUT, 'Missing startLine option', filePath);
-    }
-    const readOptions = buildReadContentOptions(normalized);
-    const { content, truncated, linesRead, hasMoreLines } = await readRangeContent(handle, startLine, endLine, readOptions);
-    return buildRangeResult(validPath, content, truncated, startLine, endLine, linesRead, hasMoreLines);
-}
-async function readFullResult(handle, validPath, filePath, stats, normalized) {
-    assertSizeWithinLimit(stats.size, normalized.maxSize, filePath);
-    const { content, totalLines } = await readFullContent(handle, normalized.encoding, normalized.maxSize, filePath, normalized.signal);
-    return buildFullResult(validPath, content, totalLines);
-}
-async function readTailResult(handle, validPath, filePath, normalized) {
-    if (normalized.tail === undefined) {
-        throw new McpError(ErrorCode.E_INVALID_INPUT, 'Missing tail option', filePath);
-    }
-    const readOptions = buildReadContentOptions(normalized);
-    const { content, truncated, linesRead, hasMoreLines } = await readTailContent(handle, normalized.tail, readOptions);
-    return buildTailResult(validPath, content, truncated, normalized.tail, linesRead, hasMoreLines);
-}
-async function readByMode(handle, validPath, filePath, stats, normalized) {
-    const mode = resolveReadMode(normalized);
-    if (mode === 'head') {
-        return readHeadResult(handle, validPath, filePath, normalized);
-    }
-    if (mode === 'tail') {
-        return readTailResult(handle, validPath, filePath, normalized);
-    }
-    if (mode === 'range') {
-        return readRangeResult(handle, validPath, filePath, normalized);
-    }
-    return readFullResult(handle, validPath, filePath, stats, normalized);
+const READ_MODE_HANDLERS = {
+    head: executeHeadRead,
+    range: executeRangeRead,
+    full: executeFullRead,
+    tail: executeTailRead,
+};
+async function readByMode(context) {
+    const mode = resolveReadMode(context.normalized);
+    return READ_MODE_HANDLERS[mode](context);
 }
 function assertFileStats(filePath, stats) {
     if (!stats.isFile()) {
@@ -605,19 +609,32 @@ function assertFileStats(filePath, stats) {
     }
 }
 async function readFileWithStatsInternal(filePath, validPath, stats, normalized) {
-    assertNotAborted(normalized.signal);
-    assertAllowedFileAccess(filePath, validPath);
-    assertFileStats(filePath, stats);
-    if (normalized.skipBinary) {
-        await assertNotBinary(validPath, filePath, normalized);
-    }
-    assertNotAborted(normalized.signal);
-    const handle = await withAbort(fsp.open(validPath, 'r'), normalized.signal);
+    const env_2 = { stack: [], error: void 0, hasError: false };
     try {
-        return await readByMode(handle, validPath, filePath, stats, normalized);
+        assertNotAborted(normalized.signal);
+        assertAllowedFileAccess(filePath, validPath);
+        assertFileStats(filePath, stats);
+        if (normalized.skipBinary) {
+            await assertNotBinary(validPath, filePath, normalized);
+        }
+        assertNotAborted(normalized.signal);
+        const handle = __addDisposableResource(env_2, await openReadableFileHandle(validPath, normalized.signal), true);
+        return await readByMode({
+            handle,
+            validPath,
+            filePath,
+            stats,
+            normalized,
+        });
+    }
+    catch (e_2) {
+        env_2.error = e_2;
+        env_2.hasError = true;
     }
     finally {
-        await handle.close();
+        const result_2 = __disposeResources(env_2);
+        if (result_2)
+            await result_2;
     }
 }
 export async function readFileWithStats(filePath, validPath, stats, options = {}) {
@@ -636,7 +653,7 @@ export async function atomicWriteFile(filePath, content, options = {}) {
     const tempPath = `${filePath}.${randomUUID()}.tmp`;
     try {
         assertNotAborted(signal);
-        await withAbort(fsp.writeFile(tempPath, content, { encoding, signal }), signal);
+        await fsp.writeFile(tempPath, content, { encoding, signal });
         await withAbort(fsp.rename(tempPath, filePath), signal);
     }
     catch (error) {

package/dist/prompts.d.ts

@@ -3,3 +3,4 @@ import { type IconInfo } from './tools/shared.js';
 export declare function registerGetHelpPrompt(server: McpServer, instructions: string, iconInfo?: IconInfo): void;
 export declare function registerCompareFilesPrompt(server: McpServer, iconInfo?: IconInfo): void;
 export declare function registerAnalyzePathPrompt(server: McpServer, iconInfo?: IconInfo): void;
+export declare function registerGetToolHelpPrompt(server: McpServer, iconInfo?: IconInfo): void;

package/dist/prompts.js

@@ -1,4 +1,6 @@
 import { z } from 'zod';
+import { ErrorCode, McpError } from './lib/errors.js';
+import { buildToolInfo, getSortedToolContracts, } from './resources/tool-info.js';
 import { withDefaultIcons } from './tools/shared.js';
 const HELP_PROMPT_NAME = 'get-help';
 const HELP_PROMPT_TITLE = 'Get Help';
@@ -9,6 +11,9 @@ const COMPARE_FILES_PROMPT_DESCRIPTION = 'Generate a workflow for comparing two
 const ANALYZE_PATH_PROMPT_NAME = 'analyze-path';
 const ANALYZE_PATH_PROMPT_TITLE = 'Analyze Path';
 const ANALYZE_PATH_PROMPT_DESCRIPTION = 'Generate a workflow for analyzing a file or directory using stat, read, and tree.';
+const GET_TOOL_HELP_PROMPT_NAME = 'get-tool-help';
+const GET_TOOL_HELP_PROMPT_TITLE = 'Get Tool Help';
+const GET_TOOL_HELP_PROMPT_DESCRIPTION = 'Return a prompt with the authoritative contract for a specific filesystem-mcp tool.';
 function filterInstructionsByTopic(instructions, topic) {
     const normalized = topic.trim().toLowerCase();
     if (!normalized)
@@ -24,6 +29,12 @@ function filterInstructionsByTopic(instructions, topic) {
         .join(', ');
     return `Section '${topic}' not found. Available: ${available}\n\n${instructions}`;
 }
+function findKnownToolName(rawName) {
+    const normalized = rawName.trim().toLowerCase();
+    if (!normalized)
+        return undefined;
+    return getSortedToolContracts().find((contract) => contract.name.toLowerCase() === normalized)?.name;
+}
 export function registerGetHelpPrompt(server, instructions, iconInfo) {
     const baseConfig = withDefaultIcons({ title: HELP_PROMPT_TITLE, description: HELP_PROMPT_DESCRIPTION }, iconInfo);
     server.registerPrompt(HELP_PROMPT_NAME, {
@@ -97,3 +108,50 @@ export function registerAnalyzePathPrompt(server, iconInfo) {
         ],
     }));
 }
+export function registerGetToolHelpPrompt(server, iconInfo) {
+    server.registerPrompt(GET_TOOL_HELP_PROMPT_NAME, {
+        ...withDefaultIcons({
+            title: GET_TOOL_HELP_PROMPT_TITLE,
+            description: GET_TOOL_HELP_PROMPT_DESCRIPTION,
+        }, iconInfo),
+        argsSchema: {
+            name: z
+                .string()
+                .min(1)
+                .describe('Tool name from tools/list or internal://tool-info/{name}.'),
+        },
+    }, ({ name }) => {
+        const toolName = findKnownToolName(name);
+        if (!toolName) {
+            throw new McpError(ErrorCode.E_INVALID_INPUT, `Unknown tool: ${name}`);
+        }
+        const toolInfo = buildToolInfo(toolName);
+        if (!toolInfo) {
+            throw new McpError(ErrorCode.E_INVALID_INPUT, `Unknown tool: ${toolName}`);
+        }
+        return {
+            description: GET_TOOL_HELP_PROMPT_DESCRIPTION,
+            messages: [
+                {
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text: `Use the embedded contract for \`${toolName}\` as the authoritative reference. ` +
+                            'Summarize when to use it, its key constraints, and the safest next action.',
+                    },
+                },
+                {
+                    role: 'user',
+                    content: {
+                        type: 'resource',
+                        resource: {
+                            uri: `internal://tool-info/${toolName}`,
+                            mimeType: 'text/markdown',
+                            text: toolInfo,
+                        },
+                    },
+                },
+            ],
+        };
+    });
+}

package/dist/resources/generated-instructions.js

@@ -1,6 +1,9 @@
 import { buildToolCatalogDetailsOnly } from './tool-catalog.js';
-import { buildCoreContextPack, formatToolNameList, getSharedConstraints, getTaskCapableToolNames, getToolContracts, pickAvailableToolNames, } from './tool-info.js';
+import { buildCoreContextPack, formatToolNameList, getSharedConstraints, getTaskCapableToolNames, getTaskToolNamesBySupport, getToolContracts, pickAvailableToolNames, } from './tool-info.js';
 import { buildWorkflowGuide } from './workflows.js';
+function formatTaskModeLine(label, names) {
+    return `${label}: ${names.length > 0 ? formatToolNameList(names) : 'none'}.`;
+}
 function buildToolsOverview() {
     const rows = [
         ['Navigate', pickAvailableToolNames(['roots', 'ls', 'tree', 'find'])],
@@ -29,6 +32,8 @@ function buildToolsOverview() {
 }
 function buildInstructionsHeader() {
     const taskCapable = formatToolNameList(getTaskCapableToolNames());
+    const optionalTaskTools = getTaskToolNamesBySupport('optional');
+    const requiredTaskTools = getTaskToolNamesBySupport('required');
     return `<role>
 Filesystem agent. Scope: allowed roots only. Discover paths before acting — never guess.
 </role>
@@ -49,9 +54,12 @@ ${buildToolsOverview()}
 </resources>
 
 <task_protocol>
-Task execution: Tools returning a task ID must be polled via \`tasks/get\`, then retrieved via \`tasks/result\`.
+Task execution: Call task-capable tools inline by default; add \`task\` only when durable polling or deferred results are needed.
+Task results: When a task is requested, poll via \`tasks/get\`, then retrieve the final payload via \`tasks/result\`.
 Progress: Pass \`_meta.progressToken\` in \`tools/call\` to receive \`notifications/progress\`.
-Task-capable: ${taskCapable}.
+Task-capable: ${taskCapable || 'none'}.
+${formatTaskModeLine('Optional task mode', optionalTaskTools)}
+${formatTaskModeLine('Required task mode', requiredTaskTools)}
 </task_protocol>
 `;
 }

package/dist/resources/tool-catalog.js

@@ -1,4 +1,4 @@
-import { buildCoreContextPack, pickAvailableToolNames } from './tool-info.js';
+import { buildCoreContextPack, getTaskCapableToolNames, pickAvailableToolNames, } from './tool-info.js';
 function buildCrossToolDataFlow() {
     const flows = [];
     if (pickAvailableToolNames(['find', 'read']).length === 2) {
@@ -14,13 +14,59 @@ function buildCrossToolDataFlow() {
     return flows.join('\n');
 }
 function buildCatalogGuide() {
-    return `<tool_selection_guide>
+    const taskCapable = getTaskCapableToolNames();
+    return (`<tool_selection_guide>
+## Primitive Routing
+
+- ` +
+        '`tools`' +
+        `: model-controlled operations that inspect or mutate the allowed filesystem.
+- ` +
+        '`resources`' +
+        `: application-driven context such as ` +
+        '`internal://instructions`' +
+        `, ` +
+        '`internal://tool-info/{name}`' +
+        `, and cached ` +
+        '`filesystem-mcp://result/{id}`' +
+        ` output.
+- ` +
+        '`prompts`' +
+        `: user-controlled workflow templates for help, comparison, and guided inspection.
+- ` +
+        '`completion`' +
+        `: argument suggestions for prompts and resource templates; not a discovery mechanism.
+
 ## Cross-Tool Data Flow
 
 \`\`\`
 ${buildCrossToolDataFlow()}
 \`\`\`
 
+## Result Contract
+
+- Successful tools return ` +
+        '`content`' +
+        ` and usually ` +
+        '`structuredContent`' +
+        `.
+- Tool/business failures return ` +
+        '`isError: true`' +
+        ` inside the tool result, not a JSON-RPC protocol error.
+- When a tool returns ` +
+        '`resourceUri`' +
+        ` or a ` +
+        '`resource_link`' +
+        `, follow it with ` +
+        '`resources/read`' +
+        ` immediately.
+
+## Task Mode Routing
+
+- Inline first for fast operations.
+- Add task mode only when the caller needs durable polling, deferred retrieval, or cancellation after the initial response.
+- Task-capable tools: ${taskCapable.length > 0 ? taskCapable.map((name) => `\`${name}\``).join(', ') : 'none'}.
+
 ## Search Strategy
 
 - \`find\`: glob file discovery.
@@ -47,7 +93,7 @@ ${buildCrossToolDataFlow()}
 - \`apply_patch\` accepts unified diffs - single-file or multi-file.
 - Multi-file: \`path\` is base directory; each file is best-effort with per-file \`results[]\`.
 </tool_selection_guide>
-`;
+`);
 }
 export function buildToolCatalog() {
     return `${buildCoreContextPack()}\n\n${buildCatalogGuide()}`;

package/dist/resources/tool-info.d.ts

@@ -4,6 +4,7 @@ export declare function getSortedToolContracts(): ToolContract[];
 export declare function pickAvailableToolNames(names: readonly string[]): string[];
 export declare function formatToolNameList(names: readonly string[]): string;
 export declare function getTaskCapableToolNames(): string[];
+export declare function getTaskToolNamesBySupport(taskSupport: Extract<ToolContract['taskSupport'], 'optional' | 'required'>): string[];
 export declare function buildCoreContextPack(): string;
 export declare function getSharedConstraints(): string[];
 export declare function buildToolInfo(name: string): string | undefined;