@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.20

package/dist/tools/builtins/sandbox/edit.js

@@ -1,40 +1,42 @@
 import { ToolError } from "@capybara-hq/plugin-sdk";
 import { lineDiff, viewPath } from "../../view.js";
-import { checkWritable, clip, display, inSandbox, looksBinary, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, withNotices, withPathLease, } from "./common.js";
-/** 可编辑的最大文件（字节）：更大的用 sandbox_bash 处理。 */
+import { checkPathShape, checkWritable, clip, display, inSandbox, looksBinary, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, withNotices, withPathLease, } from "./common.js";
+import { assertReadAndUnchanged, fileStateOf, normalizeSandboxPath, recordedFile, } from "./file-state.js";
+import { READ_MAX_BYTES } from "./read.js";
+/** 可编辑的最大文件（字节）：更大的用 Bash 处理。 */
 const EDIT_MAX_BYTES = 10 * 1024 * 1024;
 const SPEC = {
-    name: "sandbox_edit",
+    name: "Edit",
     // Display only (the tool row; not in the fingerprint, never sent to the model).
-    keyArgs: ["path"],
-    description: "Edit a text file in this conversation's sandbox by replacing exact text. oldText must match " +
-        "the file exactly (including whitespace and indentation) and, unless replaceAll is true, occur " +
-        "exactly once; include enough surrounding lines to make it unique. Read the file with " +
-        "sandbox_read first. Use sandbox_write to create a file or replace all of it.",
+    keyArgs: ["file_path"],
+    description: "Edit a text file in this conversation's sandbox by replacing exact text. old_string must match " +
+        "the file exactly (including whitespace and indentation) and, unless replace_all is true, occur " +
+        "exactly once; include enough surrounding lines to make it unique. Read the file first; " +
+        "editing a file you have not read, or one changed since you read it, fails. Use Write to create a file or replace all of it.",
     inputSchema: {
         type: "object",
         properties: {
-            path: {
+            file_path: {
                 type: "string",
                 minLength: 1,
-                description: 'Absolute path of the file, e.g. "/workspace/src/app.py".',
+                description: "Absolute path of the file, e.g. src/app.py in the workspace directory.",
             },
-            oldText: { type: "string", minLength: 1, description: "The exact text to replace." },
-            newText: { type: "string", description: "The replacement text." },
-            replaceAll: {
+            old_string: { type: "string", minLength: 1, description: "The exact text to replace." },
+            new_string: { type: "string", description: "The replacement text." },
+            replace_all: {
                 type: "boolean",
-                description: "Replace every occurrence of oldText instead of exactly one. Default false.",
+                description: "Replace every occurrence of old_string instead of exactly one. Default false.",
             },
         },
-        required: ["path", "oldText", "newText"],
+        required: ["file_path", "old_string", "new_string"],
         additionalProperties: false,
     },
 };
-const notFound = (path) => `File not found: ${clip(path, 200)}. Check the path with sandbox_glob, or use sandbox_write to create it.`;
-const notText = (path) => `${clip(path, 200)} is a directory, a binary file or larger than ${EDIT_MAX_BYTES} bytes; use sandbox_bash to change it.`;
-const SAME_TEXT = "oldText and newText are the same; pass the text you want to change and its replacement.";
-const noMatch = (path) => `oldText was not found in ${clip(path, 200)}; call sandbox_read and pass the exact text, including whitespace.`;
-const ambiguous = (n) => `oldText occurs ${n} times; pass more surrounding text to make it unique, or pass replaceAll: true.`;
+const notFound = (path) => `File not found: ${clip(path, 200)}. Check the path with Glob, or use Write to create it.`;
+const notText = (path) => `${clip(path, 200)} is a directory, a binary file or larger than ${EDIT_MAX_BYTES} bytes; use Bash to change it.`;
+const SAME_TEXT = "old_string and new_string are the same; pass the text you want to change and its replacement.";
+const noMatch = (path) => `old_string was not found in ${clip(path, 200)}; call Read and pass the exact text, including whitespace.`;
+const ambiguous = (n) => `old_string occurs ${n} times; pass more surrounding text to make it unique, or pass replace_all: true.`;
 /** 出现次数（不重叠）。 */
 function occurrences(text, sub) {
     let n = 0;
@@ -42,7 +44,7 @@ function occurrences(text, sub) {
         n++;
     return n;
 }
-/** 内置工具 `sandbox_edit`：按精确文本替换。 */
+/** 内置工具 `Edit`：按精确文本替换。 */
 export function sandboxEditTool(deps) {
     return {
         spec: SPEC,
@@ -50,36 +52,47 @@ export function sandboxEditTool(deps) {
         unavailable: unavailableWhenNoSandbox(deps),
         timeoutMs: () => sandboxBaseTimeoutMs(deps.config.get()),
         async run(input, ctx) {
-            const { oldText, newText, replaceAll = false } = input;
-            const path = checkWritable(input.path);
-            if (oldText === newText)
+            const { old_string, new_string, replace_all = false } = input;
+            if (old_string === new_string)
                 throw new ToolError(SAME_TEXT);
-            const { value: edit, notices } = await inSandbox(deps, ctx, ({ h, p, signal }) => 
-            // read, replace, write: one holder at a time per file
-            withPathLease(deps, ctx, path, signal, async (signal) => {
-                const st = await p.stat(h, path, signal);
-                if (st === null)
-                    throw new ToolError(notFound(path));
-                if (st.isDir)
-                    throw new ToolError(notText(path));
-                const got = await p.readFile(h, path, { maxBytes: EDIT_MAX_BYTES, signal });
-                if (got === null)
-                    throw new ToolError(notFound(path));
-                if (got.truncated || looksBinary(got.data))
-                    throw new ToolError(notText(path));
-                const text = new TextDecoder().decode(got.data);
-                const count = occurrences(text, oldText);
-                if (count === 0)
-                    throw new ToolError(noMatch(path));
-                if (count > 1 && !replaceAll)
-                    throw new ToolError(ambiguous(count));
-                // 用函数形式替换：newText 里的 `$&` 等不被当成替换模式
-                const next = replaceAll
-                    ? text.split(oldText).join(newText)
-                    : text.replace(oldText, () => newText);
-                await p.writeFile(h, path, new TextEncoder().encode(next), signal);
-                return { n: replaceAll ? count : 1, before: text, after: next };
-            }));
+            checkPathShape(input.file_path, "file_path");
+            let path = "";
+            const { value: edit, notices } = await inSandbox(deps, ctx, ({ deviceId, h, roots, p, signal }) => {
+                path = checkWritable(input.file_path, roots);
+                // read, replace, write: one holder at a time per file
+                return withPathLease(deps, { deviceId }, path, signal, async (signal) => {
+                    const st = await p.stat(h, path, signal);
+                    if (st === null)
+                        throw new ToolError(notFound(path));
+                    if (st.isDir)
+                        throw new ToolError(notText(path));
+                    const got = await p.readFile(h, path, { maxBytes: EDIT_MAX_BYTES, signal });
+                    if (got === null)
+                        throw new ToolError(notFound(path));
+                    if (got.truncated || looksBinary(got.data))
+                        throw new ToolError(notText(path));
+                    await assertReadAndUnchanged(deps, ctx.conversationId, path, fileStateOf(got.data, st.size));
+                    const text = new TextDecoder().decode(got.data);
+                    const count = occurrences(text, old_string);
+                    if (count === 0)
+                        throw new ToolError(noMatch(path));
+                    if (count > 1 && !replace_all)
+                        throw new ToolError(ambiguous(count));
+                    // 用函数形式替换：new_string 里的 `$&` 等不被当成替换模式
+                    const next = replace_all
+                        ? text.split(old_string).join(new_string)
+                        : text.replace(old_string, () => new_string);
+                    const nextBytes = new TextEncoder().encode(next);
+                    await p.writeFile(h, path, nextBytes, signal);
+                    return {
+                        n: replace_all ? count : 1,
+                        before: text,
+                        after: next,
+                        // over the bytes the next Write / Edit reads back (Read's limit), as Read records it
+                        file: recordedFile(normalizeSandboxPath(path), nextBytes.subarray(0, READ_MAX_BYTES), nextBytes.byteLength),
+                    };
+                });
+            });
             const { n } = edit;
             const text = `Edited ${path}: replaced ${n} occurrence${n === 1 ? "" : "s"}.`;
             return {
@@ -91,6 +104,7 @@ export function sandboxEditTool(deps) {
                     path: viewPath(path),
                     created: false,
                     ...lineDiff(edit.before, edit.after),
+                    file: edit.file,
                 },
             };
         },

package/dist/tools/builtins/sandbox/file-state.d.ts

@@ -0,0 +1,34 @@
+import type { EventLog } from "../../../conversations/event-log.js";
+/**
+ * Read before `Write` / `Edit` (tool naming spec §4.5). The state of a file as a `Read`, `Write` or
+ * `Edit` saw or left it is recorded in the display-only `tool_result.view.file`; before writing,
+ * the tools compare the latest recorded state of the path in this conversation's log with the
+ * content they read anyway. Nothing lives in process memory, so every replica decides the same.
+ */
+export interface FileState {
+    /** The file's full size in bytes. */
+    size: number;
+    /** sha256 (hex) of the bytes handled: the first bytes only for a file over `Read`'s byte limit. */
+    sha256: string;
+}
+/** What the tools put into `view.file`: the state plus the full normalized path (never cut). */
+export interface RecordedFile extends FileState {
+    path: string;
+}
+export declare const NOT_READ_TEXT = "File has not been read yet. Read it first before writing to it.";
+export declare const MODIFIED_TEXT = "File has been modified since it was read, either by the user or by another command. Read it again before writing to it.";
+/** The state of `bytes`, the bytes handled of a file whose full size is `fullSize`. */
+export declare function fileStateOf(bytes: Uint8Array, fullSize: number): FileState;
+/** The `view.file` value for a file at `path` (already normalized). */
+export declare function recordedFile(path: string, bytes: Uint8Array, fullSize: number): RecordedFile;
+/** POSIX-normalized absolute path (`/workspace/./a.txt` and `/workspace/a.txt` are one file). */
+export declare function normalizeSandboxPath(path: string): string;
+/** The latest recorded state of `path` in the conversation's log; null when it was never recorded. */
+export declare function lastFileState(log: Pick<EventLog, "latestFileState">, conversationId: string, path: string): Promise<FileState | null>;
+/**
+ * Throws the model-visible error unless the conversation read (or wrote) the file and it is
+ * unchanged: `current` is the state of the content the caller just read.
+ */
+export declare function assertReadAndUnchanged(deps: {
+    eventLog: Pick<EventLog, "latestFileState">;
+}, conversationId: string, path: string, current: FileState): Promise<void>;

package/dist/tools/builtins/sandbox/file-state.js

@@ -0,0 +1,34 @@
+import { createHash } from "node:crypto";
+import { posix } from "node:path";
+import { ToolError } from "@capybara-hq/plugin-sdk";
+export const NOT_READ_TEXT = "File has not been read yet. Read it first before writing to it.";
+export const MODIFIED_TEXT = "File has been modified since it was read, either by the user or by another command. Read it again before writing to it.";
+/** The state of `bytes`, the bytes handled of a file whose full size is `fullSize`. */
+export function fileStateOf(bytes, fullSize) {
+    return { size: fullSize, sha256: createHash("sha256").update(bytes).digest("hex") };
+}
+/** The `view.file` value for a file at `path` (already normalized). */
+export function recordedFile(path, bytes, fullSize) {
+    return { path, ...fileStateOf(bytes, fullSize) };
+}
+/** POSIX-normalized absolute path (`/workspace/./a.txt` and `/workspace/a.txt` are one file). */
+export function normalizeSandboxPath(path) {
+    const n = posix.normalize(path);
+    return n.length > 1 && n.endsWith("/") ? n.slice(0, -1) : n;
+}
+/** The latest recorded state of `path` in the conversation's log; null when it was never recorded. */
+export async function lastFileState(log, conversationId, path) {
+    return log.latestFileState(conversationId, normalizeSandboxPath(path));
+}
+/**
+ * Throws the model-visible error unless the conversation read (or wrote) the file and it is
+ * unchanged: `current` is the state of the content the caller just read.
+ */
+export async function assertReadAndUnchanged(deps, conversationId, path, current) {
+    const seen = await lastFileState(deps.eventLog, conversationId, path);
+    if (seen === null)
+        throw new ToolError(NOT_READ_TEXT);
+    if (seen.size !== current.size || seen.sha256 !== current.sha256) {
+        throw new ToolError(MODIFIED_TEXT);
+    }
+}

package/dist/tools/builtins/sandbox/glob-match.d.ts

@@ -1,5 +1,5 @@
 /**
- * 线性时间的 glob 匹配（sandbox_glob 用；模式由模型给出，不能编译成会回溯爆炸的正则）。
+ * 线性时间的 glob 匹配（Glob 用；模式由模型给出，不能编译成会回溯爆炸的正则）。
  *
  * 语法：路径按 `/` 分段；整段 `**` 跨任意层目录（含零层）；段内 `*` 匹配任意个字符（不跨 `/`），`?` 一个字符，
  * `[abc]` / `[a-z]` / `[!x]`（或 `[^x]`）字符类，`{a,b}` 二选一（可嵌套，展开后最多 {@link MAX_ALTERNATIVES} 个）；

package/dist/tools/builtins/sandbox/glob-match.js

@@ -1,5 +1,5 @@
 /**
- * 线性时间的 glob 匹配（sandbox_glob 用；模式由模型给出，不能编译成会回溯爆炸的正则）。
+ * 线性时间的 glob 匹配（Glob 用；模式由模型给出，不能编译成会回溯爆炸的正则）。
  *
  * 语法：路径按 `/` 分段；整段 `**` 跨任意层目录（含零层）；段内 `*` 匹配任意个字符（不跨 `/`），`?` 一个字符，
  * `[abc]` / `[a-z]` / `[!x]`（或 `[^x]`）字符类，`{a,b}` 二选一（可嵌套，展开后最多 {@link MAX_ALTERNATIVES} 个）；

package/dist/tools/builtins/sandbox/glob.d.ts

@@ -1,4 +1,4 @@
 import type { BuiltinTool } from "../../registry.js";
 import { type SandboxToolDeps } from "./common.js";
-/** 内置工具 `sandbox_glob`：按文件名模式找文件（只读）。 */
+/** 内置工具 `Glob`：按文件名模式找文件（只读）。 */
 export declare function sandboxGlobTool(deps: SandboxToolDeps): BuiltinTool;

package/dist/tools/builtins/sandbox/glob.js

@@ -1,19 +1,19 @@
 import { ToolError } from "@capybara-hq/plugin-sdk";
-import { checkPath, clip, display, inSandbox, SYNC_MARKER, sandboxBaseTimeoutMs, searchTimeoutMs, unavailableWhenNoSandbox, withNotices, } from "./common.js";
+import { checkPath, checkPathShape, clip, display, inSandbox, sandboxBaseTimeoutMs, searchTimeoutMs, syncMarkerMatcher, unavailableWhenNoSandbox, withNotices, } from "./common.js";
 import { compileGlob, GlobPatternError } from "./glob-match.js";
 /** 最多列出的文件数。 */
 const MAX_RESULTS = 1000;
 /** `find` 输出的上限（字节）。 */
 const MAX_FIND_BYTES = 8 * 1024 * 1024;
 const SPEC = {
-    name: "sandbox_glob",
+    name: "Glob",
     // Display only (the tool row; not in the fingerprint, never sent to the model).
     keyArgs: ["pattern"],
     description: "Find files by name pattern in this conversation's sandbox. Use it to list files and to " +
         'locate files by name, e.g. pattern "**/*.py" for all Python files. The pattern is matched ' +
-        "against paths relative to path (default /workspace): * matches within one directory, ** " +
+        "against paths relative to path (default: the workspace directory): * matches within one directory, ** " +
         "matches across directories, ? matches one character, {a,b} matches either. Returns absolute " +
-        "paths sorted by name, up to 1000. To search file contents, use sandbox_grep.",
+        "paths sorted by name, up to 1000. To search file contents, use Grep.",
     inputSchema: {
         type: "object",
         properties: {
@@ -25,7 +25,7 @@ const SPEC = {
             path: {
                 type: "string",
                 minLength: 1,
-                description: "Absolute directory to search in. Default /workspace.",
+                description: "Absolute directory to search in. Default: the workspace directory.",
             },
         },
         required: ["pattern"],
@@ -34,9 +34,9 @@ const SPEC = {
     annotations: { readOnlyHint: true },
 };
 const ABSOLUTE_PATTERN = 'The pattern must be relative to path; pass the directory in path and a relative pattern such as "**/*.py".';
-const notDirectory = (path) => `${clip(path, 200)} is not a directory; pass an existing directory in path (default /workspace).`;
+const notDirectory = (path, workspace) => `${clip(path, 200)} is not a directory; pass an existing directory in path (default ${workspace}).`;
 const FIND_FAILED = "Listing files did not finish in time; pass a narrower path or pattern and retry.";
-/** 内置工具 `sandbox_glob`：按文件名模式找文件（只读）。 */
+/** 内置工具 `Glob`：按文件名模式找文件（只读）。 */
 export function sandboxGlobTool(deps) {
     return {
         spec: SPEC,
@@ -48,7 +48,6 @@ export function sandboxGlobTool(deps) {
             const { pattern } = input;
             if (pattern.startsWith("/"))
                 throw new ToolError(ABSOLUTE_PATTERN);
-            const dir = checkPath(input.path ?? "/workspace");
             let matches;
             try {
                 matches = compileGlob(pattern);
@@ -58,10 +57,15 @@ export function sandboxGlobTool(deps) {
                     throw e;
                 throw new ToolError(`Invalid glob pattern: ${e.message}; pass a simpler pattern (fewer wildcards and braces) and retry.`);
             }
-            const { value: files, notices } = await inSandbox(deps, ctx, async ({ h, p, signal }) => {
+            const given = input.path;
+            if (given !== undefined)
+                checkPathShape(given);
+            let dir = "";
+            const { value: files, notices } = await inSandbox(deps, ctx, async ({ h, roots, p, signal }) => {
+                dir = checkPath(input.path ?? roots.workspace, roots);
                 const st = await p.stat(h, dir, signal);
                 if (!st?.isDir)
-                    throw new ToolError(notDirectory(dir));
+                    throw new ToolError(notDirectory(dir, roots.workspace));
                 const r = await p.exec(h, {
                     command: "find . -type f -print0",
                     cwd: dir,
@@ -77,14 +81,15 @@ export function sandboxGlobTool(deps) {
                 if (r.truncated)
                     names.pop();
                 const base = dir === "/" ? "" : dir;
+                const isMarker = syncMarkerMatcher(roots);
                 return (names
                     .filter((l) => l.startsWith("./"))
                     .map((l) => l.slice(2))
                     .filter((rel) => matches(rel))
                     .map((rel) => `${base}/${rel}`)
-                    .filter((abs) => abs !== SYNC_MARKER)
+                    .filter((abs) => !isMarker(abs))
                     .sort()
-                    // 文件名里的换行显示为 `\n`（与 sandbox_grep 一致），一行一个文件
+                    // 文件名里的换行显示为 `\n`（与 Grep 一致），一行一个文件
                     .map((abs) => abs.replace(/\n/g, "\\n")));
             });
             const shown = files.slice(0, MAX_RESULTS);

package/dist/tools/builtins/sandbox/grep.d.ts

@@ -1,9 +1,12 @@
 import type { BuiltinTool } from "../../registry.js";
 import { type SandboxToolDeps } from "./common.js";
 /**
- * 解析 `grep -nH --null` 的输出：每条为 `<文件名>\0<行号>:<行>\n`（文件名可能含换行，行本身不含）。
- * 返回 `<绝对路径>:<行号>:<行>`；文件名里的换行显示为 `\n`。最后一条不完整（输出被截断）时丢掉。
+ * Parses the output of `grep -H --null` (with `-n` when `numbered`): each entry is
+ * `<file name>\0<line number>:<line>\n` (the file name may contain newlines, the line does not).
+ * Returns `<absolute path>:<line number>:<line>`; context lines (`<line number>-<line>`, only with
+ * `-A/-B/-C`) become `<absolute path>-<line number>-<line>`, and the `--` group separator is kept.
+ * A newline in a file name shows as `\n`. An incomplete last entry (truncated output) is dropped.
  */
-export declare function parseGrepNull(stdout: string, base: string): string[];
-/** 内置工具 `sandbox_grep`：按正则搜文件内容（只读）。 */
+export declare function parseGrepNull(stdout: string, base: string, numbered?: boolean): string[];
+/** 内置工具 `Grep`：按正则搜文件内容（只读）。 */
 export declare function sandboxGrepTool(deps: SandboxToolDeps): BuiltinTool;

package/dist/tools/builtins/sandbox/grep.js

@@ -1,20 +1,28 @@
 import { ToolError } from "@capybara-hq/plugin-sdk";
-import { checkPath, clip, display, inSandbox, SYNC_MARKER, sandboxBaseTimeoutMs, searchTimeoutMs, shellQuote, unavailableWhenNoSandbox, withNotices, } from "./common.js";
-/** 最多返回的匹配行数。 */
+import { checkPath, checkPathShape, clip, display, inSandbox, sandboxBaseTimeoutMs, searchTimeoutMs, shellQuote, syncMarkerMatcher, unavailableWhenNoSandbox, withNotices, } from "./common.js";
+/** The most output entries (lines, files or counts) returned in one call, whatever `head_limit` says. */
 const MAX_MATCHES = 500;
+/** `head_limit` when the model gives none. */
+const DEFAULT_HEAD_LIMIT = 250;
 /** 每个匹配行最多显示的字符数。 */
 const MAX_LINE_CHARS = 500;
 /** grep 输出的上限（字节）。 */
 const MAX_GREP_BYTES = 4 * 1024 * 1024;
+const MODES = ["content", "files_with_matches", "count"];
 const SPEC = {
-    name: "sandbox_grep",
+    name: "Grep",
     // Display only (the tool row; not in the fingerprint, never sent to the model).
     keyArgs: ["pattern", "path"],
     description: "Search file contents in this conversation's sandbox with a regular expression (POSIX " +
         "extended, as grep -E). Use it to find where something is defined or mentioned. Searches path " +
-        "(a file, or a directory recursively; default /workspace), skipping binary files; glob limits " +
-        'the files searched by name, e.g. "*.py". Returns matching lines as <path>:<line>:<text>, up ' +
-        "to 500. To find files by name, use sandbox_glob.",
+        "(a file, or a directory recursively; default: the workspace directory), skipping binary files; glob limits " +
+        'the files searched by name, e.g. "*.py". output_mode picks what comes back: ' +
+        '"files_with_matches" (default) lists the paths of files that match, "content" returns the ' +
+        "matching lines as <path>:<line>:<text> (with -A, -B or -C lines of context around them), " +
+        '"count" returns <path>:<number of matching lines> per file. -n (line numbers) and the context ' +
+        "options apply only to content mode. head_limit caps the entries returned (default 250; " +
+        "0 = up to 500); pass offset to skip entries and page through more. To find files by " +
+        "name, use Glob.",
     inputSchema: {
         type: "object",
         properties: {
@@ -26,31 +34,73 @@ const SPEC = {
             path: {
                 type: "string",
                 minLength: 1,
-                description: "Absolute file or directory to search. Default /workspace.",
+                description: "Absolute file or directory to search. Default: the workspace directory.",
             },
             glob: {
                 type: "string",
                 minLength: 1,
                 description: 'Only search files whose name matches this glob, e.g. "*.md".',
             },
-            ignoreCase: { type: "boolean", description: "Case-insensitive match. Default false." },
+            "-i": { type: "boolean", description: "Case-insensitive match. Default false." },
+            output_mode: {
+                type: "string",
+                enum: [...MODES],
+                description: 'What to return: "files_with_matches" (file paths, default), "content" (matching lines) or "count" (matching lines per file).',
+            },
+            "-n": {
+                type: "boolean",
+                description: "Show line numbers in content mode. Default true.",
+            },
+            "-A": {
+                type: "integer",
+                minimum: 0,
+                description: "Lines of context after each match (content mode).",
+            },
+            "-B": {
+                type: "integer",
+                minimum: 0,
+                description: "Lines of context before each match (content mode).",
+            },
+            "-C": {
+                type: "integer",
+                minimum: 0,
+                description: "Lines of context before and after each match (content mode).",
+            },
+            head_limit: {
+                type: "integer",
+                minimum: 0,
+                description: `Return at most this many entries (lines, files or counts, by mode). Default ${DEFAULT_HEAD_LIMIT}; 0 = up to ${MAX_MATCHES}.`,
+            },
+            offset: {
+                type: "integer",
+                minimum: 0,
+                description: "Skip this many entries before returning (for paging). Default 0.",
+            },
         },
         required: ["pattern"],
         additionalProperties: false,
     },
     annotations: { readOnlyHint: true },
 };
-const notFound = (path) => `${clip(path, 200)} does not exist; check the path with sandbox_glob.`;
+const notFound = (path) => `${clip(path, 200)} does not exist; check the path with Glob.`;
 const failed = (stderr) => `grep failed: ${clip(stderr, 300)}. Check the pattern (POSIX extended regular expression) and retry.`;
 const GREP_TIMEOUT = "The search did not finish in time; pass a narrower path or a glob and retry.";
 /**
- * 解析 `grep -nH --null` 的输出：每条为 `<文件名>\0<行号>:<行>\n`（文件名可能含换行，行本身不含）。
- * 返回 `<绝对路径>:<行号>:<行>`；文件名里的换行显示为 `\n`。最后一条不完整（输出被截断）时丢掉。
+ * Parses the output of `grep -H --null` (with `-n` when `numbered`): each entry is
+ * `<file name>\0<line number>:<line>\n` (the file name may contain newlines, the line does not).
+ * Returns `<absolute path>:<line number>:<line>`; context lines (`<line number>-<line>`, only with
+ * `-A/-B/-C`) become `<absolute path>-<line number>-<line>`, and the `--` group separator is kept.
+ * A newline in a file name shows as `\n`. An incomplete last entry (truncated output) is dropped.
  */
-export function parseGrepNull(stdout, base) {
+export function parseGrepNull(stdout, base, numbered = true) {
     const out = [];
     let pos = 0;
     for (;;) {
+        if (stdout.startsWith("--\n", pos)) {
+            out.push("--");
+            pos += 3;
+            continue;
+        }
         const nul = stdout.indexOf("\0", pos);
         if (nul === -1)
             break;
@@ -59,12 +109,45 @@ export function parseGrepNull(stdout, base) {
             break;
         const raw = stdout.slice(pos, nul);
         const name = (raw.startsWith("./") ? raw.slice(2) : raw).replace(/\n/g, "\\n");
-        out.push(`${base}/${name}:${stdout.slice(nul + 1, nl)}`);
+        const rest = stdout.slice(nul + 1, nl);
+        out.push(numbered && /^\d+-/.test(rest) ? `${base}/${name}-${rest}` : `${base}/${name}:${rest}`);
         pos = nl + 1;
     }
     return out;
 }
-/** 内置工具 `sandbox_grep`：按正则搜文件内容（只读）。 */
+const displayName = (raw) => (raw.startsWith("./") ? raw.slice(2) : raw).replace(/\n/g, "\\n");
+/** `grep -l --null` output: the matching files, each followed by NUL. */
+function parseFileList(stdout, base) {
+    const parts = stdout.split("\0");
+    // the last part is empty, or an incomplete name when the output was truncated: dropped
+    parts.pop();
+    return parts.filter((n) => n !== "").map((n) => `${base}/${displayName(n)}`);
+}
+/**
+ * `grep -c` output as `<path>:<count>` for the files with at least one matching line. GNU grep
+ * with `--null` writes `<file>\0<count>\n`; other implementations write `<file>:<count>`.
+ */
+function parseCounts(stdout, base) {
+    const out = [];
+    if (stdout.includes("\0")) {
+        for (const l of parseGrepNull(stdout, base, false)) {
+            if (!l.endsWith(":0"))
+                out.push(l);
+        }
+        return out;
+    }
+    for (const line of stdout.split("\n")) {
+        const i = line.lastIndexOf(":");
+        if (i <= 0)
+            continue;
+        const count = line.slice(i + 1);
+        if (count === "0" || !/^\d+$/.test(count))
+            continue;
+        out.push(`${base}/${displayName(line.slice(0, i))}:${count}`);
+    }
+    return out;
+}
+/** 内置工具 `Grep`：按正则搜文件内容（只读）。 */
 export function sandboxGrepTool(deps) {
     return {
         spec: SPEC,
@@ -73,9 +156,15 @@ export function sandboxGrepTool(deps) {
         timeoutMs: () => sandboxBaseTimeoutMs(deps.config.get()),
         async run(input, ctx) {
             const startedAt = Date.now();
-            const { pattern, glob, ignoreCase = false } = input;
-            const path = checkPath(input.path ?? "/workspace");
-            const { value, notices } = await inSandbox(deps, ctx, async ({ h, p, signal }) => {
+            const g = input;
+            const { pattern, glob } = g;
+            const mode = g.output_mode ?? "files_with_matches";
+            const numbered = g["-n"] ?? true;
+            if (g.path !== undefined)
+                checkPathShape(g.path);
+            let path = "";
+            const { value, notices } = await inSandbox(deps, ctx, async ({ h, roots, p, signal }) => {
+                path = checkPath(g.path ?? roots.workspace, roots);
                 const st = await p.stat(h, path, signal);
                 if (st === null)
                     throw new ToolError(notFound(path));
@@ -83,10 +172,22 @@ export function sandboxGrepTool(deps) {
                 const slash = path.lastIndexOf("/");
                 const cwd = st.isDir ? path : path.slice(0, slash) || "/";
                 const target = st.isDir ? "." : path.slice(slash + 1);
+                const base = cwd === "/" ? "" : cwd;
+                // GNU grep options (`-l`, `-c`, `-n`, `-A/-B/-C`, `--null`): the sandbox images are Debian
+                const modeFlags = mode === "files_with_matches"
+                    ? ["-rlIE", "--null"]
+                    : mode === "count"
+                        ? ["-rcHIE", "--null"]
+                        : [numbered ? "-rnHIE" : "-rHIE", "--null"];
+                const context = mode === "content"
+                    ? ["-A", "-B", "-C"].flatMap((f) => g[f] !== undefined ? [f, String(g[f])] : [])
+                    : [];
                 const command = [
                     // --null：文件名后跟 NUL 而不是 `:`，文件名里有换行或冒号也能解析
-                    "grep -rnHIE --null",
-                    ...(ignoreCase ? ["-i"] : []),
+                    "grep",
+                    ...modeFlags,
+                    ...(g["-i"] === true ? ["-i"] : []),
+                    ...context,
                     ...(glob !== undefined ? [`--include=${shellQuote(glob)}`] : []),
                     "-e",
                     shellQuote(pattern),
@@ -103,27 +204,45 @@ export function sandboxGrepTool(deps) {
                 if (r.timedOut || r.exitCode === null)
                     throw new ToolError(GREP_TIMEOUT);
                 if (r.exitCode === 1)
-                    return { lines: [], warning: null };
-                const all = parseGrepNull(r.stdout, cwd === "/" ? "" : cwd);
-                const lines = all.filter((l) => !l.startsWith(`${SYNC_MARKER}:`));
+                    return { entries: [], warning: null };
+                const all = mode === "files_with_matches"
+                    ? parseFileList(r.stdout, base)
+                    : mode === "count"
+                        ? parseCounts(r.stdout, base)
+                        : parseGrepNull(r.stdout, base, numbered);
+                const isMarker = syncMarkerMatcher(roots);
+                const entries = all.filter((l) => !isMarker(l));
                 // 退出码 2 = 有错误（如个别文件不可读）；有输出时照常返回（可能为空：只匹配到隐藏的标记文件）并附上说明
                 if (r.exitCode !== 0 && all.length === 0)
                     throw new ToolError(failed(r.stderr));
                 const warning = r.exitCode !== 0 ? clip(r.stderr, 300) : null;
-                return { lines, warning };
+                return { entries, warning };
             });
-            const { lines, warning } = value;
-            const shown = lines
-                .slice(0, MAX_MATCHES)
-                .map((l) => (l.length > MAX_LINE_CHARS ? `${l.slice(0, MAX_LINE_CHARS)}…` : l));
+            const { entries, warning } = value;
+            const total = entries.length;
+            const offset = g.offset ?? 0;
+            const headLimit = g.head_limit === undefined ? DEFAULT_HEAD_LIMIT : g.head_limit;
+            const limit = headLimit === 0 ? MAX_MATCHES : Math.min(headLimit, MAX_MATCHES);
+            const page = entries.slice(offset, offset + limit);
+            const shown = page.map((l) => l.length > MAX_LINE_CHARS ? `${l.slice(0, MAX_LINE_CHARS)}…` : l);
             const note = warning !== null ? `\n[grep also reported errors: ${warning}]` : "";
-            const text = (lines.length === 0
-                ? `No matches for ${pattern} in ${path}.`
-                : shown.join("\n") +
-                    (lines.length > MAX_MATCHES
-                        ? `\n[Showing the first ${MAX_MATCHES} of ${lines.length} matching lines; use a narrower pattern, path or glob.]`
-                        : "")) + note;
-            const n = lines.length;
+            let text;
+            if (total === 0) {
+                text = `No matches for ${pattern} in ${path}.${note}`;
+            }
+            else if (page.length === 0) {
+                text = `No more results (${total} total).${note}`;
+            }
+            else {
+                const end = offset + page.length;
+                text =
+                    shown.join("\n") +
+                        (end < total
+                            ? `\n[Showing entries ${offset + 1}–${end} of ${total}; pass offset=${end} to continue, or use a narrower pattern, path or glob.]`
+                            : "") +
+                        note;
+            }
+            const n = total;
             return {
                 content: [{ type: "text", text: withNotices(notices, text) }],
                 display: display(`搜索 ${clip(pattern, 120)}（${n} 处）`, `Searched for ${clip(pattern, 120)} (${n} match${n === 1 ? "" : "es"})`),