@theokit/sdk-tools 0.18.0 → 0.20.0

package/dist/index.d.cts

@@ -6,17 +6,21 @@ import { InteractiveProvider } from '@theokit/sdk/interactive';
 /**
  * `apply_patch` — built-in tool for coding agents.
  *
- * Parses a unified diff string and applies it to the project files.
- * Creates `.bak` backups before modifying each file.
+ * Codex's V4A patch grammar (`*** Begin Patch` … `*** End Patch`): `*** Add/Update/Delete File:`, an
+ * optional `*** Move to:`, and `@@`-anchored `+`/`-`/context hunks matched with a context-tolerant ladder
+ * (exact → rstrip → trim → unicode). See `internal/v4a-patch.ts` for the parser + matcher.
+ *
+ * Applied STRICTLY atomically: the whole patch is planned (every file read + new content computed + path
+ * security-checked) before ANY write. A parse error, context mismatch, or path violation anywhere ⇒ typed
+ * error and ZERO writes (stronger than Codex, which writes file-by-file and can leave partial writes).
  *
  * Return shape (always a JSON string):
  *   - `{ ok: true, files_patched: string[] }`
- *   - `{ ok: false, error: 'parse_error' | 'path_traversal' |
- *        'forbidden_path' | 'patch_failed' }`
+ *   - `{ ok: false, error: 'parse_error' | 'path_traversal' | 'forbidden_path' | 'not_found' | 'patch_failed' }`
  */
 
 interface CreateApplyPatchToolOptions {
-    /** Absolute path to the project root. */
+    /** Absolute path to the project root. Every hunk path is gated against this boundary. */
     projectRoot: string;
 }
 declare function createApplyPatchTool(opts: CreateApplyPatchToolOptions): CustomTool;
@@ -780,6 +784,12 @@ interface CreateSearchTextToolOptions {
     /** Optional injected filesystem (`@theokit/sdk/filesystem`) — when provided, the recursive walk reads
      *  through the backend (surface-agnostic); omitted ⇒ the local `readdir`/`readFile` walk (unchanged). */
     filesystem?: FilesystemProvider;
+    /** M17 — treat `query` as a JavaScript RegExp instead of a literal substring (grep semantics). An
+     *  invalid pattern returns `{ ok: false, error: 'invalid_regex' }`. Default `false` ⇒ literal (unchanged). */
+    regex?: boolean;
+    /** M17 — opt-in "reads-anywhere": honor an ABSOLUTE `path` scope outside `projectRoot` (Codex read-only
+     *  sandbox). Forbidden dirs are still skipped. Default `false` ⇒ absolute scope rejected (unchanged). */
+    allowAbsolute?: boolean;
 }
 declare function createSearchTextTool(opts: CreateSearchTextToolOptions): CustomTool;
 

package/dist/index.d.ts

@@ -6,17 +6,21 @@ import { InteractiveProvider } from '@theokit/sdk/interactive';
 /**
  * `apply_patch` — built-in tool for coding agents.
  *
- * Parses a unified diff string and applies it to the project files.
- * Creates `.bak` backups before modifying each file.
+ * Codex's V4A patch grammar (`*** Begin Patch` … `*** End Patch`): `*** Add/Update/Delete File:`, an
+ * optional `*** Move to:`, and `@@`-anchored `+`/`-`/context hunks matched with a context-tolerant ladder
+ * (exact → rstrip → trim → unicode). See `internal/v4a-patch.ts` for the parser + matcher.
+ *
+ * Applied STRICTLY atomically: the whole patch is planned (every file read + new content computed + path
+ * security-checked) before ANY write. A parse error, context mismatch, or path violation anywhere ⇒ typed
+ * error and ZERO writes (stronger than Codex, which writes file-by-file and can leave partial writes).
  *
  * Return shape (always a JSON string):
  *   - `{ ok: true, files_patched: string[] }`
- *   - `{ ok: false, error: 'parse_error' | 'path_traversal' |
- *        'forbidden_path' | 'patch_failed' }`
+ *   - `{ ok: false, error: 'parse_error' | 'path_traversal' | 'forbidden_path' | 'not_found' | 'patch_failed' }`
  */
 
 interface CreateApplyPatchToolOptions {
-    /** Absolute path to the project root. */
+    /** Absolute path to the project root. Every hunk path is gated against this boundary. */
     projectRoot: string;
 }
 declare function createApplyPatchTool(opts: CreateApplyPatchToolOptions): CustomTool;
