@theokit/sdk-tools 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.4.0
+
+### Minor Changes
+
+- bd10da3: SOTA default descriptions for the 9 built-in tools (`read_file`/`write_file`/`edit_file`/`glob_files`/`search_text`/`shell_exec`/`todolist`/`web_fetch`/`web_search`).
+
+  Each tool's default `description` is upgraded from terse mechanics-only copy to rich, behavior-accurate ACI copy (preconditions, when-to-prefer-which-tool, return shape) — the Agent-Computer Interface the model reads to choose tools, which measurably improves tool-selection. Every claim is verified against the tool's own handler (e.g. `search_text` is described as LITERAL + CASE-SENSITIVE because it matches via `line.includes`; `web_fetch` is described as SSRF-guarded because `screenedFetch` defaults `allowPrivateHosts: false`), so the description lives next to the implementation it describes and cannot drift. Descriptions are generalized (no app-specific cross-tool references). `edit_file` now also ENFORCES the documented `old_string !== new_string` precondition (a no-op edit returns `{ ok: false, error: "no_change" }` instead of a misleading `replacements: 1`), so the description matches behavior. Otherwise no API change: same factory signatures, same return shapes; only the default description string changed. Consumers no longer need to override these descriptions app-side — `withDescription` remains for genuine per-consumer customization. Added `tests/sota-descriptions.test.ts` asserting each description's load-bearing behavioral phrases.
+
+## 0.3.0
+
+### Minor Changes
+
+- 986f340: V3-1 — harden `catastrophicShellReason` to theocode's security-reviewed shell-guard. The `shell_exec` guardrail previously missed 18 of 42 catastrophic commands (empirical probe): `git reset --hard`, `git clean -fd`, secret-file exfiltration (`cat .env | curl`, `tar ~/.aws | nc`), command-substitution / eval RCE (`eval "$(curl)"`, `. <(curl)`, `bash -c "$(curl)"`), `find / -delete` / `-exec rm`, `truncate /dev/sda`, and a range of `rm -rf` targets (`~/sub`, `/usr/local`, `../..`, `$HOME/x`, flags after the operand, any absolute non-scratch path). The rules are ported from theocode's hardened guard (proven by a 42-blocked + 24-allowed corpus at 0 misses / 0 false-positives) as a SUPERSET — the SDK's extra screens (recursive `chmod`/`chown` on a root path, extra block-device families, `//` collapse) are kept, and the segment splitter now also covers `&` and newlines. Reason strings widened to describe each category; the public API (`catastrophicShellReason(cmd): string | null`, `CatastrophicCommandError`) is unchanged. No new dependency.
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -4,6 +4,8 @@ Built-in tools for `@theokit/sdk` agents. File system, git, subprocess, search-t
 
 Extracted from `@theokit/sdk@1.7.0` as part of the SDK 2.0 package split.
 
