@coreyuan/vector-mind 1.0.20 → 1.0.32

package/dist/index.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 import path from "node:path";
 import fs from "node:fs";
+import * as readline from "node:readline";
 import crypto from "node:crypto";
 import os from "node:os";
+import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import chokidar from "chokidar";
 import Database from "better-sqlite3";
@@ -11,8 +13,10 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { toJsonSchemaCompat } from "@modelcontextprotocol/sdk/server/zod-json-schema-compat.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { BUILTIN_CONVENTIONS } from "./builtin-conventions.js";
+import { BUILTIN_ARCHITECTURE_AND_CODE_ORGANIZATION_INSTRUCTIONS, BUILTIN_DESTRUCTIVE_OPERATION_GUARD_INSTRUCTIONS, BUILTIN_LOW_OVERHEAD_WORKFLOW_INSTRUCTIONS, BUILTIN_PLAN_LITE_INSTRUCTIONS, BUILTIN_WRITE_POLICY_INSTRUCTIONS, } from "./builtin-instructions.js";
 const SERVER_NAME = "vector-mind";
-const SERVER_VERSION = "1.0.19";
+const SERVER_VERSION = "1.0.32";
 const rootFromEnv = process.env.VECTORMIND_ROOT?.trim() ?? "";
 const prettyJsonOutput = ["1", "true", "on", "yes"].includes((process.env.VECTORMIND_PRETTY_JSON ?? "").trim().toLowerCase());
 const debugLogEnabled = ["1", "true", "on", "yes"].includes((process.env.VECTORMIND_DEBUG_LOG ?? "").trim().toLowerCase());
@@ -61,6 +65,33 @@ const PENDING_PRUNE_EVERY = (() => {
         return 500;
     return n;
 })();
