@ikarmic/forge-core 5.2.0 → 5.4.0

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 } : {}),
         };
     },

package/dist/tools/read-image.js

@@ -24,7 +24,7 @@
  */
 import { readFile } from 'node:fs/promises';
 import { z } from 'zod';
-import { resolveAndCheckPath } from './shared.js';
+import { resolveReadPath } from './shared.js';
 /** Default cap: matches typical vision API limits. */
 const DEFAULT_MAX_BYTES = 5 * 1024 * 1024;
 /** Mime types we accept. Keep this list small: vision APIs vary. */
@@ -54,7 +54,7 @@ export const readImageTool = {
     description: 'Read an image file (PNG / JPEG / GIF / WebP) and return its bytes as a base64 data URL. Use this to inspect screenshots, diagrams, UI mocks, or other visual content. The image is attached to your next turn so vision-capable models can see it. Max 5 MB by default.',
     parameters: params,
     execute: async (args, ctx) => {
-        const resolved = resolveAndCheckPath(args.path, ctx);
+        const resolved = await resolveReadPath(args.path, ctx);
         const maxBytes = args.max_bytes ?? DEFAULT_MAX_BYTES;
         let raw;
         try {

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

@@ -3,6 +3,6 @@
  * anything. Asking before each of them is noise, so they are approved without a prompt by default;
  * edits, commands, web access and sub-agents still ask.
  */
-export declare const READ_ONLY_TOOLS: readonly ["read_file", "list_files", "search_files", "find_symbol", "list_symbols", "find_references", "git_diff", "codebase_search", "memory_read", "sub_agent_wait"];
+export declare const READ_ONLY_TOOLS: readonly ["read_file", "list_files", "search_files", "find_symbol", "list_symbols", "find_references", "git_diff", "codebase_search", "memory_read", "sub_agent_wait", "skill", "suggest_plan"];
 /** The tools that run without a prompt: the user's list, or the read-only tools when none is set. */
 export declare function resolveAutoApprove(configured?: readonly string[]): string[];

package/dist/tools/read-only.js

@@ -16,6 +16,10 @@ export const READ_ONLY_TOOLS = [
     'memory_read',
     // Only observes the sub-agents the person already let start.
     'sub_agent_wait',
+    // Returns the text of a skill that is already loaded; starts nothing.
+    'skill',
+    // Only signals the chat, which asks the person before anything happens.
+    'suggest_plan',
 ];
 /** The tools that run without a prompt: the user's list, or the read-only tools when none is set. */
 export function resolveAutoApprove(configured) {

package/dist/tools/repo-clone.d.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import type { ToolDefinition } from '../types.js';
+export interface RepoSpec {
+    host: string;
+    owner: string;
+    repo: string;
+    /** What git is given. */
+    url: string;
+}
+/** Read what the model gave; throws a sentence saying what is wrong. */
+export declare function parseRepoSpec(input: string): RepoSpec;
+/** Arguments for `git clone`. Options end at `--`, so an address can never be read as one. */
+export declare function cloneArgs(spec: Pick<RepoSpec, 'url'>, dest: string, emptyHooks: string, ref?: string): string[];
+export interface CloneOptions {
+    cacheRoot: string;
+    ref?: string;
+    timeoutMs?: number;
+    maxBytes?: number;
+    /** Tests only: config applied after the safety settings, to reach a local fixture. */
+    testGitConfig?: string[];
+}
+/** What went wrong, from git's stderr: its own `fatal:` and `error:` lines, not the progress text before them. */
+export declare function gitProblem(stderr: string): string;
+/** Clone, or refresh an earlier clone. Returns the folder and whether it was a refresh. */
+export declare function cloneInto(spec: RepoSpec, options: CloneOptions): Promise<{
+    path: string;
+    updated: boolean;
+    note?: string;
+}>;
+declare const params: z.ZodObject<{
+    repo: z.ZodString;
+    ref: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const repoCloneTool: ToolDefinition<z.infer<typeof params>, {
+    path: string;
+    url: string;
+    updated: boolean;
+    note: string;
+}>;
+export {};

package/dist/tools/repo-clone.js

@@ -0,0 +1,218 @@
+/**
+ * `repo_clone`: fetch a public repository into a cache so the read tools can look at it.
+ *
+ * A model supplies the address and the repository is a stranger's files, so: only https and ssh to a named host
+ * (never `file:`, `ext::`, a local path or a plain `http:`), no credentials in the address, no internal host
+ * (RB-21), git run with hooks, fsmonitor, submodules and symlinks off, a size and a time limit, and the folder it
+ * leaves is readable by read tools only, for this run only (`ToolContext.readRoots`, RB-20). Starting git is
+ * starting a program the repository's settings can influence, so it asks first (RB-41).
+ */
+import { execFile } from 'node:child_process';
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, renameSync, rmSync } from 'node:fs';
+import net from 'node:net';
+import { homedir, tmpdir } from 'node:os';
+import path from 'node:path';
+import { z } from 'zod';
+import { assertUrlNotBlocked, isBlockedAddress } from './fetch-url.js';
+const GENERIC = 'Give a repository as owner/repo (GitHub), an https address, or an ssh address such as git@host:owner/repo. Local paths and other protocols are refused.';
+const NAME = /^[A-Za-z0-9._-]+$/;
+const HOST = /^[a-z0-9.-]+$/;
+const REF = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/;
+function validName(n) {
+    return NAME.test(n) && n !== '.' && n !== '..';
+}
+function checkHost(host) {
+    const bare = host.toLowerCase().replace(/^\[|\]$/g, '');
+    if (bare === 'localhost' || bare.endsWith('.localhost') || bare.endsWith('.local') || bare.endsWith('.internal'))
+        throw new Error(`"${host}" is an internal host, not allowed.`);
+    if (net.isIP(bare)) {
+        if (isBlockedAddress(bare))
+            throw new Error(`"${host}" is a loopback, private or link-local address, not allowed.`);
+        return bare;
+    }
+    if (!HOST.test(bare) || bare.startsWith('.') || bare.endsWith('.') || bare.includes('..'))
+        throw new Error(`"${host}" is not a valid host name.`);
+    return bare;
+}
+function ownerRepo(parts) {
+    const [owner, rawRepo, ...rest] = parts;
+    const repo = rawRepo?.replace(/\.git$/, '');
+    if (!owner || !repo || rest.length > 0)
+        throw new Error('The address must name an owner and a repository, like https://host/owner/repo.');
+    if (!validName(owner) || !validName(repo))
+        throw new Error(`Invalid owner or repository name: ${owner}/${repo}.`);
+    return { owner, repo };
+}
+/** Read what the model gave; throws a sentence saying what is wrong. */
+export function parseRepoSpec(input) {
+    const spec = input.trim();
+    if (!spec)
+        throw new Error(`The repository is empty. ${GENERIC}`);
+    if (spec.startsWith('-'))
+        throw new Error(GENERIC);
+    // owner/repo
+    const short = /^([A-Za-z0-9._-]+)\/([A-Za-z0-9._-]+)$/.exec(spec);
+    if (short) {
+        if (!validName(short[1]) || !validName(short[2].replace(/\.git$/, '')))
+            throw new Error(GENERIC);
+        const { owner, repo } = ownerRepo([short[1], short[2]]);
+        return { host: 'github.com', owner, repo, url: `https://github.com/${owner}/${repo}.git` };
+    }
+    // git@host:owner/repo
+    const scp = /^([A-Za-z0-9._-]+)@([A-Za-z0-9.[\]:-]+?):(?!\/\/)(\S+)$/.exec(spec);
+    if (scp && !spec.includes('://')) {
+        const host = checkHost(scp[2]);
+        const { owner, repo } = ownerRepo(scp[3].replace(/^\/+/, '').split('/'));
+        return { host, owner, repo, url: `${scp[1]}@${host}:${owner}/${repo}.git` };
+    }
+    let u;
+    try {
+        u = new URL(spec);
+    }
+    catch {
+        throw new Error(GENERIC);
+    }
+    if (u.protocol !== 'https:' && u.protocol !== 'ssh:')
+        throw new Error(`Only https and ssh addresses are allowed (got ${u.protocol}). ${GENERIC}`);
+    if (u.password || (u.protocol === 'https:' && u.username))
+        throw new Error('Credentials in the address are not accepted. Clone public repositories, or set up your own git credentials.');
+    if (u.port)
+        throw new Error('An address with a port is not accepted.');
+    const host = checkHost(u.hostname);
+    const { owner, repo } = ownerRepo(u.pathname.replace(/^\/+|\/+$/g, '').split('/'));
+    const url = u.protocol === 'https:' ? `https://${host}/${owner}/${repo}.git` : `ssh://${u.username || 'git'}@${host}/${owner}/${repo}.git`;
+    return { host, owner, repo, url };
+}
+/** The safety settings every git call here carries. */
+function safety(emptyHooks) {
+    return [
+        '-c', `core.hooksPath=${emptyHooks}`,
+        '-c', 'core.fsmonitor=false',
+        '-c', 'core.symlinks=false',
+        '-c', 'protocol.file.allow=never',
+        '-c', 'protocol.ext.allow=never',
+    ];
+}
+/** Arguments for `git clone`. Options end at `--`, so an address can never be read as one. */
+export function cloneArgs(spec, dest, emptyHooks, ref) {
+    return [
+        ...safety(emptyHooks),
+        'clone', '--depth', '1', '--no-tags', '--single-branch', '--no-recurse-submodules', `--template=${emptyHooks}`,
+        ...(ref ? ['--branch', ref] : []),
+        '--', spec.url, dest,
+    ];
+}
+const DEFAULT_TIMEOUT_MS = 120_000;
+const DEFAULT_MAX_BYTES = 300 * 1024 * 1024;
+/** What went wrong, from git's stderr: its own `fatal:` and `error:` lines, not the progress text before them. */
+export function gitProblem(stderr) {
+    const lines = stderr.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+    const own = lines.filter((l) => /^(fatal|error|remote: (error|fatal)|warning: (could not|unable))/i.test(l));
+    return (own.length > 0 ? own.slice(-4) : lines.slice(-3)).join(' ').slice(0, 400);
+}
+function runGit(args, opts) {
+    return new Promise((resolve, reject) => {
+        execFile('git', args, {
+            cwd: opts.cwd,
+            timeout: opts.timeoutMs,
+            windowsHide: true,
+            maxBuffer: 4 * 1024 * 1024,
+            env: {
+                ...process.env,
+                GIT_TERMINAL_PROMPT: '0',
+                GIT_ASKPASS: '',
+                GIT_SSH_COMMAND: 'ssh -o BatchMode=yes',
+                GIT_ALLOW_PROTOCOL: opts.allowFile ? 'https:ssh:file' : 'https:ssh',
+            },
+        }, (err, stdout, stderr) => {
+            if (!err)
+                return resolve(String(stdout));
+            const killed = err.killed;
+            reject(new Error(killed ? `git took longer than ${Math.round(opts.timeoutMs / 1000)} seconds and was stopped.` : `git failed: ${gitProblem(String(stderr || err.message))}`));
+        });
+    });
+}
+function sizeOf(dir) {
+    let total = 0;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const p = path.join(dir, entry.name);
+        total += entry.isDirectory() ? sizeOf(p) : lstatSync(p).size;
+    }
+    return total;
+}
+/** Clone, or refresh an earlier clone. Returns the folder and whether it was a refresh. */
+export async function cloneInto(spec, options) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const allowFile = (options.testGitConfig?.length ?? 0) > 0;
+    const test = options.testGitConfig ?? [];
+    const dest = path.join(options.cacheRoot, spec.host, spec.owner, spec.repo);
+    const emptyHooks = mkdtempSync(path.join(tmpdir(), 'forge-nohooks-'));
+    try {
+        if (existsSync(path.join(dest, '.git'))) {
+            try {
+                const target = options.ref ?? 'HEAD';
+                await runGit([...safety(emptyHooks), ...test, 'fetch', '--depth', '1', '--no-tags', '--no-recurse-submodules', 'origin', target], { cwd: dest, timeoutMs, allowFile });
+                await runGit([...safety(emptyHooks), 'reset', '--hard', '-q', 'FETCH_HEAD'], { cwd: dest, timeoutMs, allowFile });
+                return { path: dest, updated: true };
+            }
+            catch (err) {
+                return { path: dest, updated: false, note: `Could not refresh it, so this is the copy fetched earlier. ${err.message}` };
+            }
+        }
+        mkdirSync(path.dirname(dest), { recursive: true });
+        const partial = `${dest}.partial-${process.pid}-${Date.now()}`;
+        try {
+            await runGit(insertTest(cloneArgs(spec, partial, emptyHooks, options.ref), test), { timeoutMs, allowFile });
+            if (sizeOf(partial) > (options.maxBytes ?? DEFAULT_MAX_BYTES))
+                throw new Error('The repository is too large to fetch here.');
+            renameSync(partial, dest);
+        }
+        catch (err) {
+            rmSync(partial, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+            throw err;
+        }
+        return { path: dest, updated: false };
+    }
+    finally {
+        rmSync(emptyHooks, { recursive: true, force: true });
+    }
+}
+/** Test config goes right after the safety settings and before the `clone` word, so it overrides them. */
+function insertTest(args, test) {
+    const at = args.indexOf('clone');
+    return [...args.slice(0, at), ...test, ...args.slice(at)];
+}
+function defaultCacheRoot() {
+    return path.join(homedir(), '.forge', 'cache', 'repos');
+}
+const params = z.object({
+    repo: z.string().describe('owner/repo for GitHub, an https address, or an ssh address such as git@host:owner/repo.'),
+    ref: z.string().optional().describe('A branch or tag to fetch. Default: the repository default branch.'),
+});
+export const repoCloneTool = {
+    name: 'repo_clone',
+    description: 'Fetch a public git repository (a shallow copy, no submodules) into a cache and return its folder, so you can read it with read_file, list_files and search_files. ' +
+        'Only https and ssh addresses and owner/repo are accepted. The copy is read-only for you, and a repeat call refreshes it. It reaches the network and starts git, so it asks first.',
+    parameters: params,
+    destructive: true,
+    execute: async (args, ctx) => {
+        const spec = parseRepoSpec(args.repo);
+        if (args.ref !== undefined && !REF.test(args.ref))
+            throw new Error(`Invalid branch or tag name: ${args.ref}`);
+        // A name that resolves to an internal address is refused as well as a literal one (the same check as fetch_url).
+        await assertUrlNotBlocked(`https://${spec.host}/`, ctx.policy).catch((err) => {
+            throw new Error(err.message.replace(/^fetch_url: /, 'repo_clone: '));
+        });
+        const root = ctx.repoCache?.root ?? defaultCacheRoot();
+        const r = await cloneInto(spec, { cacheRoot: root, ...(args.ref ? { ref: args.ref } : {}), ...(ctx.repoCache?.testGitConfig ? { testGitConfig: ctx.repoCache.testGitConfig } : {}) });
+        // Read tools compare real paths on both sides (shared.ts), so this list needs no resolving.
+        if (ctx.readRoots && !ctx.readRoots.includes(r.path))
+            ctx.readRoots.push(r.path);
+        return {
+            path: r.path,
+            url: spec.url,
+            updated: r.updated,
+            note: `${r.note ? `${r.note} ` : ''}Read it with read_file, list_files and search_files using paths under ${r.path}. It is read-only; nothing you write goes there.`,
+        };
+    },
+};

package/dist/tools/result-cap.d.ts

@@ -0,0 +1,8 @@
+/** About 25,000 tokens. A surface can set its own through `AgentConfig.maxToolOutputChars`. */
+export declare const DEFAULT_TOOL_RESULT_CHARS = 100000;
+/**
+ * The result itself when it fits in `max` characters. Otherwise long strings inside it are cut first (so the shape
+ * stays); a result that is still too big is cut as text. An image or PDF (`dataUrl`) is attached by the agent, not
+ * read as text, so it is left alone.
+ */
+export declare function capToolResult(result: unknown, max?: number): unknown;

package/dist/tools/result-cap.js

@@ -0,0 +1,44 @@
+/**
+ * One size limit for what any tool hands back to the model (G6). `run_command` already cut its own streams; every
+ * other tool (an MCP server, `fetch_url`, a search with thousands of matches) could put a megabyte into the prompt.
+ */
+import { clampOutput } from './run-command.js';
+/** About 25,000 tokens. A surface can set its own through `AgentConfig.maxToolOutputChars`. */
+export const DEFAULT_TOOL_RESULT_CHARS = 100_000;
+function isMedia(value) {
+    const v = value;
+    return typeof v === 'object' && v !== null && typeof v.dataUrl === 'string';
+}
+function clampStrings(value, limit) {
+    if (typeof value === 'string')
+        return value.length > limit ? clampOutput(value, limit) : value;
+    if (Array.isArray(value))
+        return value.map((v) => clampStrings(v, limit));
+    if (typeof value === 'object' && value !== null) {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, clampStrings(v, limit)]));
+    }
+    return value;
+}
+/**
+ * The result itself when it fits in `max` characters. Otherwise long strings inside it are cut first (so the shape
+ * stays); a result that is still too big is cut as text. An image or PDF (`dataUrl`) is attached by the agent, not
+ * read as text, so it is left alone.
+ */
+export function capToolResult(result, max = DEFAULT_TOOL_RESULT_CHARS) {
+    if (typeof result === 'string')
+        return result.length > max ? clampOutput(result, max) : result;
+    if (result === null || typeof result !== 'object' || isMedia(result))
+        return result;
+    const size = JSON.stringify(result)?.length ?? 0;
+    if (size <= max)
+        return result;
+    // Keep as much of each long string as the budget allows: half the budget, then a quarter, then an eighth.
+    for (const divisor of [2, 4, 8]) {
+        const shrunk = clampStrings(result, Math.max(500, Math.floor(max / divisor)));
+        if ((JSON.stringify(shrunk)?.length ?? 0) <= max)
+            return shrunk;
+    }
+    // The text is a string inside the wrapper below, so its quotes get escaped again: leave room for that.
+    const text = JSON.stringify(result);
+    return { truncatedResult: clampOutput(text, Math.floor(max * 0.8)), note: `The result was ${size} characters and was cut to ${max}. Ask for less (a narrower path, a smaller range, a more specific pattern).` };
+}

