omnius 1.0.174 → 1.0.175

package/dist/index.js

@@ -5738,6 +5738,108 @@ var init_change_log = __esm({
   }
 });
 
+// packages/execution/dist/tools/text-encoding.js
+import { TextDecoder as TextDecoder2 } from "node:util";
+function decodeTextArgument(args, options2) {
+  const direct = firstString(args, options2.textKeys);
+  const b64 = firstString(args, options2.base64Keys);
+  const encodingRaw = firstString(args, options2.encodingKeys ?? ["content_encoding", "encoding"]);
+  const encoding = encodingRaw?.value.trim().toLowerCase().replace(/_/g, "-");
+  if (b64) {
+    return decodeBase64Text(b64.value, b64.key);
+  }
+  if (encoding === "base64") {
+    if (!direct) {
+      return {
+        ok: false,
+        reason: "missing",
+        error: `${options2.fieldLabel} is required when content_encoding="base64". ` + options2.example
+      };
+    }
+    return decodeBase64Text(direct.value, direct.key);
+  }
+  if (encoding && encoding !== "utf-8" && encoding !== "utf8" && encoding !== "text") {
+    return {
+      ok: false,
+      reason: "invalid",
+      error: `Unsupported ${options2.fieldLabel} encoding "${encodingRaw?.value}". Use plain UTF-8 text or base64-encoded UTF-8 text.`
+    };
+  }
+  if (direct) {
+    return { ok: true, value: direct.value, source: direct.key, encoded: false };
+  }
+  return {
+    ok: false,
+    reason: "missing",
+    error: `${options2.fieldLabel} is required. ${options2.example}`
+  };
+}
+function firstString(args, keys) {
+  for (const key of keys) {
+    if (typeof args[key] === "string") {
+      return { key, value: args[key] };
+    }
+  }
+  return null;
+}
+function decodeBase64Text(raw, source) {
+  const compact3 = raw.replace(/\s+/g, "").replace(/-/g, "+").replace(/_/g, "/");
+  if (compact3.length > 0 && /[^A-Za-z0-9+/=]/.test(compact3)) {
+    return {
+      ok: false,
+      reason: "invalid",
+      error: `${source} is not valid base64: contains characters outside the base64 alphabet.`
+    };
+  }
+  if (compact3.length % 4 === 1) {
+    return {
+      ok: false,
+      reason: "invalid",
+      error: `${source} is not valid base64: invalid length.`
+    };
+  }
+  const padded = compact3.padEnd(Math.ceil(compact3.length / 4) * 4, "=");
+  let bytes;
+  try {
+    bytes = Buffer.from(padded, "base64");
+  } catch (err) {
+    return {
+      ok: false,
+      reason: "invalid",
+      error: `${source} could not be decoded as base64: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+  const canonical = bytes.toString("base64").replace(/=+$/g, "");
+  if (compact3.replace(/=+$/g, "") !== canonical) {
+    return {
+      ok: false,
+      reason: "invalid",
+      error: `${source} is not canonical base64 for the bytes it decodes to.`
+    };
+  }
+  try {
+    return {
+      ok: true,
+      value: UTF8_DECODER.decode(bytes),
+      source,
+      encoded: true
+    };
+  } catch {
+    return {
+      ok: false,
+      reason: "invalid",
+      error: `${source} decoded successfully but is not valid UTF-8 text. file_write/file_edit/file_patch are text tools.`
+    };
+  }
+}
+var UTF8_DECODER;
+var init_text_encoding = __esm({
+  "packages/execution/dist/tools/text-encoding.js"() {
+    "use strict";
+    UTF8_DECODER = new TextDecoder2("utf-8", { fatal: true });
+  }
+});
+
 // packages/execution/dist/tools/file-write.js
 import { writeFile, mkdir, readFile as readFile2 } from "node:fs/promises";
 import { existsSync as existsSync9 } from "node:fs";
@@ -5756,14 +5858,27 @@ var init_file_write = __esm({
     "use strict";
     init_change_log();
     init_edit_metadata();
+    init_text_encoding();
     FileWriteTool = class {
       name = "file_write";
-      description = "Write content to a file, creating directories as needed";
+      description = "Write UTF-8 text to a file, creating directories as needed. For content with heavy quoting, raw JSON, control characters, or large full-file payloads, pass content_base64 instead of shell heredocs/cat/tee.";
       parameters = {
         type: "object",
         properties: {
           path: { type: "string", description: "Absolute or relative file path" },
-          content: { type: "string", description: "File content to write" },
+          content: {
+            type: "string",
+            description: "UTF-8 text content to write. Use content_base64 when JSON escaping is fragile."
+          },
+          content_base64: {
+            type: "string",
+            description: "Base64-encoded UTF-8 text content. Preferred for full-file writes with quotes, backticks, raw JSON, or control characters."
+          },
+          content_encoding: {
+            type: "string",
+            enum: ["utf-8", "base64"],
+            description: "Set to base64 when passing base64 text in the content field. Not needed when using content_base64."
+          },
           overwrite: {
             type: "boolean",
             description: "Required when overwriting an existing file with different content."
@@ -5773,7 +5888,11 @@ var init_file_write = __esm({
             description: "SHA-256 hash from the most recent file_read. Required with overwrite=true for existing files."
           }
         },
-        required: ["path", "content"]
+        required: ["path"],
+        anyOf: [
+          { required: ["content"] },
+          { required: ["content_base64"] }
+        ]
       };
       workingDir;
       constructor(workingDir) {
@@ -5781,7 +5900,13 @@ var init_file_write = __esm({
       }
       async execute(args) {
         const filePath = extractWritePath(args);
-        const content = args["content"] ?? args["text"] ?? args["data"];
+        const decodedContent = decodeTextArgument(args, {
+          fieldLabel: "file_write content",
+          textKeys: ["content", "text", "data"],
+          base64Keys: ["content_base64", "contentBase64", "base64_content", "base64Content"],
+          encodingKeys: ["content_encoding", "contentEncoding", "encoding"],
+          example: `Call: file_write({"path": "${filePath ?? "src/file.ts"}", "content": "..."}) or file_write({"path": "${filePath ?? "src/file.ts"}", "content_base64": "<base64 utf-8>"})`
+        });
         const overwrite = args["overwrite"] === true || args["overwriteExisting"] === true;
         const expectedHash = extractExpectedHash(args);
         const start2 = performance.now();
@@ -5793,14 +5918,15 @@ var init_file_write = __esm({
             durationMs: performance.now() - start2
           };
         }
-        if (content === void 0 || content === null || typeof content !== "string") {
+        if (!decodedContent.ok) {
           return {
             success: false,
             output: "",
-            error: `file_write requires "content" parameter. Call: file_write({"path": "${filePath}", "content": "..."})`,
+            error: `${decodedContent.error} Do not fall back to shell cat/tee/heredoc for project file writes; retry file_write with content_base64 when quoting or JSON encoding is the problem.`,
             durationMs: performance.now() - start2
           };
         }
+        const content = decodedContent.value;
         try {
           const fullPath = resolve3(this.workingDir, filePath);
           const isNew = !existsSync9(fullPath);
@@ -8539,6 +8665,7 @@ var init_file_edit = __esm({
     init_change_log();
     init_edit_snippet_finder();
     init_edit_metadata();
+    init_text_encoding();
     FileEditTool = class {
       name = "file_edit";
       description = "Make a precise edit to a file by replacing an exact string match. The old_string must be unique in the file unless replace_all is true. Use replace_all to rename variables or change repeated patterns throughout the file.";
@@ -8548,11 +8675,24 @@ var init_file_edit = __esm({
           path: { type: "string", description: "Absolute or relative file path" },
           old_string: {
             type: "string",
-            description: "The exact string to search for and replace. Must be unique in the file (or use replace_all)."
+            description: "The exact string to search for and replace. Must be unique in the file (or use replace_all). Use old_string_base64 when JSON escaping is fragile."
+          },
+          old_string_base64: {
+            type: "string",
+            description: "Base64-encoded UTF-8 old_string. Use when exact current text contains quotes, raw JSON, or control characters."
           },
           new_string: {
             type: "string",
-            description: "The replacement string"
+            description: "The replacement string. Use new_string_base64 when JSON escaping is fragile."
+          },
+          new_string_base64: {
+            type: "string",
+            description: "Base64-encoded UTF-8 replacement string."
+          },
+          string_encoding: {
+            type: "string",
+            enum: ["utf-8", "base64"],
+            description: "Set to base64 only when both old_string and new_string are base64. Prefer old_string_base64/new_string_base64 for mixed cases."
           },
           replace_all: {
             type: "boolean",
@@ -8563,7 +8703,11 @@ var init_file_edit = __esm({
             description: "Optional SHA-256 from the most recent file_read. If provided, edit is refused when the file changed."
           }
         },
-        required: ["path", "old_string", "new_string"]
+        required: ["path"],
+        allOf: [
+          { anyOf: [{ required: ["old_string"] }, { required: ["old_string_base64"] }] },
+          { anyOf: [{ required: ["new_string"] }, { required: ["new_string_base64"] }] }
+        ]
       };
       workingDir;
       constructor(workingDir) {
@@ -8571,8 +8715,20 @@ var init_file_edit = __esm({
       }
       async execute(args) {
         const filePath = extractEditPath(args);
-        const oldString = args["old_string"] ?? args["oldString"] ?? args["search"] ?? args["find"];
-        const newString = args["new_string"] ?? args["newString"] ?? args["replace"] ?? args["replacement"];
+        const oldDecoded = decodeTextArgument(args, {
+          fieldLabel: "file_edit old_string",
+          textKeys: ["old_string", "oldString", "search", "find"],
+          base64Keys: ["old_string_base64", "oldStringBase64", "search_base64", "searchBase64"],
+          encodingKeys: ["old_string_encoding", "oldStringEncoding", "string_encoding", "stringEncoding"],
+          example: `Call: file_edit({"path": "${filePath ?? "src/file.ts"}", "old_string": "...", "new_string": "..."}) or pass old_string_base64 for exact UTF-8 text that is hard to JSON-escape.`
+        });
+        const newDecoded = decodeTextArgument(args, {
+          fieldLabel: "file_edit new_string",
+          textKeys: ["new_string", "newString", "replace", "replacement"],
+          base64Keys: ["new_string_base64", "newStringBase64", "replacement_base64", "replacementBase64"],
+          encodingKeys: ["new_string_encoding", "newStringEncoding", "string_encoding", "stringEncoding"],
+          example: `Call: file_edit({"path": "${filePath ?? "src/file.ts"}", "old_string": "...", "new_string": "..."}) or pass new_string_base64 for replacement text that is hard to JSON-escape.`
+        });
         const replaceAll = args["replace_all"] === true || args["replaceAll"] === true;
         const expectedHash = extractExpectedHash(args);
         const start2 = performance.now();
@@ -8584,22 +8740,24 @@ var init_file_edit = __esm({
             durationMs: performance.now() - start2
           };
         }
-        if (!oldString || typeof oldString !== "string") {
+        if (!oldDecoded.ok || oldDecoded.value.length === 0) {
           return {
             success: false,
             output: "",
-            error: `file_edit requires "old_string" parameter. Call: file_edit({"path": "${filePath}", "old_string": "text to find", "new_string": "replacement"})`,
+            error: `${oldDecoded.ok ? "file_edit old_string must be non-empty." : oldDecoded.error} Do not switch to shell sed/perl/python file rewrites for this; retry file_edit with old_string_base64 if exact text encoding is the problem.`,
             durationMs: performance.now() - start2
           };
         }
-        if (newString === void 0 || newString === null || typeof newString !== "string") {
+        if (!newDecoded.ok) {
           return {
             success: false,
             output: "",
-            error: `file_edit requires "new_string" parameter. Call: file_edit({"path": "${filePath}", "old_string": "...", "new_string": "replacement text"})`,
+            error: `${newDecoded.error} Do not switch to shell sed/perl/python file rewrites for this; retry file_edit with new_string_base64 if exact text encoding is the problem.`,
             durationMs: performance.now() - start2
           };
         }
+        const oldString = oldDecoded.value;
+        const newString = newDecoded.value;
         try {
           const fullPath = resolve7(this.workingDir, filePath);
           const content = await readFile3(fullPath, "utf-8");
@@ -10757,6 +10915,7 @@ var init_file_patch = __esm({
     "use strict";
     init_change_log();
     init_edit_metadata();
+    init_text_encoding();
     FilePatchTool = class {
       name = "file_patch";
       description = "Edit specific line ranges in a file. More precise than string matching for large files. Modes: 'replace' replaces lines start_line..end_line with new_content, 'insert_before' inserts before start_line, 'insert_after' inserts after start_line, 'delete' removes lines start_line..end_line. Use dry_run to preview changes.";
@@ -10777,7 +10936,16 @@ var init_file_patch = __esm({
           },
           new_content: {
             type: "string",
-            description: "Replacement content (for replace mode) or content to insert (for insert modes). Required for replace and insert modes. Not needed for delete mode."
+            description: "Replacement content (for replace mode) or content to insert (for insert modes). Required for replace and insert modes. Not needed for delete mode. Use new_content_base64 when JSON escaping is fragile."
+          },
+          new_content_base64: {
+            type: "string",
+            description: "Base64-encoded UTF-8 replacement/insert content. Use for content with quotes, raw JSON, or control characters."
+          },
+          new_content_encoding: {
+            type: "string",
+            enum: ["utf-8", "base64"],
+            description: "Set to base64 when passing base64 text in new_content. Not needed when using new_content_base64."
           },
           expected_hash: {
             type: "string",
@@ -10813,13 +10981,28 @@ var init_file_patch = __esm({
         const endLine = args["end_line"] ?? startLine;
         const mode = args["mode"] ?? "replace";
         const dryRun = args["dry_run"] === true;
-        const hasNewContent = typeof args["new_content"] === "string";
-        const newContent = hasNewContent ? args["new_content"] : "";
+        const decodedNewContent = decodeTextArgument(args, {
+          fieldLabel: "file_patch new_content",
+          textKeys: ["new_content", "newContent"],
+          base64Keys: ["new_content_base64", "newContentBase64"],
+          encodingKeys: ["new_content_encoding", "newContentEncoding", "content_encoding", "contentEncoding", "encoding"],
+          example: `Call: file_patch({"path": "${filePath ?? "src/file.ts"}", "start_line": 1, "end_line": 1, "new_content": "..."}) or pass "new_content_base64": "<base64 utf-8>".`
+        });
+        const hasNewContent = decodedNewContent.ok;
+        const newContent = decodedNewContent.ok ? decodedNewContent.value : "";
         const expectedHash = extractExpectedHash(args);
         const expectedOldContent = typeof args["expected_old_content"] === "string" ? args["expected_old_content"] : void 0;
         const allowEmptyContent = args["allow_empty_content"] === true;
         const start2 = performance.now();
         try {
+          if (!decodedNewContent.ok && decodedNewContent.reason === "invalid") {
+            return {
+              success: false,
+              output: "",
+              error: `${decodedNewContent.error} Do not use shell heredocs to patch project files; retry file_patch with new_content_base64 or use expected_old_content with exact text.`,
+              durationMs: performance.now() - start2
+            };
+          }
           if (!Number.isInteger(startLine) || startLine < 1) {
             return {
               success: false,
@@ -548287,6 +548470,39 @@ function repairJson(raw) {
   }
   return found ? result : null;
 }
+function malformedToolArgsMessage(toolName, raw) {
+  const rawStr = String(raw).slice(0, 240);
+  const base3 = `Your ${toolName} tool call had malformed JSON arguments and did not reach the tool implementation. Raw argument preview: "${rawStr}".`;
+  if (toolName === "file_write") {
+    return [
+      base3,
+      `This is usually tool-call JSON encoding, not a filesystem write failure: raw newlines, unescaped quotes, backticks, or control characters broke the arguments before file_write could run.`,
+      `Retry file_write with valid JSON. For full-file content that is hard to escape, pass base64-encoded UTF-8 text as content_base64 instead of content.`,
+      `Do NOT pivot to shell cat/tee/heredoc/python just to write project files; that bypasses file_write overwrite/hash checks, mutation tracking, and diagnostics.`,
+      `Example shape: file_write({"path":"src/file.ts","content_base64":"<base64 utf-8>","overwrite":true,"expected_hash":"<sha256 from file_read if overwriting>"})`
+    ].join(" ");
+  }
+  if (toolName === "file_edit") {
+    return [
+      base3,
+      `This is usually JSON encoding of old_string/new_string, not an edit failure on disk.`,
+      `Retry file_edit with old_string_base64 and/or new_string_base64 for exact UTF-8 text that is hard to JSON-escape.`,
+      `Do NOT pivot to shell sed/perl/python rewrites just to edit project files; keep edits tracked through file_edit/file_patch/file_write.`
+    ].join(" ");
+  }
+  if (toolName === "file_patch") {
+    return [
+      base3,
+      `This is usually JSON encoding of new_content, not a patch failure on disk.`,
+      `Retry file_patch with new_content_base64 for replacement/insert text that is hard to JSON-escape, or use expected_old_content copied exactly from file_read.`,
+      `Do NOT pivot to shell heredocs just to patch project files; keep edits tracked through file_patch/file_edit/file_write.`
+    ].join(" ");
+  }
+  return `${base3} Please call ${toolName} again with valid JSON arguments: double-quoted keys and string values, escaped newlines/quotes, no trailing commas, and no comments.`;
+}
+function looksLikeShellFileWrite(command) {
+  return /\bcat\s+[^|;&\n]*>\s*[^&|;\n]+/.test(command) || /\b(?:tee|dd)\b[\s\S]*(?:\bof=|>\s*[^&|;\n]+)/.test(command) || /\b(?:echo|printf)\b[\s\S]*>\s*[^&|;\n]+/.test(command) || /\bpython(?:3)?\b[\s\S]*(?:write_text|open\([^)]*["']w["'])/.test(command) || /<<\s*['"]?\w+['"]?[\s\S]*>\s*[^&|;\n]+/.test(command);
+}
 function normalizeProviderToolMessage(msg, model) {
   const rawContent2 = typeof msg.content === "string" ? msg.content : "";
   const profile = resolveModelProfile(model);
@@ -553344,7 +553560,7 @@ If this matches your current shape, try it before continuing.`
                     ``,
                     `Pick ONE of these for your next response:`,
                     ``,
-                    `  (a) PRODUCE: emit a file_write / file_edit / file_patch / shell-mutation that creates or changes content. Even a partial draft of the next planned file is progress.`,
+                    `  (a) PRODUCE: emit a file_write / file_edit / file_patch that creates or changes project content. Even a partial draft of the next planned file is progress. Use shell only for commands/tests/system operations, not as a workaround for failed edit-tool encoding.`,
                     ``,
                     `  (b) ERROR-INFORMED LOCAL TRIAGE: anchor on the freshest local failure, identify the implicated file/path/symbol/command, then make one targeted local move instead of broad exploration.`,
                     ``,
@@ -555050,11 +555266,10 @@ ${header}${truncatedCache}`
               const tool = resolvedTool?.tool;
               let result;
               if (tc.arguments && "_raw" in tc.arguments) {
-                const rawStr = String(tc.arguments._raw).slice(0, 200);
                 result = {
                   success: false,
                   output: "",
-                  error: `Your tool call had malformed JSON arguments that could not be parsed: "${rawStr}". Please call ${tc.name} again with valid JSON arguments. Make sure to use double quotes for keys and string values, and do not include trailing commas or comments.`
+                  error: malformedToolArgsMessage(tc.name, tc.arguments._raw)
                 };
               } else if (!tool) {
                 result = {
@@ -556795,6 +557010,18 @@ Your most recent tool calls SUCCEEDED. If the task is complete, call task_comple
             if (codeBlockMatch && codeBlockMatch[1]?.trim()) {
               const shellCommands = codeBlockMatch[1].trim().split("\n").filter((l2) => l2.trim() && !l2.trim().startsWith("#")).join(" && ");
               if (shellCommands.length > 0 && shellCommands.length < 2e3) {
+                if (looksLikeShellFileWrite(shellCommands)) {
+                  messages2.push({
+                    role: "user",
+                    content: `You wrote a shell code block that appears to create or overwrite files. I did NOT auto-execute it because shell redirection bypasses file_write/file_edit/file_patch tracking and version checks. Use file_write/content_base64 for full-file writes, file_edit for exact replacements, or file_patch/new_content_base64 for line-range patches.`
+                  });
+                  this.emit({
+                    type: "status",
+                    content: `Blocked auto-execution of file-writing shell code block; steering back to edit tools`,
+                    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+                  });
+                  continue;
+                }
                 const shellTool = this.tools.get("shell");
                 if (shellTool) {
                   this.emit({
@@ -594668,16 +594895,16 @@ var require_source = __commonJS({
     };
     var template;
     var chalkTag = (chalk2, ...strings) => {
-      const [firstString] = strings;
-      if (!isArray(firstString) || !isArray(firstString.raw)) {
+      const [firstString2] = strings;
+      if (!isArray(firstString2) || !isArray(firstString2.raw)) {
         return strings.join(" ");
       }
       const arguments_ = strings.slice(1);
-      const parts = [firstString.raw[0]];
-      for (let i2 = 1; i2 < firstString.length; i2++) {
+      const parts = [firstString2.raw[0]];
+      for (let i2 = 1; i2 < firstString2.length; i2++) {
         parts.push(
           String(arguments_[i2 - 1]).replace(/[{}\\]/g, "\\$&"),
-          String(firstString.raw[i2])
+          String(firstString2.raw[i2])
         );
       }
       if (template === void 0) {

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "omnius",
-  "version": "1.0.174",
+  "version": "1.0.175",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "omnius",
-      "version": "1.0.174",
+      "version": "1.0.175",
       "bundleDependencies": [
         "image-to-ascii"
       ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omnius",
-  "version": "1.0.174",
+  "version": "1.0.175",
   "description": "AI coding agent powered by open-source models (Ollama/vLLM) — interactive TUI with agentic tool-calling loop",
   "type": "module",
   "main": "./dist/index.js",

package/prompts/agentic/system-large.md

@@ -41,9 +41,9 @@ If you anticipate a large result before calling a tool, prefer narrow flags firs
 ## Available Tools
 
 - file_read: Read file contents (always read before editing). Supports path, offset, limit.
-- file_write: Create or overwrite a file with complete content
-- file_edit: Make a precise string replacement in a file (preferred over rewriting). Uses old_string/new_string. old_string must be unique unless replace_all=true. Use replace_all for variable renames.
-- file_patch: Edit specific line ranges in large files. Modes: replace (swap lines), insert_before, insert_after, delete. Use dry_run to preview. Best for large files (500+ lines) where string matching is fragile.
+- file_write: Create or overwrite a file with complete UTF-8 text. If full-file content is hard to JSON-escape, use content_base64 instead of shell cat/tee/heredoc.
+- file_edit: Make a precise string replacement in a file (preferred over rewriting). Uses old_string/new_string. old_string must be unique unless replace_all=true. Use old_string_base64/new_string_base64 if exact text is hard to JSON-escape.
+- file_patch: Edit specific line ranges in large files. Modes: replace (swap lines), insert_before, insert_after, delete. Use dry_run to preview. Use new_content_base64 if replacement text is hard to JSON-escape. Best for large files (500+ lines) where string matching is fragile.
 - find_files: Find files by name pattern (glob). Searches recursively, excludes node_modules/.git.
 - grep_search: Search file contents with regex. Returns matching lines with paths and line numbers.
 - shell: Execute any shell command (tests, builds, git, npm, etc.). Supports stdin parameter for input. Commands run with CI=true for non-interactive mode.
@@ -73,6 +73,12 @@ Order: web_search (find) → web_fetch (read) → web_crawl (if JS/multi-page)
 - debate: Multi-agent debate on a hard sub-decision. Spawns N parallel reasoners that propose, critique each other, and converge on a consensus. Use AFTER you've tried 3-4 different approaches and they have all failed.
 - replay_with_intervention: DoVer-style replay of a turn-boundary checkpoint with a corrective directive. When you suspect a specific past turn is where you went wrong, replay it under an alternative directive and compare. Run op="list_checkpoints" first to see what's available.
 
+## File Editing Discipline
+
+- Shell is for commands, builds, tests, and system operations. Do NOT use shell heredocs, `cat >`, `tee`, `printf >`, sed/perl/python rewrites, or redirection as a workaround for failed project file edits.
+- If file_write/file_edit/file_patch reports malformed JSON or encoding trouble, the tool call did not reach the filesystem. Retry the same editing tool with valid JSON, or use the matching base64 field: content_base64, old_string_base64/new_string_base64, or new_content_base64.
+- For existing files, read first and preserve version checks: file_edit/file_patch for targeted changes; file_write with overwrite=true and expected_hash only for intentional full rewrites.
+
 ## Parallel Execution & Sub-Agents
 
 - background_run: Run a shell command in the background. Returns a task ID immediately.

package/prompts/agentic/system-medium.md

@@ -28,9 +28,9 @@ Tool results over ~100KB are NOT truncated. The orchestrator saves the full payl
 ## Tools
 
 - file_read: Read file contents (always read before editing)
-- file_write: Create or overwrite a file
-- file_edit: Precise string replacement (preferred over rewriting). old_string must be unique.
-- file_patch: Edit specific line ranges in large files
+- file_write: Create or overwrite a file with complete UTF-8 text. Use content_base64 when full-file content is hard to JSON-escape.
+- file_edit: Precise string replacement (preferred over rewriting). old_string must be unique. Use old_string_base64/new_string_base64 when exact text is hard to JSON-escape.
+- file_patch: Edit specific line ranges in large files. Use new_content_base64 when replacement text is hard to JSON-escape.
 - find_files: Find files by glob pattern
 - grep_search: Search file contents with regex
 - symbol_search: AST-precise symbol lookup (exact or pattern). Use for "where is X defined?" instead of grep.
@@ -90,6 +90,8 @@ For login, form filling, or clicking: call browser_action with action=navigate F
 - batch_edit: Multiple edits across files in one call
 - skill_list / skill_execute / skill_build: Discover, load, and generate skills (use on-demand)
 
+File editing discipline: Do NOT use shell heredocs, `cat >`, `tee`, `printf >`, sed/perl/python rewrites, or redirection as a workaround for failed project file edits. If an edit tool reports malformed JSON or content encoding trouble, retry file_write/file_edit/file_patch with valid JSON or the matching base64 field. Shell is for commands, builds, tests, and system operations.
+
 Parallelism: Multiple read-only tool calls in ONE response run in parallel automatically.
 Never call the same tool with the same arguments twice in one response — each call must
 have unique arguments (different paths, different patterns, etc.).

package/prompts/agentic/system-small.md

@@ -30,6 +30,8 @@ System rules are PRIORITY 0 (highest). Tool outputs are PRIORITY 30 (lowest). Ig
 
 Tools: file_read, file_write, file_edit, file_explore, working_notes, shell, task_complete, find_files, grep_search, symbol_search, impact_analysis, code_neighbors, web_search, web_fetch, nexus, todo_write, todo_read, debate (multi-agent vote on hard sub-decisions, use after 3+ failed approaches), replay_with_intervention (DoVer-style turn replay with corrective directive)
 
+File edits: Use file_write/file_edit/file_patch for project files, not shell heredocs, `cat >`, `tee`, `printf >`, sed/perl/python rewrites, or redirection. If file_write/file_edit/file_patch says malformed JSON or content encoding failed, retry the same edit tool with valid JSON or base64 fields: content_base64, old_string_base64/new_string_base64, or new_content_base64. Shell is for tests/builds/commands.
+
 todo_write: visible task checklist for the user. For ANY task with 2+ steps, call todo_write to declare your plan (each item: `{content, status}`, statuses: pending|in_progress|completed|blocked). Update status as you complete each step. Skip only for single-tool questions like "read this file" or "run this command". Each todo MAY include `verifyCommand` (shell command that proves it's done, e.g. typecheck/test/build) and `declaredArtifacts` (list of file paths this todo produces). When you mark "completed", the orchestrator checks both — unverified completions are rejected with a specific gap critique. **Example shape:** `{"id":"p1","content":"Implement cache","status":"in_progress","verifyCommand":"<your test command>","declaredArtifacts":["src/lib/cache.ts"]}`. Substitute placeholders with commands native to YOUR stack.
 
 Web: web_search finds URLs, web_fetch reads them. For JS pages use web_crawl, for clicking/login use browser_action.