+See the [**Theo Harness Capability Map**](../../docs/harness-capability-map.md) for every tool + guard primitive (`buildRepoMap`, `isBlockedIp`, `screenedFetch`, `catastrophicShellReason`, ...) with import paths and examples.
+
 ## Install
 
 ```bash

package/dist/index.cjs

@@ -96,8 +96,8 @@ function isForbiddenPath(input) {
   if (first === ".git") return true;
   if (first === "node_modules") return true;
   if (first === ".theo") return true;
-  const basename2 = segments[segments.length - 1];
-  if (LOCK_FILES.has(basename2)) return true;
+  const basename = segments[segments.length - 1];
+  if (LOCK_FILES.has(basename)) return true;
   return false;
 }
 
@@ -268,7 +268,7 @@ function createEditFileTool(opts) {
   const { projectRoot } = opts;
   return sdk.defineTool({
     name: "edit_file",
-    description: "Replace the first occurrence of old_string with new_string in a project-relative file. Falls back to whitespace-normalized matching when the exact match fails. Creates a .bak backup before editing. Returns { ok, replacements } or { ok: false, error }.",
+    description: "Make an exact string replacement in a project-relative file. Replaces the FIRST occurrence of old_string with new_string (a whitespace-normalized fallback is attempted if the exact match fails) and writes a .bak backup first. Read the file first so old_string matches the on-disk text exactly; include enough surrounding context to make it unique \u2014 only the first match is replaced, so a too-short old_string can edit the wrong location. old_string must be non-empty and differ from new_string; to change every occurrence, call edit_file repeatedly. Returns { ok, replacements } or { ok: false, error }.",
     inputSchema: zod.z.object({
       path: zod.z.string().min(1).describe("Project-relative file path."),
       old_string: zod.z.string().min(1).describe("String to find in the file."),
@@ -276,6 +276,9 @@ function createEditFileTool(opts) {
     }),
     // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: unified diff parsing is inherently complex
     handler: async ({ path, old_string, new_string }) => {
+      if (old_string === new_string) {
+        return JSON.stringify({ ok: false, error: "no_change", path });
+      }
       if (isForbiddenPath(path)) {
         return JSON.stringify({ ok: false, error: "forbidden_path", path });
       }
@@ -524,7 +527,7 @@ function createGlobTool(opts) {
   const { projectRoot } = opts;
   return sdk.defineTool({
     name: "glob_files",
-    description: "List project files matching a glob-like pattern. Excludes node_modules, .git, dist, .theo by default. Returns relative paths. Pattern supports * and ** wildcards. Returns { ok, files } or { ok: false, error }.",
+    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: zod.z.object({
       pattern: zod.z.string().min(1).describe("Glob pattern (e.g. '**/*.ts', 'src/**/*.json')."),
       cwd: zod.z.string().optional().describe("Project-relative subdirectory to search from.")
@@ -601,128 +604,96 @@ var CatastrophicCommandError = class extends sdk.ConfigurationError {
     });
   }
 };
-var SHELL_NAMES = /* @__PURE__ */ new Set(["sh", "bash", "zsh", "dash", "ksh", "ash"]);
-var PREFIX_TOKENS = /* @__PURE__ */ new Set([
-  "sudo",
-  "doas",
-  "env",
-  "command",
-  "time",
-  "nice",
-  "nohup",
-  "exec",
-  "builtin"
-]);
-var FORK_BOMB = /:\s*\(\s*\)\s*\{[^}]*\|[^}]*&[^}]*\}/;
-var DEVICE_REDIRECT = /[>]\s*\/dev\/(?:sd|nvme|hd|vd|mmcblk|disk|loop|dm-)\w*/;
-var SYSTEM_DIR = /^\/(?:etc|usr|bin|sbin|lib|lib64|var|boot|home|root|opt|sys|proc|dev)(?:\/\*?)?$/;
-function basename(p) {
-  const i = p.lastIndexOf("/");
-  return i >= 0 ? p.slice(i + 1) : p;
-}
-function unquote(t) {
-  if (t.length >= 2) {
-    const a = t[0];
-    const b = t[t.length - 1];
-    if (a === '"' && b === '"' || a === "'" && b === "'") return t.slice(1, -1);
-  }
-  return t;
-}
-function tokenize(s) {
-  return s.trim().split(/\s+/).filter(Boolean);
-}
-function splitSegments(cmd) {
-  return cmd.split(/&&|\|\||;|\|/);
-}
-function stripPrefixTokens(tokens) {
-  let t = tokens;
-  let head = t[0];
-  while (head !== void 0 && PREFIX_TOKENS.has(basename(unquote(head)))) {
-    t = t.slice(1);
-    head = t[0];
-  }
-  return t;
-}
-function operandsOf(tokens) {
-  return tokens.slice(1).filter((t) => !t.startsWith("-")).map(unquote);
-}
-var HOME_VAR = /^\$\{?HOME\}?$/;
-function isRootishPath(op) {
-  if (op === "~" || op === "*" || op === "." || HOME_VAR.test(op)) return true;
-  let collapsed = op.replace(/\/+/g, "/");
-  if (collapsed.length > 1 && collapsed.endsWith("/")) collapsed = collapsed.slice(0, -1);
-  if (collapsed === "/" || collapsed === "/*" || collapsed === "/.") return true;
-  return SYSTEM_DIR.test(collapsed);
-}
-function hasRecursiveForce(tokens) {
-  const flags = tokens.slice(1).filter((t) => t.startsWith("-"));
-  const recursive = flags.some(
-    (f) => f === "--recursive" || !f.startsWith("--") && /[rR]/.test(f)
-  );
-  const force = flags.some((f) => f === "--force" || !f.startsWith("--") && f.includes("f"));
+function unquote(token) {
+  return token.replace(/^(['"])(.*)\1$/, "$2").replace(/^['"]|['"]$/g, "");
+}
+function commandSegments(command) {
+  return command.split(/&&|\|\||[;|&\n]/).map((s) => s.trim()).filter((s) => s.length > 0);
+}
+function commandArgs(segment, name) {
+  const tokens = segment.split(/\s+/);
+  let i = 0;
+  if (tokens[i] === "sudo") i += 1;
+  if (tokens[i] !== name) return null;
+  return tokens.slice(i + 1);
+}
+function commandSegmentsNamed(command, name) {
+  return commandSegments(command).map((s) => commandArgs(s, name)).filter((args) => args !== null);
+}
+function isRecursiveForce(args) {
+  const flags = args.filter((t) => t.startsWith("-")).join(" ");
+  if (flags.length === 0) return false;
+  const recursive = /-[a-z]*r/i.test(flags) || /--recursive/.test(flags);
+  const force = /-[a-z]*f/i.test(flags) || /--force/.test(flags);
   return recursive && force;
 }
-function hasRecursiveFlag(tokens) {
-  return tokens.slice(1).some(
-    (t) => t === "--recursive" || t.startsWith("-") && !t.startsWith("--") && /[rR]/.test(t)
-  );
+function isRecursive(args) {
+  const flags = args.filter((t) => t.startsWith("-")).join(" ");
+  return /-[a-z]*r/i.test(flags) || /--recursive/.test(flags);
+}
+var SAFE_ABSOLUTE_TARGET = /^\/(tmp|var\/tmp)(\/|$)/;
+function targetsDangerousPath(args) {
+  const targets = args.filter((token) => token.length > 0 && !token.startsWith("-")).map(unquote);
+  return targets.some((raw) => {
+    const t = raw.replace(/\/+/g, "/");
+    if (t === "/dev/null" || SAFE_ABSOLUTE_TARGET.test(t)) return false;
+    return /^\/($|\*)/.test(t) || // "/" or "/*"
+    /^\/[^/]/.test(t) || // an absolute path like /etc, /usr/local, /home/user/x
+    t === "~" || t.startsWith("~/") || /\$\{?HOME\b\}?/.test(t) || // $HOME or ${HOME}
+    t === ".." || t.startsWith("../") || t.includes("/..") || t === "*";
+  });
 }
-function isCurlPipedToShell(cmd) {
-  const segs = cmd.replace(/\|\|/g, ";").split(/[;|]/).map((s) => s.trim()).filter(Boolean);
-  let fetcher = false;
-  let shell = false;
-  for (const s of segs) {
-    const tk = stripPrefixTokens(tokenize(s));
-    const head = tk[0];
-    if (head === void 0) continue;
-    const c = basename(unquote(head));
-    if (c === "curl" || c === "wget") fetcher = true;
-    if (SHELL_NAMES.has(c)) shell = true;
-  }
-  return fetcher && shell;
-}
-var rmCheck = (cmd0, tokens) => {
-  if (cmd0 !== "rm" || !hasRecursiveForce(tokens)) return null;
-  const ops = operandsOf(tokens);
-  return ops.length === 0 || ops.some(isRootishPath) ? "rm -rf of a root/home/glob path" : null;
-};
-var mkfsCheck = (cmd0) => cmd0.startsWith("mkfs") ? "mkfs on a device" : null;
-var ddCheck = (cmd0, tokens) => {
-  if (cmd0 !== "dd") return null;
-  return tokens.some((t) => unquote(t).startsWith("of=/dev/")) ? "dd writing to a device" : null;
-};
-var gitForceCheck = (cmd0, tokens) => {
-  if (cmd0 !== "git" || !tokens.includes("push") || tokens.includes("--force-with-lease")) {
-    return null;
+var DEVICE_WIPE = [
+  /\bmkfs(\.\w+)?\b/,
+  /\bdd\b[^\n]*\bof=\/dev\//,
+  /\btruncate\b[^\n]*\s\/dev\//,
+  />\s*\/dev\/(sd|nvme|hd|vd|mmcblk|disk|loop|dm-)/
+];
+var checkRemoteExec = (cmd) => /\b(curl|wget|fetch)\b[^\n]*\|\s*(sudo\s+)?(sh|bash|zsh|dash|python[0-9.]*|node|ruby|perl)\b/i.test(
+  cmd
+) || /(\$\(|<\()\s*(sudo\s+)?(curl|wget|fetch)\b/i.test(cmd) || /\b(eval|source)\b[^\n]*\b(curl|wget|fetch)\b/i.test(cmd) ? "executes a remote download (pipe / command-substitution / eval) \u2014 remote code execution" : null;
+var checkDeviceWipe = (cmd) => DEVICE_WIPE.some((re) => re.test(cmd)) ? "writes to a raw block device / formats a disk" : null;
+var checkForkBomb = (cmd) => /:\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/.test(cmd) ? "fork bomb" : null;
+var checkDestructiveGit = (cmd) => {
+  if (/\bgit\b[^\n]*\bpush\b[^\n]*(--force(?!-with-lease)\b|\s-f\b|\s\+\S)/.test(cmd)) {
+    return "git force-push (overwrites remote history)";
+  }
+  if (/\bgit\b[^\n]*\breset\b[^\n]*--hard\b/.test(cmd)) {
+    return "git reset --hard (discards committed and working changes)";
   }
-  const force = tokens.includes("--force") || tokens.some((t) => /^-[a-z]*f[a-z]*$/.test(t)) || operandsOf(tokens).some((op) => /^\+[^+]/.test(op));
-  return force ? "git push --force" : null;
+  if (/\bgit\b[^\n]*\bclean\b[^\n]*(-[a-z]*f[a-z]*d|-[a-z]*d[a-z]*f)/.test(cmd)) {
+    return "git clean -fd (permanently deletes untracked files)";
+  }
+  return null;
 };
-var permCheck = (cmd0, tokens) => {
-  if (cmd0 !== "chmod" && cmd0 !== "chown" || !hasRecursiveFlag(tokens)) return null;
-  return operandsOf(tokens).some(isRootishPath) ? `${cmd0} -R on a root path` : null;
+var checkRm = (cmd) => commandSegmentsNamed(cmd, "rm").some((a) => isRecursiveForce(a) && targetsDangerousPath(a)) ? "recursive force-delete of an absolute, home, or parent path" : null;
+var checkPerm = (cmd) => ["chmod", "chown"].some(
+  (name) => commandSegmentsNamed(cmd, name).some((a) => isRecursive(a) && targetsDangerousPath(a))
+) ? "recursive permission change on an absolute, home, or parent path" : null;
+var checkFind = (cmd) => /\bfind\s+(\/\S*|~\S*|\$\{?HOME\}?\S*)\s[^\n]*(-delete\b|-exec\s+rm\b)/.test(cmd) ? "find -delete / -exec rm on an absolute or home path" : null;
+var checkExfiltration = (cmd) => {
+  const touchesSecret = /(^|[\s/'"])(\.env(\.\w+)?|id_rsa|id_ed25519|\.ssh(\/|\b)|credentials|\.aws(\/|\b)|\.npmrc)\b/.test(
+    cmd
+  );
+  const sendsNetwork = /\b(curl|wget|nc|netcat|scp|ftp|telnet)\b/.test(cmd) || /\bpython[0-9.]*\s+-m\s+http/.test(cmd);
+  return touchesSecret && sendsNetwork ? "sends a secret/credential file over the network (exfiltration)" : null;
 };
-var redirectCheck = (_cmd0, _tokens, seg) => DEVICE_REDIRECT.test(seg) ? "redirect to a device" : null;
-var SEGMENT_CHECKS = [
-  rmCheck,
-  mkfsCheck,
-  ddCheck,
-  gitForceCheck,
-  permCheck,
-  redirectCheck
+var CATEGORY_CHECKS = [
+  checkRemoteExec,
+  checkDeviceWipe,
+  checkForkBomb,
+  checkDestructiveGit,
+  checkRm,
+  checkPerm,
+  checkFind,
+  checkExfiltration
 ];
-function catastrophicShellReason(cmd) {
-  if (FORK_BOMB.test(cmd)) return "fork bomb";
-  if (isCurlPipedToShell(cmd)) return "curl/wget piped into a shell";
-  for (const seg of splitSegments(cmd)) {
-    const tokens = stripPrefixTokens(tokenize(seg));
-    const head = tokens[0];
-    if (head === void 0) continue;
-    const cmd0 = basename(unquote(head));
-    for (const check of SEGMENT_CHECKS) {
-      const reason = check(cmd0, tokens, seg);
-      if (reason) return reason;
-    }
+function catastrophicShellReason(command) {
+  const cmd = command.trim();
+  if (cmd.length === 0) return null;
+  for (const check of CATEGORY_CHECKS) {
+    const reason = check(cmd);
+    if (reason) return reason;
   }
   return null;
 }
@@ -1243,7 +1214,7 @@ function createReadFileTool(opts) {
   const { projectRoot } = opts;
   return sdk.defineTool({
     name: "read_file",
-    description: "Read a single project-relative text file as UTF-8. Refuses paths that escape the project root, are in the sensitive-file blocklist (.env, .git/, node_modules/, .theo/, lock files), or contain a null byte in the first 8 KB (binary file). Returns { ok, content } or { ok: false, error }.",
+    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: zod.z.object({
       path: zod.z.string().min(1).describe("Project-relative file path.")
     }),
@@ -1433,7 +1404,7 @@ function createSearchTextTool(opts) {
   } = opts;
   return sdk.defineTool({
     name: "search_text",
-    description: `Search the project tree for a literal text query. Skips sensitive dirs (.env/.git/node_modules/.theo), binary files, and files over 1 MB. Returns up to ${String(maxMatches)} matches as { file, line, preview }. Use 'path' to scope the search to a subdirectory.`,
+    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: zod.z.object({
       query: zod.z.string().min(1).describe("Literal text to search for. Case-sensitive."),
       path: zod.z.string().optional().describe("Optional project-relative directory to scope the search.")
@@ -1544,7 +1515,7 @@ function createShellTool(opts) {
   const { projectRoot, defaultTimeoutMs = DEFAULT_TIMEOUT_MS3, allowCatastrophic = false } = opts;
   return sdk.defineTool({
     name: "shell_exec",
-    description: "Execute a shell command in the project directory. Returns stdout, stderr, and exit code. Default timeout 30s, max 5 minutes. Output capped at 5 MB. Returns { ok, stdout, stderr, exit_code } or { ok: false, error }.",
+    description: "Execute a shell command in the project directory. Use this for terminal operations \u2014 running tests, git, package managers, build tools. Do NOT use it for file operations (reading, writing, editing, finding files): prefer the specialized read_file/write_file/edit_file/glob_files/search_text tools, which are path-checked and safer. Only commit, push, or change git state when the user explicitly asks. timeout_ms defaults to 30000 (max 300000); stdout/stderr are capped (~5 MB). Returns { ok, stdout, stderr, exit_code } or { ok: false, error }.",
     inputSchema: zod.z.object({
       command: zod.z.string().min(1).describe("Shell command to execute."),
       timeout_ms: zod.z.number().int().positive().optional().describe("Timeout in milliseconds (default 30000, max 300000).")
@@ -1722,7 +1693,7 @@ ${done}/${items.length} done | ${inProg} in progress | ${pending} pending`);
   };
   return {
     name: "todolist",
-    description: "Track multi-step task progress. Actions: 'add' (create task with title), 'complete' (mark done by id), 'in_progress' (mark started by id), 'remove' (delete by id), 'list' (show all), 'clear_completed' (remove done items). Returns { ok, items, items_summary } (items = structured array; items_summary = formatted text).",
+    description: "Create and maintain a structured task list for the current session \u2014 tracks progress and keeps a multi-step plan visible across turns. Use it proactively when the work has 3+ steps or the user gave multiple tasks; skip it for a single trivial step. Keep exactly ONE item 'in_progress' at a time, and mark 'complete' only after the work is actually done. Actions: 'add' (create with title), 'in_progress' (mark started by id), 'complete' (mark done by id), 'remove' (delete by id), 'list' (show all), 'clear_completed' (remove done items). Returns { ok, items, items_summary } (items = structured array; items_summary = formatted text).",
     inputSchema: {
       type: "object",
       properties: {
@@ -1778,7 +1749,7 @@ function createWebFetchTool(opts) {
   const allowPrivateHosts = opts?.allowPrivateHosts ?? false;
   return sdk.defineTool({
     name: "web_fetch",
-    description: "Fetch content from a URL via HTTP/HTTPS. Rejects non-http(s) URLs. Response body capped at 1 MB. Returns { ok, content, status_code } or { ok: false, error }.",
+    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: zod.z.object({
       url: zod.z.string().min(1).describe("URL to fetch (http or https only)."),
       timeout_ms: zod.z.number().int().positive().optional().describe("Timeout in milliseconds (default 30000).")
@@ -1859,7 +1830,7 @@ function createWebSearchTool(opts) {
   const { search, defaultMaxResults = 5 } = opts;
   return sdk.defineTool({
     name: "web_search",
-    description: "Search the web for a query. Returns a list of results with title, URL, and snippet. The search provider is injected by the consumer. Returns { ok, results } or { ok: false, error }.",
+    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: zod.z.object({
       query: zod.z.string().min(1).describe("Search query."),
       max_results: zod.z.number().int().positive().max(20).optional().describe("Maximum results to return (default 5, max 20).")
@@ -1917,7 +1888,7 @@ function createWriteFileTool(opts) {
   const { projectRoot } = opts;
   return sdk.defineTool({
     name: "write_file",
-    description: "Write UTF-8 content to a project-relative file. Creates parent directories recursively. 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 project root, sensitive files (.env, .git/, node_modules/, .theo/, lock files), and binary-file overwrites. Returns { ok, path, bytes } or { ok: false, error }.",
     inputSchema: zod.z.object({
       path: zod.z.string().min(1).describe("Project-relative file path."),
       content: zod.z.string().describe("UTF-8 content to write.")