@sema-agent/core 2.0.1 → 2.2.0

package/dist/tools/fs/fs-read.js

@@ -15,10 +15,10 @@ export function createReadFileTool(env, state, rootCanonical, cwdRef, additional
             "\n" +
             "- `file_path` may be relative (resolved against the tracked working directory) or absolute (within the configured roots).\n" +
             "- By default, it reads the whole file (from `offset`, 1-based); a very large file is served as a partial view with an explicit marker and the next-page call.\n" +
-            "- When you already know which part of the file you need, only read that part. This can be important for larger files.\n" +
+            "- You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the whole file by not providing these parameters\n" +
             "- Results are returned using cat -n format, with line numbers starting at 1\n" +
             "- Reads images (PNG, JPG, …) and presents them visually. Reads PDFs via the `pages` parameter (e.g. \"1-5\", max 20 pages/request; a PDF whose detected page count exceeds 10 requires `pages`). Reads Jupyter notebooks (.ipynb) as cells with outputs (offset/limit do not apply).\n" +
-            "- Reading a directory, a missing file, or an empty file returns an error or warning rather than content.\n" +
+            "- Reading a directory, a missing file, or an empty file returns an error or system reminder rather than content.\n" +
             "- Other binaries (archives, executables) are refused. A whole-file read of a text file over 256 KB is refused — read it in slices with explicit offset/limit, or Grep it instead.\n" +
             "- You must read a file before editing it.\n" +
             "- Do NOT re-read a file you just edited to verify — Edit/Write would have errored if the change failed, and the harness tracks file state for you.",
@@ -26,7 +26,7 @@ export function createReadFileTool(env, state, rootCanonical, cwdRef, additional
             "\n" +
             "Usage:\n" +
             "- By default, it reads the whole file (from `offset`, 1-based); a very large file is served as a partial view with an explicit marker and the next-page call\n" +
-            "- When you already know which part of the file you need, only read that part. This can be important for larger files.\n" +
+            "- You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the whole file by not providing these parameters\n" +
             "- Results are returned using cat -n format, with each line prefixed by its line number and a tab\n" +
             "- This tool allows the model to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually.\n" +
             "- This tool can only read files, not directories. To read a directory, use Glob/Grep or an ls command via the Bash tool.\n" +
@@ -34,7 +34,7 @@ export function createReadFileTool(env, state, rootCanonical, cwdRef, additional
             "- Reads PDFs (.pdf): the document is provided to the model directly (text layer included). Use the `pages` parameter (e.g., \"1-5\") to read a page range; a PDF whose detected page count exceeds 10 requires `pages`. Maximum 20 pages per request.\n" +
             "- Reads Jupyter notebooks (.ipynb) as cells with outputs (offset/limit do not apply).\n" +
             "- Other binaries (archives, executables) are refused. A whole-file read of a text file over 256 KB is refused — read it in slices with explicit offset/limit, or Grep it instead.\n" +
-            "- If you read a file that exists but has empty contents you will receive a warning in place of file contents.\n" +
+            "- If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.\n" +
             "- Do NOT re-read a file you just edited to verify — Edit/Write would have errored if the change failed, and the harness tracks file state for you.",
         parameters: Type.Object({
             ...FILE_PATH_PARAMS,
@@ -129,7 +129,7 @@ export function createReadFileTool(env, state, rootCanonical, cwdRef, additional
                         `(${info.value.size} bytes > ${SLICED_READ_MAX_BYTES}-byte cap — the reader loads the whole file into memory before slicing). ` +
                         `Stream a portion with bash instead, e.g. \`sed -n '1,200p' <file>\` for a line range or \`head -c 65536 <file>\` for the leading bytes, or use grep to search it.`);
                 }
-                if (!isNb && info.value.size > MAX_READ_BYTES && offset === undefined && limit === undefined) {
+                if (!isNb && info.value.size > MAX_READ_BYTES && limit === undefined) {
                     return errorResult(`Error (Read): "${path}" is too large to read in full (${info.value.size} bytes > ${MAX_READ_BYTES}-byte cap); pass an explicit offset/limit to read a slice, or use grep to search it instead.`);
                 }
             }
@@ -147,7 +147,7 @@ export function createReadFileTool(env, state, rootCanonical, cwdRef, additional
                     `(${readSize} bytes > ${SLICED_READ_MAX_BYTES}-byte cap — the reader loads the whole file into memory before slicing). ` +
                     `Stream a portion with bash instead, e.g. \`sed -n '1,200p' <file>\` for a line range or \`head -c 65536 <file>\` for the leading bytes, or use grep to search it.`);
             }
-            if (!isNb && readSize > MAX_READ_BYTES && offset === undefined && limit === undefined) {
+            if (!isNb && readSize > MAX_READ_BYTES && limit === undefined) {
                 return errorResult(`Error (Read): "${path}" is too large to read in full (${readSize} bytes > ${MAX_READ_BYTES}-byte cap); pass an explicit offset/limit to read a slice, or use grep to search it instead.`);
             }
             if (pdfMagicMatches(readBin.value)) {
@@ -158,7 +158,7 @@ export function createReadFileTool(env, state, rootCanonical, cwdRef, additional
                 return errorResult(`Error (Read): "${path}" has a UTF-16 BOM but a truncated (odd-length) body — the file is corrupt or mis-labelled; repair/convert it with bash (e.g. \`iconv\`) first.`);
             }
             const content = decoded.text;
-            if (isBinaryContent(content.slice(0, 4096))) {
+            if (isBinaryContent(content.slice(0, 8192))) {
                 return errorResult(`Error (Read): "${path}" appears to be a binary file (non-text content); this tool reads UTF-8 and BOM-marked UTF-16LE text only. ` +
                     `If it is UTF-16 without a BOM or a legacy encoding, convert it first (e.g. \`iconv -f UTF-16LE -t UTF-8\`) or inspect/transform it with bash.`);
             }
@@ -193,10 +193,10 @@ export function createReadFileTool(env, state, rootCanonical, cwdRef, additional
                             `  cat "${path}" | jq '.cells[] | select(.cell_type=="code") | .source' # All code sources`);
                     }
                     const prevNb = state.get(r.key);
-                    if (prevNb?.seededFromContext && prevNb.hash === hash) {
+                    if (prevNb?.seededFromContext && !prevNb.isPartialView && prevNb.hash === hash) {
                         return seededFileUnchangedReminder(r.key);
                     }
-                    if (prevNb && prevNb.hash === hash && prevNb.view && prevNb.view.start === 1 && prevNb.view.end === total) {
+                    if (prevNb && !prevNb.isPartialView && prevNb.hash === hash && prevNb.view && prevNb.view.start === 1 && prevNb.view.end === total) {
                         return `[${path}: unchanged since you last read it (lines 1-${total} of ${total}); content omitted to save context]`;
                     }
                     state.set(r.key, { hash, totalLines: countLines(content), truncated: false, view: { start: 1, end: total }, lastReadAt: Date.now() });
@@ -250,10 +250,10 @@ export function createReadFileTool(env, state, rootCanonical, cwdRef, additional
             }
             const truncated = start > 1 || end < total || pageMarker !== undefined;
             const prev = state.get(r.key);
-            if (total > 0 && prev?.seededFromContext && start === 1 && effLimit === undefined && prev.hash === hash) {
+            if (total > 0 && prev?.seededFromContext && !prev.isPartialView && start === 1 && effLimit === undefined && prev.hash === hash) {
                 return seededFileUnchangedReminder(r.key);
             }
-            if (total > 0 && prev && prev.hash === hash && prev.view && prev.view.start === start && prev.view.end === end) {
+            if (total > 0 && prev && !prev.isPartialView && prev.hash === hash && prev.view && prev.view.start === start && prev.view.end === end) {
                 return `[${path}: unchanged since you last read it (lines ${start}-${end} of ${total}); content omitted to save context]`;
             }
             state.set(r.key, {
@@ -265,7 +265,7 @@ export function createReadFileTool(env, state, rootCanonical, cwdRef, additional
                 lastReadAt: Date.now(),
             });
             if (total === 0)
-                return `<system-reminder>Warning: the file exists but is shorter than the provided offset (${start}). The file has 1 lines.</system-reminder>`;
+                return `<system-reminder>Warning: the file exists but the contents are empty.</system-reminder>`;
             const header = pageMarker ?? (truncated ? `[${path}: lines ${start}-${end} of ${total}${end < total ? " — use offset to see more" : ""}]\n` : "");
             return {
                 content: `${nbFallbackPrefix}${header}${body}${READ_CYBER_REMINDER}`,

package/dist/tools/fs/fs-search-tools.js

@@ -1,21 +1,22 @@
 import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
 import { resolveKey, violationText } from "./safety.js";
-import { runGrepDetailed, runGlobDetailed, splitAbsoluteGlobPattern } from "./search.js";
+import { runGrepDetailed, runGlobDetailed, splitAbsoluteGlobPattern, invalidGlobTokens } from "./search.js";
 export function createGrepTool(env, rootCanonical, additionalRoots) {
     return defineTool({
         name: "Grep",
         contract: { contractId: "core.grep@1", implementationRevision: "1" },
         description: "Content search built on ripgrep. Prefer this over `grep`/`rg` via Bash — results integrate with the permission UI and file links.\n" +
+            "\n" +
             '- Full regex syntax (e.g. "log.*Error", "function\\s+\\w+"). Ripgrep, not grep — escape literal braces (`interface\\{\\}`).\n' +
             '- Filter with `glob` (e.g. "**/*.tsx") or `type` (e.g. "js", "py", "rust").\n' +
             '- `output_mode`: "content" (matching lines), "files_with_matches" (paths only, default), or "count".\n' +
             "- `multiline: true` for patterns that span lines.\n" +
             "- Uses ripgrep when available (respects .gitignore, skips binary files and VCS directories), otherwise a JS fallback that skips node_modules/build/… and parses .gitignore. Hidden files/directories ARE searched.\n" +
-            "- Use Agent tool for open-ended searches requiring multiple rounds",
+            "- Use Agent tool (if available) for open-ended searches requiring multiple rounds",
         parameters: Type.Object({
             pattern: Type.String({ description: "The regular expression pattern to search for in file contents" }),
-            path: Type.Optional(Type.String({ description: "Restrict to a sub-directory (relative to root)." })),
+            path: Type.Optional(Type.String({ description: "File or directory to search in (rg PATH). Relative paths resolve against the root; defaults to the whole root." })),
             glob: Type.Optional(Type.String({ description: 'Glob pattern to filter files (e.g. "*.js", "*.{ts,tsx}")' })),
             type: Type.Optional(Type.String({ description: 'File type to search (rg --type): "js", "py", "rust", "go", "java", etc. More efficient than glob for standard file types.' })),
             output_mode: Type.Optional(Type.Union([Type.Literal("content"), Type.Literal("files_with_matches"), Type.Literal("count")], {
@@ -41,6 +42,23 @@ export function createGrepTool(env, rootCanonical, additionalRoots) {
         effect: "read",
         execute: async (args, ctx) => {
             const a = args;
+            for (const [name, value] of [
+                ["head_limit", a.head_limit],
+                ["offset", a.offset],
+            ]) {
+                if (value !== undefined && (!Number.isInteger(value) || value < 0)) {
+                    return errorResult(`Error (Grep): ${name} must be a whole number of 0 or more, got ${value}.${name === "head_limit" ? " Pass 0 for unlimited." : ""}`);
+                }
+            }
+            if (typeof a.glob === "string" && a.glob.length > 0) {
+                const badGlobs = invalidGlobTokens(a.glob);
+                if (badGlobs.length > 0) {
+                    return errorResult(`Error (Grep): rejected the glob ${badGlobs.map((g) => JSON.stringify(g)).join(", ")} without searching — ` +
+                        `an unterminated \`[\` class or \`{\` group cannot be compiled as a glob, and matching it literally would ` +
+                        `silently narrow the search to a file with that exact name (an empty result would NOT mean "no matches"). ` +
+                        `Close the bracket/brace, or drop \`glob\` and filter with \`path\`/\`type\` instead.`);
+                }
+            }
             let scoped = a.path;
             if (a.path !== undefined) {
                 const r = await resolveKey(env, rootCanonical, a.path, ctx.signal, rootCanonical, additionalRoots);
@@ -77,9 +95,14 @@ export function createGrepTool(env, rootCanonical, additionalRoots) {
                 const m = /^(.*?):(\d+):/.exec(l);
                 return m ? m[1] : l;
             };
+            const capMarker = /^…\[capped at (\d+) of (\d+)\]$/m.exec(text);
+            const cappedAt = capMarker ? Number(capMarker[1]) : undefined;
+            const capTotal = capMarker ? Number(capMarker[2]) : undefined;
+            const appliedOffset = typeof a.offset === "number" && a.offset > 0 ? { appliedOffset: a.offset } : {};
+            const appliedLimit = cappedAt !== undefined ? { appliedLimit: cappedAt } : {};
             let detailFields;
             if (mode === "files_with_matches") {
-                detailFields = { filenames: rows, numFiles: rows.length };
+                detailFields = { filenames: rows, numFiles: rows.length, totalFiles: capTotal ?? rows.length, ...appliedLimit, ...appliedOffset };
             }
             else if (mode === "count") {
                 const filenames = [...new Set(rows.map((l) => (l.includes(":") ? l.slice(0, l.lastIndexOf(":")) : l)))];
@@ -92,7 +115,14 @@ export function createGrepTool(env, rootCanonical, additionalRoots) {
                     else
                         malformed = true;
                 }
-                detailFields = { filenames, numFiles: filenames.length, ...(malformed ? {} : { numMatches }) };
+                detailFields = {
+                    filenames,
+                    numFiles: filenames.length,
+                    content: rows.join("\n"),
+                    ...(malformed ? {} : { numMatches }),
+                    ...appliedLimit,
+                    ...appliedOffset,
+                };
             }
             else {
                 const filenames = [...new Set(rows.map(contentPathOf))];
@@ -103,6 +133,9 @@ export function createGrepTool(env, rootCanonical, additionalRoots) {
                     numFiles: filenames.length,
                     content: joined.length > GREP_CONTENT_PREVIEW_CHARS ? `${joined.slice(0, GREP_CONTENT_PREVIEW_CHARS)}\n…[truncated — full text in the tool output]` : joined,
                     numLines: rows.length,
+                    totalLines: capTotal ?? rows.length,
+                    ...appliedLimit,
+                    ...appliedOffset,
                 };
             }
             return {
@@ -126,10 +159,12 @@ export function createGlobTool(env, rootCanonical, additionalRoots) {
             "- On environments that do not report modification times, results fall back to alphabetical order\n" +
             "- Paths are RELATIVE to the root; ignored trees (node_modules/build/.gitignore) are skipped unless your pattern names them explicitly (e.g. `dist/**`)\n" +
             "- Use this tool when you need to find files by name patterns; use `path` to scope to a sub-directory\n" +
-            "- When you are doing an open ended search that may require multiple rounds of globbing and grepping, use the Agent tool instead",
+            "- When you are doing an open ended search that may require multiple rounds of globbing and grepping, use the Agent tool instead (if available)",
         parameters: Type.Object({
             pattern: Type.String({ description: "Glob pattern (`*`, `**`, `?`)." }),
-            path: Type.Optional(Type.String({ description: "Scope the search to this sub-directory (relative to root)." })),
+            path: Type.Optional(Type.String({
+                description: 'Scope the search to this sub-directory (relative to root). IMPORTANT: Omit this field to search the whole root. DO NOT enter "undefined" or "null" - simply omit it for the default behavior. Must be a valid directory path if provided.',
+            })),
             max_results: Type.Optional(Type.Number({ description: "Cap results (default 500)." })),
         }),
         effect: "read",

package/dist/tools/fs/fs-write.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
-import { sha256, resolveKey, violationText, requireRead, checkStale, checkEditMatch, checkNoChange, fileArgPath, resolveQuoteMatch, adaptNewStringQuotes, deletionOldString, countOccurrences, WRITE_ENCODING_DEADLOCK_ESCAPE_HINT, } from "./safety.js";
+import { sha256, resolveKey, violationText, requireRead, checkStale, checkEditMatch, checkNoChange, fileArgPath, resolveQuoteMatch, adaptNewStringQuotes, resolveEscapeMatch, adaptNewStringEscapes, escapeMatchWasAttempted, ESCAPE_MATCH_MISS_NOTE, deletionOldString, countOccurrences, WRITE_ENCODING_DEADLOCK_ESCAPE_HINT, } from "./safety.js";
 import { decodeTextBytes, encodeTextForFile, normalizeEditText, normalizeFileText } from "./encoding.js";
 import { MAX_EDIT_BYTES, formatByteSize, decodeEditBytes, persistedTextOf, notReadRefusalText, enoentMessage, FILE_STATE_TRAILER, FILE_PATH_PARAMS, ipynbRedirect, countLines, } from "./fs-shared.js";
 async function gateToolWrite(hook, tool, path, key, content) {
@@ -54,12 +54,12 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
             const path = fileArgPath(args);
             if (path === undefined)
                 return errorResult(`Error (Edit): file_path is required.`);
-            const ipynb = ipynbRedirect("Edit", path);
-            if (ipynb)
-                return errorResult(ipynb);
             const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots);
             if (!r.ok)
                 return errorResult(violationText("Edit", r.violation));
+            if (!batch && a.old_string === a.new_string) {
+                return errorResult(violationText("Edit", { code: "invalid", message: "No changes to make: old_string and new_string are exactly the same." }));
+            }
             const singleOld = batch ? undefined : a.old_string;
             const exists = await env.exists(r.key, ctx.signal);
             if (!exists.ok)
@@ -132,6 +132,9 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
                     details: { type: "edit", filePath: path, originalFile: preDec.text, oldString: "", newString: newContent, replaceAll: false, edits: [{ oldString: "", newString: newContent, replaceAll: false }] },
                 };
             }
+            const ipynb = ipynbRedirect("Edit", path);
+            if (ipynb)
+                return errorResult(ipynb);
             const notRead = requireRead(state, r.key);
             if (notRead)
                 return errorResult(await notReadRefusalText(env, "Edit", r.key, notRead, ctx.signal));
@@ -170,9 +173,18 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
                         oldS = resolved;
                     }
                 }
+                if (oldS !== "" && !working.includes(oldS)) {
+                    const resolvedEsc = resolveEscapeMatch(working, oldS);
+                    if (resolvedEsc !== undefined && resolvedEsc !== oldS) {
+                        newS = adaptNewStringEscapes(oldS, resolvedEsc, newS);
+                        oldS = resolvedEsc;
+                    }
+                }
                 const match = checkEditMatch(working, oldS, e.replace_all === true, entry.truncated);
-                if (match)
-                    return errorResult(batch ? `Error (Edit): ${where}${match.message} (no changes written — the batch is atomic).` : violationText("Edit", match));
+                if (match) {
+                    const escNote = match.code === "ambiguous_edit" && escapeMatchWasAttempted(e.old_string) && !working.includes(oldS) ? ESCAPE_MATCH_MISS_NOTE : "";
+                    return errorResult(batch ? `Error (Edit): ${where}${match.message}${escNote} (no changes written — the batch is atomic).` : `${violationText("Edit", match)}${escNote}`);
+                }
                 replacements += e.replace_all === true ? countOccurrences(working, oldS) : 1;
                 const effOld = e.replace_all === true ? oldS : deletionOldString(working, oldS, newS);
                 working = e.replace_all === true ? working.split(effOld).join(newS) : working.replace(effOld, () => newS);

package/dist/tools/fs/index.d.ts

@@ -29,6 +29,7 @@ export interface HandsToolkitOptions {
     }) => void;
     detachHub?: import("../../core/tool-detach.js").ToolDetachHub;
     execClamp?: ExecClampOption;
+    oneShot?: boolean;
     autoBackgroundOnTimeout?: boolean;
     readImageDownsampler?: ReadImageDownsamplerOption;
     pdfModelCapabilities?: PdfModelCapabilities;

package/dist/tools/fs/index.js

@@ -45,11 +45,12 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
                 detachHub: opts.detachHub,
                 execClamp: opts.execClamp,
                 ...(opts.autoBackgroundOnTimeout !== undefined ? { autoBackgroundOnTimeout: opts.autoBackgroundOnTimeout } : {}),
+                ...(opts.oneShot !== undefined ? { oneShot: opts.oneShot } : {}),
             }));
         if (!readOnly && mountBackgroundTaskTools && hasBackgroundShell(env)) {
             const sessionAxis = opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {};
             tools.push(opts.taskRegistry
-                ? createTaskOutputTool({ registry: opts.taskRegistry, owner: opts.taskOwner, scope: opts.taskScope, ...sessionAxis })
+                ? createTaskOutputTool({ registry: opts.taskRegistry, owner: opts.taskOwner, scope: opts.taskScope, ...sessionAxis, ...(opts.oneShot !== undefined ? { oneShot: opts.oneShot } : {}) })
                 : createEnvTaskOutputTool(env), opts.taskRegistry
                 ? createTaskStopTool({ registry: opts.taskRegistry, owner: opts.taskOwner, scope: opts.taskScope, ...sessionAxis })
                 : createEnvTaskStopTool(env));

package/dist/tools/fs/safety.d.ts

@@ -53,6 +53,10 @@ export declare function countOccurrences(haystack: string, needle: string): numb
 export declare function similarNameSuggestion(siblingNames: readonly string[], missingName: string): string | undefined;
 export declare function normalizeQuotes(s: string): string;
 export declare function resolveQuoteMatch(content: string, oldString: string): string | undefined;
+export declare function resolveEscapeMatch(content: string, oldString: string): string | undefined;
+export declare function adaptNewStringEscapes(oldString: string, matchedOld: string, newString: string): string;
+export declare function escapeMatchWasAttempted(oldString: string): boolean;
+export declare const ESCAPE_MATCH_MISS_NOTE = "\n(note: Edit also tried swapping \\uXXXX escapes and their characters; neither form matched, so the mismatch is likely elsewhere in old_string. Re-read the file and copy the exact surrounding text.)";
 export declare function adaptNewStringQuotes(matchedOld: string, newString: string): string;
 export declare function deletionOldString(content: string, oldString: string, newString: string): string;
 export declare function checkEditMatch(content: string, oldString: string, replaceAll: boolean, truncated: boolean): FsViolation | undefined;

package/dist/tools/fs/safety.js

@@ -38,17 +38,26 @@ const BLOCKED_DEVICE_PATHS = new Set([
     "/dev/stdin", "/dev/stdout", "/dev/stderr", "/dev/tty", "/dev/console",
     "/dev/fd/0", "/dev/fd/1", "/dev/fd/2",
 ]);
-const PROC_FD_RE = /^\/proc\/[^/]+\/fd\/[0-2]$/;
+function isProcStdioFd(key) {
+    return key.startsWith("/proc/") && (key.endsWith("/fd/0") || key.endsWith("/fd/1") || key.endsWith("/fd/2"));
+}
+const PROC_SENSITIVE_SUFFIXES = ["/environ", "/cmdline", "/auxv", "/maps", "/mem", "/stat"];
+function isProcSensitiveFile(key) {
+    return key.startsWith("/proc/") && PROC_SENSITIVE_SUFFIXES.some((suf) => key.endsWith(suf));
+}
 const WIN_RESERVED_RE = /^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(\.[^\\/]*)?$/i;
+function isWinFormPath(p) {
+    return /^[A-Za-z]:[\\/]/.test(p) || p.startsWith("\\\\") || (!p.startsWith("/") && p.includes("\\"));
+}
 function isWinReservedDeviceKey(key) {
-    if (!(/^[A-Za-z]:[\\/]/.test(key) || key.startsWith("\\\\") || (!key.startsWith("/") && key.includes("\\"))))
+    if (!isWinFormPath(key))
         return false;
     const t = key.replace(/[\\/]+$/, "");
     const base = t.slice(Math.max(t.lastIndexOf("/"), t.lastIndexOf("\\")) + 1);
     return WIN_RESERVED_RE.test(base);
 }
 export function isBlockedDevicePath(key) {
-    return BLOCKED_DEVICE_PATHS.has(key) || PROC_FD_RE.test(key) || isWinReservedDeviceKey(key);
+    return BLOCKED_DEVICE_PATHS.has(key) || isProcStdioFd(key) || isProcSensitiveFile(key) || isWinReservedDeviceKey(key);
 }
 export function normalizeAbsPathLexically(p) {
     if (!p.startsWith("/"))
@@ -67,12 +76,16 @@ export function normalizeAbsPathLexically(p) {
 }
 const BINARY_EXTENSIONS = new Set([
     ".exe", ".dll", ".so", ".dylib", ".o", ".a", ".obj", ".lib", ".bin", ".class", ".pyc", ".pyo", ".wasm",
-    ".zip", ".tar", ".gz", ".tgz", ".bz2", ".xz", ".7z", ".rar", ".jar", ".war", ".ear", ".lz4", ".zst",
+    ".app", ".msi", ".deb", ".rpm", ".node", ".rlib",
+    ".zip", ".tar", ".gz", ".tgz", ".bz2", ".xz", ".7z", ".rar", ".jar", ".war", ".ear", ".lz4", ".zst", ".z",
     ".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".tiff", ".tif", ".ico", ".heic", ".avif",
-    ".mp3", ".wav", ".flac", ".ogg", ".m4a", ".aac", ".mp4", ".mov", ".avi", ".mkv", ".webm", ".wmv", ".flv",
+    ".mp3", ".wav", ".flac", ".ogg", ".m4a", ".aac", ".wma", ".aiff", ".opus",
+    ".mp4", ".mov", ".avi", ".mkv", ".webm", ".wmv", ".flv", ".m4v", ".mpeg", ".mpg",
     ".pdf", ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx", ".odt", ".ods", ".odp",
     ".woff", ".woff2", ".ttf", ".otf", ".eot",
-    ".db", ".sqlite", ".sqlite3", ".mdb", ".dat", ".pdb", ".ipa", ".apk", ".dmg", ".iso", ".img",
+    ".psd", ".ai", ".eps", ".sketch", ".fig", ".xd", ".blend", ".3ds", ".max", ".swf", ".fla",
+    ".db", ".sqlite", ".sqlite3", ".mdb", ".idx", ".dat", ".data", ".lockb",
+    ".pdb", ".ipa", ".apk", ".dmg", ".iso", ".img",
 ]);
 export function hasBinaryExtension(path) {
     const dot = path.lastIndexOf(".");
@@ -168,10 +181,11 @@ export async function resolveKey(env, rootCanonical, path, signal, baseCwd, addi
     return { ok: true, key };
 }
 export async function canonicalizeTarget(env, path, signal, baseCwd) {
-    if (isUncPath(path)) {
-        return { ok: false, message: `path "${path}" is a UNC/network path; refused (potential credential leak).` };
+    if (isUncPath(path) && isWinFormPath(path)) {
+        return { ok: true, key: path };
     }
-    const target = baseCwd && !isAbsolutePathForm(path) ? `${baseCwd.replace(/[\\/]+$/, "")}/${path}` : path;
+    const spelled = path.startsWith("//") ? path.replace(/^\/+/, "/") : path;
+    const target = baseCwd && !isAbsolutePathForm(spelled) ? `${baseCwd.replace(/[\\/]+$/, "")}/${spelled}` : spelled;
     const absR = await env.absolutePath(target, signal);
     if (!absR.ok)
         return { ok: false, message: `cannot resolve path "${path}": ${absR.error.message}` };
@@ -249,7 +263,7 @@ export function checkNoChange(oldString, newString) {
 }
 export function checkStale(entry, currentHash) {
     if (entry.hash !== currentHash) {
-        return { code: "stale", message: "File has been modified since it was read; read it again before editing." };
+        return { code: "stale", message: "File has been modified since read, either by the user or by a linter. Read it again before attempting to write it." };
     }
     return undefined;
 }
@@ -285,6 +299,95 @@ export function resolveQuoteMatch(content, oldString) {
         return undefined;
     return content.substring(idx, idx + oldString.length);
 }
+const UNICODE_ESCAPE_RE = /\\u[0-9a-fA-F]{4}/;
+const NON_ASCII_RE = /[\u0080-\uffff]/;
+function decodeUnicodeEscapes(s) {
+    return s.replace(/(\\\\)|\\u([0-9a-fA-F]{4})/g, (m, dbl, hex) => (dbl !== undefined ? m : String.fromCharCode(parseInt(hex, 16))));
+}
+function escapedSpellingPattern(s) {
+    let out = "";
+    for (let i = 0; i < s.length; i++) {
+        const code = s.charCodeAt(i);
+        if (code >= 128) {
+            out += "\\\\u";
+            for (const d of code.toString(16).padStart(4, "0"))
+                out += d >= "a" ? `[${d}${d.toUpperCase()}]` : d;
+        }
+        else
+            out += s[i].replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    }
+    return out;
+}
+export function resolveEscapeMatch(content, oldString) {
+    if (oldString === "")
+        return undefined;
+    if (UNICODE_ESCAPE_RE.test(oldString)) {
+        const decoded = decodeUnicodeEscapes(oldString);
+        if (decoded !== oldString && content.includes(decoded))
+            return decoded;
+    }
+    if (NON_ASCII_RE.test(oldString)) {
+        let hit = null;
+        try {
+            hit = content.match(new RegExp(escapedSpellingPattern(oldString)));
+        }
+        catch {
+            hit = null;
+        }
+        if (hit)
+            return hit[0];
+    }
+    return undefined;
+}
+export function adaptNewStringEscapes(oldString, matchedOld, newString) {
+    if (oldString === matchedOld)
+        return newString;
+    if (NON_ASCII_RE.test(oldString)) {
+        let full;
+        try {
+            full = new RegExp(`^${escapedSpellingPattern(oldString)}$`);
+        }
+        catch {
+            full = undefined;
+        }
+        if (full?.test(matchedOld)) {
+            const hexOf = new Map();
+            let upper = 0;
+            let lower = 0;
+            for (let i = 0, at = 0; i < oldString.length; i++) {
+                const code = oldString.charCodeAt(i);
+                if (code >= 128) {
+                    const hex = matchedOld.slice(at + 2, at + 6);
+                    hexOf.set(code, hex);
+                    for (const d of hex) {
+                        if (d >= "a" && d <= "f")
+                            lower++;
+                        else if (d >= "A" && d <= "F")
+                            upper++;
+                    }
+                    at += 6;
+                }
+                else
+                    at += 1;
+            }
+            return newString.replace(/[\u0080-\uffff]/g, (ch) => {
+                const code = ch.charCodeAt(0);
+                const known = hexOf.get(code);
+                if (known !== undefined)
+                    return `\\u${known}`;
+                const hex = code.toString(16).padStart(4, "0");
+                return `\\u${upper > lower ? hex.toUpperCase() : hex}`;
+            });
+        }
+    }
+    if (UNICODE_ESCAPE_RE.test(oldString) && decodeUnicodeEscapes(oldString) === matchedOld)
+        return decodeUnicodeEscapes(newString);
+    return newString;
+}
+export function escapeMatchWasAttempted(oldString) {
+    return UNICODE_ESCAPE_RE.test(oldString) || NON_ASCII_RE.test(oldString);
+}
+export const ESCAPE_MATCH_MISS_NOTE = "\n(note: Edit also tried swapping \\uXXXX escapes and their characters; neither form matched, so the mismatch is likely elsewhere in old_string. Re-read the file and copy the exact surrounding text.)";
 function isQuoteOpenerPosition(chars, i) {
     if (i === 0)
         return true;

package/dist/tools/fs/search.d.ts

@@ -21,6 +21,7 @@ export declare function splitAbsoluteGlobPattern(pattern: string): {
     relativePattern: string;
 } | undefined;
 export declare function shellQuote(s: string): string;
+export declare function invalidGlobTokens(glob: string): string[];
 export declare function gitignoreMatcher(content: string): (rel: string, isDir: boolean) => boolean;
 export declare function buildIgnore(env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<(rel: string, isDir: boolean) => boolean>;
 export interface WalkResult {

package/dist/tools/fs/search.js

@@ -76,7 +76,7 @@ export function splitAbsoluteGlobPattern(pattern) {
 export function shellQuote(s) {
     return `'${s.replace(/'/g, `'\\''`)}'`;
 }
-function globTokenToRegExp(token, anchored, glob = false) {
+function globTokenToRegExp(token, anchored, glob = false, report) {
     const charToRe = (ch) => ch === "*" ? "[^/]*" : ch === "?" ? "[^/]" : ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
     let re = "";
     for (let i = 0; i < token.length; i++) {
@@ -100,8 +100,11 @@ function globTokenToRegExp(token, anchored, glob = false) {
                 re += `(?:${alts.join("|")})`;
                 i = close;
             }
-            else
+            else {
                 re += "\\{";
+                if (report)
+                    report.degraded = true;
+            }
         }
         else if (glob && c === "[") {
             let j = i + 1;
@@ -129,14 +132,27 @@ function globTokenToRegExp(token, anchored, glob = false) {
                 re += cls;
                 i = close;
             }
-            else
+            else {
                 re += "\\[";
+                if (report)
+                    report.degraded = true;
+            }
         }
         else
             re += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
     }
     return new RegExp(`${anchored ? "^" : "(^|/)"}${re}$`);
 }
+export function invalidGlobTokens(glob) {
+    const bad = [];
+    for (const token of splitGlobParam(glob)) {
+        const report = { degraded: false };
+        globTokenToRegExp(normalizeGlobToken(token), globIsAnchored(token), true, report);
+        if (report.degraded)
+            bad.push(token);
+    }
+    return bad;
+}
 function normalizeGlobToken(token) {
     let t = token;
     while (t.startsWith("./"))
@@ -1095,6 +1111,10 @@ export async function runGlobDetailed(env, root, pattern, opts = {}, signal) {
             const error = `Error (Glob): path ${JSON.stringify(opts.path)} does not exist — check the path, or omit \`path\` to search the whole root.`;
             return { text: error, error, filenames: [], numFiles: 0, truncated: false, durationMs: Date.now() - t0, totalMatches: 0, countIsComplete: false };
         }
+        if (probe.ok && probe.value.kind === "file") {
+            const error = `Error (Glob): path ${JSON.stringify(opts.path)} is not a directory — \`path\` scopes the search to a directory; pass its parent directory (and name the file in \`pattern\`), or omit \`path\` to search the whole root.`;
+            return { text: error, error, filenames: [], numFiles: 0, truncated: false, durationMs: Date.now() - t0, totalMatches: 0, countIsComplete: false };
+        }
     }
     const pat = normalizeGlobToken(pattern);
     const anchored = globIsAnchored(pattern);

package/dist/tools/monitor.js

@@ -10,7 +10,7 @@ const MONITOR_DESCRIPTION = "Run a shell command in the background and watch its
     `exceeds its timeout is killed and reported (default ${MONITOR_DEFAULT_TIMEOUT_MS}ms, max ${MONITOR_MAX_TIMEOUT_MS}ms).\n` +
     "- stderr does NOT trigger notifications, but it is captured — read it any time with TaskOutput(task_id), " +
     "which also serves the full re-readable stdout spool.\n" +
-    "- A monitor that produces too many events is stopped automatically (the stop notification says why).\n" +
+    "- A monitor that produces too many events is rate-limited: excess batches are suppressed (a notification tells you how many), and a watch that stays over the limit is stopped automatically.\n" +
     "- Set persistent: true for a session-resident watch with no watch timeout of its own; it still ends when " +
     "the execution environment's background time budget expires, when you stop it with TaskStop(task_id), or " +
     "when the session is released.\n" +

package/dist/tools/task-list.d.ts

@@ -20,5 +20,6 @@ export interface TaskListStore {
 }
 export declare function normalizeTaskShape<T>(item: T): T;
 export declare function assertJsonMetadata(value: unknown, path?: string): void;
+export declare function compareTaskIds(a: string, b: string): number;
 export declare function createMemoryTaskListStore(): TaskListStore;
 export declare function createTaskListTools(store?: TaskListStore): ToolSpec[];

package/dist/tools/task-list.js

@@ -55,6 +55,17 @@ export function assertJsonMetadata(value, path = "metadata") {
     }
     throw new Error(`Task ${path} must be JSON-serializable (found ${t === "object" ? "non-plain object" : t}).`);
 }
+export function compareTaskIds(a, b) {
+    const num = (id) => (/^\d+$/.test(id) ? Number.parseInt(id, 10) : Number.NaN);
+    const [na, nb] = [num(a), num(b)];
+    if (Number.isFinite(na) && Number.isFinite(nb))
+        return na - nb || a.localeCompare(b);
+    if (Number.isFinite(na))
+        return -1;
+    if (Number.isFinite(nb))
+        return 1;
+    return a.localeCompare(b);
+}
 export function createMemoryTaskListStore() {
     const tasks = new Map();
     let nextId = 1;
@@ -69,7 +80,7 @@ export function createMemoryTaskListStore() {
             tasks.set(id, snapTask(item));
         },
         delete: (id) => tasks.delete(id),
-        list: () => [...tasks.values()].map(snapTask),
+        list: () => [...tasks.values()].sort((a, b) => compareTaskIds(a.id, b.id)).map(snapTask),
         allocateId: () => String(nextId++),
     };
 }
@@ -133,7 +144,7 @@ export function createTaskListTools(store) {
             activeForm: Type.Optional(Type.String({ description: 'Present continuous form shown when in_progress (e.g., "Running tests")' })),
             metadata: Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: "Arbitrary metadata to attach to the task" })),
         }),
-        effect: "idempotent",
+        effect: "write",
         execute: (args) => serialized(tasks, async (tx) => {
             const a = args;
             if (a.metadata)