@theokit/sdk-tools 0.8.0 → 0.9.1

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import { CustomTool, ConfigurationError } from '@theokit/sdk';
+import { FilesystemProvider } from '@theokit/sdk/filesystem';
 
 /**
  * `apply_patch` — built-in tool for coding agents.
@@ -423,6 +424,13 @@ interface CreateListDirToolOptions {
     projectRoot: string;
     /** Maximum number of entries returned per call. Default 500. */
     max?: number;
+    /**
+     * SE31 — optional pluggable filesystem backend (`@theokit/sdk/filesystem`), or
+     * a per-request resolver. When provided, listings route through the backend
+     * (its own boundary + `basePath`) instead of the local `projectRoot`; omitted
+     * ⇒ identical current behavior (multi-tenant / per-request roots).
+     */
+    filesystem?: FilesystemProvider;
 }
 declare function createListDirTool(opts: CreateListDirToolOptions): CustomTool;
 
@@ -504,6 +512,25 @@ interface QuestionTool {
 }
 declare function createQuestionTool(opts: QuestionToolOptions): QuestionTool;
 
+/**
+ * `ReadTracker` — SE32 read-before-write safety.
+ *
+ * A per-run map of `path → mtimeMs` recorded whenever the read tool reads a
+ * file. The write tool (with `requireReadBeforeWrite` on) consults it before an
+ * overwrite: a file that was never read, or that changed on disk since it was
+ * read, is refused instead of silently clobbered. Scope one tracker per run /
+ * session — it is deliberately NOT a global singleton (no cross-run leak).
+ *
+ * @public
+ */
+declare class ReadTracker {
+    private readonly seen;
+    /** Record the mtime observed when `path` was read. */
+    record(path: string, mtimeMs: number): void;
+    /** The mtime last recorded for `path`, or `undefined` if never read. */
+    expected(path: string): number | undefined;
+}
+
 /**
  * `read_file` — built-in tool for coding agents.
  *
@@ -533,6 +560,19 @@ declare function createQuestionTool(opts: QuestionToolOptions): QuestionTool;
 interface CreateReadFileToolOptions {
     /** Absolute path to the project root. Every read is gated against this boundary. */
     projectRoot: string;
+    /**
+     * SE32 — optional read-before-write tracker. When provided, a successful read
+     * records the file's mtime so a paired `write_file` (with
+     * `requireReadBeforeWrite`) can refuse a blind or stale overwrite.
+     */
+    readTracker?: ReadTracker;
+    /**
+     * SE31 — optional pluggable filesystem backend (`@theokit/sdk/filesystem`), or
+     * a per-request resolver. When provided, reads route through the backend (its
+     * own boundary + `basePath`) instead of the local `projectRoot`; omitted ⇒
+     * identical current behavior (multi-tenant / per-request roots).
+     */
+    filesystem?: FilesystemProvider;
 }
 declare function createReadFileTool(opts: CreateReadFileToolOptions): CustomTool;
 
