tachibot-mcp 2.17.0 → 2.18.0

package/CHANGELOG.md

@@ -5,6 +5,42 @@ All notable changes to TachiBot MCP will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.18.0] - 2026-03-21
+
+### Added
+- **Goal-oriented checkpoints** — `planner_maker` and `planner_runner` now accept `goal` parameter for success criteria tracking
+- **6 checkpoint gates** with 5 different models (no adjacent repeats): step1 (Gemini Sherlock), 10% (Grok), 25% (GPT + amendment protocol), 50% (Qwen), 80% (Kimi decompose), 100% (GPT+Gemini dual judge)
+- **Reflexion Lite** — at 100%, Gemini reflects on what worked/failed, lesson saved to devlog
+- **Amendment protocol** — at 25%, structured plan revision (evidence + proposed changes + impact) with human gate
+- **Unblinded checkpoints** — `diff`, `testResults`, `modifiedFiles` params replace blind `code.substring(0,1500)` with real evidence
+- **`files` param on all analysis tools** — 39 tools across 9 files can now read ACTUAL CODE from disk via `readFilesIntoContext()`
+- **Shared `src/utils/file-reader.ts`** — reusable file reader with line range support (`file.ts:100-200`), size limits, directory expansion
+- **Blueprint skill updated** — `goal` param, prompt template, `planner_runner` as default execution path
+
+### Fixed
+- **Step index reset bug** — filtered arrays used local index instead of original step number (found by 3-model consensus: Kimi + Gemini + Qwen reading actual code)
+- **Truncation indicators** — `code.substring()` now adds `[truncated]` so judge models know they're seeing partial code
+
+## [2.17.2] - 2026-03-21
+
+### Added
+- **`files` parameter on 13+ more tools** — grok_architect, grok_brainstorm, grok_reason_v4, openai_explain, kimi_code, kimi_long_context, gemini_judge, gemini_brainstorm, gemini_query, gemini_summarize, qwq_reason, qwen_competitive, qwen_general (38 tools now support `files`)
+- **Directory expansion in file reader** — pass `src/tools/` to read all code files in a directory (non-recursive, capped at 20 files)
+- **Smart char budget** — multi-file reads distribute token budget across files to prevent context overflow
+
+## [2.17.1] - 2026-03-21
+
+### Fixed
+- **kimi_decompose readability overhaul** — output now uses OVERVIEW/STRUCTURE/DETAILS/RISKS sections instead of dense inline metadata
+- **Reasoning leak stripped** — Kimi K2.5 dumps CoT into content; now extracted via `<output>` tags with OVERVIEW fallback
+- **Conflicting FORMAT_INSTRUCTION removed** — emoji headers and verdict lines no longer clash with decomposition formatting
+- **Heartbeat interval fixed** — was incorrectly set to 240s instead of default 5s; network timeout now correctly passed to callOpenRouter (360s)
+- **Type safety** — args typed from zod schema, unused `log` removed, `||` replaced with `??`
+
+### Changed
+- **Smart decomposition** — model now infers context, constraints, risks, and measurable criteria even when user doesn't state them
+- **Tuned for format adherence** — temperature 0.3 (was 0.5), maxTokens 4500 (was 6000), timeout 360s (was 180s default)
+
 ## [2.17.0] - 2026-03-21
 
 ### Changed

package/dist/src/tools/advanced-modes.js

@@ -5,6 +5,7 @@ import { Architect } from "../modes/architect.js";
 import { CodeReviewer } from "../modes/code-reviewer.js";
 import { DocumentationWriter } from "../modes/documentation-writer.js";
 import { TestArchitect } from "../modes/test-architect.js";
+import { readFilesIntoContext } from "../utils/file-reader.js";
 // Workflow tools removed - using workflow-runner.ts instead
 const auditor = new Auditor();
 const commitGuardian = new CommitGuardian();
