@theokit/sdk-tools 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -269,17 +269,28 @@ declare function buildEnvContext(cwd: string): string;
 declare function buildRepoMap(cwd: string, opts?: RepoMapOptions): string;
 
 /**
- * Catastrophic-command guardrail for `shell_exec` (M3-2).
- *
- * `catastrophicShellReason` is a pure, segment-aware deny-list: it splits a
- * command on top-level connectors (`;`, `&&`, `||`, pipe), strips `sudo`/`env`
- * prefixes, and matches at COMMAND POSITION (the executable, not an arbitrary
- * substring) so a mention like `echo "rm -rf /"` is not over-blocked. It returns
- * a human reason for the first catastrophic segment, else `null`.
- *
- * This is a heuristic GUARDRAIL, NOT a sandbox: it is bypassable by obfuscation
- * (eval/base64) and is best-effort. POSIX `/bin/sh` only; Windows PowerShell is
- * out of scope. Design: blueprint m3-catastrophic-shell. Zero new deps.
+ * Catastrophic-command guardrail for `shell_exec` (M3-2; hardened V3-1).
+ *
+ * `catastrophicShellReason` is a pure, segment-aware deny-list ported from
+ * theocode's security-reviewed `shell-guard.ts` (the proven spec: 42-blocked +
+ * 24-allowed corpus, 0 misses / 0 false-positives). It splits a command on shell
+ * separators (`;`, `&&`, `||`, `|`, `&`, newline), inspects EVERY segment (so a
+ * chained `rm -rf <safe>; rm -rf /` cannot hide), and matches at COMMAND POSITION
+ * (the executable, not an arbitrary substring) so a mention like `echo "rm -rf /"`
+ * is not over-blocked. Returns a human reason for the first catastrophic segment,
+ * else `null`.
+ *
+ * Categories: recursive-force `rm` of an absolute/home/parent path; destructive git
+ * (force-push, `reset --hard`, `clean -fd`); remote-code-execution (curl/wget piped
+ * OR command-substitution `$( )` / `<( )` / eval / source); disk/raw-device wipe
+ * (mkfs, `dd of=/dev/`, `truncate /dev/`, `> /dev/<blockdev>`); recursive chmod/chown
+ * of a root path (SDK extra); fork bomb; `find -delete` / `-exec rm`; secret-file
+ * exfiltration over the network.
+ *
+ * This is a heuristic GUARDRAIL, NOT a sandbox: it is bypassable by deep obfuscation
+ * (base64/env-indirection) and is best-effort. POSIX `/bin/sh` only; Windows
+ * PowerShell is out of scope. True isolation needs a container.
+ * referencia: .claude/knowledge-base/references/theocode-shell-guard/server-lib/shell-guard.ts
  */
 
 /** Thrown / reported when a command matches the catastrophic deny-list. */
@@ -288,10 +299,10 @@ declare class CatastrophicCommandError extends ConfigurationError {
     constructor(reason: string);
 }
 /**
- * Returns a human reason if `cmd` contains a catastrophic command (in any
- * segment, across chains/sudo/pipes), else `null`.
+ * Return a human-readable reason when `command` is catastrophic/irreversible, or `null`.
+ * The message is surfaced to the model so it self-corrects.
  */
-declare function catastrophicShellReason(cmd: string): string | null;
+declare function catastrophicShellReason(command: string): string | null;
 
 /**
  * ACI (Agent-Computer Interface) helpers for tools (M3-5).

package/dist/index.d.ts

@@ -269,17 +269,28 @@ declare function buildEnvContext(cwd: string): string;
 declare function buildRepoMap(cwd: string, opts?: RepoMapOptions): string;
 
 /**
- * Catastrophic-command guardrail for `shell_exec` (M3-2).
- *
- * `catastrophicShellReason` is a pure, segment-aware deny-list: it splits a
- * command on top-level connectors (`;`, `&&`, `||`, pipe), strips `sudo`/`env`
- * prefixes, and matches at COMMAND POSITION (the executable, not an arbitrary
- * substring) so a mention like `echo "rm -rf /"` is not over-blocked. It returns
- * a human reason for the first catastrophic segment, else `null`.
- *
- * This is a heuristic GUARDRAIL, NOT a sandbox: it is bypassable by obfuscation
- * (eval/base64) and is best-effort. POSIX `/bin/sh` only; Windows PowerShell is
- * out of scope. Design: blueprint m3-catastrophic-shell. Zero new deps.
+ * Catastrophic-command guardrail for `shell_exec` (M3-2; hardened V3-1).
+ *
+ * `catastrophicShellReason` is a pure, segment-aware deny-list ported from
+ * theocode's security-reviewed `shell-guard.ts` (the proven spec: 42-blocked +
+ * 24-allowed corpus, 0 misses / 0 false-positives). It splits a command on shell
+ * separators (`;`, `&&`, `||`, `|`, `&`, newline), inspects EVERY segment (so a
+ * chained `rm -rf <safe>; rm -rf /` cannot hide), and matches at COMMAND POSITION
+ * (the executable, not an arbitrary substring) so a mention like `echo "rm -rf /"`
+ * is not over-blocked. Returns a human reason for the first catastrophic segment,
+ * else `null`.
+ *
+ * Categories: recursive-force `rm` of an absolute/home/parent path; destructive git
+ * (force-push, `reset --hard`, `clean -fd`); remote-code-execution (curl/wget piped
+ * OR command-substitution `$( )` / `<( )` / eval / source); disk/raw-device wipe
+ * (mkfs, `dd of=/dev/`, `truncate /dev/`, `> /dev/<blockdev>`); recursive chmod/chown
+ * of a root path (SDK extra); fork bomb; `find -delete` / `-exec rm`; secret-file
+ * exfiltration over the network.
+ *
+ * This is a heuristic GUARDRAIL, NOT a sandbox: it is bypassable by deep obfuscation
+ * (base64/env-indirection) and is best-effort. POSIX `/bin/sh` only; Windows
+ * PowerShell is out of scope. True isolation needs a container.
+ * referencia: .claude/knowledge-base/references/theocode-shell-guard/server-lib/shell-guard.ts
  */
 
 /** Thrown / reported when a command matches the catastrophic deny-list. */
