nodebench-mcp 1.4.1 → 2.1.0

package/dist/tools/localFileTools.js

@@ -0,0 +1,386 @@
+/**
+ * Local file parsing tools (deterministic).
+ *
+ * These tools intentionally avoid network access and operate only on local files.
+ * Primary use cases:
+ * - GAIA file-backed tasks (PDF / XLSX / CSV attachments)
+ * - Internal agent workflows that need structured parsing without "LLM OCR"
+ *
+ * Optional deps (installed by default when available):
+ * - xlsx: XLSX parsing
+ * - papaparse: CSV parsing
+ * - pdf-parse: PDF text extraction (page-aware)
+ */
+import { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+function expandTilde(p) {
+    if (!p)
+        return p;
+    if (p === "~")
+        return os.homedir();
+    if (p.startsWith("~/") || p.startsWith("~\\"))
+        return path.join(os.homedir(), p.slice(2));
+    return p;
+}
+function resolveLocalPath(inputPath) {
+    const expanded = expandTilde(String(inputPath ?? "").trim());
+    if (!expanded)
+        throw new Error("path is required");
+    return path.isAbsolute(expanded) ? expanded : path.resolve(process.cwd(), expanded);
+}
+function clampInt(value, fallback, min, max) {
+    const n = typeof value === "number" ? value : Number.parseInt(String(value ?? ""), 10);
+    if (!Number.isFinite(n))
+        return fallback;
+    return Math.max(min, Math.min(max, n));
+}
+function truncateCell(value, maxChars) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === "number")
+        return value;
+    if (typeof value === "boolean")
+        return value;
+    if (value instanceof Date)
+        return value.toISOString();
+    const s = String(value);
+    if (s.length <= maxChars)
+        return s;
+    return s.slice(0, maxChars) + "...";
+}
+async function getXlsx() {
+    try {
+        const mod = await import("xlsx");
+        return mod.default ?? mod;
+    }
+    catch (err) {
+        throw new Error("Missing optional dependency: xlsx. Install it (or run npm install in packages/mcp-local) to use XLSX parsing.");
+    }
+}
+async function getPapaParse() {
+    try {
+        const mod = await import("papaparse");
+        return mod.default ?? mod;
+    }
+    catch {
+        return null;
+    }
+}
+async function getPdfParseModule() {
+    try {
+        return await import("pdf-parse");
+    }
+    catch {
+        throw new Error("Missing optional dependency: pdf-parse. Install it (or run npm install in packages/mcp-local) to use PDF parsing.");
+    }
+}
+export const localFileTools = [
+    {
+        name: "read_csv_file",
+        description: "Read a local CSV file and return a bounded table preview (headers + rows). Deterministic, no network.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Path to a local .csv file (absolute or relative to current working directory).",
+                },
+                hasHeader: {
+                    type: "boolean",
+                    description: "If true, treats the first row as headers.",
+                    default: true,
+                },
+                delimiter: {
+                    type: "string",
+                    description: "Optional delimiter override, e.g. ',' or '\\t'. If omitted, parser default is used.",
+                },
+                encoding: {
+                    type: "string",
+                    description: "File encoding (default: utf8).",
+                    default: "utf8",
+                },
+                maxRows: {
+                    type: "number",
+                    description: "Maximum number of data rows to return (excluding header).",
+                    default: 200,
+                },
+                maxCols: {
+                    type: "number",
+                    description: "Maximum number of columns to return.",
+                    default: 50,
+                },
+                maxCellChars: {
+                    type: "number",
+                    description: "Maximum characters to return per cell (long cells are truncated).",
+                    default: 2000,
+                },
+            },
+            required: ["path"],
+        },
+        handler: async (args) => {
+            const filePath = resolveLocalPath(args?.path);
+            if (!existsSync(filePath))
+                throw new Error(`File not found: ${filePath}`);
+            const encoding = String(args?.encoding ?? "utf8");
+            const text = await readFile(filePath, { encoding });
+            const hasHeader = args?.hasHeader !== false;
+            const maxRows = clampInt(args?.maxRows, 200, 1, 5000);
+            const maxCols = clampInt(args?.maxCols, 50, 1, 500);
+            const maxCellChars = clampInt(args?.maxCellChars, 2000, 20, 20000);
+            const delimiter = typeof args?.delimiter === "string" ? args.delimiter : undefined;
+            const papa = await getPapaParse();
+            let rows = [];
+            let parseErrors = [];
+            if (papa?.parse) {
+                const result = papa.parse(text, {
+                    ...(delimiter ? { delimiter } : {}),
+                    skipEmptyLines: true,
+                    dynamicTyping: false,
+                });
+                rows = Array.isArray(result?.data) ? result.data : [];
+                parseErrors = Array.isArray(result?.errors) ? result.errors : [];
+            }
+            else {
+                // Minimal fallback parser: split by newlines and commas (no quote handling).
+                const lines = String(text).split(/\r?\n/).filter((l) => l.trim().length > 0);
+                rows = lines.map((l) => l.split(delimiter ?? ","));
+            }
+            // Normalize to array-of-arrays and bound.
+            const normalized = rows
+                .filter((r) => Array.isArray(r))
+                .map((r) => r.slice(0, maxCols).map((c) => truncateCell(c, maxCellChars)));
+            const headerRow = hasHeader ? normalized[0] : undefined;
+            const dataRows = hasHeader ? normalized.slice(1) : normalized;
+            const limitedRows = dataRows.slice(0, maxRows);
+            const colCount = Math.max(headerRow ? headerRow.length : 0, ...limitedRows.map((r) => r.length));
+            const truncated = dataRows.length > limitedRows.length ||
+                normalized.some((r) => r.length > maxCols) ||
+                colCount > maxCols;
+            const headers = headerRow
+                ? headerRow.map((h) => String(h ?? "").trim())
+                : Array.from({ length: colCount }, (_, i) => `col_${i + 1}`);
+            return {
+                path: filePath,
+                encoding,
+                hasHeader,
+                delimiter: delimiter ?? null,
+                parseErrors: parseErrors.length > 0 ? parseErrors.slice(0, 5) : [],
+                rowCount: dataRows.length,
+                returnedRows: limitedRows.length,
+                colCount,
+                truncated,
+                headers: headers.slice(0, maxCols),
+                rows: limitedRows.map((r) => r.slice(0, maxCols)),
+            };
+        },
+    },
+    {
+        name: "read_xlsx_file",
+        description: "Read a local XLSX workbook and return a bounded sheet preview (headers + rows). Deterministic, no network.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Path to a local .xlsx file (absolute or relative to current working directory).",
+                },
+                sheetName: {
+                    type: "string",
+                    description: "Sheet to read. If omitted, the first sheet is used.",
+                },
+                headerRow: {
+                    type: "number",
+                    description: "1-based header row index. Use 0 for no header row.",
+                    default: 1,
+                },
+                rangeA1: {
+                    type: "string",
+                    description: "Optional A1 range (e.g. A1:D50) to limit parsing to a specific region.",
+                },
+                maxRows: {
+                    type: "number",
+                    description: "Maximum number of data rows to return (excluding header).",
+                    default: 200,
+                },
+                maxCols: {
+                    type: "number",
+                    description: "Maximum number of columns to return.",
+                    default: 50,
+                },
+                maxCellChars: {
+                    type: "number",
+                    description: "Maximum characters to return per cell (long cells are truncated).",
+                    default: 2000,
+                },
+            },
+            required: ["path"],
+        },
+        handler: async (args) => {
+            const filePath = resolveLocalPath(args?.path);
+            if (!existsSync(filePath))
+                throw new Error(`File not found: ${filePath}`);
+            const XLSX = await getXlsx();
+            const wb = XLSX.readFile(filePath, {
+                cellDates: true,
+                dense: true,
+            });
+            const sheets = Array.isArray(wb?.SheetNames) ? wb.SheetNames : [];
+            if (sheets.length === 0)
+                throw new Error(`No sheets found in workbook: ${filePath}`);
+            const requestedSheet = typeof args?.sheetName === "string" ? args.sheetName.trim() : "";
+            const sheetName = requestedSheet || sheets[0];
+            const sheet = wb.Sheets?.[sheetName];
+            if (!sheet) {
+                throw new Error(`Sheet not found: "${sheetName}". Available sheets: ${sheets.join(", ")}`);
+            }
+            const headerRow = clampInt(args?.headerRow, 1, 0, 1000);
+            const maxRows = clampInt(args?.maxRows, 200, 1, 5000);
+            const maxCols = clampInt(args?.maxCols, 50, 1, 500);
+            const maxCellChars = clampInt(args?.maxCellChars, 2000, 20, 20000);
+            const rangeA1 = typeof args?.rangeA1 === "string" ? args.rangeA1.trim() : "";
+            const table = XLSX.utils.sheet_to_json(sheet, {
+                header: 1,
+                blankrows: false,
+                defval: "",
+                ...(rangeA1 ? { range: rangeA1 } : {}),
+            });
+            const normalized = table
+                .filter((r) => Array.isArray(r))
+                .map((r) => r.slice(0, maxCols).map((c) => truncateCell(c, maxCellChars)));
+            const headerIdx = headerRow > 0 ? headerRow - 1 : -1;
+            const header = headerIdx >= 0 ? normalized[headerIdx] : undefined;
+            const dataRows = headerIdx >= 0 ? normalized.slice(headerIdx + 1) : normalized;
+            const limitedRows = dataRows.slice(0, maxRows);
+            const colCount = Math.max(header ? header.length : 0, ...limitedRows.map((r) => r.length));
+            const truncated = dataRows.length > limitedRows.length ||
+                normalized.some((r) => r.length > maxCols) ||
+                colCount > maxCols;
+            const headers = header
+                ? header.map((h) => String(h ?? "").trim())
+                : Array.from({ length: colCount }, (_, i) => `col_${i + 1}`);
+            return {
+                path: filePath,
+                sheets,
+                sheetName,
+                headerRow,
+                rangeA1: rangeA1 || null,
+                rowCount: dataRows.length,
+                returnedRows: limitedRows.length,
+                colCount,
+                truncated,
+                headers: headers.slice(0, maxCols),
+                rows: limitedRows.map((r) => r.slice(0, maxCols)),
+            };
+        },
+    },
+    {
+        name: "read_pdf_text",
+        description: "Extract text from a local PDF file for selected pages. Returns bounded text with page markers. Deterministic, no network.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Path to a local .pdf file (absolute or relative to current working directory).",
+                },
+                pageStart: {
+                    type: "number",
+                    description: "1-based start page (inclusive). Defaults to 1.",
+                    default: 1,
+                },
+                pageEnd: {
+                    type: "number",
+                    description: "1-based end page (inclusive). Defaults to 3.",
+                    default: 3,
+                },
+                pageNumbers: {
+                    type: "array",
+                    description: "Optional explicit list of 1-based pages to extract (overrides pageStart/pageEnd).",
+                    items: { type: "number" },
+                },
+                maxChars: {
+                    type: "number",
+                    description: "Maximum characters to return across all extracted pages (text is truncated).",
+                    default: 12000,
+                },
+            },
+            required: ["path"],
+        },
+        handler: async (args) => {
+            const filePath = resolveLocalPath(args?.path);
+            if (!existsSync(filePath))
+                throw new Error(`File not found: ${filePath}`);
+            const maxChars = clampInt(args?.maxChars, 12000, 1000, 200000);
+            const pageNumbersRaw = Array.isArray(args?.pageNumbers) ? args.pageNumbers : null;
+            const explicitPages = pageNumbersRaw
+                ? pageNumbersRaw
+                    .map((n) => clampInt(n, 0, 0, 100000))
+                    .filter((n) => n > 0)
+                : null;
+            const pageStart = clampInt(args?.pageStart, 1, 1, 100000);
+            const pageEnd = clampInt(args?.pageEnd, 3, 1, 100000);
+            const mod = await getPdfParseModule();
+            const PDFParse = mod?.PDFParse;
+            if (typeof PDFParse !== "function") {
+                throw new Error("pdf-parse module missing PDFParse export (unsupported version)");
+            }
+            const buffer = await readFile(filePath);
+            const parser = new PDFParse({ data: buffer });
+            let numPages = 0;
+            let text = "";
+            let extractedPages = [];
+            try {
+                const parseParams = {
+                    // Prefer consistent structure; we add our own page markers below.
+                    lineEnforce: true,
+                    pageJoiner: "",
+                    parseHyperlinks: false,
+                };
+                if (explicitPages && explicitPages.length > 0) {
+                    parseParams.partial = explicitPages;
+                }
+                else {
+                    const start = Math.min(pageStart, pageEnd);
+                    const end = Math.max(pageStart, pageEnd);
+                    parseParams.first = start;
+                    parseParams.last = end;
+                }
+                const result = await parser.getText(parseParams);
+                numPages = Number(result?.total ?? 0);
+                const pages = Array.isArray(result?.pages) ? result.pages : [];
+                extractedPages = pages
+                    .map((p) => Number(p?.num ?? 0))
+                    .filter((n) => Number.isFinite(n) && n > 0);
+                text = pages
+                    .map((p) => `\n\n[PAGE ${Number(p?.num ?? 0)}]\n${String(p?.text ?? "").trim()}\n`)
+                    .join("")
+                    .trim();
+            }
+            finally {
+                try {
+                    await parser.destroy();
+                }
+                catch {
+                    // ignore
+                }
+            }
+            let truncated = false;
+            if (text.length > maxChars) {
+                text = text.slice(0, maxChars);
+                truncated = true;
+            }
+            const pagesIncluded = extractedPages;
+            return {
+                path: filePath,
+                numPages,
+                pagesIncluded,
+                maxChars,
+                truncated,
+                text,
+            };
+        },
+    },
+];
+//# sourceMappingURL=localFileTools.js.map