@@ -780,6 +784,12 @@ interface CreateSearchTextToolOptions {
     /** Optional injected filesystem (`@theokit/sdk/filesystem`) — when provided, the recursive walk reads
      *  through the backend (surface-agnostic); omitted ⇒ the local `readdir`/`readFile` walk (unchanged). */
     filesystem?: FilesystemProvider;
+    /** M17 — treat `query` as a JavaScript RegExp instead of a literal substring (grep semantics). An
+     *  invalid pattern returns `{ ok: false, error: 'invalid_regex' }`. Default `false` ⇒ literal (unchanged). */
+    regex?: boolean;
+    /** M17 — opt-in "reads-anywhere": honor an ABSOLUTE `path` scope outside `projectRoot` (Codex read-only
+     *  sandbox). Forbidden dirs are still skipped. Default `false` ⇒ absolute scope rejected (unchanged). */
+    allowAbsolute?: boolean;
 }
 declare function createSearchTextTool(opts: CreateSearchTextToolOptions): CustomTool;
 

package/dist/index.js

@@ -1,4 +1,4 @@
-import { readFile, copyFile, mkdir, writeFile, readdir, open, stat } from 'fs/promises';
+import { rm, mkdir, writeFile, readFile, readdir, open, stat, copyFile } from 'fs/promises';
 import { dirname, join, relative, isAbsolute, resolve, sep } from 'path';
 import { Tool, ConfigurationError } from '@theokit/sdk';
 import { z } from 'zod';
@@ -102,129 +102,304 @@ function isForbiddenPath(input) {
   return false;
 }
 
