@ikarmic/forge-core 5.2.0 → 5.4.0

package/dist/tools/search-files.js

@@ -1,9 +1,9 @@
-import { readFile } from 'node:fs/promises';
 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 { resolveAndCheckPath, truncateByLines, DEFAULT_IGNORED_DIRS } from './shared.js';
+import { DEFAULT_SEARCH_TIMEOUT_MS, matchInWorker } from './search-worker.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,20 +28,15 @@ 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;
-        const matches = [];
-        let truncated = false;
-        let filesScanned = 0;
+        // The walk (I/O and ignore rules) stays here; reading and matching run in a worker with a time limit (RB-22).
+        const files = [];
         const rules = args.include_ignored ? null : IgnoreRules.forRoot(ctx.cwd);
         async function walk(dir) {
-            if (matches.length >= maxResults) {
-                truncated = true;
-                return;
-            }
             const { readdir } = await import('node:fs/promises');
             let entries;
             try {
@@ -54,10 +49,6 @@ export const searchFilesTool = {
                 throw err;
             }
             for (const entry of entries) {
-                if (matches.length >= maxResults) {
-                    truncated = true;
-                    return;
-                }
                 if (entry.name.startsWith('.'))
                     continue;
                 if (DEFAULT_IGNORED_DIRS.has(entry.name))
@@ -70,42 +61,9 @@ 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;
-                    await searchFile(abs, rel);
-                }
-            }
-        }
-        async function searchFile(abs, rel) {
-            filesScanned++;
-            let buf;
-            try {
-                buf = await readFile(abs);
-            }
-            catch {
-                return;
-            }
-            // Skip binary files.
-            if (buf.includes(0))
-                return;
-            const text = buf.toString('utf8');
-            const lines = text.split(/\r?\n/);
-            for (let i = 0; i < lines.length; i++) {
-                if (matches.length >= maxResults) {
-                    truncated = true;
-                    return;
-                }
-                const line = lines[i];
-                regex.lastIndex = 0;
-                if (regex.test(line)) {
-                    const start = Math.max(0, i - contextLines);
-                    const end = Math.min(lines.length - 1, i + contextLines);
-                    const block = [];
-                    for (let j = start; j <= end; j++) {
-                        const marker = j === i ? '>' : ' ';
-                        block.push(`${marker} ${String(j + 1).padStart(6)}\t${lines[j]}`);
-                    }
-                    matches.push({ path: rel, line: i + 1, text: truncateByLines(block.join('\n'), 10) });
+                    files.push({ abs, rel });
                 }
             }
         }
@@ -113,12 +71,13 @@ export const searchFilesTool = {
         if (!stat)
             throw new Error(`Path not found: ${root}`);
         if (stat.isFile()) {
-            await searchFile(root, path.basename(root));
+            files.push({ abs: root, rel: path.basename(root) });
         }
         else {
             await walk(root);
         }
-        return { pattern: args.pattern, matches, truncated, filesScanned };
+        const result = await matchInWorker({ files, source: regex.source, flags: regex.flags, maxResults, contextLines }, { timeoutMs: ctx.searchTimeoutMs ?? DEFAULT_SEARCH_TIMEOUT_MS });
+        return { pattern: args.pattern, ...result };
     },
 };
 /**

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

@@ -0,0 +1,23 @@
+import { Worker } from 'node:worker_threads';
+import type { SearchMatch } from './search-files.js';
+export interface MatchJob {
+    files: Array<{
+        abs: string;
+        rel: string;
+    }>;
+    source: string;
+    flags: string;
+    maxResults: number;
+    contextLines: number;
+}
+export interface MatchResult {
+    matches: SearchMatch[];
+    truncated: boolean;
+    filesScanned: number;
+}
+export declare const DEFAULT_SEARCH_TIMEOUT_MS = 20000;
+/** Match `job` in a worker; throws when it runs longer than `timeoutMs`. Falls back to in-process if no worker starts. */
+export declare function matchInWorker(job: MatchJob, opts: {
+    timeoutMs: number;
+    startWorker?: (source: string, data: MatchJob) => Worker;
+}): Promise<MatchResult>;

package/dist/tools/search-worker.js