package/dist/tools/localFileTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"localFileTools.js","sourceRoot":"","sources":["../../src/tools/localFileTools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAG7B,SAAS,WAAW,CAAC,CAAS;IAC5B,IAAI,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IACjB,IAAI,CAAC,KAAK,GAAG;QAAE,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC;IACnC,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1F,OAAO,CAAC,CAAC;AACX,CAAC;AAED,SAAS,gBAAgB,CAAC,SAAiB;IACzC,MAAM,QAAQ,GAAG,WAAW,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAC7D,IAAI,CAAC,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,kBAAkB,CAAC,CAAC;IACnD,OAAO,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,QAAQ,CAAC,CAAC;AACtF,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc,EAAE,QAAgB,EAAE,GAAW,EAAE,GAAW;IAC1E,MAAM,CAAC,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;IACvF,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;QAAE,OAAO,QAAQ,CAAC;IACzC,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;AACzC,CAAC;AAED,SAAS,YAAY,CAAC,KAAc,EAAE,QAAgB;IACpD,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACvD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAC7C,IAAI,KAAK,YAAY,IAAI;QAAE,OAAO,KAAK,CAAC,WAAW,EAAE,CAAC;IACtD,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IACxB,IAAI,CAAC,CAAC,MAAM,IAAI,QAAQ;QAAE,OAAO,CAAC,CAAC;IACnC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,GAAG,KAAK,CAAC;AACtC,CAAC;AAED,KAAK,UAAU,OAAO;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC;QACjC,OAAQ,GAAW,CAAC,OAAO,IAAI,GAAG,CAAC;IACrC,CAAC;IAAC,OAAO,GAAQ,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CACb,+GAA+G,CAChH,CAAC;IACJ,CAAC;AACH,CAAC;AAED,KAAK,UAAU,YAAY;IACzB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC;QACtC,OAAQ,GAAW,CAAC,OAAO,IAAI,GAAG,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,KAAK,UAAU,iBAAiB;IAC9B,IAAI,CAAC;QACH,OAAO,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,mHAAmH,CACpH,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,cAAc,GAAc;IACvC;QACE,IAAI,EAAE,eAAe;QACrB,WAAW,EACT,uGAAuG;QACzG,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,gFAAgF;iBAC9F;gBACD,SAAS,EAAE;oBACT,IAAI,EAAE,SAAS;oBACf,WAAW,EAAE,2CAA2C;oBACxD,OAAO,EAAE,IAAI;iBACd;gBACD,SAAS,EAAE;oBACT,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,qFAAqF;iBACnG;gBACD,QAAQ,EAAE;oBACR,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,gCAAgC;oBAC7C,OAAO,EAAE,MAAM;iBAChB;gBACD,OAAO,EAAE;oBACP,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,2DAA2D;oBACxE,OAAO,EAAE,GAAG;iBACb;gBACD,OAAO,EAAE;oBACP,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,sCAAsC;oBACnD,OAAO,EAAE,EAAE;iBACZ;gBACD,YAAY,EAAE;oBACZ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,mEAAmE;oBAChF,OAAO,EAAE,IAAI;iBACd;aACF;YACD,QAAQ,EAAE,CAAC,MAAM,CAAC;SACnB;QACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YACtB,MAAM,QAAQ,GAAG,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAC9C,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,QAAQ,EAAE,CAAC,CAAC;YAE1E,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,EAAE,QAAQ,IAAI,MAAM,CAA0B,CAAC;YAC3E,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;YAEpD,MAAM,SAAS,GAAG,IAAI,EAAE,SAAS,KAAK,KAAK,CAAC;YAC5C,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;YACtD,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;YACpD,MAAM,YAAY,GAAG,QAAQ,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC;YACnE,MAAM,SAAS,GAAG,OAAO,IAAI,EAAE,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;YAEnF,MAAM,IAAI,GAAG,MAAM,YAAY,EAAE,CAAC;YAElC,IAAI,IAAI,GAAgB,EAAE,CAAC;YAC3B,IAAI,WAAW,GAAU,EAAE,CAAC;YAE5B,IAAI,IAAI,EAAE,KAAK,EAAE,CAAC;gBAChB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE;oBAC9B,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBACnC,cAAc,EAAE,IAAI;oBACpB,aAAa,EAAE,KAAK;iBACrB,CAAC,CAAC;gBACH,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,CAAE,MAAM,CAAC,IAAoB,CAAC,CAAC,CAAC,EAAE,CAAC;gBACvE,WAAW,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;YACnE,CAAC;iBAAM,CAAC;gBACN,6EAA6E;gBAC7E,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;gBAC7E,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,IAAI,GAAG,CAAC,CAAC,CAAC;YACrD,CAAC;YAED,0CAA0C;YAC1C,MAAM,UAAU,GAAG,IAAI;iBACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;iBAC/B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAE,CAAe,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;YAE5F,MAAM,SAAS,GAAG,SAAS,CAAC,CAAC,CAAE,UAAU,CAAC,CAAC,CAAuB,CAAC,CAAC,CAAC,SAAS,CAAC;YAC/E,MAAM,QAAQ,GAAG,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;YAE9D,MAAM,WAAW,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;YAE/C,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CACvB,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAChC,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CACpC,CAAC;YACF,MAAM,SAAS,GACb,QAAQ,CAAC,MAAM,GAAG,WAAW,CAAC,MAAM;gBACpC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,OAAO,CAAC;gBAC1C,QAAQ,GAAG,OAAO,CAAC;YAErB,MAAM,OAAO,GAAG,SAAS;gBACvB,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;gBAC9C,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAE/D,OAAO;gBACL,IAAI,EAAE,QAAQ;gBACd,QAAQ;gBACR,SAAS;gBACT,SAAS,EAAE,SAAS,IAAI,IAAI;gBAC5B,WAAW,EAAE,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE;gBAClE,QAAQ,EAAE,QAAQ,CAAC,MAAM;gBACzB,YAAY,EAAE,WAAW,CAAC,MAAM;gBAChC,QAAQ;gBACR,SAAS;gBACT,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC;gBAClC,IAAI,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;aAClD,CAAC;QACJ,CAAC;KACF;IACD;QACE,IAAI,EAAE,gBAAgB;QACtB,WAAW,EACT,4GAA4G;QAC9G,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,iFAAiF;iBAC/F;gBACD,SAAS,EAAE;oBACT,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,qDAAqD;iBACnE;gBACD,SAAS,EAAE;oBACT,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,oDAAoD;oBACjE,OAAO,EAAE,CAAC;iBACX;gBACD,OAAO,EAAE;oBACP,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,wEAAwE;iBACtF;gBACD,OAAO,EAAE;oBACP,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,2DAA2D;oBACxE,OAAO,EAAE,GAAG;iBACb;gBACD,OAAO,EAAE;oBACP,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,sCAAsC;oBACnD,OAAO,EAAE,EAAE;iBACZ;gBACD,YAAY,EAAE;oBACZ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,mEAAmE;oBAChF,OAAO,EAAE,IAAI;iBACd;aACF;YACD,QAAQ,EAAE,CAAC,MAAM,CAAC;SACnB;QACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YACtB,MAAM,QAAQ,GAAG,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAC9C,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,QAAQ,EAAE,CAAC,CAAC;YAE1E,MAAM,IAAI,GAAG,MAAM,OAAO,EAAE,CAAC;YAC7B,MAAM,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE;gBACjC,SAAS,EAAE,IAAI;gBACf,KAAK,EAAE,IAAI;aACZ,CAAC,CAAC;YAEH,MAAM,MAAM,GAAa,KAAK,CAAC,OAAO,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5E,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,QAAQ,EAAE,CAAC,CAAC;YAErF,MAAM,cAAc,GAAG,OAAO,IAAI,EAAE,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACxF,MAAM,SAAS,GAAG,cAAc,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC;YAC9C,MAAM,KAAK,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC,SAAS,CAAC,CAAC;YACrC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,MAAM,IAAI,KAAK,CACb,qBAAqB,SAAS,wBAAwB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC1E,CAAC;YACJ,CAAC;YAED,MAAM,SAAS,GAAG,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;YACxD,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;YACtD,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;YACpD,MAAM,YAAY,GAAG,QAAQ,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC;YACnE,MAAM,OAAO,GAAG,OAAO,IAAI,EAAE,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAE7E,MAAM,KAAK,GAAgB,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,KAAK,EAAE;gBACzD,MAAM,EAAE,CAAC;gBACT,SAAS,EAAE,KAAK;gBAChB,MAAM,EAAE,EAAE;gBACV,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACvC,CAAC,CAAC;YAEH,MAAM,UAAU,GAAG,KAAK;iBACrB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;iBAC/B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAE,CAAe,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;YAE5F,MAAM,SAAS,GAAG,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACrD,MAAM,MAAM,GAAG,SAAS,IAAI,CAAC,CAAC,CAAC,CAAE,UAAU,CAAC,SAAS,CAAuB,CAAC,CAAC,CAAC,SAAS,CAAC;YAEzF,MAAM,QAAQ,GAAG,SAAS,IAAI,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;YAC/E,MAAM,WAAW,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;YAE/C,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;YAC3F,MAAM,SAAS,GACb,QAAQ,CAAC,MAAM,GAAG,WAAW,CAAC,MAAM;gBACpC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,OAAO,CAAC;gBAC1C,QAAQ,GAAG,OAAO,CAAC;YAErB,MAAM,OAAO,GAAG,MAAM;gBACpB,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;gBAC3C,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAE/D,OAAO;gBACL,IAAI,EAAE,QAAQ;gBACd,MAAM;gBACN,SAAS;gBACT,SAAS;gBACT,OAAO,EAAE,OAAO,IAAI,IAAI;gBACxB,QAAQ,EAAE,QAAQ,CAAC,MAAM;gBACzB,YAAY,EAAE,WAAW,CAAC,MAAM;gBAChC,QAAQ;gBACR,SAAS;gBACT,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC;gBAClC,IAAI,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;aAClD,CAAC;QACJ,CAAC;KACF;IACD;QACE,IAAI,EAAE,eAAe;QACrB,WAAW,EACT,2HAA2H;QAC7H,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,gFAAgF;iBAC9F;gBACD,SAAS,EAAE;oBACT,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,gDAAgD;oBAC7D,OAAO,EAAE,CAAC;iBACX;gBACD,OAAO,EAAE;oBACP,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,8CAA8C;oBAC3D,OAAO,EAAE,CAAC;iBACX;gBACD,WAAW,EAAE;oBACX,IAAI,EAAE,OAAO;oBACb,WAAW,EAAE,mFAAmF;oBAChG,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;iBAC1B;gBACD,QAAQ,EAAE;oBACR,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,8EAA8E;oBAC3F,OAAO,EAAE,KAAK;iBACf;aACF;YACD,QAAQ,EAAE,CAAC,MAAM,CAAC;SACnB;QACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YACtB,MAAM,QAAQ,GAAG,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAC9C,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,QAAQ,EAAE,CAAC,CAAC;YAE1E,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;YAE/D,MAAM,cAAc,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,CAAE,IAAI,CAAC,WAAyB,CAAC,CAAC,CAAC,IAAI,CAAC;YACjG,MAAM,aAAa,GAAG,cAAc;gBAClC,CAAC,CAAC,cAAc;qBACX,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;qBACrC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;gBACzB,CAAC,CAAC,IAAI,CAAC;YACT,MAAM,SAAS,GAAG,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;YAC1D,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;YAEtD,MAAM,GAAG,GAAG,MAAM,iBAAiB,EAAE,CAAC;YACtC,MAAM,QAAQ,GAAI,GAAW,EAAE,QAAQ,CAAC;YACxC,IAAI,OAAO,QAAQ,KAAK,UAAU,EAAE,CAAC;gBACnC,MAAM,IAAI,KAAK,CAAC,gEAAgE,CAAC,CAAC;YACpF,CAAC;YAED,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC;YACxC,MAAM,MAAM,GAAG,IAAI,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;YAE9C,IAAI,QAAQ,GAAG,CAAC,CAAC;YACjB,IAAI,IAAI,GAAG,EAAE,CAAC;YACd,IAAI,cAAc,GAAa,EAAE,CAAC;YAClC,IAAI,CAAC;gBACH,MAAM,WAAW,GAAQ;oBACvB,kEAAkE;oBAClE,WAAW,EAAE,IAAI;oBACjB,UAAU,EAAE,EAAE;oBACd,eAAe,EAAE,KAAK;iBACvB,CAAC;gBAEF,IAAI,aAAa,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBAC9C,WAAW,CAAC,OAAO,GAAG,aAAa,CAAC;gBACtC,CAAC;qBAAM,CAAC;oBACN,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;oBAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;oBACzC,WAAW,CAAC,KAAK,GAAG,KAAK,CAAC;oBAC1B,WAAW,CAAC,IAAI,GAAG,GAAG,CAAC;gBACzB,CAAC;gBAED,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;gBACjD,QAAQ,GAAG,MAAM,CAAE,MAAc,EAAE,KAAK,IAAI,CAAC,CAAC,CAAC;gBAC/C,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAE,MAAc,EAAE,KAAK,CAAC,CAAC,CAAC,CAAE,MAAc,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;gBACjF,cAAc,GAAG,KAAK;qBACnB,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;qBACpC,MAAM,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;gBACtD,IAAI,GAAG,KAAK;qBACT,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,aAAa,MAAM,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,MAAM,MAAM,CAAC,CAAC,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC;qBACvF,IAAI,CAAC,EAAE,CAAC;qBACR,IAAI,EAAE,CAAC;YACZ,CAAC;oBAAS,CAAC;gBACT,IAAI,CAAC;oBACH,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;gBACzB,CAAC;gBAAC,MAAM,CAAC;oBACP,SAAS;gBACX,CAAC;YACH,CAAC;YAED,IAAI,SAAS,GAAG,KAAK,CAAC;YACtB,IAAI,IAAI,CAAC,MAAM,GAAG,QAAQ,EAAE,CAAC;gBAC3B,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;gBAC/B,SAAS,GAAG,IAAI,CAAC;YACnB,CAAC;YAED,MAAM,aAAa,GAAG,cAAc,CAAC;YAErC,OAAO;gBACL,IAAI,EAAE,QAAQ;gBACd,QAAQ;gBACR,aAAa;gBACb,QAAQ;gBACR,SAAS;gBACT,IAAI;aACL,CAAC;QACJ,CAAC;KACF;CACF,CAAC"}

