@denizokcu/haze 0.0.1 → 0.0.3

package/dist/llm/hazeTools.js

@@ -40,6 +40,172 @@ 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)}`;
+}
+function hazeContext(context) {
+    return typeof context.experimental_context === 'object' && context.experimental_context != null
+        ? context.experimental_context
+        : undefined;
+}
+function isMutatingTool(toolName) {
+    return ['editFile', 'replaceLines', 'writeFile'].includes(toolName);
+}
+function isReadOnlyFileTool(toolName) {
+    return ['listFiles', 'readFile'].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 };
+}
+async function runDedupedTool(toolName, input, context, execute) {
+    const ctx = hazeContext(context);
+    if (!ctx)
+        return execute();
+    ctx.inFlightToolCalls ??= new Map();
+    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.`);
+    }
+    const completedAt = ctx.completedToolCalls.get(key);
+    const readAfterFailedMutation = toolName === 'readFile' && pathForInput && ctx.failedMutationPaths.has(pathForInput) && !ctx.pathsReadAfterFailedMutation.has(pathForInput);
+    if ((isReadOnlyFileTool(toolName) || toolName === 'bash') && completedAt === ctx.mutationEpoch && !readAfterFailedMutation) {
+        return {
+            ok: true,
+            duplicateSkipped: true,
+            toolName,
+            reason: toolName === 'bash'
+                ? 'Skipped duplicate bash command; no files changed since the previous run.'
+                : 'Skipped duplicate read-only tool call with identical input; no files changed since the previous call.',
+        };
+    }
+    if (ctx.inFlightToolCalls.has(key)) {
+        return {
+            ok: true,
+            duplicateSkipped: true,
+            toolName,
+            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)) {
+            ctx.mutationEpoch += 1;
+            if (pathForInput) {
+                ctx.failedMutationPaths.delete(pathForInput);
+                ctx.pathsReadAfterFailedMutation.delete(pathForInput);
+            }
+        }
+        ctx.completedToolCalls.set(key, ctx.mutationEpoch);
+        return result;
+    }
+    catch (error) {
+        if (isMutatingTool(toolName) && pathForInput) {
+            ctx.failedMutationPaths.add(pathForInput);
+            ctx.pathsReadAfterFailedMutation.delete(pathForInput);
+        }
+        throw error;
+    }
+    finally {
+        ctx.inFlightToolCalls.delete(key);
+        if (isMutatingTool(toolName) && pathForInput)
+            ctx.inFlightMutationPaths?.delete(pathForInput);
+    }
+}
+function looksLikeShellFileMutation(command) {
+    return /(^|[;&|]\s*)(sed\s+-i|perl\s+-pi|tee\b|chmod\b|mv\b|cp\b|rm\b|mkdir\b|touch\b)/.test(command)
+        || /(^|\s)(>|>>)(\s|\S)/.test(command)
+        || /\b(File\.write|writeFileSync|writeFile|appendFileSync|appendFile)\b/.test(command);
+}
 export const hazeTools = {
     listFiles: tool({
         description: 'List files and directories in the current workspace. Prefer this over bash ls/find for discovering project structure.',
@@ -47,31 +213,39 @@ export const hazeTools = {
             path: z.string().default('.').describe('Directory path relative to the current workspace'),
             recursive: z.boolean().default(false).describe('Whether to list files recursively'),
             maxEntries: z.number().int().positive().max(500).default(100).describe('Maximum number of entries to return'),
+            cursor: z.string().optional().describe('Pagination cursor from a previous listFiles result. Continue after that entry.'),
             includeIgnored: z.boolean().default(false).describe('Include files ignored by .gitignore. Use only when explicitly needed.'),
         }),
-        execute: async ({ path: dirPath, recursive, maxEntries, includeIgnored }) => {
-            const absolutePath = resolveWorkspacePath(dirPath);
-            await assertNotIgnored(absolutePath, dirPath, includeIgnored);
-            const entries = [];
-            let ignoredSkipped = 0;
-            const walked = await walkDir(absolutePath, { recursive, maxEntries, filter: async (entry) => {
-                    if (!includeIgnored && await isGitIgnored(entry.absolutePath)) {
-                        ignoredSkipped++;
-                        return false;
+        execute: async ({ path: dirPath, recursive, maxEntries, cursor, includeIgnored }, context) => runDedupedTool('listFiles', { path: dirPath, recursive, maxEntries, cursor, includeIgnored }, context, async () => {
+            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;
-                } });
-            for (const entry of walked) {
-                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 };
             }
-            return { path: dirPath, recursive, includeIgnored, ignoredSkipped, entries, truncated: entries.length >= maxEntries };
-        },
+            catch (error) {
+                return structuredToolFailure('listFiles', error, 'Check that the directory exists and is not ignored, or retry with a narrower path.', dirPath);
+            }
+        }),
     }),
     readFile: tool({
         description: 'Read a UTF-8 text file from the current workspace. Supports optional 1-based line offset and line limit.',
@@ -81,72 +255,104 @@ export const hazeTools = {
             limit: z.number().int().positive().max(2000).optional().describe('Maximum number of lines to return'),
             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 }) => {
-            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),
-            };
-        },
+        execute: async ({ path: filePath, offset, limit, allowIgnored }, context) => runDedupedTool('readFile', { path: filePath, offset, limit, allowIgnored }, context, async () => {
+            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);
+            }
+        }),
     }),
     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'),
