@theokit/sdk-tools 0.7.0 → 0.9.0

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.
@@ -272,8 +273,14 @@ interface RepoMapOptions {
     /** Max directory depth to descend. Default 4. */
     maxDepth?: number;
 }
+interface EnvContextOptions {
+    /** Injectable clock for the date line (deterministic tests). Default `new Date()`. */
+    now?: Date;
+    /** Path to the git `HEAD` file. Default `<cwd>/.git/HEAD`. */
+    gitHeadPath?: string;
+}
 /** Render a portable `<env>` orientation block. Never throws. */
-declare function buildEnvContext(cwd: string): string;
+declare function buildEnvContext(cwd: string, opts?: EnvContextOptions): string;
 /** Render a char-bounded, depth-limited directory tree. Never throws. */
 declare function buildRepoMap(cwd: string, opts?: RepoMapOptions): string;
 
@@ -498,6 +505,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.
  *
@@ -527,6 +553,12 @@ 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;
 }
 declare function createReadFileTool(opts: CreateReadFileToolOptions): CustomTool;
 
@@ -792,12 +824,12 @@ declare function createWebSearchTool(opts: CreateWebSearchToolOptions): CustomTo
  * the required auth header. Zero new dependencies. Design: blueprint m3-websearch-adapter.
  */
 
-type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+type FetchLike$1 = (url: string, init?: RequestInit) => Promise<Response>;
 interface CreateBraveWebSearchAdapterOptions {
     /** Brave API key. Defaults to `process.env.BRAVE_API_KEY`. */
     apiKey?: string;
     /** Injectable fetch (default `globalThis.fetch`) — set in tests for offline runs. */
-    fetchImpl?: FetchLike;
+    fetchImpl?: FetchLike$1;
     /** Override the Brave endpoint (self-host / test). */
     endpoint?: string;
 }
@@ -807,6 +839,42 @@ interface CreateBraveWebSearchAdapterOptions {
  */
 declare function createBraveWebSearchAdapter(opts?: CreateBraveWebSearchAdapterOptions): WebSearchCallback;
 
+/**
+ * Generic HTTP web-search adapter for `createWebSearchTool` (RADAR #92.d).
+ *
+ * `createGenericHttpSearchAdapter()` returns a `WebSearchCallback` that queries
+ * an arbitrary HTTP search endpoint keyed by env vars:
+ *   - `THEOKIT_SEARCH_API_URL` — endpoint returning `{ results: [{title,url,snippet}] }`
+ *   - `THEOKIT_SEARCH_API_KEY` — bearer token
+ *
+ * Request shape: `GET {endpoint}?q={query}&n={maxResults}` with
+ * `Authorization: Bearer {apiKey}`. Both values may be passed explicitly (params
+ * win over env). Unlike the Brave adapter (which fails early — fixed host, fixed
+ * auth), this one is provider-agnostic and **degrades gracefully**: when
+ * unconfigured OR on any network/parse failure it returns `[]` and never throws
+ * into the agent turn. A recurring empty result is a provider-config issue, not
+ * an agent bug. `fetchImpl` is injectable (default `globalThis.fetch`) for
+ * offline tests. Zero new dependencies.
+ *
+ * Promoted from theocode's `server/lib/web-search.ts` (`createSearchProvider`),
+ * re-keyed to neutral `THEOKIT_*` env vars.
+ */
+
+type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+interface CreateGenericHttpSearchAdapterOptions {
+    /** Bearer token. Defaults to `process.env.THEOKIT_SEARCH_API_KEY`. */
+    apiKey?: string;
+    /** Search endpoint URL. Defaults to `process.env.THEOKIT_SEARCH_API_URL`. */
+    endpoint?: string;
+    /** Injectable fetch (default `globalThis.fetch`) — set in tests for offline runs. */
+    fetchImpl?: FetchLike;
+}
+/**
+ * Build a `WebSearchCallback` backed by a generic HTTP search endpoint. Returns
+ * `[]` (graceful no-op) when unconfigured or on any failure — never throws.
+ */
+declare function createGenericHttpSearchAdapter(opts?: CreateGenericHttpSearchAdapterOptions): WebSearchCallback;
+
 /**
  * `write_file` — built-in tool for coding agents.
  *
@@ -820,10 +888,32 @@ declare function createBraveWebSearchAdapter(opts?: CreateBraveWebSearchAdapterO
  *        '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 CreateGitDiffToolOptions, type CreateGlobToolOptions, type CreateListDirToolOptions, type CreateReadFileToolOptions, type CreateRunVitestToolOptions, type CreateSearchTextToolOptions, type CreateShellToolOptions, type CreateWebFetchToolOptions, type CreateWebSearchToolOptions, type CreateWriteFileToolOptions, DEFAULT_TOOL_GUIDANCE, 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, 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.
@@ -272,8 +273,14 @@ interface RepoMapOptions {
     /** Max directory depth to descend. Default 4. */
     maxDepth?: number;
 }