+// src/internal/v4a-patch.ts
+var BEGIN = "*** Begin Patch";
+var END = "*** End Patch";
+var ADD = "*** Add File: ";
+var DELETE = "*** Delete File: ";
+var UPDATE = "*** Update File: ";
+var MOVE = "*** Move to: ";
+var EOF_MARK = "*** End of File";
+var CTX = "@@ ";
+var CTX_EMPTY = "@@";
+var V4APatchError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "V4APatchError";
+  }
+};
+function parseV4A(patch) {
+  const lines = patch.split("\n").map((l) => l.endsWith("\r") ? l.slice(0, -1) : l);
+  let i = 0;
+  while (i < lines.length && lines[i].trim() !== BEGIN) i++;
+  if (i >= lines.length) throw new V4APatchError("Invalid patch: missing '*** Begin Patch'");
+  i++;
+  const hunks = [];
+  while (i < lines.length) {
+    if (lines[i].trim() === END) return hunks;
+    const step = parseNextHunk(lines, i);
+    if (step.hunk) hunks.push(step.hunk);
+    i = step.next;
+  }
+  throw new V4APatchError("Invalid patch: missing '*** End Patch'");
+}
+function parseNextHunk(lines, i) {
+  const line = lines[i];
+  if (line.startsWith(ADD)) {
+    const [hunk, next] = parseAdd(lines, i);
+    return { hunk, next };
+  }
+  if (line.startsWith(DELETE)) {
+    return { hunk: { kind: "delete", path: line.slice(DELETE.length).trim() }, next: i + 1 };
+  }
+  if (line.startsWith(UPDATE)) {
+    const [hunk, next] = parseUpdate(lines, i);
+    return { hunk, next };
+  }
+  if (line.trim() === "") return { next: i + 1 };
+  throw new V4APatchError(`Invalid patch hunk on line ${i + 1}: unexpected '${line}'`);
+}
+function parseAdd(lines, start) {
+  const path = lines[start].slice(ADD.length).trim();
+  let i = start + 1;
+  const body = [];
+  while (i < lines.length && lines[i].startsWith("+")) {
+    body.push(lines[i].slice(1));
+    i++;
+  }
+  const content = body.length > 0 ? `${body.join("\n")}
+` : "";
+  return [{ kind: "add", path, content }, i];
+}
+function parseUpdate(lines, start) {
+  const path = lines[start].slice(UPDATE.length).trim();
+  let i = start + 1;
+  let movePath = null;
+  if (i < lines.length && lines[i].startsWith(MOVE)) {
+    movePath = lines[i].slice(MOVE.length).trim();
+    i++;
+  }
+  const chunks = [];
+  let cur = null;
+  for (; i < lines.length; i++) {
+    const line = lines[i];
+    if (isHunkBoundary(line)) break;
+    cur = feedLine(chunks, cur, line, path, i + 1);
+  }
+  pushChunk(chunks, cur, path);
+  if (chunks.length === 0) throw new V4APatchError(`Update file hunk for '${path}' is empty`);
+  return [{ kind: "update", path, movePath, chunks }, i];
+}
+function isHunkBoundary(line) {
+  return line.trim() === END || line.startsWith(ADD) || line.startsWith(DELETE) || line.startsWith(UPDATE);
+}
+function emptyChunk() {
+  return { context: null, oldLines: [], newLines: [], eof: false };
+}
+function pushChunk(chunks, cur, path) {
+  if (!cur) return;
+  if (cur.oldLines.length === 0 && cur.newLines.length === 0) {
+    throw new V4APatchError(`Update hunk for '${path}' has an empty change block`);
+  }
+  chunks.push(cur);
+}
+function feedLine(chunks, cur, line, path, lineNum) {
+  if (line === CTX_EMPTY || line.startsWith(CTX)) {
+    pushChunk(chunks, cur, path);
+    return {
+      context: line === CTX_EMPTY ? null : line.slice(CTX.length),
+      oldLines: [],
+      newLines: [],
+      eof: false
+    };
+  }
+  if (line.trim() === EOF_MARK) {
+    if (!cur) throw new V4APatchError(`'*** End of File' before any change in '${path}'`);
+    cur.eof = true;
+    return cur;
+  }
+  return appendChangeLine(cur, line, path, lineNum);
+}
+function appendChangeLine(cur, line, path, lineNum) {
+  const c = cur ?? emptyChunk();
+  if (line.startsWith("+")) {
+    c.newLines.push(line.slice(1));
+    return c;
+  }
+  if (line.startsWith("-")) {
+    c.oldLines.push(line.slice(1));
+    return c;
+  }
+  if (line === "" || line.startsWith(" ")) {
+    const content = line === "" ? "" : line.slice(1);
+    c.oldLines.push(content);
+    c.newLines.push(content);
+    return c;
+  }
+  throw new V4APatchError(
+    `Unexpected line in update hunk for '${path}' (line ${lineNum}): every line must start with ' ', '+', or '-': '${line}'`
+  );
+}
+var UNICODE_MAP = {
+  "\u2010": "-",
+  "\u2011": "-",
+  "\u2012": "-",
+  "\u2013": "-",
+  "\u2014": "-",
+  "\u2015": "-",
+  "\u2018": "'",
+  "\u2019": "'",
+  "\u201C": '"',
+  "\u201D": '"',
+  "\xA0": " ",
+  "\u2007": " ",
+  "\u202F": " "
+};
+function normalise(s) {
+  let out = "";
+  for (const ch of s) out += UNICODE_MAP[ch] ?? ch;
+  return out.trim();
+}
+var LADDER = [
+  (a, b) => a === b,
+  (a, b) => a.replace(/\s+$/, "") === b.replace(/\s+$/, ""),
+  (a, b) => a.trim() === b.trim(),
+  (a, b) => normalise(a) === normalise(b)
+];
+function matchesAt(lines, pattern, at, eq) {
+  for (let k = 0; k < pattern.length; k++) {
+    if (!eq(lines[at + k], pattern[k])) return false;
+  }
+  return true;
+}
+function seekSequence(lines, pattern, searchStart, eof) {
+  if (pattern.length === 0) return searchStart;
+  if (pattern.length > lines.length) return null;
+  const start = eof ? Math.max(searchStart, lines.length - pattern.length) : searchStart;
+  for (const eq of LADDER) {
+    for (let i = start; i <= lines.length - pattern.length; i++) {
+      if (matchesAt(lines, pattern, i, eq)) return i;
+    }
+  }
+  return null;
+}
+function applyUpdateChunks(content, path, chunks) {
+  const lines = content.split("\n");
+  const edits = [];
+  let cursor = 0;
+  for (const chunk of chunks) {
+    if (chunk.context !== null) {
+      const ctxAt = seekSequence(lines, [chunk.context], cursor, false);
+      if (ctxAt === null) {
+        throw new V4APatchError(`Failed to find context '${chunk.context}' in ${path}`);
+      }
+      cursor = ctxAt + 1;
+    }
+    const at = seekSequence(lines, chunk.oldLines, cursor, chunk.eof);
+    if (at === null) {
+      throw new V4APatchError(
+        `Failed to find expected lines in ${path}:
+${chunk.oldLines.join("\n")}`
+      );
+    }
+    edits.push({ start: at, oldLen: chunk.oldLines.length, newLines: chunk.newLines });
+    cursor = at + chunk.oldLines.length;
+  }
+  edits.sort((a, b) => b.start - a.start);
+  for (const e of edits) {
+    lines.splice(e.start, e.oldLen, ...e.newLines);
+  }
+  return lines.join("\n");
+}
+
 // src/apply-patch.ts
 function createApplyPatchTool(opts) {
   const { projectRoot } = opts;
   return Tool.create({
     name: "apply_patch",
-    description: "Apply a unified diff patch to project files. Each file in the diff is security-checked against the project root. Creates .bak backups before modifying. Returns { ok, files_patched } or { ok: false, error }.",
+    description: "Apply a Codex-style V4A patch. The patch is `*** Begin Patch` \u2026 `*** End Patch` wrapping one or more hunks: `*** Add File: <path>` (then `+`lines), `*** Delete File: <path>`, or `*** Update File: <path>` (optional `*** Move to: <path>`) with `@@`-anchored `+` (add) / `-` (remove) / ` ` (context) lines. Read a file first so your context/removed lines match. Applied atomically \u2014 a mismatch anywhere aborts the whole patch with zero writes; each path is security-checked. Returns { ok, files_patched } or { ok: false, error }.",
     inputSchema: z.object({
-      patch: z.string().min(1).describe("Unified diff content.")
+      patch: z.string().min(1).describe("V4A patch: *** Begin Patch \u2026 *** End Patch.")
     }),
-    // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: unified diff parsing is inherently complex
-    handler: async ({ patch }) => {
-      const hunks = parsePatch(patch);
-      if (hunks.length === 0) {
-        return JSON.stringify({ ok: false, error: "parse_error", detail: "no file hunks found" });
-      }
-      for (const hunk of hunks) {
-        if (isForbiddenPath(hunk.file)) {
-          return JSON.stringify({ ok: false, error: "forbidden_path", path: hunk.file });
-        }
-        try {
-          const abs = safePathJoin(projectRoot, hunk.file);
-          assertNoSymlinkEscape(abs, projectRoot);
-        } catch (err) {
-          if (err instanceof PathTraversalError || err instanceof ForbiddenPathError) {
-            return JSON.stringify({ ok: false, error: "path_traversal", path: hunk.file });
-          }
-          throw err;
-        }
-      }
-      const patched = [];
-      for (const hunk of hunks) {
-        const absolutePath = safePathJoin(projectRoot, hunk.file);
-        let content;
-        try {
-          content = await readFile(absolutePath, "utf-8");
-        } catch (err) {
-          const e = err;
-          if (e.code === "ENOENT") {
-            content = "";
-          } else {
-            throw err;
-          }
-        }
-        const result = applyHunks(content, hunk.changes);
-        if (result === null) {
-          return JSON.stringify({
-            ok: false,
-            error: "patch_failed",
-            path: hunk.file,
-            detail: "hunk context mismatch"
-          });
-        }
-        if (content !== "") {
-          await copyFile(absolutePath, `${absolutePath}.bak`);
-        }
-        await mkdir(dirname(absolutePath), { recursive: true });
-        await writeFile(absolutePath, result, "utf-8");
-        patched.push(hunk.file);
-      }
-      return JSON.stringify({ ok: true, files_patched: patched });
-    }
+    handler: async ({ patch }) => applyV4APatch(projectRoot, patch)
   });
 }