@@ -862,10 +902,32 @@ declare function createGenericHttpSearchAdapter(opts?: CreateGenericHttpSearchAd
  *        'binary_file' }` on refusal
  */
 
+/** The run-scoped context a `defineTool` handler receives as its 2nd argument. */
+type WriteToolContext = {
+    signal?: AbortSignal;
+    context?: unknown;
+};
 interface CreateWriteFileToolOptions {
     /** Absolute path to the project root. Every write is gated against this boundary. */
     projectRoot: string;
+    /**
+     * SE31 — optional pluggable filesystem backend (`@theokit/sdk/filesystem`), or
+     * a per-request resolver `(ctx) => FilesystemBackend`. When provided, writes
+     * route through it (its own boundary + `readOnly` + per-request root) instead
+     * of the local project fs. Omitted ⇒ identical current behavior (local
+     * `projectRoot`). The `.env`/`.git` policy still applies (storage-independent).
+     */
+    filesystem?: FilesystemProvider<WriteToolContext>;
+    /**
+     * SE32 — when true (and a {@link ReadTracker} is supplied), refuse to
+     * overwrite an existing file that was not read first, or that changed on disk
+     * since it was read (`read_required` / `stale_file`). A NEW file writes
+     * freely. Default OFF (unchanged behavior).
+     */
+    requireReadBeforeWrite?: boolean;
+    /** SE32 — the per-run tracker populated by the paired `read_file` tool. */
+    readTracker?: ReadTracker;
 }
 declare function createWriteFileTool(opts: CreateWriteFileToolOptions): CustomTool;
 
-export { CatastrophicCommandError, type CommandPolicy, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGlobToolOptions, type CreateListDirToolOptions, type CreateReadFileToolOptions, type CreateRunVitestToolOptions, type CreateSearchTextToolOptions, type CreateShellToolOptions, type CreateWebFetchToolOptions, type CreateWebSearchToolOptions, type CreateWriteFileToolOptions, DEFAULT_TOOL_GUIDANCE, type EnvContextOptions, type PlanModeTool, type PlanModeToolOptions, type PlanModeToolWithStore, type PlanNode, type QuestionTool, type QuestionToolOptions, RedirectBlockedError, type RepoMapOptions, type ResolveAndScreenOptions, type ScreenedFetchOptions, type SessionArtifactStore, type SessionArtifactStoreOptions, SsrfBlockedError, type TodoItem, type TodolistTool, type ToolGuidanceMap, type TruncationOptions, type TruncationResult, type VitestSummary, type WebSearchCallback, type WebSearchResult, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGlobTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withShellExitGuidance, withToolResultGuidance };
+export { CatastrophicCommandError, type CommandPolicy, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGlobToolOptions, type CreateListDirToolOptions, type CreateReadFileToolOptions, type CreateRunVitestToolOptions, type CreateSearchTextToolOptions, type CreateShellToolOptions, type CreateWebFetchToolOptions, type CreateWebSearchToolOptions, type CreateWriteFileToolOptions, DEFAULT_TOOL_GUIDANCE, type EnvContextOptions, type PlanModeTool, type PlanModeToolOptions, type PlanModeToolWithStore, type PlanNode, type QuestionTool, type QuestionToolOptions, ReadTracker, RedirectBlockedError, type RepoMapOptions, type ResolveAndScreenOptions, type ScreenedFetchOptions, type SessionArtifactStore, type SessionArtifactStoreOptions, SsrfBlockedError, type TodoItem, type TodolistTool, type ToolGuidanceMap, type TruncationOptions, type TruncationResult, type VitestSummary, type WebSearchCallback, type WebSearchResult, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGlobTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withShellExitGuidance, withToolResultGuidance };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { CustomTool, ConfigurationError } from '@theokit/sdk';
+import { FilesystemProvider } from '@theokit/sdk/filesystem';
 
 /**
  * `apply_patch` — built-in tool for coding agents.
@@ -423,6 +424,13 @@ interface CreateListDirToolOptions {
     projectRoot: string;
     /** Maximum number of entries returned per call. Default 500. */
     max?: number;
+    /**
+     * SE31 — optional pluggable filesystem backend (`@theokit/sdk/filesystem`), or
+     * a per-request resolver. When provided, listings route through the backend
+     * (its own boundary + `basePath`) instead of the local `projectRoot`; omitted
+     * ⇒ identical current behavior (multi-tenant / per-request roots).
+     */
+    filesystem?: FilesystemProvider;
 }
 declare function createListDirTool(opts: CreateListDirToolOptions): CustomTool;
 
@@ -504,6 +512,25 @@ interface QuestionTool {
 }
 declare function createQuestionTool(opts: QuestionToolOptions): QuestionTool;
 
+/**
+ * `ReadTracker` — SE32 read-before-write safety.
+ *
+ * A per-run map of `path → mtimeMs` recorded whenever the read tool reads a
+ * file. The write tool (with `requireReadBeforeWrite` on) consults it before an
+ * overwrite: a file that was never read, or that changed on disk since it was
+ * read, is refused instead of silently clobbered. Scope one tracker per run /
+ * session — it is deliberately NOT a global singleton (no cross-run leak).
+ *
+ * @public
+ */
+declare class ReadTracker {
+    private readonly seen;
+    /** Record the mtime observed when `path` was read. */
+    record(path: string, mtimeMs: number): void;
+    /** The mtime last recorded for `path`, or `undefined` if never read. */
+    expected(path: string): number | undefined;
+}
+
 /**
  * `read_file` — built-in tool for coding agents.
  *
@@ -533,6 +560,19 @@ declare function createQuestionTool(opts: QuestionToolOptions): QuestionTool;
 interface CreateReadFileToolOptions {
     /** Absolute path to the project root. Every read is gated against this boundary. */
     projectRoot: string;
+    /**
+     * SE32 — optional read-before-write tracker. When provided, a successful read
+     * records the file's mtime so a paired `write_file` (with
+     * `requireReadBeforeWrite`) can refuse a blind or stale overwrite.
+     */
+    readTracker?: ReadTracker;
+    /**
+     * SE31 — optional pluggable filesystem backend (`@theokit/sdk/filesystem`), or
+     * a per-request resolver. When provided, reads route through the backend (its
+     * own boundary + `basePath`) instead of the local `projectRoot`; omitted ⇒
+     * identical current behavior (multi-tenant / per-request roots).
+     */
+    filesystem?: FilesystemProvider;
 }
 declare function createReadFileTool(opts: CreateReadFileToolOptions): CustomTool;
 
@@ -862,10 +902,32 @@ declare function createGenericHttpSearchAdapter(opts?: CreateGenericHttpSearchAd
  *        'binary_file' }` on refusal
  */
 