+interface EnvContextOptions {
+    /** Injectable clock for the date line (deterministic tests). Default `new Date()`. */
+    now?: Date;
+    /** Path to the git `HEAD` file. Default `<cwd>/.git/HEAD`. */
+    gitHeadPath?: string;
+}
 /** Render a portable `<env>` orientation block. Never throws. */
-declare function buildEnvContext(cwd: string): string;
+declare function buildEnvContext(cwd: string, opts?: EnvContextOptions): string;
 /** Render a char-bounded, depth-limited directory tree. Never throws. */
 declare function buildRepoMap(cwd: string, opts?: RepoMapOptions): string;
 
@@ -498,6 +505,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.
  *
@@ -527,6 +553,12 @@ 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;
 }
 declare function createReadFileTool(opts: CreateReadFileToolOptions): CustomTool;
 
@@ -792,12 +824,12 @@ declare function createWebSearchTool(opts: CreateWebSearchToolOptions): CustomTo
  * the required auth header. Zero new dependencies. Design: blueprint m3-websearch-adapter.
  */
 
-type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+type FetchLike$1 = (url: string, init?: RequestInit) => Promise<Response>;
 interface CreateBraveWebSearchAdapterOptions {
     /** Brave API key. Defaults to `process.env.BRAVE_API_KEY`. */
     apiKey?: string;
     /** Injectable fetch (default `globalThis.fetch`) — set in tests for offline runs. */
-    fetchImpl?: FetchLike;
+    fetchImpl?: FetchLike$1;
     /** Override the Brave endpoint (self-host / test). */
     endpoint?: string;
 }
