atom-agent 1.3.0 → 1.5.0

package/dist/tools/registry.js

@@ -6,7 +6,8 @@ import * as path from "node:path";
 import { editTool, readTool, writeTool, } from "./filesystem.js";
 import { GREP_OUTPUT_MODES, globTool, grepTool } from "./search.js";
 import { bashOutputTool, bashTool, } from "./shell.js";
-import { err, invalidCall } from "./shared.js";
+import { invalidCall } from "./shared.js";
+import { goalReportOutsideError, validateUpdateGoalArgs } from "../goal.js";
 import { clearCustomTools, customToolNames, getCustomTool, isCustomTool, listCustomTools, registerCustomTool, unregisterCustomTool, validateCustomToolArgs, validateExtensionToolDef, } from "./custom.js";
 export { validateExtensionToolDef } from "./custom.js";
 import { getToolOverride, isToolOverridden, registerToolOverride, unregisterToolOverride, validateExtensionToolOverrideDef, } from "./overrides.js";
@@ -44,20 +45,38 @@ export function needsApproval(name) {
         return custom.requireApproval;
     return false;
 }
-// Known tool names (single source: builtin TOOL_DEFINITIONS plus
-// extension-registered custom tools, defined below). The validator + loop
-// build "Available: ..." lists from this so the message can never drift
-// from the schema.
+// Known tool names (single source: builtin TOOL_DEFINITIONS plus the
+// intercepted update_goal definition below plus extension-registered custom
+// tools, defined below). The validator + loop build "Available: ..." lists
+// from this so the message can never drift from the schema — and the loop's
+// unknown-name gate reads this same list, so model visibility and
+// executability cannot drift apart either.
 export function toolNames() {
-    return [...TOOL_DEFINITIONS.map((t) => t.function.name), ...customToolNames()];
+    return [
+        ...TOOL_DEFINITIONS.map((t) => t.function.name),
+        UPDATE_GOAL_TOOL_DEFINITION.function.name,
+        ...customToolNames(),
+    ];
 }