@@ -288,10 +299,10 @@ declare class CatastrophicCommandError extends ConfigurationError {
     constructor(reason: string);
 }
 /**
- * Returns a human reason if `cmd` contains a catastrophic command (in any
- * segment, across chains/sudo/pipes), else `null`.
+ * Return a human-readable reason when `command` is catastrophic/irreversible, or `null`.
+ * The message is surfaced to the model so it self-corrects.
  */
-declare function catastrophicShellReason(cmd: string): string | null;
+declare function catastrophicShellReason(command: string): string | null;
 
 /**
  * ACI (Agent-Computer Interface) helpers for tools (M3-5).

package/dist/index.js

@@ -94,8 +94,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;
 }
 
@@ -266,7 +266,7 @@ function createEditFileTool(opts) {
   const { projectRoot } = opts;
   return 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: z.object({
       path: z.string().min(1).describe("Project-relative file path."),
       old_string: z.string().min(1).describe("String to find in the file."),
@@ -274,6 +274,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 });
       }
@@ -522,7 +525,7 @@ function createGlobTool(opts) {
   const { projectRoot } = opts;
   return 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: z.object({
       pattern: z.string().min(1).describe("Glob pattern (e.g. '**/*.ts', 'src/**/*.json')."),
       cwd: z.string().optional().describe("Project-relative subdirectory to search from.")
@@ -599,128 +602,96 @@ var CatastrophicCommandError = class extends 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;
 }
@@ -1241,7 +1212,7 @@ function createReadFileTool(opts) {
   const { projectRoot } = opts;
   return 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: z.object({
       path: z.string().min(1).describe("Project-relative file path.")
     }),
@@ -1431,7 +1402,7 @@ function createSearchTextTool(opts) {
   } = opts;
   return 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: z.object({
       query: z.string().min(1).describe("Literal text to search for. Case-sensitive."),
       path: z.string().optional().describe("Optional project-relative directory to scope the search.")
@@ -1542,7 +1513,7 @@ function createShellTool(opts) {
   const { projectRoot, defaultTimeoutMs = DEFAULT_TIMEOUT_MS3, allowCatastrophic = false } = opts;
   return 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: z.object({
       command: z.string().min(1).describe("Shell command to execute."),
       timeout_ms: z.number().int().positive().optional().describe("Timeout in milliseconds (default 30000, max 300000).")
@@ -1720,7 +1691,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: {
@@ -1776,7 +1747,7 @@ function createWebFetchTool(opts) {
   const allowPrivateHosts = opts?.allowPrivateHosts ?? false;
   return 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: z.object({
       url: z.string().min(1).describe("URL to fetch (http or https only)."),
       timeout_ms: z.number().int().positive().optional().describe("Timeout in milliseconds (default 30000).")
@@ -1857,7 +1828,7 @@ function createWebSearchTool(opts) {
   const { search, defaultMaxResults = 5 } = opts;
   return 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: z.object({
       query: z.string().min(1).describe("Search query."),
       max_results: z.number().int().positive().max(20).optional().describe("Maximum results to return (default 5, max 20).")
@@ -1915,7 +1886,7 @@ function createWriteFileTool(opts) {
   const { projectRoot } = opts;
   return 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: z.object({
       path: z.string().min(1).describe("Project-relative file path."),
       content: z.string().describe("UTF-8 content to write.")