@@ -807,6 +839,42 @@ interface CreateBraveWebSearchAdapterOptions {
  */
 declare function createBraveWebSearchAdapter(opts?: CreateBraveWebSearchAdapterOptions): WebSearchCallback;
 
+/**
+ * Generic HTTP web-search adapter for `createWebSearchTool` (RADAR #92.d).
+ *
+ * `createGenericHttpSearchAdapter()` returns a `WebSearchCallback` that queries
+ * an arbitrary HTTP search endpoint keyed by env vars:
+ *   - `THEOKIT_SEARCH_API_URL` — endpoint returning `{ results: [{title,url,snippet}] }`
+ *   - `THEOKIT_SEARCH_API_KEY` — bearer token
+ *
+ * Request shape: `GET {endpoint}?q={query}&n={maxResults}` with
+ * `Authorization: Bearer {apiKey}`. Both values may be passed explicitly (params
+ * win over env). Unlike the Brave adapter (which fails early — fixed host, fixed
+ * auth), this one is provider-agnostic and **degrades gracefully**: when
+ * unconfigured OR on any network/parse failure it returns `[]` and never throws
+ * into the agent turn. A recurring empty result is a provider-config issue, not
+ * an agent bug. `fetchImpl` is injectable (default `globalThis.fetch`) for
+ * offline tests. Zero new dependencies.
+ *
+ * Promoted from theocode's `server/lib/web-search.ts` (`createSearchProvider`),
+ * re-keyed to neutral `THEOKIT_*` env vars.
+ */
+
+type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+interface CreateGenericHttpSearchAdapterOptions {
+    /** Bearer token. Defaults to `process.env.THEOKIT_SEARCH_API_KEY`. */
+    apiKey?: string;
+    /** Search endpoint URL. Defaults to `process.env.THEOKIT_SEARCH_API_URL`. */
+    endpoint?: string;
+    /** Injectable fetch (default `globalThis.fetch`) — set in tests for offline runs. */
+    fetchImpl?: FetchLike;
+}
+/**
+ * Build a `WebSearchCallback` backed by a generic HTTP search endpoint. Returns
+ * `[]` (graceful no-op) when unconfigured or on any failure — never throws.
+ */
+declare function createGenericHttpSearchAdapter(opts?: CreateGenericHttpSearchAdapterOptions): WebSearchCallback;
+
 /**
  * `write_file` — built-in tool for coding agents.
  *
@@ -820,10 +888,32 @@ declare function createBraveWebSearchAdapter(opts?: CreateBraveWebSearchAdapterO
  *        '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 CreateGitDiffToolOptions, type CreateGlobToolOptions, type CreateListDirToolOptions, type CreateReadFileToolOptions, type CreateRunVitestToolOptions, type CreateSearchTextToolOptions, type CreateShellToolOptions, type CreateWebFetchToolOptions, type CreateWebSearchToolOptions, type CreateWriteFileToolOptions, DEFAULT_TOOL_GUIDANCE, 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, 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

@@ -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, FilesystemSecurityError, FilesystemReadOnlyError, StaleFileError, FilesystemError, FileNotFoundError } from '@theokit/sdk/filesystem';
 
 // src/apply-patch.ts
 var PathTraversalError = class extends ConfigurationError {
@@ -885,15 +886,26 @@ function safeReadHead(p, n) {
     return "";
   }
 }
-function buildEnvContext(cwd) {
+function gitBranch(headPath) {
+  try {
+    const head = readFileSync(headPath, "utf-8").trim();
+    const match = head.match(/^ref:\s*refs\/heads\/(.+)$/);
+    return match ? match[1] : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function buildEnvContext(cwd, opts = {}) {
   const lines = [
     "<env>",
     `  Working directory: ${cwd}`,
     `  Platform: ${process.platform} (${process.arch})`,
     `  Node: ${process.version}`,
-    `  Is git repo: ${safeExists(join(cwd, ".git")) ? "yes" : "no"}`,
-    `  Today's date: ${(/* @__PURE__ */ new Date()).toDateString()}`
+    `  Is git repo: ${safeExists(join(cwd, ".git")) ? "yes" : "no"}`
   ];
+  const branch = gitBranch(opts.gitHeadPath ?? join(cwd, ".git", "HEAD"));
+  if (branch) lines.push(`  Branch: ${branch}`);
+  lines.push(`  Today's date: ${(opts.now ?? /* @__PURE__ */ new Date()).toDateString()}`);
   const docs = PROJECT_DOCS.filter((d) => safeExists(join(cwd, d)));
   if (docs.length > 0) {
     lines.push(`  Project docs: ${docs.join(", ")}`);
@@ -1041,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) {
@@ -1055,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);
@@ -1251,7 +1267,7 @@ function createQuestionTool(opts) {
 var MAX_FILE_SIZE = 5 * 1024 * 1024;
 var BINARY_PROBE_BYTES = 8 * 1024;
 function createReadFileTool(opts) {
-  const { projectRoot } = opts;
+  const { projectRoot, readTracker } = opts;
   return defineTool({
     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 }.",
@@ -1267,7 +1283,11 @@ function createReadFileTool(opts) {
       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();
       }
@@ -1298,7 +1318,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({
@@ -1313,6 +1333,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) {
@@ -1325,6 +1346,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) {
@@ -1932,40 +1973,136 @@ function createBraveWebSearchAdapter(opts = {}) {
     }));
   };
 }
+
+// src/web-search-http.ts
+function createGenericHttpSearchAdapter(opts = {}) {
+  const apiKey = opts.apiKey ?? process.env.THEOKIT_SEARCH_API_KEY;
+  const endpoint = opts.endpoint ?? process.env.THEOKIT_SEARCH_API_URL;
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  return async (query, maxResults) => {
+    if (!apiKey || !endpoint) return [];
+    try {
+      const url = `${endpoint}?q=${encodeURIComponent(query)}&n=${maxResults}`;
+      const res = await fetchImpl(url, { headers: { Authorization: `Bearer ${apiKey}` } });
+      if (!res.ok) return [];
+      const data = await res.json();
+      return (data?.results ?? []).slice(0, maxResults).map((r) => ({
+        title: String(r?.title ?? ""),
+        url: String(r?.url ?? ""),
+        snippet: String(r?.snippet ?? "")
+      }));
+    } catch {
+      return [];
+    }
+  };
+}
 var BINARY_PROBE_BYTES3 = 8 * 1024;
 function createWriteFileTool(opts) {
-  const { projectRoot } = opts;
+  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 defineTool({
     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 {
@@ -1988,6 +2125,6 @@ async function isBinaryFile(absolutePath) {
   }
 }
 
-export { CatastrophicCommandError, DEFAULT_TOOL_GUIDANCE, RedirectBlockedError, SsrfBlockedError, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createEditFileTool, 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