+const RIPGREP_RESOLVE_TIMEOUT_MS = 5_000;
+const RIPGREP_SEARCH_TIMEOUT_MS = 30_000;
+const RIPGREP_MAX_BUFFER_BYTES = 16 * 1024 * 1024;
+let cachedRipgrepCommand;
+let cachedRipgrepResolveError = null;
+function getCodexHomeDir() {
+    const raw = process.env.CODEX_HOME?.trim();
+    if (raw)
+        return path.resolve(raw);
+    return path.join(os.homedir(), ".codex");
+}
+function getAgentsHomeDir() {
+    const raw = process.env.AGENTS_HOME?.trim();
+    if (raw)
+        return path.resolve(raw);
+    return path.join(os.homedir(), ".agents");
+}
+function getAllowedCodexTextRoots() {
+    const codexHome = getCodexHomeDir();
+    const agentsHome = getAgentsHomeDir();
+    return Array.from(new Set([
+        path.join(codexHome, "skills"),
+        path.join(codexHome, "prompts"),
+        path.join(codexHome, "rules"),
+        path.join(agentsHome, "skills"),
+    ].map((p) => path.resolve(p))));
+}
 const INDEX_MAX_CODE_BYTES = (() => {
     const raw = process.env.VECTORMIND_INDEX_MAX_CODE_BYTES?.trim();
     if (!raw)
@@ -227,8 +258,18 @@ function summarizeActivityEvent(e) {
             return `pending_list returned=${String(d.returned ?? "")} total=${String(d.total ?? "")}`;
         case "semantic_search":
             return `semantic_search mode=${String(d.mode ?? "")} q=${String(d.query ?? "")} matches=${String(d.matches ?? "")}`;
+        case "grep":
+            return `grep backend=${String(d.backend ?? "")} q=${String(d.query ?? "")} matches=${String(d.matches ?? "")} truncated=${String(d.truncated ?? "")}`;
         case "query_codebase":
             return `query_codebase q=${String(d.query ?? "")} matches=${String(d.matches ?? "")}`;
+        case "read_file_lines":
+            return `read_file_lines file=${String(d.file_path ?? "")} returned=${String(d.returned ?? "")} truncated=${String(d.truncated ?? "")}`;
+        case "read_file_text":
+            return `read_file_text file=${String(d.file_path ?? "")} returned=${String(d.returned_chars ?? "")}/${String(d.total_chars ?? "")} truncated=${String(d.truncated ?? "")}`;
+        case "list_project_files":
+            return `list_project_files path=${String(d.path ?? "")} returned=${String(d.returned ?? "")} scanned=${String(d.scanned ?? "")} truncated=${String(d.truncated ?? "")}`;
+        case "read_codex_text_file":
+            return `read_codex_text_file file=${String(d.file_path ?? "")} returned=${String(d.returned_chars ?? "")}/${String(d.total_chars ?? "")} truncated=${String(d.truncated ?? "")}`;
         case "start_requirement":
             return `start_requirement #${String(d.req_id ?? "")} ${String(d.title ?? "")}`;
         case "sync_change_intent":
@@ -470,6 +511,22 @@ const IGNORED_PATH_SEGMENTS = new Set([
     "x64",
     "x86",
 ].map((s) => s.toLowerCase()));
+const NOISE_FILE_SUFFIXES = [
+    ".min.js",
+    ".min.css",
+    ".bundle.js",
+    ".bundle.css",
+    ".chunk.js",
+    ".chunk.css",
+];
+const NOISE_FILE_BASENAMES = [
+    "package-lock.json",
+    "pnpm-lock.yaml",
+    "yarn.lock",
+    "bun.lockb",
+    "cargo.lock",
+    "composer.lock",
+];
 const IGNORED_LIKE_PATTERNS = (() => {
     const patterns = [];
     for (const seg of IGNORED_PATH_SEGMENTS) {
@@ -573,27 +630,11 @@ function pruneIgnoredIndexesByPathPatterns() {
 function pruneFilenameNoiseIndexes() {
     if (!db)
         return { chunks_deleted: 0, symbols_deleted: 0 };
-    const suffixes = [
-        ".min.js",
-        ".min.css",
-        ".bundle.js",
-        ".bundle.css",
-        ".chunk.js",
-        ".chunk.css",
-    ];
-    const baseNames = [
-        "package-lock.json",
-        "pnpm-lock.yaml",
-        "yarn.lock",
-        "bun.lockb",
-        "cargo.lock",
-        "composer.lock",
-    ];
     try {
-        const suffixWhere = suffixes.map(() => "LOWER(file_path) LIKE ?").join(" OR ");
-        const baseWhere = baseNames.map(() => "LOWER(file_path) LIKE ?").join(" OR ");
-        const suffixArgs = suffixes.map((s) => `%${s}`);
-        const baseArgs = baseNames.map((n) => `%/${n}`);
+        const suffixWhere = NOISE_FILE_SUFFIXES.map(() => "LOWER(file_path) LIKE ?").join(" OR ");
+        const baseWhere = NOISE_FILE_BASENAMES.map(() => "LOWER(file_path) LIKE ?").join(" OR ");
+        const suffixArgs = NOISE_FILE_SUFFIXES.map((s) => `%${s}`);
+        const baseArgs = NOISE_FILE_BASENAMES.map((n) => `%/${n}`);
         const whereParts = [];
         const args = [];
         if (suffixWhere) {
@@ -675,21 +716,9 @@ function isSymbolIndexableFile(filePath) {
 }
 function shouldIgnoreContentFile(filePath) {
     const base = path.basename(filePath).toLowerCase();
-    const ignoreNames = new Set([
-        "package-lock.json",
-        "pnpm-lock.yaml",
-        "yarn.lock",
-        "bun.lockb",
-        "cargo.lock",
-        "composer.lock",
-    ]);
-    if (ignoreNames.has(base))
-        return true;
-    if (base.endsWith(".min.js") || base.endsWith(".min.css"))
-        return true;
-    if (base.endsWith(".bundle.js") || base.endsWith(".bundle.css"))
+    if (NOISE_FILE_BASENAMES.includes(base))
         return true;
-    if (base.endsWith(".chunk.js") || base.endsWith(".chunk.css"))
+    if (NOISE_FILE_SUFFIXES.some((suffix) => base.endsWith(suffix)))
         return true;
     return false;
 }
@@ -1133,6 +1162,66 @@ const SyncChangeIntentArgsSchema = ProjectRootArgSchema.merge(z.object({
 const QueryCodebaseArgsSchema = ProjectRootArgSchema.merge(z.object({
     query: z.string().min(1),
 }));
+const GrepArgsSchema = ProjectRootArgSchema.merge(z.object({
+    // Pattern to search for. Defaults to regex mode for parity with tools like ripgrep.
+    query: z.string().min(1),
+    mode: z.enum(["regex", "literal"]).optional().default("regex"),
+    // If case_sensitive is omitted and smart_case=true, uppercase => case-sensitive, otherwise case-insensitive.
+    smart_case: z.boolean().optional().default(true),
+    case_sensitive: z.boolean().optional(),
+    // Compatibility knob for the indexed fallback when ripgrep is unavailable.
+    literal_hint: z.string().optional().default(""),
+    // Compatibility knob for the indexed fallback when ripgrep is unavailable.
+    kinds: z.array(z.string().min(1)).optional(),
+    include_paths: z.array(z.string().min(1)).optional(),
+    exclude_paths: z.array(z.string().min(1)).optional(),
+    max_results: z.number().int().min(1).max(5000).optional().default(200),
+    // Compatibility knob for the indexed fallback when ripgrep is unavailable.
+    max_candidates: z.number().int().min(1).max(50_000).optional(),
+}));
+const ReadFileLinesArgsSchema = ProjectRootArgSchema.merge(z.object({
+    // Relative to project_root, or an absolute path under project_root.
+    path: z.string().min(1),
+    from_line: z.number().int().min(1).optional().default(1),
+    to_line: z.number().int().min(1).optional(),
+    // Convenience for "head": if set, reads from_line..(from_line+total_count-1) unless to_line is provided.
+    total_count: z.number().int().min(1).optional(),
+    // Hard limits to avoid huge token blow-ups.
+    max_lines: z.number().int().min(1).max(2000).optional().default(400),
+    max_chars: z.number().int().min(200).max(200_000).optional().default(20_000),
+}));
+const ReadFileTextArgsSchema = ProjectRootArgSchema.merge(z.object({
+    // Relative to project_root, or an absolute path under project_root.
+    path: z.string().min(1),
+    // Character offset in the decoded UTF-8 text.
+    offset: z.number().int().min(0).optional().default(0),
+    // Hard limit on returned text to avoid huge outputs.
+    max_chars: z.number().int().min(1).max(200_000).optional().default(20_000),
+    // Safety guard for raw reads; use read_file_lines on larger files.
+    max_file_bytes: z.number().int().min(1_000).max(5_000_000).optional().default(1_000_000),
+}));
+const ReadCodexTextFileArgsSchema = ProjectRootArgSchema.merge(z.object({
+    // Absolute path, file:// URI, or a path under CODEX_HOME / AGENTS_HOME allowed roots.
+    path: z.string().min(1),
+    offset: z.number().int().min(0).optional().default(0),
+    max_chars: z.number().int().min(1).max(200_000).optional().default(20_000),
+    max_file_bytes: z.number().int().min(1_000).max(5_000_000).optional().default(1_000_000),
+}));
+const ListProjectFilesArgsSchema = ProjectRootArgSchema.merge(z.object({
+    // Relative directory/file path under project_root. "." means the project root.
+    path: z.string().optional().default("."),
+    recursive: z.boolean().optional().default(false),
+    max_depth: z.number().int().min(1).max(20).optional().default(4),
+    include_files: z.boolean().optional().default(true),
+    include_dirs: z.boolean().optional().default(true),
+    include_hidden: z.boolean().optional().default(false),
+    respect_ignore: z.boolean().optional().default(true),
+    include_paths: z.array(z.string().min(1)).optional(),
+    exclude_paths: z.array(z.string().min(1)).optional(),
+    extensions: z.array(z.string().min(1)).optional(),
+    max_results: z.number().int().min(1).max(5000).optional().default(200),
+    include_stats: z.boolean().optional().default(false),
+}));
 const UpsertProjectSummaryArgsSchema = ProjectRootArgSchema.merge(z.object({
     summary: z.string().min(1),
 }));
@@ -1429,6 +1518,34 @@ function toMemoryItemPreview(row, includeContent, previewChars, contentMaxChars)
         updated_at: row.updated_at,
     };
 }
+function getBuiltinConventionRows() {
+    return BUILTIN_CONVENTIONS.map((spec, idx) => ({
+        id: -1000 - idx,
+        kind: "convention",
+        title: spec.key,
+        content: spec.content,
+        file_path: null,
+        start_line: null,
+        end_line: null,
+        req_id: null,
+        metadata_json: safeJson({ source: "builtin", key: spec.key, tags: spec.tags ?? [] }),
+        content_hash: sha256Hex(spec.content),
+        created_at: "builtin",
+        updated_at: "builtin",
+    }));
+}
+function getConventionPreviews(conventionsLimit, previewChars, contentMaxChars) {
+    if (conventionsLimit <= 0)
+        return [];
+    const builtin = getBuiltinConventionRows()
+        .map((row) => toMemoryItemPreview(row, false, previewChars, contentMaxChars))
+        .slice(0, conventionsLimit);
+    if (builtin.length >= conventionsLimit)
+        return builtin;
+    const remaining = conventionsLimit - builtin.length;
+    const stored = listConventionsStmt.all(remaining).map((c) => toMemoryItemPreview(c, false, previewChars, contentMaxChars));
+    return [...builtin, ...stored];
+}
 function toRequirementPreview(req, includeContent, previewChars, contentMaxChars) {
     const context = req.context_data ?? null;
     const contextPreview = context ? makePreviewText(context, previewChars) : null;
@@ -1687,18 +1804,740 @@ async function semanticSearchHybridInternal(opts) {
     }
     return likeSearchInternal(opts);
 }
-const server = new Server({ name: SERVER_NAME, version: SERVER_VERSION }, {
-    capabilities: { tools: {} },
-    instructions: [
+function escapeRegExp(literal) {
+    return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function hasUppercaseAscii(s) {
+    return /[A-Z]/.test(s);
+}
+function extractLongestLiteralFromRegex(pattern) {
+    // Best-effort extraction: pull the longest literal run to use as an indexed candidate hint.
+    // This is intentionally conservative; if we can't find a reasonable literal anchor, callers
+    // should pass `literal_hint` or narrow with include_paths.
+    let best = "";
+    let cur = "";
+    let inClass = false;
+    const flush = () => {
+        if (cur.length > best.length)
+            best = cur;
+        cur = "";
+    };
+    for (let i = 0; i < pattern.length; i++) {
+        const ch = pattern[i] ?? "";
+        if (!ch)
+            break;
+        if (inClass) {
+            // Skip until the closing bracket.
+            if (ch === "]")
+                inClass = false;
+            flush();
+            continue;
+        }
+        if (ch === "[") {
+            inClass = true;
+            flush();
+            continue;
+        }
+        if (ch === "\\") {
+            const next = pattern[i + 1] ?? "";
+            if (!next) {
+                flush();
+                continue;
+            }
+            // Common regex escapes that are NOT literal characters.
+            if (/[dDsSwWbB0-9]/.test(next)) {
+                flush();
+                i += 1;
+                continue;
+            }
+            // Treat \x as literal x (e.g. \( \) \. \\).
+            cur += next;
+            i += 1;
+            continue;
+        }
+        // Regex metacharacters.
+        if (".*+?^$|(){}".includes(ch)) {
+            flush();
+            continue;
+        }
+        cur += ch;
+    }
+    flush();
+    return best;
+}
+function normalizePathNeedle(s) {
+    return s.replace(/\\/g, "/").toLowerCase();
+}
+function passesPathFilters(filePath, includePaths, excludePaths) {
+    const fp = filePath.toLowerCase();
+    if (excludePaths?.length) {
+        for (const raw of excludePaths) {
+            const n = normalizePathNeedle(raw);
+            if (!n)
+                continue;
+            if (fp.includes(n))
+                return false;
+        }
+    }
+    if (includePaths?.length) {
+        for (const raw of includePaths) {
+            const n = normalizePathNeedle(raw);
+            if (!n)
+                continue;
+            if (fp.includes(n))
+                return true;
+        }
+        return false;
+    }
+    return true;
+}
+function buildLineStarts(text) {
+    const starts = [0];
+    for (let i = 0; i < text.length; i++) {
+        if (text.charCodeAt(i) === 10)
+            starts.push(i + 1); // '\n'
+    }
+    return starts;
+}
+function lineIndexForOffset(lineStarts, offset) {
+    let lo = 0;
+    let hi = lineStarts.length - 1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        const v = lineStarts[mid] ?? 0;
+        if (v <= offset)
+            lo = mid + 1;
+        else
+            hi = mid - 1;
+    }
+    return Math.max(0, lo - 1);
+}
+function compileGrepRegex(opts) {
+    const flags = `${opts.caseSensitive ? "" : "i"}gm`;
+    const source = opts.mode === "literal" ? escapeRegExp(opts.query) : opts.query;
+    return new RegExp(source, flags);
+}
+function trimGrepText(input, maxChars) {
+    if (input.length <= maxChars)
+        return input;
+    return `${input.slice(0, maxChars)}…`;
+}
+function buildGrepPreviewSnippet(lineText, col, maxChars = 500) {
+    const clean = lineText.replace(/\r$/, "");
+    if (clean.length <= maxChars)
+        return clean;
+    const matchIndex = Math.max(0, col - 1);
+    let start = Math.max(0, matchIndex - Math.floor(maxChars * 0.35));
+    if (start + maxChars > clean.length)
+        start = Math.max(0, clean.length - maxChars);
+    const end = Math.min(clean.length, start + maxChars);
+    let snippet = clean.slice(start, end);
+    if (start > 0)
+        snippet = `…${snippet}`;
+    if (end < clean.length)
+        snippet = `${snippet}…`;
+    return snippet;
+}
+function extractGrepMatchText(opts) {
+    const clean = opts.lineText.replace(/\r$/, "");
+    const startIndex = Math.max(0, opts.col - 1);
+    if (opts.mode === "literal") {
+        const slice = clean.slice(startIndex, startIndex + opts.query.length) || opts.query;
+        return trimGrepText(slice, 200);
+    }
+    try {
+        const flags = opts.caseSensitive ? "m" : "im";
+        const anchored = new RegExp(opts.query, flags);
+        const tail = clean.slice(startIndex);
+        const found = anchored.exec(tail);
+        if (found?.index === 0 && found[0])
+            return trimGrepText(found[0], 200);
+    }
+    catch { }
+    const fallback = clean.slice(startIndex, Math.min(clean.length, startIndex + 200));
+    return trimGrepText(fallback || opts.query, 200);
+}
+function toProcessText(value) {
+    if (typeof value === "string")
+        return value;
+    if (value == null)
+        return "";
+    return value.toString("utf8");
+}
+function formatProcessFailure(result) {
+    if (result.error)
+        return `${result.error.name}: ${result.error.message}`;
+    const stderr = toProcessText(result.stderr).trim();
+    if (stderr)
+        return stderr;
+    const stdout = toProcessText(result.stdout).trim();
+    if (stdout)
+        return stdout;
+    if (typeof result.status === "number")
+        return `exit ${result.status}`;
+    if (result.signal)
+        return `signal ${result.signal}`;
+    return "unknown failure";
+}
+function buildRipgrepEnv() {
+    const env = { ...process.env };
+    delete env.RIPGREP_CONFIG_PATH;
+    return env;
+}
+function pushUniqueCandidate(candidates, seen, raw) {
+    const value = raw?.trim();
+    if (!value || seen.has(value))
+        return;
+    seen.add(value);
+    candidates.push(value);
+}
+function listChildDirsSafe(dirPath) {
+    try {
+        return fs
+            .readdirSync(dirPath, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => path.join(dirPath, entry.name));
+    }
+    catch {
+        return [];
+    }
+}
+function collectRipgrepCandidates() {
+    const candidates = [];
+    const seen = new Set();
+    const override = process.env.VECTORMIND_RG_PATH?.trim();
+    if (override)
+        pushUniqueCandidate(candidates, seen, path.resolve(override));
+    if (process.platform === "win32") {
+        pushUniqueCandidate(candidates, seen, "rg.exe");
+        pushUniqueCandidate(candidates, seen, "rg");
+    }
+    else {
+        pushUniqueCandidate(candidates, seen, "rg");
+    }
+    for (const rawDir of (process.env.PATH ?? "").split(path.delimiter)) {
+        const dir = rawDir.trim().replace(/^"+|"+$/g, "");
+        if (!dir)
+            continue;
+        if (process.platform === "win32") {
+            pushUniqueCandidate(candidates, seen, path.join(dir, "rg.exe"));
+            pushUniqueCandidate(candidates, seen, path.join(dir, "rg"));
+        }
+        else {
+            pushUniqueCandidate(candidates, seen, path.join(dir, "rg"));
+        }
+    }
+    if (process.platform === "win32") {
+        const localAppData = process.env.LOCALAPPDATA?.trim();
+        const programsDir = localAppData ? path.join(localAppData, "Programs") : "";
+        if (programsDir && fs.existsSync(programsDir)) {
+            for (const appDir of listChildDirsSafe(programsDir)) {
+                pushUniqueCandidate(candidates, seen, path.join(appDir, "resources", "app", "node_modules", "@vscode", "ripgrep", "bin", "rg.exe"));
+                pushUniqueCandidate(candidates, seen, path.join(appDir, "resources", "app", "extensions", "kiro.kiro-agent", "node_modules", "@vscode", "ripgrep", "bin", "rg.exe"));
+                for (const childDir of listChildDirsSafe(appDir)) {
+                    pushUniqueCandidate(candidates, seen, path.join(childDir, "resources", "app", "node_modules", "@vscode", "ripgrep", "bin", "rg.exe"));
+                }
+            }
+        }
+    }
+    return candidates;
+}
+function resolveRipgrepCommand() {
+    if (typeof cachedRipgrepCommand !== "undefined") {
+        if (cachedRipgrepCommand)
+            return { ok: true, command: cachedRipgrepCommand };
+        return { ok: false, error: cachedRipgrepResolveError ?? "ripgrep unavailable", attempts: [] };
+    }
+    const env = buildRipgrepEnv();
+    const attempts = [];
+    for (const candidate of collectRipgrepCandidates()) {
+        const probe = spawnSync(candidate, ["--version"], {
+            cwd: projectRoot || undefined,
+            env,
+            encoding: "utf8",
+            windowsHide: true,
+            timeout: RIPGREP_RESOLVE_TIMEOUT_MS,
+            maxBuffer: 256 * 1024,
+        });
+        if (probe.status === 0) {
+            cachedRipgrepCommand = candidate;
+            cachedRipgrepResolveError = null;
+            return { ok: true, command: candidate };
+        }
+        attempts.push(`${candidate}: ${formatProcessFailure(probe)}`);
+    }
+    cachedRipgrepCommand = null;
+    cachedRipgrepResolveError = attempts.slice(0, 8).join(" | ") || "ripgrep unavailable";
+    return { ok: false, error: cachedRipgrepResolveError, attempts };
+}
+function appendBuiltInRipgrepExcludes(args) {
+    for (const segment of IGNORED_PATH_SEGMENTS) {
+        args.push("-g", `!${segment}/**`);
+        args.push("-g", `!**/${segment}/**`);
+    }
+    for (const baseName of NOISE_FILE_BASENAMES) {
+        args.push("-g", `!**/${baseName}`);
+    }
+    for (const suffix of NOISE_FILE_SUFFIXES) {
+        args.push("-g", `!**/*${suffix}`);
+    }
+}
+function runRipgrepSearch(opts) {
+    const resolved = resolveRipgrepCommand();
+    if (!resolved.ok) {
+        return { ok: false, unavailable: true, error: resolved.error, attempts: resolved.attempts };
+    }
+    const args = ["--vimgrep", "--no-heading", "--color", "never", "-m", String(opts.maxResults)];
+    args.push(opts.caseSensitive ? "-s" : "-i");
+    if (opts.mode === "literal")
+        args.push("-F");
+    appendBuiltInRipgrepExcludes(args);
+    args.push("--", opts.query, ".");
+    const result = spawnSync(resolved.command, args, {
+        cwd: projectRoot,
+        env: buildRipgrepEnv(),
+        encoding: "utf8",
+        windowsHide: true,
+        timeout: RIPGREP_SEARCH_TIMEOUT_MS,
+        maxBuffer: RIPGREP_MAX_BUFFER_BYTES,
+    });
+    if (result.error) {
+        return {
+            ok: false,
+            unavailable: false,
+            error: formatProcessFailure(result),
+            attempts: [],
+            rg_command: resolved.command,
+            exit_status: result.status,
+        };
+    }
+    const status = result.status ?? 0;
+    if (status !== 0 && status !== 1) {
+        return {
+            ok: false,
+            unavailable: false,
+            error: formatProcessFailure(result),
+            attempts: [],
+            rg_command: resolved.command,
+            exit_status: status,
+        };
+    }
+    const matches = [];
+    let totalMatches = 0;
+    let truncated = false;
+    for (const rawLine of toProcessText(result.stdout).split(/\r?\n/)) {
+        if (!rawLine)
+            continue;
+        const parsed = /^(.*?):(\d+):(\d+):(.*)$/.exec(rawLine);
+        if (!parsed)
+            continue;
+        const filePath = path.posix
+            .normalize(parsed[1].replace(/\\/g, "/"))
+            .replace(/^\.\/+/, "");
+        const lineNumber = Number.parseInt(parsed[2] ?? "0", 10);
+        const colNumber = Number.parseInt(parsed[3] ?? "0", 10);
+        const lineText = (parsed[4] ?? "").replace(/\r$/, "");
+        if (!filePath || !Number.isFinite(lineNumber) || !Number.isFinite(colNumber))
+            continue;
+        if (shouldIgnoreDbFilePath(filePath))
+            continue;
+        if (shouldIgnoreContentFile(filePath))
+            continue;
+        if (!passesPathFilters(filePath, opts.includePaths, opts.excludePaths))
+            continue;
+        totalMatches += 1;
+        if (matches.length >= opts.maxResults) {
+            truncated = true;
+            continue;
+        }
+        matches.push({
+            file_path: filePath,
+            kind: "file_match",
+            line: lineNumber,
+            col: colNumber,
+            preview: buildGrepPreviewSnippet(lineText, colNumber),
+            match: extractGrepMatchText({
+                lineText,
+                query: opts.query,
+                mode: opts.mode,
+                caseSensitive: opts.caseSensitive,
+                col: colNumber,
+            }),
+        });
+    }
+    return {
+        ok: true,
+        backend: "ripgrep",
+        rg_command: resolved.command,
+        matches,
+        truncated,
+        total_matches: totalMatches,
+    };
+}
+function runIndexedGrepSearch(opts) {
+    const hint = (() => {
+        if (opts.mode === "literal")
+            return opts.query;
+        const explicit = opts.literalHint.trim();
+        if (explicit)
+            return explicit;
+        return extractLongestLiteralFromRegex(opts.query);
+    })();
+    if (opts.mode === "regex" && hint.trim().length < 3) {
+        throw new Error("Regex has no sufficiently long literal anchor for indexed narrowing. Provide literal_hint (>= 3 chars) or narrow with include_paths.");
+    }
+    let re;
+    try {
+        re = compileGrepRegex({
+            query: opts.query,
+            mode: opts.mode,
+            caseSensitive: opts.caseSensitive,
+        });
+    }
+    catch (err) {
+        throw new Error(`Invalid pattern: ${String(err)}`);
+    }
+    const maxCandidates = opts.maxCandidates ?? Math.min(50_000, Math.max(1000, opts.maxResults * 200));
+    const candidates = (() => {
+        if (ftsAvailable) {
+            const matchQuery = buildFtsMatchQuery(hint);
+            const placeholders = opts.kinds.map(() => "?").join(", ");
+            const stmt = db.prepare(`
+        SELECT
+          m.id as id,
+          m.kind as kind,
+          m.content as content,
+          m.file_path as file_path,
+          m.start_line as start_line,
+          m.end_line as end_line
+        FROM ${FTS_TABLE_NAME}
+        JOIN memory_items m ON m.id = ${FTS_TABLE_NAME}.rowid
+        WHERE ${FTS_TABLE_NAME} MATCH ?
+          AND m.kind IN (${placeholders})
+        ORDER BY m.file_path ASC, m.start_line ASC, m.id ASC
+        LIMIT ?
+      `);
+            return stmt.all(matchQuery, ...opts.kinds, maxCandidates);
+        }
+        const needle = opts.mode === "literal" ? opts.query : hint;
+        const escaped = escapeLike(needle);
+        const like = `%${escaped}%`;
+        const placeholders = opts.kinds.map(() => "?").join(", ");
+        const stmt = db.prepare(`
+      SELECT
+        id,
+        kind,
+        content,
+        file_path,
+        start_line,
+        end_line
+      FROM memory_items
+      WHERE content LIKE ? ESCAPE '\\'
+        AND kind IN (${placeholders})
+      ORDER BY file_path ASC, start_line ASC, id ASC
+      LIMIT ?
+    `);
+        return stmt.all(like, ...opts.kinds, maxCandidates);
+    })();
+    const matches = [];
+    let candidatesScanned = 0;
+    let truncated = false;
+    for (const c of candidates) {
+        candidatesScanned += 1;
+        if (!c.file_path || c.start_line == null)
+            continue;
+        if (shouldIgnoreDbFilePath(c.file_path))
+            continue;
+        if (!passesPathFilters(c.file_path, opts.includePaths, opts.excludePaths))
+            continue;
+        const content = c.content ?? "";
+        const lineStarts = buildLineStarts(content);
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(content)) !== null) {
+            const idx = m.index ?? 0;
+            const matched = m[0] ?? "";
+            if (!matched) {
+                if (re.lastIndex >= content.length)
+                    break;
+                re.lastIndex += 1;
+                continue;
+            }
+            const lineIdx = lineIndexForOffset(lineStarts, idx);
+            const lineStart = lineStarts[lineIdx] ?? 0;
+            const lineEnd = lineIdx + 1 < lineStarts.length
+                ? (lineStarts[lineIdx + 1] ?? content.length) - 1
+                : content.length;
+            const previewRaw = content.slice(lineStart, Math.max(lineStart, lineEnd));
+            matches.push({
+                file_path: c.file_path,
+                kind: c.kind,
+                line: c.start_line + lineIdx,
+                col: idx - lineStart + 1,
+                preview: trimGrepText(previewRaw, 500),
+                match: trimGrepText(matched, 200),
+            });
+            if (matches.length >= opts.maxResults) {
+                truncated = true;
+                break;
+            }
+        }
+        if (truncated)
+            break;
+    }
+    return {
+        backend: "indexed_fallback",
+        hint,
+        kinds: opts.kinds,
+        include_paths: opts.includePaths ?? [],
+        exclude_paths: opts.excludePaths ?? [],
+        candidates: { total: candidates.length, scanned: candidatesScanned },
+        matches,
+        truncated,
+    };
+}
+function resolveProjectPathUnderRoot(inputPath, opts = {}) {
+    const normalizedInput = inputPath.trim() || ".";
+    const abs = path.isAbsolute(normalizedInput) ? normalizedInput : path.join(projectRoot, normalizedInput);
+    const absPath = path.resolve(abs);
+    const root = path.resolve(projectRoot);
+    const rel = path.relative(root, absPath);
+    const insideRoot = rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+    if (!insideRoot) {
+        throw new Error(`[VectorMind] Path must be under project_root: ${inputPath}`);
+    }
+    if (rel === "" && !opts.allowRoot) {
+        throw new Error(`[VectorMind] Path must not be the project_root itself: ${inputPath}`);
+    }
+    return {
+        absPath,
+        dbFilePath: rel === "" ? "." : normalizeToDbPath(absPath),
+    };
+}
+function resolveReadPathUnderProjectRoot(inputPath) {
+    return resolveProjectPathUnderRoot(inputPath, { allowRoot: false });
+}
+function resolveCodexTextPath(inputPath) {
+    const trimmed = inputPath.trim();
+    if (!trimmed)
+        throw new Error("[VectorMind] path is required");
+    const uriPath = trimmed.startsWith("file:") ? parseFileUriToPath(trimmed) : null;
+    const absPath = path.resolve(uriPath ?? trimmed);
+    const allowedRoot = getAllowedCodexTextRoots().find((root) => {
+        const rel = path.relative(root, absPath);
+        return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+    });
+    if (!allowedRoot) {
+        throw new Error(`[VectorMind] Path must be under one of the allowed local text roots: ${getAllowedCodexTextRoots().join(", ")}`);
+    }
+    return { absPath, displayPath: absPath, allowedRoot };
+}
+function isHiddenBaseName(name) {
+    return name.startsWith(".") && name !== "." && name !== "..";
+}
+function normalizeExtensionsFilter(values) {
+    if (!values?.length)
+        return null;
+    const normalized = values
+        .map((v) => v.trim().toLowerCase())
+        .filter(Boolean)
+        .map((v) => (v.startsWith(".") ? v : `.${v}`));
+    return normalized.length ? Array.from(new Set(normalized)) : null;
+}
+async function readTextFileLines(opts) {
+    let lineNo = 0;
+    const lines = [];
+    let totalChars = 0;
+    let truncated = false;
+    const stream = fs.createReadStream(opts.absPath, { encoding: "utf8" });
+    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    try {
+        for await (const line of rl) {
+            lineNo += 1;
+            if (lineNo < opts.fromLine)
+                continue;
+            if (lineNo > opts.toLine)
+                break;
+            const rendered = `${lineNo}:${line}`;
+            totalChars += rendered.length + 1;
+            if (lines.length >= opts.maxLines || totalChars > opts.maxChars) {
+                truncated = true;
+                break;
+            }
+            lines.push(rendered);
+        }
+    }
+    finally {
+        try {
+            rl.close();
+        }
+        catch { }
+        try {
+            stream.destroy();
+        }
+        catch { }
+    }
+    return { text: lines.join("\n"), returned: lines.length, truncated };
+}
+function readTextFileSlice(opts) {
+    const st = fs.statSync(opts.absPath);
+    if (!st.isFile())
+        throw new Error("Not a file");
+    if (st.size > opts.maxFileBytes) {
+        throw new Error(`File is too large for raw text read (${st.size} bytes > limit ${opts.maxFileBytes}). Use read_file_lines instead.`);
+    }
+    const text = fs.readFileSync(opts.absPath, "utf8");
+    const totalChars = text.length;
+    const safeOffset = Math.min(opts.offset, totalChars);
+    const slice = text.slice(safeOffset, safeOffset + opts.maxChars);
+    const returnedChars = slice.length;
+    const truncated = safeOffset + returnedChars < totalChars;
+    return { text: slice, totalChars, returnedChars, truncated };
+}
+function listProjectFilesInternal(opts) {
+    const entries = [];
+    let scanned = 0;
+    let truncated = false;
+    const pushEntry = (entry) => {
+        if (entries.length >= opts.maxResults) {
+            truncated = true;
+            return;
+        }
+        entries.push(entry);
+    };
+    const startStat = fs.statSync(opts.startAbsPath);
+    if (startStat.isFile()) {
+        const relPath = opts.startDbPath;
+        if ((!opts.respectIgnore || !shouldIgnoreDbFilePath(relPath)) && passesPathFilters(relPath, opts.includePaths, opts.excludePaths)) {
+            const ext = path.extname(relPath).toLowerCase();
+            if (!opts.extensions || opts.extensions.includes(ext)) {
+                pushEntry({
+                    path: relPath,
+                    kind: "file",
+                    depth: 0,
+                    ...(opts.includeStats ? { size: startStat.size, mtime: startStat.mtime.toISOString() } : {}),
+                });
+            }
+        }
+        return { entries, returned: entries.length, scanned: 1, truncated };
+    }
+    const effectiveMaxDepth = opts.recursive ? opts.maxDepth : 1;
+    const stack = [{ absPath: opts.startAbsPath, depth: 0 }];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (!current)
+            break;
+        let dirEntries;
+        try {
+            dirEntries = fs.readdirSync(current.absPath, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        dirEntries.sort((a, b) => a.name.localeCompare(b.name));
+        for (let idx = dirEntries.length - 1; idx >= 0; idx -= 1) {
+            const child = dirEntries[idx];
+            if (!child)
+                continue;
+            if (!opts.includeHidden && isHiddenBaseName(child.name))
+                continue;
+            const childAbs = path.join(current.absPath, child.name);
+            const childRel = normalizeToDbPath(childAbs);
+            if (opts.respectIgnore && shouldIgnoreDbFilePath(childRel))
+                continue;
+            scanned += 1;
+            const childDepth = current.depth + 1;
+            const matchesPath = passesPathFilters(childRel, opts.includePaths, opts.excludePaths);
+            if (child.isDirectory()) {
+                if (opts.includeDirs && matchesPath) {
+                    let stats = null;
+                    if (opts.includeStats) {
+                        try {
+                            stats = fs.statSync(childAbs);
+                        }
+                        catch {
+                            stats = null;
+                        }
+                    }
+                    pushEntry({
+                        path: childRel,
+                        kind: "dir",
+                        depth: childDepth,
+                        ...(stats ? { size: stats.size, mtime: stats.mtime.toISOString() } : {}),
+                    });
+                    if (truncated)
+                        break;
+                }
+                if (childDepth < effectiveMaxDepth) {
+                    stack.push({ absPath: childAbs, depth: childDepth });
+                }
+                continue;
+            }
+            if (!child.isFile())
+                continue;
+            if (!opts.includeFiles || !matchesPath)
+                continue;
+            const ext = path.extname(childRel).toLowerCase();
+            if (opts.extensions && !opts.extensions.includes(ext))
+                continue;
+            let stats = null;
+            if (opts.includeStats) {
+                try {
+                    stats = fs.statSync(childAbs);
+                }
+                catch {
+                    stats = null;
+                }
+            }
+            pushEntry({
+                path: childRel,
+                kind: "file",
+                depth: childDepth,
+                ...(stats ? { size: stats.size, mtime: stats.mtime.toISOString() } : {}),
+            });
+            if (truncated)
+                break;
+        }
+        if (truncated)
+            break;
+    }
+    entries.sort((a, b) => a.path.localeCompare(b.path));
+    return { entries, returned: entries.length, scanned, truncated };
+}
+function buildServerInstructions() {
+    return [
         "VectorMind MCP is available in this session. Use it to avoid guessing project context.",
+        "This package ships built-in baseline policy. If a client supports MCP instructions, these rules auto-apply as soon as the MCP is installed and connected; no user-side config file is required.",
+        "The write-operation rules below are strict workflow constraints. Do not claim that the environment has real git branch locks, checkout APIs, or file-lock tools unless such tools are actually available in the current client/runtime. If such tools are absent, you must still enforce the same exclusivity semantics through explicit coordination and serialized same-file edits.",
         "Project root resolution order: tool argument project_root (recommended for clients without roots/list), then VECTORMIND_ROOT (avoid hardcoding in global config), then MCP roots/list (best-effort; falls back quickly if unsupported), then process.cwd() (so start your MCP client in the project directory for per-project isolation).",
         "If root_source is fallback, file watching/indexing is disabled (pass project_root to enable per-project tracking).",
         "",
+        "Built-in write-operation policy:",
+        BUILTIN_WRITE_POLICY_INSTRUCTIONS,
+        "",
+        "Built-in task-list / Plan-Lite policy:",
+        BUILTIN_PLAN_LITE_INSTRUCTIONS,
+        "",
+        "Built-in destructive-operation guard policy:",
+        BUILTIN_DESTRUCTIVE_OPERATION_GUARD_INSTRUCTIONS,
+        "",
+        "Built-in architecture and code-organization policy:",
+        BUILTIN_ARCHITECTURE_AND_CODE_ORGANIZATION_INSTRUCTIONS,
+        "",
+        "Built-in low-overhead execution and heavy-thread policy:",
+        BUILTIN_LOW_OVERHEAD_WORKFLOW_INSTRUCTIONS,
+        "",
         "Required workflow:",
-        "- On every new conversation/session: call bootstrap_context({ query: <current goal> }) first (or at least get_brain_dump()) to restore context and retrieve relevant matches from the local memory store (vector if enabled; otherwise FTS/LIKE).",
+        "- On every new conversation/session for analysis/design/development work: call bootstrap_context({ query: <current goal> }) first (or at least get_brain_dump()) to restore context and retrieve relevant matches from the local memory store (vector if enabled; otherwise FTS/LIKE).",
         "  - Output is compact by default. Use include_content=true only when you truly need full text (it increases tokens).",
         "  - Tune output size with: requirements_limit/changes_limit/notes_limit, preview_chars, pending_limit/pending_offset.",
         "  - Prefer read_memory_item(id, offset, limit) to fetch full text on demand instead of returning large content in other tool outputs.",
+        "- For pure execution-first tasks with explicit targets (for example compile/build/run/launch/package/publish/test rerun), you may skip retrieval and go straight to the minimum necessary shell or host tools unless code/context lookup is actually needed to unblock execution.",
+        "- To read local Codex skill/prompt/rule files (for example SKILL.md under CODEX_HOME or AGENTS_HOME), prefer read_codex_text_file({ path }) instead of assuming a filesystem MCP resource server exists.",
+        "- For project file/directory browsing, prefer list_project_files({ path, recursive?, max_depth? }) over shelling out to Get-ChildItem/ls. It respects ignore rules and keeps output bounded.",
+        "- For small/medium raw file reads, prefer read_file_text({ path, offset?, max_chars? }) over Get-Content -Raw. Use read_file_lines(...) when you need deterministic line ranges or the file may be large.",
+        "- For raw repo text search with exact file+line+col matches, prefer grep({ query: <pattern> }). It uses ripgrep against real project files when available, applies built-in noise filters, and only falls back to indexed search if ripgrep is unavailable.",
+        "- To read a bounded segment of a file, prefer read_file_lines({ path: <file>, from_line/to_line or total_count }) over unbounded file reads.",
         "- BEFORE editing code: call start_requirement(title, background) to set the active requirement.",
         "- AFTER editing + saving: call get_pending_changes() to see unsynced files, then call sync_change_intent(intent, files). (You can omit files to auto-link all pending changes.)",
         "- After major milestones/decisions: call upsert_project_summary(summary) and/or add_note(...) to persist durable context locally.",
@@ -1706,9 +2545,14 @@ const server = new Server({ name: SERVER_NAME, version: SERVER_VERSION }, {
         "- When you need full text for a specific note/summary/match: call read_memory_item(id, offset, limit) and page through it.",
         "- When asked to locate code (class/function/type): call query_codebase(query) instead of guessing.",
         "- When you need to recall relevant context from history/code/docs: call semantic_search(query, ...) instead of guessing.",
+        "- If the current thread is already heavy or the user reports it has become slow, switch to a lighter workflow: avoid redundant retrieval, keep outputs compact, and recommend continuing substantial new analysis in a fresh thread after a short handoff summary.",
         "",
         "If tool output conflicts with assumptions, trust the tool output.",
-    ].join("\n"),
+    ].join("\n");
+}
+const server = new Server({ name: SERVER_NAME, version: SERVER_VERSION }, {
+    capabilities: { tools: {} },
+    instructions: buildServerInstructions(),
 });
 async function resolveProjectRootFromMcpRoots() {
     const caps = server.getClientCapabilities();
@@ -2265,6 +3109,31 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 description: "Clear the in-memory debug activity log. Enable logging with VECTORMIND_DEBUG_LOG=1.",
                 inputSchema: toJsonSchemaCompat(ClearActivityLogArgsSchema),
             },
+            {
+                name: "grep",
+                description: "Repo text search with precise file/line/col matches, powered by ripgrep against real project files plus built-in noise filters. Falls back to indexed search only when ripgrep is unavailable.",
+                inputSchema: toJsonSchemaCompat(GrepArgsSchema),
+            },
+            {
+                name: "list_project_files",
+                description: "AI-friendly, ignore-aware file/directory listing under project_root with bounded output. Prefer this over Get-ChildItem/ls for local repository browsing.",
+                inputSchema: toJsonSchemaCompat(ListProjectFilesArgsSchema),
+            },
+            {
+                name: "read_codex_text_file",
+                description: "Read bounded text from local Codex/agents files such as SKILL.md, prompt files, and rules under CODEX_HOME/AGENTS_HOME. Prefer this over assuming a filesystem MCP resource server exists.",
+                inputSchema: toJsonSchemaCompat(ReadCodexTextFileArgsSchema),
+            },
+            {
+                name: "read_file_lines",
+                description: "Read a specific line range from a file under project_root (with strict size limits). Prefer this over Get-Content for deterministic reads.",
+                inputSchema: toJsonSchemaCompat(ReadFileLinesArgsSchema),
+            },
+            {
+                name: "read_file_text",
+                description: "Read bounded raw UTF-8 text from a file under project_root. Prefer this over Get-Content -Raw for small/medium text files; use read_file_lines for large files or line-specific reads.",
+                inputSchema: toJsonSchemaCompat(ReadFileTextArgsSchema),
+            },
             {
                 name: "query_codebase",
                 description: "Search the symbol index for class/function/type names (or substrings) to locate definitions by file path and signature. Use this when you need to find code—do not guess locations.",
@@ -2610,7 +3479,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ? toMemoryItemPreview(projectSummaryRow, includeContent, previewChars, contentMaxChars)
                 : null;
             const recent_notes = listRecentNotesStmt.all(notesLimit).map((n) => toMemoryItemPreview(n, includeContent, previewChars, contentMaxChars));
-            const conventions = listConventionsStmt.all(conventionsLimit).map((c) => toMemoryItemPreview(c, false, previewChars, contentMaxChars));
+            const conventions = getConventionPreviews(conventionsLimit, previewChars, contentMaxChars);
             const pending_total = Number(countPendingChangesStmt.get()?.total ?? 0);
             const pending_offset = args.pending_offset;
             const pending_limit = args.pending_limit;
@@ -2706,7 +3575,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ? toMemoryItemPreview(projectSummaryRow, includeContent, previewChars, contentMaxChars)
                 : null;
             const recent_notes = listRecentNotesStmt.all(notesLimit).map((n) => toMemoryItemPreview(n, includeContent, previewChars, contentMaxChars));
-            const conventions = listConventionsStmt.all(conventionsLimit).map((c) => toMemoryItemPreview(c, false, previewChars, contentMaxChars));
+            const conventions = getConventionPreviews(conventionsLimit, previewChars, contentMaxChars);
             const pending_total = Number(countPendingChangesStmt.get()?.total ?? 0);
             const pending_offset = args.pending_offset;
             const pending_limit = args.pending_limit;
@@ -2935,6 +3804,418 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             clearActivityLog();
             return { content: [{ type: "text", text: toolJson({ ok: true }) }] };
         }
+        if (toolName === "grep") {
+            const args = GrepArgsSchema.parse(rawArgs);
+            const q = args.query;
+            const mode = args.mode;
+            const smartCase = args.smart_case;
+            const kinds = args.kinds?.length ? args.kinds : ["code_chunk", "doc_chunk"];
+            const includePaths = args.include_paths?.length ? args.include_paths : null;
+            const excludePaths = args.exclude_paths?.length ? args.exclude_paths : null;
+            const maxResults = args.max_results;
+            const caseSensitive = args.case_sensitive ?? (smartCase ? hasUppercaseAscii(q) : true);
+            const ripgrepResult = runRipgrepSearch({
+                query: q,
+                mode,
+                smartCase,
+                caseSensitive,
+                includePaths,
+                excludePaths,
+                maxResults,
+            });
+            if (ripgrepResult.ok) {
+                logActivity("grep", {
+                    backend: ripgrepResult.backend,
+                    rg_command: ripgrepResult.rg_command,
+                    query: q,
+                    mode,
+                    case_sensitive: caseSensitive,
+                    smart_case: smartCase,
+                    include_paths: includePaths ?? [],
+                    exclude_paths: excludePaths ?? [],
+                    matches: ripgrepResult.matches.length,
+                    total_matches: ripgrepResult.total_matches,
+                    truncated: ripgrepResult.truncated,
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: toolJson({
+                                ok: true,
+                                backend: ripgrepResult.backend,
+                                rg_command: ripgrepResult.rg_command,
+                                query: q,
+                                mode,
+                                case_sensitive: caseSensitive,
+                                smart_case: smartCase,
+                                include_paths: includePaths ?? [],
+                                exclude_paths: excludePaths ?? [],
+                                matches: ripgrepResult.matches,
+                                total_matches: ripgrepResult.total_matches,
+                                truncated: ripgrepResult.truncated,
+                            }),
+                        },
+                    ],
+                };
+            }
+            if (!ripgrepResult.unavailable) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: "text",
+                            text: toolJson({
+                                ok: false,
+                                backend: "ripgrep",
+                                error: ripgrepResult.error,
+                                rg_command: ripgrepResult.rg_command,
+                                exit_status: ripgrepResult.exit_status,
+                                query: q,
+                                mode,
+                            }),
+                        },
+                    ],
+                };
+            }
+            let indexedResult;
+            try {
+                indexedResult = runIndexedGrepSearch({
+                    query: q,
+                    mode,
+                    smartCase,
+                    caseSensitive,
+                    literalHint: args.literal_hint,
+                    kinds,
+                    includePaths,
+                    excludePaths,
+                    maxResults,
+                    maxCandidates: args.max_candidates,
+                });
+            }
+            catch (err) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: "text",
+                            text: toolJson({
+                                ok: false,
+                                backend: "indexed_fallback",
+                                fallback_reason: "ripgrep_unavailable",
+                                ripgrep_error: ripgrepResult.error,
+                                ripgrep_attempts: ripgrepResult.attempts,
+                                error: String(err),
+                                query: q,
+                                mode,
+                                literal_hint: args.literal_hint,
+                            }),
+                        },
+                    ],
+                };
+            }
+            logActivity("grep", {
+                backend: indexedResult.backend,
+                fallback_reason: "ripgrep_unavailable",
+                ripgrep_error: ripgrepResult.error,
+                query: q,
+                mode,
+                case_sensitive: caseSensitive,
+                smart_case: smartCase,
+                hint: indexedResult.hint,
+                kinds,
+                include_paths: includePaths ?? [],
+                exclude_paths: excludePaths ?? [],
+                candidates: indexedResult.candidates.total,
+                candidates_scanned: indexedResult.candidates.scanned,
+                matches: indexedResult.matches.length,
+                truncated: indexedResult.truncated,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: toolJson({
+                            ok: true,
+                            backend: indexedResult.backend,
+                            fallback_reason: "ripgrep_unavailable",
+                            ripgrep_error: ripgrepResult.error,
+                            ripgrep_attempts: ripgrepResult.attempts,
+                            query: q,
+                            mode,
+                            case_sensitive: caseSensitive,
+                            smart_case: smartCase,
+                            hint: indexedResult.hint,
+                            kinds,
+                            include_paths: includePaths ?? [],
+                            exclude_paths: excludePaths ?? [],
+                            candidates: indexedResult.candidates,
+                            matches: indexedResult.matches,
+                            truncated: indexedResult.truncated,
+                        }),
+                    },
+                ],
+            };
+        }
+        if (toolName === "list_project_files") {
+            const args = ListProjectFilesArgsSchema.parse(rawArgs);
+            const resolved = resolveProjectPathUnderRoot(args.path, { allowRoot: true });
+            let st;
+            try {
+                st = fs.statSync(resolved.absPath);
+            }
+            catch (err) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: toolJson({ ok: false, error: `Path not found: ${String(err)}` }) }],
+                };
+            }
+            const includePaths = args.include_paths?.length ? args.include_paths : null;
+            const excludePaths = args.exclude_paths?.length ? args.exclude_paths : null;
+            const extensions = normalizeExtensionsFilter(args.extensions);
+            const result = listProjectFilesInternal({
+                startAbsPath: resolved.absPath,
+                startDbPath: resolved.dbFilePath,
+                recursive: args.recursive,
+                maxDepth: args.max_depth,
+                includeFiles: args.include_files,
+                includeDirs: args.include_dirs,
+                includeHidden: args.include_hidden,
+                respectIgnore: args.respect_ignore,
+                includePaths,
+                excludePaths,
+                extensions,
+                maxResults: args.max_results,
+                includeStats: args.include_stats,
+            });
+            logActivity("list_project_files", {
+                path: resolved.dbFilePath,
+                recursive: args.recursive,
+                max_depth: args.max_depth,
+                include_files: args.include_files,
+                include_dirs: args.include_dirs,
+                include_hidden: args.include_hidden,
+                respect_ignore: args.respect_ignore,
+                include_paths: includePaths ?? [],
+                exclude_paths: excludePaths ?? [],
+                extensions: extensions ?? [],
+                returned: result.returned,
+                scanned: result.scanned,
+                truncated: result.truncated,
+                path_kind: st.isFile() ? "file" : st.isDirectory() ? "dir" : "other",
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: toolJson({
+                            ok: true,
+                            path: resolved.dbFilePath,
+                            path_kind: st.isFile() ? "file" : st.isDirectory() ? "dir" : "other",
+                            recursive: args.recursive,
+                            max_depth: args.recursive ? args.max_depth : 1,
+                            include_files: args.include_files,
+                            include_dirs: args.include_dirs,
+                            include_hidden: args.include_hidden,
+                            respect_ignore: args.respect_ignore,
+                            include_paths: includePaths ?? [],
+                            exclude_paths: excludePaths ?? [],
+                            extensions: extensions ?? [],
+                            returned: result.returned,
+                            scanned: result.scanned,
+                            truncated: result.truncated,
+                            entries: result.entries,
+                        }),
+                    },
+                ],
+            };
+        }
+        if (toolName === "read_file_text") {
+            const args = ReadFileTextArgsSchema.parse(rawArgs);
+            const resolved = resolveReadPathUnderProjectRoot(args.path);
+            let st;
+            try {
+                st = fs.statSync(resolved.absPath);
+            }
+            catch (err) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: toolJson({ ok: false, error: `File not found: ${String(err)}` }) }],
+                };
+            }
+            if (!st.isFile()) {
+                return { isError: true, content: [{ type: "text", text: toolJson({ ok: false, error: "Not a file" }) }] };
+            }
+            let result;
+            try {
+                result = readTextFileSlice({
+                    absPath: resolved.absPath,
+                    offset: args.offset,
+                    maxChars: args.max_chars,
+                    maxFileBytes: args.max_file_bytes,
+                });
+            }
+            catch (err) {
+                return { isError: true, content: [{ type: "text", text: toolJson({ ok: false, error: String(err) }) }] };
+            }
+            logActivity("read_file_text", {
+                file_path: resolved.dbFilePath,
+                offset: args.offset,
+                returned_chars: result.returnedChars,
+                total_chars: result.totalChars,
+                truncated: result.truncated,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: toolJson({
+                            ok: true,
+                            file_path: resolved.dbFilePath,
+                            offset: args.offset,
+                            returned_chars: result.returnedChars,
+                            total_chars: result.totalChars,
+                            truncated: result.truncated,
+                            text: result.text,
+                        }),
+                    },
+                ],
+            };
+        }
+        if (toolName === "read_codex_text_file") {
+            const args = ReadCodexTextFileArgsSchema.parse(rawArgs);
+            let resolved;
+            try {
+                resolved = resolveCodexTextPath(args.path);
+            }
+            catch (err) {
+                return { isError: true, content: [{ type: "text", text: toolJson({ ok: false, error: String(err) }) }] };
+            }
+            let st;
+            try {
+                st = fs.statSync(resolved.absPath);
+            }
+            catch (err) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: toolJson({ ok: false, error: `File not found: ${String(err)}` }) }],
+                };
+            }
+            if (!st.isFile()) {
+                return { isError: true, content: [{ type: "text", text: toolJson({ ok: false, error: "Not a file" }) }] };
+            }
+            let result;
+            try {
+                result = readTextFileSlice({
+                    absPath: resolved.absPath,
+                    offset: args.offset,
+                    maxChars: args.max_chars,
+                    maxFileBytes: args.max_file_bytes,
+                });
+            }
+            catch (err) {
+                return { isError: true, content: [{ type: "text", text: toolJson({ ok: false, error: String(err) }) }] };
+            }
+            logActivity("read_codex_text_file", {
+                file_path: resolved.displayPath,
+                allowed_root: resolved.allowedRoot,
+                offset: args.offset,
+                returned_chars: result.returnedChars,
+                total_chars: result.totalChars,
+                truncated: result.truncated,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: toolJson({
+                            ok: true,
+                            file_path: resolved.displayPath,
+                            allowed_root: resolved.allowedRoot,
+                            offset: args.offset,
+                            returned_chars: result.returnedChars,
+                            total_chars: result.totalChars,
+                            truncated: result.truncated,
+                            text: result.text,
+                        }),
+                    },
+                ],
+            };
+        }
+        if (toolName === "read_file_lines") {
+            const args = ReadFileLinesArgsSchema.parse(rawArgs);
+            const resolved = resolveReadPathUnderProjectRoot(args.path);
+            let fromLine = args.from_line;
+            let toLine = args.to_line;
+            if (toLine == null) {
+                const total = args.total_count ?? 200;
+                toLine = fromLine + total - 1;
+            }
+            if (toLine < fromLine) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: "text",
+                            text: toolJson({
+                                ok: false,
+                                error: "to_line must be >= from_line",
+                                path: args.path,
+                                from_line: fromLine,
+                                to_line: toLine,
+                            }),
+                        },
+                    ],
+                };
+            }
+            let st;
+            try {
+                st = fs.statSync(resolved.absPath);
+            }
+            catch (err) {
+                return {
+                    isError: true,
+                    content: [
+                        { type: "text", text: toolJson({ ok: false, error: `File not found: ${String(err)}` }) },
+                    ],
+                };
+            }
+            if (!st.isFile()) {
+                return { isError: true, content: [{ type: "text", text: toolJson({ ok: false, error: "Not a file" }) }] };
+            }
+            const maxLines = Math.max(1, Math.min(2000, args.max_lines));
+            const maxChars = Math.max(200, Math.min(200_000, args.max_chars));
+            const result = await readTextFileLines({
+                absPath: resolved.absPath,
+                fromLine,
+                toLine,
+                maxLines,
+                maxChars,
+            });
+            logActivity("read_file_lines", {
+                file_path: resolved.dbFilePath,
+                from_line: fromLine,
+                to_line: toLine,
+                returned: result.returned,
+                truncated: result.truncated,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: toolJson({
+                            ok: true,
+                            file_path: resolved.dbFilePath,
+                            from_line: fromLine,
+                            to_line: toLine,
+                            returned: result.returned,
+                            truncated: result.truncated,
+                            text: result.text,
+                        }),
+                    },
+                ],
+            };
+        }
         if (toolName === "query_codebase") {
             const args = QueryCodebaseArgsSchema.parse(rawArgs);
             const q = args.query.trim();