@ikarmic/forge-core 5.0.0 → 5.1.1

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,30 @@ 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/);
+        // 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
+        // lines look truncated. A genuinely blank last line ("a\n\n") still counts: only the piece after the final newline goes.
+        if (lines.length > 1 && lines[lines.length - 1] === '')
+            lines.pop();
         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 } : {}),
+    };
+}

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

@@ -1,8 +1,11 @@
 import { z } from 'zod';
-import type { ToolDefinition } from '../types.js';
+import { type AgentDef } from '../agents/agent-files.js';
+import type { AgentConfig, ModelConfig, ToolContext, ToolDefinition } from '../types.js';
 declare const params: z.ZodObject<{
     /** The task for the sub-agent to perform. Free-form text. */
     task: z.ZodString;
+    /** Name of an agent file (`.forge/agents/<name>.md`) to run as: its prompt, tools, model and step cap. */
+    agent: z.ZodOptional<z.ZodString>;
     /** Hard cap on iterations for the sub-agent. Default 10. */
     max_iterations: z.ZodOptional<z.ZodNumber>;
     /**
@@ -51,23 +54,39 @@ declare const params: z.ZodObject<{
      * won't collide.
      */
     cleanup_branch: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Start the child and return at once. The child keeps working while the parent continues; collect its answer with
+     * `sub_agent_wait`. Only where the surface can show background runs; elsewhere the child runs to completion as usual.
+     */
+    background: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     task: string;
+    agent?: string | undefined;
     cwd?: string | undefined;
-    max_iterations?: number | undefined;
     auto?: boolean | undefined;
+    background?: boolean | undefined;
+    max_iterations?: number | undefined;
     use_worktree?: boolean | undefined;
     worktree_label?: string | undefined;
     cleanup_branch?: boolean | undefined;
 }, {
     task: string;
+    agent?: string | undefined;
     cwd?: string | undefined;
-    max_iterations?: number | undefined;
     auto?: boolean | undefined;
+    background?: boolean | undefined;
+    max_iterations?: number | undefined;
     use_worktree?: boolean | undefined;
     worktree_label?: string | undefined;
     cleanup_branch?: boolean | undefined;
 }>;
+/** What `sub_agent { background: true }` returns instead of a result. */
+export interface SubAgentStarted {
+    started: true;
+    id: string;
+    task: string;
+    message: string;
+}
 export interface SubAgentResult {
     task: string;
     finalText: string;
@@ -103,5 +122,32 @@ export interface SubAgentResult {
  *    tools unless the parent explicitly opts in via the `auto` parameter.
  *  - The sub-agent inherits the parent's cwd and model unless overridden.
  */
-export declare const subAgentTool: ToolDefinition<z.infer<typeof params>, SubAgentResult>;
+export declare const subAgentTool: ToolDefinition<z.infer<typeof params>, SubAgentResult | SubAgentStarted>;
+/**
+ * What a child runs with: the tools it may see, its model, step cap and system prompt. Without an agent file this is
+ * the old behaviour (every tool but `sub_agent`, the sub-agent or parent model, default cap). `sub_agent` is never
+ * offered to a child, whatever the file says.
+ */
+export declare function childSetupFor<T extends {
+    name: string;
+}>(def: AgentDef | undefined, tools: readonly T[], ctx: Pick<ToolContext, 'subAgentModel' | 'parentModel'>, requestedIterations: number | undefined): {
+    tools: T[];
+    model: ModelConfig;
+    maxIterations: number;
+    systemPrompt?: string;
+};
+/**
+ * The child's Agent configuration. It carries the limits the person set for the parent (permission rules, tool
+ * sandbox): a child started with `auto: true` must not be a way around an `edit: deny` rule or a denied tool.
+ */
+export declare function childAgentConfig(setup: {
+    tools: readonly unknown[];
+    model: ModelConfig;
+    maxIterations: number;
+    systemPrompt?: string;
+}, ctx: Pick<ToolContext, 'autoApproveTools' | 'permissionRules' | 'toolSandbox' | 'askBudget'>, cwd: string, auto: boolean): AgentConfig;
+/** What a child runs without asking: what the parent does, else the read-only tools. Destructive tools still never run unasked. */
+export declare function childAutoApprove(ctx: Pick<ToolContext, 'autoApproveTools'>): string[];
+/** The configured sub-agent model, else the parent's, else a last-resort default. */
+export declare function childModelFor(ctx: Pick<ToolContext, 'subAgentModel' | 'parentModel'>): ModelConfig;
 export {};