+/** The run-scoped context a `defineTool` handler receives as its 2nd argument. */
+type WriteToolContext = {
+    signal?: AbortSignal;
+    context?: unknown;
+};
 interface CreateWriteFileToolOptions {
     /** Absolute path to the project root. Every write is gated against this boundary. */
     projectRoot: string;
+    /**
+     * SE31 — optional pluggable filesystem backend (`@theokit/sdk/filesystem`), or
+     * a per-request resolver `(ctx) => FilesystemBackend`. When provided, writes
+     * route through it (its own boundary + `readOnly` + per-request root) instead
+     * of the local project fs. Omitted ⇒ identical current behavior (local
+     * `projectRoot`). The `.env`/`.git` policy still applies (storage-independent).
+     */
+    filesystem?: FilesystemProvider<WriteToolContext>;
+    /**
+     * SE32 — when true (and a {@link ReadTracker} is supplied), refuse to
+     * overwrite an existing file that was not read first, or that changed on disk
+     * since it was read (`read_required` / `stale_file`). A NEW file writes
+     * freely. Default OFF (unchanged behavior).
+     */
+    requireReadBeforeWrite?: boolean;
+    /** SE32 — the per-run tracker populated by the paired `read_file` tool. */
+    readTracker?: ReadTracker;
 }
 declare function createWriteFileTool(opts: CreateWriteFileToolOptions): CustomTool;
 
-export { CatastrophicCommandError, type CommandPolicy, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGlobToolOptions, type CreateListDirToolOptions, type CreateReadFileToolOptions, type CreateRunVitestToolOptions, type CreateSearchTextToolOptions, type CreateShellToolOptions, type CreateWebFetchToolOptions, type CreateWebSearchToolOptions, type CreateWriteFileToolOptions, DEFAULT_TOOL_GUIDANCE, type EnvContextOptions, type PlanModeTool, type PlanModeToolOptions, type PlanModeToolWithStore, type PlanNode, type QuestionTool, type QuestionToolOptions, RedirectBlockedError, type RepoMapOptions, type ResolveAndScreenOptions, type ScreenedFetchOptions, type SessionArtifactStore, type SessionArtifactStoreOptions, SsrfBlockedError, type TodoItem, type TodolistTool, type ToolGuidanceMap, type TruncationOptions, type TruncationResult, type VitestSummary, type WebSearchCallback, type WebSearchResult, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGlobTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withShellExitGuidance, withToolResultGuidance };
+export { CatastrophicCommandError, type CommandPolicy, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGlobToolOptions, type CreateListDirToolOptions, type CreateReadFileToolOptions, type CreateRunVitestToolOptions, type CreateSearchTextToolOptions, type CreateShellToolOptions, type CreateWebFetchToolOptions, type CreateWebSearchToolOptions, type CreateWriteFileToolOptions, DEFAULT_TOOL_GUIDANCE, type EnvContextOptions, type PlanModeTool, type PlanModeToolOptions, type PlanModeToolWithStore, type PlanNode, type QuestionTool, type QuestionToolOptions, ReadTracker, RedirectBlockedError, type RepoMapOptions, type ResolveAndScreenOptions, type ScreenedFetchOptions, type SessionArtifactStore, type SessionArtifactStoreOptions, SsrfBlockedError, type TodoItem, type TodolistTool, type ToolGuidanceMap, type TruncationOptions, type TruncationResult, type VitestSummary, type WebSearchCallback, type WebSearchResult, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGlobTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withShellExitGuidance, withToolResultGuidance };