@@ -0,0 +1,86 @@
+/**
+ * search_files' matching, run in a worker thread with a time limit. JavaScript cannot interrupt a running regex, so a
+ * pattern that backtracks badly on the main thread froze the process (in VS Code, the extension host): in a worker it
+ * is terminated after `timeoutMs`. The worker source is a plain string, not a function's text, so a bundler cannot
+ * rename or wrap anything in it; the same string runs in-process when a worker cannot start.
+ */
+import { readFileSync } from 'node:fs';
+import { Worker } from 'node:worker_threads';
+export const DEFAULT_SEARCH_TIMEOUT_MS = 20_000;
+/** Body of `function (job, readFile)`: read each file, skip binaries, match line by line, keep context. */
+const MATCH_BODY = String.raw `
+  var regex = new RegExp(job.source, job.flags);
+  var matches = [];
+  var truncated = false;
+  var filesScanned = 0;
+  function truncateByLines(text, maxLines) {
+    var lines = text.split(/\r?\n/);
+    if (lines.length <= maxLines) return text;
+    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];
+    filesScanned++;
+    var buf;
+    try { buf = readFile(file.abs); } catch (e) { continue; }
+    if (buf.includes(0)) continue;
+    var lines = buf.toString('utf8').split(/\r?\n/);
+    for (var i = 0; i < lines.length; i++) {
+      if (matches.length >= job.maxResults) { truncated = true; break; }
+      regex.lastIndex = 0;
+      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' + clip(lines[j], j === i ? hit.index : 0));
+        matches.push({ path: file.rel, line: i + 1, text: truncateByLines(block.join('\n'), 10) });
+      }
+    }
+  }
+  return { matches: matches, truncated: truncated, filesScanned: filesScanned };
+`;
+const WORKER_SOURCE = `
+const { parentPort, workerData } = require('node:worker_threads');
+const fs = require('node:fs');
+const match = new Function('job', 'readFile', ${JSON.stringify(MATCH_BODY)});
+parentPort.postMessage(match(workerData, (p) => fs.readFileSync(p)));
+`;
+function matchInProcess(job) {
+    return new Function('job', 'readFile', MATCH_BODY)(job, (p) => readFileSync(p));
+}
+/** Match `job` in a worker; throws when it runs longer than `timeoutMs`. Falls back to in-process if no worker starts. */
+export function matchInWorker(job, opts) {
+    let worker;
+    try {
+        worker = (opts.startWorker ?? ((source, data) => new Worker(source, { eval: true, workerData: data })))(WORKER_SOURCE, job);
+    }
+    catch {
+        return Promise.resolve(matchInProcess(job));
+    }
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            void worker.terminate();
+            reject(new Error(`The search pattern took longer than ${Math.round(opts.timeoutMs / 1000)} s and was stopped. Simplify it (avoid repeated groups that can match the same text in several ways) or search fewer files.`));
+        }, opts.timeoutMs);
+        worker.once('message', (result) => {
+            clearTimeout(timer);
+            void worker.terminate();
+            resolve(result);
+        });
+        worker.once('error', (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}

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.

package/dist/tools/shared.js

@@ -1,4 +1,5 @@
-import { realpathSync } from 'node:fs';
+import { realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
 import path from 'node:path';
 import { checkPolicyViolation } from './policy.js';
 /**
@@ -15,11 +16,82 @@ export function resolveSafePath(inputPath, ctx, options = {}) {
     if (!options.allowOutside) {
         // 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}).`);
+            // A read may also reach a folder this run was explicitly given (a repository it cloned), never anything else.
+            if (options.read && inReadRoot(resolved, ctx))
+                return resolved;
+            throw new OutsideWorkspaceError(`Path "${inputPath}" resolves outside of the working directory (${ctx.cwd}).`);
         }
     }
     return resolved;
 }
+/** A path that leads outside the working directory: the one error a host may answer by asking (G16). */
+export class OutsideWorkspaceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'OutsideWorkspaceError';
+    }
+}
+/** Is `resolved` inside one of the run's extra read roots, judged by where it really is after links (RB-20)? */
+function inReadRoot(resolved, ctx) {
+    const real = realPath(resolved);
+    return (ctx.readRoots ?? []).some((root) => !escapes(realPath(root), real));
+}
+const SENSITIVE_DIRS = new Set(['.ssh', '.aws', '.gnupg', '.kube', '.azure', '.docker', '.password-store', 'credentials', 'protect', 'user data']);
+/** Why a directory must not be offered for reading, or undefined: too broad to be a choice, or holds credentials. */
+function notOfferable(dir) {
+    if (path.parse(dir).root === dir)
+        return 'it is the top of a drive, too broad to open';
+    let home;
+    try {
+        home = realpathSync.native(homedir());
+    }
+    catch {
+        home = undefined;
+    }
+    // The home folder and everything above it would open the credential folders inside it.
+    if (home && !escapes(dir, home))
+        return 'it is your home folder or a folder above it, too broad to open';
+    const key = (p) => (process.platform === 'win32' ? p.toLowerCase() : p);
+    if (path.normalize(dir).split(path.sep).some((part) => SENSITIVE_DIRS.has(key(part))))
+        return 'it holds credentials';
+    return undefined;
+}
+/**
+ * `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 async function resolveReadPath(inputPath, ctx) {
+    try {
+        return resolveAndCheckPath(inputPath, ctx, { read: true });
+    }
+    catch (err) {
+        if (!(err instanceof OutsideWorkspaceError) || !ctx.askReadOutside)
+            throw err;
+        const resolved = path.isAbsolute(inputPath) ? path.normalize(inputPath) : path.resolve(ctx.cwd, inputPath);
+        const real = realPath(resolved);
+        let isDir = false;
+        try {
+            isDir = statSync(real).isDirectory();
+        }
+        catch {
+            isDir = false;
+        }
+        const dir = isDir ? real : path.dirname(real);
+        const key = process.platform === 'win32' ? dir.toLowerCase() : dir;
+        if (ctx.deniedReadDirs?.has(key))
+            throw err;
+        const why = notOfferable(dir);
+        if (why)
+            throw new OutsideWorkspaceError(`Path "${inputPath}" is outside the working directory, and Forge will not offer to open ${dir}: ${why}.`);
+        if (!(await ctx.askReadOutside(dir))) {
+            (ctx.deniedReadDirs ??= new Set()).add(key);
+            throw new OutsideWorkspaceError(`Path "${inputPath}" is outside the working directory, and reading in ${dir} was not allowed.`);
+        }
+        (ctx.readRoots ??= []).push(dir);
+        return resolveAndCheckPath(inputPath, ctx, { read: true });
+    }
+}
 /**
  * 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('..')`.
@@ -53,8 +125,8 @@ function realPath(p) {
  * tools call this instead of `resolveSafePath` directly so the sandbox is
  * applied uniformly.
  */
