@hasna/terminal 4.2.0 → 4.3.1

package/src/mcp/tools/files.ts

@@ -0,0 +1,369 @@
+// File tools: read_file, read_files, symbols, symbols_dir, read_symbol, edit, review
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z, type ToolHelpers } from "./helpers.js";
+import { stripAnsi } from "../../compression.js";
+import { estimateTokens } from "../../tokens.js";
+import { getOutputProvider } from "../../providers/index.js";
+import { cachedRead } from "../../file-cache.js";
+
+export function registerFileTools(server: McpServer, h: ToolHelpers): void {
+
+  // ── read_file ─────────────────────────────────────────────────────────────
+
+  server.tool(
+    "read_file",
+    "Read a file with summarize=true for AI outline (~90% fewer tokens). For full file reads without summarization, prefer your native Read tool (faster, no MCP overhead). Use this when you want cached reads or AI summaries.",
+    {
+      path: z.string().describe("File path"),
+      offset: z.number().optional().describe("Start line (0-indexed)"),
+      limit: z.number().optional().describe("Max lines to return"),
+      summarize: z.boolean().optional().describe("Return AI summary instead of full content (saves ~90% tokens)"),
+      focus: z.string().optional().describe("Focus hint for summary (e.g., 'public API', 'error handling', 'auth logic')"),
+    },
+    async ({ path: rawPath, offset, limit, summarize, focus }) => {
+      const start = Date.now();
+      const path = h.resolvePath(rawPath);
+      const result = cachedRead(path, { offset, limit });
+
+      if (summarize && result.content.length > 500) {
+        const provider = getOutputProvider();
+        const outputModel = provider.name === "groq" ? "llama-3.1-8b-instant" : undefined;
+        const content = result.content.length > 8000 ? result.content.slice(0, 8000) : result.content;
+        const focusInstruction = focus
+          ? `Focus specifically on: ${focus}. Describe only aspects related to "${focus}".`
+          : `Describe what this source file does in 2-4 lines. Include: main class/module name, key methods/functions, what it exports, and its purpose.`;
+        const summary = await provider.complete(
+          `File: ${path}\n\n${content}`,
+          {
+            model: outputModel,
+            system: `${focusInstruction} Be specific — name the actual functions and what they do. Never just say "N lines of code."`,
+            maxTokens: 300,
+            temperature: 0.2,
+          }
+        );
+        const outputTokens = estimateTokens(result.content);
+        const summaryTokens = estimateTokens(summary);
+        const saved = Math.max(0, outputTokens - summaryTokens);
+        h.logCall("read_file", { command: path, outputTokens, tokensSaved: saved, durationMs: Date.now() - start, aiProcessed: true });
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify({
+            summary,
+            lines: result.content.split("\n").length,
+            tokensSaved: saved,
+            cached: result.cached,
+          }) }],
+        };
+      }
+
+      h.logCall("read_file", { command: path, outputTokens: estimateTokens(result.content), tokensSaved: 0, durationMs: Date.now() - start });
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify({
+          content: result.content,
+          cached: result.cached,
+          readCount: result.readCount,
+          ...(result.cached ? { note: `Served from cache (read #${result.readCount})` } : {}),
+        }) }],
+      };
+    }
+  );
+
+  // ── read_files ────────────────────────────────────────────────────────────
+
+  server.tool(
+    "read_files",
+    "Read multiple files in one call. Use summarize=true for AI outlines (~90% fewer tokens per file). Saves N-1 round trips vs separate read_file calls.",
+    {
+      files: z.array(z.string()).describe("File paths (relative or absolute)"),
+      summarize: z.boolean().optional().describe("AI summary instead of full content"),
+    },
+    async ({ files, summarize }) => {
+      const start = Date.now();
+      const results: Record<string, any> = {};
+
+      for (const f of files.slice(0, 10)) { // max 10 files per call
+        const filePath = h.resolvePath(f);
+        const result = cachedRead(filePath, {});
+
+        if (summarize && result.content.length > 500) {
+          const provider = getOutputProvider();
+          const outputModel = provider.name === "groq" ? "llama-3.1-8b-instant" : undefined;
+          const content = result.content.length > 8000 ? result.content.slice(0, 8000) : result.content;
+          const summary = await provider.complete(`File: ${filePath}\n\n${content}`, {
+            model: outputModel,
+            system: `Describe what this source file does in 2-4 lines. Include: main class/module name, key methods/functions, what it exports, and its purpose. Be specific.`,
+            maxTokens: 300, temperature: 0.2,
+          });
+          results[f] = { summary, lines: result.content.split("\n").length };
+        } else {
+          results[f] = { content: result.content, lines: result.content.split("\n").length };
+        }
+      }
+
+      h.logCall("read_files", { command: `${files.length} files`, durationMs: Date.now() - start, aiProcessed: !!summarize });
+      return { content: [{ type: "text" as const, text: JSON.stringify(results) }] };
+    }
+  );
+
+  // ── symbols ───────────────────────────────────────────────────────────────
+
+  server.tool(
+    "symbols",
+    "Get a structured outline of any source file — functions, classes, methods, interfaces, exports with line numbers. Works for ALL languages (TypeScript, Python, Go, Rust, Java, C#, Ruby, PHP, etc.). AI-powered, not regex.",
+    {
+      path: z.string().describe("File path to extract symbols from"),
+    },
+    async ({ path: rawPath }) => {
+      const start = Date.now();
+      const filePath = h.resolvePath(rawPath);
+      const result = cachedRead(filePath, {});
+      if (!result.content || result.content.startsWith("Error:")) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ error: `Cannot read ${filePath}` }) }] };
+      }
+
+      // AI extracts symbols — works for ANY language
+      let symbols: any[] = [];
+      try {
+        const provider = getOutputProvider();
+        const outputModel = provider.name === "groq" ? "llama-3.1-8b-instant" : undefined;
+        const content = result.content.length > 8000 ? result.content.slice(0, 8000) : result.content;
+        const summary = await provider.complete(
+          `File: ${filePath}\n\n${content}`,
+          {
+            model: outputModel,
+            system: `Extract all symbols from this source file. Return ONLY a JSON array, no explanation.
+
+Each symbol: {"name": "symbolName", "kind": "function|class|method|interface|type|variable|export", "line": lineNumber, "signature": "brief signature"}
+
+For class methods, use "ClassName.methodName" as name with kind "method".
+Include: functions, classes, methods, interfaces, types, exported constants.
+Exclude: imports, local variables, comments.
+Line numbers must be accurate (count from 1).`,
+            maxTokens: 2000,
+            temperature: 0,
+          }
+        );
+
+        const jsonMatch = summary.match(/\[[\s\S]*\]/);
+        if (jsonMatch) symbols = JSON.parse(jsonMatch[0]);
+      } catch (err: any) {
+        // Surface the error instead of silently returning []
+        return { content: [{ type: "text" as const, text: JSON.stringify({ error: `AI symbol extraction failed: ${err.message?.slice(0, 200)}`, file: filePath }) }] };
+      }
+
+      const outputTokens = estimateTokens(result.content);
+      const symbolTokens = estimateTokens(JSON.stringify(symbols));
+      h.logCall("symbols", { command: filePath, outputTokens, tokensSaved: Math.max(0, outputTokens - symbolTokens), durationMs: Date.now() - start, aiProcessed: true });
+
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(symbols) }],
+      };
+    }
+  );
+
+  // ── symbols_dir ───────────────────────────────────────────────────────────
+
+  server.tool(
+    "symbols_dir",
+    "Get symbols for all source files in a directory. AI-powered, works for any language. One call replaces N separate symbols calls.",
+    {
+      path: z.string().optional().describe("Directory (default: src/)"),
+      maxFiles: z.number().optional().describe("Max files to scan (default: 10)"),
+    },
+    async ({ path: dirPath, maxFiles }) => {
+      const start = Date.now();
+      const dir = h.resolvePath(dirPath ?? "src/");
+      const limit = maxFiles ?? 10;
+
+      // Find source files
+      const findResult = await h.exec(
+        `find "${dir}" -maxdepth 3 -type f \\( -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.java" -o -name "*.rb" -o -name "*.php" \\) -not -path "*/node_modules/*" -not -path "*/dist/*" -not -name "*.test.*" -not -name "*.spec.*" | head -${limit}`,
+        process.cwd(), 5000
+      );
+      const files = findResult.stdout.split("\n").filter(l => l.trim());
+
+      const allSymbols: Record<string, any[]> = {};
+      const provider = getOutputProvider();
+      const outputModel = provider.name === "groq" ? "llama-3.1-8b-instant" : undefined;
+
+      for (const file of files) {
+        const result = cachedRead(file, {});
+        if (!result.content || result.content.startsWith("Error:")) continue;
+        try {
+          const content = result.content.length > 6000 ? result.content.slice(0, 6000) : result.content;
+          const summary = await provider.complete(`File: ${file}\n\n${content}`, {
+            model: outputModel,
+            system: `Extract all symbols. Return ONLY a JSON array. Each: {"name":"x","kind":"function|class|method|interface|type","line":N,"signature":"brief"}. For class methods use "Class.method". Exclude imports.`,
+            maxTokens: 1500, temperature: 0,
+          });
+          const jsonMatch = summary.match(/\[[\s\S]*\]/);
+          if (jsonMatch) allSymbols[file] = JSON.parse(jsonMatch[0]);
+        } catch {}
+      }
+
+      h.logCall("symbols_dir", { command: `${files.length} files in ${dir}`, durationMs: Date.now() - start, aiProcessed: true });
+      return { content: [{ type: "text" as const, text: JSON.stringify({ directory: dir, files: files.length, symbols: allSymbols }) }] };
+    }
+  );
+
+  // ── read_symbol ───────────────────────────────────────────────────────────
+
+  server.tool(
+    "read_symbol",
+    "Read a specific function, class, or interface by name from a source file. Returns only the code block — not the entire file. Saves 70-85% tokens vs reading the whole file.",
+    {
+      path: z.string().describe("Source file path"),
+      name: z.string().describe("Symbol name (function, class, interface)"),
+    },
+    async ({ path: rawPath, name }) => {
+      const start = Date.now();
+      const filePath = h.resolvePath(rawPath);
+      const result = cachedRead(filePath, {});
+      if (!result.content || result.content.startsWith("Error:")) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ error: `Cannot read ${filePath}` }) }] };
+      }
+
+      // AI extracts the specific symbol — works for ANY language
+      const provider = getOutputProvider();
+      const outputModel = provider.name === "groq" ? "llama-3.1-8b-instant" : undefined;
+      const summary = await provider.complete(
+        `File: ${filePath}\nSymbol to extract: ${name}\n\n${result.content.slice(0, 8000)}`,
+        {
+          model: outputModel,
+          system: `Extract the complete code block for the symbol "${name}" from this file. Return ONLY a JSON object:
+{"name": "${name}", "code": "the complete code block", "startLine": N, "endLine": N}
+
+If the symbol is not found, return: {"error": "not found", "available": ["list", "of", "symbol", "names"]}
+
+Match by function name, class name, method name (including ClassName.method), interface, type, or variable name.`,
+          maxTokens: 2000,
+          temperature: 0,
+        }
+      );
+
+      let parsed: any = {};
+      try {
+        const jsonMatch = summary.match(/\{[\s\S]*\}/);
+        if (jsonMatch) parsed = JSON.parse(jsonMatch[0]);
+      } catch {}
+
+      h.logCall("read_symbol", { command: `${filePath}:${name}`, outputTokens: estimateTokens(result.content), tokensSaved: Math.max(0, estimateTokens(result.content) - estimateTokens(JSON.stringify(parsed))), durationMs: Date.now() - start, aiProcessed: true });
+
+      return { content: [{ type: "text" as const, text: JSON.stringify(parsed) }] };
+    }
+  );
+
+  // ── edit ───────────────────────────────────────────────────────────────────
+
+  server.tool(
+    "edit",
+    "Find and replace in a file. For simple edits, prefer your native Edit tool (faster). Use this for batch replacements (all=true) or when you don't have a native Edit tool available.",
+    {
+      file: z.string().describe("File path"),
+      find: z.string().describe("Text to find (exact match)"),
+      replace: z.string().describe("Replacement text"),
+      all: z.boolean().optional().describe("Replace all occurrences (default: first only)"),
+    },
+    async ({ file: rawFile, find, replace, all }) => {
+      const start = Date.now();
+      const file = h.resolvePath(rawFile);
+      const { readFileSync, writeFileSync } = await import("fs");
+      try {
+        let content = readFileSync(file, "utf8");
+        const count = (content.match(new RegExp(find.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g")) || []).length;
+        if (count === 0) {
+          return { content: [{ type: "text" as const, text: JSON.stringify({ error: "Text not found", file }) }] };
+        }
+        if (all) {
+          content = content.split(find).join(replace);
+        } else {
+          content = content.replace(find, replace);
+        }
+        writeFileSync(file, content);
+        h.logCall("edit", { command: `edit ${file}`, durationMs: Date.now() - start });
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, file, replacements: all ? count : 1, diff: { removed: find.slice(0, 100), added: replace.slice(0, 100) } }) }] };
+      } catch (e: any) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ error: e.message }) }] };
+      }
+    }
+  );
+
+  // ── review ────────────────────────────────────────────────────────────────
+
+  server.tool(
+    "review",
+    "AI code review of recent changes or specific files. Returns: bugs, security issues, suggestions. One call replaces git diff + manual reading.",
+    {
+      since: z.string().optional().describe("Git ref to diff against (e.g., 'HEAD~3', 'main')"),
+      files: z.array(z.string()).optional().describe("Specific files to review"),
+      cwd: z.string().optional().describe("Working directory"),
+    },
+    async ({ since, files, cwd }) => {
+      const start = Date.now();
+      const workDir = cwd ?? process.cwd();
+
+      let content: string;
+      if (files && files.length > 0) {
+        const fileContents = files.map(f => {
+          const result = cachedRead(h.resolvePath(f, workDir), {});
+          return `=== ${f} ===\n${result.content.slice(0, 4000)}`;
+        });
+        content = fileContents.join("\n\n");
+      } else {
+        const ref = since ?? "HEAD~1";
+        const diff = await h.exec(`git diff ${ref} --no-color`, workDir, 15000);
+        content = diff.stdout.slice(0, 12000);
+      }
+
+      const provider = getOutputProvider();
+      const outputModel = provider.name === "groq" ? "llama-3.1-8b-instant" : undefined;
+      const review = await provider.complete(`Review this code:\n\n${content}`, {
+        model: outputModel,
+        system: `You are a senior code reviewer. Review concisely:
+- Bugs or logic errors
+- Security issues (injection, auth, secrets)
+- Missing error handling
+- Performance concerns
+- Style/naming issues (only if significant)
+
+Format: list issues as "- [severity] file:line description". If clean, say "No issues found."
+Be specific, not generic. Only flag real problems.`,
+        maxTokens: 800, temperature: 0.2,
+      });
+
+      h.logCall("review", { command: `review ${since ?? files?.join(",") ?? "HEAD~1"}`, durationMs: Date.now() - start, aiProcessed: true });
+      return { content: [{ type: "text" as const, text: JSON.stringify({ review, scope: since ?? files }) }] };
+    }
+  );
+
+  // ── write_files ─────────────────────────────────────────────────────────
+
+  server.tool(
+    "write_files",
+    "Write multiple files in one call. Auto-creates parent directories. Saves N-1 round trips vs separate writes.",
+    {
+      files: z.array(z.object({
+        path: z.string().describe("File path (relative or absolute)"),
+        content: z.string().describe("File content"),
+      })).describe("Files to write"),
+    },
+    async ({ files }) => {
+      const { writeFileSync, mkdirSync, existsSync } = await import("fs");
+      const { dirname } = await import("path");
+      const results: { path: string; ok: boolean; bytes?: number; error?: string }[] = [];
+      for (const f of files.slice(0, 20)) {
+        try {
+          const filePath = h.resolvePath(f.path);
+          const dir = dirname(filePath);
+          if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+          writeFileSync(filePath, f.content);
+          results.push({ path: f.path, ok: true, bytes: f.content.length });
+        } catch (e: any) {
+          results.push({ path: f.path, ok: false, error: e.message?.slice(0, 100) });
+        }
+      }
+      h.logCall("write_files", { command: `${files.length} files` });
+      return { content: [{ type: "text" as const, text: JSON.stringify({ written: results.filter(r => r.ok).length, total: results.length, results }) }] };
+    }
+  );
+}

