@ikarmic/forge-core 5.3.0 → 5.4.0

package/dist/tools/network-policy.d.ts

@@ -0,0 +1,5 @@
+import type { CommandSandbox } from '../types.js';
+/** A host pattern matches exactly, as `*.example.com` (a subdomain, not the apex), or as `*` (anything). */
+export declare function hostMatches(host: string, patterns: readonly string[]): boolean;
+/** Why a tool call may not go ahead under this sandbox, or undefined. */
+export declare function networkDenial(toolName: string, args: unknown, sandbox: CommandSandbox | undefined): string | undefined;

package/dist/tools/network-policy.js

@@ -0,0 +1,77 @@
+/**
+ * The command sandbox's network setting, applied to Forge's own network tools (F13). With the network off, `run_command` is
+ * cut off by the OS sandbox, but fetch_url, web_search, repo_clone, the browser and GitHub run in Forge's process: they are
+ * held to the sandbox's allowed hosts here, from one place in the agent loop, so a new network tool is covered by adding it to
+ * `networkTarget` and cannot forget the check. An allowed-hosts list cannot be enforced for shell commands (they are all or
+ * nothing), so it applies to these tools only.
+ */
+import net from 'node:net';
+import { parseRepoSpec } from './repo-clone.js';
+/** A host pattern matches exactly, as `*.example.com` (a subdomain, not the apex), or as `*` (anything). */
+export function hostMatches(host, patterns) {
+    const h = host.toLowerCase();
+    return patterns.some((raw) => {
+        const p = raw.trim().toLowerCase();
+        if (p === '*')
+            return true;
+        if (p.startsWith('*.'))
+            return h.endsWith(p.slice(1)) && h.length > p.length - 1;
+        return h === p;
+    });
+}
+function isLocal(host) {
+    const h = host.replace(/^\[|\]$/g, '').toLowerCase();
+    return h === 'localhost' || h.endsWith('.localhost') || h === '::1' || (net.isIPv4(h) && h.startsWith('127.'));
+}
+/** What a network tool is about to reach, or undefined for a tool or action that does not use the network. */
+function networkTarget(toolName, args) {
+    const a = (args && typeof args === 'object' ? args : {});
+    const url = (label) => {
+        try {
+            return { host: new URL(String(a.url)).hostname, label };
+        }
+        catch {
+            return { unreadable: 'The address could not be read' };
+        }
+    };
+    switch (toolName) {
+        case 'fetch_url':
+            return url('fetch a page');
+        case 'browser':
+            return a.action === 'open' ? url('open a page in the browser') : undefined;
+        case 'repo_clone':
+            try {
+                return { host: parseRepoSpec(String(a.repo ?? '')).host, label: 'download a repository' };
+            }
+            catch {
+                return { unreadable: 'The repository address could not be read' };
+            }
+        case 'web_search':
+            return { host: '*search*', label: 'search the web' };
+        case 'github_pr_read':
+        case 'github_pr_create':
+            return { host: 'api.github.com', label: 'use GitHub' };
+        default:
+            return undefined;
+    }
+}
+/** Why a tool call may not go ahead under this sandbox, or undefined. */
+export function networkDenial(toolName, args, sandbox) {
+    if (!sandbox || sandbox.network)
+        return undefined;
+    const target = networkTarget(toolName, args);
+    if (!target)
+        return undefined;
+    if ('unreadable' in target)
+        return `The command sandbox's network is off, and ${target.unreadable.toLowerCase()}, so it was not tried.`;
+    const allowed = sandbox.allowedHosts ?? [];
+    if (target.host === '*search*') {
+        // A search goes to whichever service is set up; only an "any host" entry opens it.
+        return hostMatches('x', allowed.filter((p) => p.trim() === '*'))
+            ? undefined
+            : "The command sandbox's network is off, so Forge may not search the web. Allow all hosts in the sandbox's allowed hosts, or turn the network on.";
+    }
+    if (isLocal(target.host) || hostMatches(target.host, allowed))
+        return undefined;
+    return `The command sandbox's network is off, so Forge may not ${target.label} at ${target.host}. Add the host to the sandbox's allowed hosts, or turn the network on.`;
+}

