opencode-readseek 0.12.0 → 0.12.1

package/README.md

@@ -68,9 +68,14 @@ is retained separately in `metadata.readseek`; image attachments are unchanged.
 references and renames use line or hash cursors. KDL selection/check rules
 may be inline or `@path`; tool calls cannot supply standard input.
 
-`readseek_grep` accepts exactly one of literal `text` or regex `pattern`.
-The adapter also supports `literal`, `ignoreCase`, `glob`, `context`, `limit`,
-and per-file `summary`. Native `grep` searches literally.
+`readseek_grep` requires `pattern`: native UTF-8 RE2 regex by default, or exact
+text with `literal: true`. Lookaround and backreferences are unsupported.
+Native ReadSeek handles `ignoreCase`, `glob`, `context`, `summary`, and
+`scope: "symbol"` grouping. `scopeContext` requires symbol scope. The positive
+`limit` defaults to 100 matching lines, not occurrences. `gitScope` accepts
+`tracked`, `untracked`, `ignored`, or `all` (default: tracked plus untracked).
+Source hits carry editable `LINE:HASH` anchors; document hits carry node/page
+selectors and do not mark files as editable.
 
 Read fresh `LINE:HASH` anchors before editing. Each edit item contains exactly
 one nested `set_line`, `replace_lines`, `insert_after`, `replace_symbol`, or

package/dist/index.js

