@denizokcu/haze 0.0.2 → 0.1.0

package/dist/llm/hazeTools.js

@@ -40,6 +40,60 @@ function truncate(text, maxChars = MAX_OUTPUT_CHARS) {
 function numberLines(lines, startLine) {
     return lines.map((line, index) => `${String(startLine + index).padStart(4, ' ')} | ${line}`).join('\n');
 }
+function stripLineNumberPrefixes(text) {
+    return text.replace(/^\s*\d+\s+\| ?/gm, '');
+}
+function lineStartOffsets(text) {
+    const offsets = [0];
+    for (let index = 0; index < text.length; index++) {
+        if (text[index] === '\n')
+            offsets.push(index + 1);
+    }
+    return offsets;
+}
+function findLineTrimmedRange(original, oldText) {
+    const wantedLines = oldText.replace(/\r\n/g, '\n').split('\n').map(line => line.trimEnd());
+    if (wantedLines.at(-1) === '')
+        wantedLines.pop();
+    if (wantedLines.length === 0)
+        return undefined;
+    const originalLines = original.replace(/\r\n/g, '\n').split('\n');
+    const hasTrailingNewline = original.endsWith('\n');
+    if (hasTrailingNewline)
+        originalLines.pop();
+    const offsets = lineStartOffsets(original);
+    const matches = [];
+    for (let lineIndex = 0; lineIndex <= originalLines.length - wantedLines.length; lineIndex++) {
+        const window = originalLines.slice(lineIndex, lineIndex + wantedLines.length).map(line => line.trimEnd());
+        if (window.every((line, index) => line === wantedLines[index])) {
+            const start = offsets[lineIndex] ?? 0;
+            const endLineIndex = lineIndex + wantedLines.length;
+            const end = endLineIndex < offsets.length ? (offsets[endLineIndex] ?? original.length) : original.length;
+            matches.push({ start, end });
+        }
+    }
+    if (matches.length !== 1)
+        return undefined;
+    return matches[0];
+}
+function findEditRange(original, oldText) {
+    const candidates = [oldText, stripLineNumberPrefixes(oldText)].filter((candidate, index, all) => candidate.length > 0 && all.indexOf(candidate) === index);
+    for (const candidate of candidates) {
+        const first = original.indexOf(candidate);
+        if (first !== -1) {
+            const second = original.indexOf(candidate, first + candidate.length);
+            if (second !== -1)
+                return { kind: 'multiple' };
+            return { kind: 'found', start: first, end: first + candidate.length, approximate: candidate !== oldText };
+        }
+    }
+    for (const candidate of candidates) {
+        const range = findLineTrimmedRange(original, candidate);
+        if (range)
+            return { kind: 'found', ...range, approximate: true };
+    }
+    return { kind: 'missing' };
+}
 function toolCallKey(toolName, input) {
     return `${toolName}:${JSON.stringify(input)}`;
 }
@@ -52,13 +106,46 @@ function isMutatingTool(toolName) {
     return ['editFile', 'replaceLines', 'writeFile'].includes(toolName);
 }
 function isReadOnlyFileTool(toolName) {
-    return ['listFiles', 'readFile'].includes(toolName);
+    return ['listFiles', 'readFile', 'grep'].includes(toolName);
 }
 function inputPath(input) {
     return typeof input === 'object' && input != null && 'path' in input && typeof input.path === 'string'
         ? input.path
         : undefined;
 }
+function isStructuredFailure(value) {
+    return typeof value === 'object' && value != null && 'ok' in value && value.ok === false;
+}
+function structuredToolFailure(toolName, error, suggestedNextStep, pathForError) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { ok: false, toolName, path: pathForError, error: message, recoverable: true, suggestedNextStep };
+}
+const INLINE_DIFF_LINE_LIMIT = 20;
+function splitDiffLines(text) {
+    const lines = text.split(/\r?\n/);
+    if (text.endsWith('\n') || text.endsWith('\r\n'))
+        lines.pop();
+    return lines;
+}
+function lineNumberAtOffset(text, offset) {
+    let line = 1;
+    for (let index = 0; index < offset; index++) {
+        if (text.charCodeAt(index) === 10)
+            line += 1;
+    }
+    return line;
+}
+function replacementDiff(oldText, newText, oldStartLine, newStartLine, context) {
+    const oldLines = splitDiffLines(oldText);
+    const newLines = splitDiffLines(newText);
+    const diff = [];
+    if (context?.before)
+        diff.push({ type: 'context', ...context.before });
+    diff.push(...oldLines.map((text, index) => ({ type: 'remove', oldLine: oldStartLine + index, text })), ...newLines.map((text, index) => ({ type: 'add', newLine: newStartLine + index, text })));
+    if (context?.after)
+        diff.push({ type: 'context', ...context.after });
+    return { diff, addedLines: newLines.length, removedLines: oldLines.length };
+}
 async function runDedupedTool(toolName, input, context, execute) {
     const ctx = hazeContext(context);
     if (!ctx)
@@ -67,9 +154,18 @@ async function runDedupedTool(toolName, input, context, execute) {
     ctx.completedToolCalls ??= new Map();
     ctx.failedMutationPaths ??= new Set();
     ctx.pathsReadAfterFailedMutation ??= new Set();
+    ctx.inFlightMutationPaths ??= new Set();
     ctx.mutationEpoch ??= 0;
     const key = toolCallKey(toolName, input);
     const pathForInput = inputPath(input);
+    if (isMutatingTool(toolName) && pathForInput && ctx.inFlightMutationPaths.has(pathForInput)) {
+        return {
+            ok: true,
+            duplicateSkipped: true,
+            toolName,
+            reason: `Skipped concurrent mutation for ${pathForInput}. Read the file again, then make one editFile call with all non-overlapping replacements or one replaceLines call based on the latest line numbers.`,
+        };
+    }
     if (isMutatingTool(toolName) && pathForInput && ctx.failedMutationPaths.has(pathForInput) && !ctx.pathsReadAfterFailedMutation.has(pathForInput)) {
         throw new Error(`Read ${pathForInput} before attempting another edit after the previous edit failure.`);
     }
@@ -93,10 +189,19 @@ async function runDedupedTool(toolName, input, context, execute) {
             reason: 'Skipped duplicate in-flight tool call with identical input.',
         };
     }
+    if (isMutatingTool(toolName) && pathForInput)
+        ctx.inFlightMutationPaths.add(pathForInput);
     const promise = execute();
     ctx.inFlightToolCalls.set(key, promise);
     try {
         const result = await promise;
+        if (isStructuredFailure(result)) {
+            if (isMutatingTool(toolName) && pathForInput) {
+                ctx.failedMutationPaths.add(pathForInput);
+                ctx.pathsReadAfterFailedMutation.delete(pathForInput);
+            }
+            return result;
+        }
         if (toolName === 'readFile' && pathForInput)
             ctx.pathsReadAfterFailedMutation.add(pathForInput);
         if (isMutatingTool(toolName)) {
@@ -118,6 +223,8 @@ async function runDedupedTool(toolName, input, context, execute) {
     }
     finally {
         ctx.inFlightToolCalls.delete(key);
+        if (isMutatingTool(toolName) && pathForInput)
+            ctx.inFlightMutationPaths?.delete(pathForInput);
     }
 }
 function looksLikeShellFileMutation(command) {
@@ -136,29 +243,34 @@ export const hazeTools = {
             includeIgnored: z.boolean().default(false).describe('Include files ignored by .gitignore. Use only when explicitly needed.'),
         }),
         execute: async ({ path: dirPath, recursive, maxEntries, cursor, includeIgnored }, context) => runDedupedTool('listFiles', { path: dirPath, recursive, maxEntries, cursor, includeIgnored }, context, async () => {
-            const absolutePath = resolveWorkspacePath(dirPath);
-            await assertNotIgnored(absolutePath, dirPath, includeIgnored);
-            const entries = [];
-            let ignoredSkipped = 0;
-            const walked = await walkDir(absolutePath, { recursive, maxEntries: maxEntries + 1, cursor, filter: async (entry) => {
-                    if (!includeIgnored && await isGitIgnored(entry.absolutePath)) {
-                        ignoredSkipped++;
-                        return false;
+            try {
+                const absolutePath = resolveWorkspacePath(dirPath);
+                await assertNotIgnored(absolutePath, dirPath, includeIgnored);
+                const entries = [];
+                let ignoredSkipped = 0;
+                const walked = await walkDir(absolutePath, { recursive, maxEntries: maxEntries + 1, cursor, filter: async (entry) => {
+                        if (!includeIgnored && await isGitIgnored(entry.absolutePath)) {
+                            ignoredSkipped++;
+                            return false;
+                        }
+                        return true;
+                    } });
+                const page = walked.slice(0, maxEntries);
+                const hasMore = walked.length > maxEntries;
+                for (const entry of page) {
+                    if (entry.isDirectory) {
+                        entries.push({ path: entry.path, type: 'directory' });
+                    }
+                    else if (entry.isFile) {
+                        const stat = await fs.stat(entry.absolutePath);
+                        entries.push({ path: entry.path, type: 'file', size: stat.size });
                     }
-                    return true;
-                } });
-            const page = walked.slice(0, maxEntries);
-            const hasMore = walked.length > maxEntries;
-            for (const entry of page) {
-                if (entry.isDirectory) {
-                    entries.push({ path: entry.path, type: 'directory' });
-                }
-                else if (entry.isFile) {
-                    const stat = await fs.stat(entry.absolutePath);
-                    entries.push({ path: entry.path, type: 'file', size: stat.size });
                 }
+                return { path: dirPath, recursive, includeIgnored, cursor, nextCursor: hasMore ? page.at(-1)?.path : undefined, ignoredSkipped, entries, truncated: hasMore };
+            }
+            catch (error) {
+                return structuredToolFailure('listFiles', error, 'Check that the directory exists and is not ignored, or retry with a narrower path.', dirPath);
             }
-            return { path: dirPath, recursive, includeIgnored, cursor, nextCursor: hasMore ? page.at(-1)?.path : undefined, ignoredSkipped, entries, truncated: hasMore };
         }),
     }),
     readFile: tool({
@@ -170,26 +282,92 @@ export const hazeTools = {
             allowIgnored: z.boolean().default(false).describe('Read the file even if it is ignored by .gitignore. Use only when explicitly needed.'),
         }),
         execute: async ({ path: filePath, offset, limit, allowIgnored }, context) => runDedupedTool('readFile', { path: filePath, offset, limit, allowIgnored }, context, async () => {
-            const absolutePath = resolveWorkspacePath(filePath);
-            await assertNotIgnored(absolutePath, filePath, allowIgnored);
-            const content = await fs.readFile(absolutePath, 'utf8');
-            const lines = content.split(/\r?\n/);
-            const start = offset == null ? 0 : offset - 1;
-            const end = limit == null ? lines.length : start + limit;
-            const selectedLines = lines.slice(start, end);
-            const selected = selectedLines.join('\n');
-            return {
-                path: filePath,
-                startLine: start + 1,
-                endLine: Math.min(end, lines.length),
-                totalLines: lines.length,
-                lineNumberedText: numberLines(selectedLines, start + 1),
-                ...truncate(selected),
-            };
+            try {
+                const absolutePath = resolveWorkspacePath(filePath);
+                await assertNotIgnored(absolutePath, filePath, allowIgnored);
+                const content = await fs.readFile(absolutePath, 'utf8');
+                const lines = content.split(/\r?\n/);
+                const start = offset == null ? 0 : offset - 1;
+                const end = limit == null ? lines.length : start + limit;
+                const selectedLines = lines.slice(start, end);
+                const selected = selectedLines.join('\n');
+                return {
+                    path: filePath,
+                    startLine: start + 1,
+                    endLine: Math.min(end, lines.length),
+                    totalLines: lines.length,
+                    lineNumberedText: numberLines(selectedLines, start + 1),
+                    ...truncate(selected),
+                };
+            }
+            catch (error) {
+                return structuredToolFailure('readFile', error, 'Check the path with listFiles, or set allowIgnored=true only if the user explicitly asked to inspect an ignored file.', filePath);
+            }
+        }),
+    }),
+    grep: tool({
+        description: 'Search file contents with a regex pattern using ripgrep. Use this to find symbol definitions, usages, string literals, import paths, and code patterns across the workspace. Much faster and more targeted than reading files one by one with readFile. Respects .gitignore by default.',
+        inputSchema: z.object({
+            pattern: z.string().min(1).describe('Regex pattern to search for (PCRE-compatible). Examples: "function handleClick", "import.*from.*react", "class UserService", "TODO|FIXME"'),
+            path: z.string().default('.').describe('Directory or file path to search in, relative to the workspace. Narrow this to focus results.'),
+            glob: z.string().optional().describe('File glob filter. Examples: "*.ts", "*.{js,jsx}", "src/**/*.py". Narrows search to matching files.'),
+            contextLines: z.number().int().nonnegative().max(5).default(2).describe('Number of context lines before and after each match (0-5). Use 0 for compact output, 2-3 for understanding surrounding code.'),
+            maxMatches: z.number().int().positive().max(200).default(50).describe('Maximum number of matches to return. Increase for broad searches, decrease for focused lookups.'),
+            caseInsensitive: z.boolean().default(false).describe('Case-insensitive matching. Useful for symbol names that may vary in casing.'),
+        }),
+        execute: async ({ pattern, path: searchPath, glob, contextLines, maxMatches, caseInsensitive }, context) => runDedupedTool('grep', { pattern, path: searchPath, glob, contextLines, maxMatches, caseInsensitive }, context, async () => {
+            try {
+                const absolutePath = resolveWorkspacePath(searchPath);
+                const args = [
+                    '--no-heading', '--line-number', '--color=never',
+                    '--max-count', String(maxMatches),
+                    '--context', String(contextLines),
+                ];
+                if (caseInsensitive)
+                    args.push('--ignore-case');
+                if (glob)
+                    args.push('--glob', glob);
+                args.push('--', pattern, absolutePath);
+                let stdout = '';
+                try {
+                    const result = await execFile('rg', args, { cwd: workspaceRoot(), timeout: 30_000 });
+                    stdout = result.stdout;
+                }
+                catch (error) {
+                    const code = typeof error === 'object' && error != null && 'code' in error ? error.code : undefined;
+                    if (code === 1) {
+                        stdout = '';
+                    }
+                    else {
+                        throw error;
+                    }
+                }
+                if (!stdout) {
+                    return { pattern, path: searchPath, glob: glob ?? null, caseInsensitive, matches: [], totalMatches: 0, truncated: false };
+                }
+                const { text: output, truncated } = truncate(stdout);
+                const lines = output.split('\n').filter(Boolean);
+                const matches = [];
+                for (const line of lines) {
+                    const match = line.match(/^(\S+?):(\d+)[-:](.*)$/);
+                    if (!match)
+                        continue;
+                    const [, file, lineStr, content] = match;
+                    if (file && lineStr && content !== undefined) {
+                        const isContext = line.includes('-');
+                        const relativePath = path.relative(workspaceRoot(), file);
+                        matches.push({ file: relativePath, line: Number(lineStr), content, isContext });
+                    }
+                }
+                return { pattern, path: searchPath, glob: glob ?? null, caseInsensitive, matches, totalMatches: matches.filter(m => !m.isContext).length, truncated };
+            }
+            catch (error) {
+                return structuredToolFailure('grep', error, 'Check that the search path exists and the pattern is valid regex. Try a narrower path or simpler pattern.', searchPath);
+            }
         }),
     }),
     replaceLines: tool({
-        description: 'Replace a 1-based inclusive line range in an existing UTF-8 text file. Prefer this after reading a file when exact editFile replacements are ambiguous or fail.',
+        description: 'Replace a 1-based inclusive line range in an existing UTF-8 text file. Prefer this after reading a file when exact editFile replacements are ambiguous or fail. If endLine is slightly beyond EOF, it is clamped to the current last line.',
         inputSchema: z.object({
             path: z.string().describe('File path relative to the current workspace'),
             startLine: z.number().int().positive().describe('First 1-based line number to replace'),
@@ -198,30 +376,41 @@ export const hazeTools = {
             allowIgnored: z.boolean().default(false).describe('Edit the file even if it is ignored by .gitignore. Use only when explicitly needed.'),
         }),
         execute: async ({ path: filePath, startLine, endLine, content, allowIgnored }, context) => runDedupedTool('replaceLines', { path: filePath, startLine, endLine, content, allowIgnored }, context, async () => {
-            const absolutePath = resolveWorkspacePath(filePath);
-            await assertNotIgnored(absolutePath, filePath, allowIgnored);
-            const original = await fs.readFile(absolutePath, 'utf8');
-            const hasTrailingNewline = original.endsWith('\n');
-            const lines = original.split(/\r?\n/);
-            if (hasTrailingNewline)
-                lines.pop();
-            const isAppend = startLine === lines.length + 1 && endLine === lines.length;
-            if (!isAppend && endLine < startLine)
-                throw new Error('endLine must be greater than or equal to startLine, except when appending at EOF with startLine=totalLines+1 and endLine=totalLines');
-            if (startLine > lines.length + 1)
-                throw new Error(`startLine ${startLine} is beyond end of file (${lines.length} lines)`);
-            if (endLine > lines.length)
-                throw new Error(`endLine ${endLine} is beyond end of file (${lines.length} lines)`);
-            const replacementLines = content.length === 0 ? [] : content.split(/\r?\n/);
-            if (isAppend) {
-                lines.push(...replacementLines);
+            try {
+                const absolutePath = resolveWorkspacePath(filePath);
+                await assertNotIgnored(absolutePath, filePath, allowIgnored);
+                const original = await fs.readFile(absolutePath, 'utf8');
+                const hasTrailingNewline = original.endsWith('\n');
+                const lines = original.split(/\r?\n/);
+                if (hasTrailingNewline)
+                    lines.pop();
+                const isAppend = startLine === lines.length + 1 && endLine === lines.length;
+                if (!isAppend && endLine < startLine)
+                    throw new Error('endLine must be greater than or equal to startLine, except when appending at EOF with startLine=totalLines+1 and endLine=totalLines');
+                if (startLine > lines.length + 1)
+                    throw new Error(`startLine ${startLine} is beyond end of file (${lines.length} lines)`);
+                const effectiveEndLine = !isAppend && endLine > lines.length ? lines.length : endLine;
+                const replacementLines = content.length === 0 ? [] : content.split(/\r?\n/);
+                const removedText = isAppend ? '' : lines.slice(startLine - 1, effectiveEndLine).join('\n');
+                const beforeContext = startLine > 1 ? { oldLine: startLine - 1, newLine: startLine - 1, text: lines[startLine - 2] ?? '' } : undefined;
+                const afterContext = !isAppend && effectiveEndLine < lines.length
+                    ? { oldLine: effectiveEndLine + 1, newLine: startLine + replacementLines.length, text: lines[effectiveEndLine] ?? '' }
+                    : undefined;
+                if (isAppend) {
+                    lines.push(...replacementLines);
+                }
+                else {
+                    lines.splice(startLine - 1, effectiveEndLine - startLine + 1, ...replacementLines);
+                }
+                const updated = lines.join('\n') + (hasTrailingNewline ? '\n' : '');
+                const { diff, addedLines, removedLines } = replacementDiff(removedText, content, startLine, startLine, { before: beforeContext, after: afterContext });
+                const diffLineCount = diff.length;
+                await fs.writeFile(absolutePath, updated, 'utf8');
+                return { ok: true, path: filePath, startLine, endLine: effectiveEndLine, requestedEndLine: endLine, endLineClamped: effectiveEndLine !== endLine, replacementLines: replacementLines.length, appended: isAppend, addedLines, removedLines, diffLineCount, diff: diffLineCount <= INLINE_DIFF_LINE_LIMIT ? diff : undefined };
             }
-            else {
-                lines.splice(startLine - 1, endLine - startLine + 1, ...replacementLines);
+            catch (error) {
+                return structuredToolFailure('replaceLines', error, 'Read the file again for current line numbers, then retry replaceLines with a valid range.', filePath);
             }
-            const updated = lines.join('\n') + (hasTrailingNewline ? '\n' : '');
-            await fs.writeFile(absolutePath, updated, 'utf8');
-            return { ok: true, path: filePath, startLine, endLine, replacementLines: replacementLines.length, appended: isAppend };
         }),
     }),
     writeFile: tool({
@@ -233,26 +422,31 @@ export const hazeTools = {
             allowIgnored: z.boolean().default(false).describe('Write the file even if it is ignored by .gitignore. Use only when explicitly needed.'),
         }),
         execute: async ({ path: filePath, content, overwriteExisting, allowIgnored }, context) => runDedupedTool('writeFile', { path: filePath, content, overwriteExisting, allowIgnored }, context, async () => {
-            const absolutePath = resolveWorkspacePath(filePath);
-            await assertNotIgnored(absolutePath, filePath, allowIgnored);
             try {
-                await fs.access(absolutePath);
-                if (!overwriteExisting) {
-                    throw new Error(`Refusing to overwrite existing file: ${filePath}. Use editFile/replaceLines for targeted edits, or set overwriteExisting=true for an intentional complete rewrite.`);
+                const absolutePath = resolveWorkspacePath(filePath);
+                await assertNotIgnored(absolutePath, filePath, allowIgnored);
+                try {
+                    await fs.access(absolutePath);
+                    if (!overwriteExisting) {
+                        throw new Error(`Refusing to overwrite existing file: ${filePath}. Use editFile/replaceLines for targeted edits, or set overwriteExisting=true for an intentional complete rewrite.`);
+                    }
+                }
+                catch (error) {
+                    const code = typeof error === 'object' && error != null && 'code' in error ? error.code : undefined;
+                    if (code !== 'ENOENT')
+                        throw error;
                 }
+                await fs.mkdir(path.dirname(absolutePath), { recursive: true });
+                await fs.writeFile(absolutePath, content, 'utf8');
+                return { ok: true, path: filePath, bytes: Buffer.byteLength(content, 'utf8'), overwritten: overwriteExisting };
             }
             catch (error) {
-                const code = typeof error === 'object' && error != null && 'code' in error ? error.code : undefined;
-                if (code !== 'ENOENT')
-                    throw error;
+                return structuredToolFailure('writeFile', error, 'Use editFile/replaceLines for existing files, set overwriteExisting=true only for an intentional rewrite, or check the path/ignored-file setting.', filePath);
             }
-            await fs.mkdir(path.dirname(absolutePath), { recursive: true });
-            await fs.writeFile(absolutePath, content, 'utf8');
-            return { ok: true, path: filePath, bytes: Buffer.byteLength(content, 'utf8'), overwritten: overwriteExisting };
         }),
     }),
     editFile: tool({
-        description: 'Edit a text file using exact replacements. Each oldText must match exactly once in the original file and edits must not overlap. If this fails because text is missing or not unique, do not retry; use replaceLines instead.',
+        description: 'Edit a text file using unique replacements. Each oldText should match the current file; line-number prefixes from readFile output and trailing-whitespace-only differences are tolerated when the match is still unique. Put multiple edits to the same file in one call. If this fails because text is missing or not unique, read the file again and use replaceLines.',
         inputSchema: z.object({
             path: z.string().describe('File path relative to the current workspace'),
             edits: z.array(z.object({
@@ -262,29 +456,55 @@ export const hazeTools = {
             allowIgnored: z.boolean().default(false).describe('Edit the file even if it is ignored by .gitignore. Use only when explicitly needed.'),
         }),
         execute: async ({ path: filePath, edits, allowIgnored }, context) => runDedupedTool('editFile', { path: filePath, edits, allowIgnored }, context, async () => {
-            const absolutePath = resolveWorkspacePath(filePath);
-            await assertNotIgnored(absolutePath, filePath, allowIgnored);
-            const original = await fs.readFile(absolutePath, 'utf8');
-            const ranges = edits.map((edit, index) => {
-                const first = original.indexOf(edit.oldText);
-                if (first === -1)
-                    throw new Error(`edit ${index}: oldText was not found`);
-                const second = original.indexOf(edit.oldText, first + edit.oldText.length);
-                if (second !== -1)
-                    throw new Error(`edit ${index}: oldText is not unique`);
-                return { index, start: first, end: first + edit.oldText.length, edit };
-            }).sort((a, b) => a.start - b.start);
-            for (let i = 1; i < ranges.length; i++) {
-                if (ranges[i].start < ranges[i - 1].end) {
-                    throw new Error(`edits ${ranges[i - 1].index} and ${ranges[i].index} overlap`);
+            try {
+                const absolutePath = resolveWorkspacePath(filePath);
+                await assertNotIgnored(absolutePath, filePath, allowIgnored);
+                const original = await fs.readFile(absolutePath, 'utf8');
+                const ranges = edits.map((edit, index) => {
+                    const match = findEditRange(original, edit.oldText);
+                    if (match.kind === 'missing')
+                        throw new Error(`edit ${index}: oldText was not found. Read the file again and use the exact current text, or use replaceLines with the latest line numbers.`);
+                    if (match.kind === 'multiple')
+                        throw new Error(`edit ${index}: oldText is not unique`);
+                    return { index, start: match.start, end: match.end, edit, approximate: match.approximate };
+                }).sort((a, b) => a.start - b.start);
+                for (let i = 1; i < ranges.length; i++) {
+                    if (ranges[i].start < ranges[i - 1].end) {
+                        throw new Error(`edits ${ranges[i - 1].index} and ${ranges[i].index} overlap`);
+                    }
                 }
+                let updated = original;
+                for (const range of [...ranges].sort((a, b) => b.start - a.start)) {
+                    updated = updated.slice(0, range.start) + range.edit.newText + updated.slice(range.end);
+                }
+                const originalLines = splitDiffLines(original);
+                let lineDelta = 0;
+                let addedLines = 0;
+                let removedLines = 0;
+                const diff = [];
+                for (const range of ranges) {
+                    const oldStartLine = lineNumberAtOffset(original, range.start);
+                    const newStartLine = oldStartLine + lineDelta;
+                    const oldLineCount = splitDiffLines(range.edit.oldText).length;
+                    const newLineCount = splitDiffLines(range.edit.newText).length;
+                    const beforeContext = oldStartLine > 1 ? { oldLine: oldStartLine - 1, newLine: newStartLine - 1, text: originalLines[oldStartLine - 2] ?? '' } : undefined;
+                    const afterOldLine = oldStartLine + oldLineCount;
+                    const afterContext = afterOldLine <= originalLines.length
+                        ? { oldLine: afterOldLine, newLine: newStartLine + newLineCount, text: originalLines[afterOldLine - 1] ?? '' }
+                        : undefined;
+                    const rangeDiff = replacementDiff(range.edit.oldText, range.edit.newText, oldStartLine, newStartLine, { before: beforeContext, after: afterContext });
+                    diff.push(...rangeDiff.diff);
+                    addedLines += rangeDiff.addedLines;
+                    removedLines += rangeDiff.removedLines;
+                    lineDelta += rangeDiff.addedLines - rangeDiff.removedLines;
+                }
+                const diffLineCount = diff.length;
+                await fs.writeFile(absolutePath, updated, 'utf8');
+                return { ok: true, path: filePath, edits: edits.length, approximateMatches: ranges.filter(range => range.approximate).length, addedLines, removedLines, diffLineCount, diff: diffLineCount <= INLINE_DIFF_LINE_LIMIT ? diff : undefined };
             }
-            let updated = original;
-            for (const range of [...ranges].sort((a, b) => b.start - a.start)) {
-                updated = updated.slice(0, range.start) + range.edit.newText + updated.slice(range.end);
+            catch (error) {
+                return structuredToolFailure('editFile', error, 'Read the file again, then retry with exact current text or use replaceLines with the latest line numbers.', filePath);
             }
-            await fs.writeFile(absolutePath, updated, 'utf8');
-            return { ok: true, path: filePath, edits: edits.length };
         }),
     }),
     bash: tool({
@@ -296,7 +516,7 @@ export const hazeTools = {
         }),
         execute: async ({ command, timeoutSeconds, allowMutation }, context) => runDedupedTool('bash', { command, timeoutSeconds, allowMutation }, context, async () => {
             if (!allowMutation && looksLikeShellFileMutation(command)) {
-                throw new Error('Refusing to mutate files via bash. Use writeFile/editFile/replaceLines, or set allowMutation=true only when shell mutation is explicitly required.');
+                return structuredToolFailure('bash', 'Refusing to mutate files via bash. Use writeFile/editFile/replaceLines, or set allowMutation=true only when shell mutation is explicitly required.', 'Use writeFile/editFile/replaceLines for file changes, or retry bash with allowMutation=true only when shell mutation is explicitly required.');
             }
             const timeoutMs = (timeoutSeconds ?? 60) * 1000;
             return await new Promise(resolve => {

package/dist/llm/initPrompt.js

@@ -1,10 +1,12 @@
 export function buildInitPrompt() {
     return `Initialize this repository for Haze by creating a best-practice AGENTS.md file.
 
-Explore the codebase first, respecting .gitignore:
+Explore the codebase first, respecting .gitignore, but keep this quick and minimal:
 1. Start with exactly one listFiles call from the workspace root. Do not announce that you are starting before the tool call.
-2. After listFiles returns, do not call listFiles with the same input again. Immediately read the files needed to understand project conventions, commands, architecture, and release workflow. Usually read package/config files, README, AGENTS.md if present, and key source entrypoints.
-3. Do not read ignored files unless truly necessary.
+2. Do not use bash for discovery unless package metadata is missing. Do not grep/find the tree for this command.
+3. After listFiles returns, read only the small set needed to understand conventions: package/config files, README, existing AGENTS.md if present, and at most three key source entrypoints/directories.
+4. Do not call listFiles with the same input twice. Do not read the same path repeatedly. Do not read speculative files; list the parent first if unsure.
+5. Aim to finish in 12 tool calls or fewer. Do not read ignored files unless truly necessary.
 
 Create or update AGENTS.md at the workspace root. It should be concise and useful for future coding agents. Include sections when known:
 - Project overview
@@ -15,5 +17,5 @@ Create or update AGENTS.md at the workspace root. It should be concise and usefu
 - Testing/validation expectations
 - Safety notes or files/directories to avoid
 
-If AGENTS.md already exists, preserve useful existing instructions and improve them. After writing it, summarize what you learned and what you wrote.`;
+If AGENTS.md already exists, preserve useful existing instructions and improve them with targeted editFile/replaceLines edits. Do not rewrite the entire file unless it is missing or unusable. After writing it, summarize only the change and validation status.`;
 }

package/dist/llm/systemPrompt.js

@@ -5,31 +5,35 @@ export function buildSystemPrompt(contextFiles = []) {
     return `You are Haze, an expert coding assistant operating inside a terminal-based agent CLI. You help users build apps by understanding the current conversation, inspecting projects, running commands, and editing files.
 
 Available tools:
-- listFiles: List files and directories in the current workspace. Supports recursive listings and cursor pagination. Prefer this over bash ls/find for project discovery.
-- readFile: Read UTF-8 files with optional line ranges. Returns lineNumberedText for line-based edits.
-- editFile: Edit files with exact unique text replacements. Use only for small, unambiguous replacements.
-- replaceLines: Replace a 1-based inclusive line range. Use when editFile is ambiguous or has failed once. To append at EOF, use startLine=totalLines+1 and endLine=totalLines from the latest readFile result.
+- grep: Fast regex search across the workspace using ripgrep. Use to find symbol definitions, usages, string literals, import paths, and code patterns. Prefer grep over readFile when you need to locate something in the codebase -- grep searches all files at once and returns matching lines with file paths and line numbers. Use glob to narrow to specific file types and path to narrow to specific directories.
+- listFiles: List files and directories in the current workspace. Supports recursive listings and cursor pagination. Use for project structure discovery, not for finding specific code.
+- readFile: Read a specific file when you already know which file to look at. Returns numbered lines for precise edits. Use after grep to read the full context around a match, not to search for code across files.
+- editFile: Edit files with unique text replacements. Use only for small, unambiguous replacements. Put multiple edits to the same file in one editFile call; do not issue parallel separate edits for the same file.
+- replaceLines: Replace a 1-based inclusive line range. Use when editFile is ambiguous or has failed once. To append at EOF, use startLine=totalLines+1 and endLine=totalLines from the latest readFile result. Slightly-too-large endLine values are clamped to EOF.
 - writeFile: Create files, or overwrite existing files only when overwriteExisting=true is intentionally set for a complete rewrite. Prefer editFile/replaceLines for existing files.
 - bash: Run shell commands for tests, builds, scripts, and inspection that cannot be done with file tools. Do not use bash to mutate files unless explicitly requested or file tools cannot do the job.
+- subagent: Spawn focused subagents to run independent tasks in parallel. Each subagent gets a fresh context and full tool access. ONLY use subagents when a request clearly decomposes into 2+ independent subtasks that can run concurrently. Do NOT use subagents for single tasks, sequential work, or tasks that benefit from your full conversation context — do those yourself. Subagents have no access to the conversation history, so the main agent should always handle complex, context-dependent work directly.
 - skill_*: Markdown skills installed in ~/.haze/skills. Use a skill tool when its description matches the user's request; it returns workflow instructions and explicitly referenced files.
 
 Guidelines:
 - Be concise, technical, and practical.
+- Only spawn subagents when a request clearly splits into 2+ independent parallel tasks (e.g. "check auth, payments, and users" -> 3 subagents). For everything else, do the work yourself — you have the most context. Never spawn a single subagent for a task you could do directly.
 - You have access to the tools listed above. Never claim that you cannot inspect files, run shell commands, or make file changes when an available tool can do it.
 - Skills are optional instruction bundles. Call a skill tool only when relevant, then follow the returned SKILL.md instructions and references.
 - If answering requires current workspace information, inspect it with tools instead of guessing or saying you cannot access it.
 - When the user asks you to run a command, inspect command output, or reason about local project state, use bash or file tools rather than only explaining what the user could run.
 - Preserve user-provided content exactly. When the user asks to add, modify, or use "this", "that", "it", or previous content, refer to the current conversation and do not substitute different text.
+- Use grep to find code across the workspace. Do not read multiple files one by one to locate a symbol, import, or string -- use grep with a targeted pattern and glob filter instead. Only use readFile after grep has identified the relevant file and line range, or when the user names a specific file.
 - Use listFiles for project discovery instead of bash ls/find. Start non-recursive, use recursive for focused directories, and follow nextCursor only when more listing is genuinely needed.
 - Do not list or read the same path repeatedly unless the file changed or the previous result was insufficient.
 - Read only directly relevant files, usually once. Do not read README/package files unless needed for the task.
 - File tools follow .gitignore by default. Only set includeIgnored/allowIgnored when the user explicitly asks or the task truly requires ignored files, and say why.
-- Prefer editFile for existing files when one small exact replacement is unique.
+- Prefer editFile for existing files when one small replacement is unique. For multiple edits in one file, use one editFile call with multiple non-overlapping edits instead of parallel tool calls.
 - If editFile fails because oldText is missing or not unique, do not retry editFile for the same change; use replaceLines with lineNumberedText from readFile.
 - Use writeFile for new files. For existing files, prefer editFile or replaceLines; only set writeFile overwriteExisting=true when a complete rewrite is intentional and safer than targeted edits.
 - Use bash mainly for tests, builds, package scripts, and commands that are not covered by file tools. Do not combine validation with file mutation in one shell command; use file tools for edits and bash only for validation/inspection.
 - After making changes, validate with the project's relevant test/typecheck/build command when practical. After editing source or test files in languages with syntax checkers, run the syntax check before the full test command when practical. Once a requested change is edited and validation passes, summarize; do not continue inspecting files.
-- For action requests such as "add", "create", "write", "implement", "update", "fix", "test", or "document", do not stop after only inspecting files. Make the requested file/code changes unless blocked or clarification is required.
+- For action requests such as "add", "create", "write", "implement", "update", "fix", "test", or "document", work autonomously until the requested goal is complete, validation has run when practical, a concrete blocker prevents progress, or a user decision is required. Do not stop after only inspecting files.
 - Requests like "create a plan", "make a plan", or "outline a plan" are planning requests, not implementation requests. If you create a plan document, summarize it; do not start implementing or validating unless asked.
 - If editFile or replaceLines fails, read the affected file again with readFile before another edit attempt, then make one smaller targeted change; do not batch speculative replacements. Bash/cat does not satisfy this recovery step.
 - For plan-only requests, stop after creating/updating the plan artifact and summarize it; do not edit source files or run validation in the same turn.
@@ -37,7 +41,7 @@ Guidelines:
 - After tool use, always respond with a concise summary of what changed or what failed for the current user request only. Do not recap unrelated earlier tasks unless directly relevant.
 - Do not call ordinary unfinished work or unresolved optional scope a blocker. A blocker is a concrete tool failure, missing/ambiguous requirement, permission problem, or unavailable dependency.
 - For Ruby ad-hoc checks, prefer adding/running Minitest tests. If a one-liner is truly useful, use ruby -I. -e with require "file" rather than require_relative from -e.
-- Do not say tools are unavailable just because a tool budget or loop guard was mentioned; if you can still call tools in the current turn, continue the requested work.
+- Do not say tools are unavailable just because a tool slice or loop guard was mentioned; if you can still call tools in the current turn, continue the requested work. If a local tool slice ends and work remains, state the next concrete unfinished action rather than asking the user to type continue.
 - Do not claim tests passed or commands succeeded unless you actually ran them in the current turn and saw success.
 - Ask before destructive actions.
 - Show file paths clearly when working with files.${projectContext}

package/dist/skills/builder/SkillBuilder.d.ts

@@ -9,6 +9,9 @@ type GeneratedSkill = {
 export declare function slug(s: string): string;
 declare function fallbackSkill(description: string): GeneratedSkill;
 declare function withStandardRequirements(content: string): string;
+declare function withSkillName(content: string, name: string): string;
+declare function normalizeSkillDescription(description: string): string;
+declare function withSkillDescription(content: string, description: string): string;
 declare function parseGeneratedSkill(text: string, description: string): GeneratedSkill;
 export declare function createSkill(description: string): Promise<{
     name: string;
@@ -21,5 +24,8 @@ export declare const internals: {
     parseGeneratedSkill: typeof parseGeneratedSkill;
     fallbackSkill: typeof fallbackSkill;
     withStandardRequirements: typeof withStandardRequirements;
+    withSkillName: typeof withSkillName;
+    withSkillDescription: typeof withSkillDescription;
+    normalizeSkillDescription: typeof normalizeSkillDescription;
 };
 export {};