@gaunt-sloth/agent 2.0.0-alpha.3 → 2.0.0-alpha.30

package/dist/tools/GthFileSystemToolkit.js

@@ -4,7 +4,6 @@ import fs from 'fs/promises';
 import path from 'node:path';
 import os from 'os';
 import { createTwoFilesPatch } from 'diff';
-import { displayInfo } from '@gaunt-sloth/core/utils/consoleUtils.js';
 import { shouldIgnoreFile } from '@gaunt-sloth/core/utils/aiignoreUtils.js';
 import { getCurrentWorkDir } from '@gaunt-sloth/core/utils/systemUtils.js';
 import { getFormatForExtension, getMimeType, readBinaryFile } from '#src/tools/binaryUtils.js';
@@ -14,6 +13,17 @@ import { getFormatForExtension, getMimeType, readBinaryFile } from '#src/tools/b
  */
 // TODO make it configurable
 const IGNORED_DIRS = ['node_modules', '.git', '.idea', 'dist'];
+// read_file safety envelope (GS2-39). A single large file — or a minified bundle that is one
+// multi-MB line — must not consume the whole context window in one uncapped read. Defaults are
+// adopted from opencode's read tool (packages/core/src/tool/read-filesystem.ts): at most
+// MAX_READ_LINES lines or MAX_READ_BYTES bytes are returned, and any single line longer than
+// MAX_LINE_LENGTH characters is truncated with LINE_TRUNCATED_SUFFIX. offset/limit paging is the
+// escape hatch to fetch whatever the cap dropped. This bounds context, not process memory: like
+// the existing head/tail helpers the file is still read whole and then trimmed.
+const MAX_READ_LINES = 2000;
+const MAX_READ_BYTES = 50 * 1024;
+const MAX_LINE_LENGTH = 2000;
+const LINE_TRUNCATED_SUFFIX = `... (line truncated to ${MAX_LINE_LENGTH} chars)`;
 // Helper function to create a tool with filesystem type
 function createGthTool(fn, config, gthFileSystemType) {
     const toolInstance = tool(fn, config);
@@ -24,8 +34,33 @@ function createGthTool(fn, config, gthFileSystemType) {
 // Schema definitions
 const ReadFileArgsSchema = z.object({
     path: z.string(),
-    tail: z.number().optional().describe('If provided, returns only the last N lines of the file'),
-    head: z.number().optional().describe('If provided, returns only the first N lines of the file'),
+    offset: z
+        .number()
+        .optional()
+        .describe('Start of a 1-based line window: the first line to return (inclusive). Combine with ' +
+        '`limit` to page through a large file (e.g. offset 2001 continues past the default ' +
+        `${MAX_READ_LINES}-line cap). Mutually exclusive with head/tail — pass a line window ` +
+        '(offset/limit) OR head/tail, not both.'),
+    limit: z
+        .number()
+        .optional()
+        .describe('Number of lines to return starting at `offset` (defaults to and is hard-capped at ' +
+        `${MAX_READ_LINES}). Use with \`offset\` to read an arbitrary window. Mutually ` +
+        'exclusive with head/tail.'),
+    tail: z
+        .number()
+        .optional()
+        .describe('If provided, returns only the last N lines of the file. May be combined with head ' +
+        '(no longer mutually exclusive): head+tail returns the first head lines, a ' +
+        '`... [N lines skipped] ...` marker, then the last tail lines. Mutually exclusive ' +
+        'with the offset/limit line window.'),
+    head: z
+        .number()
+        .optional()
+        .describe('If provided, returns only the first N lines of the file. May be combined with tail ' +
+        '(no longer mutually exclusive): head+tail returns the first head lines, a ' +
+        '`... [N lines skipped] ...` marker, then the last tail lines. Mutually exclusive ' +
+        'with the offset/limit line window.'),
 });
 const ReadBinaryArgsSchema = z.object({
     path: z.string().describe('Path to the binary file to read'),
@@ -44,6 +79,12 @@ const WriteFileArgsSchema = z.object({
 const EditOperation = z.object({
     oldText: z.string().describe('Text to search for - must match exactly'),
     newText: z.string().describe('Text to replace with'),
+    replaceAll: z
+        .boolean()
+        .default(false)
+        .describe('Replace all occurrences of oldText. Default false requires a unique match: if oldText ' +
+        'appears more than once the edit fails so you can add surrounding context to disambiguate; ' +
+        'set true to replace every occurrence.'),
 });
 const EditFileArgsSchema = z.object({
     path: z.string(),
@@ -274,14 +315,50 @@ export default class GthFileSystemToolkit extends BaseToolkit {
         const normalizedNew = this.normalizeLineEndings(newContent);
         return createTwoFilesPatch(filepath, filepath, normalizedOriginal, normalizedNew, 'original', 'modified');
     }
+    /**
+     * Count non-overlapping exact occurrences of `search` in `content`.
+     * Uses an indexOf scan (no regex) so arbitrary text is matched literally.
+     */
+    countOccurrences(content, search) {
+        if (search === '')
+            return 0;
+        let count = 0;
+        let offset = 0;
+        let idx = content.indexOf(search, offset);
+        while (idx !== -1) {
+            count++;
+            offset = idx + search.length;
+            idx = content.indexOf(search, offset);
+        }
+        return count;
+    }
     async applyFileEdits(filePath, edits, dryRun = false) {
         const content = this.normalizeLineEndings(await fs.readFile(filePath, 'utf-8'));
         let modifiedContent = content;
+        const summaries = [];
+        let editIndex = 0;
         for (const edit of edits) {
+            editIndex++;
             const normalizedOld = this.normalizeLineEndings(edit.oldText);
             const normalizedNew = this.normalizeLineEndings(edit.newText);
-            if (modifiedContent.includes(normalizedOld)) {
-                modifiedContent = modifiedContent.replace(normalizedOld, normalizedNew);
+            const occurrences = this.countOccurrences(modifiedContent, normalizedOld);
+            if (occurrences > 0) {
+                if (occurrences > 1 && edit.replaceAll !== true) {
+                    // Ambiguous match: refuse rather than silently editing the first occurrence. Thrown here
+                    // and caught at the tool boundary (GS2-36), which surfaces it as a recoverable errored
+                    // result naming the path — so the model can add surrounding context and retry instead of
+                    // the run aborting. Phrased as an action-oriented recovery hint (EXT-34 hermes style).
+                    throw new Error(`found ${occurrences} occurrences of the search text, so the edit is ambiguous and the ` +
+                        'file was NOT modified. Add more surrounding context to make the match unique, or set ' +
+                        'replaceAll: true to replace every occurrence.\n' +
+                        edit.oldText);
+                }
+                // split/join replaces every occurrence without regex escaping and, unlike
+                // String.replace, does NOT interpret `$`-patterns ($&, $`, $', $$) in the
+                // replacement text; for a unique match (occurrences === 1) it replaces exactly
+                // that one occurrence.
+                modifiedContent = modifiedContent.split(normalizedOld).join(normalizedNew);
+                summaries.push(`edit ${editIndex}: replaced ${occurrences} occurrence(s)`);
                 continue;
             }
             const oldLines = normalizedOld.split('\n');
@@ -313,8 +390,18 @@ export default class GthFileSystemToolkit extends BaseToolkit {
                 }
             }
             if (!matchFound) {
-                throw new Error(`Could not find exact match for edit:\n${edit.oldText}`);
+                // No occurrence of the search text (exact or fuzzy) — thrown here and caught at the tool
+                // boundary (GS2-36) so it reaches the model as a recoverable errored result naming the
+                // path, not a fatal abort. Action-oriented recovery hint (EXT-34 hermes style): re-read to
+                // get the exact current text, or fall back to a whole-file write_file.
+                throw new Error('no occurrence of the search text was found, so the file was NOT modified. Re-read the ' +
+                    'file to get its exact current text (whitespace and indentation must match), then retry ' +
+                    'the edit, or use write_file to replace the whole file.\n' +
+                    edit.oldText);
             }
+            // Fuzzy (trim-based line) match applied: flag it so the model knows the edit
+            // landed on a near-match, not an exact one.
+            summaries.push(`edit ${editIndex}: applied via fuzzy line-match (no exact match)`);
         }
         const diff = this.createUnifiedDiff(content, modifiedContent, filePath);
         let numBackticks = 3;
@@ -325,7 +412,9 @@ export default class GthFileSystemToolkit extends BaseToolkit {
         if (!dryRun) {
             await fs.writeFile(filePath, modifiedContent, 'utf-8');
         }
-        return formattedDiff;
+        // Per-edit machine-readable summary, prepended so the diff block stays intact.
+        const summaryBlock = summaries.length > 0 ? `${summaries.join('\n')}\n\n` : '';
+        return summaryBlock + formattedDiff;
     }
     formatSize(bytes) {
         const units = ['B', 'KB', 'MB', 'GB', 'TB'];
@@ -349,6 +438,7 @@ export default class GthFileSystemToolkit extends BaseToolkit {
             let chunk = Buffer.alloc(CHUNK_SIZE);
             let linesFound = 0;
             let remainingText = '';
+            let firstChunk = true;
             while (position > 0 && linesFound < numLines) {
                 const size = Math.min(CHUNK_SIZE, position);
                 position -= size;
@@ -357,7 +447,17 @@ export default class GthFileSystemToolkit extends BaseToolkit {
                     break;
                 const readData = chunk.slice(0, bytesRead).toString('utf-8');
                 const chunkText = readData + remainingText;
-                const chunkLines = this.normalizeLineEndings(chunkText).split('\n');
+                const normalizedChunk = this.normalizeLineEndings(chunkText);
+                const chunkLines = normalizedChunk.split('\n');
+                // We read backward from EOF, so the file's terminating newline (if any) is only
+                // ever in this first chunk. Its split yields a phantom trailing empty element that
+                // must not be counted as the last line. Drop exactly one here so tail counting
+                // matches head/full reads; a file without a trailing newline is untouched and a
+                // genuine blank last line ("...\n\n") is preserved (only one element removed).
+                if (firstChunk && normalizedChunk.endsWith('\n')) {
+                    chunkLines.pop();
+                }
+                firstChunk = false;
                 if (position > 0) {
                     remainingText = chunkLines[0];
                     chunkLines.shift();
@@ -406,12 +506,150 @@ export default class GthFileSystemToolkit extends BaseToolkit {
             await fileHandle.close();
         }
     }
+    /**
+     * Returns the first `head` lines and the last `tail` lines of a file, separated by a
+     * `... [N lines skipped] ...` marker. When the two windows cover or overlap the whole
+     * file (`head + tail >= total`) the entire file is returned unchanged (no marker, no
+     * duplicated lines).
+     */
+    async headAndTailFile(filePath, head, tail) {
+        const content = await fs.readFile(filePath, 'utf-8');
+        const normalized = this.normalizeLineEndings(content);
+        const lines = normalized.split('\n');
+        // A terminating newline yields a phantom trailing empty element that would be
+        // miscounted as a real line (inflating `total`, so the true last line gets pushed
+        // into the "skipped" gap and the tail comes back empty). Drop exactly one when the
+        // file ends in a newline so counting/slicing matches head/full reads. Files without a
+        // trailing newline are untouched, and a genuine blank last line ("...\n\n") is
+        // preserved because only a single element is removed.
+        if (normalized.endsWith('\n')) {
+            lines.pop();
+        }
+        const total = lines.length;
+        if (head + tail >= total) {
+            return content;
+        }
+        const skipped = total - head - tail;
+        const headContent = lines.slice(0, head).join('\n');
+        const tailContent = lines.slice(total - tail).join('\n');
+        return headContent + '\n... [' + skipped + ' lines skipped] ...\n' + tailContent;
+    }
+    /**
+     * Return the file's lines from the 1-based `offset` to EOF (GS2-39 paging). Deliberately does
+     * NOT apply `limit` here — the caller hands the result to capReadContent with maxLines = limit so
+     * that a limit-bounded read is *observable* to the envelope (it can then tell "more file remains
+     * past this window" from "reached EOF" and emit the correct resume notice). Pre-slicing to
+     * exactly `limit` lines here would hide that signal and silently drop the continuation.
+     *
+     * Mirrors headAndTailFile's trailing-newline handling so line numbering matches head/tail/full
+     * reads: a terminating newline yields a phantom trailing empty element that must not be counted
+     * as a real line. Clamps rather than throwing: an offset past EOF returns a short recoverable note
+     * (not an empty string, which is indistinguishable from an empty file).
+     */
+    async windowFile(filePath, offset) {
+        const content = await fs.readFile(filePath, 'utf-8');
+        const normalized = this.normalizeLineEndings(content);
+        const lines = normalized.split('\n');
+        if (normalized.endsWith('\n')) {
+            lines.pop();
+        }
+        const total = lines.length;
+        if (total === 0) {
+            return '';
+        }
+        const start = offset - 1; // offset is >= 1 (clamped by the caller)
+        if (start >= total) {
+            return `[read_file: offset ${offset} is past end of file (${total} lines total)]`;
+        }
+        return lines.slice(start).join('\n');
+    }
+    /**
+     * Apply the read safety envelope (GS2-39) to already-selected file content:
+     *  - any single line longer than MAX_LINE_LENGTH is truncated with LINE_TRUNCATED_SUFFIX;
+     *  - emission stops once `maxLines` lines OR MAX_READ_BYTES bytes have been produced.
+     *
+     * When nothing exceeds the caps the content is returned verbatim (byte-identical), so normal
+     * files behave exactly as before — the change only bites on pathological / huge files.
+     *
+     * Three truncation signals are kept deliberately separate:
+     *  - a per-line cut is marked only by the inline LINE_TRUNCATED_SUFFIX (no global notice);
+     *  - the BYTE cap always appends the global "output truncated" notice, because it is the hard
+     *    safety envelope regardless of who asked for the read;
+     *  - the LINE cap appends the global notice only when `lineCapIsHard` is true — i.e. `maxLines`
+     *    is the hard MAX_READ_LINES envelope (a defaulted or clamped-down window, or the whole-file
+     *    read), NOT a deliberate small explicit `limit`. This distinguishes a *capped continuation*
+     *    (notify so the model can page) from a *satisfied explicit window* (stay quiet).
+     *
+     * `startLine` is the 1-based file line of the first line in `content`; it is used only to put a
+     * concrete resume `offset` in the global notice. Pass `undefined` (head/tail paths, where the
+     * first emitted line is not line `startLine` of the file) to emit a generic notice instead.
+     */
+    capReadContent(content, maxLines, startLine, lineCapIsHard) {
+        const lines = content.split('\n');
+        const withinBytes = Buffer.byteLength(content, 'utf-8') <= MAX_READ_BYTES;
+        const withinLines = lines.length <= maxLines;
+        const noLongLine = lines.every((line) => line.length <= MAX_LINE_LENGTH);
+        if (withinBytes && withinLines && noLongLine) {
+            return content;
+        }
+        const out = [];
+        let bytes = 0;
+        let stoppedByLine = false;
+        let stoppedByByte = false;
+        for (const rawLine of lines) {
+            if (out.length >= maxLines) {
+                stoppedByLine = true;
+                break;
+            }
+            const line = rawLine.length > MAX_LINE_LENGTH
+                ? rawLine.slice(0, MAX_LINE_LENGTH) + LINE_TRUNCATED_SUFFIX
+                : rawLine;
+            // +1 accounts for the '\n' that re-joins this line to the previous one. Always emit at
+            // least one (already per-line-truncated) line so the result is never empty.
+            const size = Buffer.byteLength(line, 'utf-8') + (out.length > 0 ? 1 : 0);
+            if (out.length > 0 && bytes + size > MAX_READ_BYTES) {
+                stoppedByByte = true;
+                break;
+            }
+            out.push(line);
+            bytes += size;
+        }
+        let result = out.join('\n');
+        // The byte cap is a hard envelope and always warrants a notice; the line cap warrants one only
+        // when it represents the hard MAX_READ_LINES envelope, not a deliberate explicit `limit`.
+        if (stoppedByByte || (stoppedByLine && lineCapIsHard)) {
+            const nextOffset = startLine !== undefined ? startLine + out.length : undefined;
+            const resume = nextOffset !== undefined
+                ? `resume with offset:${nextOffset} (and an optional limit)`
+                : 'use offset/limit to page through the rest';
+            result += `\n... [read_file: output truncated at the ${MAX_READ_LINES}-line / ${MAX_READ_BYTES / 1024} KB read cap — ${resume}] ...`;
+        }
+        return result;
+    }
+    /**
+     * GS2-36 — turn a fatal tool throw into a recoverable, action-oriented errored result.
+     *
+     * A filesystem tool that throws (a denied/symlinked-out path from validatePath, a missing file,
+     * EISDIR, permission-denied, a directory-not-empty refusal, …) otherwise propagates to
+     * GthAgentRunner as a fatal `Stream processing failed` and crashes the whole turn. The house
+     * convention (AGENTS.md: a tool result must never abort a run; the write_file precedent in
+     * `5892801a`) is to return the failure to the model as a plain string it can act on. This wraps
+     * that string in a uniform `Error <action>: <message>` shape — the underlying fs/validation
+     * message (ENOENT / EISDIR / EACCES / "Access denied - …") is itself the actionable detail, and
+     * the deliberately-thrown logical messages (edit_file no-match/ambiguous, "Directory not empty",
+     * "Cannot delete protected directory") are already phrased as recovery hints. EXT-14 containment
+     * is preserved everywhere: validatePath runs first and throws on a symlink-out BEFORE any fs
+     * mutation, so the mutation never happens — the denial is merely surfaced as a result here.
+     */
+    recoverableError(action, error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return `Error ${action}: ${message}`;
+    }
     createReadBinaryTool() {
         return createGthTool(async (args) => {
             if (!this.binaryFormats || !Array.isArray(this.binaryFormats)) {
                 return 'Binary formats are not configured. Add binaryFormats to your config to enable this feature.';
             }
-            displayInfo(`\n📁 Reading binary file: ${args.path}\n`);
             let validPath;
             try {
                 validPath = await this.validatePath(args.path);
@@ -468,35 +706,97 @@ export default class GthFileSystemToolkit extends BaseToolkit {
     createTools() {
         const tools = [
             createGthTool(async (args) => {
-                displayInfo(`\n📁 Reading file: ${args.path}\n`);
-                const validPath = await this.validatePath(args.path);
-                if (args.head && args.tail) {
-                    throw new Error('Cannot specify both head and tail parameters simultaneously');
+                // TUI-C32 residual b — the legacy `📁 Reading file: …` notice is dropped: the surface-
+                // agnostic tool-call block (`✓ 📁 read_file(path=…)`, TUI-C30) now announces the op once
+                // on both surfaces, so the old notice was a DL-10 double announcement.
+                const hasWindow = args.offset !== undefined || args.limit !== undefined;
+                const hasHeadTail = Boolean(args.head) || Boolean(args.tail);
+                // Argument guard first (pure, no filesystem access): the line window (offset/limit) and
+                // head/tail are two different slice mechanisms, so combining them is ambiguous. Return a
+                // recoverable string the model can act on rather than throwing — a thrown tool result
+                // aborts the whole agent run (the GS2-36 anti-pattern).
+                if (hasWindow && hasHeadTail) {
+                    return ('read_file: pass a line window (offset/limit) OR head/tail, not both. ' +
+                        'Use offset/limit to read an arbitrary range (offset = 1-based first line, ' +
+                        'limit = number of lines); use head/tail for the first/last N lines.');
                 }
-                if (args.tail) {
-                    return await this.tailFile(validPath, args.tail);
+                // GS2-36: a missing file, a denied / symlinked-out path (validatePath throws before any
+                // read), or a read failure (EISDIR, EACCES) becomes a recoverable errored result the
+                // model can act on, instead of a fatal `Stream processing failed` that aborts the run.
+                try {
+                    const validPath = await this.validatePath(args.path);
+                    // Line window (offset/limit). offset defaults to 1; limit defaults to and is hard-capped
+                    // at MAX_READ_LINES. windowFile returns from offset to EOF and capReadContent (maxLines =
+                    // limit) does the slicing, so a limit-bounded read that leaves more file behind is
+                    // *observable* and gets a resume notice. That notice fires only when the limit is the
+                    // hard envelope — defaulted, or an explicit limit clamped down to MAX_READ_LINES — so a
+                    // deliberately small explicit window (fully satisfied) stays quiet.
+                    if (hasWindow) {
+                        const offset = args.offset !== undefined ? Math.max(1, Math.trunc(args.offset)) : 1;
+                        const limitWasDefaulted = args.limit === undefined;
+                        const limitWasClamped = args.limit !== undefined && Math.trunc(args.limit) > MAX_READ_LINES;
+                        const limit = limitWasDefaulted
+                            ? MAX_READ_LINES
+                            : Math.min(Math.max(1, Math.trunc(args.limit)), MAX_READ_LINES);
+                        const lineCapIsHard = limitWasDefaulted || limitWasClamped;
+                        const windowed = await this.windowFile(validPath, offset);
+                        return this.capReadContent(windowed, limit, offset, lineCapIsHard);
+                    }
+                    // head/tail paths respect the explicit line count the model asked for (maxLines =
+                    // Infinity, so the line cap never fires — lineCapIsHard is moot), but still get the
+                    // per-line and byte safety envelope — e.g. a `tail 1` that returns one multi-MB minified
+                    // line is still truncated. No resume offset is emitted for these paths because the first
+                    // emitted line is not line 1 of the file.
+                    if (args.head && args.tail) {
+                        return this.capReadContent(await this.headAndTailFile(validPath, args.head, args.tail), Number.POSITIVE_INFINITY, undefined, false);
+                    }
+                    if (args.tail) {
+                        return this.capReadContent(await this.tailFile(validPath, args.tail), Number.POSITIVE_INFINITY, undefined, false);
+                    }
+                    if (args.head) {
+                        return this.capReadContent(await this.headFile(validPath, args.head), Number.POSITIVE_INFINITY, undefined, false);
+                    }
+                    // Default whole-file read: capped at MAX_READ_LINES / MAX_READ_BYTES with per-line
+                    // truncation (the line cap here IS the hard envelope). Files under the caps come back
+                    // byte-identical to the old uncapped read.
+                    return this.capReadContent(await fs.readFile(validPath, 'utf-8'), MAX_READ_LINES, 1, true);
                 }
-                if (args.head) {
-                    return await this.headFile(validPath, args.head);
+                catch (error) {
+                    return this.recoverableError(`reading file ${args.path}`, error);
                 }
-                return await fs.readFile(validPath, 'utf-8');
             }, {
                 name: 'read_file',
                 description: 'Read the complete contents of a file from the file system. ' +
                     'Handles various text encodings and provides detailed error messages ' +
                     'if the file cannot be read. Use this tool when you need to examine ' +
-                    "the contents of a single file. Use the 'head' parameter to read only " +
-                    "the first N lines of a file, or the 'tail' parameter to read only " +
-                    'the last N lines of a file. Only works within allowed directories.',
+                    'the contents of a single file. ' +
+                    `Large reads are capped for safety: at most ${MAX_READ_LINES} lines or ` +
+                    `${MAX_READ_BYTES / 1024} KB are returned, and any line longer than ${MAX_LINE_LENGTH} ` +
+                    'characters is truncated with a `... (line truncated to N chars)` marker; when a read ' +
+                    'is capped a `... [read_file: output truncated ...] ...` notice is appended. ' +
+                    'To read past the cap or fetch an arbitrary range, use `offset` (1-based first line) ' +
+                    'and `limit` (number of lines). ' +
+                    "Alternatively use the 'head' parameter to read only the first N lines of a file, or " +
+                    "the 'tail' parameter to read only the last N lines; 'head' and 'tail' may be combined " +
+                    'to get the first N lines, a `... [N lines skipped] ...` marker, and the last M lines. ' +
+                    'The offset/limit line window and head/tail are mutually exclusive — pass one or the ' +
+                    'other, not both. Only works within allowed directories.',
                 schema: ReadFileArgsSchema,
             }, 'read'),
             createGthTool(async (args) => {
-                displayInfo(`\n📁 Reading ${args.paths.length} files\n`);
                 const results = await Promise.all(args.paths.map(async (filePath) => {
                     try {
                         const validPath = await this.validatePath(filePath);
                         const content = await fs.readFile(validPath, 'utf-8');
-                        return `${filePath}:\n${content}\n`;
+                        // Apply the same whole-file read safety envelope as read_file's default path
+                        // (GS2-39/GS2-52): a single oversized file — or a one-line minified bundle — in a
+                        // multi-file read must not blow the context window. maxLines = MAX_READ_LINES,
+                        // startLine = 1, lineCapIsHard = true mirror read_file's whole-file read, so a
+                        // capped file carries the "resume with offset:N" notice; the model pages the rest
+                        // with read_file on that path. Sub-cap files come back byte-identical (verbatim
+                        // fast-path). There is no offset/limit here on purpose — read_file is the pager.
+                        const capped = this.capReadContent(content, MAX_READ_LINES, 1, true);
+                        return `${filePath}:\n${capped}\n`;
                     }
                     catch (error) {
                         const errorMessage = error instanceof Error ? error.message : String(error);
@@ -510,25 +810,61 @@ export default class GthFileSystemToolkit extends BaseToolkit {
                     'efficient than reading files one by one when you need to analyze ' +
                     "or compare multiple files. Each file's content is returned with its " +
                     "path as a reference. Failed reads for individual files won't stop " +
-                    'the entire operation. Only works within allowed directories.',
+                    'the entire operation. ' +
+                    `Each file is subject to the same per-file read cap as read_file: at most ${MAX_READ_LINES} ` +
+                    `lines or ${MAX_READ_BYTES / 1024} KB are returned and any line longer than ` +
+                    `${MAX_LINE_LENGTH} characters is truncated; when a file is capped a ` +
+                    '`... [read_file: output truncated ...] ...` notice is appended — page past it by ' +
+                    'reading that file individually with read_file (offset/limit). ' +
+                    'Only works within allowed directories.',
                 schema: ReadMultipleFilesArgsSchema,
             }, 'read'),
             createGthTool(async (args) => {
-                displayInfo(`\n📁 Writing file: ${args.path}\n`);
-                const validPath = await this.validatePath(args.path);
-                await fs.writeFile(validPath, args.content, 'utf-8');
-                return `Successfully wrote to ${args.path}`;
+                // TUI-C32 residual b — legacy `📁 Writing file: …` notice dropped (see read_file above);
+                // the TUI-C30 tool-call block announces the write once on both surfaces.
+                try {
+                    const validPath = await this.validatePath(args.path);
+                    // Create any missing parent directories (mkdir -p) so a write into a
+                    // not-yet-created subdirectory succeeds instead of throwing ENOENT. The
+                    // model expects the near-universal agent-tool `mkdir -p` semantics and
+                    // routinely writes a new file before creating its dir. validatePath has
+                    // already confirmed the nearest existing ancestor is inside the sandbox,
+                    // so the new directories are created within an allowed root.
+                    await fs.mkdir(path.dirname(validPath), { recursive: true });
+                    await fs.writeFile(validPath, args.content, 'utf-8');
+                    return `Successfully wrote to ${args.path}`;
+                }
+                catch (error) {
+                    // Surface the failure to the model as a recoverable tool result rather
+                    // than throwing, which would abort the entire agent run (GS2-36). The
+                    // model can read the message and adjust (e.g. the path is a directory,
+                    // or is denied by the sandbox) instead of the session dying.
+                    const message = error instanceof Error ? error.message : String(error);
+                    return `Error writing file ${args.path}: ${message}`;
+                }
             }, {
                 name: 'write_file',
                 description: 'Create a new file or completely overwrite an existing file with new content. ' +
+                    'Missing parent directories are created automatically. ' +
                     'Use with caution as it will overwrite existing files without warning. ' +
                     'Handles text content with proper encoding. Only works within allowed directories.',
                 schema: WriteFileArgsSchema,
             }, 'write'),
             createGthTool(async (args) => {
-                displayInfo(`\n📁 Editing file: ${args.path}\n`);
-                const validPath = await this.validatePath(args.path);
-                return await this.applyFileEdits(validPath, args.edits, args.dryRun);
+                // TUI-C32 residual b — legacy `📁 Editing file: …` notice dropped (see read_file above);
+                // the TUI-C30 tool-call block announces the edit once on both surfaces.
+                // GS2-36: a no-match / ambiguous edit, a missing file, a denied or symlinked-out path
+                // (validatePath throws BEFORE applyFileEdits mutates anything — EXT-14 containment
+                // preserved), or a write failure becomes a recoverable errored result the model can act
+                // on, instead of a fatal throw that aborts the whole run. applyFileEdits' no-match /
+                // ambiguous messages are already phrased as action-oriented recovery hints.
+                try {
+                    const validPath = await this.validatePath(args.path);
+                    return await this.applyFileEdits(validPath, args.edits, args.dryRun);
+                }
+                catch (error) {
+                    return this.recoverableError(`editing file ${args.path}`, error);
+                }
             }, {
                 name: 'edit_file',
                 description: 'Make line-based edits to a text file. Each edit replaces exact line sequences ' +
@@ -542,10 +878,16 @@ export default class GthFileSystemToolkit extends BaseToolkit {
                 schema: EditFileArgsSchema,
             }, 'write'),
             createGthTool(async (args) => {
-                displayInfo(`\n📁 Creating directory: ${args.path}\n`);
-                const validPath = await this.validatePath(args.path);
-                await fs.mkdir(validPath, { recursive: true });
-                return `Successfully created directory ${args.path}`;
+                // GS2-36: a denied / symlinked-out path or an mkdir failure (e.g. a file already exists at
+                // the path) becomes a recoverable errored result rather than a fatal run abort.
+                try {
+                    const validPath = await this.validatePath(args.path);
+                    await fs.mkdir(validPath, { recursive: true });
+                    return `Successfully created directory ${args.path}`;
+                }
+                catch (error) {
+                    return this.recoverableError(`creating directory ${args.path}`, error);
+                }
             }, {
                 name: 'create_directory',
                 description: 'Create a new directory or ensure a directory exists. Can create multiple ' +
@@ -555,17 +897,23 @@ export default class GthFileSystemToolkit extends BaseToolkit {
                 schema: CreateDirectoryArgsSchema,
             }, 'write'),
             createGthTool(async (args) => {
-                displayInfo(`\n📁 Listing directory: ${args.path}\n`);
-                const validPath = await this.validatePath(args.path);
-                const entries = await fs.readdir(validPath, { withFileTypes: true });
-                const aiignoreConfig = this.aiignoreConfig;
-                const filteredEntries = entries.filter((entry) => {
-                    const fullPath = path.join(validPath, entry.name);
-                    return !shouldIgnoreFile(fullPath, getCurrentWorkDir(), aiignoreConfig?.patterns, aiignoreConfig?.enabled);
-                });
-                return filteredEntries
-                    .map((entry) => `${entry.isDirectory() ? '[DIR]' : '[FILE]'} ${entry.name}`)
-                    .join('\n');
+                // GS2-36: a missing directory, a denied / symlinked-out path, or a not-a-directory
+                // (ENOTDIR) error becomes a recoverable errored result rather than a fatal run abort.
+                try {
+                    const validPath = await this.validatePath(args.path);
+                    const entries = await fs.readdir(validPath, { withFileTypes: true });
+                    const aiignoreConfig = this.aiignoreConfig;
+                    const filteredEntries = entries.filter((entry) => {
+                        const fullPath = path.join(validPath, entry.name);
+                        return !shouldIgnoreFile(fullPath, getCurrentWorkDir(), aiignoreConfig?.patterns, aiignoreConfig?.enabled);
+                    });
+                    return filteredEntries
+                        .map((entry) => `${entry.isDirectory() ? '[DIR]' : '[FILE]'} ${entry.name}`)
+                        .join('\n');
+                }
+                catch (error) {
+                    return this.recoverableError(`listing directory ${args.path}`, error);
+                }
             }, {
                 name: 'list_directory',
                 description: 'Get a detailed listing of all files and directories in a specified path. ' +
@@ -575,9 +923,18 @@ export default class GthFileSystemToolkit extends BaseToolkit {
                 schema: ListDirectoryArgsSchema,
             }, 'read'),
             createGthTool(async (args) => {
-                displayInfo(`\n📁 Listing directory with sizes: ${args.path}\n`);
-                const validPath = await this.validatePath(args.path);
-                const entries = await fs.readdir(validPath, { withFileTypes: true });
+                // GS2-36: a missing directory or denied path becomes a recoverable errored result rather
+                // than a fatal run abort. Only validatePath + readdir can throw fatally here (the per-entry
+                // stat below already has its own try/catch), so guard just those.
+                let validPath;
+                let entries;
+                try {
+                    validPath = await this.validatePath(args.path);
+                    entries = (await fs.readdir(validPath, { withFileTypes: true }));
+                }
+                catch (error) {
+                    return this.recoverableError(`listing directory ${args.path}`, error);
+                }
                 const aiignoreConfig = this.aiignoreConfig;
                 const filteredEntries = entries.filter((entry) => {
                     const fullPath = path.join(validPath, entry.name);
@@ -628,50 +985,69 @@ export default class GthFileSystemToolkit extends BaseToolkit {
                 schema: ListDirectoryWithSizesArgsSchema,
             }, 'read'),
             createGthTool(async (args) => {
-                displayInfo(`\n📁 Building directory tree: ${args.path}\n`);
                 const buildTree = async (currentPath) => {
                     const validPath = await this.validatePath(currentPath);
                     const entries = await fs.readdir(validPath, { withFileTypes: true });
                     const result = [];
                     const aiignoreConfig = this.aiignoreConfig;
                     for (const entry of entries) {
+                        // `.aiignore` is a privacy boundary, not an annotation: an ignored entry is dropped
+                        // outright, exactly as list_directory / list_directory_with_sizes / search_files drop
+                        // it. Emitting the entry with a marker still hands the model — and therefore the
+                        // provider — the very filename `.aiignore` exists to hide, and a name is often the
+                        // whole payload. Tested first so an ignored directory is neither named nor descended.
+                        const fullPath = path.join(currentPath, entry.name);
+                        if (shouldIgnoreFile(fullPath, getCurrentWorkDir(), aiignoreConfig?.patterns, aiignoreConfig?.enabled)) {
+                            continue;
+                        }
                         const entryData = {
                             name: entry.name,
                             type: entry.isDirectory() ? 'directory' : 'file',
                         };
+                        // Noise directories are listed but never walked. `ignored` is what tells the model
+                        // why such a directory carries no `children` — without it an unwalked directory reads
+                        // as an empty one — and that is the flag's only remaining purpose.
                         if (IGNORED_DIRS.indexOf(entry.name) >= 0) {
                             entryData.ignored = true;
                         }
-                        // Check if file should be ignored by aiignore
-                        const fullPath = path.join(currentPath, entry.name);
-                        const shouldIgnore = shouldIgnoreFile(fullPath, getCurrentWorkDir(), aiignoreConfig?.patterns, aiignoreConfig?.enabled);
-                        if (shouldIgnore) {
-                            entryData.ignored = true;
-                        }
                         if (entry.isDirectory() && !entryData.ignored) {
-                            const subPath = path.join(currentPath, entry.name);
-                            entryData.children = await buildTree(subPath);
+                            entryData.children = await buildTree(fullPath);
                         }
                         result.push(entryData);
                     }
                     return result;
                 };
-                const treeData = await buildTree(args.path);
-                return JSON.stringify(treeData, null, 2);
+                // GS2-36: a missing directory, denied path, or a symlink-out encountered mid-walk
+                // (buildTree calls validatePath on each level) becomes a recoverable errored result
+                // rather than a fatal run abort.
+                try {
+                    const treeData = await buildTree(args.path);
+                    return JSON.stringify(treeData, null, 2);
+                }
+                catch (error) {
+                    return this.recoverableError(`building directory tree for ${args.path}`, error);
+                }
             }, {
                 name: 'directory_tree',
                 description: 'Get a recursive tree view of files and directories as a JSON structure. ' +
                     "Each entry includes 'name', 'type' (file/directory), and 'children' for directories. " +
-                    'Files have no children array, while directories always have a children array (which may be empty). ' +
+                    "Files have no children array; a directory has one (possibly empty) unless it carries 'ignored': true, " +
+                    'which means the directory was listed but not walked, so its contents are unknown rather than absent. ' +
                     'The output is formatted with 2-space indentation for readability. Only works within allowed directories.',
                 schema: DirectoryTreeArgsSchema,
             }, 'read'),
             createGthTool(async (args) => {
-                displayInfo(`\n📁 Moving ${args.source} to ${args.destination}\n`);
-                const validSourcePath = await this.validatePath(args.source);
-                const validDestPath = await this.validatePath(args.destination);
-                await fs.rename(validSourcePath, validDestPath);
-                return `Successfully moved ${args.source} to ${args.destination}`;
+                // GS2-36: a missing source, an existing destination, or a denied / symlinked-out path
+                // becomes a recoverable errored result rather than a fatal run abort.
+                try {
+                    const validSourcePath = await this.validatePath(args.source);
+                    const validDestPath = await this.validatePath(args.destination);
+                    await fs.rename(validSourcePath, validDestPath);
+                    return `Successfully moved ${args.source} to ${args.destination}`;
+                }
+                catch (error) {
+                    return this.recoverableError(`moving ${args.source} to ${args.destination}`, error);
+                }
             }, {
                 name: 'move_file',
                 description: 'Move or rename files and directories. Can move files between directories ' +
@@ -681,10 +1057,16 @@ export default class GthFileSystemToolkit extends BaseToolkit {
                 schema: MoveFileArgsSchema,
             }, 'write'),
             createGthTool(async (args) => {
-                displayInfo(`\n📁 Searching for '${args.pattern}' in ${args.path}\n`);
-                const validPath = await this.validatePath(args.path);
-                const results = await this.searchFiles(validPath, args.pattern, args.excludePatterns);
-                return results.length > 0 ? results.join('\n') : 'No matches found';
+                // GS2-36: a missing or denied root path becomes a recoverable errored result rather than a
+                // fatal run abort (searchFiles already swallows per-entry errors internally).
+                try {
+                    const validPath = await this.validatePath(args.path);
+                    const results = await this.searchFiles(validPath, args.pattern, args.excludePatterns);
+                    return results.length > 0 ? results.join('\n') : 'No matches found';
+                }
+                catch (error) {
+                    return this.recoverableError(`searching ${args.path}`, error);
+                }
             }, {
                 name: 'search_files',
                 description: 'Recursively search for files and directories matching a pattern. ' +
@@ -695,12 +1077,18 @@ export default class GthFileSystemToolkit extends BaseToolkit {
                 schema: SearchFilesArgsSchema,
             }, 'read'),
             createGthTool(async (args) => {
-                displayInfo(`\n📁 Getting file info: ${args.path}\n`);
-                const validPath = await this.validatePath(args.path);
-                const info = await this.getFileStats(validPath);
-                return Object.entries(info)
-                    .map(([key, value]) => `${key}: ${value}`)
-                    .join('\n');
+                // GS2-36: a missing file or denied path becomes a recoverable errored result rather than a
+                // fatal run abort.
+                try {
+                    const validPath = await this.validatePath(args.path);
+                    const info = await this.getFileStats(validPath);
+                    return Object.entries(info)
+                        .map(([key, value]) => `${key}: ${value}`)
+                        .join('\n');
+                }
+                catch (error) {
+                    return this.recoverableError(`getting file info for ${args.path}`, error);
+                }
             }, {
                 name: 'get_file_info',
                 description: 'Retrieve detailed metadata about a file or directory. Returns comprehensive ' +
@@ -710,14 +1098,20 @@ export default class GthFileSystemToolkit extends BaseToolkit {
                 schema: GetFileInfoArgsSchema,
             }, 'read'),
             createGthTool(async (args) => {
-                displayInfo(`\n📁 Deleting file: ${args.path}\n`);
-                const validPath = await this.validatePath(args.path);
-                const stats = await fs.stat(validPath);
-                if (stats.isDirectory()) {
-                    throw new Error(`Cannot delete directory: ${args.path}. Use rmdir or a recursive delete tool for directories.`);
-                }
-                await fs.unlink(validPath);
-                return `Successfully deleted file: ${args.path}`;
+                // GS2-36: a missing file, a denied path, or the "this is a directory" refusal becomes a
+                // recoverable errored result the model can act on, rather than a fatal run abort.
+                try {
+                    const validPath = await this.validatePath(args.path);
+                    const stats = await fs.stat(validPath);
+                    if (stats.isDirectory()) {
+                        throw new Error(`Cannot delete directory: ${args.path}. Use rmdir or a recursive delete tool for directories.`);
+                    }
+                    await fs.unlink(validPath);
+                    return `Successfully deleted file: ${args.path}`;
+                }
+                catch (error) {
+                    return this.recoverableError(`deleting file ${args.path}`, error);
+                }
             }, {
                 name: 'delete_file',
                 description: 'Delete a file from the filesystem. This operation cannot be undone. ' +
@@ -726,28 +1120,35 @@ export default class GthFileSystemToolkit extends BaseToolkit {
                 schema: DeleteFileArgsSchema,
             }, 'write'),
             createGthTool(async (args) => {
-                displayInfo(`\n📁 Deleting directory: ${args.path}${args.recursive ? ' (recursive)' : ''}\n`);
-                const validPath = await this.validatePath(args.path);
-                // Check if this is a protected directory
-                if (this.isProtectedDirectory(validPath)) {
-                    throw new Error(`Cannot delete protected directory: ${args.path}. This is one of the allowed root directories.`);
-                }
-                const stats = await fs.stat(validPath);
-                if (!stats.isDirectory()) {
-                    throw new Error(`Not a directory: ${args.path}. Use delete_file for files.`);
-                }
-                if (args.recursive) {
-                    await fs.rm(validPath, { recursive: true, force: true });
-                    return `Successfully deleted directory and all contents: ${args.path}`;
-                }
-                else {
-                    // For non-recursive delete, check if directory is empty
-                    const entries = await fs.readdir(validPath);
-                    if (entries.length > 0) {
-                        throw new Error(`Directory not empty: ${args.path}. Use recursive: true to delete non-empty directories.`);
+                // GS2-36: a missing directory, a denied path, the protected-root / not-a-directory /
+                // not-empty refusals all become recoverable errored results the model can act on, rather
+                // than a fatal run abort. Each refusal message is already an action-oriented hint.
+                try {
+                    const validPath = await this.validatePath(args.path);
+                    // Check if this is a protected directory
+                    if (this.isProtectedDirectory(validPath)) {
+                        throw new Error(`Cannot delete protected directory: ${args.path}. This is one of the allowed root directories.`);
                     }
-                    await fs.rmdir(validPath);
-                    return `Successfully deleted empty directory: ${args.path}`;
+                    const stats = await fs.stat(validPath);
+                    if (!stats.isDirectory()) {
+                        throw new Error(`Not a directory: ${args.path}. Use delete_file for files.`);
+                    }
+                    if (args.recursive) {
+                        await fs.rm(validPath, { recursive: true, force: true });
+                        return `Successfully deleted directory and all contents: ${args.path}`;
+                    }
+                    else {
+                        // For non-recursive delete, check if directory is empty
+                        const entries = await fs.readdir(validPath);
+                        if (entries.length > 0) {
+                            throw new Error(`Directory not empty: ${args.path}. Use recursive: true to delete non-empty directories.`);
+                        }
+                        await fs.rmdir(validPath);
+                        return `Successfully deleted empty directory: ${args.path}`;
+                    }
+                }
+                catch (error) {
+                    return this.recoverableError(`deleting directory ${args.path}`, error);
                 }
             }, {
                 name: 'delete_directory',