package/dist/tools/office-docs.d.ts

@@ -0,0 +1,6 @@
+export type OfficeKind = 'docx' | 'xlsx';
+export declare function officeKind(filePath: string): OfficeKind | undefined;
+/** The text of the wanted entries of a zip archive. Throws a sentence a person can act on. */
+export declare function readZip(buf: Buffer, want: (name: string) => boolean): Map<string, string>;
+export declare function renderDocx(buf: Buffer): string;
+export declare function renderXlsx(buf: Buffer): string;

package/dist/tools/office-docs.js

@@ -0,0 +1,393 @@
+/**
+ * Read Word (.docx) and Excel (.xlsx) files as text for `read_file` (G20). Both are zip archives of XML. The archive is read
+ * with Node's zlib only (no dependency in the extension bundle) and never extracted to disk; what an entry may expand to is
+ * capped, and the XML is scanned with `indexOf` rather than a parser or a regex that can backtrack, because the file is
+ * whatever a repository or an email attachment contains (RB-22, RB-82).
+ */
+import { inflateRawSync } from 'node:zlib';
+import { decodeEntities } from './html-to-markdown.js';
+export function officeKind(filePath) {
+    const m = /\.(docx|xlsx)$/i.exec(filePath);
+    return m ? m[1].toLowerCase() : undefined;
+}
+const MAX_ENTRY_BYTES = 20 * 1024 * 1024;
+const MAX_ENTRIES = 10_000;
+const MAX_SHEETS = 20;
+const MAX_ROWS = 2_000;
+const MAX_COLS = 100;
+/** The text of the wanted entries of a zip archive. Throws a sentence a person can act on. */
+export function readZip(buf, want) {
+    try {
+        return readZipUnchecked(buf, want);
+    }
+    catch (err) {
+        if (err instanceof RangeError)
+            throw new Error('The zip archive is damaged or cut short');
+        throw err;
+    }
+}
+function readZipUnchecked(buf, want) {
+    let eocd = -1;
+    for (let i = buf.length - 22; i >= Math.max(0, buf.length - 22 - 65_535); i--) {
+        if (buf.readUInt32LE(i) === 0x06054b50) {
+            eocd = i;
+            break;
+        }
+    }
+    if (eocd < 0)
+        throw new Error('This is not a zip archive. A password-protected Office file, or an older .doc or .xls saved with the wrong extension, looks like this');
+    const count = buf.readUInt16LE(eocd + 10);
+    const cdOffset = buf.readUInt32LE(eocd + 16);
+    if (count === 0xffff || cdOffset === 0xffffffff)
+        throw new Error('Zip64 archives are not supported');
+    if (count > MAX_ENTRIES)
+        throw new Error('The zip archive holds too many files');
+    const out = new Map();
+    let p = cdOffset;
+    for (let n = 0; n < count; n++) {
+        if (p + 46 > buf.length || buf.readUInt32LE(p) !== 0x02014b50)
+            throw new Error('The zip archive is damaged (its file list is unreadable)');
+        const flags = buf.readUInt16LE(p + 8);
+        const method = buf.readUInt16LE(p + 10);
+        const compressed = buf.readUInt32LE(p + 20);
+        const size = buf.readUInt32LE(p + 24);
+        const nameLen = buf.readUInt16LE(p + 28);
+        const extraLen = buf.readUInt16LE(p + 30);
+        const commentLen = buf.readUInt16LE(p + 32);
+        const local = buf.readUInt32LE(p + 42);
+        const name = buf.toString('utf8', p + 46, p + 46 + nameLen);
+        p += 46 + nameLen + extraLen + commentLen;
+        if (!want(name))
+            continue;
+        if (flags & 1)
+            throw new Error('The file is password-protected (encrypted)');
+        if (size > MAX_ENTRY_BYTES)
+            throw new Error(`${name} is too large to read (over ${MAX_ENTRY_BYTES / 1024 / 1024} MB expanded)`);
+        if (local + 30 > buf.length || buf.readUInt32LE(local) !== 0x04034b50)
+            throw new Error('The zip archive is damaged (a file header is missing)');
+        const start = local + 30 + buf.readUInt16LE(local + 26) + buf.readUInt16LE(local + 28);
+        const data = buf.subarray(start, start + compressed);
+        if (data.length !== compressed)
+            throw new Error('The zip archive is damaged (a file is cut short)');
+        let raw;
+        if (method === 0)
+            raw = data;
+        else if (method === 8) {
+            try {
+                raw = inflateRawSync(data, { maxOutputLength: MAX_ENTRY_BYTES });
+            }
+            catch (err) {
+                const code = err.code;
+                throw new Error(code === 'ERR_BUFFER_TOO_LARGE' ? `${name} is too large to read (over ${MAX_ENTRY_BYTES / 1024 / 1024} MB expanded)` : `${name} is damaged inside the zip archive`);
+            }
+        }
+        else
+            throw new Error(`${name} uses a zip compression method that is not supported`);
+        if (raw.length > MAX_ENTRY_BYTES)
+            throw new Error(`${name} is too large to read`);
+        out.set(name, raw.toString('utf8'));
+    }
+    return out;
+}
+/** Index of the next `<name` that is really that element (`<w:p>` or `<w:p ...>`, not `<w:pPr>`), or -1. */
+function findOpen(s, name, from) {
+    const open = `<${name}`;
+    let i = s.indexOf(open, from);
+    while (i !== -1) {
+        const c = s.charAt(i + open.length);
+        if (c === '>' || c === ' ' || c === '/' || c === '\n' || c === '\t' || c === '\r')
+            return i;
+        i = s.indexOf(open, i + 1);
+    }
+    return -1;
+}
+/** Every element with one of `names`, in document order, each consumed whole (a nested element of the same name stays inside). */
+function* elements(s, names) {
+    const next = {};
+    let from = 0;
+    for (;;) {
+        let best = '';
+        let bestPos = -1;
+        for (const nm of names) {
+            let pos = next[nm];
+            if (pos === undefined || (pos !== -1 && pos < from)) {
+                pos = findOpen(s, nm, from);
+                next[nm] = pos;
+            }
+            if (pos !== -1 && (bestPos === -1 || pos < bestPos)) {
+                bestPos = pos;
+                best = nm;
+            }
+        }
+        if (bestPos === -1)
+            return;
+        const gt = s.indexOf('>', bestPos);
+        if (gt === -1)
+            return;
+        const attrs = s.slice(bestPos + best.length + 1, gt);
+        if (s.charAt(gt - 1) === '/') {
+            yield { name: best, attrs, inner: '' };
+            from = gt + 1;
+            continue;
+        }
+        const close = `</${best}>`;
+        const end = s.indexOf(close, gt);
+        if (end === -1)
+            return;
+        yield { name: best, attrs, inner: s.slice(gt + 1, end) };
+        from = end + close.length;
+    }
+}
+function attrOf(attrs, name) {
+    const m = new RegExp(`(?:^|\\s)${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)')`).exec(attrs);
+    return m ? decodeEntities(m[1] ?? m[2] ?? '') : undefined;
+}
+/** The text of every `<tag>` in `s` (`<w:t>`, `<t>`): the characters between the tags, entities decoded. */
+function textsOf(s, tag) {
+    let out = '';
+    for (const el of elements(s, [tag]))
+        out += decodeEntities(el.inner);
+    return out;
+}
+function escapeCell(s) {
+    return s.replace(/\s+/g, ' ').trim().replace(/\|/g, '\\|');
+}
+function markdownTable(rows) {
+    const width = Math.max(...rows.map((r) => r.length));
+    const pad = (r) => [...r, ...Array(width - r.length).fill('')];
+    const line = (r) => `| ${pad(r).join(' | ')} |`;
+    return [line(rows[0]), line(Array(width).fill('---')), ...rows.slice(1).map(line)].join('\n');
+}
+// ---- Word ----
+const NOT_WORD = 'This is not a Word document (word/document.xml is missing). It may be an older .doc file saved with the wrong extension.';
+function docxParagraph(inner) {
+    const style = /<w:pStyle\s[^>]*w:val="([^"]*)"/.exec(inner)?.[1] ?? '';
+    let text = '';
+    const tokens = /<w:t(?:\s[^>]*)?>([^<]*)<\/w:t>|<w:tab\s*\/>|<w:br\b[^>]*>/g;
+    for (const m of inner.matchAll(tokens)) {
+        if (m[1] !== undefined)
+            text += decodeEntities(m[1]);
+        else
+            text += m[0].startsWith('<w:tab') ? '\t' : '\n';
+    }
+    const h = /^heading\s*(\d)$/i.exec(style);
+    const heading = h ? Number(h[1]) : /^title$/i.test(style) ? 1 : 0;
+    const numbered = inner.includes('<w:numPr') || /^list/i.test(style);
+    const level = Number(/<w:ilvl\s[^>]*w:val="(\d+)"/.exec(inner)?.[1] ?? 0);
+    return { text, heading, list: numbered && !heading ? Math.min(level, 8) : undefined };
+}
+function docxTable(inner) {
+    const rows = [];
+    for (const tr of elements(inner, ['w:tr'])) {
+        const cells = [];
+        for (const tc of elements(tr.inner, ['w:tc'])) {
+            const parts = [];
+            for (const p of elements(tc.inner, ['w:p']))
+                parts.push(docxParagraph(p.inner).text);
+            cells.push(escapeCell(parts.join(' ')));
+        }
+        if (cells.length > 0)
+            rows.push(cells);
+    }
+    return rows.length > 0 ? markdownTable(rows) : '';
+}
+export function renderDocx(buf) {
+    const xml = readZip(buf, (n) => n === 'word/document.xml').get('word/document.xml');
+    if (xml === undefined)
+        throw new Error(NOT_WORD);
+    const lines = [];
+    let inList = false;
+    const blank = () => {
+        if (lines.length > 0 && lines[lines.length - 1] !== '')
+            lines.push('');
+    };
+    for (const el of elements(xml, ['w:tbl', 'w:p'])) {
+        if (el.name === 'w:tbl') {
+            const table = docxTable(el.inner);
+            if (table) {
+                blank();
+                lines.push(table);
+                inList = false;
+            }
+            continue;
+        }
+        const para = docxParagraph(el.inner);
+        if (!para.text.trim())
+            continue;
+        if (para.list !== undefined) {
+            if (!inList)
+                blank();
+            lines.push(`${'  '.repeat(para.list)}- ${para.text.trim()}`);
+            inList = true;
+            continue;
+        }
+        inList = false;
+        blank();
+        lines.push(para.heading > 0 ? `${'#'.repeat(Math.min(para.heading, 6))} ${para.text.trim()}` : para.text);
+    }
+    const out = lines.join('\n').trim();
+    return out || '(the document has no text)';
+}
+// ---- Excel ----
+const NOT_EXCEL = 'This is not an Excel workbook (xl/workbook.xml is missing). It may be an older .xls file saved with the wrong extension.';
+function columnIndex(ref) {
+    let n = 0;
+    for (let i = 0; i < ref.length; i++) {
+        const c = ref.charCodeAt(i);
+        if (c < 65 || c > 90)
+            break;
+        n = n * 26 + (c - 64);
+    }
+    return n;
+}
+function columnLetters(index) {
+    let s = '';
+    for (let n = index; n > 0; n = Math.floor((n - 1) / 26))
+        s = String.fromCharCode(65 + ((n - 1) % 26)) + s;
+    return s;
+}
+/** Number formats that show a date or time: the built-in ids and any custom code that has date or time letters. */
+function isDateFormat(id, code) {
+    if ((id >= 14 && id <= 22) || (id >= 27 && id <= 36) || (id >= 45 && id <= 47) || (id >= 50 && id <= 58))
+        return true;
+    if (code === undefined)
+        return false;
+    const bare = code.replace(/"[^"]*"/g, '').replace(/\\./g, '').replace(/\[[^\]]*\]/g, '');
+    return /[dyhms]/i.test(bare);
+}
+function dateStyles(styles) {
+    const out = new Set();
+    if (!styles)
+        return out;
+    const codes = new Map();
+    for (const el of elements(styles, ['numFmt'])) {
+        const id = Number(attrOf(el.attrs, 'numFmtId'));
+        const code = attrOf(el.attrs, 'formatCode');
+        if (Number.isFinite(id) && code !== undefined)
+            codes.set(id, code);
+    }
+    for (const xfs of elements(styles, ['cellXfs'])) {
+        let index = 0;
+        for (const xf of elements(xfs.inner, ['xf'])) {
+            const id = Number(attrOf(xf.attrs, 'numFmtId') ?? 0);
+            if (isDateFormat(id, codes.get(id)))
+                out.add(index);
+            index++;
+        }
+        break;
+    }
+    return out;
+}
+function serialToText(serial, epoch1904) {
+    const days = serial - (epoch1904 ? 24107 : 25569);
+    const iso = new Date(Math.round(days * 86_400_000)).toISOString(); // 2023-03-15T12:00:00.000Z
+    const date = iso.slice(0, 10);
+    const time = iso.slice(11, 19);
+    if (serial < 1)
+        return time;
+    if (time === '00:00:00')
+        return date;
+    return `${date} ${time.endsWith(':00') ? time.slice(0, 5) : time}`;
+}
+function sharedStrings(xml) {
+    if (!xml)
+        return [];
+    const out = [];
+    for (const si of elements(xml, ['si'])) {
+        // Phonetic guides (<rPh>) repeat the text in another script: leave them out.
+        let inner = si.inner;
+        for (let a = inner.indexOf('<rPh'); a !== -1; a = inner.indexOf('<rPh')) {
+            const b = inner.indexOf('</rPh>', a);
+            inner = b === -1 ? inner.slice(0, a) : inner.slice(0, a) + inner.slice(b + 6);
+        }
+        out.push(textsOf(inner, 't'));
+    }
+    return out;
+}
+export function renderXlsx(buf) {
+    const files = readZip(buf, (n) => n === 'xl/workbook.xml' || n === 'xl/_rels/workbook.xml.rels' || n === 'xl/sharedStrings.xml' || n === 'xl/styles.xml' || /^xl\/worksheets\/[^/]+\.xml$/.test(n));
+    const workbook = files.get('xl/workbook.xml');
+    if (workbook === undefined)
+        throw new Error(NOT_EXCEL);
+    const epoch1904 = /<workbookPr\b[^>]*date1904="(?:1|true)"/.test(workbook);
+    const targets = new Map();
+    for (const rel of elements(files.get('xl/_rels/workbook.xml.rels') ?? '', ['Relationship'])) {
+        const id = attrOf(rel.attrs, 'Id');
+        const target = attrOf(rel.attrs, 'Target');
+        if (id && target)
+            targets.set(id, target.startsWith('/') ? target.slice(1) : `xl/${target.replace(/^\.\//, '')}`);
+    }
+    const strings = sharedStrings(files.get('xl/sharedStrings.xml'));
+    const dates = dateStyles(files.get('xl/styles.xml'));
+    const sections = [];
+    let shown = 0;
+    for (const sheet of elements(workbook, ['sheet'])) {
+        if (shown++ >= MAX_SHEETS) {
+            sections.push(`(more sheets not shown; ${MAX_SHEETS} at most)`);
+            break;
+        }
+        const name = attrOf(sheet.attrs, 'name') ?? 'Sheet';
+        const hidden = (attrOf(sheet.attrs, 'state') ?? 'visible') !== 'visible';
+        const heading = `## ${name}${hidden ? ' (hidden)' : ''}`;
+        const xml = files.get(targets.get(attrOf(sheet.attrs, 'r:id') ?? '') ?? '');
+        sections.push(`${heading}\n\n${xml === undefined ? '(this sheet could not be found in the file)' : renderSheet(xml, strings, dates, epoch1904)}`);
+    }
+    return sections.join('\n\n') || '(the workbook has no sheets)';
+}
+function renderSheet(xml, strings, dates, epoch1904) {
+    const rows = new Map();
+    let maxCol = 0;
+    let seq = 0;
+    let more = false;
+    for (const row of elements(xml, ['row'])) {
+        seq = Number(attrOf(row.attrs, 'r')) || seq + 1;
+        if (rows.size >= MAX_ROWS) {
+            more = true;
+            break;
+        }
+        const cells = new Map();
+        let nextCol = 0;
+        for (const c of elements(row.inner, ['c'])) {
+            const ref = attrOf(c.attrs, 'r') ?? '';
+            const col = ref ? columnIndex(ref) : nextCol + 1;
+            nextCol = col;
+            if (col < 1 || col > MAX_COLS)
+                continue;
+            const text = cellText(c, strings, dates, epoch1904);
+            if (text !== '') {
+                cells.set(col, escapeCell(text));
+                if (col > maxCol)
+                    maxCol = col;
+            }
+        }
+        if (cells.size > 0)
+            rows.set(seq, cells);
+    }
+    if (rows.size === 0)
+        return '(empty)';
+    const header = ['', ...Array.from({ length: maxCol }, (_, i) => columnLetters(i + 1))];
+    const body = [...rows.entries()].map(([r, cells]) => [String(r), ...Array.from({ length: maxCol }, (_, i) => cells.get(i + 1) ?? '')]);
+    const table = markdownTable([header, ...body]);
+    return more ? `${table}\n\n(more rows not shown; the first ${MAX_ROWS} rows with content are listed)` : table;
+}
+function cellText(c, strings, dates, epoch1904) {
+    const type = attrOf(c.attrs, 't') ?? 'n';
+    const v = textsOf(c.inner, 'v');
+    if (type === 'inlineStr')
+        return textsOf(c.inner, 't');
+    if (type === 's')
+        return strings[Number(v)] ?? '';
+    if (type === 'b')
+        return v === '1' ? 'TRUE' : v === '0' ? 'FALSE' : v;
+    if (v === '') {
+        const f = textsOf(c.inner, 'f');
+        return f ? `=${f}` : '';
+    }
+    if (type === 'n') {
+        const style = Number(attrOf(c.attrs, 's') ?? 0);
+        const n = Number(v);
+        if (dates.has(style) && Number.isFinite(n) && n >= 0 && n < 2_958_466)
+            return serialToText(n, epoch1904);
+    }
+    return v;
+}

