gitnexus 1.6.13-rc.44 → 1.6.13-rc.45

package/README.md

@@ -210,7 +210,7 @@ Note that the bundled Graphology path is no longer the slow option it once was:
 
 ## MCP Tools
 
-Your AI agent gets **17 tools** (15 per-repo + 2 group) automatically:
+Your AI agent gets **19 tools** (17 per-repo + 2 group) automatically:
 
 | Tool             | What It Does                                                                                                                                      |
 | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -229,10 +229,12 @@ Your AI agent gets **17 tools** (15 per-repo + 2 group) automatically:
 | `api_impact`     | Pre-change impact report for an API route handler                                                                                                 |
 | `explain`        | Explain persisted taint findings (source→sink flows, `--pdg` indexes)                                                                             |
 | `pdg_query`      | Query control/data dependence at statement level (`--pdg` indexes)                                                                                |
+| `read_file`      | Read a checkout file (optional 0-indexed slice; `maxLines` cap)                                                                                   |
+| `grep`           | Regex search of the working tree for indexed files (1-based hits; optional `caseSensitive` / `literal`)                                           |
 | `group_list`     | List configured repository groups                                                                                                                 |
 | `group_sync`     | Rebuild a group's Contract Registry and cross-repo links                                                                                          |
 
-> Read-only tools can omit `repo` when one repo is indexed, an MCP default is configured, or the GitNexus process cwd is inside a registered path without crossing into an unindexed nested Git checkout. Otherwise—and for mutating tools with multiple indexed repos and no MCP default—specify it explicitly: `query({search_query: "auth", repo: "my-app"})`. Per-repo tools also take an optional `branch` for indexes pinned with `gitnexus analyze --branch`; omitting it queries the workspace index, which follows your checked-out working tree. `explain` and `pdg_query` need an index built with `gitnexus analyze --pdg`.
+> Read-only tools can omit `repo` when one repo is indexed, an MCP default is configured, or the GitNexus process cwd is inside a registered path without crossing into an unindexed nested Git checkout. Otherwise—and for mutating tools with multiple indexed repos and no MCP default—specify it explicitly: `query({search_query: "auth", repo: "my-app"})`. Per-repo tools also take an optional `branch` for indexes pinned with `gitnexus analyze --branch`, except `read_file` and `grep`, which read the checkout and do not accept `branch`. Omitting `branch` queries the workspace index, which follows your checked-out working tree. `explain` and `pdg_query` need an index built with `gitnexus analyze --pdg`.
 
 ## MCP Resources
 

package/dist/mcp/local/local-backend.d.ts

