@theokit/sdk-tools 0.20.1 → 0.22.0

package/dist/index.cjs

@@ -4,105 +4,17 @@ var promises = require('fs/promises');
 var path = require('path');
 var sdk = require('@theokit/sdk');
 var zod = require('zod');
-var fs = require('fs');
 var pathSafety = require('@theokit/sdk/path-safety');
 var persistence = require('@theokit/sdk/persistence');
 var filesystem = require('@theokit/sdk/filesystem');
-var child_process = require('child_process');
+var fs = require('fs');
 var sandbox = require('@theokit/sdk/sandbox');
+var child_process = require('child_process');
 var interactive = require('@theokit/sdk/interactive');
 var promises$1 = require('dns/promises');
 var net = require('net');
 
 // src/apply-patch.ts
-var PathTraversalError = class extends sdk.ConfigurationError {
-  name = "PathTraversalError";
-  constructor(input, resolvedPath) {
-    super(`Path traversal attempt: ${input} \u2192 ${resolvedPath}`, {
-      code: "path_traversal"
-    });
-  }
-};
-var ForbiddenPathError = class extends sdk.ConfigurationError {
-  name = "ForbiddenPathError";
-  constructor(path) {
-    super(
-      `Path '${path}' is in the sensitive-file blocklist (.env, .git/, node_modules/, .theo/, lock files)`,
-      {
-        code: "forbidden_path"
-      }
-    );
-  }
-};
-function safePathJoin(base, ...parts) {
-  if (base === "") {
-    throw new Error("safePathJoin: base must be non-empty");
-  }
-  const baseResolved = path.resolve(base);
-  const target = path.resolve(base, ...parts);
-  if (target !== baseResolved && !target.startsWith(baseResolved + path.sep)) {
-    throw new PathTraversalError(parts.join("/"), target);
-  }
-  return target;
-}
-function assertNoSymlinkEscape(path$1, base) {
-  let baseResolved;
-  try {
-    baseResolved = fs.realpathSync(base);
-  } catch {
-    baseResolved = path.resolve(base);
-  }
-  const resolved = realpathOfDeepestExisting(path$1);
-  if (resolved === void 0) return;
-  if (resolved !== baseResolved && !resolved.startsWith(baseResolved + path.sep)) {
-    throw new PathTraversalError(`symlink ${path$1}`, resolved);
-  }
-}
-function realpathOfDeepestExisting(path$1) {
-  try {
-    return fs.realpathSync(path$1);
-  } catch {
-  }
-  try {
-    const stat3 = fs.lstatSync(path$1);
-    if (stat3.isSymbolicLink()) {
-      const target = fs.readlinkSync(path$1);
-      const parentReal = realpathOfDeepestExisting(path.dirname(path$1));
-      const parentBase = parentReal ?? path.dirname(path$1);
-      return path.resolve(parentBase, target);
-    }
-  } catch {
-  }
-  let cursor = path.dirname(path$1);
-  let suffix = path$1.slice(cursor.length);
-  while (cursor !== path.dirname(cursor)) {
-    try {
-      const real = fs.realpathSync(cursor);
-      return path.resolve(real, `.${suffix}`);
-    } catch {
-      suffix = path$1.slice(path.dirname(cursor).length);
-      cursor = path.dirname(cursor);
-    }
-  }
-  return void 0;
-}
-var LOCK_FILES = /* @__PURE__ */ new Set(["pnpm-lock.yaml", "package-lock.json", "yarn.lock", "bun.lockb"]);
-function isForbiddenPath(input) {
-  const normalized = input.replace(/\\/g, "/").replace(/^\.\//, "");
-  if (normalized.length === 0) return false;
-  const segments = normalized.split("/").filter((s) => s.length > 0);
-  if (segments.length === 0) return false;
-  const first = segments[0];
-  if (first === ".env.example") return false;
-  if (first === ".env") return true;
-  if (/^\.env\./.test(first)) return true;
-  if (first === ".git") return true;
-  if (first === "node_modules") return true;
-  if (first === ".theo") return true;
-  const basename = segments[segments.length - 1];
-  if (LOCK_FILES.has(basename)) return true;
-  return false;
-}
 
 // src/internal/v4a-patch.ts
 var BEGIN = "*** Begin Patch";
@@ -446,15 +358,15 @@ function isForbiddenRel(rel) {
 function v4aScope(projectRoot, file) {
   let abs;
   try {
-    abs = safePathJoin(projectRoot, file);
-    assertNoSymlinkEscape(abs, projectRoot);
+    abs = pathSafety.safePathJoin(projectRoot, file);
+    pathSafety.assertNoSymlinkEscape(abs, projectRoot);
   } catch (err) {
-    if (err instanceof PathTraversalError || err instanceof ForbiddenPathError) {
+    if (err instanceof pathSafety.PathTraversalError || err instanceof pathSafety.ForbiddenPathError) {
       return { error: JSON.stringify({ ok: false, error: "path_traversal", path: file }) };
     }
     throw err;
   }
-  if (isForbiddenPath(file) || isForbiddenRel(path.relative(projectRoot, abs))) {
+  if (pathSafety.isForbiddenPath(file) || isForbiddenRel(path.relative(projectRoot, abs))) {
     return { error: JSON.stringify({ ok: false, error: "forbidden_path", path: file }) };
   }
   return { abs };
@@ -665,7 +577,7 @@ async function editViaBackend(filesystem$1, ctx, path, old_string, new_string) {
   return JSON.stringify({ ok: true, replacements: 1 });
 }
 async function editViaLocal(projectRoot, path, old_string, new_string) {
-  const absolutePath = safePathJoin(projectRoot, path);
+  const absolutePath = pathSafety.safePathJoin(projectRoot, path);
   let content;
   try {
     content = await promises.readFile(absolutePath, "utf-8");
@@ -683,14 +595,14 @@ async function editViaLocal(projectRoot, path, old_string, new_string) {
   return JSON.stringify({ ok: true, replacements: 1 });
 }
 function editScopeError(path, projectRoot) {
-  if (isForbiddenPath(path)) {
+  if (pathSafety.isForbiddenPath(path)) {
     return JSON.stringify({ ok: false, error: "forbidden_path", path });
   }
   try {
-    assertNoSymlinkEscape(safePathJoin(projectRoot, path), projectRoot);
+    pathSafety.assertNoSymlinkEscape(pathSafety.safePathJoin(projectRoot, path), projectRoot);
     return null;
   } catch (err) {
-    if (err instanceof PathTraversalError || err instanceof ForbiddenPathError) {
+    if (err instanceof pathSafety.PathTraversalError || err instanceof pathSafety.ForbiddenPathError) {
       return JSON.stringify({ ok: false, error: "path_traversal", path });
     }
     throw err;
@@ -699,8 +611,8 @@ function editScopeError(path, projectRoot) {
 function createEditFileTool(opts) {
   const { projectRoot, filesystem } = opts;
   return sdk.Tool.create({
-    name: "edit_file",
-    description: "Make an exact string replacement in a project-relative file. Replaces the FIRST occurrence of old_string with new_string (a whitespace-normalized fallback is attempted if the exact match fails) and writes a .bak backup first. Read the file first so old_string matches the on-disk text exactly; include enough surrounding context to make it unique \u2014 only the first match is replaced, so a too-short old_string can edit the wrong location. old_string must be non-empty and differ from new_string; to change every occurrence, call edit_file repeatedly. Returns { ok, replacements } or { ok: false, error }.",
+    name: opts.name ?? "edit_file",
+    description: opts.description ?? "Make an exact string replacement in a project-relative file. Replaces the FIRST occurrence of old_string with new_string (a whitespace-normalized fallback is attempted if the exact match fails) and writes a .bak backup first. Read the file first so old_string matches the on-disk text exactly; include enough surrounding context to make it unique \u2014 only the first match is replaced, so a too-short old_string can edit the wrong location. old_string must be non-empty and differ from new_string; to change every occurrence, call edit_file repeatedly. Returns { ok, replacements } or { ok: false, error }.",
     inputSchema: zod.z.object({
       path: zod.z.string().min(1).describe("Project-relative file path."),
       old_string: zod.z.string().min(1).describe("String to find in the file."),
@@ -772,21 +684,6 @@ function formatError(message, code) {
   return `> **Error:** ${prefix}${message}`;
 }
 
-// src/path-scope.ts
-function checkPathScope(path, projectRoot) {
-  if (path === void 0 || path === "") return null;
-  try {
-    const abs = safePathJoin(projectRoot, path);
-    assertNoSymlinkEscape(abs, projectRoot);
-    return null;
-  } catch (err) {
-    if (err instanceof PathTraversalError || err instanceof ForbiddenPathError) {
-      return JSON.stringify({ ok: false, error: "path_traversal", path });
-    }
-    throw err;
-  }
-}
-
 // src/subprocess.ts
 function createSettleGate(timer) {
   let done = false;
@@ -800,25 +697,104 @@ function createSettleGate(timer) {
     }
   };
 }
-function armTimeoutKill(child, timeoutMs, onTimeout, resolve2) {
+function armTimeoutKill(child, timeoutMs, onTimeout, resolve) {
   const timer = setTimeout(() => {
     gate.fire(() => {
       try {
         process.kill(-(child.pid ?? 0), "SIGKILL");
       } catch {
       }
-      resolve2(onTimeout());
+      resolve(onTimeout());
     });
   }, timeoutMs);
   const gate = createSettleGate(timer);
   return gate;
 }
-function attachChildSettlers(child, gate, onClose, onError, resolve2) {
+function attachChildSettlers(child, gate, onClose, onError, resolve) {
   child.on("close", (code) => {
-    gate.fire(() => resolve2(onClose(code)));
+    gate.fire(() => resolve(onClose(code)));
   });
   child.on("error", (err) => {
-    gate.fire(() => resolve2(onError(err)));
+    gate.fire(() => resolve(onError(err)));
+  });
+}
+
+// src/internal/git-exec.ts
+function formatGitResult(result, timeoutMs) {
+  if (result.kind === "timeout") {
+    return JSON.stringify({ ok: false, error: "timeout", timeoutMs });
+  }
+  if (result.kind === "error") {
+    return JSON.stringify({ ok: false, error: "git_failed", stderr: result.stderr });
+  }
+  return JSON.stringify({ ok: true, diff: result.stdout, truncated: result.truncated });
+}
+function runGitProcess(cwd, args, timeoutMs, maxStdoutBytes) {
+  return new Promise((resolve) => {
+    const child = child_process.spawn("git", args, { cwd, detached: true, stdio: ["ignore", "pipe", "pipe"] });
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    let stdoutBytes = 0;
+    let truncated = false;
+    const gate = armTimeoutKill(
+      child,
+      timeoutMs,
+      () => ({ kind: "timeout" }),
+      resolve
+    );
+    child.stdout.on("data", (chunk) => {
+      if (gate.settled()) return;
+      if (stdoutBytes >= maxStdoutBytes) {
+        truncated = true;
+        return;
+      }
+      const remaining = maxStdoutBytes - stdoutBytes;
+      if (chunk.length > remaining) {
+        stdoutChunks.push(chunk.subarray(0, remaining));
+        stdoutBytes = maxStdoutBytes;
+        truncated = true;
+      } else {
+        stdoutChunks.push(chunk);
+        stdoutBytes += chunk.length;
+      }
+    });
+    child.stderr.on("data", (chunk) => {
+      stderrChunks.push(chunk);
+    });
+    attachChildSettlers(
+      child,
+      gate,
+      (code) => {
+        const stdout = Buffer.concat(stdoutChunks).toString("utf-8");
+        const stderr = Buffer.concat(stderrChunks).toString("utf-8");
+        return code === 0 ? { kind: "ok", stdout, truncated } : { kind: "error", stderr };
+      },
+      (err) => ({ kind: "error", stderr: err.message }),
+      resolve
+    );
+  });
+}
+
+// src/path-scope.ts
+function checkPathScope(path, projectRoot) {
+  if (path === void 0 || path === "") return null;
+  try {
+    const abs = pathSafety.safePathJoin(projectRoot, path);
+    pathSafety.assertNoSymlinkEscape(abs, projectRoot);
+    return null;
+  } catch (err) {
+    if (err instanceof pathSafety.PathTraversalError || err instanceof pathSafety.ForbiddenPathError) {
+      return JSON.stringify({ ok: false, error: "path_traversal", path });
+    }
+    throw err;
+  }
+}
+var SEGMENTOS_SENSIVEIS = /* @__PURE__ */ new Set([".env", ".git", "node_modules", ".theo"]);
+function ehProibidoEmQualquerProfundidade(path) {
+  const segs = path.replace(/\\/g, "/").split("/").filter(Boolean);
+  return segs.some((s) => {
+    if (s === ".env.example") return false;
+    return SEGMENTOS_SENSIVEIS.has(s) || /^\.env\./.test(s);
   });
 }
 
@@ -875,58 +851,25 @@ function buildDiffArgs(cached, path) {
   if (path !== void 0 && path !== "") args.push("--", path);
   return args;
 }
-function formatGitResult(result, timeoutMs) {
-  if (result.kind === "timeout") {
-    return JSON.stringify({ ok: false, error: "timeout", timeoutMs });
-  }
-  if (result.kind === "error") {
-    return JSON.stringify({ ok: false, error: "git_failed", stderr: result.stderr });
-  }
-  return JSON.stringify({ ok: true, diff: result.stdout, truncated: result.truncated });
-}
-function runGitProcess(cwd, args, timeoutMs, maxStdoutBytes) {
-  return new Promise((resolve2) => {
-    const child = child_process.spawn("git", args, { cwd, detached: true, stdio: ["ignore", "pipe", "pipe"] });
-    const stdoutChunks = [];
-    const stderrChunks = [];
-    let stdoutBytes = 0;
-    let truncated = false;
-    const gate = armTimeoutKill(
-      child,
-      timeoutMs,
-      () => ({ kind: "timeout" }),
-      resolve2
-    );
-    child.stdout.on("data", (chunk) => {
-      if (gate.settled()) return;
-      if (stdoutBytes >= maxStdoutBytes) {
-        truncated = true;
-        return;
-      }
-      const remaining = maxStdoutBytes - stdoutBytes;
-      if (chunk.length > remaining) {
-        stdoutChunks.push(chunk.subarray(0, remaining));
-        stdoutBytes = maxStdoutBytes;
-        truncated = true;
-      } else {
-        stdoutChunks.push(chunk);
-        stdoutBytes += chunk.length;
+function createGitStatusTool(opts) {
+  const { projectRoot, timeoutMs = 3e4, maxStdoutBytes = 5 * 1024 * 1024 } = opts;
+  return sdk.Tool.create({
+    name: opts.name ?? "git_status",
+    description: opts.description ?? "Show the working-tree status in porcelain format: staged, unstaged and untracked paths, one per line with a two-character status code. Use before committing, or to see what changed without reading the full diff. Optional 'path' scopes the report to a subdirectory.",
+    inputSchema: zod.z.object({
+      path: zod.z.string().optional().describe("Optional project-relative path to scope the status report.")
+    }),
+    handler: async ({ path: path$1 }) => {
+      if (!fs.existsSync(path.join(projectRoot, ".git"))) {
+        return JSON.stringify({ ok: false, error: "not_a_repo" });
       }
-    });
-    child.stderr.on("data", (chunk) => {
-      stderrChunks.push(chunk);
-    });
-    attachChildSettlers(
-      child,
-      gate,
-      (code) => {
-        const stdout = Buffer.concat(stdoutChunks).toString("utf-8");
-        const stderr = Buffer.concat(stderrChunks).toString("utf-8");
-        return code === 0 ? { kind: "ok", stdout, truncated } : { kind: "error", stderr };
-      },
-      (err) => ({ kind: "error", stderr: err.message }),
-      resolve2
-    );
+      const scopeCheck = checkPathScope(path$1, projectRoot);
+      if (scopeCheck !== null) return scopeCheck;
+      const args = ["status", "--porcelain"];
+      if (path$1 !== void 0 && path$1 !== "") args.push("--", path$1);
+      const result = await runGitProcess(projectRoot, args, timeoutMs, maxStdoutBytes);
+      return formatGitResult(result, timeoutMs);
+    }
   });
 }
 var DEFAULT_EXCLUDES = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", ".theo"]);
@@ -951,7 +894,7 @@ function createGlobTool(opts) {
         await walkDirBackend(backend, searchRel, searchRel, regex, found, 0);
         return JSON.stringify({ ok: true, files: found.sort(), count: found.length });
       }
-      const searchRoot = cwd ? safePathJoin(projectRoot, cwd) : projectRoot;
+      const searchRoot = cwd ? pathSafety.safePathJoin(projectRoot, cwd) : projectRoot;
       const files = [];
       await walkDir(searchRoot, searchRoot, regex, files);
       const relativePaths = files.map((f) => path.relative(projectRoot, f)).sort();
@@ -962,10 +905,10 @@ function createGlobTool(opts) {
 function globScopeError(cwd, projectRoot) {
   if (!cwd) return null;
   try {
-    assertNoSymlinkEscape(safePathJoin(projectRoot, cwd), projectRoot);
+    pathSafety.assertNoSymlinkEscape(pathSafety.safePathJoin(projectRoot, cwd), projectRoot);
     return null;
   } catch (err) {
-    if (err instanceof PathTraversalError || err instanceof ForbiddenPathError) {
+    if (err instanceof pathSafety.PathTraversalError || err instanceof pathSafety.ForbiddenPathError) {
       return JSON.stringify({ ok: false, error: "path_traversal", path: cwd });
     }
     throw err;
@@ -1598,15 +1541,17 @@ var DEFAULT_MAX_ENTRIES = 500;
 function createListDirTool(opts) {
   const { projectRoot, max = DEFAULT_MAX_ENTRIES, filesystem: filesystem$1 } = opts;
   return sdk.Tool.create({
-    name: "list_dir",
-    description: `Return the direct entries of a project-relative directory. Refuses paths outside the project root or in the sensitive-file blocklist (.env, .git/, node_modules/, .theo/, lock files). Caps at ${String(max)} entries by default; result carries truncated + totalCount.`,
+    name: opts.name ?? "list_dir",
+    description: opts.description ?? `Return the direct entries of a project-relative directory. Refuses paths outside the project root or in the sensitive-file blocklist (.env, .git/, node_modules/, .theo/, lock files). Caps at ${String(max)} entries by default; result carries truncated + totalCount.`,
     inputSchema: zod.z.object({
       path: zod.z.string().min(1).describe("Project-relative directory path. Use '.' for root.")
     }),
     handler: async ({ path }, ctx) => {
       const relative3 = path === "" || path === "." ? "." : path;
-      if (relative3 !== "." && isForbiddenPath(relative3)) {
-        return JSON.stringify({ ok: false, error: "forbidden_path", path });
+      const veredito = decidirEscopo(relative3, path, opts.allowAbsolute === true);
+      if (veredito.erro !== void 0) return veredito.erro;
+      if (veredito.raizAbsoluta !== void 0) {
+        return listViaLocalFs(veredito.raizAbsoluta, ".", path, max);
       }
       if (filesystem$1) {
         const backend = await filesystem.resolveFilesystem(filesystem$1, ctx ?? {});
@@ -1616,6 +1561,16 @@ function createListDirTool(opts) {
     }
   });
 }
+function decidirEscopo(relative3, original, allowAbsolute) {
+  const recusa = (error) => ({
+    erro: JSON.stringify({ ok: false, error, path: original })
+  });
+  if (relative3 !== "." && pathSafety.isForbiddenPath(relative3)) return recusa("forbidden_path");
+  if (!path.isAbsolute(relative3)) return {};
+  if (!allowAbsolute) return recusa("path_traversal");
+  if (ehProibidoEmQualquerProfundidade(relative3)) return recusa("forbidden_path");
+  return { raizAbsoluta: relative3 };
+}
 async function listViaLocalFs(projectRoot, relative3, originalPath, max) {
   const boundary = resolveDirBoundary(relative3, projectRoot, originalPath);
   if ("error" in boundary) return boundary.error;
@@ -1653,11 +1608,11 @@ async function listViaBackend(backend, relative3, originalPath, max) {
 }
 function resolveDirBoundary(relative3, projectRoot, originalPath) {
   try {
-    const absolutePath = relative3 === "." ? projectRoot : safePathJoin(projectRoot, relative3);
-    assertNoSymlinkEscape(absolutePath, projectRoot);
+    const absolutePath = relative3 === "." ? projectRoot : pathSafety.safePathJoin(projectRoot, relative3);
+    pathSafety.assertNoSymlinkEscape(absolutePath, projectRoot);
     return { absolutePath };
   } catch (err) {
-    if (err instanceof PathTraversalError || err instanceof ForbiddenPathError) {
+    if (err instanceof pathSafety.PathTraversalError || err instanceof pathSafety.ForbiddenPathError) {
       return { error: JSON.stringify({ ok: false, error: "path_traversal", path: originalPath }) };
     }
     throw err;
@@ -1776,6 +1731,11 @@ function createPlanModeTool(options) {
 }
 
 // src/question.ts
+function askerDoContexto(context) {
+  if (typeof context !== "object" || context === null) return void 0;
+  const candidato = context.askUser;
+  return typeof candidato === "function" ? candidato : void 0;
+}
 function createQuestionTool(opts) {
   const timeoutMs = opts.timeoutMs ?? 3e5;
   return {
@@ -1788,12 +1748,20 @@ function createQuestionTool(opts) {
       },
       required: ["question"]
     },
-    handler: async (input) => {
+    handler: async (input, ctx) => {
+      const askUser = askerDoContexto(ctx?.context) ?? opts.askUser;
+      if (askUser === void 0) {
+        return JSON.stringify({
+          ok: false,
+          error: "no_asker",
+          message: "No asker available: pass `askUser` to createQuestionTool, or provide `context.askUser` via SendOptions.context."
+        });
+      }
       const timeout = new Promise((_, reject) => {
         setTimeout(() => reject(new Error("timeout")), timeoutMs);
       });
       try {
-        const answer = await Promise.race([opts.askUser(input.question), timeout]);
+        const answer = await Promise.race([askUser(input.question), timeout]);
         return JSON.stringify({ ok: true, answer });
       } catch (err) {
         if (err instanceof Error && err.message === "timeout") {
@@ -1819,7 +1787,7 @@ function isForbiddenAtAnyDepth(path) {
   });
 }
 function forbiddenReadError(path$1, allowAbsolute) {
-  if (isForbiddenPath(path$1)) {
+  if (pathSafety.isForbiddenPath(path$1)) {
     return JSON.stringify({ ok: false, error: "forbidden_path", path: path$1 });
   }
   if (allowAbsolute && path.isAbsolute(path$1) && isForbiddenAtAnyDepth(path$1)) {
@@ -1906,11 +1874,11 @@ function resolveBoundary(path$1, projectRoot, allowAbsolute) {
     return { absolutePath: path$1 };
   }
   try {
-    const absolutePath = safePathJoin(projectRoot, path$1);
-    assertNoSymlinkEscape(absolutePath, projectRoot);
+    const absolutePath = pathSafety.safePathJoin(projectRoot, path$1);
+    pathSafety.assertNoSymlinkEscape(absolutePath, projectRoot);
     return { absolutePath };
   } catch (err) {
-    if (err instanceof PathTraversalError || err instanceof ForbiddenPathError) {
+    if (err instanceof pathSafety.PathTraversalError || err instanceof pathSafety.ForbiddenPathError) {
       return { error: JSON.stringify({ ok: false, error: "path_traversal", path: path$1 }) };
     }
     throw err;
@@ -2032,7 +2000,7 @@ function createRunVitestTool(opts) {
   });
 }
 function validateVitestScope(path, projectRoot) {
-  if (path !== void 0 && path !== "" && isForbiddenPath(path)) {
+  if (path !== void 0 && path !== "" && pathSafety.isForbiddenPath(path)) {
     return JSON.stringify({ ok: false, error: "forbidden_path", path });
   }
   return checkPathScope(path, projectRoot);
@@ -2078,7 +2046,7 @@ function appendCapped(chunks, chunk, current, cap) {
   return current + chunk.length;
 }
 function runProcess(cwd, command, args, timeoutMs, maxStdoutBytes) {
-  return new Promise((resolve2) => {
+  return new Promise((resolve) => {
     const child = child_process.spawn(command, args, {
       cwd,
       detached: true,
@@ -2091,7 +2059,7 @@ function runProcess(cwd, command, args, timeoutMs, maxStdoutBytes) {
       child,
       timeoutMs,
       () => ({ kind: "timeout" }),
-      resolve2
+      resolve
     );
     child.stdout.on("data", (chunk) => {
       if (gate.settled()) return;
@@ -2110,7 +2078,7 @@ function runProcess(cwd, command, args, timeoutMs, maxStdoutBytes) {
         exitCode: code ?? 0
       }),
       (err) => ({ kind: "spawn_error", message: err.message }),
-      resolve2
+      resolve
     );
   });
 }
@@ -2131,8 +2099,8 @@ function createSearchTextTool(opts) {
   const queryKind = regex ? "a JavaScript REGULAR EXPRESSION" : "LITERAL, CASE-SENSITIVE text";
   const queryMatch = regex ? "matched as a regex" : "matched as a substring, not a regex";
   return sdk.Tool.create({
-    name: "search_text",
-    description: `Search file CONTENTS for ${queryKind} across the project tree (the query is ${queryMatch}). Use search_text when you know the content; use glob_files when you know the filename shape; use read_file when you know the exact path. Skips sensitive dirs (.env/.git/node_modules/.theo), binary files, and files over 1 MB; 'path' scopes the search to a subdirectory. Returns up to ${String(maxMatches)} matches as { file, line, preview } \u2014 cite locations to the user as file:line. Returns { ok, matches } or { ok: false, error }.`,
+    name: opts.name ?? "search_text",
+    description: opts.description ?? `Search file CONTENTS for ${queryKind} across the project tree (the query is ${queryMatch}). Use search_text when you know the content; use glob_files when you know the filename shape; use read_file when you know the exact path. Skips sensitive dirs (.env/.git/node_modules/.theo), binary files, and files over 1 MB; 'path' scopes the search to a subdirectory. Returns up to ${String(maxMatches)} matches as { file, line, preview } \u2014 cite locations to the user as file:line. Returns { ok, matches } or { ok: false, error }.`,
     inputSchema: zod.z.object({
       query: regex ? zod.z.string().min(1).describe("A JavaScript regular expression, e.g. 'function\\\\s+main'.") : zod.z.string().min(1).describe("Literal text to search for. Case-sensitive."),
       path: zod.z.string().optional().describe(
@@ -2191,11 +2159,11 @@ function resolveSearchScope(path$1, projectRoot, allowAbsolute) {
     return { scopeAbs: scopeRel };
   }
   try {
-    const scopeAbs = scopeRel === "." ? projectRoot : safePathJoin(projectRoot, scopeRel);
-    assertNoSymlinkEscape(scopeAbs, projectRoot);
+    const scopeAbs = scopeRel === "." ? projectRoot : pathSafety.safePathJoin(projectRoot, scopeRel);
+    pathSafety.assertNoSymlinkEscape(scopeAbs, projectRoot);
     return { scopeAbs };
   } catch (err) {
-    if (err instanceof PathTraversalError || err instanceof ForbiddenPathError) {
+    if (err instanceof pathSafety.PathTraversalError || err instanceof pathSafety.ForbiddenPathError) {
       return { error: JSON.stringify({ ok: false, error: "path_traversal", path: path$1 }) };
     }
     throw err;
@@ -2204,7 +2172,7 @@ function resolveSearchScope(path$1, projectRoot, allowAbsolute) {
 async function handleEntry(entry, absDir, state) {
   const entryAbs = path.join(absDir, entry.name);
   const entryRel = path.relative(state.projectRoot, entryAbs);
-  if (isForbiddenPath(entryRel)) return;
+  if (pathSafety.isForbiddenPath(entryRel)) return;
   if (entry.isDirectory()) {
     await walk(entryAbs, state);
     return;
@@ -2270,10 +2238,10 @@ function resolveScopeRel(path$1, projectRoot, allowAbsolute) {
   if (scopeRel === "") return { rel: "" };
   if (allowAbsolute && path.isAbsolute(scopeRel)) return { rel: scopeRel };
   try {
-    assertNoSymlinkEscape(safePathJoin(projectRoot, scopeRel), projectRoot);
+    pathSafety.assertNoSymlinkEscape(pathSafety.safePathJoin(projectRoot, scopeRel), projectRoot);
     return { rel: scopeRel };
   } catch (err) {
-    if (err instanceof PathTraversalError || err instanceof ForbiddenPathError) {
+    if (err instanceof pathSafety.PathTraversalError || err instanceof pathSafety.ForbiddenPathError) {
       return { error: JSON.stringify({ ok: false, error: "path_traversal", path: path$1 }) };
     }
     throw err;
@@ -2295,7 +2263,7 @@ async function walkBackend(backend, dirRel, state, depth) {
 }
 async function handleBackendEntry(backend, dirRel, name, state, depth) {
   const entryRel = dirRel === "" ? name : `${dirRel}/${name}`;
-  if (isForbiddenPath(entryRel)) return;
+  if (pathSafety.isForbiddenPath(entryRel)) return;
   let st;
   try {
     st = await backend.stat(entryRel);
@@ -2340,8 +2308,8 @@ function createShellTool(opts) {
     sandbox
   } = opts;
   return sdk.Tool.create({
-    name: "shell_exec",
-    description: "Execute a shell command in the project directory. Use this for terminal operations \u2014 running tests, git, package managers, build tools. Do NOT use it for file operations (reading, writing, editing, finding files): prefer the specialized read_file/write_file/edit_file/glob_files/search_text tools, which are path-checked and safer. Only commit, push, or change git state when the user explicitly asks. timeout_ms defaults to 30000 (max 300000); stdout/stderr are capped (~5 MB). Returns { ok, stdout, stderr, exit_code } or { ok: false, error }.",
+    name: opts.name ?? "shell_exec",
+    description: opts.description ?? "Execute a shell command in the project directory. Use this for terminal operations \u2014 running tests, git, package managers, build tools. Do NOT use it for file operations (reading, writing, editing, finding files): prefer the specialized read_file/write_file/edit_file/glob_files/search_text tools, which are path-checked and safer. Only commit, push, or change git state when the user explicitly asks. timeout_ms defaults to 30000 (max 300000); stdout/stderr are capped (~5 MB). Returns { ok, stdout, stderr, exit_code } or { ok: false, error }.",
     inputSchema: zod.z.object({
       command: zod.z.string().min(1).describe("Shell command to execute."),
       timeout_ms: zod.z.number().int().positive().optional().describe("Timeout in milliseconds (default 30000, max 300000).")
@@ -2361,7 +2329,7 @@ function createShellTool(opts) {
   });
 }
 function runShell(cwd, command, timeoutMs) {
-  return new Promise((resolve2) => {
+  return new Promise((resolve) => {
     const child = child_process.spawn("/bin/sh", ["-c", command], {
       cwd,
       detached: true,
@@ -2375,7 +2343,7 @@ function runShell(cwd, command, timeoutMs) {
       child,
       timeoutMs,
       () => ({ kind: "timeout" }),
-      (result) => resolve2(formatResult(result, timeoutMs))
+      (result) => resolve(formatResult(result, timeoutMs))
     );
     child.stdout.on("data", (chunk) => {
       if (gate.settled()) return;
@@ -2413,7 +2381,7 @@ function runShell(cwd, command, timeoutMs) {
         exitCode: code
       }),
       (err) => ({ kind: "error", message: err.message }),
-      (result) => resolve2(formatResult(result, timeoutMs))
+      (result) => resolve(formatResult(result, timeoutMs))
     );
   });
 }
@@ -2795,7 +2763,7 @@ function createWriteFileTool(opts) {
       content: zod.z.string().describe("UTF-8 content to write.")
     }),
     handler: async ({ path, content }, ctx) => {
-      if (isForbiddenPath(path)) {
+      if (pathSafety.isForbiddenPath(path)) {
         return JSON.stringify({ ok: false, error: "forbidden_path", path });
       }
       if (filesystem$1) {
@@ -2817,10 +2785,10 @@ function readBeforeWriteError(guard, path, currentMtimeMs) {
 async function writeViaLocalFs(projectRoot, path$1, content, guard) {
   let absolutePath;
   try {
-    absolutePath = safePathJoin(projectRoot, path$1);
-    assertNoSymlinkEscape(absolutePath, projectRoot);
+    absolutePath = pathSafety.safePathJoin(projectRoot, path$1);
+    pathSafety.assertNoSymlinkEscape(absolutePath, projectRoot);
   } catch (err) {
-    if (err instanceof PathTraversalError || err instanceof ForbiddenPathError) {
+    if (err instanceof pathSafety.PathTraversalError || err instanceof pathSafety.ForbiddenPathError) {
       return JSON.stringify({ ok: false, error: "path_traversal", path: path$1 });
     }
     throw err;
@@ -2924,6 +2892,7 @@ exports.createCurrentTimeTool = createCurrentTimeTool;
 exports.createEditFileTool = createEditFileTool;
 exports.createGenericHttpSearchAdapter = createGenericHttpSearchAdapter;
 exports.createGitDiffTool = createGitDiffTool;
+exports.createGitStatusTool = createGitStatusTool;
 exports.createGlobTool = createGlobTool;
 exports.createInteractiveShellTool = createInteractiveShellTool;
 exports.createListDirTool = createListDirTool;