package/dist/index.js

@@ -1,6 +1,6 @@
 import { readFile, copyFile, mkdir, writeFile, readdir, open, stat } from 'fs/promises';
 import { dirname, join, relative, resolve, sep } from 'path';
-import { defineTool, ConfigurationError } from '@theokit/sdk';
+import { Tool, ConfigurationError } from '@theokit/sdk';
 import { z } from 'zod';
 import { existsSync, statSync, mkdirSync, writeFileSync, realpathSync, readFileSync, lstatSync, readlinkSync, readdirSync } from 'fs';
 import { replaceFileAtomic } from '@theokit/sdk/internal/persistence';
@@ -8,6 +8,7 @@ import { safeFilenameForId, safePathJoin as safePathJoin$1 } from '@theokit/sdk/
 import { spawn } from 'child_process';
 import { lookup } from 'dns/promises';
 import { isIP } from 'net';
+import { resolveFilesystem, FileNotFoundError, FilesystemSecurityError, FilesystemReadOnlyError, StaleFileError, FilesystemError } from '@theokit/sdk/filesystem';
 
 // src/apply-patch.ts
 var PathTraversalError = class extends ConfigurationError {
@@ -102,7 +103,7 @@ function isForbiddenPath(input) {
 // src/apply-patch.ts
 function createApplyPatchTool(opts) {
   const { projectRoot } = opts;
-  return defineTool({
+  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 }.",
     inputSchema: z.object({
@@ -264,7 +265,7 @@ function createSessionArtifactStore(options) {
 }
 function createEditFileTool(opts) {
   const { projectRoot } = opts;
-  return defineTool({
+  return 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 }.",
     inputSchema: z.object({
@@ -441,7 +442,7 @@ function createGitDiffTool(opts) {
     timeoutMs = DEFAULT_TIMEOUT_MS,
     maxStdoutBytes = DEFAULT_MAX_STDOUT_BYTES
   } = opts;
-  return defineTool({
+  return Tool.create({
     name: "git_diff",
     description: "Return the unified diff of the project's working tree (or staged changes when cached=true). Scoped to a single file when 'path' is provided. Requires the project to be a git repository. Returns { ok, diff, truncated? } or { ok: false, error }.",
     inputSchema: z.object({
@@ -523,7 +524,7 @@ function runGitProcess(cwd, args, timeoutMs, maxStdoutBytes) {
 var DEFAULT_EXCLUDES = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", ".theo"]);
 function createGlobTool(opts) {
   const { projectRoot } = opts;
-  return defineTool({
+  return Tool.create({
     name: "glob_files",
     description: "Find files by glob pattern across the project \u2014 fast at any repo size. Use glob_files when you know the filename SHAPE; use search_text when you know the file CONTENT; use read_file when you know the exact path. The pattern supports * and ** wildcards (e.g. '**/*.ts', 'src/**/*.json'); node_modules/.git/dist/.theo are excluded and results are relative paths. Returns { ok, files } or { ok: false, error }.",
     inputSchema: z.object({
@@ -1052,7 +1053,10 @@ function withToolResultGuidance(tool, guidance) {
     name: tool.name,
     description: tool.description,
     inputSchema: tool.inputSchema,
-    handler: async (input) => injectGuidance(await tool.handler(input), guidance)
+    handler: async (input) => {
+      const out = await tool.handler(input);
+      return typeof out === "string" ? injectGuidance(out, guidance) : out;
+    }
   };
 }
 function withDefaultGuidance(tool) {
@@ -1066,6 +1070,7 @@ function withShellExitGuidance(tool) {
     inputSchema: tool.inputSchema,
     handler: async (input) => {
       const out = await tool.handler(input);
+      if (typeof out !== "string") return out;
       let parsed;
       try {
         parsed = JSON.parse(out);
@@ -1082,26 +1087,61 @@ function withShellExitGuidance(tool) {
 }
 var DEFAULT_MAX_ENTRIES = 500;
 function createListDirTool(opts) {
-  const { projectRoot, max = DEFAULT_MAX_ENTRIES } = opts;
-  return defineTool({
+  const { projectRoot, max = DEFAULT_MAX_ENTRIES, filesystem } = opts;
+  return 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.`,
     inputSchema: z.object({
       path: z.string().min(1).describe("Project-relative directory path. Use '.' for root.")
     }),
-    handler: async ({ path }) => {
+    handler: async ({ path }, ctx) => {
       const relative2 = path === "" || path === "." ? "." : path;
       if (relative2 !== "." && isForbiddenPath(relative2)) {
         return JSON.stringify({ ok: false, error: "forbidden_path", path });
       }
-      const boundary = resolveDirBoundary(relative2, projectRoot, path);
-      if ("error" in boundary) return boundary.error;
-      const readResult = await readDirSafe(boundary.absolutePath, path);
-      if ("error" in readResult) return readResult.error;
-      return formatListing(readResult.dirents, max);
+      if (filesystem) {
+        const backend = await resolveFilesystem(filesystem, ctx ?? {});
+        return listViaBackend(backend, relative2, path, max);
+      }
+      return listViaLocalFs(projectRoot, relative2, path, max);
     }
   });
 }
+async function listViaLocalFs(projectRoot, relative2, originalPath, max) {
+  const boundary = resolveDirBoundary(relative2, projectRoot, originalPath);
+  if ("error" in boundary) return boundary.error;
+  const readResult = await readDirSafe(boundary.absolutePath, originalPath);
+  if ("error" in readResult) return readResult.error;
+  return formatListing(readResult.dirents, max);
+}
+async function listViaBackend(backend, relative2, originalPath, max) {
+  let names;
+  try {
+    names = await backend.list(relative2);
+  } catch (err) {
+    if (err instanceof FileNotFoundError) {
+      return JSON.stringify({ ok: false, error: "not_found", path: originalPath });
+    }
+    if (err instanceof FilesystemSecurityError) {
+      return JSON.stringify({ ok: false, error: "path_traversal", path: originalPath });
+    }
+    throw err;
+  }
+  const totalCount = names.length;
+  const windowed = names.slice(0, max);
+  const entries = await Promise.all(
+    windowed.map(async (name) => {
+      const child = relative2 === "." ? name : `${relative2}/${name}`;
+      let type = "file";
+      try {
+        type = (await backend.stat(child)).isDirectory ? "directory" : "file";
+      } catch {
+      }
+      return { name, type };
+    })
+  );
+  return JSON.stringify({ ok: true, entries, truncated: totalCount > max, totalCount });
+}
 function resolveDirBoundary(relative2, projectRoot, originalPath) {
   try {
     const absolutePath = relative2 === "." ? projectRoot : safePathJoin(projectRoot, relative2);
@@ -1262,29 +1302,65 @@ function createQuestionTool(opts) {
 var MAX_FILE_SIZE = 5 * 1024 * 1024;
 var BINARY_PROBE_BYTES = 8 * 1024;
 function createReadFileTool(opts) {
-  const { projectRoot } = opts;
-  return defineTool({
+  const { projectRoot, readTracker, filesystem } = opts;
+  return Tool.create({
     name: "read_file",
     description: "Read a project-relative text file as UTF-8. ALWAYS read a file before you edit it (edit_file) or overwrite it (write_file), so your old_string / new content matches the real bytes exactly. Returns the WHOLE file (there is no offset or line-range parameter); to locate a symbol inside a large file, use search_text instead of re-reading. Refuses paths that escape the project root, sensitive files (.env, .git/, node_modules/, .theo/, lock files), and binary files (null byte in the first 8 KB); caps at 5 MB. Returns { ok, content, size } or { ok: false, error }.",
     inputSchema: z.object({
       path: z.string().min(1).describe("Project-relative file path.")
     }),
-    handler: async ({ path }) => {
+    handler: async ({ path }, ctx) => {
       if (isForbiddenPath(path)) {
         return JSON.stringify({ ok: false, error: "forbidden_path", path });
       }
+      if (filesystem) {
+        const backend = await resolveFilesystem(filesystem, ctx ?? {});
+        return readViaBackend(backend, path, (mtimeMs) => readTracker?.record(path, mtimeMs));
+      }
       const boundary = resolveBoundary(path, projectRoot);
       if ("error" in boundary) return boundary.error;
       const opened = await openHandleSafe(boundary.absolutePath, path);
       if ("error" in opened) return opened.error;
       try {
-        return await readContent(opened.handle, path);
+        return await readContent(
+          opened.handle,
+          path,
+          (mtimeMs) => readTracker?.record(path, mtimeMs)
+        );
       } finally {
         await opened.handle.close();
       }
     }
   });
 }
+async function readViaBackend(backend, path, onRead) {
+  try {
+    const stat2 = await backend.stat(path);
+    if (stat2.size > MAX_FILE_SIZE) {
+      return JSON.stringify({
+        ok: false,
+        error: "too_large",
+        path,
+        size: stat2.size,
+        limit: MAX_FILE_SIZE
+      });
+    }
+    const content = await backend.readFile(path);
+    if (content.includes("\0")) {
+      return JSON.stringify({ ok: false, error: "binary_file", path, size: stat2.size });
+    }
+    onRead?.(stat2.mtimeMs);
+    return JSON.stringify({ ok: true, content, size: stat2.size });
+  } catch (err) {
+    if (err instanceof FileNotFoundError) {
+      return JSON.stringify({ ok: false, error: "not_found", path });
+    }
+    if (err instanceof FilesystemSecurityError) {
+      return JSON.stringify({ ok: false, error: "path_traversal", path });
+    }
+    throw err;
+  }
+}
 function resolveBoundary(path, projectRoot) {
   try {
     const absolutePath = safePathJoin(projectRoot, path);
@@ -1309,7 +1385,7 @@ async function openHandleSafe(absolutePath, path) {
     throw err;
   }
 }
-async function readContent(handle, path) {
+async function readContent(handle, path, onRead) {
   const stat2 = await handle.stat();
   if (stat2.size > MAX_FILE_SIZE) {
     return JSON.stringify({
@@ -1324,6 +1400,7 @@ async function readContent(handle, path) {
     return JSON.stringify({ ok: false, error: "binary_file", path, size: stat2.size });
   }
   const content = await handle.readFile({ encoding: "utf-8" });
+  onRead?.(stat2.mtimeMs);
   return JSON.stringify({ ok: true, content, size: stat2.size });
 }
 async function isBinaryProbe(handle, size) {
@@ -1336,6 +1413,26 @@ async function isBinaryProbe(handle, size) {
   }
   return false;
 }
+
+// src/read-tracker.ts
+var ReadTracker = class {
+  seen = /* @__PURE__ */ new Map();
+  /** Record the mtime observed when `path` was read. */
+  record(path, mtimeMs) {
+    this.seen.set(path, mtimeMs);
+  }
+  /** The mtime last recorded for `path`, or `undefined` if never read. */
+  expected(path) {
+    return this.seen.get(path);
+  }
+};
+function evaluateReadBeforeWrite(tracker, path, currentMtimeMs) {
+  if (currentMtimeMs === null) return "ok";
+  const recorded = tracker.expected(path);
+  if (recorded === void 0) return "read_required";
+  if (recorded !== currentMtimeMs) return "stale";
+  return "ok";
+}
 var DEFAULT_TIMEOUT_MS2 = 12e4;
 var DEFAULT_MAX_STDOUT_BYTES2 = 10 * 1024 * 1024;
 function createRunVitestTool(opts) {
@@ -1344,7 +1441,7 @@ function createRunVitestTool(opts) {
     timeoutMs = DEFAULT_TIMEOUT_MS2,
     maxStdoutBytes = DEFAULT_MAX_STDOUT_BYTES2
   } = opts;
-  return defineTool({
+  return Tool.create({
     name: "run_vitest",
     description: "Run the project's vitest suite, optionally scoped to a file or pattern via 'path'. Returns parsed { ok, summary } or { ok: false, error }. Vitest stdout warnings are stripped \u2014 the parser extracts the trailing JSON report.",
     inputSchema: z.object({
@@ -1453,7 +1550,7 @@ function createSearchTextTool(opts) {
     maxMatches = DEFAULT_MAX_MATCHES,
     maxFileSize = DEFAULT_MAX_FILE_SIZE
   } = opts;
-  return defineTool({
+  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 }.`,
     inputSchema: z.object({
@@ -1564,7 +1661,7 @@ var MAX_TIMEOUT_MS = 3e5;
 var MAX_OUTPUT_BYTES = 5 * 1024 * 1024;
 function createShellTool(opts) {
   const { projectRoot, defaultTimeoutMs = DEFAULT_TIMEOUT_MS3, allowCatastrophic = false } = opts;
-  return defineTool({
+  return 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 }.",
     inputSchema: z.object({
@@ -1801,7 +1898,7 @@ function createWebFetchTool(opts) {
   const maxRedirects = opts?.maxRedirects;
   const fetchImpl = opts?.fetchImpl;
   const lookup = opts?.lookup;
-  return defineTool({
+  return Tool.create({
     name: "web_fetch",
     description: "Fetch the contents of a URL via HTTP/HTTPS. Use only for URLs the user provided or that you are confident help with the task; never invent or guess URLs. Rejects non-http(s) URLs and is SSRF-guarded by default (private/loopback/link-local/cloud-metadata hosts are refused with an ssrf_blocked error). The response body is capped at 1 MB. Returns { ok, content, status_code, content_type } or { ok: false, error }.",
     inputSchema: z.object({
@@ -1888,7 +1985,7 @@ function createWebFetchTool(opts) {
 }
 function createWebSearchTool(opts) {
   const { search, defaultMaxResults = 5 } = opts;
-  return defineTool({
+  return Tool.create({
     name: "web_search",
     description: "Search the web for a query \u2014 use when you need current information beyond the repo or your training cutoff (library docs, an error message, an API). Returns a list of results with title, URL, and snippet; follow up with web_fetch on a promising result to read it in full. The search provider is injected by the consumer. Returns { ok, results } or { ok: false, error }.",
     inputSchema: z.object({
@@ -1968,38 +2065,111 @@ function createGenericHttpSearchAdapter(opts = {}) {
 }
 var BINARY_PROBE_BYTES3 = 8 * 1024;
 function createWriteFileTool(opts) {
-  const { projectRoot } = opts;
-  return defineTool({
+  const { projectRoot, filesystem } = opts;
+  if (opts.requireReadBeforeWrite && !opts.readTracker) {
+    throw new Error(
+      "createWriteFileTool: requireReadBeforeWrite is true but no readTracker was provided \u2014 pass the same ReadTracker instance to createReadFileTool and createWriteFileTool."
+    );
+  }
+  const guard = opts.requireReadBeforeWrite ? opts.readTracker : void 0;
+  return Tool.create({
     name: "write_file",
-    description: "Write UTF-8 content to a project-relative file, creating parent directories as needed. OVERWRITES any existing file at the path. Prefer editing an existing file with edit_file over rewriting it; use write_file to create a NEW file or fully replace a small one. If the file already exists, read_file it first so you do not discard content you have not seen. Refuses paths that escape the project root, sensitive files (.env, .git/, node_modules/, .theo/, lock files), and binary-file overwrites. Returns { ok, path, bytes } or { ok: false, error }.",
+    description: "Write UTF-8 content to a project-relative file, creating parent directories as needed. OVERWRITES any existing file at the path. Prefer editing an existing file with edit_file over rewriting it; use write_file to create a NEW file or fully replace a small one. If the file already exists, read_file it first so you do not discard content you have not seen. Refuses paths that escape the write root and sensitive files (.env, .git/, node_modules/, .theo/, lock files); the default local root also refuses binary-file overwrites. Returns { ok, path, bytes } or { ok: false, error }.",
     inputSchema: z.object({
       path: z.string().min(1).describe("Project-relative file path."),
       content: z.string().describe("UTF-8 content to write.")
     }),
-    handler: async ({ path, content }) => {
+    handler: async ({ path, content }, ctx) => {
       if (isForbiddenPath(path)) {
         return JSON.stringify({ ok: false, error: "forbidden_path", path });
       }
-      let absolutePath;
-      try {
-        absolutePath = safePathJoin(projectRoot, path);
-        assertNoSymlinkEscape(absolutePath, projectRoot);
-      } catch (err) {
-        if (err instanceof PathTraversalError || err instanceof ForbiddenPathError) {
-          return JSON.stringify({ ok: false, error: "path_traversal", path });
-        }
-        throw err;
-      }
-      if (await isBinaryFile(absolutePath)) {
-        return JSON.stringify({ ok: false, error: "binary_file", path });
+      if (filesystem) {
+        const backend = await resolveFilesystem(filesystem, ctx ?? {});
+        return writeViaBackend(backend, path, content, guard);
       }
-      await mkdir(dirname(absolutePath), { recursive: true });
-      await writeFile(absolutePath, content, "utf-8");
-      const bytes = Buffer.byteLength(content, "utf-8");
-      return JSON.stringify({ ok: true, path, bytes });
+      return writeViaLocalFs(projectRoot, path, content, guard);
     }
   });
 }
+function readBeforeWriteError(guard, path, currentMtimeMs) {
+  if (!guard) return null;
+  const decision = evaluateReadBeforeWrite(guard, path, currentMtimeMs);
+  if (decision === "read_required")
+    return JSON.stringify({ ok: false, error: "read_required", path });
+  if (decision === "stale") return JSON.stringify({ ok: false, error: "stale_file", path });
+  return null;
+}
+async function writeViaLocalFs(projectRoot, path, content, guard) {
+  let absolutePath;
+  try {
+    absolutePath = safePathJoin(projectRoot, path);
+    assertNoSymlinkEscape(absolutePath, projectRoot);
+  } catch (err) {
+    if (err instanceof PathTraversalError || err instanceof ForbiddenPathError) {
+      return JSON.stringify({ ok: false, error: "path_traversal", path });
+    }
+    throw err;
+  }
+  const rbw = readBeforeWriteError(guard, path, await statMtimeOrNull(absolutePath));
+  if (rbw) return rbw;
+  if (await isBinaryFile(absolutePath)) {
+    return JSON.stringify({ ok: false, error: "binary_file", path });
+  }
+  await mkdir(dirname(absolutePath), { recursive: true });
+  await writeFile(absolutePath, content, "utf-8");
+  const bytes = Buffer.byteLength(content, "utf-8");
+  return JSON.stringify({ ok: true, path, bytes });
+}
+async function statMtimeOrNull(absolutePath) {
+  try {
+    return (await stat(absolutePath)).mtimeMs;
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+}
+async function backendMtimeOrNull(backend, path) {
+  try {
+    return (await backend.stat(path)).mtimeMs;
+  } catch (err) {
+    if (err instanceof FileNotFoundError) return null;
+    throw err;
+  }
+}
+async function writeViaBackend(backend, path, content, guard) {
+  try {
+    let expectedMtime;
+    if (guard) {
+      const current = await backendMtimeOrNull(backend, path);
+      const rbw = readBeforeWriteError(guard, path, current);
+      if (rbw) return rbw;
+      expectedMtime = current ?? void 0;
+    }
+    const stat2 = await backend.writeFile(
+      path,
+      content,
+      expectedMtime !== void 0 ? { expectedMtime } : void 0
+    );
+    return JSON.stringify({ ok: true, path, bytes: stat2.size });
+  } catch (err) {
+    return backendErrorToJson(err, path);
+  }
+}
+function backendErrorToJson(err, path) {
+  if (err instanceof FilesystemSecurityError) {
+    return JSON.stringify({ ok: false, error: "path_traversal", path });
+  }
+  if (err instanceof FilesystemReadOnlyError) {
+    return JSON.stringify({ ok: false, error: "read_only", path });
+  }
+  if (err instanceof StaleFileError) {
+    return JSON.stringify({ ok: false, error: "stale_file", path });
+  }
+  if (err instanceof FilesystemError) {
+    return JSON.stringify({ ok: false, error: "write_failed", path });
+  }
+  throw err;
+}
 async function isBinaryFile(absolutePath) {
   let handle;
   try {
@@ -2022,6 +2192,6 @@ async function isBinaryFile(absolutePath) {
   }
 }
 
-export { CatastrophicCommandError, DEFAULT_TOOL_GUIDANCE, RedirectBlockedError, SsrfBlockedError, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGlobTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withShellExitGuidance, withToolResultGuidance };
+export { CatastrophicCommandError, DEFAULT_TOOL_GUIDANCE, ReadTracker, RedirectBlockedError, SsrfBlockedError, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGlobTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withShellExitGuidance, withToolResultGuidance };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map