package/src/mcp/tools/git.ts

@@ -0,0 +1,306 @@
+// Git tools: commit, bulk_commit, smart_commit, diff, repo_state, last_commit
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z, type ToolHelpers } from "./helpers.js";
+import { stripAnsi } from "../../compression.js";
+import { estimateTokens } from "../../tokens.js";
+import { processOutput } from "../../output-processor.js";
+import { getOutputProvider } from "../../providers/index.js";
+import { invalidateBootCache } from "../../session-boot.js";
+
+export function registerGitTools(server: McpServer, h: ToolHelpers): void {
+
+  // ── commit ────────────────────────────────────────────────────────────────
+
+  server.tool(
+    "commit",
+    "Commit and optionally push. Agent says what to commit, we handle git add/commit/push. Saves ~400 tokens vs raw git commands.",
+    {
+      message: z.string().describe("Commit message"),
+      files: z.array(z.string()).optional().describe("Files to stage (default: all changed)"),
+      push: z.boolean().optional().describe("Push after commit (default: false)"),
+      cwd: z.string().optional().describe("Working directory"),
+    },
+    async ({ message, files, push, cwd }) => {
+      const start = Date.now();
+      const workDir = cwd ?? process.cwd();
+      const addCmd = files && files.length > 0 ? `git add ${files.map(f => `"${f}"`).join(" ")}` : "git add -A";
+      const commitCmd = `${addCmd} && git commit -m ${JSON.stringify(message)}`;
+      const fullCmd = push ? `${commitCmd} && git push` : commitCmd;
+
+      const result = await h.exec(fullCmd, workDir, 30000);
+      const output = (result.stdout + result.stderr).trim();
+      h.logCall("commit", { command: `commit: ${message.slice(0, 80)}`, durationMs: Date.now() - start, exitCode: result.exitCode });
+      invalidateBootCache();
+
+      return { content: [{ type: "text" as const, text: JSON.stringify({
+        exitCode: result.exitCode,
+        output: stripAnsi(output).split("\n").filter(l => l.trim()).slice(0, 5).join("\n"),
+        pushed: push ?? false,
+      }) }] };
+    }
+  );
+
+  // ── bulk_commit ───────────────────────────────────────────────────────────
+
+  server.tool(
+    "bulk_commit",
+    "Multiple logical commits in one call. Agent decides which files go in which commit, we handle all git commands. No AI cost. Use smart_commit instead if you want AI to decide the grouping.",
+    {
+      commits: z.array(z.object({
+        message: z.string().describe("Commit message"),
+        files: z.array(z.string()).describe("Files to stage for this commit"),
+      })).describe("Array of logical commits"),
+      push: z.boolean().optional().describe("Push after all commits (default: true)"),
+      cwd: z.string().optional().describe("Working directory"),
+    },
+    async ({ commits, push, cwd }) => {
+      const start = Date.now();
+      const workDir = cwd ?? process.cwd();
+      const results: { message: string; files: number; ok: boolean }[] = [];
+
+      for (const c of commits) {
+        const fileArgs = c.files.map(f => `"${f}"`).join(" ");
+        const cmd = `git add ${fileArgs} && git commit -m ${JSON.stringify(c.message)}`;
+        const r = await h.exec(cmd, workDir, 15000);
+        results.push({ message: c.message, files: c.files.length, ok: r.exitCode === 0 });
+      }
+
+      let pushed = false;
+      if (push !== false) {
+        const pushResult = await h.exec("git push", workDir, 30000);
+        pushed = pushResult.exitCode === 0;
+      }
+
+      invalidateBootCache();
+      h.logCall("bulk_commit", { command: `${commits.length} commits`, durationMs: Date.now() - start });
+
+      return { content: [{ type: "text" as const, text: JSON.stringify({ commits: results, pushed, total: results.length }) }] };
+    }
+  );
+
+  // ── smart_commit ──────────────────────────────────────────────────────────
+
+  server.tool(
+    "smart_commit",
+    "AI-powered git commit. Analyzes all changes, groups into logical commits with generated messages, stages and commits each group, optionally pushes. One call replaces the entire git workflow. Agent just says 'commit my work'.",
+    {
+      push: z.boolean().optional().describe("Push after all commits (default: true)"),
+      hint: z.string().optional().describe("Optional context about the changes (e.g., 'fixed auth + added users endpoint')"),
+      cwd: z.string().optional().describe("Working directory"),
+    },
+    async ({ push, hint, cwd }) => {
+      const start = Date.now();
+      const workDir = cwd ?? process.cwd();
+
+      // 1. Get all changed files
+      const status = await h.exec("git status --porcelain", workDir, 10000);
+      const diffStat = await h.exec("git diff --stat", workDir, 10000);
+      const untrackedDiff = await h.exec("git diff HEAD --stat", workDir, 10000);
+
+      const changedFiles = status.stdout.trim();
+      if (!changedFiles) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ message: "Nothing to commit — working tree clean" }) }] };
+      }
+
+      // 2. AI groups changes into logical commits
+      const provider = getOutputProvider();
+      const outputModel = provider.name === "groq" ? "llama-3.1-8b-instant" : undefined;
+
+      const grouping = await provider.complete(
+        `Changed files:\n${changedFiles}\n\nDiff stats:\n${diffStat.stdout}\n${untrackedDiff.stdout}${hint ? `\n\nContext: ${hint}` : ""}`,
+        {
+          model: outputModel,
+          system: `You are a git commit assistant. Group these changed files into logical commits. Return ONLY a JSON array:
+
+[{"message": "conventional commit message", "files": ["file1.ts", "file2.ts"]}]
+
+Rules:
+- Group related changes (same feature, same fix, same refactor)
+- Use conventional commits: feat:, fix:, refactor:, test:, docs:, chore:
+- Message should explain WHY, not WHAT (the diff shows what)
+- Each file appears in exactly one group
+- If all changes are related, use a single commit
+- Extract file paths from the status output (skip the status prefix like M, A, ??)`,
+          maxTokens: 1000,
+          temperature: 0,
+        }
+      );
+
+      let commits: { message: string; files: string[] }[] = [];
+      try {
+        const jsonMatch = grouping.match(/\[[\s\S]*\]/);
+        if (jsonMatch) commits = JSON.parse(jsonMatch[0]);
+      } catch {}
+
+      if (commits.length === 0) {
+        // Fallback: single commit with all files
+        commits = [{ message: hint ?? "chore: update files", files: changedFiles.split("\n").map(l => l.slice(3).trim()) }];
+      }
+
+      // 3. Execute each commit
+      const results: { message: string; files: number; ok: boolean }[] = [];
+      for (const c of commits) {
+        const fileArgs = c.files.map(f => `"${f}"`).join(" ");
+        const cmd = `git add ${fileArgs} && git commit -m ${JSON.stringify(c.message)}`;
+        const r = await h.exec(cmd, workDir, 15000);
+        results.push({ message: c.message, files: c.files.length, ok: r.exitCode === 0 });
+      }
+
+      // 4. Push if requested
+      let pushed = false;
+      if (push !== false) {
+        const pushResult = await h.exec("git push", workDir, 30000);
+        pushed = pushResult.exitCode === 0;
+      }
+
+      invalidateBootCache();
+      h.logCall("smart_commit", { command: `${commits.length} commits`, durationMs: Date.now() - start, aiProcessed: true });
+
+      return { content: [{ type: "text" as const, text: JSON.stringify({
+        commits: results,
+        pushed,
+        total: results.length,
+        ok: results.every(r => r.ok),
+      }) }] };
+    }
+  );
+
+  // ── diff ──────────────────────────────────────────────────────────────────
+
+  server.tool(
+    "diff",
+    "Show what changed — git diff with AI summary. One call replaces constructing git diff commands.",
+    {
+      ref: z.string().optional().describe("Diff against this ref (default: unstaged changes). Examples: HEAD~1, main, abc123"),
+      file: z.string().optional().describe("Diff a specific file only"),
+      stat: z.boolean().optional().describe("Show file-level stats only, not full diff (default: false)"),
+      cwd: z.string().optional().describe("Working directory"),
+    },
+    async ({ ref, file, stat, cwd }) => {
+      const start = Date.now();
+      const workDir = cwd ?? process.cwd();
+      let cmd = "git diff";
+      if (ref) cmd += ` ${ref}`;
+      if (stat) cmd += " --stat";
+      if (file) cmd += ` -- ${file}`;
+
+      const result = await h.exec(cmd, workDir, 15000);
+      const output = (result.stdout + result.stderr).trim();
+
+      if (!output) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ clean: true, message: "No changes" }) }] };
+      }
+
+      const processed = await processOutput(cmd, output);
+      h.logCall("diff", { command: cmd, outputTokens: estimateTokens(output), tokensSaved: processed.tokensSaved, durationMs: Date.now() - start, aiProcessed: processed.aiProcessed });
+
+      return { content: [{ type: "text" as const, text: JSON.stringify({
+        summary: processed.summary,
+        lines: output.split("\n").length,
+        tokensSaved: processed.tokensSaved,
+      }) }] };
+    }
+  );
+
+  // ── repo_state ────────────────────────────────────────────────────────────
+
+  server.tool(
+    "repo_state",
+    "Get full repository state in one call — branch, status, staged/unstaged files, recent commits. Replaces the common 3-command pattern: git status + git diff --stat + git log.",
+    {
+      path: z.string().optional().describe("Repo path (default: cwd)"),
+    },
+    async ({ path }) => {
+      const cwd = path ?? process.cwd();
+      const [statusResult, diffResult, logResult] = await Promise.all([
+        h.exec("git status --porcelain", cwd),
+        h.exec("git diff --stat", cwd),
+        h.exec("git log --oneline -12 --decorate", cwd),
+      ]);
+
+      const branchResult = await h.exec("git branch --show-current", cwd);
+
+      const staged: string[] = [];
+      const unstaged: string[] = [];
+      const untracked: string[] = [];
+      for (const line of statusResult.stdout.split("\n").filter(l => l.trim())) {
+        const x = line[0], y = line[1], file = line.slice(3);
+        if (x === "?" && y === "?") untracked.push(file);
+        else if (x !== " " && x !== "?") staged.push(file);
+        if (y !== " " && y !== "?") unstaged.push(file);
+      }
+
+      const commits = logResult.stdout.split("\n").filter(l => l.trim()).map(l => {
+        const match = l.match(/^([a-f0-9]+)\s+(.+)$/);
+        return match ? { hash: match[1], message: match[2] } : { hash: "", message: l };
+      });
+
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify({
+          branch: branchResult.stdout.trim(),
+          dirty: staged.length + unstaged.length + untracked.length > 0,
+          staged, unstaged, untracked,
+          diffSummary: diffResult.stdout.trim() || "no changes",
+          recentCommits: commits,
+        }) }],
+      };
+    }
+  );
+
+  // ── last_commit ───────────────────────────────────────────────────────────
+
+  server.tool(
+    "last_commit",
+    "Get details of the last commit — hash, message, files changed, diff stats. Replaces: git log -1 + git show --stat + git diff HEAD~1.",
+    {
+      path: z.string().optional().describe("Repo path (default: cwd)"),
+    },
+    async ({ path }) => {
+      const cwd = path ?? process.cwd();
+      const [logResult, statResult] = await Promise.all([
+        h.exec("git log -1 --format='%H%n%s%n%an%n%ai'", cwd),
+        h.exec("git show --stat --format='' HEAD", cwd),
+      ]);
+
+      const [hash, message, author, date] = logResult.stdout.split("\n");
+      const filesChanged = statResult.stdout.split("\n").filter(l => l.trim() && !l.includes("changed"));
+
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify({
+          hash: hash?.trim(),
+          message: message?.trim(),
+          author: author?.trim(),
+          date: date?.trim(),
+          filesChanged,
+        }) }],
+      };
+    }
+  );
+
+  // ── git_init ────────────────────────────────────────────────────────────
+
+  server.tool(
+    "git_init",
+    "Initialize a new git repo, optionally with .gitignore and initial commit.",
+    {
+      cwd: z.string().optional().describe("Directory to init (default: cwd)"),
+      gitignore: z.string().optional().describe("Content for .gitignore file"),
+      initialCommit: z.boolean().optional().describe("Create initial commit (default: true)"),
+    },
+    async ({ cwd, gitignore, initialCommit }) => {
+      const workDir = cwd ?? process.cwd();
+      await h.exec("git init", workDir, 5000);
+      if (gitignore) {
+        const { writeFileSync } = await import("fs");
+        const { join } = await import("path");
+        writeFileSync(join(workDir, ".gitignore"), gitignore);
+      }
+      if (initialCommit !== false) {
+        await h.exec("git add -A && git commit -m 'init' --allow-empty", workDir, 10000);
+      }
+      h.logCall("git_init", { command: "git init" });
+      return { content: [{ type: "text" as const, text: JSON.stringify({ initialized: true, cwd: workDir }) }] };
+    }
+  );
+}