@@ -18,11 +19,15 @@ export const auditorTool = {
     description: "Evidence-based audit. Put the CONTEXT in the 'context' parameter.",
     parameters: z.object({
         context: z.string().describe("What to audit (REQUIRED - put your audit request here)"),
+        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE."),
         evidenceRequired: z.boolean().optional().describe("Require evidence for claims")
     }),
     execute: async (args, { log }) => {
         log.info("Starting audit");
-        const result = await auditor.audit(args.context, {
+        const fileContext = args.files?.length
+            ? `\n\nSOURCE CODE:\n${readFilesIntoContext(args.files)}`
+            : "";
+        const result = await auditor.audit(args.context + fileContext, {
             evidenceRequired: args.evidenceRequired
         });
         log.info("Audit complete", {
@@ -38,6 +43,7 @@ export const commitGuardianTool = {
     description: "Pre-commit validation. Put the CONTEXT in the 'context' parameter.",
     parameters: z.object({
         context: z.string().describe("Code changes to validate (REQUIRED - put your diff/changes here)"),
+        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE."),
         strict: z.boolean().optional().describe("Use strict validation rules"),
         checkSecurity: z.boolean().optional().describe("Check for security issues"),
         checkQuality: z.boolean().optional().describe("Check code quality"),
@@ -45,7 +51,10 @@ export const commitGuardianTool = {
     }),
     execute: async (args, { log }) => {
         log.info("Validating commit");
-        const result = await commitGuardian.validate(args.context, {
+        const fileContext = args.files?.length
+            ? `\n\nSOURCE CODE:\n${readFilesIntoContext(args.files)}`
+            : "";
+        const result = await commitGuardian.validate(args.context + fileContext, {
             strict: args.strict,
             checkSecurity: args.checkSecurity,
             checkQuality: args.checkQuality,
@@ -66,6 +75,7 @@ export const architectTool = {
     parameters: z.object({
         query: z.string().describe("What to analyze in the codebase (REQUIRED - put your question here)"),
         path: z.string().optional().describe("Path to the codebase to analyze"),
+        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE."),
         depth: z.enum(["shallow", "normal", "deep"])
             .optional()
             .describe("Analysis depth - must be one of: shallow, normal, deep"),
@@ -76,7 +86,10 @@ export const architectTool = {
             depth: args.depth || "normal",
             path: args.path
         });
-        const result = await architect.analyze(args.query, {
+        const fileContext = args.files?.length
+            ? `\n\nSOURCE CODE:\n${readFilesIntoContext(args.files)}`
+            : "";
+        const result = await architect.analyze(args.query + fileContext, {
             path: args.path,
             depth: args.depth,
             focusAreas: args.focusAreas
@@ -98,6 +111,7 @@ export const codeReviewerTool = {
     parameters: z.object({
         code: z.string().describe("The actual source code to review (REQUIRED - put your code here)"),
         language: z.string().optional().describe("Programming language (e.g., 'typescript', 'python')"),
+        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE."),
         focusAreas: z.array(z.enum(['security', 'performance', 'readability', 'bugs', 'best-practices']))
             .optional()
             .describe("Focus areas - array of: security, performance, readability, bugs, best-practices"),
@@ -111,7 +125,10 @@ export const codeReviewerTool = {
             language: args.language || 'auto-detect',
             focusAreas: args.focusAreas || 'all'
         });
-        const result = await codeReviewer.review(args.code, {
+        const fileContext = args.files?.length
+            ? `\n\nSOURCE CODE:\n${readFilesIntoContext(args.files)}`
+            : "";
+        const result = await codeReviewer.review(args.code + fileContext, {
             language: args.language,
             focusAreas: args.focusAreas,
             severity: args.severity,
@@ -131,6 +148,7 @@ export const documentationWriterTool = {
     description: "Documentation generation. Put the CODE in the 'code' parameter.",
     parameters: z.object({
         code: z.string().describe("The source code to document (REQUIRED - put your code here)"),
+        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE."),
         style: z.enum(['narrative', 'technical', 'beginner-friendly', 'api-reference'])
             .optional()
             .describe("Documentation style - must be one of: narrative, technical, beginner-friendly, api-reference"),
@@ -145,7 +163,10 @@ export const documentationWriterTool = {
             style: args.style || 'narrative',
             format: args.format || 'markdown'
         });
-        const result = await documentationWriter.generateDocs(args.code, {
+        const fileContext = args.files?.length
+            ? `\n\nSOURCE CODE:\n${readFilesIntoContext(args.files)}`
+            : "";
+        const result = await documentationWriter.generateDocs(args.code + fileContext, {
             style: args.style,
             includeExamples: args.includeExamples,
             generateToc: args.generateToc,
@@ -166,6 +187,7 @@ export const testArchitectTool = {
     description: "Test suite design. Put the CODE in the 'code' parameter.",
     parameters: z.object({
         code: z.string().describe("The source code to create tests for (REQUIRED - put your code here)"),
+        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE."),
         testFramework: z.enum(['jest', 'mocha', 'vitest', 'cypress', 'playwright'])
             .optional()
             .describe("Test framework - must be one of: jest, mocha, vitest, cypress, playwright"),
@@ -183,7 +205,10 @@ export const testArchitectTool = {
             testTypes: args.testTypes || ['unit', 'integration', 'e2e'],
             coverage: args.coverage || 'thorough'
         });
-        const result = await testArchitect.architectTests(args.code, {
+        const fileContext = args.files?.length
+            ? `\n\nSOURCE CODE:\n${readFilesIntoContext(args.files)}`
+            : "";
+        const result = await testArchitect.architectTests(args.code + fileContext, {
             testFramework: args.testFramework,
             testTypes: args.testTypes,
             coverage: args.coverage,

package/dist/src/tools/gemini-tools.js

@@ -11,6 +11,7 @@ import { stripFormatting } from "../utils/format-stripper.js";
 import { FORMAT_INSTRUCTION } from "../utils/format-constants.js";
 import { withHeartbeat } from "../utils/streaming-helper.js";
 import { getTimeoutConfig } from "../config/timeout-config.js";
+import { readFilesIntoContext } from "../utils/file-reader.js";
 // Note: renderOutput is applied centrally in server.ts safeAddTool() - no need to import here
 // NOTE: dotenv is loaded in server.ts before any imports
 // No need to reload here - just read from process.env
@@ -171,7 +172,8 @@ export const geminiQueryTool = {
         model: z.enum(["gemini-3", "pro", "flash"])
             .optional()
             .default("gemini-3")
-            .describe("Model variant - must be one of: gemini-3 (default), pro, flash")
+            .describe("Model variant - must be one of: gemini-3 (default), pro, flash"),
+        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE.")
     }),
     execute: async (args, { log, reportProgress }) => {
         let model = GEMINI_MODELS.GEMINI_3_PRO; // Default to Gemini 3
@@ -182,8 +184,9 @@ export const geminiQueryTool = {
             model = GEMINI_MODELS.PRO;
         }
         // Skip validation - queries may contain code or LLM-generated content
+        const fileContext = args.files?.length ? `\n\nSOURCE CODE:\n${readFilesIntoContext(args.files)}` : "";
         const reportFn = reportProgress ?? (async () => { });
-        const result = await withHeartbeat(() => callGemini(args.prompt, model, undefined, 0.7, 'llm-orchestration'), reportFn);
+        const result = await withHeartbeat(() => callGemini(args.prompt + fileContext, model, undefined, 0.7, 'llm-orchestration'), reportFn);
         return stripFormatting(result);
     }
 };
@@ -200,7 +203,8 @@ export const geminiBrainstormTool = {
     parameters: z.object({
         prompt: z.string().describe("The ideas or topic to organize and refine (REQUIRED - put raw ideas or topic here)"),
         claudeThoughts: z.string().optional().describe("Claude's initial thoughts or raw ideas to cluster and refine"),
-        maxClusters: z.number().optional().default(5).describe("Number of idea clusters to create (default: 5)")
+        maxClusters: z.number().optional().default(5).describe("Number of idea clusters to create (default: 5)"),
+        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE.")
     }),
     execute: async (args, { log, reportProgress }) => {
         const systemPrompt = `Convergent synthesis engine. Output consumed by automated toolchain.
@@ -226,8 +230,11 @@ Per cluster: Name | Score (1-10) | Top ideas (ranked) | Key insight
 Final: Which cluster has highest expected value and why. State the meta-pattern.
 No preamble. Structured output only.
 ${FORMAT_INSTRUCTION}`;
+        const fileContext = args.files?.length
+            ? `\n\nSOURCE CODE:\n${readFilesIntoContext(args.files)}`
+            : "";
         const reportFn = reportProgress ?? (async () => { });
-        const response = await withHeartbeat(() => callGemini(args.prompt, GEMINI_MODELS.GEMINI_3_PRO, systemPrompt, 0.7, 'llm-orchestration'), reportFn);
+        const response = await withHeartbeat(() => callGemini(args.prompt + fileContext, GEMINI_MODELS.GEMINI_3_PRO, systemPrompt, 0.7, 'llm-orchestration'), reportFn);
         return stripFormatting(response);
     }
 };
@@ -241,6 +248,7 @@ export const geminiAnalyzeCodeTool = {
     parameters: z.object({
         code: z.string().describe("The actual source code to analyze (REQUIRED - put your code here)"),
         language: z.string().optional().describe("Programming language (e.g., 'typescript', 'python')"),
+        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE."),
         focus: z.string().optional().default("general").describe("Analysis focus (e.g., quality, security, performance, bugs, general)")
     }),
     execute: async (args, { log, reportProgress }) => {
@@ -255,9 +263,12 @@ export const geminiAnalyzeCodeTool = {
         const systemPrompt = `Expert code reviewer. ${args.language || ''} code.
 ${focusText}.
 ${FORMAT_INSTRUCTION}`;
+        const fileContext = args.files?.length
+            ? `\n\nSOURCE CODE:\n${readFilesIntoContext(args.files)}`
+            : "";
         // Skip validation - code analysis naturally contains patterns that trigger false positives
         const reportFn = reportProgress ?? (async () => { });
-        const result = await withHeartbeat(() => callGemini(`Analyze this code:\n\n\`\`\`${args.language || ''}\n${args.code}\n\`\`\``, GEMINI_MODELS.GEMINI_3_PRO, systemPrompt, 0.3, 'llm-orchestration'), reportFn);
+        const result = await withHeartbeat(() => callGemini(`Analyze this code:\n\n\`\`\`${args.language || ''}\n${args.code}\n\`\`\`${fileContext}`, GEMINI_MODELS.GEMINI_3_PRO, systemPrompt, 0.3, 'llm-orchestration'), reportFn);
         return stripFormatting(result);
     }
 };
@@ -270,6 +281,7 @@ export const geminiAnalyzeTextTool = {
     description: "Rhetorical analysis: dissect arguments for bias, logical fallacies, and persuasion tactics. Use for evaluating claims, detecting manipulation, or understanding argument structure. Put the TEXT in the 'text' parameter.",
     parameters: z.object({
         text: z.string().describe("The text to analyze (REQUIRED - put your text here)"),
+        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE."),
         type: z.string()
             .optional()
             .default("rhetoric")
@@ -306,8 +318,11 @@ OUTPUT:
 ${analysisText}
 No preamble. Structured output only.
 ${FORMAT_INSTRUCTION}`;
+        const fileContext = args.files?.length
+            ? `\n\nSOURCE CODE:\n${readFilesIntoContext(args.files)}`
+            : "";
         const reportFn = reportProgress ?? (async () => { });
-        const result = await withHeartbeat(() => callGemini(`Analyze this text:\n\n${args.text}`, GEMINI_MODELS.GEMINI_3_PRO, systemPrompt, 0.3, 'llm-orchestration'), reportFn);
+        const result = await withHeartbeat(() => callGemini(`Analyze this text:\n\n${args.text}${fileContext}`, GEMINI_MODELS.GEMINI_3_PRO, systemPrompt, 0.3, 'llm-orchestration'), reportFn);
         return stripFormatting(result);
     }
 };
@@ -327,7 +342,8 @@ export const geminiSummarizeTool = {
         format: z.enum(["paragraph", "bullet-points", "outline"])
             .optional()
             .default("paragraph")
-            .describe("Output format - must be one of: paragraph, bullet-points, outline")
+            .describe("Output format - must be one of: paragraph, bullet-points, outline"),
+        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE.")
     }),
     execute: async (args, { log, reportProgress }) => {
         const lengthGuides = {
@@ -349,8 +365,9 @@ Focus on:
 - Conclusions and implications
 ${FORMAT_INSTRUCTION}`;
         // Skip validation for internal summarization calls
+        const fileContext = args.files?.length ? `\n\nSOURCE CODE:\n${readFilesIntoContext(args.files)}` : "";
         const reportFn = reportProgress ?? (async () => { });
-        const result = await withHeartbeat(() => callGemini(`Summarize this content:\n\n${args.content}`, GEMINI_MODELS.GEMINI_3_PRO, systemPrompt, 0.3, 'llm-orchestration'), reportFn);
+        const result = await withHeartbeat(() => callGemini(`Summarize this content:\n\n${args.content}` + fileContext, GEMINI_MODELS.GEMINI_3_PRO, systemPrompt, 0.3, 'llm-orchestration'), reportFn);
         return stripFormatting(result);
     }
 };
@@ -411,7 +428,8 @@ export const geminiJudgeTool = {
         mode: z.enum(["synthesize", "evaluate", "rank", "resolve"])
             .optional()
             .default("synthesize")
-            .describe("Judge mode: synthesize (merge best), evaluate (score each), rank (order by quality), resolve (settle conflicts)")
+            .describe("Judge mode: synthesize (merge best), evaluate (score each), rank (order by quality), resolve (settle conflicts)"),
+        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE.")
     }),
     execute: async (args, { log, reportProgress }) => {
         // Resolve perspectives from fallback params (AI clients sometimes use wrong param name)
@@ -475,8 +493,11 @@ ${FORMAT_INSTRUCTION}`;
         const userPrompt = args.question
             ? `QUESTION: ${args.question}\n\nPERSPECTIVES TO JUDGE:\n${args.perspectives}`
             : args.perspectives;
+        const fileContext = args.files?.length
+            ? `\n\nSOURCE CODE:\n${readFilesIntoContext(args.files)}`
+            : "";
         const reportFn = reportProgress ?? (async () => { });
-        const result = await withHeartbeat(() => callGemini(userPrompt, GEMINI_MODELS.GEMINI_3_PRO, systemPrompt, 0.3, 'llm-orchestration'), reportFn);
+        const result = await withHeartbeat(() => callGemini(userPrompt + fileContext, GEMINI_MODELS.GEMINI_3_PRO, systemPrompt, 0.3, 'llm-orchestration'), reportFn);
         return stripFormatting(result);
     }
 };

package/dist/src/tools/grok-enhanced.js

@@ -7,6 +7,7 @@ import { config } from "dotenv";
 import * as path from 'path';
 import { fileURLToPath } from 'url';
 import { getGrokApiKey, hasGrokApiKey } from "../utils/api-keys.js";
+import { readFilesIntoContext } from "../utils/file-reader.js";
 import { link } from "../utils/ansi-renderer.js";
 import { stripFormatting } from "../utils/format-stripper.js";
 import { FORMAT_INSTRUCTION } from "../utils/format-constants.js";
@@ -222,10 +223,11 @@ export const grokReasonEnhanced = {
         context: z.string().optional(),
         useHeavy: z.boolean().optional(),
         enableLiveSearch: z.boolean().optional(),
-        maxSteps: z.number().optional()
+        maxSteps: z.number().optional(),
+        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE.")
     }),
     execute: async (args, { log }) => {
-        const { problem, approach = "first-principles", context, useHeavy = false, enableLiveSearch = false, maxSteps = 5 } = args;
+        const { problem, approach = "first-principles", context, useHeavy = false, enableLiveSearch = false, maxSteps = 5, files } = args;
         const approachPrompts = {
             analytical: "Break down the problem systematically and analyze each component",
             creative: "Think outside the box and consider unconventional solutions",
@@ -233,6 +235,7 @@ export const grokReasonEnhanced = {
             "first-principles": "Break down to fundamental truths and build up from there",
             "multi-agent": "Consider multiple perspectives and synthesize them"
         };
+        const fileContext = files?.length ? `\n\nSOURCE CODE:\n${readFilesIntoContext(files)}` : "";
         const messages = [
             {
                 role: "system",
@@ -245,7 +248,7 @@ ${FORMAT_INSTRUCTION}`
             },
             {
                 role: "user",
-                content: problem
+                content: problem + fileContext
             }
         ];
         const modelName = useHeavy ? 'Grok-4-Heavy' : 'Grok-4.1';

package/dist/src/tools/grok-tools.js

@@ -13,6 +13,7 @@ import { stripFormatting } from "../utils/format-stripper.js";
 import { FORMAT_INSTRUCTION } from "../utils/format-constants.js";
 import { tryOpenRouterGateway, isGatewayEnabled } from "../utils/openrouter-gateway.js";
 import { withHeartbeat } from "../utils/streaming-helper.js";
+import { readFilesIntoContext } from "../utils/file-reader.js";
 // Note: renderOutput is applied centrally in server.ts safeAddTool() - no need to import here
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -130,6 +131,7 @@ export const grokReasonTool = {
             .optional()
             .describe("Reasoning approach (e.g., analytical, creative, systematic, first-principles)"),
         context: z.string().optional().describe("Additional context for the problem"),
+        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE."),
         useHeavy: z.boolean().optional().describe("Use expensive Grok 4 Heavy model ($3/$15) for complex tasks")
     }),
     execute: async (args, { log, reportProgress }) => {
@@ -140,6 +142,9 @@ export const grokReasonTool = {
             systematic: "Follow a step-by-step logical process",
             "first-principles": "Break down to fundamental truths and build up from there"
         };
+        const fileContext = args.files?.length
+            ? `\n\nSOURCE CODE:\n${readFilesIntoContext(args.files)}`
+            : "";
         const messages = [
             {
                 role: "system",
@@ -150,7 +155,7 @@ ${FORMAT_INSTRUCTION}`
             },
             {
                 role: "user",
-                content: problem
+                content: problem + fileContext
             }
         ];
         // Use GROK_4_1_FAST_REASONING by default (latest with enhanced reasoning!), GROK_4_HEAVY only if explicitly requested
@@ -175,6 +180,7 @@ export const grokCodeTool = {
             .describe("Code task (e.g., analyze, optimize, debug, review, refactor)"),
         code: z.string().describe("The actual source code to analyze (REQUIRED - put your code here)"),
         language: z.string().optional().describe("Programming language (e.g., 'typescript', 'python')"),
+        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE."),
         requirements: z.string().optional().describe("Specific requirements or focus areas")
     }),
     execute: async (args, { log, reportProgress }) => {
@@ -186,6 +192,9 @@ export const grokCodeTool = {
             review: "Review this code for best practices and improvements",
             refactor: "Refactor this code for better maintainability and clarity"
         };
+        const fileContext = args.files?.length
+            ? `\n\nSOURCE CODE:\n${readFilesIntoContext(args.files)}`
+            : "";
         const messages = [
             {
                 role: "system",
@@ -197,7 +206,7 @@ ${FORMAT_INSTRUCTION}`
             },
             {
                 role: "user",
-                content: `Code:\n\`\`\`${language || ''}\n${code}\n\`\`\``
+                content: `Code:\n\`\`\`${language || ''}\n${code}\n\`\`\`` + fileContext
             }
         ];
         log?.info(`Using Grok 4.1 Fast Non-Reasoning (2M context, tool-calling optimized, $0.20/$0.50)`);
@@ -218,6 +227,7 @@ export const grokDebugTool = {
         issue: z.string().describe("Description of the issue or bug (REQUIRED - put your problem here)"),
         code: z.string().optional().describe("Relevant code that has the issue"),
         error: z.string().optional().describe("Error message or stack trace"),
+        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE."),
         context: z.string().optional().describe("Additional context about the environment or conditions")
     }),
     execute: async (args, { log, reportProgress }) => {
@@ -232,6 +242,9 @@ export const grokDebugTool = {
         if (context) {
             prompt += `\nContext: ${context}\n`;
         }
+        const fileContext = args.files?.length
+            ? `\n\nSOURCE CODE:\n${readFilesIntoContext(args.files)}`
+            : "";
         const messages = [
             {
                 role: "system",
@@ -245,7 +258,7 @@ ${FORMAT_INSTRUCTION}`
             },
             {
                 role: "user",
-                content: prompt
+                content: prompt + fileContext
             }
         ];
         log?.info(`Using Grok 4.1 Fast Non-Reasoning for debugging (tool-calling optimized, $0.20/$0.50)`);
@@ -267,10 +280,14 @@ export const grokArchitectTool = {
         constraints: z.string().optional().describe("Technical or business constraints to consider"),
         scale: z.string()
             .optional()
-            .describe("Expected scale (e.g., small, medium, large, enterprise)")
+            .describe("Expected scale (e.g., small, medium, large, enterprise)"),
+        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE."),
     }),
     execute: async (args, { log, reportProgress }) => {
         const { requirements, constraints, scale } = args;
+        const fileContext = args.files?.length
+            ? `\n\nSOURCE CODE:\n${readFilesIntoContext(args.files)}`
+            : "";
         const messages = [
             {
                 role: "system",
@@ -282,7 +299,7 @@ ${FORMAT_INSTRUCTION}`
             },
             {
                 role: "user",
-                content: requirements
+                content: requirements + fileContext
             }
         ];
         log?.info(`Using Grok 4.1 Fast Reasoning for architecture (latest model, $0.20/$0.50)`);
@@ -303,10 +320,14 @@ export const grokBrainstormTool = {
         topic: z.string().describe("The topic to brainstorm about (REQUIRED - put your idea/topic here)"),
         constraints: z.string().optional().describe("Any constraints or requirements to consider"),
         numIdeas: z.number().optional().describe("Number of radical rebuilds to generate (default: 5)"),
-        forceHeavy: z.boolean().optional().describe("Use expensive Grok 4 Heavy model ($3/$15) for deeper creativity")
+        forceHeavy: z.boolean().optional().describe("Use expensive Grok 4 Heavy model ($3/$15) for deeper creativity"),
+        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE."),
     }),
     execute: async (args, { log, reportProgress }) => {
         const { topic, constraints, numIdeas = 5, forceHeavy = false } = args;
+        const fileContext = args.files?.length
+            ? `\n\nSOURCE CODE:\n${readFilesIntoContext(args.files)}`
+            : "";
         const messages = [
             {
                 role: "system",
@@ -332,7 +353,7 @@ ${FORMAT_INSTRUCTION}`
             },
             {
                 role: "user",
-                content: topic
+                content: topic + fileContext
             }
         ];
         const model = forceHeavy ? GrokModel.GROK_4_HEAVY : GrokModel.GROK_4_1_FAST_REASONING;

package/dist/src/tools/openai-tools.js

@@ -13,6 +13,7 @@ import { OPENAI_MODELS } from "../config/model-constants.js";
 import { FORMAT_INSTRUCTION } from "../utils/format-constants.js";
 import { stripFormatting } from "../utils/format-stripper.js";
 import { withHeartbeat } from "../utils/streaming-helper.js";
+import { readFilesIntoContext } from "../utils/file-reader.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 config({ path: path.resolve(__dirname, '../../../.env') });
@@ -342,6 +343,7 @@ export const openaiGpt5ReasonTool = {
     parameters: z.object({
         query: z.string().describe("The question or problem to reason about (REQUIRED - put your question here)"),
         context: z.string().optional().describe("Additional context for the reasoning task"),
+        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE."),
         mode: z.string()
             .optional()
             .default("analytical")
@@ -354,6 +356,9 @@ export const openaiGpt5ReasonTool = {
             logical: "Use formal logic and systematic deduction",
             analytical: "Break down complex problems into components"
         };
+        const fileContext = args.files?.length
+            ? `\n\nSOURCE CODE:\n${readFilesIntoContext(args.files)}`
+            : "";
         const messages = [
             {
                 role: "system",
@@ -365,7 +370,7 @@ ${FORMAT_INSTRUCTION}`
             },
             {
                 role: "user",
-                content: args.query
+                content: args.query + fileContext
             }
         ];
         // Use heartbeat to prevent MCP timeout during reasoning
@@ -383,6 +388,7 @@ export const openAIBrainstormTool = {
     parameters: z.object({
         problem: z.string().describe("The engineering problem or design tradeoff to brainstorm about (REQUIRED)"),
         constraints: z.string().optional().describe("Technical constraints: language, framework, performance requirements, team size"),
+        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE."),
         quantity: z.number().optional().describe("Number of approaches to generate (default: 5)"),
         model: z.enum(["gpt-5.4", "gpt-5.4-mini", "gpt-5.4-pro"])
             .optional()
@@ -396,6 +402,9 @@ export const openAIBrainstormTool = {
         const { problem, constraints, quantity = 5, model = OPENAI_MODELS.DEFAULT, reasoning_effort = "medium", max_tokens = 6000 } = args;
         // GPT-5.4 reasoning tokens eat into max_output_tokens — enforce minimum
         const effectiveMaxTokens = Math.max(max_tokens, 4000);
+        const fileContext = args.files?.length
+            ? `\n\nSOURCE CODE:\n${readFilesIntoContext(args.files)}`
+            : "";
         const messages = [
             {
                 role: "system",
@@ -430,7 +439,7 @@ ${FORMAT_INSTRUCTION}`
             },
             {
                 role: "user",
-                content: problem
+                content: problem + fileContext
             }
         ];
         const modelEnum = model;
@@ -447,6 +456,7 @@ export const openaiCodeReviewTool = {
     parameters: z.object({
         code: z.string().describe("The actual source code to review (REQUIRED - put your code here)"),
         language: z.string().optional().describe("Programming language (e.g., 'typescript', 'python')"),
+        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE."),
         focusAreas: z.array(z.enum(["security", "performance", "readability", "bugs", "best-practices"]))
             .optional()
             .describe("Focus areas - array of: security, performance, readability, bugs, best-practices")
@@ -455,6 +465,9 @@ export const openaiCodeReviewTool = {
         const focusText = args.focusAreas
             ? `Focus especially on: ${args.focusAreas.join(', ')}`
             : "Review all aspects: security, performance, readability, bugs, and best practices";
+        const fileContext = args.files?.length
+            ? `\n\nSOURCE CODE:\n${readFilesIntoContext(args.files)}`
+            : "";
         const messages = [
             {
                 role: "system",
@@ -467,7 +480,7 @@ ${FORMAT_INSTRUCTION}`
             },
             {
                 role: "user",
-                content: `Review this code:\n\`\`\`${args.language || ''}\n${args.code}\n\`\`\``
+                content: `Review this code:\n\`\`\`${args.language || ''}\n${args.code}\n\`\`\`` + fileContext
             }
         ];
         // Use heartbeat to prevent MCP timeout
@@ -491,7 +504,8 @@ export const openaiExplainTool = {
         style: z.enum(["technical", "simple", "analogy", "visual"])
             .optional()
             .default("simple")
-            .describe("Explanation style - must be one of: technical, simple, analogy, visual")
+            .describe("Explanation style - must be one of: technical, simple, analogy, visual"),
+        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE."),
     }),
     execute: async (args, { log }) => {
         const levelPrompts = {
@@ -505,6 +519,9 @@ export const openaiExplainTool = {
             analogy: "Use analogies and metaphors",
             visual: "Describe with visual concepts and diagrams"
         };
+        const fileContext = args.files?.length
+            ? `\n\nSOURCE CODE:\n${readFilesIntoContext(args.files)}`
+            : "";
         const messages = [
             {
                 role: "system",
@@ -516,7 +533,7 @@ ${FORMAT_INSTRUCTION}`
             },
             {
                 role: "user",
-                content: `Explain: ${args.topic}`
+                content: `Explain: ${args.topic}` + fileContext
             }
         ];
         return await callOpenAI(messages, OPENAI_MODELS.DEFAULT, 0.7, 2500, "low");