-export function resolveAndCheckPath(inputPath, ctx) {
-    const resolved = resolveSafePath(inputPath, ctx);
+export function resolveAndCheckPath(inputPath, ctx, options = {}) {
+    const resolved = resolveSafePath(inputPath, ctx, options);
     const violation = checkPolicyViolation(ctx.policy, { cwd: ctx.cwd, resolvedPath: resolved });
     if (violation)
         throw new Error(`[sandbox] ${violation}`);

package/dist/tools/shell.d.ts

@@ -0,0 +1,27 @@
+export type ShellKind = 'pwsh' | 'powershell' | 'bash' | 'cmd' | 'sh';
+/** What a person can ask for. */
+export type ShellPreference = 'auto' | 'pwsh' | 'powershell' | 'bash' | 'cmd';
+export interface ShellChoice {
+    kind: ShellKind;
+    /** The program to start; absent for cmd.exe and sh, which `spawn(..., { shell: true })` finds itself. */
+    file?: string;
+}
+export interface ChooseShellInput {
+    platform: NodeJS.Platform;
+    env: NodeJS.ProcessEnv;
+    preference?: ShellPreference;
+    /** Tests: does this file exist? */
+    exists?: (file: string) => boolean;
+    /** Tests: where is this program on PATH? */
+    find?: (name: string) => string | undefined;
+    /** Tests: Git Bash, when known. */
+    gitBash?: string | undefined;
+}
+export declare function chooseShell(input: ChooseShellInput): ShellChoice;
+/** The program and arguments that run `command` in `shell`. `file` is undefined for cmd.exe and sh: use `shell: true`. */
+export declare function shellInvocation(shell: ShellChoice, command: string): {
+    file: string | undefined;
+    args: string[];
+};
+/** The shell for this machine, looked up once per preference. */
+export declare function runnerShell(preference?: ShellPreference | undefined, platform?: NodeJS.Platform): ShellChoice;

package/dist/tools/shell.js

@@ -0,0 +1,80 @@
+/**
+ * Which shell Forge's own command runner uses (G11). On Windows `cmd.exe` has no `ls`, `cat` or `grep`, and models
+ * write worse commands for it, so the runner prefers `pwsh`, then Windows PowerShell, then Git Bash, then `cmd.exe`.
+ * Elsewhere it stays `/bin/sh`. In VS Code the command runs in the integrated terminal instead and this is not used.
+ *
+ * RB-24 still holds: a shell started in the workspace must not run a program the repository ships. cmd.exe is
+ * handled by `shellEnv`; PowerShell and bash look in PATH only (a script in the current folder needs `.\`).
+ */
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { resolveOnPath } from '../lsp/client.js';
+/** `bash.exe` of a Git for Windows install, found from `git` on PATH. Never `System32\bash.exe`, which starts WSL. */
+function findGitBash(input, find, exists) {
+    if (input.gitBash !== undefined)
+        return input.gitBash;
+    const git = find('git');
+    if (!git)
+        return undefined;
+    const root = path.dirname(path.dirname(git));
+    for (const rel of [['bin', 'bash.exe'], ['usr', 'bin', 'bash.exe']]) {
+        const candidate = path.join(root, ...rel);
+        if (exists(candidate) && !/system32/i.test(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+export function chooseShell(input) {
+    if (input.platform !== 'win32')
+        return { kind: 'sh' };
+    const exists = input.exists ?? existsSync;
+    const find = input.find ?? ((n) => resolveOnPath(n, input.env, 'win32'));
+    const pwsh = find('pwsh');
+    const powershell = find('powershell');
+    const bash = findGitBash(input, find, exists);
+    const available = {
+        pwsh: pwsh ? { kind: 'pwsh', file: pwsh } : undefined,
+        powershell: powershell ? { kind: 'powershell', file: powershell } : undefined,
+        bash: bash ? { kind: 'bash', file: bash } : undefined,
+        cmd: { kind: 'cmd' },
+    };
+    const pref = input.preference ?? 'auto';
+    if (pref !== 'auto' && available[pref])
+        return available[pref];
+    // Asked for a shell that is not installed: fall through the usual order.
+    return available.pwsh ?? available.powershell ?? available.bash ?? available.cmd;
+}
+/**
+ * `powershell -Command` ends with exit code 1 when the last command failed, whatever the code of a native program was.
+ * This keeps the program's own code (node, git and npm tell apart failures by it) with the status of the LAST command,
+ * as sh and cmd report it: a native failure followed by a cmdlet that works is a success. The tail is on its own line
+ * so a trailing comment in the command cannot swallow it.
+ */
+function withExitCode(command) {
+    return `$global:LASTEXITCODE = $null\n${command}\nif (-not $?) { if ($null -ne $LASTEXITCODE -and $LASTEXITCODE -ne 0) { exit $LASTEXITCODE } else { exit 1 } }`;
+}
+/** The program and arguments that run `command` in `shell`. `file` is undefined for cmd.exe and sh: use `shell: true`. */
+export function shellInvocation(shell, command) {
+    switch (shell.kind) {
+        case 'pwsh':
+            return { file: shell.file, args: ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', withExitCode(command)] };
+        case 'powershell':
+            // Windows PowerShell writes the console code page (not UTF-8) to a pipe, which mangles accents and CJK text.
+            return { file: shell.file, args: ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', `[Console]::OutputEncoding=[System.Text.Encoding]::UTF8\n${withExitCode(command)}`] };
+        case 'bash':
+            return { file: shell.file, args: ['-c', command] };
+        default:
+            return { file: undefined, args: [] };
+    }
+}
+const cache = new Map();
+/** The shell for this machine, looked up once per preference. */
+export function runnerShell(preference = 'auto', platform = process.platform) {
+    const key = `${platform}:${preference}`;
+    let found = cache.get(key);
+    if (!found) {
+        found = chooseShell({ platform, env: process.env, preference });
+        cache.set(key, found);
+    }
+    return found;
+}

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

@@ -77,7 +77,7 @@ export declare function childAgentConfig(setup: {
     model: ModelConfig;
     maxIterations: number;
     systemPrompt?: string;
-}, ctx: Pick<ToolContext, 'autoApproveTools' | 'permissionRules' | 'toolSandbox' | 'askBudget'>, cwd: string, auto: boolean): AgentConfig;
+}, ctx: Pick<ToolContext, 'autoApproveTools' | 'permissionRules' | 'toolSandbox' | 'askBudget' | 'commandSandbox'>, 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. */

package/dist/tools/sub-agent.js

@@ -107,7 +107,9 @@ const DEFAULT_MAX_ITERATIONS = 10;
  *    passing `allowSubAgent: true` via context if you really want it)
  *  - nothing else: the sub-agent gets the full built-in toolset.
  */
-const FORBIDDEN_TOOLS = new Set(['sub_agent', 'sub_agent_wait']);
+// A child has no one to approve a command and no run of its own to stop a process when it ends, so it gets no
+// background processes either (RB-14).
+const FORBIDDEN_TOOLS = new Set(['sub_agent', 'sub_agent_wait', 'bg_start', 'bg_read', 'bg_stop', 'schedule_wakeup', 'cancel_wakeup', 'repo_clone', 'suggest_plan']);
 /**
  * Delegate a task to a child agent. The child runs synchronously and its
  * final text + run statistics are returned to the parent. Useful for
@@ -328,6 +330,7 @@ export function childAgentConfig(setup, ctx, cwd, auto) {
         autoApproveTools: childAutoApprove(ctx),
         ...(ctx.permissionRules ? { permissionRules: ctx.permissionRules } : {}),
         ...(ctx.toolSandbox ? { toolSandbox: ctx.toolSandbox } : {}),
+        ...(ctx.commandSandbox ? { commandSandbox: ctx.commandSandbox } : {}),
         // The same budget object, not a copy: a child that started its own four
         // would be a way around the limit the parent is under (RB-14).
         ...(ctx.askBudget ? { askBudget: ctx.askBudget } : {}),

package/dist/tools/suggest-plan.d.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+import type { ToolDefinition } from '../types.js';
+declare const params: z.ZodObject<{
+    reason: z.ZodString;
+}, z.core.$strip>;
+export interface SuggestPlanResult {
+    /** True when the chat will ask the person; the model should then stop. */
+    suggested: boolean;
+    reason?: string;
+    note: string;
+}
+/**
+ * `suggest_plan`: the model says a request is big or unclear enough to plan before changing anything. It only signals.
+ * The chat reads the result after the run and asks the person ("Plan first / Just do it"); "Just do it" runs the request
+ * again with `planDeclined` set, so the model cannot ask twice. Where no chat can ask, it says to carry on.
+ */
+export declare const suggestPlanTool: ToolDefinition<z.infer<typeof params>, SuggestPlanResult>;
+export {};

package/dist/tools/suggest-plan.js

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+const params = z.object({
+    reason: z.string().min(1).describe('One sentence on why this needs a plan first, for the person to read.'),
+});
+/**
+ * `suggest_plan`: the model says a request is big or unclear enough to plan before changing anything. It only signals.
+ * The chat reads the result after the run and asks the person ("Plan first / Just do it"); "Just do it" runs the request
+ * again with `planDeclined` set, so the model cannot ask twice. Where no chat can ask, it says to carry on.
+ */
+export const suggestPlanTool = {
+    name: 'suggest_plan',
+    description: 'Suggest planning first when a request asks for a whole system or feature, a redesign or rewrite, or work of more than about ten steps or five files. ' +
+        'The person is asked whether to plan first. Call it as your first action, before reading or editing anything, then stop and reply with one short sentence. Not for a simple edit, a question, or when they asked for a plan or told you to just do it.',
+    parameters: params,
+    execute: async (args, ctx) => {
+        if (ctx.planDeclined) {
+            return { suggested: false, note: 'The person already chose to go ahead without a plan. Carry on with the task.' };
+        }
+        if (!ctx.suggestPlan) {
+            return { suggested: false, note: 'Nobody can be asked here. Carry on with the task, and state your plan in a sentence or two first.' };
+        }
+        return {
+            suggested: true,
+            reason: args.reason,
+            note: 'The person is being asked whether to plan first. Stop now: do not change any file or run any command, and reply with one short sentence saying you suggested planning first.',
+        };
+    },
+};