package/dist/tools/run-command.d.ts

@@ -1,5 +1,22 @@
+import { spawn } from 'node:child_process';
 import { z } from 'zod';
-import type { ToolDefinition } from '../types.js';
+import type { ToolContext, ToolDefinition } from '../types.js';
+/**
+ * Kill a child process and its whole tree. Windows: `taskkill /T`. POSIX: the child is started as the leader of its
+ * own process group (`detached`), and the signal goes to the group (`-pid`); signalling only the shell left whatever
+ * it had forked (`sh -c "node ..."`) running, holding the output pipes open, so a stopped or timed-out command
+ * never finished. SIGKILL follows after a grace period if the process is still alive.
+ */
+export declare function killTree(child: ReturnType<typeof spawn>, graceMs?: number): void;
+/**
+ * The checks every command Forge starts goes through, shared by `run_command` and `bg_start`: the working directory
+ * must be inside the project, the tool policy must allow the command, and the OS sandbox may wrap or refuse it.
+ * `commandLine` is what to spawn; the result still reports the command the model asked for.
+ */
+export declare function prepareCommand(command: string, cwdOverride: string | undefined, ctx: ToolContext): {
+    cwd: string;
+    commandLine: string;
+};
 declare const params: z.ZodObject<{
     command: z.ZodString;
     timeout_ms: z.ZodOptional<z.ZodNumber>;

package/dist/tools/run-command.js

@@ -1,15 +1,18 @@
 import { spawn } from 'node:child_process';
+import { tmpdir } from 'node:os';
 import { z } from 'zod';
+import { sandboxCommand } from './command-sandbox.js';
 import { checkPolicyViolation } from './policy.js';
 import { resolveAndCheckPath } from './shared.js';
 import { shellEnv } from './shell-env.js';
+import { runnerShell, shellInvocation } from './shell.js';
 /**
  * Kill a child process and its whole tree. Windows: `taskkill /T`. POSIX: the child is started as the leader of its
  * own process group (`detached`), and the signal goes to the group (`-pid`); signalling only the shell left whatever
  * it had forked (`sh -c "node ..."`) running, holding the output pipes open, so a stopped or timed-out command
  * never finished. SIGKILL follows after a grace period if the process is still alive.
  */
-function killTree(child, graceMs = 5000) {
+export function killTree(child, graceMs = 5000) {
     if (process.platform === 'win32') {
         try {
             spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
@@ -32,6 +35,30 @@ function killTree(child, graceMs = 5000) {
     signalTree('SIGTERM');
     setTimeout(() => signalTree('SIGKILL'), graceMs).unref();
 }
+/**
+ * The checks every command Forge starts goes through, shared by `run_command` and `bg_start`: the working directory
+ * must be inside the project, the tool policy must allow the command, and the OS sandbox may wrap or refuse it.
+ * `commandLine` is what to spawn; the result still reports the command the model asked for.
+ */
+export function prepareCommand(command, cwdOverride, ctx) {
+    // resolveAndCheckPath throws if the override escapes ctx.cwd or violates ctx.policy's path rules.
+    const cwd = cwdOverride ? resolveAndCheckPath(cwdOverride, ctx) : ctx.cwd;
+    const violation = checkPolicyViolation(ctx.policy, { cwd, command });
+    if (violation)
+        throw new Error(`[sandbox] ${violation}`);
+    let commandLine = command;
+    if (ctx.commandSandbox) {
+        const boxed = sandboxCommand(command, { cwd, sandbox: ctx.commandSandbox, platform: process.platform, tmpDir: tmpdir() });
+        if (boxed.kind === 'refused')
+            throw new Error(`[sandbox] ${boxed.reason}`);
+        // A sandbox was asked for and this system cannot give one: say so, unless the person was told and chose to go on (F13).
+        if (boxed.kind === 'unavailable' && !ctx.commandSandbox.allowUnconfined) {
+            throw new Error('[sandbox] The command sandbox is on, but this system cannot confine commands (Windows has no sandbox tool), so the command was not run. Turn the sandbox off to run commands unconfined.');
+        }
+        commandLine = boxed.command;
+    }
+    return { cwd, commandLine };
+}
 const params = z.object({
     command: z.string().describe('The shell command to execute. Use arrays for cross-platform safety when possible.'),
     /**
@@ -59,15 +86,12 @@ export const runCommandTool = {
         // to spawn() with no check, and the policy check below used the
         // parent's original ctx.cwd regardless, so a configured path policy
         // could never see (let alone block) the override.
-        const cwd = args.cwd ? resolveAndCheckPath(args.cwd, ctx) : ctx.cwd;
-        const violation = checkPolicyViolation(ctx.policy, { cwd, command: args.command });
-        if (violation)
-            throw new Error(`[sandbox] ${violation}`);
+        const { cwd, commandLine } = prepareCommand(args.command, args.cwd, ctx);
         const timeoutMs = args.timeout_ms ?? DEFAULT_TIMEOUT_MS;
         if (ctx.commandRunner) {
             const started = Date.now();
             const out = await ctx.commandRunner({
-                command: args.command,
+                command: commandLine,
                 cwd,
                 timeoutMs,
                 ...(ctx.abortSignal ? { signal: ctx.abortSignal } : {}),
@@ -91,8 +115,9 @@ export const runCommandTool = {
         }
         return new Promise((resolve, reject) => {
             const started = Date.now();
-            const child = spawn(args.command, {
-                shell: true,
+            // Windows: PowerShell or Git Bash when installed (G11), else cmd.exe; elsewhere /bin/sh.
+            const inv = shellInvocation(runnerShell(ctx.shell), commandLine);
+            const options = {
                 cwd,
                 // Windows: never run a same-named program the repository ships in its root (see shell-env.ts).
                 env: shellEnv(process.env),
@@ -100,7 +125,8 @@ export const runCommandTool = {
                 windowsHide: true,
                 // POSIX: own process group, so a kill reaches everything the shell started (see killTree).
                 detached: process.platform !== 'win32',
-            });
+            };
+            const child = inv.file ? spawn(inv.file, inv.args, options) : spawn(commandLine, { ...options, shell: true });
             const stdoutChunks = [];
             const stderrChunks = [];
             child.stdout.on('data', (chunk) => stdoutChunks.push(chunk));
@@ -115,6 +141,15 @@ export const runCommandTool = {
             }
             const onAbort = () => killTree(child);
             ctx.abortSignal?.addEventListener('abort', onAbort, { once: true });
+            // A stopped command can leave a grandchild that started in the instant the tree was listed (taskkill /T cannot see
+            // it) holding the output pipes, so 'close' would wait for it. Once the shell itself has exited, give the pipes a
+            // moment to drain and then release them.
+            child.on('exit', () => {
+                setTimeout(() => {
+                    child.stdout.destroy();
+                    child.stderr.destroy();
+                }, 500).unref();
+            });
             child.on('error', (err) => {
                 if (timeoutHandle)
                     clearTimeout(timeoutHandle);