-            endLine: z.number().int().positive().describe('Last 1-based line number to replace, inclusive'),
+            endLine: z.number().int().nonnegative().describe('Last 1-based line number to replace, inclusive. To append at EOF, use startLine=totalLines+1 and endLine=totalLines.'),
             content: z.string().describe('Replacement content for the line range'),
             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 }) => {
-            if (endLine < startLine)
-                throw new Error('endLine must be greater than or equal to startLine');
-            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();
-            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/);
-            lines.splice(startLine - 1, endLine - startLine + 1, ...replacementLines);
-            const updated = lines.join('\n') + (hasTrailingNewline ? '\n' : '');
-            await fs.writeFile(absolutePath, updated, 'utf8');
-            return { ok: true, path: filePath, startLine, endLine, replacementLines: replacementLines.length };
-        },
+        execute: async ({ path: filePath, startLine, endLine, content, allowIgnored }, context) => runDedupedTool('replaceLines', { path: filePath, startLine, endLine, content, allowIgnored }, context, async () => {
+            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/);
+                if (isAppend) {
+                    lines.push(...replacementLines);
+                }
+                else {
+                    lines.splice(startLine - 1, effectiveEndLine - startLine + 1, ...replacementLines);
+                }
+                const updated = lines.join('\n') + (hasTrailingNewline ? '\n' : '');
+                await fs.writeFile(absolutePath, updated, 'utf8');
+                return { ok: true, path: filePath, startLine, endLine: effectiveEndLine, requestedEndLine: endLine, endLineClamped: effectiveEndLine !== endLine, replacementLines: replacementLines.length, appended: isAppend };
+            }
+            catch (error) {
+                return structuredToolFailure('replaceLines', error, 'Read the file again for current line numbers, then retry replaceLines with a valid range.', filePath);
+            }
+        }),
     }),
     writeFile: tool({
-        description: 'Create or overwrite a UTF-8 text file in the current workspace. Creates parent directories as needed. Use for new files or after smaller edit tools are not suitable.',
+        description: 'Create a UTF-8 text file in the current workspace. For existing files, prefer editFile/replaceLines; set overwriteExisting=true only for an intentional complete rewrite.',
         inputSchema: z.object({
             path: z.string().describe('File path relative to the current workspace'),
             content: z.string().describe('Complete file contents to write'),
+            overwriteExisting: z.boolean().default(false).describe('Required to overwrite an existing file. Prefer editFile or replaceLines for existing files unless a complete rewrite is intentional.'),
             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, allowIgnored }) => {
-            const absolutePath = resolveWorkspacePath(filePath);
-            await assertNotIgnored(absolutePath, filePath, allowIgnored);
-            await fs.mkdir(path.dirname(absolutePath), { recursive: true });
-            await fs.writeFile(absolutePath, content, 'utf8');
-            return { ok: true, path: filePath, bytes: Buffer.byteLength(content, 'utf8') };
-        },
+        execute: async ({ path: filePath, content, overwriteExisting, allowIgnored }, context) => runDedupedTool('writeFile', { path: filePath, content, overwriteExisting, allowIgnored }, context, async () => {
+            try {
+                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) {
+                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);
+            }
+        }),
     }),
     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({
@@ -155,39 +361,47 @@ export const hazeTools = {
             })).min(1).describe('One or more non-overlapping exact replacements'),
             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 }) => {
-            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`);
+        execute: async ({ path: filePath, edits, allowIgnored }, context) => runDedupedTool('editFile', { path: filePath, edits, allowIgnored }, context, async () => {
+            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);
                 }
+                await fs.writeFile(absolutePath, updated, 'utf8');
+                return { ok: true, path: filePath, edits: edits.length, approximateMatches: ranges.filter(range => range.approximate).length };
             }
-            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({
-        description: 'Run a bash command in the current workspace. Use for inspecting files, running tests, builds, and other shell tasks. Avoid destructive commands unless the user explicitly asked.',
+        description: 'Run a bash command in the current workspace. Use for tests, builds, validation, and inspection. Do not use bash to edit files; use file tools instead unless the user explicitly requested a shell mutation.',
         inputSchema: z.object({
             command: z.string().min(1).describe('Command to execute with bash -lc'),
             timeoutSeconds: z.number().int().positive().max(600).optional().describe('Timeout in seconds; defaults to 60'),
+            allowMutation: z.boolean().default(false).describe('Allow shell commands that mutate files (chmod, redirection, tee, sed -i, File.write, etc.). Use only when explicitly requested or when file tools cannot do the job.'),
         }),
-        execute: async ({ command, timeoutSeconds }, { abortSignal }) => {
+        execute: async ({ command, timeoutSeconds, allowMutation }, context) => runDedupedTool('bash', { command, timeoutSeconds, allowMutation }, context, async () => {
+            if (!allowMutation && looksLikeShellFileMutation(command)) {
+                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 => {
                 const child = spawn('bash', ['-lc', command], { cwd: workspaceRoot(), stdio: ['ignore', 'pipe', 'pipe'] });
@@ -199,13 +413,13 @@ export const hazeTools = {
                         child.kill('SIGTERM');
                 }, timeoutMs);
                 const abort = () => child.kill('SIGTERM');
-                abortSignal?.addEventListener('abort', abort, { once: true });
+                context.abortSignal?.addEventListener('abort', abort, { once: true });
                 child.stdout.on('data', data => stdout += data.toString());
                 child.stderr.on('data', data => stderr += data.toString());
                 child.on('close', code => {
                     settled = true;
                     clearTimeout(timer);
-                    abortSignal?.removeEventListener('abort', abort);
+                    context.abortSignal?.removeEventListener('abort', abort);
                     resolve({
                         ok: code === 0,
                         code,
@@ -217,10 +431,10 @@ export const hazeTools = {
                 child.on('error', error => {
                     settled = true;
                     clearTimeout(timer);
-                    abortSignal?.removeEventListener('abort', abort);
+                    context.abortSignal?.removeEventListener('abort', abort);
                     resolve({ ok: false, command, error: error.message });
                 });
             });
-        },
+        }),
     }),
 };

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:
-1. Use listFiles recursively from the workspace root.
-2. Read only the files needed to understand project conventions, commands, architecture, and release workflow. Usually read package/config files, README, and key source entrypoints.
-3. Do not read ignored files unless truly necessary.
+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. 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,26 +5,40 @@ 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. Prefer this over bash ls/find for project discovery.
+- 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.
-- writeFile: Create or overwrite files. Use for new files or intentional complete rewrites.
-- bash: Run shell commands for tests, builds, scripts, and inspection that cannot be done with file tools.
+- 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.
+- 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.
+- 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 listFiles for project discovery instead of bash ls/find.
+- 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 only for new files or complete rewrites.
-- Use bash mainly for tests, builds, package scripts, and commands that are not covered by file tools.
-- After making changes, validate with the project's relevant test/typecheck/build command when practical.
-- After tool use, always respond with a concise summary of what changed or what failed.
+- 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.
+- 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.
+- When asked to implement a plan, identify the concrete required checklist items first and compare them with the current files. Do not edit source or tests when the required behavior is already present. Implement the smallest clearly required phase or required items, skip optional/design-question items unless explicitly requested, prefer adding tests over exploratory one-off scripts, validate once after code/test edits, and do not edit the plan file itself unless asked or unless marking completed items after validation passes.
+- 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 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/SkillLoader.d.ts

@@ -1,2 +1,12 @@
-import type { LoadedSkill } from './types.js';
-export declare function loadSkill(dir: string, source: 'global' | 'local'): Promise<LoadedSkill | null>;
+import type { LoadedSkill, SkillFrontmatter } from './types.js';
+declare function parseSkillMarkdown(content: string): {
+    frontmatter: SkillFrontmatter;
+    body: string;
+};
+declare function referencedPaths(body: string): string[];
+export declare function loadSkill(dir: string, source?: 'global'): Promise<LoadedSkill | null>;
+export declare const internals: {
+    parseSkillMarkdown: typeof parseSkillMarkdown;
+    referencedPaths: typeof referencedPaths;
+};
+export {};