-// Every definition the model sees: builtins plus extension tools. The raw
-// TOOL_DEFINITIONS export stays builtin-only (tests pin its 13 entries);
-// chat payloads must use this so custom tools are discoverable. A builtin
+// Every definition the model sees: builtins plus the intercepted update_goal
+// definition below plus extension tools. The raw TOOL_DEFINITIONS export
+// stays builtin-only (tests pin its 13 entries); chat payloads must use this
+// so update_goal and custom tools are discoverable. A builtin
 // shadowed by an extension override (ticket 06) keeps its name, schema, and
 // position, but its description carries an audit-visible override marker so
 // the shadowing is never silent.
 export function allToolDefinitions() {
+    return chatToolDefinitions(true);
+}
+// Per-POST model-visible surface: identical to allToolDefinitions, minus
+// update_goal when the turn has no live goal to report into. The model
+// repeatedly filed `complete` outside goal turns (greetings, task done-ups)
+// despite the description's WHEN NOT — an invisible tool cannot be misused,
+// and hiding it also trims every no-goal POST by one schema. Executability
+// (toolNames + runInterceptedTool) stays full by design: a hallucinated call
+// still routes to the outside-turn error instead of an unknown-name dead
+// end, and the loop's recordGoalReport backstop is untouched.
+export function chatToolDefinitions(includeUpdateGoal = true) {
     return [
         ...TOOL_DEFINITIONS.map((t) => isToolOverridden(t.function.name)
             ? {
@@ -69,6 +88,7 @@ export function allToolDefinitions() {
                 },
             }
             : t),
+        ...(includeUpdateGoal ? [UPDATE_GOAL_TOOL_DEFINITION] : []),
         ...listCustomTools().map((c) => ({
             type: "function",
             function: { name: c.name, description: c.description, parameters: c.parameters },
@@ -281,6 +301,10 @@ export function validateToolArgs(name, args) {
         }
         case "ask_question":
             return askQuestionDetail(a);
+        case "update_goal":
+            // Validator lives in goal.ts (same detail-string contract as every
+            // other arm here); the schema and executor live beside this arm above.
+            return validateUpdateGoalArgs(a);
         default:
             return null;
     }
@@ -377,39 +401,32 @@ export async function executeTool(name, args, cwd = process.cwd()) {
             return e instanceof Error ? `Error: ${e.message}` : `Error: ${String(e)}`;
         }
     }
-    // ask_question keeps its dedicated hook-missing path, but validation
-    // still comes first (validateAskQuestionArgs already uses invalidCall).
-    if (name === "ask_question") {
-        // No UI hook at this layer: the agentic loop intercepts ask_question
-        // and serves it via its askUser hook. Direct calls validate, then
-        // report the missing hook as a result string (never throw).
-        const invalid = validateAskQuestionArgs(a);
-        if (invalid)
-            return invalid;
-        return err("ask_question has no UI hook");
-    }
+    // Intercepted tools (ask_question/update_goal) resolve without an
+    // executor through the registry runner above: validation first (model
+    // mistakes never run), then the context-free result — the no-hook error
+    // for ask_question, the outside-turn error for update_goal. Direct calls
+    // never throw.
+    const intercepted = await runInterceptedTool(name, a, {});
+    if (intercepted !== null)
+        return intercepted.result;
     const detail = validateToolArgs(name, a);
     if (detail)
         return invalidCall(detail);
     return executeBuiltinTool(name, a, cwd);
 }
 // Pristine builtin execution (ticket 06: the override passthrough target).
-// Validation first, then the builtin executor — exactly the path above, so
-// pass-through behavior is byte-identical to no override. Never consults the
-// override store, so recursion is impossible by construction. A throwing
-// executor degrades to an `Error:` result string, never a crash.
+// Intercepted names resolve context-free first, then validation, then the
+// builtin executor — exactly the path above, so pass-through behavior is
+// byte-identical to no override. Never consults the override store, so
+// recursion is impossible by construction. A throwing executor degrades to
+// an `Error:` result string, never a crash.
 async function executeBuiltinTool(name, args, cwd) {
-    // ask_question keeps its dedicated hook-missing path, but validation
-    // still comes first (validateAskQuestionArgs already uses invalidCall).
-    if (name === "ask_question") {
-        // No UI hook at this layer: the agentic loop intercepts ask_question
-        // and serves it via its askUser hook. Direct calls validate, then
-        // report the missing hook as a result string (never throw).
-        const invalid = validateAskQuestionArgs(args);
-        if (invalid)
-            return invalid;
-        return err("ask_question has no UI hook");
-    }
+    // Intercepted tools have no executor: the pristine path resolves them
+    // context-free (validated, then the no-hook / outside-turn error), so an
+    // override passthrough behaves byte-identically to no override.
+    const intercepted = await runInterceptedTool(name, args, {});
+    if (intercepted !== null)
+        return intercepted.result;
     const detail = validateToolArgs(name, args);
     if (detail)
         return invalidCall(detail);
@@ -598,9 +615,10 @@ export const TOOL_DEFINITIONS = [
         function: {
             name: "read",
             description: "Read a UTF-8 text file with 1-based line numbers (`<n>: <text>` per line) or list a directory (plain entry names, no line numbers). " +
+                "PNG, JPEG, GIF, and WebP images (up to 8 MiB) are read as vision input — the result says so and the image reaches the model automatically; describe what you see. " +
                 "WHEN to use: inspecting source before editing — read first, then edit with an exact oldString copied from the numbered output; " +
                 "paging large files with the offset/limit line window (output truncates with a follow pointer). " +
-                "WHEN NOT to use: binaries or huge dumps — narrow with grep/glob first. " +
+                "WHEN NOT to use: other binaries (PDF, audio, video) are rejected — convert to PNG/text first (e.g. pdftoppm, pdftotext); huge dumps — narrow with grep/glob first. " +
                 "Paths may be relative or absolute, anywhere on the computer.",
             parameters: {
                 type: "object",
@@ -640,7 +658,7 @@ export const TOOL_DEFINITIONS = [
             description: "Edit a file with exact-match string replacement. " +
                 "WHEN to use: small targeted changes to an already-read file — read first, then pass the exact oldString copied from the numbered output " +
                 "(line numbers are display-only, never file content; never invent oldString from memory). " +
-                "WHEN NOT to use: don't create or rewrite whole files (use write). " +
+                "WHEN NOT to use: don't create or rewrite whole files (use write). Files over 1MB are refused outright — use bash for targeted changes to huge files. " +
                 "oldString must match exactly once unless replaceAll is true. Enforces a stale-read guard: re-read after any external change. " +
                 "Edits report the occurrence count. Asks for approval in normal mode.",
             parameters: {
@@ -660,11 +678,13 @@ export const TOOL_DEFINITIONS = [
         type: "function",
         function: {
             name: "grep",
-            description: "Search file contents under dir (default '.') for lines matching a JS regex (JS RegExp engine, ripgrep-style intent). " +
-                "WHEN to use: finding usages without reading every file — scope with outputMode files_with_matches first, then read; never shell out to a system grep. " +
+            description: "Search file contents under dir (default '.') for lines matching a JS regex. " +
+                "WHEN to use: finding usages — scope with outputMode files_with_matches first, then read. " +
                 "WHEN NOT to use: don't list files by name (use glob); don't read whole files (use read). " +
-                "include filters by glob. content returns 'file:line: text' (100 matches); files_with_matches lists paths newest-first; " +
-                "count adds per-file totals. Long lines trim; binaries skipped; node_modules/.git never searched.",
+                "Case-sensitive; (?i) prefix = case-insensitive. dir takes a directory or a file. " +
+                "include is a glob with {a,b} (e.g. '*.{ts,tsx}'); prefer one scoped call. " +
+                "content returns 'file:line: text' (100); files_with_matches lists paths newest-first; " +
+                "count adds totals. Binaries skipped; node_modules/.git never searched.",
             parameters: {
                 type: "object",
                 properties: {
@@ -686,10 +706,10 @@ export const TOOL_DEFINITIONS = [
         type: "function",
         function: {
             name: "glob",
-            description: "Find files by glob pattern (*, ?, **) under dir (default '.'). " +
-                "WHEN to use: locating files by name before reading. " +
+            description: "Find files by glob (*, ?, **, {a,b}) under dir (default '.'; a file tests just it). " +
+                "WHEN to use: locating files by name — one pattern like '**/*goal*' answers most. " +
                 "WHEN NOT to use: don't search contents (use grep); don't read bodies (use read). " +
-                "A slash-less pattern matches basenames at any depth. Paths newest-first (capped at 200). " +
+                "Slash-less patterns match basenames at any depth. Paths newest-first (capped at 200). " +
                 "node_modules/.git skipped.",
             parameters: {
                 type: "object",
@@ -921,6 +941,124 @@ export const TOOL_DEFINITIONS = [
         },
     },
 ];
+// Intercepted tools (ticket 06): loop-resolved, executor-free registry
+// entries — schema, validator, and executor in one place. ask_question's
+// schema stays in TOOL_DEFINITIONS above (its 13-entry pin holds) with its
+// validator (validateToolArgs/validateAskQuestionArgs) and executor
+// (runInterceptedTool) beside it in this module; update_goal's schema lives
+// here (NOT in TOOL_DEFINITIONS, so the 13-entry pin and the
+// scheduler-effects completeness test stay green) with its validator
+// delegating to goal.ts (same detail-string contract — kept home there per
+// the ticket brief) and its executor beside it below. The loop dispatches
+// both through runInterceptedTool via isInterceptedTool — never by name —
+// so the roster below is the single source for model visibility
+// (allToolDefinitions) and executability (toolNames + this runner).
+export const UPDATE_GOAL_TOOL_DEFINITION = {
+    type: "function",
+    function: {
+        name: "update_goal",
+        description: "Report this goal turn's outcome (goal-scoped: only available during an active goal turn). " +
+            "WHEN to use: at the end of each goal turn — status \"continue\" with the next action, " +
+            "or \"complete\"/\"blocked\" with a reason. " +
+            "A \"complete\" lands only on genuinely finished work: verified checks and resolved todos. " +
+            "Checks you could not run go in \"unverified\" (recorded openly in the closing summary, never a gate). " +
+            "WHEN NOT to use: never outside a goal turn (it records nothing there); " +
+            "never for greetings, small talk, or non-goal answers; " +
+            "a turn with no report continues the goal.",
+        parameters: {
+            type: "object",
+            properties: {
+                status: {
+                    type: "string",
+                    enum: ["continue", "complete", "blocked"],
+                    description: "Turn outcome: \"continue\" (keep working), \"complete\" (goal done), \"blocked\" (cannot proceed).",
+                },
+                next: {
+                    type: "string",
+                    description: "Next action (only with status \"continue\"; omit otherwise).",
+                },
+                reason: {
+                    type: "string",
+                    description: "Why the goal is done or stuck (required with \"complete\"/\"blocked\"; omit otherwise).",
+                },
+                unverified: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Checks that could not be run (only with status \"complete\"; omit otherwise). " +
+                        "Recorded openly in the closing summary; at most 10 non-empty items of 200 characters each.",
+                },
+            },
+            required: ["status"],
+            additionalProperties: false,
+        },
+    },
+};
+// Roster query for the loop's dispatch stage: true exactly for the tools
+// runInterceptedTool resolves (never by name in the caller).
+export function isInterceptedTool(name) {
+    return name === "ask_question" || name === UPDATE_GOAL_TOOL_DEFINITION.function.name;
+}
+// Resolve one intercepted call: validated, approval-free, executor-free.
+// Returns null for non-intercepted names (the caller falls through to the
+// executor path). Cancel-like askUser failures rethrow raw — the pipeline
+// maps them to LoopCancelledError (it cannot be named here: the pipeline
+// imports this module, so that edge would cycle); everything else is an
+// `Error:` result string, never a throw.
+export async function runInterceptedTool(name, parsed, ctx = {}) {
+    switch (name) {
+        case "ask_question":
+            return { result: await runAskQuestionTool(parsed, ctx), decision: "ask-question" };
+        case "update_goal":
+            return { result: runUpdateGoalTool(parsed, ctx), decision: "goal-report" };
+        default:
+            return null;
+    }
+}
+// Local cancel classification (mirrors agent/tool-pipeline's isCancelError,
+// which cannot be imported here for the cycle reason above).
+function isInterceptCancel(e, signal) {
+    if (signal?.aborted)
+        return true;
+    if (e instanceof Error && (e.name === "LoopCancelledError" || e.name === "AbortError"))
+        return true;
+    if (typeof DOMException !== "undefined" && e instanceof DOMException && e.name === "AbortError") {
+        return true;
+    }
+    return false;
+}
+async function runAskQuestionTool(parsed, ctx) {
+    const invalid = validateAskQuestionArgs(parsed);
+    if (invalid)
+        return invalid;
+    if (!ctx.askUser)
+        return "Error: ask_question has no UI hook";
+    const q = parsed;
+    const allowCustom = q.allowCustom === true;
+    try {
+        const answer = await ctx.askUser(q.question, q.options, allowCustom);
+        if (typeof answer === "string" && answer.startsWith("Error:"))
+            return answer;
+        return JSON.stringify({ answer });
+    }
+    catch (e) {
+        // A cancelled turn rethrows raw (the pipeline maps it); an Esc-style
+        // cancel message is the user-cancellable result, never a throw.
+        if (isInterceptCancel(e, ctx.signal))
+            throw e;
+        const msg = e instanceof Error ? e.message : String(e);
+        if (/cancel/i.test(msg))
+            return "Error: question cancelled by user";
+        return `Error: ${msg}`;
+    }
+}
+function runUpdateGoalTool(parsed, ctx) {
+    const detail = validateUpdateGoalArgs(parsed);
+    if (detail)
+        return invalidCall(detail);
+    if (!ctx.onUpdateGoal)
+        return goalReportOutsideError();
+    return ctx.onUpdateGoal(parsed);
+}
 // One-line summaries for the /tools command (single source of truth for
 // the tool list shown in the TUI).
 export const TOOL_ONE_LINERS = {
@@ -945,7 +1083,8 @@ export const TOOL_ONE_LINERS = {
 // shadow. Returns an unregister function for hot-reload style removal.
 export function registerExtensionTool(def) {
     validateExtensionToolDef(def);
-    if (TOOL_DEFINITIONS.some((t) => t.function.name === def.name)) {
+    if (TOOL_DEFINITIONS.some((t) => t.function.name === def.name) ||
+        def.name === UPDATE_GOAL_TOOL_DEFINITION.function.name) {
         throw new Error(`extension tool "${def.name}" collides with a builtin tool`);
     }
     const unregister = registerCustomTool(def);

package/dist/tools/ripgrep.js

@@ -115,10 +115,11 @@ function isRegexError(stderr) {
 // (caller renders the mode's empty shape); anything else is a fallback
 // signal — with regex-parse errors being the EXPECTED fallback trigger
 // (lookahead and friends are valid JS, invalid Rust).
-async function runRgSearch(absDir, baseArgs, pattern) {
+async function runRgSearch(absDir, baseArgs, pattern, caseInsensitive = false) {
     let res;
     try {
-        res = await runRg(absDir, [...baseArgs, "-e", pattern, "--", "."]);
+        const flagArgs = caseInsensitive ? ["-i", ...baseArgs] : baseArgs;
+        res = await runRg(absDir, [...flagArgs, "-e", pattern, "--", "."]);
     }
     catch {
         return { kind: "fallback" };
@@ -173,8 +174,8 @@ function parseJsonEvents(stdout) {
 // order. Hits carry raw line text; the caller applies the shared 200-char
 // trim + 100-hit cap + note (same code as the walker path would — see
 // grepTool; this module only supplies ordered raw material).
-export async function rgContentHits(absDir, cwd, pattern, allowed) {
-    const run = await runRgSearch(absDir, [...BASE_ARGS, "--json", "--max-count", String(RG_CONTENT_MAX_COUNT)], pattern);
+export async function rgContentHits(absDir, cwd, pattern, allowed, caseInsensitive = false) {
+    const run = await runRgSearch(absDir, [...BASE_ARGS, "--json", "--max-count", String(RG_CONTENT_MAX_COUNT)], pattern, caseInsensitive);
     if (run.kind !== "ok")
         return run.kind === "empty" ? { counts: [], hits: [], cappedFile: false } : null;
     const perFile = new Map();
@@ -226,8 +227,8 @@ export async function rgContentHits(absDir, cwd, pattern, allowed) {
 // `rg --count` (ripgrep --count semantics already match the walker's).
 // files_with_matches derives its file set from these counts, so one spawn
 // serves both modes. Caller applies totals/caps/recency.
-export async function rgFileCounts(absDir, cwd, pattern, allowed) {
-    const run = await runRgSearch(absDir, [...BASE_ARGS, "--count"], pattern);
+export async function rgFileCounts(absDir, cwd, pattern, allowed, caseInsensitive = false) {
+    const run = await runRgSearch(absDir, [...BASE_ARGS, "--count"], pattern, caseInsensitive);
     if (run.kind !== "ok")
         return run.kind === "empty" ? { counts: [] } : null;
     const counts = [];

package/dist/tools/search.js

@@ -5,9 +5,68 @@ import * as path from "node:path";
 import { listFiles } from "./dir-cache.js";
 import { appendOverflow } from "./overflow.js";
 import { noteRgFallback, rgAvailable, rgContentHits, rgFileCounts, rgMinFiles, } from "./ripgrep.js";
-import { err, GLOB_MATCH_CAP, GREP_MATCH_CAP, invalidCall, READ_CHAR_CAP, resolveSandbox, truncateHead } from "./shared.js";
-// Minimal glob matcher: supports **, **/, *, ?. Used for grep `include`
-// and the glob tool. Patterns without a slash match the basename.
+import { err, GLOB_MATCH_CAP, GREP_MATCH_CAP, invalidCall, READ_CHAR_CAP, READ_FILE_MAX_BYTES, resolveSandbox, truncateHead } from "./shared.js";
+// Minimal glob matcher: supports **, **/, *, ?, and {a,b,c} brace
+// alternation (single- or multi-level, e.g. "*.{ts,tsx}" or
+// "src/**/*.{test,spec}.ts"). Patterns without a slash match the basename.
+function expandBraces(pattern) {
+    // Cap: a pathological "{a,b}x{a,b}x..." chain explodes combinatorially;
+    // past the cap the raw pattern stands (legacy literal-brace behavior).
+    const MAX_EXPANSIONS = 128;
+    const out = expandBracesInner(pattern);
+    return out.length > MAX_EXPANSIONS ? [pattern] : out;
+}
+function expandBracesInner(pattern) {
+    const open = pattern.indexOf("{");
+    if (open < 0)
+        return [pattern];
+    // Find the matching close brace, accounting for nesting.
+    let depth = 0;
+    let close = -1;
+    for (let i = open; i < pattern.length; i++) {
+        if (pattern[i] === "{")
+            depth += 1;
+        else if (pattern[i] === "}") {
+            depth -= 1;
+            if (depth === 0) {
+                close = i;
+                break;
+            }
+        }
+    }
+    if (close < 0)
+        return [pattern]; // unbalanced — literal
+    const prefix = pattern.slice(0, open);
+    const suffix = pattern.slice(close + 1);
+    const inner = pattern.slice(open + 1, close);
+    // Split on top-level commas only (nested braces stay intact per part).
+    const parts = [];
+    let partDepth = 0;
+    let current = "";
+    for (const ch of inner) {
+        if (ch === "{")
+            partDepth += 1;
+        else if (ch === "}")
+            partDepth -= 1;
+        if (ch === "," && partDepth === 0) {
+            parts.push(current);
+            current = "";
+        }
+        else {
+            current += ch;
+        }
+    }
+    parts.push(current);
+    if (parts.length < 2)
+        return [pattern]; // no alternation — literal
+    const out = [];
+    for (const part of parts) {
+        for (const expanded of expandBracesInner(`${prefix}${part}${suffix}`)) {
+            out.push(expanded);
+        }
+    }
+    return out;
+}
 function globToRegExp(glob) {
     let re = "";
     let i = 0;
@@ -43,11 +102,35 @@ function globToRegExp(glob) {
 }
 function matchesGlob(pattern, relPosix) {
     const norm = pattern.replace(/\\/g, "/");
-    if (!norm.includes("/")) {
-        const base = relPosix.slice(relPosix.lastIndexOf("/") + 1);
-        return globToRegExp(norm).test(base);
+    for (const alt of expandBraces(norm)) {
+        if (!alt.includes("/")) {
+            const base = relPosix.slice(relPosix.lastIndexOf("/") + 1);
+            if (globToRegExp(alt).test(base))
+                return true;
+        }
+        else {
+            // Full-rel match first (exact glob semantics); then a trailing-suffix
+            // fallback so a repo-rooted shorthand like "tools/registry.ts" still
+            // hits "src/tools/registry.ts" instead of silently matching nothing
+            // (the Temp-session c21 trap: correct file, correct pattern shape,
+            // zero results, one wasted round plus a manual fallback).
+            if (globToRegExp(alt).test(relPosix))
+                return true;
+            if (globToRegExp(`**/${alt}`).test(relPosix))
+                return true;
+        }
     }
-    return globToRegExp(norm).test(relPosix);
+    return false;
+}
+// Grep pattern pre-parse: a leading "(?i)" prefix selects case-insensitive
+// matching (Python-trained models reach for it; JS RegExp has no inline
+// flags, so `new RegExp("(?i)goal")` throws "invalid regex"). The prefix is
+// stripped and re-applied as the `i` flag for the walker and as `-i` for
+// ripgrep — one documented spelling, both engines agree.
+function parseGrepPattern(raw) {
+    if (raw.startsWith("(?i)"))
+        return { source: raw.slice(4), caseInsensitive: true };
+    return { source: raw, caseInsensitive: false };
 }
 export const GREP_OUTPUT_MODES = new Set([
     "content",
@@ -85,9 +168,9 @@ export function formatGrepHit(rel, lineNo, line) {
 // shape as the walker scan below (or null = run the walker). Content hits
 // arrive merged in (file alpha, line) order; the 100-hit cap + note apply
 // exactly like the walker path (including its take-100-blindly quirk).
-async function scanWithRipgrep(absDir, cwd, pattern, mode, allowed) {
+async function scanWithRipgrep(absDir, cwd, pattern, mode, allowed, caseInsensitive = false) {
     if (mode === "content") {
-        const r = await rgContentHits(absDir, cwd, pattern, allowed);
+        const r = await rgContentHits(absDir, cwd, pattern, allowed, caseInsensitive);
         if (r === null)
             return null;
         if (r.cappedFile)
@@ -95,7 +178,7 @@ async function scanWithRipgrep(absDir, cwd, pattern, mode, allowed) {
         const hits = r.hits.slice(0, GREP_MATCH_CAP).map((h) => formatGrepHit(h.rel, h.line, h.text));
         return { counts: r.counts, hits, hitsCapped: r.hits.length >= GREP_MATCH_CAP };
     }
-    const r = await rgFileCounts(absDir, cwd, pattern, allowed);
+    const r = await rgFileCounts(absDir, cwd, pattern, allowed, caseInsensitive);
     if (r === null)
         return null;
     return { counts: r.counts, hits: [], hitsCapped: false };
@@ -128,7 +211,20 @@ async function scanWithWalker(cwd, re, pattern, sorted, include, mode) {
         if (include && !matchesGlob(include, rel))
             return null;
         try {
-            const text = await fsp.readFile(path.resolve(cwd, rel), "utf8");
+            // OOM guard: the walker reads every file fully and concurrently —
+            // one GB input (bundle, pack, media) would OOM the heap. Oversize
+            // files skip exactly like binaries (the ripgrep path bounds itself
+            // via --max-count instead).
+            const full = path.resolve(cwd, rel);
+            try {
+                const st = await fsp.stat(full);
+                if (st.isFile() && st.size > READ_FILE_MAX_BYTES)
+                    return null;
+            }
+            catch {
+                // stat failure falls through to the read below (same as before)
+            }
+            const text = await fsp.readFile(full, "utf8");
             if (text.includes("\0"))
                 return null; // binary — skip
             return { rel, text };
@@ -172,6 +268,51 @@ async function scanWithWalker(cwd, re, pattern, sorted, include, mode) {
     }
     return { counts, hits, hitsCapped };
 }
+// Single-file grep (file-path tolerance for `dir`): same match semantics as
+// the walker over a one-entry set, same output shapes per mode. Skips
+// oversize/binary files exactly like the walker (→ "No matches.").
+async function grepSingleFile(cwd, re, pattern, rel, abs, include, mode) {
+    if (include && !matchesGlob(include, rel))
+        return "No matches.";
+    try {
+        const st = await fsp.stat(abs);
+        if (st.isFile() && st.size > READ_FILE_MAX_BYTES)
+            return "No matches.";
+        const text = await fsp.readFile(abs, "utf8");
+        if (text.includes("\0"))
+            return "No matches.";
+        const lines = text.split("\n");
+        const hits = [];
+        let n = 0;
+        for (let i = 0; i < lines.length; i++) {
+            let matched;
+            try {
+                matched = re.test(lines[i]);
+            }
+            catch {
+                return err(`regex failed on input: ${pattern}`);
+            }
+            re.lastIndex = 0;
+            if (!matched)
+                continue;
+            n += 1;
+            if (mode === "content" && hits.length < GREP_MATCH_CAP) {
+                hits.push(formatGrepHit(rel, i + 1, lines[i]));
+            }
+        }
+        if (n === 0)
+            return "No matches.";
+        if (mode === "files_with_matches")
+            return capSearchOutput(`Found 1 file(s)\n${rel}`, "grep results");
+        if (mode === "count") {
+            return capSearchOutput(`${rel}:${n}\nFound ${n} total match(es) across 1 file(s).`, "grep results");
+        }
+        return capSearchOutput(hits.join("\n"), "grep results");
+    }
+    catch {
+        return "No matches.";
+    }
+}
 // Line-regex search under dir (default "."). `include` is a glob like
 // "*.ts". `outputMode` selects the shape (Claude-Code-style):
 // - "content" (default): "file:line: text" lines, capped at 100 matches.
@@ -183,12 +324,13 @@ export async function grepTool(args, cwd = process.cwd()) {
     try {
         if (typeof args?.pattern !== "string")
             return err("pattern must be a string");
+        const parsed = parseGrepPattern(args.pattern);
         let re;
         try {
-            re = new RegExp(args.pattern);
+            re = new RegExp(parsed.source, parsed.caseInsensitive ? "i" : "");
         }
         catch {
-            return err(`invalid regex: ${args.pattern}`);
+            return err(`invalid regex: ${args.pattern} (JS RegExp syntax; prefix with (?i) for case-insensitive)`);
         }
         const mode = args?.outputMode ?? "content";
         if (!GREP_OUTPUT_MODES.has(mode)) {
@@ -205,10 +347,17 @@ export async function grepTool(args, cwd = process.cwd()) {
         catch {
             return err(`no such directory: ${dir}`);
         }
+        const include = typeof args.include === "string" && args.include.length > 0 ? args.include : null;
+        // File-path tolerance: `dir` pointing at a file searches just that file
+        // (models habitually pass "src/foo.ts" as dir). Same output shapes as
+        // the directory path; ripgrep is skipped (cwd-anchored by construction).
+        if (st.isFile()) {
+            const rel = path.relative(cwd, r.abs).split(path.sep).join("/");
+            return grepSingleFile(cwd, re, parsed.source, rel, r.abs, include, mode);
+        }
         if (!st.isDirectory())
-            return err(`not a directory: ${dir}`);
+            return err(`not a directory: ${dir} (pass a directory in dir, or read the file directly)`);
         const files = await listFiles(r.abs, cwd);
-        const include = typeof args.include === "string" && args.include.length > 0 ? args.include : null;
         const sorted = files.sort();
         // Allowed set shared by both scan paths (include filtering is identical
         // either way, so ripgrep coverage matches the walker exactly).
@@ -220,7 +369,7 @@ export async function grepTool(args, cwd = process.cwd()) {
         let hits;
         let hitsCapped;
         if (rgAvailable() && sorted.length >= rgMinFiles()) {
-            const fast = await scanWithRipgrep(r.abs, cwd, args.pattern, mode, allowed);
+            const fast = await scanWithRipgrep(r.abs, cwd, parsed.source, mode, allowed, parsed.caseInsensitive);
             if (fast !== null) {
                 ({ counts, hits, hitsCapped } = fast);
             }
@@ -285,8 +434,14 @@ export async function globTool(args, cwd = process.cwd()) {
         catch {
             return err(`no such directory: ${dir}`);
         }
+        // File-path tolerance: `dir` pointing at a file tests just that file
+        // against the glob (models habitually pass "src/foo.ts" as dir).
+        if (st.isFile()) {
+            const rel = path.relative(cwd, r.abs).split(path.sep).join("/");
+            return matchesGlob(args.pattern, rel) ? capSearchOutput(rel, "glob results") : "No matches.";
+        }
         if (!st.isDirectory())
-            return err(`not a directory: ${dir}`);
+            return err(`not a directory: ${dir} (pass a directory in dir, or read the file directly)`);
         const files = await listFiles(r.abs, cwd);
         const matched = files.filter((rel) => matchesGlob(args.pattern, rel));
         const withTime = await Promise.all(matched.map(async (rel) => ({ rel, t: await mtimeMs(path.resolve(cwd, rel)) })));

package/dist/tools/shared.js

@@ -3,6 +3,12 @@
 import * as path from "node:path";
 export const READ_CHAR_CAP = 64 * 1024;
 export const OUTPUT_CAP = 8 * 1024;
+// Full-read byte guard: no tool may materialize a whole file past this size.
+// A GB file becomes ~2x bytes as UTF-16 plus split/join copies — enough to
+// OOM the heap in a single call (observed kill: long session + one huge
+// read). Matches the diff engine + approval preview 1MB precedent, so the
+// model gets one consistent "over 1MB" story everywhere.
+export const READ_FILE_MAX_BYTES = 1_000_000;
 export const GREP_MATCH_CAP = 100;
 export const GLOB_MATCH_CAP = 200;
 export const SKIP_DIRS = new Set(["node_modules", ".git"]);