@ikarmic/forge-core 5.0.0 → 5.1.0

package/dist/tools/permission-rules.js

@@ -0,0 +1,182 @@
+import path from 'node:path';
+import { patchedPaths } from './apply-patch.js';
+import { isOutsideRel } from './shared.js';
+const ACTIONS = new Set(['allow', 'ask', 'deny']);
+/** Flatten a config object into ordered rules; entries with an unknown action are dropped. */
+export function compilePermissionRules(config) {
+    const rules = [];
+    if (!config || typeof config !== 'object')
+        return rules;
+    for (const [permission, value] of Object.entries(config)) {
+        if (typeof value === 'string') {
+            if (ACTIONS.has(value))
+                rules.push({ permission, pattern: '*', action: value });
+        }
+        else if (value && typeof value === 'object') {
+            for (const [pattern, action] of Object.entries(value)) {
+                if (ACTIONS.has(action))
+                    rules.push({ permission, pattern, action: action });
+            }
+        }
+    }
+    return rules;
+}
+const ci = process.platform === 'win32' ? 'i' : '';
+/**
+ * Wildcard match used by permission patterns: `*` and `**` match any run of characters (separators included),
+ * `?` one character, `{a,b}` alternatives. A trailing ` *` is optional so `git status *` also matches `git status`.
+ */
+function patternToRegex(pattern) {
+    let p = pattern;
+    let optionalTail = false;
+    if (p.endsWith(' *')) {
+        p = p.slice(0, -2);
+        optionalTail = true;
+    }
+    let re = '';
+    for (let i = 0; i < p.length; i++) {
+        const c = p[i];
+        if (c === '*') {
+            while (p[i + 1] === '*')
+                i++;
+            re += '.*';
+        }
+        else if (c === '?')
+            re += '.';
+        else if (c === '{') {
+            const close = p.indexOf('}', i);
+            if (close > i) {
+                re += '(?:' + p.slice(i + 1, close).split(',').map(escapeRegex).join('|') + ')';
+                i = close;
+            }
+            else
+                re += '\\{';
+        }
+        else
+            re += escapeRegex(c);
+    }
+    return new RegExp('^' + re + (optionalTail ? '(?: .*)?' : '') + '$', ci + 's');
+}
+function escapeRegex(s) {
+    return s.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+}
+/** The action of the last rule matching `permission` and `target`, or undefined when none does. */
+export function evaluatePermission(rules, permission, target) {
+    const norm = target.replace(/\\/g, '/');
+    let result;
+    for (const rule of rules) {
+        if (rule.permission !== '*' && rule.permission !== permission)
+            continue;
+        if (patternToRegex(rule.pattern.replace(/\\/g, '/')).test(norm))
+            result = rule.action;
+    }
+    return result;
+}
+/**
+ * Split a shell command into the commands a permission rule must each allow: `&&`, `||`, `;`, `|` and newlines
+ * outside quotes separate commands; the inside of `$(...)` and backticks is added as extra commands, and an
+ * unquoted `>` redirect adds a `redirect:` entry, so an allow rule for `git status *` cannot cover
+ * `git status $(rm -rf x)` or `git status > file`.
+ */
+export function splitShellCommands(command) {
+    const out = [];
+    let cur = '';
+    let quote = null;
+    const push = () => {
+        const t = cur.trim();
+        if (t)
+            out.push(t);
+        cur = '';
+    };
+    for (let i = 0; i < command.length; i++) {
+        const c = command[i];
+        if (quote) {
+            cur += c;
+            if (c === quote)
+                quote = null;
+            continue;
+        }
+        if (c === '"' || c === "'") {
+            quote = c;
+            cur += c;
+            continue;
+        }
+        if ((c === '&' && command[i + 1] === '&') || (c === '|' && command[i + 1] === '|')) {
+            push();
+            i++;
+            continue;
+        }
+        if (c === ';' || c === '|' || c === '\n') {
+            push();
+            continue;
+        }
+        cur += c;
+    }
+    push();
+    const extra = [];
+    for (const m of command.matchAll(/\$\(([^()]*)\)|`([^`]*)`/g)) {
+        for (const inner of splitShellCommands(m[1] ?? m[2] ?? ''))
+            extra.push(inner);
+    }
+    if (/(^|[^>&0-9])>{1,2}(?!&)/.test(stripQuoted(command)))
+        extra.push(`redirect: ${command.trim()}`);
+    return [...out, ...extra];
+}
+function stripQuoted(s) {
+    return s.replace(/"[^"]*"|'[^']*'/g, '""');
+}
+/** `.env` and `.env.*` hold secrets; `.env.example` and `.env.sample` are documentation. */
+export function isSensitiveFile(relPath) {
+    const base = relPath.replace(/\\/g, '/').split('/').pop() ?? '';
+    if (base === '.env.example' || base === '.env.sample')
+        return false;
+    return base === '.env' || base.startsWith('.env.');
+}
+/** True when a token of the command points outside `cwd`: `~`, a `..` escape, or an absolute path elsewhere. */
+export function touchesOutsideCwd(command, cwd) {
+    const root = path.resolve(cwd);
+    for (const raw of command.split(/\s+/)) {
+        const tok = raw.replace(/^["']|["']$/g, '');
+        if (!tok || tok.startsWith('-') || tok === '/dev/null')
+            continue;
+        if (tok === '~' || tok.startsWith('~/') || tok.startsWith('~\\'))
+            return true;
+        const absolute = tok.startsWith('/') || /^[A-Za-z]:[\\/]/.test(tok);
+        const escapes = tok.split(/[\\/]/).includes('..');
+        if (!absolute && !escapes)
+            continue;
+        const rel = path.relative(root, path.resolve(root, tok));
+        if (isOutsideRel(rel))
+            return true;
+    }
+    return false;
+}
+const READ_TOOLS = new Set(['read_file', 'read_image', 'list_files', 'search_files', 'list_symbols']);
+const EDIT_TOOLS = new Set(['write_file', 'edit_file', 'edit_notebook', 'apply_patch']);
+function relTarget(p, cwd) {
+    const raw = typeof p === 'string' && p ? p : '.';
+    const abs = path.resolve(cwd, raw);
+    const rel = path.relative(path.resolve(cwd), abs).replace(/\\/g, '/');
+    return rel === '' ? '.' : isOutsideRel(rel) ? abs.replace(/\\/g, '/') : rel;
+}
+/** Which permission a tool call falls under and the strings the rules are matched against; undefined = no rule applies. */
+export function permissionFor(toolName, args, cwd) {
+    const a = (args && typeof args === 'object' ? args : {});
+    if (READ_TOOLS.has(toolName))
+        return { permission: 'read', targets: [relTarget(a.path, cwd)] };
+    if (toolName === 'apply_patch') {
+        const paths = patchedPaths(typeof a.patch === 'string' ? a.patch : '');
+        return { permission: 'edit', targets: (paths.length ? paths : ['.']).map((p) => relTarget(p, cwd)) };
+    }
+    if (EDIT_TOOLS.has(toolName))
+        return { permission: 'edit', targets: [relTarget(a.path, cwd)] };
+    if (toolName === 'run_command')
+        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 : ''] };
+    if (toolName === 'web_search')
+        return { permission: 'websearch', targets: [typeof a.query === 'string' ? a.query : ''] };
+    if (toolName === 'sub_agent')
+        return { permission: 'task', targets: ['sub_agent'] };
+    return undefined;
+}

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

@@ -21,6 +21,11 @@ export interface ReadFileResult {
     offset: number;
     content: string;
     truncated: boolean;
+    /** `AGENTS.md` files of the folders this file sits in, shown the first time a file there is read. */
+    folderInstructions?: Array<{
+        file: string;
+        text: string;
+    }>;
 }
 /** A PDF comes back whole; the agent attaches it so document-capable models read it natively. */
 export interface ReadPdfResult {

package/dist/tools/read-file.js

@@ -2,7 +2,9 @@ import { readFile } from 'node:fs/promises';
 import { z } from 'zod';
 import { isNotebookPath, parseNotebook, renderNotebook } from './notebook.js';
 import { isPdf, MAX_ATTACHMENT_BYTES } from '../attachments.js';
+import { folderInstructionsFor } from '../steering/folder-instructions.js';
 import { resolveAndCheckPath, truncateByLines } from './shared.js';
+import { decodeText } from './text-encoding.js';
 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. */
@@ -47,22 +49,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.
-        if (looksBinary(raw)) {
+        const decoded = decodeText(raw);
+        if (decoded.encoding === 'utf8' && looksBinary(raw)) {
             throw new Error(`Refusing to read binary file: ${args.path} (${raw.length} bytes)`);
         }
-        const text = raw.toString('utf8');
+        const text = decoded.text;
         const lines = text.split(/\r?\n/);
         const offset = args.offset ?? 1;
         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;
+        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),
             truncated,
+            ...(folderInstructions ? { folderInstructions } : {}),
         };
     },
 };

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", "codebase_search", "memory_read"];
+export declare const READ_ONLY_TOOLS: readonly ["read_file", "list_files", "search_files", "find_symbol", "list_symbols", "find_references", "codebase_search", "memory_read", "sub_agent_wait"];
 /** 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

@@ -12,6 +12,8 @@ export const READ_ONLY_TOOLS = [
     'find_references',
     'codebase_search',
     'memory_read',
+    // Only observes the sub-agents the person already let start.
+    'sub_agent_wait',
 ];
 /** 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/run-command.d.ts

@@ -14,12 +14,12 @@ declare const params: z.ZodObject<{
     cwd: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     command: string;
-    cwd?: string | undefined;
     timeout_ms?: number | undefined;
+    cwd?: string | undefined;
 }, {
     command: string;
-    cwd?: string | undefined;
     timeout_ms?: number | undefined;
+    cwd?: string | undefined;
 }>;
 export interface RunCommandResult {
     command: string;
@@ -31,4 +31,6 @@ export interface RunCommandResult {
     timedOut: boolean;
 }
 export declare const runCommandTool: ToolDefinition<z.infer<typeof params>, RunCommandResult>;
+/** Cut a command's output to `max` characters, keeping the head and the tail. */
+export declare function clampOutput(text: string, max?: number): string;
 export {};

package/dist/tools/run-command.js

@@ -2,6 +2,7 @@ import { spawn } from 'node:child_process';
 import { z } from 'zod';
 import { checkPolicyViolation } from './policy.js';
 import { resolveAndCheckPath } from './shared.js';
+import { shellEnv } from './shell-env.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
@@ -77,8 +78,8 @@ export const runCommandTool = {
                     command: args.command,
                     exitCode: out.exitCode,
                     signal: out.signal ?? null,
-                    stdout: clampOutput(out.stdout),
-                    stderr: clampOutput(out.stderr),
+                    stdout: clampOutput(out.stdout, ctx.maxOutputChars),
+                    stderr: clampOutput(out.stderr, ctx.maxOutputChars),
                     durationMs: Date.now() - started,
                     timedOut: out.timedOut ?? false,
                 };
@@ -93,6 +94,8 @@ export const runCommandTool = {
             const child = spawn(args.command, {
                 shell: true,
                 cwd,
+                // Windows: never run a same-named program the repository ships in its root (see shell-env.ts).
+                env: shellEnv(process.env),
                 stdio: ['ignore', 'pipe', 'pipe'],
                 windowsHide: true,
                 // POSIX: own process group, so a kill reaches everything the shell started (see killTree).
@@ -128,8 +131,8 @@ export const runCommandTool = {
                     command: args.command,
                     exitCode: code,
                     signal: signal,
-                    stdout: clampOutput(stdout),
-                    stderr: clampOutput(stderr),
+                    stdout: clampOutput(stdout, ctx.maxOutputChars),
+                    stderr: clampOutput(stderr, ctx.maxOutputChars),
                     durationMs: Date.now() - started,
                     timedOut,
                 });
@@ -137,11 +140,12 @@ export const runCommandTool = {
         });
     },
 };
-function clampOutput(text) {
-    if (text.length <= MAX_OUTPUT_CHARS)
+/** Cut a command's output to `max` characters, keeping the head and the tail. */
+export function clampOutput(text, max = MAX_OUTPUT_CHARS) {
+    if (text.length <= max)
         return text;
-    const half = Math.floor(MAX_OUTPUT_CHARS / 2);
+    const half = Math.floor(max / 2);
     return (text.slice(0, half) +
-        `\n\n... (${text.length - MAX_OUTPUT_CHARS} characters truncated) ...\n\n` +
+        `\n\n... (${text.length - max} characters truncated) ...\n\n` +
         text.slice(text.length - half));
 }

package/dist/tools/sandbox-loader.js

@@ -1,7 +1,6 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import path from 'node:path';
 import { globalSettingsPath, projectSettingsPath, readSettings } from '../hooks/loader.js';
 import { validateToolSandboxConfig } from '../hooks/config.js';
+import { updateJsonFile } from '../config-file.js';
 const REGEX_FIELDS = ['allowedCommands', 'deniedCommands', 'allowedUrls', 'deniedUrls'];
 const PATH_FIELDS = ['allowedPaths', 'deniedPaths'];
 /** Compile a single policy's regex-string fields to RegExp, dropping any pattern that fails to compile. */
@@ -118,15 +117,6 @@ export async function loadToolSandboxConfig(cwd, opts, globalPathOverride) {
  */
 export async function saveToolSandboxConfig(sandbox, settingsPath) {
     const filePath = settingsPath ?? globalSettingsPath();
-    let existing = {};
-    try {
-        const raw = await readFile(filePath, 'utf8');
-        existing = JSON.parse(raw);
-    }
-    catch {
-        // Missing or malformed: start fresh rather than failing the save.
-    }
-    const merged = { ...existing, toolSandbox: sandbox };
-    await mkdir(path.dirname(filePath), { recursive: true });
-    await writeFile(filePath, JSON.stringify(merged, null, 2) + '\n', 'utf8');
+    // A malformed file is refused, not replaced: it holds hooks and other settings this save does not own.
+    await updateJsonFile(filePath, (existing) => ({ ...existing, toolSandbox: sandbox }));
 }

package/dist/tools/search-files.d.ts

@@ -12,15 +12,15 @@ declare const params: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     pattern: string;
     path?: string | undefined;
-    max_results?: number | undefined;
     include?: string | undefined;
+    max_results?: number | undefined;
     include_ignored?: boolean | undefined;
     context_lines?: number | undefined;
 }, {
     pattern: string;
     path?: string | undefined;
-    max_results?: number | undefined;
     include?: string | undefined;
+    max_results?: number | undefined;
     include_ignored?: boolean | undefined;
     context_lines?: number | undefined;
 }>;
@@ -36,4 +36,10 @@ export interface SearchFilesResult {
     filesScanned: number;
 }
 export declare const searchFilesTool: ToolDefinition<z.infer<typeof params>, SearchFilesResult>;
+/**
+ * True for a group that contains a repetition and is itself repeated (`(a+)+`, `(\w+\s?)*`, `(x*){2,}`): the shape that
+ * makes a backtracking engine take exponential time on a line that almost matches. JavaScript cannot stop a running
+ * regex, so such a pattern would freeze the editor; it is refused before it runs.
+ */
+export declare function hasNestedRepetition(source: string): boolean;
 export {};

package/dist/tools/search-files.js

@@ -121,7 +121,50 @@ export const searchFilesTool = {
         return { pattern: args.pattern, matches, truncated, filesScanned };
     },
 };
+/**
+ * True for a group that contains a repetition and is itself repeated (`(a+)+`, `(\w+\s?)*`, `(x*){2,}`): the shape that
+ * makes a backtracking engine take exponential time on a line that almost matches. JavaScript cannot stop a running
+ * regex, so such a pattern would freeze the editor; it is refused before it runs.
+ */
+export function hasNestedRepetition(source) {
+    const groups = []; // per open group: does it contain a repetition?
+    let inClass = false;
+    const isRepeat = (i) => source[i] === '+' || source[i] === '*' || (source[i] === '{' && /^\{\d*,?\d*\}/.test(source.slice(i)) && !/^\{\d+\}/.test(source.slice(i)));
+    for (let i = 0; i < source.length; i++) {
+        const c = source[i];
+        if (c === '\\') {
+            i++;
+            continue;
+        }
+        if (inClass) {
+            if (c === ']')
+                inClass = false;
+            continue;
+        }
+        if (c === '[') {
+            inClass = true;
+        }
+        else if (c === '(') {
+            groups.push(false);
+        }
+        else if (c === ')') {
+            const inner = groups.pop() ?? false;
+            if (inner && isRepeat(i + 1))
+                return true;
+            // A repeated group counts as a repetition inside the group around it.
+            if ((inner || isRepeat(i + 1)) && groups.length)
+                groups[groups.length - 1] = true;
+        }
+        else if (isRepeat(i) && groups.length) {
+            groups[groups.length - 1] = true;
+        }
+    }
+    return false;
+}
 function safeRegex(source) {
+    if (hasNestedRepetition(source)) {
+        throw new Error('Pattern has a repeated group that repeats again (like (a+)+), which can take exponential time on some lines. Simplify it, e.g. a+ instead of (a+)+.');
+    }
     try {
         return new RegExp(source, 'gm');
     }

package/dist/tools/shared.d.ts

@@ -9,6 +9,11 @@ import type { ToolContext } from '../types.js';
 export declare function resolveSafePath(inputPath: string, ctx: ToolContext, options?: {
     allowOutside?: boolean;
 }): 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('..')`.
+ */
+export declare function isOutsideRel(rel: string): boolean;
 /**
  * Convenience: run `resolveSafePath` then enforce the per-tool path policy
  * (allowedPaths / deniedPaths). Throws on either kind of violation. File

package/dist/tools/shared.js

@@ -1,3 +1,4 @@
+import { realpathSync } from 'node:fs';
 import path from 'node:path';
 import { checkPolicyViolation } from './policy.js';
 /**
@@ -12,13 +13,40 @@ export function resolveSafePath(inputPath, ctx, options = {}) {
         ? path.normalize(inputPath)
         : path.resolve(ctx.cwd, inputPath);
     if (!options.allowOutside) {
-        const rel = path.relative(ctx.cwd, resolved);
-        if (rel.startsWith('..') || path.isAbsolute(rel)) {
+        // Lexically, then for real: a symlink or junction inside the workspace can point anywhere on disk.
+        if (escapes(ctx.cwd, resolved) || escapes(realPath(ctx.cwd), realPath(resolved))) {
             throw new Error(`Path "${inputPath}" resolves outside of the working directory (${ctx.cwd}).`);
         }
     }
     return resolved;
 }
+/**
+ * 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('..')`.
+ */
+export function isOutsideRel(rel) {
+    return rel === '..' || rel.startsWith(`..${path.sep}`) || rel.startsWith('../') || path.isAbsolute(rel);
+}
+function escapes(root, target) {
+    return isOutsideRel(path.relative(root, target));
+}
+/** The real location of `p`: links resolved on the longest part that exists, the rest (a file not yet written) appended. */
+function realPath(p) {
+    let existing = p;
+    const rest = [];
+    for (;;) {
+        try {
+            return path.join(realpathSync.native(existing), ...rest);
+        }
+        catch {
+            const parent = path.dirname(existing);
+            if (parent === existing)
+                return p;
+            rest.unshift(path.basename(existing));
+            existing = parent;
+        }
+    }
+}
 /**
  * Convenience: run `resolveSafePath` then enforce the per-tool path policy
  * (allowedPaths / deniedPaths). Throws on either kind of violation. File

package/dist/tools/shell-env.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Environment for a command run through a shell. On Windows, cmd.exe looks for a bare program name in the current
+ * directory before PATH, and Forge runs commands in the workspace: a repository could ship `npm.cmd` or `node.cmd`
+ * and have it run instead of the real one when the person approves "npm test". `NoDefaultCurrentDirectoryInExePath`
+ * tells cmd.exe to skip the current directory; an explicit `.\script.cmd` still works.
+ */
+export declare function shellEnv(env: NodeJS.ProcessEnv, platform?: NodeJS.Platform): NodeJS.ProcessEnv;

package/dist/tools/shell-env.js

@@ -0,0 +1,9 @@
+/**
+ * Environment for a command run through a shell. On Windows, cmd.exe looks for a bare program name in the current
+ * directory before PATH, and Forge runs commands in the workspace: a repository could ship `npm.cmd` or `node.cmd`
+ * and have it run instead of the real one when the person approves "npm test". `NoDefaultCurrentDirectoryInExePath`
+ * tells cmd.exe to skip the current directory; an explicit `.\script.cmd` still works.
+ */
+export function shellEnv(env, platform = process.platform) {
+    return platform === 'win32' ? { ...env, NoDefaultCurrentDirectoryInExePath: '1' } : { ...env };
+}

package/dist/tools/sub-agent-wait.d.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import type { ToolDefinition } from '../types.js';
+declare const params: z.ZodObject<{
+    ids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    timeout_seconds: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    ids?: string[] | undefined;
+    timeout_seconds?: number | undefined;
+}, {
+    ids?: string[] | undefined;
+    timeout_seconds?: number | undefined;
+}>;
+export interface SubAgentWaitResult {
+    agents: Array<{
+        id: string;
+        task: string;
+        state: string;
+        finalText?: string;
+        error?: string;
+    }>;
+    stillRunning: number;
+    message?: string;
+}
+/**
+ * Collect the answers of sub-agents started with `sub_agent { background: true }`. Waits until they finish or the
+ * timeout passes, whichever is first; a run that is still going is reported as running and can be waited for again.
+ */
+export declare const subAgentWaitTool: ToolDefinition<z.infer<typeof params>, SubAgentWaitResult>;
+export {};

package/dist/tools/sub-agent-wait.js

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+const params = z.object({
+    ids: z
+        .array(z.string().min(1).max(40))
+        .max(20)
+        .optional()
+        .describe('Ids from sub_agent { background: true } to wait for. Omit to wait for every background agent still running.'),
+    timeout_seconds: z
+        .number()
+        .min(0)
+        .max(900)
+        .optional()
+        .describe('How long to wait before giving up and reporting what is still running. Default 300. 0 only looks.'),
+});
+/**
+ * Collect the answers of sub-agents started with `sub_agent { background: true }`. Waits until they finish or the
+ * timeout passes, whichever is first; a run that is still going is reported as running and can be waited for again.
+ */
+export const subAgentWaitTool = {
+    name: 'sub_agent_wait',
+    description: 'Wait for background sub-agents (started with sub_agent { background: true }) and return their answers. A run still going when the timeout passes is reported as running.',
+    parameters: params,
+    execute: async (args, ctx) => {
+        const bg = ctx.background;
+        if (!bg)
+            throw new Error('Background agents are not available here.');
+        const valid = params.parse(args);
+        const unknown = (valid.ids ?? []).filter((id) => !bg.get(id));
+        const known = (valid.ids ?? []).filter((id) => bg.get(id));
+        if (valid.ids && known.length === 0) {
+            return { agents: [], stillRunning: 0, message: `No background agent with id ${unknown.join(', ')}.` };
+        }
+        if (!valid.ids && bg.list().filter((a) => a.state === 'running').length === 0) {
+            // Nothing running: report what has finished, if anything has.
+            const finished = bg.takeUndelivered();
+            return {
+                agents: finished.map(view),
+                stillRunning: 0,
+                ...(finished.length === 0 ? { message: 'There are no background agents running.' } : {}),
+            };
+        }
+        const timeoutMs = (valid.timeout_seconds ?? 300) * 1000;
+        const got = await bg.wait(valid.ids ? known : undefined, { timeoutMs, ...(ctx.abortSignal ? { signal: ctx.abortSignal } : {}) });
+        bg.markDelivered(got.map((a) => a.id));
+        return {
+            agents: got.map(view),
+            stillRunning: got.filter((a) => a.state === 'running').length,
+            ...(unknown.length ? { message: `No background agent with id ${unknown.join(', ')}.` } : {}),
+        };
+    },
+};
+function view(a) {
+    return {
+        id: a.id,
+        task: a.task,
+        state: a.state,
+        ...(a.result?.finalText ? { finalText: a.result.finalText } : {}),
+        ...(a.error ? { error: a.error } : {}),
+    };
+}