@@ -941,6 +941,27 @@ export declare class LocalBackend {
      * Single query instead of N+1.
      */
     private fetchLinkedFlowsBatch;
+    /**
+     * Same predicate as HTTP `getSourceAvailability`: full retention plus a live
+     * checkout. Meta is the graph directory so a published shared-store commit
+     * still carries `contentRetention`. Wording matches HTTP 410.
+     */
+    private fullSourceUnavailable;
+    /**
+     * MCP read_file — repo-contained checkout read with an optional 0-indexed
+     * line slice. The realpath re-check matches GET /api/file. The lexical
+     * barrier stays inline for CodeQL and is narrowed to the `..` segment, so
+     * a file named `..config` is not a traversal. ENOENT is file-not-found
+     * only after the checkout directory is known to exist.
+     */
+    private readFile;
+    /**
+     * MCP grep — HTTP GET /api/grep twin. The file list is indexed File nodes
+     * that still have content; bytes come from the live checkout (same worker).
+     * Fails like HTTP 410 when full source is unavailable instead of returning
+     * an empty hit list.
+     */
+    private grep;
     private routeMap;
     private shapeCheck;
     private toolMap;

package/dist/mcp/local/local-backend.js

@@ -29,6 +29,8 @@ import { isWalCorruptionError, WAL_RECOVERY_SUGGESTION } from '../../core/lbug/l
 // import { isGitRepo, getCurrentCommit, getGitRoot } from '../../storage/git.js';
 import { parseDiffHunksResult, coalesceHunksByPath, hunksOverlapRange, findGitRootByDotGit, getCanonicalRepoRoot, getGitRoot, } from '../../storage/git.js';
 import { realpathSync } from 'fs';
+import { parseGrepQuery, GREP_TIME_BUDGET_MS } from '../../server/grep-params.js';
+import { runGrepScanInWorker } from '../../server/grep-scan.js';
 import { listRegisteredRepos, canonicalizePath, getStoragePaths, loadMeta, RegistryAmbiguousTargetError, } from '../../storage/repo-manager.js';
 import { GroupService, } from '../../core/group/service.js';
 import { resolveAtGroupMemberRepoPath } from '../../core/group/resolve-at-member.js';
@@ -58,7 +60,7 @@ import { checkStalenessAsync, checkCwdMatch } from '../../core/git-staleness.js'
 import { stalenessPayload, } from '../../core/staleness-status.js';
 import { logger } from '../../core/logger.js';
 import { isLocalEmbeddingRuntimeBlockerMessage, isLocalEmbeddingSidecarAbortMessage, isMissingLocalEmbeddingStackMessage, } from '../../core/embeddings/runtime-support.js';
-import { LIST_REPOS_DEFAULT_LIMIT, LIST_REPOS_MAX_LIMIT, EXPLAIN_DEFAULT_LIMIT, EXPLAIN_MAX_LIMIT, PDG_QUERY_DEFAULT_LIMIT, PDG_QUERY_MAX_LIMIT, QUERY_DEFAULT_LIMIT, QUERY_DEFAULT_MAX_SYMBOLS, QUERY_MAX_LIMIT, QUERY_MAX_MAX_SYMBOLS, CONTEXT_CHAIN_MAX_DEPTH, } from '../tools.js';
+import { LIST_REPOS_DEFAULT_LIMIT, LIST_REPOS_MAX_LIMIT, EXPLAIN_DEFAULT_LIMIT, EXPLAIN_MAX_LIMIT, PDG_QUERY_DEFAULT_LIMIT, PDG_QUERY_MAX_LIMIT, QUERY_DEFAULT_LIMIT, QUERY_DEFAULT_MAX_SYMBOLS, QUERY_MAX_LIMIT, QUERY_MAX_MAX_SYMBOLS, CONTEXT_CHAIN_MAX_DEPTH, CHECKOUT_SOURCE_TOOLS, READ_FILE_DEFAULT_MAX_LINES, } from '../tools.js';
 import { foldNumericToolArgumentAliases } from '../tool-arguments.js';
 import { findImportCycles, IMPORT_CYCLE_LIMIT } from '../../core/graph/import-cycles.js';
 import { decodeTaintPath } from '../../core/ingestion/taint/path-codec.js';
@@ -2170,6 +2172,14 @@ export class LocalBackend {
             p.repo.startsWith('@')) {
             return this.callToolAtGroupRepo(method, p);
         }
+        // These tools read the checkout, not a pinned index. `branch` would still
+        // rewrite lbugPath/lastCommit and withToolStaleness would label checkout
+        // bytes with that pin. Reject before selectToolRepository applies it.
+        if (CHECKOUT_SOURCE_TOOLS.has(method) && p.branch !== undefined && p.branch !== '') {
+            return {
+                error: `${method} follows the checked-out working tree and does not accept "branch". Omit it.`,
+            };
+        }
         // Resolve repo from optional param (re-reads registry on miss). An optional
         // `branch` param scopes the resolved handle to that branch's index (#2106).
         const repo = await this.selectToolRepository(p.repo, p.branch, { allowCwdDefault: method !== 'rename' });
@@ -2214,6 +2224,10 @@ export class LocalBackend {
                 return this.apiImpact(repo, p);
             case 'trace':
                 return this.trace(repo, p);
+            case 'read_file':
+                return this.withToolStaleness(repo, await this.readFile(repo, p));
+            case 'grep':
+                return this.withToolStaleness(repo, await this.grep(repo, p));
             default:
                 throw new Error(`Unknown tool: ${method}`);
         }
@@ -7783,6 +7797,178 @@ export class LocalBackend {
         }
         return result;
     }