@@ -43,7 +43,7 @@ var PARAM_DESCRIPTIONS = {
   pattern: "AST pattern (ast-grep style), such as console.log($$$ARGS)",
   patternContext: "Surrounding code context for sub-statement patterns",
   selector: "Target AST node kind to extract from pattern context",
-  grepPattern: "Regex pattern; set literal for exact text",
+  grepPattern: "Native regex pattern; set literal for exact text. Empty regex matches every line; empty literal is invalid.",
   name: "Qualified or unqualified symbol name",
   refsName: "Identifier to find references for",
   gitScope: "In a Git repository, which files to search: tracked, untracked, ignored (untracked plus ignored), or all. Defaults to tracked plus untracked.",
@@ -60,7 +60,6 @@ var PARAM_DESCRIPTIONS = {
   kind: "Restrict structure to this node kind",
   outline: "Show outline of document hierarchy or source symbols",
   noAnchors: "Omit source line anchors",
-  text: "Literal native text query; adapter grep also supports regex via pattern",
   edits: "Use set_line, replace_lines, insert_after, replace_symbol, or replace",
   editVariant: "Exactly one nested edit variant",
   setLine: 'Replace one line: {"set_line":{"anchor":"LINE:HASH","new_text":"..."}}',
@@ -92,9 +91,10 @@ var PARAM_DESCRIPTIONS = {
   literal: "Treat pattern literally",
   context: "Surrounding lines for each match",
   matchLimit: "Maximum matches to return",
+  grepLimit: "Maximum matching lines to return; positive integer, defaults to 100",
   summary: "Return per-file counts",
   grepScope: "Group matches by enclosing symbol",
-  scopeContext: "Context lines within each symbol"
+  scopeContext: "Non-negative context lines within each symbol; requires scope: symbol"
 };
 var TOOL_DESCRIPTIONS = {
   show: "Read source, document content, or image descriptors without inference. Obtain fresh `LINE:HASH` anchors before edits; use at with a column for cursor context. Document results include typed nodes and cached asset paths.",
@@ -107,7 +107,7 @@ var TOOL_DESCRIPTIONS = {
   objects: "Explicitly infer object labels and bounding boxes using an installed model.",
   ocr: "Explicitly recognize text from pixels using an installed model; reading never silently invokes OCR.",
   search: "Find AST nodes by pattern or KDL selection rule. Returns edit-ready anchors. Use `grep` for text and regex.",
-  grep: "Search text or regex and return edit-ready `LINE:HASH` anchors. Native CLI text is literal; adapters preserve regex, glob, context, summary, and symbol grouping.",
+  grep: "Search with native regex or literal matching. Returns matching-line counts, source LINE:HASH anchors, and document node-local locations. Native glob, context, summary, limits, Git scope, and symbol grouping apply; default limit is 100 matching lines.",
   def: "Find a symbol definition or declaration by qualified or unqualified name.",
   refs: "Find identifier-name matches with name, or binding-scoped references with at. Use before renaming or deleting a symbol.",
   edit: "Edit existing files with fresh `LINE:HASH` anchors. Each edits item contains exactly one set_line, replace_lines, insert_after, replace_symbol, or replace object. Preview before applying a verified plan.",
@@ -215,7 +215,7 @@ var TOOL_CONTRACTS = [
   tool("objects", "Detect objects", { ...path, ...at, ...stdin, ...level }, ["path"]),
   tool("ocr", "Recognize text", { ...path, ...at, ...stdin, ...level }, ["path"]),
   tool("search", "Search AST nodes", { ...path, ...lang, ...stdin, ...limit, ...gitScopeSchema, ...noAnchors, pattern: string(PARAM_DESCRIPTIONS.pattern), context: string(PARAM_DESCRIPTIONS.patternContext), selector: string(PARAM_DESCRIPTIONS.selector), rule: string(PARAM_DESCRIPTIONS.rule) }, []),
-  tool("grep", "Search text", { ...path, ...limit, ...gitScopeSchema, text: string(PARAM_DESCRIPTIONS.text), pattern: string(PARAM_DESCRIPTIONS.grepPattern), glob: string(PARAM_DESCRIPTIONS.glob), ignoreCase: { type: "boolean", description: PARAM_DESCRIPTIONS.ignoreCase }, literal: { type: "boolean", description: PARAM_DESCRIPTIONS.literal }, context: integer(PARAM_DESCRIPTIONS.context, 0), summary: { type: "boolean", description: PARAM_DESCRIPTIONS.summary }, scope: { type: "string", enum: ["symbol"], description: PARAM_DESCRIPTIONS.grepScope }, scopeContext: integer(PARAM_DESCRIPTIONS.scopeContext, 0) }, []),
+  tool("grep", "Search text", { path: string(PARAM_DESCRIPTIONS.searchPath), limit: { ...integer(PARAM_DESCRIPTIONS.grepLimit), default: 100 }, ...gitScopeSchema, pattern: string(PARAM_DESCRIPTIONS.grepPattern), glob: string(PARAM_DESCRIPTIONS.glob), ignoreCase: { type: "boolean", description: PARAM_DESCRIPTIONS.ignoreCase }, literal: { type: "boolean", description: PARAM_DESCRIPTIONS.literal }, context: integer(PARAM_DESCRIPTIONS.context, 0), summary: { type: "boolean", description: PARAM_DESCRIPTIONS.summary }, scope: { type: "string", enum: ["symbol"], description: PARAM_DESCRIPTIONS.grepScope }, scopeContext: integer(PARAM_DESCRIPTIONS.scopeContext, 0) }, ["pattern"]),
   tool("def", "Find definitions", { ...path, ...lang, ...gitScopeSchema, ...noAnchors, name: string(PARAM_DESCRIPTIONS.name) }, ["name"]),
   tool("refs", "Find references", { ...path, ...at, ...lang, ...gitScopeSchema, ...noAnchors, name: string(PARAM_DESCRIPTIONS.refsName) }, []),
   tool("edit", "Hash-verified edit", { ...path, ...lang, ...gitScopeSchema, ...apply, edits: { type: "array", minItems: 1, items: editItemSchema, description: PARAM_DESCRIPTIONS.edits }, postEditVerify: { type: "boolean", description: PARAM_DESCRIPTIONS.postEditVerify } }, ["path", "edits"]),
@@ -234,7 +234,7 @@ var PREFERENCE_LEADS = {
   show: "Preferred for reading source with anchors.",
   edit: "Preferred for editing existing text files with fresh LINE:HASH anchors.",
   write: "Preferred for creating or replacing a complete text file; returns LINE:HASH anchors.",
-  grep: "Preferred text/regex search; returns edit-ready LINE:HASH anchors.",
+  grep: "Preferred native text/regex search; returns edit-ready source LINE:HASH anchors and document node-local locations.",
   search: "Preferred for AST or structural code search with ast-grep-style patterns.",
   def: "Preferred for go-to-definition or declaration lookup by name.",
   refs: "Preferred for finding identifier-name matches or binding-specific references before `rename` or delete.",
@@ -245,7 +245,7 @@ var FALLBACK_TEMPLATES = {
   read: "Prefer `show` with fresh LINE:HASH anchors.",
   edit: "Prefer `edit` with fresh LINE:HASH anchors.",
   write: "Prefer `write` so the result returns LINE:HASH anchors.",
-  grep: "Prefer `grep` for text/regex search with edit-ready anchors.",
+  grep: "Prefer `grep` for native text/regex search with source anchors and document locations.",
   apply_patch: "Prefer `edit` for existing text files."
 };
 function resolveToolName(name, aliases = {}) {
@@ -316,6 +316,59 @@ function validateReferencesSelection(input) {
     return { ok: false, error: "exactly one of name or at is required" };
   return { ok: true };
 }
+function validateGrepParams(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    return { ok: false, error: "grep params must be an object" };
+  }
+  const params = input;
+  const allowed = [
+    "pattern",
+    "path",
+    "glob",
+    "ignoreCase",
+    "literal",
+    "context",
+    "limit",
+    "summary",
+    "scope",
+    "scopeContext",
+    "gitScope",
+    "signal",
+    "stdin",
+    "timeoutMs",
+    "cancelable"
+  ];
+  if (Object.keys(params).some((key) => !allowed.includes(key)))
+    return { ok: false, error: "unknown grep parameter" };
+  if (typeof params.pattern !== "string")
+    return { ok: false, error: "grep requires a pattern string" };
+  if (params.literal === true && params.pattern.length === 0)
+    return { ok: false, error: "literal pattern must not be empty" };
+  for (const key of ["path", "glob"]) {
+    if (params[key] !== undefined && (typeof params[key] !== "string" || params[key].length === 0)) {
+      return { ok: false, error: `${key} must be a non-empty string` };
+    }
+  }
+  for (const key of ["ignoreCase", "literal", "summary"]) {
+    if (params[key] !== undefined && typeof params[key] !== "boolean")
+      return { ok: false, error: `${key} must be a boolean` };
+  }
+  for (const key of ["context", "limit", "scopeContext"]) {
+    const value = params[key];
+    const minimum = key === "limit" ? 1 : 0;
+    if (value !== undefined && (typeof value !== "number" || !Number.isSafeInteger(value) || value < minimum)) {
+      return { ok: false, error: `${key} must be a ${minimum === 1 ? "positive" : "non-negative"} integer` };
+    }
+  }
+  if (params.scope !== undefined && params.scope !== "symbol")
+    return { ok: false, error: "scope must be symbol" };
+  if (params.scopeContext !== undefined && params.scope !== "symbol")
+    return { ok: false, error: "scopeContext requires scope" };
+  if (params.gitScope !== undefined && !GIT_SCOPES.includes(params.gitScope)) {
+    return { ok: false, error: "invalid gitScope" };
+  }
+  return { ok: true };
+}
 var VARIANT_FIELDS = {
   set_line: ["anchor", "new_text"],
   replace_lines: ["start_anchor", "end_anchor", "new_text"],
@@ -645,11 +698,29 @@ function buildSearchArgs(input) {
   return finish(args);
 }
 function buildGrepArgs(input) {
-  const args = start("grep", input);
-  args.push("--text", input.text);
-  limit2(args, input.limit);
+  const validated = validateGrepParams(input);
+  if (!validated.ok)
+    throw new Error(validated.error);
+  const args = ["grep", "--kdl", `--pattern=${input.pattern}`];
+  const needsPathTerminator = input.path !== undefined && input.path.startsWith("-") && input.path !== "-";
+  if (input.path !== undefined && !needsPathTerminator)
+    args.push(input.path);
+  if (input.literal)
+    args.push("--literal");
+  if (input.ignoreCase)
+    args.push("--ignore-case");
+  if (input.glob !== undefined)
+    args.push(`--glob=${input.glob}`);
+  pushOptionalNumber(args, "--context", input.context);
+  limit2(args, input.limit ?? 100);
+  if (input.summary)
+    args.push("--summary");
+  pushOptionalString(args, "--scope", input.scope);
+  pushOptionalNumber(args, "--scope-context", input.scopeContext);
   appendGitScopeArgs(args, input);
-  return finish(args);
+  if (input.path !== undefined && needsPathTerminator)
+    args.push("--", input.path);
+  return args;
 }
 function buildDefArgs(input) {
   const args = start("def", input);
@@ -704,6 +775,17 @@ function buildRenameArgs(input) {
 // ../readseek-api/src/client-output.ts
 import { Type } from "@sinclair/typebox";
 import { AssertError, Value } from "@sinclair/typebox/value";
+var OPERATIONS = ["Clone", "Clean", "Default", "Assert"];
+function parse(schema, value, what) {
+  try {
+    return Value.Parse(OPERATIONS, schema, value);
+  } catch (error) {
+    if (!(error instanceof AssertError))
+      throw error;
+    const detail = error.error;
+    throw new Error(`invalid readseek ${what}${detail?.path ?? ""}: ${detail?.message ?? "invalid value"}`);
+  }
+}
 var Int = Type.Integer({ minimum: Number.MIN_SAFE_INTEGER, maximum: Number.MAX_SAFE_INTEGER });
 var Str = Type.String();
 var Bool = Type.Boolean();
@@ -938,6 +1020,82 @@ var DefEnvelope = Type.Object({
     qualified_name: OptStr
   }))
 });
+function parseReadOutput(value) {
+  return parse(ReadOutput, value, "read output");
+}
+function parseStructureOutput(value) {
+  return parse(StructureOutput, value, "structure output");
+}
+function parseSearchOutput(value) {
+  const envelope = parse(SearchEnvelope, value, "search output");
+  const results = envelope.results;
+  if (envelope.returned_matches !== undefined)
+    results.returned_matches = envelope.returned_matches;
+  if (envelope.truncated !== undefined)
+    results.truncated = envelope.truncated;
+  if (envelope.byte_basis !== undefined)
+    results.byte_basis = envelope.byte_basis;
+  return results;
+}
+function parseRefsOutput(value) {
+  return parse(RefsEnvelope, value, "refs output").references.map(({ symbol, ...reference }) => ({
+    ...reference,
+    enclosingSymbol: symbol?.qualified_name
+  }));
+}
+function parseCheckOutput(value) {
+  const output = parse(CheckEnvelope, value, "check output");
+  return {
+    file_hash: output.file_hash,
+    errorCount: output.error_count,
+    missingCount: output.missing_count,
+    diagnostics: output.diagnostics
+  };
+}
+function parseDetectOutput(value) {
+  const output = value ?? {};
+  if (output.type === "application/pdf") {
+    return { kind: "pdf", ...parse(PdfDetectionInput, value, "detect output") };
+  }
+  if (output.width !== undefined || output.height !== undefined) {
+    return { kind: "image", ...parse(ImageDetectionInput, value, "detect output") };
+  }
+  if (output.language !== undefined) {
+    return { kind: "source", ...parse(SourceDetectionInput, value, "detect output") };
+  }
+  return { kind: "text", ...parse(TextDetectionInput, value, "detect output") };
+}
+function parseTextContent(value) {
+  const output = value ?? {};
+  if (output.hashlines === undefined || output.start_line !== undefined)
+    return parseReadOutput(value);
+  const spanned = parse(UnspannedContent, value, "content");
+  return {
+    ...spanned,
+    start_line: spanned.hashlines[0]?.line ?? 1,
+    end_line: spanned.hashlines[spanned.hashlines.length - 1]?.line ?? 0
+  };
+}
+function parseCursorOutput(value) {
+  return parse(CursorEnvelope, value, "cursor output");
+}
+function parsePdfMetadata(value) {
+  if (!value || typeof value !== "object")
+    return;
+  if (value.format !== "pdf")
+    return;
+  const document = parse(PdfMetadata, value, "inspect metadata");
+  return { kind: "pdf", type: "application/pdf", file: document.source, format: "pdf", pages: document.pages };
+}
+function parseEditOutput(value) {
+  return parse(EditOutputSchema, value, "edit output");
+}
+function parseRenameOutput(value) {
+  return parse(RenameOutputSchema, value, "rename output");
+}
+function parseDefOutput(value) {
+  return parse(DefEnvelope, value, "def output").locations;
+}
 var Bbox = Type.Object({ x: Type.Number(), y: Type.Number(), width: Type.Number(), height: Type.Number() });
 var Position = { page: OptInt, destination: OptStr, bbox: Type.Optional(Bbox) };
 var Provenance = { inferred: Type.Optional(Bool), model: OptStr, level: OptStr, task: OptStr };
@@ -994,25 +1152,41 @@ var DocumentOutput = Type.Object({
   assets: Type.Array(DocumentAsset, { default: [] }),
   vision: Type.Array(DocumentVision, { default: [] })
 });
-var TextHit = Type.Object({
-  line: Int,
-  column: Int,
+var GrepCount = Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER });
+var GrepPosition = Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER });
+var GrepAnchor = Type.String({ pattern: "^[1-9][0-9]*:[0-9a-f]{6}$" });
+var GrepLineSchema = Type.Object({
+  line: GrepPosition,
+  hash: Type.String({ pattern: "^[0-9a-f]{6}$" }),
   text: Str,
-  start_line: Int,
-  end_line: Int,
-  start_byte: Int,
-  end_byte: Int,
-  hashlines: Hashlines
+  kind: Type.Union([Type.Literal("match"), Type.Literal("context")])
 });
-var DocumentHit = Type.Object({ node_id: Str, kind: Str, snippet: Str, page: OptInt });
-var TextSearchOutput = Type.Object({
-  text: Str,
-  mode: Type.Literal("literal"),
-  total_matches: Int,
-  returned_matches: Int,
+var GrepHitSchema = Type.Object({ line: GrepPosition, column: GrepPosition, start_byte: GrepCount, end_byte: GrepCount, text: Str, anchor: GrepAnchor });
+var GrepSymbolSchema = Type.Object({ name: Str, kind: Str, start_line: GrepPosition, end_line: GrepPosition, lines: Type.Array(GrepLineSchema) });
+var GrepSourceResultSchema = Type.Object({
+  file: Str,
+  file_hash: Str,
+  language: Str,
+  total_matches: GrepCount,
+  returned_matches: GrepCount,
+  hits: Type.Array(GrepHitSchema),
+  lines: Type.Array(GrepLineSchema),
+  symbols: Type.Array(GrepSymbolSchema)
+});
+var GrepDocumentHitSchema = Type.Object({ node_id: Str, kind: Str, snippet: Str, line: GrepPosition, page: Type.Optional(GrepPosition) });
+var GrepDocumentResultSchema = Type.Object({ file: Str, content_hash: Str, total_matches: GrepCount, returned_matches: GrepCount, hits: Type.Array(GrepDocumentHitSchema) });
+var GrepOutputSchema = Type.Object({
+  pattern: Str,
+  mode: Type.Union([Type.Literal("regex"), Type.Literal("literal")]),
+  ignore_case: Bool,
+  summary: Bool,
+  total_matches: GrepCount,
+  returned_matches: GrepCount,
   truncated: Bool,
-  results: Type.Array(Type.Object({ file: Str, file_hash: Str, matches: Type.Array(TextHit) })),
-  documents: Type.Array(Type.Object({ file: Str, content_hash: Str, hits: Type.Array(DocumentHit) }))
+  count_unit: Type.Literal("lines"),
+  scope: Type.Optional(Type.Literal("symbol")),
+  results: Type.Array(GrepSourceResultSchema),
+  documents: Type.Array(GrepDocumentResultSchema)
 });
 var RuleFinding = Type.Object({
   name: Str,
@@ -1033,7 +1207,72 @@ var RulesOutput = Type.Object({
   violation_count: Int,
   diagnostics: Type.Array(RuleFinding)
 });
+function parseDocumentOutput(value) {
+  return parse(DocumentOutput, value, "document output");
+}
+function parseContentOutput(value) {
+  const output = value;
+  if (output?.format !== undefined)
+    return parseDocumentOutput(value);
+  if (!output || output.metadata === undefined || output.content === undefined)
+    throw new Error("invalid readseek content: missing metadata or content");
+  const metadata = parseDetectOutput(output.metadata);
+  return {
+    metadata,
+    content: metadata.kind === "image" ? parse(ImageDescriptor, output.content, "image descriptor") : parseTextContent(output.content),
+    ...output.cursor !== undefined ? { cursor: parseCursorOutput(output.cursor) } : {}
+  };
+}
+function parseStructureEnvelope(value) {
+  const output = value;
+  if (output?.format !== undefined)
+    return parseDocumentOutput(value);
+  if (!output || output.structure === undefined)
+    throw new Error("invalid readseek structure: missing structure");
+  return { ...output.metadata !== undefined ? { metadata: parseDetectOutput(output.metadata) } : {}, structure: parseStructureOutput(output.structure) };
+}
+function parseGrepOutput(value) {
+  const output = parse(GrepOutputSchema, value, "grep output");
+  const invalid = (message) => {
+    throw new Error(`invalid readseek grep output: ${message}`);
+  };
+  const groups = [...output.results, ...output.documents];
+  if (output.returned_matches > output.total_matches || groups.reduce((sum, group) => sum + group.total_matches, 0) !== output.total_matches || groups.reduce((sum, group) => sum + group.returned_matches, 0) !== output.returned_matches)
+    invalid("inconsistent counts");
+  for (const group of groups) {
+    if (group.total_matches === 0 || group.returned_matches > group.total_matches)
+      invalid("inconsistent file counts");
+    if (output.summary ? group.hits.length !== 0 : group.hits.length !== group.returned_matches)
+      invalid("inconsistent hit count");
+  }
+  for (const result of output.results) {
+    if (output.summary && (result.lines.length > 0 || result.symbols.length > 0))
+      invalid("summary contains display entries");
+    if (output.scope !== "symbol" && result.symbols.length > 0)
+      invalid("symbols require symbol scope");
+    for (const hit of result.hits) {
+      if (hit.end_byte < hit.start_byte || Number(hit.anchor.split(":")[0]) !== hit.line)
+        invalid("invalid hit span or anchor");
+    }
+    for (const symbol of result.symbols) {
+      if (symbol.end_line < symbol.start_line || symbol.lines.some((line) => line.line < symbol.start_line || line.line > symbol.end_line))
+        invalid("invalid symbol range");
+    }
+  }
+  return output;
+}
+function parseRulesOutput(value) {
+  return parse(RulesOutput, value, "rules output");
+}
 var SourceAssetsOutput = Type.Object({ file: OptStr, metadata: Type.Optional(Detection), assets: Type.Array(DocumentAsset, { default: [] }) });
+function parseAssetsOutput(value) {
+  const raw = value;
+  if (raw?.format !== undefined)
+    return parseDocumentOutput(value);
+  if (!raw || raw.file === undefined && raw.metadata === undefined)
+    throw new Error("invalid readseek assets output: missing file or metadata");
+  return parse(SourceAssetsOutput, { ...raw, ...raw.metadata !== undefined ? { metadata: parseDetectOutput(raw.metadata) } : {} }, "assets output");
+}
 
 // ../readseek-api/src/edit-plan.ts
 import { Document, Node, format } from "@bgotink/kdl";
@@ -1075,6 +1314,81 @@ function serializeEditPlan(edits) {
     throw new Error(validation.error);
   return format(new Document([node("plan", {}, validation.edits.map(editNode))]));
 }
+
+// ../readseek-api/src/client.ts
+function runOptions(options, vision = false) {
+  return {
+    signal: options.signal,
+    stdin: options.stdin,
+    timeoutMs: options.timeoutMs,
+    cancelable: options.cancelable,
+    ...vision ? { vision: true } : {}
+  };
+}
+function createReadSeekClient(runner) {
+  return {
+    async show(path, options = {}) {
+      const value = await runner.kdl(buildShowArgs({ ...options, path }), runOptions(options));
+      return parseContentOutput(value);
+    },
+    async tree(path, options = {}) {
+      const value = await runner.kdl(buildTreeArgs({ ...options, path }), runOptions(options));
+      return parseStructureEnvelope(value);
+    },
+    async meta(path, options = {}) {
+      const value = await runner.kdl(buildMetaArgs({ ...options, path }), runOptions(options));
+      return parsePdfMetadata(value) ?? parseDetectOutput(value?.metadata);
+    },
+    async assets(path, options = {}) {
+      const value = await runner.kdl(buildAssetsArgs({ ...options, path }), runOptions(options));
+      return parseAssetsOutput(value);
+    },
+    async syntax(path, options = {}) {
+      const value = await runner.kdl(buildSyntaxArgs({ ...options, path }), runOptions(options));
+      return parseCheckOutput(value?.diagnostics ?? value);
+    },
+    async check(path, options) {
+      const value = await runner.kdl(buildCheckArgs({ ...options, path }), runOptions(options));
+      return parseRulesOutput(value);
+    },
+    async caption(path, options = {}) {
+      const value = await runner.kdl(buildCaptionArgs({ ...options, path }), runOptions(options, true));
+      return parseContentOutput(value);
+    },
+    async objects(path, options = {}) {
+      const value = await runner.kdl(buildObjectsArgs({ ...options, path }), runOptions(options, true));
+      return parseContentOutput(value);
+    },
+    async ocr(path, options = {}) {
+      const value = await runner.kdl(buildOcrArgs({ ...options, path }), runOptions(options, true));
+      return parseContentOutput(value);
+    },
+    async search(path, options) {
+      const value = await runner.kdl(buildSearchArgs({ ...options, path }), runOptions(options));
+      return parseSearchOutput(value);
+    },
+    async grep(params) {
+      const value = await runner.kdl(buildGrepArgs(params), runOptions(params));
+      return parseGrepOutput(value);
+    },
+    async def(path, options) {
+      const value = await runner.kdl(buildDefArgs({ ...options, path }), runOptions(options));
+      return parseDefOutput(value);
+    },
+    async refs(path, options) {
+      const value = await runner.kdl(buildRefsArgs({ ...options, path }), runOptions(options));
+      return parseRefsOutput(value);
+    },
+    async edit(path, edits, options = {}) {
+      const stdin = serializeEditPlan(edits);
+      return parseEditOutput(await runner.kdl(buildEditArgs({ ...options, path, requestFromStdin: true }), runOptions({ ...options, stdin })));
+    },
+    async rename(path, options) {
+      const value = await runner.kdl(buildRenameArgs({ ...options, path }), runOptions(options));
+      return parseRenameOutput(value);
+    }
+  };
+}
 // ../readseek-api/src/show-presentation.ts
 function isShowTool(name) {
   return name === "show" || name === "tree" || name === "meta" || name === "assets";
@@ -1290,6 +1604,31 @@ function formatShowResult(presentation) {
 
 `);
 }
+// ../readseek-api/src/grep-presentation.ts
+function renderGrepOutput(output) {
+  const rendered = [`${output.returned_matches} of ${output.total_matches} matching lines${output.truncated ? " (truncated)" : ""}`];
+  const displayLine = (line) => `${line.line}:${line.hash}|${line.kind === "match" ? ">>" : "  "}${line.text}`;
+  for (const result of output.results) {
+    rendered.push(`${result.file}: ${result.total_matches} matching lines (${result.returned_matches} returned)`);
+    if (output.summary)
+      continue;
+    rendered.push(...result.lines.map(displayLine));
+    for (const symbol of result.symbols) {
+      rendered.push(`  ${symbol.kind} ${symbol.name} (${symbol.start_line}-${symbol.end_line})`);
+      rendered.push(...symbol.lines.map(displayLine));
+    }
+  }
+  for (const document of output.documents) {
+    rendered.push(`${document.file}: ${document.total_matches} matching lines (${document.returned_matches} returned)`);
+    if (output.summary)
+      continue;
+    for (const hit of document.hits) {
+      rendered.push(`  node:${hit.node_id}${hit.page === undefined ? "" : ` page:${hit.page}`} line:${hit.line} (${hit.kind}): ${hit.snippet}`);
+    }
+  }
+  return rendered.join(`
+`);
+}
 // ../readseek-api/src/platform.ts
 import { accessSync, constants as fsConstants, existsSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
@@ -1391,7 +1730,7 @@ function cleanReadSeekErrorText(stderr) {
   return stderr.replace(READSEEK_USAGE_HINT, "").replace(/^error:\s*/i, "").replace(/\s*\n\s*/g, " ").trim();
 }
 // ../readseek-api/src/kdl.ts
-import { parse } from "@bgotink/kdl";
+import { parse as parse2 } from "@bgotink/kdl";
 function convertNode(node) {
   if (node.getTag() !== null)
     throw new Error("KDL node annotations are not supported");
@@ -1419,7 +1758,7 @@ function convertNode(node) {
   };
 }
 function parseKdlDocument(text) {
-  const document = parse(text);
+  const document = parse2(text);
   if (document.nodes.length !== 1)
     throw new Error("KDL document must contain exactly one root node");
   return convertNode(document.nodes[0]);
@@ -1553,6 +1892,46 @@ function search(root) {
     }))
   };
 }
+function grepChildren(node, allowed) {
+  if (node.children.some((child) => !allowed.includes(child.name))) {
+    throw new Error(`invalid readseek KDL grep: unexpected child of ${node.name}`);
+  }
+}
+function grepLine(node) {
+  grepChildren(node, []);
+  const parsed = line(node);
+  if (requireProperty(node, "number") !== parsed.line)
+    throw new Error("invalid readseek KDL grep line number");
+  return { ...parsed, kind: requireProperty(node, "kind") };
+}
+function grep(root) {
+  grepChildren(root, ["match", "document"]);
+  return parseGrepOutput({
+    ...properties(root),
+    results: children(root, "match").map((match) => {
+      grepChildren(match, ["hit", "line", "symbol"]);
+      return {
+        ...properties(match),
+        hits: children(match, "hit").map((hit) => {
+          grepChildren(hit, []);
+          return properties(hit);
+        }),
+        lines: children(match, "line").map(grepLine),
+        symbols: children(match, "symbol").map((symbol) => {
+          grepChildren(symbol, ["line"]);
+          return { ...properties(symbol), lines: children(symbol, "line").map(grepLine) };
+        })
+      };
+    }),
+    documents: children(root, "document").map((document) => {
+      grepChildren(document, ["hit"]);
+      return { ...properties(document), hits: children(document, "hit").map((hit) => {
+        grepChildren(hit, []);
+        return properties(hit);
+      }) };
+    })
+  });
+}
 function references(root) {
   const parsed = children(root, "reference").map((reference) => {
     const sourceLine = child(reference, "line");
@@ -1668,7 +2047,7 @@ function parseReadSeekKdl(text) {
     case "document":
       return root.properties.has("format") ? pdfDocument(root) : sourceDocument(root);
     case "search":
-      return search(root);
+      return ["mode", "ignore_case", "summary", "count_unit"].some((key) => root.properties.has(key)) ? grep(root) : search(root);
     case "check":
       return diagnostics(root);
     case "refs":
@@ -1867,8 +2246,8 @@ function collectAnchoredFiles(value, files) {
   if (!value || typeof value !== "object")
     return;
   const output = value;
-  const hashlines = output.hashlines;
-  if (typeof output.file === "string" && Array.isArray(hashlines) && hashlines.some((line) => typeof record2(line).line === "number" && typeof record2(line).hash === "string"))
+  const lineGroups = [output.hashlines, output.lines, ...items(output.symbols).map((symbol) => record2(symbol).lines)];
+  if (typeof output.file === "string" && lineGroups.some((lines) => items(lines).some((line) => typeof record2(line).line === "number" && typeof record2(line).hash === "string")))
     files.add(output.file);
   for (const item of Object.values(output))
     collectAnchoredFiles(item, files);
@@ -1981,6 +2360,12 @@ async function runReadSeek(context, args, options = {}) {
     timeoutMs: options.timeoutMs
   }));
 }
+function readSeekClient(context) {
+  return createReadSeekClient({
+    text: (args, options) => runReadSeekRaw(context, [...args], options),
+    kdl: (args, options) => runReadSeek(context, [...args], options)
+  });
+}
 async function runContent(context, args, options = {}) {
   return requireContent(await runReadSeek(context, args, options));
 }
@@ -2104,7 +2489,6 @@ ${[...paths].sort().map((filePath) => `- ${filePath}`).join(`
 }
 
 // src/tools.ts
-import { readFile as readFile2, stat as stat3 } from "node:fs/promises";
 import { tool as tool3 } from "@opencode-ai/plugin";
 
 // src/constants.ts
@@ -2448,7 +2832,7 @@ function initialTitle(kind, args) {
     case "search":
       return `Find nodes ${args.pattern ?? args.context ?? args.rule}`;
     case "grep":
-      return `Find text ${args.pattern ?? args.text}`;
+      return `Find text ${args.pattern}`;
     case "def":
       return `Find definition ${args.name}`;
     case "refs":
@@ -2480,12 +2864,9 @@ function resultPresentation(kind, args, value) {
       return { title: `Found ${matches} matches`, metadata: { results: results.length, matches } };
     }
     case "grep": {
-      const results = items(output.results);
-      const matches = results.reduce((total, result) => {
-        const entry = record2(result);
-        return total + (typeof entry.count === "number" ? entry.count : items(entry.matches).length);
-      }, 0);
-      return { title: `Found ${matches} matches`, metadata: { results: results.length, matches } };
+      const results = items(output.results).length + items(output.documents).length;
+      const matches = output.total_matches;
+      return { title: `Found ${matches} matches`, metadata: { results, matches } };
     }
     case "def": {
       const locations = items(output.locations).length;
@@ -2543,8 +2924,8 @@ function readseekTool(description, args, kind, execute, imagePolicy) {
       return {
         ...attachments.length > 0 ? { attachments } : {},
         title: presentation.title,
-        output: isShowTool(kind) ? formatShowResult(presentShowResult(kind, displayResult, args)) : render(displayResult),
-        metadata: { ...presentation.metadata, ...isShowTool(kind) ? { readseek: result } : {} }
+        output: isShowTool(kind) ? formatShowResult(presentShowResult(kind, displayResult, args)) : kind === "grep" ? renderGrepOutput(result) : render(displayResult),
+        metadata: { ...presentation.metadata, ...isShowTool(kind) || kind === "grep" ? { readseek: result } : {} }
       };
     }
   });
@@ -2555,104 +2936,35 @@ function createReadSeekTools(imagePolicy) {
   return {
     ...createAccessTools(imagePolicy),
     readseek_grep: readseekTool(openCodeToolDescription("grep"), {
-      pattern: tool3.schema.string().optional().describe(PARAM_DESCRIPTIONS.grepPattern),
-      text: tool3.schema.string().optional().describe(PARAM_DESCRIPTIONS.text),
+      pattern: tool3.schema.string().describe(PARAM_DESCRIPTIONS.grepPattern),
       summary: tool3.schema.boolean().optional().describe(PARAM_DESCRIPTIONS.summary),
       path: tool3.schema.string().optional().describe(PARAM_DESCRIPTIONS.projectSearchPath),
       glob: tool3.schema.string().optional().describe(PARAM_DESCRIPTIONS.glob),
       literal: tool3.schema.boolean().optional().describe(PARAM_DESCRIPTIONS.literal),
       ignoreCase: tool3.schema.boolean().optional().describe(PARAM_DESCRIPTIONS.ignoreCase),
       context: tool3.schema.number().int().nonnegative().optional().describe(PARAM_DESCRIPTIONS.context),
-      limit: tool3.schema.number().int().positive().optional().describe(PARAM_DESCRIPTIONS.matchLimit)
+      limit: tool3.schema.number().int().positive().optional().describe(PARAM_DESCRIPTIONS.matchLimit),
+      scope: tool3.schema.literal("symbol").optional().describe(PARAM_DESCRIPTIONS.grepScope),
+      scopeContext: tool3.schema.number().int().nonnegative().optional().describe(PARAM_DESCRIPTIONS.scopeContext),
+      gitScope: tool3.schema.enum(GIT_SCOPES).optional().describe(PARAM_DESCRIPTIONS.gitScope)
     }, "grep", async (input, context) => {
       const target = resolvePath(context.directory, input.path ?? ".");
-      if (input.pattern === undefined === (input.text === undefined)) {
-        throw new Error("exactly one of pattern or text is required");
-      }
-      const pattern = input.pattern ?? input.text;
+      const pattern = input.pattern;
       await authorizeSearch(context, target, pattern);
-      if (input.text !== undefined && !input.glob && !input.ignoreCase && !input.context && !input.summary) {
-        return runReadSeek(context, buildGrepArgs({ path: target, text: pattern, limit: input.limit }));
-      }
-      let expression;
-      try {
-        const source = input.literal || input.text !== undefined ? pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") : pattern;
-        expression = new RegExp(source, input.ignoreCase ? "i" : "");
-      } catch (error) {
-        throw new Error(`invalid regular expression: ${error instanceof Error ? error.message : String(error)}`);
-      }
-      const info = await stat3(target);
-      const files = [];
-      if (info.isFile())
-        files.push(target);
-      else if (info.isDirectory()) {
-        const glob = new Bun.Glob(input.glob ?? "**/*");
-        for await (const filePath of glob.scan({ cwd: target, absolute: true, onlyFiles: true, followSymlinks: false })) {
-          files.push(filePath);
-        }
-      } else
-        throw new Error(`grep target is not a file or directory: ${target}`);
-      const maxMatches = input.limit ?? 100;
-      const contextLines = input.context ?? 0;
-      const results = [];
-      let totalMatches = 0;
-      let truncated = false;
-      for (const filePath of files.sort()) {
-        context.abort.throwIfAborted();
-        if (truncated)
-          break;
-        const buffer = await readFile2(filePath);
-        if (buffer.includes(0))
-          continue;
-        const lines = buffer.toString("utf8").replace(/\r\n/g, `
-`).split(`
-`);
-        const matchLines = new Set;
-        const ranges = [];
-        for (let index = 0;index < lines.length; index++) {
-          expression.lastIndex = 0;
-          if (!expression.test(lines[index] ?? ""))
-            continue;
-          if (totalMatches === maxMatches) {
-            truncated = true;
-            break;
-          }
-          const line = index + 1;
-          matchLines.add(line);
-          ranges.push([Math.max(1, line - contextLines), Math.min(lines.length, line + contextLines)]);
-          totalMatches++;
-        }
-        if (ranges.length === 0)
-          continue;
-        if (input.summary) {
-          results.push({ file: filePath, count: matchLines.size });
-          continue;
-        }
-        const mergedRanges = [];
-        for (const [start, end] of ranges) {
-          const previous = mergedRanges.at(-1);
-          if (previous && start <= previous[1] + 1)
-            previous[1] = Math.max(previous[1], end);
-          else
-            mergedRanges.push([start, end]);
-        }
-        const linesByNumber = new Map;
-        for (const [start, end] of mergedRanges) {
-          const output = record2(await runContent(context, readRangeArgs(filePath, start, end)));
-          for (const hashline of items(output.hashlines)) {
-            const line = record2(hashline).line;
-            if (typeof line === "number" && !linesByNumber.has(line))
-              linesByNumber.set(line, hashline);
-          }
-        }
-        const hashlines = [...linesByNumber.values()];
-        const matches = hashlines.filter((hashline) => {
-          const line = record2(hashline).line;
-          return typeof line === "number" && matchLines.has(line);
-        });
-        results.push({ file: filePath, matches, hashlines });
-      }
-      return { results, truncated };
+      return readSeekClient(context).grep({
+        pattern,
+        path: target,
+        glob: input.glob,
+        ignoreCase: input.ignoreCase,
+        literal: input.literal,
+        context: input.context,
+        limit: input.limit,
+        summary: input.summary,
+        scope: input.scope,
+        scopeContext: input.scopeContext,
+        gitScope: input.gitScope,
+        signal: context.abort
+      });
     }),
     readseek_search: readseekTool(openCodeToolDescription("search"), {
       pattern: tool3.schema.string().optional().describe(PARAM_DESCRIPTIONS.pattern),
@@ -2951,7 +3263,7 @@ readseek edit file.ts @edits.kdl --kdl
 readseek rename file.ts --at line:10:3 nextName --kdl
 \`\`\`
 
-Native \`grep\` is literal, not regex. Reference selection requires either a symbol \`name\` or \`--at\`; rename requires a line or hash cursor. Preview mutations first, then use \`--apply --plan-hash HASH\` with the returned plan hash. Edit requests are KDL: for example, \`set_line anchor="10:HASH" new_text="replacement"\`.
+Native \`grep\` uses UTF-8 RE2 regex by default; add \`--literal\` for exact text. Its positive \`--limit\` defaults to 100 matching lines, not occurrences. Reference selection requires either a symbol \`name\` or \`--at\`; rename requires a line or hash cursor. Preview mutations first, then use \`--apply --plan-hash HASH\` with the returned plan hash. Edit requests are KDL: for example, \`set_line anchor="10:HASH" new_text="replacement"\`.
 
 Syntax and rule checks return exit 0 when clean, 1 for findings, and 2 on failure. Exit 1 is not a transport failure. Syntax checks are parser checks, not type checking.
 

package/dist/v2.js

@@ -26,7 +26,7 @@ readseek edit file.ts @edits.kdl --kdl
 readseek rename file.ts --at line:10:3 nextName --kdl
 \`\`\`
 
-Native \`grep\` is literal, not regex. Reference selection requires either a symbol \`name\` or \`--at\`; rename requires a line or hash cursor. Preview mutations first, then use \`--apply --plan-hash HASH\` with the returned plan hash. Edit requests are KDL: for example, \`set_line anchor="10:HASH" new_text="replacement"\`.
+Native \`grep\` uses UTF-8 RE2 regex by default; add \`--literal\` for exact text. Its positive \`--limit\` defaults to 100 matching lines, not occurrences. Reference selection requires either a symbol \`name\` or \`--at\`; rename requires a line or hash cursor. Preview mutations first, then use \`--apply --plan-hash HASH\` with the returned plan hash. Edit requests are KDL: for example, \`set_line anchor="10:HASH" new_text="replacement"\`.
 
 Syntax and rule checks return exit 0 when clean, 1 for findings, and 2 on failure. Exit 1 is not a transport failure. Syntax checks are parser checks, not type checking.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-readseek",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "description": "OpenCode plugin for anchored file operations and structural code navigation",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,8 +33,8 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@jarkkojs/readseek": "^0.12.0",
-    "@jarkkojs/readseek-api": "^0.12.0",
+    "@jarkkojs/readseek": "^0.12.1",
+    "@jarkkojs/readseek-api": "^0.12.1",
     "@opencode-ai/plugin": "^1.18.18"
   },
   "devDependencies": {