-function parsePatch(patch) {
-  const lines = patch.split("\n");
-  const hunks = [];
-  let current = null;
-  for (const line of lines) {
-    if (line.startsWith("+++ ")) {
-      const filePath = line.slice(4).replace(/^b\//, "").trim();
-      if (filePath && filePath !== "/dev/null") {
-        current = { file: filePath, changes: [] };
-        hunks.push(current);
-      }
-      continue;
-    }
-    if (line.startsWith("--- ")) continue;
-    if (line.startsWith("@@ ")) continue;
-    if (current === null) continue;
-    if (line.startsWith("+")) {
-      current.changes.push({ type: "add", content: line.slice(1) });
-    } else if (line.startsWith("-")) {
-      current.changes.push({ type: "remove", content: line.slice(1) });
-    } else if (line.startsWith(" ")) {
-      current.changes.push({ type: "context", content: line.slice(1) });
+async function applyV4APatch(projectRoot, patch) {
+  let hunks;
+  try {
+    hunks = parseV4A(patch);
+  } catch (err) {
+    const detail = err instanceof V4APatchError ? err.message : String(err);
+    return JSON.stringify({ ok: false, error: "parse_error", detail });
+  }
+  const plan = await buildPlan(projectRoot, hunks);
+  if ("error" in plan) return plan.error;
+  await executePlan(plan.ops);
+  return JSON.stringify({ ok: true, files_patched: plan.patched });
+}
+async function buildPlan(projectRoot, hunks) {
+  const ops = [];
+  const patched = [];
+  for (const hunk of hunks) {
+    const planned = await planHunk(projectRoot, hunk);
+    if ("error" in planned) return planned;
+    ops.push(...planned.ops);
+    patched.push(hunk.kind === "update" ? hunk.movePath ?? hunk.path : hunk.path);
+  }
+  return { ops, patched };
+}
+async function executePlan(ops) {
+  for (const op of ops) {
+    if ("rm" in op) {
+      await rm(op.rm, { force: true });
+    } else {
+      await mkdir(dirname(op.write.abs), { recursive: true });
+      await writeFile(op.write.abs, op.write.content, "utf-8");
     }
   }
-  return hunks;
 }
-function applyHunks(content, changes) {
-  const originalLines = content.split("\n");
-  const result = [];
-  let origIdx = 0;
-  const firstContext = changes.find((c) => c.type === "context" || c.type === "remove");
-  if (firstContext) {
-    const startIdx = originalLines.indexOf(firstContext.content, origIdx);
-    if (startIdx === -1) return null;
-    for (let i = 0; i < startIdx; i++) {
-      result.push(originalLines[i]);
+async function planHunk(projectRoot, hunk) {
+  const scope = v4aScope(projectRoot, hunk.path);
+  if ("error" in scope) return scope;
+  if (hunk.kind === "add") return { ops: [{ write: { abs: scope.abs, content: hunk.content } }] };
+  if (hunk.kind === "delete") return { ops: [{ rm: scope.abs }] };
+  return planUpdate(projectRoot, hunk, scope.abs);
+}
+async function planUpdate(projectRoot, hunk, abs) {
+  let content;
+  try {
+    content = await readFile(abs, "utf-8");
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return { error: JSON.stringify({ ok: false, error: "not_found", path: hunk.path }) };
     }
-    origIdx = startIdx;
+    throw err;
   }
-  for (const change of changes) {
-    if (change.type === "context") {
-      if (origIdx >= originalLines.length || originalLines[origIdx] !== change.content) {
-        return null;
-      }
-      result.push(change.content);
-      origIdx++;
-    } else if (change.type === "remove") {
-      if (origIdx >= originalLines.length || originalLines[origIdx] !== change.content) {
-        return null;
-      }
-      origIdx++;
-    } else if (change.type === "add") {
-      result.push(change.content);
+  let updated;
+  try {
+    updated = applyUpdateChunks(content, hunk.path, hunk.chunks);
+  } catch (err) {
+    if (err instanceof V4APatchError) {
+      return {
+        error: JSON.stringify({
+          ok: false,
+          error: "patch_failed",
+          path: hunk.path,
+          detail: err.message
+        })
+      };
     }
+    throw err;
   }
-  while (origIdx < originalLines.length) {
-    result.push(originalLines[origIdx]);
-    origIdx++;
+  if (!hunk.movePath) return { ops: [{ write: { abs, content: updated } }] };
+  const dest = v4aScope(projectRoot, hunk.movePath);
+  if ("error" in dest) return dest;
+  return { ops: [{ write: { abs: dest.abs, content: updated } }, { rm: abs }] };
+}
+function v4aScope(projectRoot, file) {
+  if (isForbiddenPath(file)) {
+    return { error: JSON.stringify({ ok: false, error: "forbidden_path", path: file }) };
+  }
+  try {
+    const abs = safePathJoin(projectRoot, file);
+    assertNoSymlinkEscape(abs, projectRoot);
+    return { abs };
+  } catch (err) {
+    if (err instanceof PathTraversalError || err instanceof ForbiddenPathError) {
+      return { error: JSON.stringify({ ok: false, error: "path_traversal", path: file }) };
+    }
+    throw err;
   }
-  return result.join("\n");
 }
 function createSessionArtifactStore(options) {
   const { dir } = options;
@@ -328,7 +503,7 @@ var LINE_MATCH_LADDER = [
   (s) => normalizeUnicode(s).trim()
   // unicode + trim (loosest)
 ];
-function matchesAt(lines, pattern, i, norm) {
+function matchesAt2(lines, pattern, i, norm) {
   for (let p = 0; p < pattern.length; p++) {
     const lineAt = lines[i + p];
     const patAt = pattern[p];
@@ -339,7 +514,7 @@ function matchesAt(lines, pattern, i, norm) {
 function findHits(lines, pattern, norm) {
   const hits = [];
   for (let i = 0; i + pattern.length <= lines.length; i++) {
-    if (matchesAt(lines, pattern, i, norm)) hits.push(i);
+    if (matchesAt2(lines, pattern, i, norm)) hits.push(i);
   }
   return hits;
 }
@@ -1891,27 +2066,36 @@ function createSearchTextTool(opts) {
     projectRoot,
     maxMatches = DEFAULT_MAX_MATCHES,
     maxFileSize = DEFAULT_MAX_FILE_SIZE,
-    filesystem
+    filesystem,
+    regex = false,
+    allowAbsolute = false
   } = 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 Tool.create({
     name: "search_text",
-    description: `Search file CONTENTS for a LITERAL, CASE-SENSITIVE query across the project tree (the query is matched as a substring, not a regex). 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 }.`,
+    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: z.object({
-      query: z.string().min(1).describe("Literal text to search for. Case-sensitive."),
-      path: z.string().optional().describe("Optional project-relative directory to scope the search.")
+      query: regex ? z.string().min(1).describe("A JavaScript regular expression, e.g. 'function\\\\s+main'.") : z.string().min(1).describe("Literal text to search for. Case-sensitive."),
+      path: z.string().optional().describe(
+        "Optional directory to scope the search (project-relative; absolute when allowed)."
+      )
     }),
     handler: async ({ query, path }, ctx) => {
+      const built = buildMatcher(query, regex);
+      if ("error" in built) return built.error;
+      const matcher = built.matcher;
       const state = {
         matches: [],
         totalMatches: 0,
         truncated: false,
-        query,
+        matcher,
         maxMatches,
         maxFileSize,
         projectRoot
       };
       if (filesystem !== void 0) {
-        const scopeRel = resolveScopeRel(path, projectRoot);
+        const scopeRel = resolveScopeRel(path, projectRoot, allowAbsolute);
         if ("error" in scopeRel) return scopeRel.error;
         const backend = await resolveFilesystem(filesystem, ctx ?? {});
         await walkBackend(backend, scopeRel.rel, state, 0);
@@ -1922,7 +2106,7 @@ function createSearchTextTool(opts) {
           totalMatches: state.totalMatches
         });
       }
-      const scope = resolveSearchScope(path, projectRoot);
+      const scope = resolveSearchScope(path, projectRoot, allowAbsolute);
       if ("error" in scope) return scope.error;
       await walk(scope.scopeAbs, state);
       return JSON.stringify({
@@ -1934,8 +2118,20 @@ function createSearchTextTool(opts) {
     }
   });
 }
-function resolveSearchScope(path, projectRoot) {
+function buildMatcher(query, regex) {
+  if (!regex) return { matcher: (line) => line.includes(query) };
+  try {
+    const re = new RegExp(query);
+    return { matcher: (line) => re.test(line) };
+  } catch {
+    return { error: JSON.stringify({ ok: false, error: "invalid_regex", query }) };
+  }
+}
+function resolveSearchScope(path, projectRoot, allowAbsolute) {
   const scopeRel = path === void 0 || path === "" || path === "." ? "." : path;
+  if (allowAbsolute && isAbsolute(scopeRel)) {
+    return { scopeAbs: scopeRel };
+  }
   try {
     const scopeAbs = scopeRel === "." ? projectRoot : safePathJoin(projectRoot, scopeRel);
     assertNoSymlinkEscape(scopeAbs, projectRoot);
@@ -2007,13 +2203,14 @@ async function scanFile(absPath, relPath, state) {
   const lines = buffer.toString("utf-8").split("\n");
   for (let i = 0; i < lines.length; i += 1) {
     const line = lines[i];
-    if (!line.includes(state.query)) continue;
+    if (!state.matcher(line)) continue;
     if (!recordMatch(state, relPath, i + 1, line)) return;
   }
 }
-function resolveScopeRel(path, projectRoot) {
+function resolveScopeRel(path, projectRoot, allowAbsolute) {
   const scopeRel = path === void 0 || path === "" || path === "." ? "" : path;
   if (scopeRel === "") return { rel: "" };
+  if (allowAbsolute && isAbsolute(scopeRel)) return { rel: scopeRel };
   try {
     assertNoSymlinkEscape(safePathJoin(projectRoot, scopeRel), projectRoot);
     return { rel: scopeRel };
@@ -2065,7 +2262,7 @@ async function scanFileBackend(backend, relPath, size, state) {
   const lines = content.split("\n");
   for (let i = 0; i < lines.length; i += 1) {
     const line = lines[i];
-    if (!line.includes(state.query)) continue;
+    if (!state.matcher(line)) continue;
     if (!recordMatch(state, relPath, i + 1, line)) return;
   }
 }