@ikarmic/forge-core 5.3.0 → 5.4.0

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

@@ -5,13 +5,14 @@ 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 });
@@ -34,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.'),
     /**
@@ -61,19 +86,8 @@ 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;
-        // The OS sandbox wraps the command line; the result still reports the command the model asked for.
-        let commandLine = args.command;
-        if (ctx.commandSandbox) {
-            const boxed = sandboxCommand(args.command, { cwd, sandbox: ctx.commandSandbox, platform: process.platform, tmpDir: tmpdir() });
-            if (boxed.kind === 'refused')
-                throw new Error(`[sandbox] ${boxed.reason}`);
-            commandLine = boxed.command;
-        }
         if (ctx.commandRunner) {
             const started = Date.now();
             const out = await ctx.commandRunner({
@@ -101,8 +115,9 @@ export const runCommandTool = {
         }
         return new Promise((resolve, reject) => {
             const started = Date.now();
-            const child = spawn(commandLine, {
-                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),
@@ -110,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));
@@ -125,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);

package/dist/tools/search-files.js

@@ -1,9 +1,9 @@
 import path from 'node:path';
 import { z } from 'zod';
-import { globToRegex } from './policy.js';
+import { fileGlobMatcher } from './glob-filter.js';
 import { IgnoreRules } from './ignore-rules.js';
 import { DEFAULT_SEARCH_TIMEOUT_MS, matchInWorker } from './search-worker.js';
-import { resolveAndCheckPath, DEFAULT_IGNORED_DIRS } from './shared.js';
+import { resolveReadPath, DEFAULT_IGNORED_DIRS } from './shared.js';
 const params = z.object({
     pattern: z.string().describe('Regex pattern to search for in file contents.'),
     path: z
@@ -28,9 +28,9 @@ export const searchFilesTool = {
     description: 'Search file contents using a regular expression. Returns matches with file path, line number, and surrounding context. Skips heavy directories (node_modules, .git, dist, ...) by default.',
     parameters: params,
     execute: async (args, ctx) => {
-        const root = resolveAndCheckPath(args.path ?? '.', ctx);
+        const root = await resolveReadPath(args.path ?? '.', ctx);
         const regex = safeRegex(args.pattern);
-        const includeRe = args.include ? globToRegex(args.include) : null;
+        const matchesInclude = args.include ? fileGlobMatcher(args.include) : null;
         const maxResults = args.max_results ?? 200;
         const contextLines = args.context_lines ?? 1;
         // The walk (I/O and ignore rules) stays here; reading and matching run in a worker with a time limit (RB-22).
@@ -61,7 +61,7 @@ export const searchFilesTool = {
                 }
                 else if (entry.isFile()) {
                     const rel = path.relative(root, abs).split(path.sep).join('/');
-                    if (includeRe && !includeRe.test(rel))
+                    if (matchesInclude && !matchesInclude(rel, entry.name))
                         continue;
                     files.push({ abs, rel });
                 }

package/dist/tools/search-worker.js

@@ -19,6 +19,14 @@ const MATCH_BODY = String.raw `
     var dropped = lines.length - maxLines;
     return lines.slice(0, maxLines).join('\n') + '\n\n... (' + dropped + ' more line' + (dropped === 1 ? '' : 's') + ' truncated; re-read with a smaller offset to see more)';
   }
+  var LINE_MAX = 300;
+  // A match in a minified bundle is one huge line: show a window around the match, not the whole line (G5).
+  function clip(line, at) {
+    if (line.length <= LINE_MAX) return line;
+    var from = Math.max(0, Math.min(at - 100, line.length - LINE_MAX));
+    var to = Math.min(line.length, from + LINE_MAX);
+    return (from > 0 ? '...' : '') + line.slice(from, to) + (to < line.length ? '...' : '') + ' (' + (line.length - (to - from)) + ' more characters)';
+  }
   for (var f = 0; f < job.files.length; f++) {
     if (matches.length >= job.maxResults) { truncated = true; break; }
     var file = job.files[f];
@@ -30,11 +38,12 @@ const MATCH_BODY = String.raw `
     for (var i = 0; i < lines.length; i++) {
       if (matches.length >= job.maxResults) { truncated = true; break; }
       regex.lastIndex = 0;
-      if (regex.test(lines[i])) {
+      var hit = regex.exec(lines[i]);
+      if (hit) {
         var start = Math.max(0, i - job.contextLines);
         var end = Math.min(lines.length - 1, i + job.contextLines);
         var block = [];
-        for (var j = start; j <= end; j++) block.push((j === i ? '>' : ' ') + ' ' + String(j + 1).padStart(6) + '\t' + lines[j]);
+        for (var j = start; j <= end; j++) block.push((j === i ? '>' : ' ') + ' ' + String(j + 1).padStart(6) + '\t' + clip(lines[j], j === i ? hit.index : 0));
         matches.push({ path: file.rel, line: i + 1, text: truncateByLines(block.join('\n'), 10) });
       }
     }

package/dist/tools/shared.d.ts

@@ -8,7 +8,18 @@ import type { ToolContext } from '../types.js';
  */
 export declare function resolveSafePath(inputPath: string, ctx: ToolContext, options?: {
     allowOutside?: boolean;
+    read?: boolean;
 }): string;
+/** A path that leads outside the working directory: the one error a host may answer by asking (G16). */
+export declare class OutsideWorkspaceError extends Error {
+    constructor(message: string);
+}
+/**
+ * `resolveAndCheckPath` for a READ tool, with one more way to succeed: when the path leads outside the project and the host
+ * can ask, the person is asked about the real directory (links resolved), once per directory per run. A yes opens that
+ * directory and below to read tools; a no, or a directory that is too broad or holds credentials, is a refusal.
+ */
+export declare function resolveReadPath(inputPath: string, ctx: ToolContext): Promise<string>;
 /**
  * For a `path.relative(root, target)` result: does it lead out of `root`? `..` itself or `../…` does; a name that merely
  * starts with two dots (`..notes.md`) does not. Use this instead of `rel.startsWith('..')`.
@@ -20,7 +31,9 @@ export declare function isOutsideRel(rel: string): boolean;
  * tools call this instead of `resolveSafePath` directly so the sandbox is
  * applied uniformly.
  */
-export declare function resolveAndCheckPath(inputPath: string, ctx: ToolContext): string;
+export declare function resolveAndCheckPath(inputPath: string, ctx: ToolContext, options?: {
+    read?: boolean;
+}): string;
 /**
  * Truncate a string to a maximum number of lines, appending a marker so the
  * model knows the output was truncated and can re-read with a smaller window.