+    /**
+     * Same predicate as HTTP `getSourceAvailability`: full retention plus a live
+     * checkout. Meta is the graph directory so a published shared-store commit
+     * still carries `contentRetention`. Wording matches HTTP 410.
+     */
+    async fullSourceUnavailable(repo) {
+        const meta = await loadMeta(path.dirname(repo.lbugPath));
+        const retention = contentRetentionFromMeta(meta);
+        const checkoutIsDir = retention === 'full' ? await checkoutIsDirectory(repo.repoPath) : false;
+        if (isFullSourceAvailable(retention, checkoutIsDir))
+            return null;
+        const reason = retention !== 'full' ? 'content-retention' : 'checkout-missing';
+        const because = reason === 'content-retention' ? 'content retention' : 'source checkout';
+        return {
+            error: `Full source is unavailable because the ${because} is unavailable.`,
+            code: 'source-unavailable',
+            reason,
+        };
+    }
+    /**
+     * MCP read_file — repo-contained checkout read with an optional 0-indexed
+     * line slice. The realpath re-check matches GET /api/file. The lexical
+     * barrier stays inline for CodeQL and is narrowed to the `..` segment, so
+     * a file named `..config` is not a traversal. ENOENT is file-not-found
+     * only after the checkout directory is known to exist.
+     */
+    async readFile(repo, params) {
+        const rawPath = params?.path;
+        if (typeof rawPath !== 'string' || rawPath === '') {
+            return { error: 'Missing required argument "path" (repo-relative file path).' };
+        }
+        const unavailable = await this.fullSourceUnavailable(repo);
+        if (unavailable)
+            return unavailable;
+        const toInteger = (v) => typeof v === 'number' && Number.isFinite(v) ? Math.trunc(v) : undefined;
+        const startLine = toInteger(params?.startLine);
+        const endLine = toInteger(params?.endLine);
+        if (endLine !== undefined && startLine === undefined) {
+            return { error: '"endLine" requires "startLine".' };
+        }
+        const repoRoot = path.resolve(repo.repoPath);
+        const fullPath = path.resolve(repoRoot, rawPath);
+        const fullRel = path.relative(repoRoot, fullPath);
+        // `startsWith('..')` is the CodeQL path-injection sanitizer. Narrow it to
+        // the `..` segment so a repo file named `..config` is not a traversal.
+        if (path.isAbsolute(fullRel) ||
+            (fullRel.startsWith('..') && (fullRel === '..' || fullRel.startsWith(`..${path.sep}`)))) {
+            return { error: 'Path traversal denied.' };
+        }
+        let realRoot;
+        let realFull;
+        try {
+            [realRoot, realFull] = await Promise.all([fs.realpath(repoRoot), fs.realpath(fullPath)]);
+        }
+        catch (err) {
+            if (err?.code === 'ENOENT')
+                return { error: `File not found: ${rawPath}` };
+            throw err;
+        }
+        const realRel = path.relative(realRoot, realFull);
+        if (realRel === '..' || realRel.startsWith(`..${path.sep}`) || path.isAbsolute(realRel)) {
+            return { error: 'Path traversal denied.' };
+        }
+        const raw = await fs.readFile(realFull, 'utf-8');
+        const lines = raw.split('\n');
+        if (startLine !== undefined) {
+            if (endLine !== undefined && endLine < 0) {
+                return { error: '"endLine" must be an integer >= 0.' };
+            }
+            const start = Math.max(0, startLine);
+            const end = endLine !== undefined ? Math.min(lines.length, endLine + 1) : lines.length;
+            return {
+                path: fullRel,
+                content: lines.slice(start, end).join('\n'),
+                startLine: start,
+                endLine: end - 1,
+                totalLines: lines.length,
+            };
+        }
+        const requestedMaxLines = toInteger(params?.maxLines);
+        if (requestedMaxLines !== undefined && requestedMaxLines < 0) {
+            return { error: '"maxLines" must be an integer >= 0 (0 = no cap).' };
+        }
+        const maxLines = requestedMaxLines ?? READ_FILE_DEFAULT_MAX_LINES;
+        if (maxLines > 0 && lines.length > maxLines) {
+            return {
+                path: fullRel,
+                content: lines.slice(0, maxLines).join('\n'),
+                startLine: 0,
+                endLine: maxLines - 1,
+                totalLines: lines.length,
+                truncated: true,
+                suggestion: 'Re-issue with startLine/endLine for the window you need.',
+            };
+        }
+        return { path: fullRel, content: raw, totalLines: lines.length };
+    }
+    /**
+     * MCP grep — HTTP GET /api/grep twin. The file list is indexed File nodes
+     * that still have content; bytes come from the live checkout (same worker).
+     * Fails like HTTP 410 when full source is unavailable instead of returning
+     * an empty hit list.
+     */
+    async grep(repo, params) {
+        const unavailable = await this.fullSourceUnavailable(repo);
+        if (unavailable)
+            return unavailable;
+        await this.ensureInitialized(repo);
+        let parsed;
+        try {
+            parsed = parseGrepQuery({
+                pattern: params?.pattern,
+                fileFilter: params?.fileFilter,
+                limit: params?.limit,
+                caseSensitive: params?.caseSensitive,
+                literal: params?.literal,
+            });
+        }
+        catch (err) {
+            return { error: err?.message || 'Invalid grep query.' };
+        }
+        const fileRows = await executeQuery(repo.lbugPath, `MATCH (n:File) WHERE n.content IS NOT NULL RETURN n.filePath AS filePath`);
+        const filePaths = [];
+        for (const row of fileRows) {
+            const filePath = row.filePath || '';
+            if (parsed.fileFilter && !filePath.toLowerCase().includes(parsed.fileFilter))
+                continue;
+            filePaths.push(filePath);
+        }
+        // The shared scanner only checks a lexical prefix, then readFile follows
+        // symlinks. Drop paths whose realpath leaves the checkout, same as read_file.
+        const repoRoot = path.resolve(repo.repoPath);
+        const realRoot = await fs.realpath(repoRoot);
+        const containedPaths = [];
+        for (const filePath of filePaths) {
+            const fullPath = path.resolve(repoRoot, filePath);
+            const fullRel = path.relative(repoRoot, fullPath);
+            if (path.isAbsolute(fullRel) ||
+                (fullRel.startsWith('..') && (fullRel === '..' || fullRel.startsWith(`..${path.sep}`)))) {
+                continue;
+            }
+            let realFull;
+            try {
+                realFull = await fs.realpath(fullPath);
+            }
+            catch {
+                continue;
+            }
+            const realRel = path.relative(realRoot, realFull);
+            if (realRel === '..' || realRel.startsWith(`..${path.sep}`) || path.isAbsolute(realRel)) {
+                continue;
+            }
+            containedPaths.push(filePath);
+        }
+        const { results, timedOut } = await runGrepScanInWorker({
+            repoRoot,
+            filePaths: containedPaths,
+            pattern: parsed.regex.source,
+            flags: parsed.regex.flags,
+            limit: parsed.limit,
+            deadlineMs: Date.now() + GREP_TIME_BUDGET_MS,
+        });
+        return {
+            results,
+            ...(timedOut ? { timedOut: true } : {}),
+            ...(timedOut
+                ? {
+                    suggestion: 'Wall-clock budget expired — re-issue narrower (fileFilter or a tighter pattern).',
+                }
+                : {}),
+        };
+    }
     async routeMap(repo, params) {
         await this.ensureInitialized(repo);
         const routeFilter = params.route ? `AND n.name CONTAINS $route` : '';

package/dist/mcp/read-only-policy.js

@@ -2,6 +2,8 @@ export const MCP_READ_ONLY_TOOLS = new Set([
     'list_repos',
     'query',
     'context',
+    'read_file',
+    'grep',
     'detect_changes',
     'check',
     'impact',

package/dist/mcp/server.d.ts

@@ -7,7 +7,7 @@
  *
  * Supports multiple indexed repositories via the global registry.
  *
- * Tools: list_repos, query, cypher, context, impact, detect_changes, rename
+ * Tools: list_repos, query, cypher, context, read_file, grep, impact, detect_changes, rename
  * Resources: repos, repo/{name}/context, repo/{name}/clusters, ...
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';

package/dist/mcp/server.js

@@ -7,7 +7,7 @@
  *
  * Supports multiple indexed repositories via the global registry.
  *
- * Tools: list_repos, query, cypher, context, impact, detect_changes, rename
+ * Tools: list_repos, query, cypher, context, read_file, grep, impact, detect_changes, rename
  * Resources: repos, repo/{name}/context, repo/{name}/clusters, ...
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
@@ -49,6 +49,10 @@ function getNextStepHint(toolName, args) {
             return `\n\n---\n**Next:** Run detect_changes(${repoParam ? `{repo: "${repo}"}` : ''}) to verify no unexpected side effects from the rename.`;
         case 'cypher':
             return `\n\n---\n**Next:** To explore a result symbol, use context({name: "<name>"${repoParam}}). For schema reference, READ gitnexus://repo/${repoPath}/schema.`;
+        case 'read_file':
+            return `\n\n---\n**Next:** To pin a symbol seen in the file, use context({name: "<symbol>"${repoParam}}). To find other occurrences, use grep({pattern: "<token>"${repoParam}}).`;
+        case 'grep':
+            return `\n\n---\n**Next:** Read the hit window with read_file({path: "<file>"${repoParam}, startLine: <hit.line - 1>, endLine: <hit.line - 1>}). Grep line is 1-based; read_file is 0-based. Or pin the symbol with context({name: "<symbol>"${repoParam}}).`;
         // Legacy tool names — still return useful hints
         case 'search':
             return `\n\n---\n**Next:** To understand a result in context, use context({name: "<symbol_name>"${repoParam}}).`;

package/dist/mcp/tools.d.ts

@@ -37,6 +37,8 @@ export interface ToolDefinition {
  */
 export declare const LIST_REPOS_DEFAULT_LIMIT = 50;
 export declare const LIST_REPOS_MAX_LIMIT = 200;
+/** Whole-file `read_file` cap. The schema default and the handler fallback share this. */
+export declare const READ_FILE_DEFAULT_MAX_LINES = 2000;
 /**
  * Pagination bounds for the `explain` tool (#2083 M3 U6). Findings are sparse
  * and capped per function at analyze time, but a large repo can still
@@ -62,6 +64,10 @@ export declare const GITNEXUS_TOOLS: ToolDefinition[];
  * of truth: the schema property is injected here so it cannot drift from the
  * server-side default in `local-backend.ts` (`resolveRepo(repo, branch)`).
  * `list_repos` and the `group_*` tools are intentionally excluded — they are
- * not single-repo, single-branch operations.
+ * not single-repo, single-branch operations. `read_file` and `grep` are in
+ * this set so `repo` stays required with the other per-repo tools, and the
+ * loop below skips `branch` for `CHECKOUT_SOURCE_TOOLS` — a pin would label
+ * checkout bytes with another commit.
  */
+export declare const CHECKOUT_SOURCE_TOOLS: Set<string>;
 export declare const REPO_SCOPED_TOOLS: Set<string>;

package/dist/mcp/tools.js

@@ -33,6 +33,8 @@ const DESTRUCTIVE_TOOL_ANNOTATIONS = {
  */
 export const LIST_REPOS_DEFAULT_LIMIT = 50;
 export const LIST_REPOS_MAX_LIMIT = 200;
+/** Whole-file `read_file` cap. The schema default and the handler fallback share this. */
+export const READ_FILE_DEFAULT_MAX_LINES = 2000;
 /**
  * Pagination bounds for the `explain` tool (#2083 M3 U6). Findings are sparse
  * and capped per function at analyze time, but a large repo can still
@@ -941,15 +943,106 @@ DESTINATION TRACE (cross-repo): for an "@groupName" trace, OMIT to/to_uid/to_fil
             required: [],
         },
     },
+    {
+        name: 'read_file',
+        description: `Read a file from the repository checkout, optionally sliced to a 0-indexed line range.
+Returns checkout bytes plus totalLines and the slice bounds. The realpath re-check matches HTTP GET /api/file. The lexical barrier is the CodeQL \`startsWith('..')\` form narrowed to the \`..\` segment, so a file named \`..config\` stays readable. A whole-file read is capped by maxLines (default ${READ_FILE_DEFAULT_MAX_LINES}, 0 = no cap), which is stricter than the uncapped HTTP body.
+
+WHEN TO USE: After query()/cypher()/context() gave you a filePath (or file:line), read the surrounding source: header context (open/variable/import lines), a full declaration, or any line window. Prefer context({name, include_content: true}) when you already have the symbol — it returns the symbol span plus call edges in one call.
+AFTER THIS: Use the read text to ground signatures verbatim; never invent names from memory.
+
+Paths that escape the repository are refused. A missing file returns a not-found error only when the checkout directory exists. When full source is unavailable (content retention is not "full", or the checkout directory is gone), the result is code "source-unavailable" — not an empty body and not "file not found". This tool reads the checkout and does not accept branch.`,
+        annotations: READ_ONLY_TOOL_ANNOTATIONS,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Repository-contained file path (e.g. "Mathlib/Analysis/SpecificLimits/Basic.lean"). Paths that escape the repository, including ".." escapes, are refused.',
+                },
+                startLine: {
+                    type: 'integer',
+                    description: 'Optional 0-indexed first line of the slice (inclusive).',
+                    minimum: 0,
+                },
+                endLine: {
+                    type: 'integer',
+                    description: 'Optional 0-indexed last line of the slice (inclusive). Requires startLine.',
+                    minimum: 0,
+                },
+                maxLines: {
+                    type: 'integer',
+                    description: `Maximum lines returned for a whole-file read (default ${READ_FILE_DEFAULT_MAX_LINES}, 0 = no cap). Ignored when startLine is set. Negative values are rejected.`,
+                    default: READ_FILE_DEFAULT_MAX_LINES,
+                    minimum: 0,
+                },
+                repo: {
+                    type: 'string',
+                    description: `Indexed repository name or path. ${CWD_AWARE_REPO_OMISSION}`,
+                },
+            },
+            required: ['path'],
+        },
+    },
+    {
+        name: 'grep',
+        description: `Regex search of the live checkout for files the index retained — the MCP twin of HTTP GET /api/grep.
+The file list is indexed File nodes that still have content. Bytes are read from the working tree, so edits since the last analyze are visible. Hits are 1-based. read_file startLine/endLine are 0-based.
+
+WHEN TO USE: Only after graph tools came back empty or ambiguous — exact-name pinning, docstring fallback, or literal tokens the index does not model (e.g. tactic names inside proof bodies, notation). Graph first (query/context/cypher); grep is the offline-capable fallback, never the default.
+AFTER THIS: Read the matching line with read_file({path, startLine: hit.line - 1, endLine: hit.line - 1}) or pin the symbol with context({name}).
+
+Optional caseSensitive and literal match HTTP /api/grep (default: case-insensitive regex). When full source is unavailable the result is code "source-unavailable", not an empty hit list. This tool reads the checkout and does not accept branch. Results carry timedOut: true when the wall-clock budget expired first — re-issue narrower (fileFilter or a tighter pattern).`,
+        annotations: READ_ONLY_TOOL_ANNOTATIONS,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                pattern: {
+                    type: 'string',
+                    description: 'Regex pattern (max 200 chars) matched against file content lines.',
+                },
+                fileFilter: {
+                    type: 'string',
+                    description: 'Optional case-insensitive substring filter on file paths.',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Maximum hits returned (default 50, max 200).',
+                    default: 50,
+                    minimum: 1,
+                    maximum: 200,
+                },
+                caseSensitive: {
+                    type: 'boolean',
+                    description: 'Optional. When true, match case. Default is case-insensitive, matching HTTP /api/grep.',
+                },
+                literal: {
+                    type: 'boolean',
+                    description: 'Optional. When true, treat pattern as a literal substring (escaped), matching HTTP /api/grep literal=1. Default is a regex.',
+                },
+                repo: {
+                    type: 'string',
+                    description: `Indexed repository name or path. ${CWD_AWARE_REPO_OMISSION}`,
+                },
+            },
+            required: ['pattern'],
+        },
+    },
 ];
 /**
  * Per-repo tools that accept an optional `branch` scope (#2106). Single source
  * of truth: the schema property is injected here so it cannot drift from the
  * server-side default in `local-backend.ts` (`resolveRepo(repo, branch)`).
  * `list_repos` and the `group_*` tools are intentionally excluded — they are
- * not single-repo, single-branch operations.
+ * not single-repo, single-branch operations. `read_file` and `grep` are in
+ * this set so `repo` stays required with the other per-repo tools, and the
+ * loop below skips `branch` for `CHECKOUT_SOURCE_TOOLS` — a pin would label
+ * checkout bytes with another commit.
  */
+export const CHECKOUT_SOURCE_TOOLS = new Set(['read_file', 'grep']);
 export const REPO_SCOPED_TOOLS = new Set([
+    'read_file',
+    'grep',
     'query',
     'cypher',
     'context',
@@ -978,6 +1071,9 @@ for (const tool of GITNEXUS_TOOLS) {
     tool.inputSchema.additionalProperties = false;
     if (!REPO_SCOPED_TOOLS.has(tool.name))
         continue;
+    // Checkout reads follow the working tree. Do not advertise `branch`.
+    if (CHECKOUT_SOURCE_TOOLS.has(tool.name))
+        continue;
     if (tool.inputSchema.properties.branch)
         continue;
     // Optional — `required` is left unchanged so omitting `branch` keeps today's

package/dist/server/grep-params.js

@@ -29,6 +29,10 @@ export const GREP_TIME_BUDGET_MS = 5_000;
 export const GREP_DEFAULT_LIMIT = 50;
 export const GREP_MAX_LIMIT = 200;
 const isFlagTrue = (value, name) => {
+    // MCP passes booleans. HTTP query strings stay '1' / 'true'. Null and
+    // undefined stay an empty string so an omitted flag is still false.
+    if (typeof value === 'boolean')
+        return value;
     const s = assertString(value ?? '', name).toLowerCase();
     return s === '1' || s === 'true';
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.13-rc.44",
+  "version": "1.6.13-rc.45",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",