package/dist/tools/permission-rules.js

@@ -118,12 +118,58 @@ export function splitShellCommands(command) {
         for (const inner of splitShellCommands(m[1] ?? m[2] ?? ''))
             extra.push(inner);
     }
-    if (/(^|[^>&0-9])>{1,2}(?!&)/.test(stripQuoted(command)))
+    if (writesFile(command))
         extra.push(`redirect: ${command.trim()}`);
-    return [...out, ...extra];
+    // A pipe into PowerShell's Out-Null only throws output away: it is not a command that needs its own rule (G21).
+    return [...out.filter((c) => !/^out-null$/i.test(c)), ...extra];
 }
-function stripQuoted(s) {
-    return s.replace(/"[^"]*"|'[^']*'/g, '""');
+/** Where output is thrown away, so redirecting to it writes nothing (G21). */
+const NULL_SINKS = /^(?:\/dev\/null|nul|\$null)$/i;
+/**
+ * Does an unquoted output redirect write somewhere real? `> file`, `>> file`, `2>file`, `&>file` and `>&file` do; a
+ * redirect to `/dev/null`, `nul` or `$null` and a copy of one stream onto another (`2>&1`, `>&2`) do not.
+ * The old test skipped any `>` after a digit or an ampersand, which let `2>out.txt` and `&>out.txt` write a file unseen.
+ */
+function writesFile(command) {
+    let quote = null;
+    for (let i = 0; i < command.length; i++) {
+        const c = command[i];
+        if (quote) {
+            if (c === quote)
+                quote = null;
+            continue;
+        }
+        if (c === '"' || c === "'") {
+            quote = c;
+            continue;
+        }
+        if (c !== '>')
+            continue;
+        let j = i + 1;
+        if (command[j] === '>')
+            j++; // >>
+        // >& : a copy of one stream onto another when a stream number or - follows; otherwise both streams go to the named file
+        if (command[j] === '&') {
+            const dup = /^&(?:\d+|-)(?![\w./\\-])/.exec(command.slice(j));
+            if (dup) {
+                i = j + dup[0].length - 1;
+                continue;
+            }
+            j++;
+        }
+        while (command[j] === ' ' || command[j] === '\t')
+            j++;
+        if (command[j] === '(')
+            return true; // >(...) process substitution
+        let k = j;
+        while (k < command.length && !/[\s;|&<>()]/.test(command[k]))
+            k++;
+        const target = command.slice(j, k).replace(/^["']|["']$/g, '');
+        if (!NULL_SINKS.test(target))
+            return true;
+        i = Math.max(i, k - 1);
+    }
+    return false;
 }
 /** `.env` and `.env.*` hold secrets; `.env.example` and `.env.sample` are documentation. */
 export function isSensitiveFile(relPath) {
@@ -170,10 +216,14 @@ export function permissionFor(toolName, args, cwd) {
     }
     if (EDIT_TOOLS.has(toolName))
         return { permission: 'edit', targets: [relTarget(a.path, cwd)] };
-    if (toolName === 'run_command')
+    // bg_start starts the same kind of thing as run_command, so a rule about commands covers it.
+    if (toolName === 'run_command' || toolName === 'bg_start')
         return { permission: 'bash', targets: splitShellCommands(typeof a.command === 'string' ? a.command : '') };
     if (toolName === 'fetch_url')
         return { permission: 'webfetch', targets: [typeof a.url === 'string' ? a.url : ''] };
+    // A clone reaches a host over the network, so a rule about fetching covers it.
+    if (toolName === 'repo_clone')
+        return { permission: 'webfetch', targets: [typeof a.repo === 'string' ? a.repo : ''] };
     if (toolName === 'web_search')
         return { permission: 'websearch', targets: [typeof a.query === 'string' ? a.query : ''] };
     if (toolName === 'sub_agent')

package/dist/tools/read-file.d.ts

@@ -11,6 +11,8 @@ export interface ReadFileResult {
     offset: number;
     content: string;
     truncated: boolean;
+    /** Where to carry on reading when the result stopped early (`offset` for the next call). */
+    nextOffset?: number;
     /** `AGENTS.md` files of the folders this file sits in, shown the first time a file there is read. */
     folderInstructions?: Array<{
         file: string;

package/dist/tools/read-file.js

@@ -1,10 +1,14 @@
 import { readFile } from 'node:fs/promises';
 import { z } from 'zod';
 import { isNotebookPath, parseNotebook, renderNotebook } from './notebook.js';
+import { officeKind, renderDocx, renderXlsx } from './office-docs.js';
 import { isPdf, MAX_ATTACHMENT_BYTES } from '../attachments.js';
 import { folderInstructionsFor } from '../steering/folder-instructions.js';
-import { resolveAndCheckPath, truncateByLines } from './shared.js';
+import { resolveReadPath } from './shared.js';
 import { decodeText } from './text-encoding.js';
+const MAX_LINE_CHARS = 2000;
+/** About 50 KB of text per call: enough to page through a file, small enough to leave room for the rest of the chat. */
+const MAX_READ_CHARS = 50_000;
 const params = z.object({
     path: z.string().describe('Path to the file to read, relative to the working directory or absolute.'),
     /** 1-based line number to start reading from. Omit to start at the beginning. */
@@ -14,10 +18,10 @@ const params = z.object({
 });
 export const readFileTool = {
     name: 'read_file',
-    description: 'Read the contents of a file. Returns text with line numbers; supports an optional offset and max_lines to page through large files. A Jupyter notebook (.ipynb) is shown as numbered cells with their outputs. A PDF is attached whole so you can read it (text, tables and figures). Other binary files are rejected.',
+    description: 'Read the contents of a file. Returns text with line numbers; supports an optional offset and max_lines to page through large files. A Jupyter notebook (.ipynb) is shown as numbered cells with their outputs. A Word document (.docx) is shown as text with its headings, lists and tables; an Excel workbook (.xlsx) as one table per sheet with column letters and row numbers. A PDF is attached whole so you can read it (text, tables and figures). Other binary files, including the older .doc and .xls, are rejected.',
     parameters: params,
     execute: async (args, ctx) => {
-        const resolved = resolveAndCheckPath(args.path, ctx);
+        const resolved = await resolveReadPath(args.path, ctx);
         let raw;
         try {
             raw = await readFile(resolved);
@@ -48,12 +52,25 @@ export const readFileTool = {
             }
             return { path: resolved, mime: 'application/pdf', bytes: raw.length, dataUrl: `data:application/pdf;base64,${raw.toString('base64')}` };
         }
-        // Reject obvious binary content.
-        const decoded = decodeText(raw);
-        if (decoded.encoding === 'utf8' && looksBinary(raw)) {
-            throw new Error(`Refusing to read binary file: ${args.path} (${raw.length} bytes)`);
+        let text;
+        const office = officeKind(resolved);
+        if (office) {
+            // A Word or Excel file is a zip of XML: show its text, then page through it like any other file (G20).
+            try {
+                text = office === 'docx' ? renderDocx(raw) : renderXlsx(raw);
+            }
+            catch (err) {
+                throw new Error(`Could not read ${args.path}: ${err.message}`);
+            }
+        }
+        else {
+            // Reject obvious binary content.
+            const decoded = decodeText(raw);
+            if (decoded.encoding === 'utf8' && looksBinary(raw)) {
+                throw new Error(`Refusing to read binary file: ${args.path} (${raw.length} bytes)`);
+            }
+            text = decoded.text;
         }
-        const text = decoded.text;
         const lines = text.split(/\r?\n/);
         // A file that ends with a newline splits into one extra, empty piece. It is not a line. Numbering it told the model a
         // 37-line file had 38 lines and that the last was empty (a live spec caught it), and made a file of exactly max_lines
@@ -64,14 +81,34 @@ export const readFileTool = {
         const maxLines = args.max_lines ?? 2000;
         const slice = lines.slice(offset - 1, offset - 1 + maxLines);
         const endIdx = offset - 1 + maxLines;
-        const truncated = endIdx < lines.length;
+        // A minified file is one line of hundreds of kilobytes, and a log can be megabytes: cut long lines and stop at a byte
+        // budget, and say where to carry on (G4). The line limit alone did neither.
+        const shown = [];
+        let used = 0;
+        let nextOffset;
+        for (let i = 0; i < slice.length; i++) {
+            const line = slice[i];
+            const cut = line.length > MAX_LINE_CHARS ? `${line.slice(0, MAX_LINE_CHARS)}... (${line.length - MAX_LINE_CHARS} more characters)` : line;
+            const row = `${String(offset + i).padStart(6)}\t${cut}`;
+            if (shown.length > 0 && used + row.length + 1 > MAX_READ_CHARS) {
+                nextOffset = offset + i;
+                break;
+            }
+            shown.push(row);
+            used += row.length + 1;
+        }
+        if (nextOffset === undefined && endIdx < lines.length)
+            nextOffset = endIdx + 1;
+        const truncated = nextOffset !== undefined;
+        const note = nextOffset !== undefined ? `\n\n... (${lines.length - nextOffset + 1} more lines; continue with offset ${nextOffset})` : '';
         const folderInstructions = ctx.shownFolderInstructions ? await folderInstructionsFor(resolved, ctx.cwd, ctx.shownFolderInstructions) : undefined;
         return {
             path: resolved,
             totalLines: lines.length,
             offset,
-            content: truncateByLines(slice.map((l, i) => `${String(offset + i).padStart(6)}\t${l}`).join('\n'), maxLines),
+            content: shown.join('\n') + note,
             truncated,
+            ...(nextOffset !== undefined ? { nextOffset } : {}),
             ...(folderInstructions ? { folderInstructions } : {}),
         };
     },