package/dist/tools/metaTools.js

@@ -723,9 +723,120 @@ const METHODOLOGY_CONTENT = {
         },
         composesWith: "Use alongside agent_bootstrap for complete autonomous infrastructure setup. Feeds into triple_verify for validation.",
     },
+    parallel_agent_teams: {
+        title: "Parallel Agent Teams — Multi-Agent Coordination",
+        description: 'Based on Anthropic\'s "Building a C Compiler with Parallel Claudes" (Feb 2026). Patterns for running multiple AI agents in parallel on a shared codebase: task locking to prevent duplicate work, role specialization, context window budget management, oracle-based testing, and progress tracking for fresh agent sessions. Reference: https://www.anthropic.com/engineering/building-c-compiler',
+        steps: [
+            {
+                step: 1,
+                name: "Orient — Check Parallel Status",
+                description: "Every new agent session starts by checking what other agents are doing. Avoid duplicate work. Review blocked tasks that need fresh eyes.",
+                tools: ["get_parallel_status", "list_agent_tasks"],
+                action: "Call get_parallel_status to see active tasks, roles, failed oracle tests, and context budgets. Then call list_agent_tasks to see what's claimed.",
+            },
+            {
+                step: 2,
+                name: "Assign Role — Specialize",
+                description: "Assign yourself a role. Specialization enables parallelism: implementer, dedup_reviewer, performance_optimizer, documentation_maintainer, code_quality_critic, test_writer, security_auditor.",
+                tools: ["assign_agent_role", "get_agent_role"],
+                action: 'Call assign_agent_role({ role: "implementer", focusArea: "auth module" }). Each parallel agent should have a different role or focus area.',
+            },
+            {
+                step: 3,
+                name: "Claim Task — Lock Before Working",
+                description: "Claim a task lock before starting work. This prevents two agents from solving the same problem. If another agent already claimed the task, pick a different one.",
+                tools: ["claim_agent_task"],
+                action: 'Call claim_agent_task({ taskKey: "fix_auth_middleware", description: "Fix JWT validation" }). If conflict, pick another task.',
+            },
+            {
+                step: 4,
+                name: "Work — Monitor Context Budget",
+                description: "Work on the task. Track context window usage to prevent pollution. Pre-compute summaries instead of dumping raw output. Log errors with ERROR prefix on same line for easy grep.",
+                tools: ["log_context_budget"],
+                action: "After reading large files or receiving large test output, call log_context_budget to track usage. Heed warnings about approaching limits.",
+            },
+            {
+                step: 5,
+                name: "Validate — Oracle Comparison",
+                description: "Compare your output against a known-good reference (oracle). The oracle pattern enables parallel debugging: each failing comparison can be assigned to a different agent.",
+                tools: ["run_oracle_comparison"],
+                action: 'Call run_oracle_comparison({ testLabel: "api_output", actualOutput: "...", expectedOutput: "...", oracleSource: "production_v2" }). Fix differences before committing.',
+            },
+            {
+                step: 6,
+                name: "Release — Handoff to Next Agent",
+                description: "Release the task lock with a progress note. If blocked, mark as blocked so another agent can pick it up with context about what was tried.",
+                tools: ["release_agent_task"],
+                action: 'Call release_agent_task({ taskKey: "fix_auth_middleware", status: "completed", progressNote: "Fixed JWT validation, added tests" }).',
+            },
+        ],
+        keyPatterns: {
+            task_locking: "File-based locks in Anthropic's implementation; SQLite-based locks in NodeBench. Prevents duplicate work when agents run in parallel.",
+            role_specialization: "Different agents for different concerns: one implements features, one deduplicates code, one optimizes performance, one maintains docs, one reviews code quality.",
+            context_pollution_prevention: "Test harnesses should NOT print thousands of useless bytes. Pre-compute summaries, use --fast sampling for large suites, log details to files.",
+            time_blindness_mitigation: "Agents can't tell time. Print incremental progress infrequently. Include --fast option for 1-10% random sample of tests.",
+            oracle_testing: "Use a known-good reference as an oracle. Compare outputs to identify which specific components are broken. Enables parallel debugging.",
+            progress_files: "Maintain running docs of status, failed approaches, and remaining tasks. Fresh agent sessions read these to orient themselves.",
+            bootstrap_external_repos: "When connected to another project that lacks parallel agent capabilities, use bootstrap_parallel_agents to auto-detect gaps and scaffold infrastructure. The tool scans 7 categories (task coordination, roles, oracle, context budget, progress files, AGENTS.md parallel section, git worktrees) and generates ready-to-use files. Follow the AI Flywheel closed loop: detect → scaffold → verify → fix → document.",
+        },
+        claudeCodeNativePath: {
+            title: "Claude Code Native Parallel Subagents",
+            description: "If you are using Claude Code (Anthropic's CLI), you already have parallel subagent support via the Task tool. NodeBench MCP adds coordination, tracking, and impact measurement on top of Claude Code's native parallelism.",
+            howItWorks: [
+                "1. The main Claude Code session is the COORDINATOR — it breaks work into independent tasks",
+                "2. Each Task tool call spawns a SUBAGENT — a separate Claude instance with its own context",
+                "3. Each subagent has access to the same NodeBench MCP tools (shared SQLite database)",
+                "4. Subagents use claim_agent_task/release_agent_task to coordinate without conflicts",
+                "5. The coordinator uses get_parallel_status to monitor progress across all subagents",
+            ],
+            exampleWorkflow: [
+                "COORDINATOR: Break work into 3 independent tasks",
+                "COORDINATOR: For each task, spawn a Task tool subagent with prompt:",
+                '  "You have access to NodeBench MCP. First call claim_agent_task({ taskKey: \'fix_auth\' }), then do the work, then call release_agent_task with a progress note."',
+                "COORDINATOR: Call get_parallel_status to see all subagent progress",
+                "COORDINATOR: When all subagents complete, aggregate results and run quality gate",
+            ],
+            impact: "Prevents duplicate work across subagents, captures per-task learnings, enables oracle-based validation, tracks context budget per subagent",
+        },
+        whenToUseParallelTools: {
+            description: "Parallel agent tools are NOT always needed. Use them ONLY when the situation calls for coordination.",
+            useWhen: [
+                "You are running 2+ agent sessions (Claude Code subagents, worktrees, or separate terminals)",
+                "You need to prevent two agents from working on the same thing",
+                "You want oracle-based testing to split failures into independent work items",
+                "You are bootstrapping parallel agent infrastructure for an external project",
+            ],
+            doNotUseWhen: [
+                "You are a single agent working sequentially — standard verification/eval tools are sufficient",
+                "The task is simple enough for one agent to handle end-to-end",
+                "You are not in a multi-agent or multi-session context",
+            ],
+        },
+        impactPerStep: {
+            orient: "IMPACT: Prevents wasted time re-doing work another agent already started or completed",
+            assign_role: "IMPACT: Specialization enables parallelism — agents don't step on each other's toes",
+            claim_task: "IMPACT: Zero duplicate work — each task is owned by exactly one agent",
+            monitor_budget: "IMPACT: Prevents context window exhaustion that forces expensive session restarts",
+            oracle_validate: "IMPACT: Catches regressions by comparing against known-good reference — each failure is an independent debuggable work item",
+            release_handoff: "IMPACT: Progress notes ensure the next agent (or next session) doesn't restart from scratch",
+        },
+        bootstrapForExternalRepos: {
+            description: "When nodebench-mcp detects that a target project repo does not have parallel agent infrastructure, it can automatically bootstrap it using the AI Flywheel closed loop.",
+            steps: [
+                "1. DETECT: Call bootstrap_parallel_agents({ projectRoot: '/path/to/their/repo', dryRun: true }) — scans 7 categories and returns gap report",
+                "2. SCAFFOLD: Call bootstrap_parallel_agents({ projectRoot: '...', dryRun: false, techStack: 'TypeScript/React' }) — creates .parallel-agents/ dir, progress.md, roles.json, lock dirs, oracle dirs",
+                "3. AGENTS.MD: Call generate_parallel_agents_md({ techStack: '...', projectName: '...', maxAgents: 4 }) — generates portable AGENTS.md section, paste into their repo",
+                "4. VERIFY: Run the 6-step flywheel plan returned by bootstrap_parallel_agents — static analysis, happy path, conflict test, oracle test, gap re-scan, document",
+                "5. FIX: If any flywheel step fails, fix and re-verify from step 1",
+                "6. DOCUMENT: Call record_learning with patterns discovered during bootstrap",
+            ],
+        },
+        authoritativeSource: "https://www.anthropic.com/engineering/building-c-compiler",
+        composesWith: "Works with verification cycles (each agent runs its own), eval runs (aggregate across agents), and learnings (shared knowledge base). Task claims compose with the mandatory flywheel. bootstrap_parallel_agents works on ANY project directory — not just nodebench.",
+    },
     self_reinforced_learning: {
         title: "Self-Reinforced Learning Loop",
-        description: "Continuous self-improvement cycle for agents using the MCP. As users develop with the tools, the system accumulates trajectory data, identifies patterns, and surfaces recommendations. The loop: Use tools → Log calls → Analyze trajectories → Find gaps → Recommend improvements → Apply → Re-analyze. Over time, the system gets smarter about the project's specific development patterns.",
+        description: "Continuous self-improvement cycle for agents using the MCP. Tool calls are now auto-instrumented — every call is automatically logged with timing and status. The loop: Use tools → Auto-log → Analyze trajectories → Find gaps → Clean stale data → Synthesize recon → Recommend improvements → Apply → Re-analyze. Over time, the system gets smarter about the project's specific development patterns.",
         steps: [
             {
                 step: 1,
@@ -757,6 +868,13 @@ const METHODOLOGY_CONTENT = {
             },
             {
                 step: 5,
+                name: "Clean & Synthesize",
+                description: "Clean up stale runs and synthesize recon findings into learnings. Orphaned eval runs and stale gaps skew health scores. Recon findings are ephemeral — convert them into searchable learnings.",
+                tools: ["cleanup_stale_runs", "synthesize_recon_to_learnings"],
+                action: "Call cleanup_stale_runs(dryRun=true) to preview, then dryRun=false to clean. Call synthesize_recon_to_learnings(dryRun=true) to preview conversions, then dryRun=false.",
+            },
+            {
+                step: 6,
                 name: "Apply & Re-Analyze",
                 description: "Implement the top recommendations, then re-run the analysis to verify improvement. This closes the loop and makes the system progressively smarter.",
                 tools: ["record_learning", "get_self_eval_report"],
@@ -789,7 +907,8 @@ const METHODOLOGY_CONTENT = {
                     agents_md_maintenance: "AGENTS.md Maintenance — keep documentation synchronized with implementations",
                     agent_bootstrap: "Agent Bootstrap — self-discover infrastructure, triple verification with authoritative sources, self-implement missing components",
                     autonomous_maintenance: "Autonomous Maintenance — risk-tiered execution, re-update before create, self-maintenance cycles, OpenClaw scaffolding, Ralph Wiggum loops",
-                    self_reinforced_learning: "Self-Reinforced Learning — trajectory analysis, self-evaluation reports, improvement recommendations, closed-loop optimization",
+                    parallel_agent_teams: "Parallel Agent Teams — task locking, role specialization, context budget management, oracle testing. Based on Anthropic's 'Building a C Compiler with Parallel Claudes' (Feb 2026)",
+                    self_reinforced_learning: "Self-Reinforced Learning — auto-instrumented trajectory analysis, self-evaluation reports, improvement recommendations, stale run cleanup, recon synthesis, closed-loop optimization",
                 },
             },
             {
@@ -851,6 +970,7 @@ export function createMetaTools(allTools) {
                             "documentation",
                             "bootstrap",
                             "self_eval",
+                            "parallel_agents",
                             "meta",
                         ],
                         description: "Filter by tool category (optional)",
@@ -945,6 +1065,20 @@ export function createMetaTools(allTools) {
                         "get_trajectory_analysis",
                         "get_self_eval_report",
                         "get_improvement_recommendations",
+                        "cleanup_stale_runs",
+                        "synthesize_recon_to_learnings",
+                    ],
+                    parallel_agents: [
+                        "claim_agent_task",
+                        "release_agent_task",
+                        "list_agent_tasks",
+                        "assign_agent_role",
+                        "get_agent_role",
+                        "log_context_budget",
+                        "run_oracle_comparison",
+                        "get_parallel_status",
+                        "bootstrap_parallel_agents",
+                        "generate_parallel_agents_md",
                     ],
                     meta: ["findTools", "getMethodology"],
                 };
@@ -957,6 +1091,36 @@ export function createMetaTools(allTools) {
                     const text = `${t.name} ${t.description}`.toLowerCase();
                     return query.split(/\s+/).some((word) => text.includes(word));
                 });
+                // Contextual recommendations: surface parallel tools only when relevant
+                const parallelKeywords = ["parallel", "agent", "team", "multi-agent", "subagent", "concurrent", "worktree", "oracle", "lock", "coordinate", "role"];
+                const queryHintsParallel = parallelKeywords.some((kw) => query.includes(kw));
+                const parallelToolNames = new Set(categoryMap.parallel_agents);
+                // Add contextual hint about parallel tools
+                const contextHints = [];
+                if (!queryHintsParallel && !category) {
+                    // Don't surface parallel tools unless the query is about parallel/agent work
+                    const filtered = matches.filter((t) => !parallelToolNames.has(t.name));
+                    if (filtered.length < matches.length) {
+                        contextHints.push("Parallel agent tools are available but not shown (query didn't indicate multi-agent work). " +
+                            "Use findTools({ category: 'parallel_agents' }) or include 'parallel'/'agent'/'team' in your query to discover them.");
+                    }
+                    return {
+                        query,
+                        count: filtered.length,
+                        tools: filtered.map((t) => ({
+                            name: t.name,
+                            description: t.description,
+                        })),
+                        contextHints,
+                        tip: "Use category filter or specific keywords to narrow results. Call getMethodology('overview') for all available methodologies.",
+                    };
+                }
+                // When parallel tools ARE relevant, add Claude Code guidance
+                if (queryHintsParallel || category === "parallel_agents") {
+                    contextHints.push("Claude Code users: Use the Task tool to spawn parallel subagents, each with access to NodeBench MCP. " +
+                        "Each subagent calls claim_agent_task to lock work, assign_agent_role for specialization, and release_agent_task when done. " +
+                        "Call getMethodology('parallel_agent_teams') for the full workflow.");
+                }
                 return {
                     query,
                     count: matches.length,
@@ -964,12 +1128,14 @@ export function createMetaTools(allTools) {
                         name: t.name,
                         description: t.description,
                     })),
+                    contextHints,
+                    tip: "Use category filter or specific keywords to narrow results. Call getMethodology('overview') for all available methodologies.",
                 };
             },
         },
         {
             name: "getMethodology",
-            description: 'Get step-by-step guidance for a development methodology. Topics: verification, eval, flywheel, mandatory_flywheel, reconnaissance, quality_gates, ui_ux_qa, agentic_vision, closed_loop, learnings, project_ideation, tech_stack_2026, telemetry_setup, agents_md_maintenance, agent_bootstrap, autonomous_maintenance, self_reinforced_learning, overview. Call with topic "overview" to see all available methodologies.',
+            description: 'Get step-by-step guidance for a development methodology. Topics: verification, eval, flywheel, mandatory_flywheel, reconnaissance, quality_gates, ui_ux_qa, agentic_vision, closed_loop, learnings, project_ideation, tech_stack_2026, telemetry_setup, agents_md_maintenance, agent_bootstrap, autonomous_maintenance, parallel_agent_teams, self_reinforced_learning, overview. Call with topic "overview" to see all available methodologies.',
             inputSchema: {
                 type: "object",
                 properties: {
@@ -992,6 +1158,7 @@ export function createMetaTools(allTools) {
                             "agents_md_maintenance",
                             "agent_bootstrap",
                             "autonomous_maintenance",
+                            "parallel_agent_teams",
                             "self_reinforced_learning",
                             "overview",
                         ],