@ikarmic/forge-core 5.0.0 → 5.1.1

package/dist/tools/sub-agent.js

@@ -1,7 +1,10 @@
 import { z } from 'zod';
+import { registeredAgent, registeredAgents } from '../agents/agent-files.js';
 import { Agent } from '../agent/agent.js';
+import { applyResolved, resolveModelAlias } from '../model-alias.js';
 import { WorktreeError, WorktreeManager } from '../worktree/index.js';
 import { BUILTIN_TOOLS } from './index.js';
+import { READ_ONLY_TOOLS } from './read-only.js';
 import { resolveAndCheckPath } from './shared.js';
 const params = z.object({
     /** The task for the sub-agent to perform. Free-form text. */
@@ -10,6 +13,13 @@ const params = z.object({
         .min(1)
         .max(20_000)
         .describe('Plain-English task for the sub-agent to perform.'),
+    /** Name of an agent file (`.forge/agents/<name>.md`) to run as: its prompt, tools, model and step cap. */
+    agent: z
+        .string()
+        .min(1)
+        .max(64)
+        .optional()
+        .describe('Run as the named agent defined in .forge/agents (its prompt, tools and model). Omit for a general helper.'),
     /** Hard cap on iterations for the sub-agent. Default 10. */
     max_iterations: z
         .number()
@@ -81,6 +91,14 @@ const params = z.object({
         .boolean()
         .optional()
         .describe('When use_worktree is true: also delete the auto-created branch alongside the worktree (skipped if another worktree still uses it). Default true. v2.14.'),
+    /**
+     * 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
+        .boolean()
+        .optional()
+        .describe('Start the sub-agent and return immediately with an id; keep working, then collect the answer with sub_agent_wait. Use it for independent work that does not block your next step. Default false.'),
 });
 const DEFAULT_MAX_ITERATIONS = 10;
 /**
@@ -89,7 +107,7 @@ 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']);
+const FORBIDDEN_TOOLS = new Set(['sub_agent', 'sub_agent_wait']);
 /**
  * Delegate a task to a child agent. The child runs synchronously and its
  * final text + run statistics are returned to the parent. Useful for
@@ -122,140 +140,210 @@ export const subAgentTool = {
             throw new Error(`Invalid sub_agent arguments: ${parsed.error.message}`);
         }
         const valid = parsed.data;
-        const maxIterations = Math.min(valid.max_iterations ?? DEFAULT_MAX_ITERATIONS, 50);
-        // Security: `cwd` becomes the CHILD agent's own sandbox root: an
-        // unvalidated override would let a caller point the child anywhere on
-        // disk (e.g. cwd: "C:\\Users\\victim\\Documents") with none of the
-        // approval gating `run_command`/`sub_agent` itself otherwise gets.
-        // resolveAndCheckPath resolves relative to the parent's own `ctx.cwd`
-        // and throws if the result escapes it (or violates `ctx.policy`),
-        // which matches this tool's documented intent: "operate on a
-        // subdirectory": while still accepting the common case.
-        const baseCwd = valid.cwd ? resolveAndCheckPath(valid.cwd, ctx) : ctx.cwd;
-        const auto = valid.auto ?? false;
-        // Worktree setup. We do this *before* constructing the child Agent
-        // so the child runs with the worktree path as its cwd. On any
-        // error during creation, we fall back to plain cwd mode with a
-        // stderr warning: the user gets a working sub-agent instead of
-        // an opaque failure.
-        let worktreeInfo;
-        let manager;
-        if (valid.use_worktree) {
-            const repoRoot = await WorktreeManager.resolveRepoRoot(baseCwd);
-            if (!repoRoot) {
-                // Not a git repo: warn but proceed without isolation. Better
-                // than failing outright; the user can fix the repo separately.
-                ctx.onProgress?.(`sub_agent: use_worktree requested but ${baseCwd} is not a git repo; running without isolation`);
+        const agentDef = valid.agent ? registeredAgent(valid.agent) : undefined;
+        if (valid.agent && !agentDef) {
+            const known = registeredAgents().map((a) => a.name);
+            throw new Error(`Unknown agent "${valid.agent}". ${known.length ? `Known agents: ${known.join(', ')}.` : 'No agents are defined in .forge/agents.'}`);
+        }
+        if (valid.background && ctx.background) {
+            // The child gets its own abort signal (the person stops it from the strip) and reports to the strip, not to the
+            // run that started it, which may be over by the time the child speaks.
+            const { abortSignal: _parentSignal, onChildProgress: _progress, onProgress: _line, ...rest } = ctx;
+            const started = ctx.background.start({
+                task: valid.task,
+                agent: valid.agent,
+                run: (signal) => runSubAgent(valid, agentDef, { ...rest, abortSignal: signal }),
+            });
+            return {
+                started: true,
+                id: started.id,
+                task: valid.task,
+                message: `Started background agent ${started.id}. Carry on with other work; call sub_agent_wait to collect its answer. Do not start it again.`,
+            };
+        }
+        return runSubAgent(valid, agentDef, ctx);
+    },
+};
+/** One child run, to completion: worktree setup, the child agent, cleanup, and the result. */
+async function runSubAgent(valid, agentDef, ctx) {
+    // Security: `cwd` becomes the CHILD agent's own sandbox root: an
+    // unvalidated override would let a caller point the child anywhere on
+    // disk (e.g. cwd: "C:\\Users\\victim\\Documents") with none of the
+    // approval gating `run_command`/`sub_agent` itself otherwise gets.
+    // resolveAndCheckPath resolves relative to the parent's own `ctx.cwd`
+    // and throws if the result escapes it (or violates `ctx.policy`),
+    // which matches this tool's documented intent: "operate on a
+    // subdirectory": while still accepting the common case.
+    const baseCwd = valid.cwd ? resolveAndCheckPath(valid.cwd, ctx) : ctx.cwd;
+    const auto = valid.auto ?? false;
+    // Worktree setup. We do this *before* constructing the child Agent
+    // so the child runs with the worktree path as its cwd. On any
+    // error during creation, we fall back to plain cwd mode with a
+    // stderr warning: the user gets a working sub-agent instead of
+    // an opaque failure.
+    let worktreeInfo;
+    let manager;
+    if (valid.use_worktree) {
+        const repoRoot = await WorktreeManager.resolveRepoRoot(baseCwd);
+        if (!repoRoot) {
+            // Not a git repo: warn but proceed without isolation. Better
+            // than failing outright; the user can fix the repo separately.
+            ctx.onProgress?.(`sub_agent: use_worktree requested but ${baseCwd} is not a git repo; running without isolation`);
+        }
+        else {
+            try {
+                manager = new WorktreeManager(repoRoot);
+                // Clean up any leftover worktrees from a previous crashed
+                // session before we allocate a new one. Best-effort.
+                await manager.pruneStale();
+                worktreeInfo = await manager.create({
+                    ...(valid.worktree_label ? { label: valid.worktree_label } : {}),
+                });
+                ctx.onProgress?.(`sub_agent: isolated in worktree ${worktreeInfo.path} (branch ${worktreeInfo.branch})`);
             }
-            else {
-                try {
-                    manager = new WorktreeManager(repoRoot);
-                    // Clean up any leftover worktrees from a previous crashed
-                    // session before we allocate a new one. Best-effort.
-                    await manager.pruneStale();
-                    worktreeInfo = await manager.create({
-                        ...(valid.worktree_label ? { label: valid.worktree_label } : {}),
-                    });
-                    ctx.onProgress?.(`sub_agent: isolated in worktree ${worktreeInfo.path} (branch ${worktreeInfo.branch})`);
+            catch (err) {
+                if (err instanceof WorktreeError) {
+                    ctx.onProgress?.(`sub_agent: worktree setup failed (${err.message}); running without isolation`);
                 }
-                catch (err) {
-                    if (err instanceof WorktreeError) {
-                        ctx.onProgress?.(`sub_agent: worktree setup failed (${err.message}); running without isolation`);
-                    }
-                    else {
-                        throw err;
-                    }
+                else {
+                    throw err;
                 }
             }
         }
-        const cwd = worktreeInfo ? worktreeInfo.path : baseCwd;
-        const toolsAllowed = BUILTIN_TOOLS.filter((t) => !FORBIDDEN_TOOLS.has(t.name));
-        // The sub-agent inherits our system prompt by default; users can override
-        // via the AGENT_CONFIG system prompt if needed. For the v1 we keep the
-        // child on the same system prompt so its behavior matches the parent's.
-        const child = new Agent({
-            model: ctx.parentModel ?? fallbackModel(),
-            cwd,
-            auto,
-            maxIterations,
-            disableBuiltins: false,
-            // The child's toolset is the standard built-in set (without sub_agent).
-            extraTools: toolsAllowed,
+    }
+    const cwd = worktreeInfo ? worktreeInfo.path : baseCwd;
+    const setup = childSetupFor(agentDef, BUILTIN_TOOLS, ctx, valid.max_iterations);
+    const maxIterations = setup.maxIterations;
+    // The sub-agent inherits our system prompt by default; users can override
+    // via the AGENT_CONFIG system prompt if needed. For the v1 we keep the
+    // child on the same system prompt so its behavior matches the parent's.
+    const child = new Agent(childAgentConfig({ ...setup, maxIterations }, ctx, cwd, auto));
+    const toolsUsed = [];
+    const started = Date.now();
+    let result;
+    try {
+        result = await child.run({
+            task: valid.task,
+            ...(ctx.abortSignal ? { abortSignal: ctx.abortSignal } : {}),
+            onEvent: (event) => {
+                if (event.type === 'tool_call') {
+                    toolsUsed.push(event.name);
+                }
+                // Stream a compact progress line through the parent's context so the
+                // user can see the child is making progress in interactive mode.
+                ctx.onChildProgress?.({
+                    tool: 'sub_agent',
+                    task: valid.task,
+                    event,
+                });
+            },
         });
-        const toolsUsed = [];
-        const started = Date.now();
-        let result;
-        try {
-            result = await child.run({
-                task: valid.task,
-                onEvent: (event) => {
-                    if (event.type === 'tool_call') {
-                        toolsUsed.push(event.name);
-                    }
-                    // Stream a compact progress line through the parent's context so the
-                    // user can see the child is making progress in interactive mode.
-                    ctx.onChildProgress?.({
-                        tool: 'sub_agent',
-                        task: valid.task,
-                        event,
-                    });
-                },
-            });
-        }
-        finally {
-            // Best-effort cleanup. We always try to remove the worktree,
-            // even on error / abort, so a crashed sub-agent doesn't leak a
-            // directory. Force=true so uncommitted changes don't block us.
-            //
-            // v2.14: also delete the auto-created `forge/<label>-<sha>`
-            // branch unless the caller explicitly turned it off. Most
-            // sub-agents finish their work cleanly, so leaving the branch
-            // behind is pure clutter. The branch-deletion logic in
-            // `WorktreeManager.remove` is safety-checked: it refuses to
-            // delete a branch that another worktree still uses, so two
-            // concurrent sub-agents on the same branch won't collide.
-            if (manager && worktreeInfo) {
-                // Optional with z.boolean().optional() → default true when
-                // the caller omits the key. Using `.default(true)` on the
-                // schema would mismatch ToolDefinition<TArgs>'s expected
-                // input type (the schema's input side stays `boolean |
-                // undefined` while the inferred output becomes `boolean`),
-                // so we keep the default in code.
-                const cleanupBranch = valid.cleanup_branch ?? true;
-                try {
-                    const result = await manager.remove(worktreeInfo.path, {
-                        force: true,
-                        deleteBranch: cleanupBranch,
-                    });
-                    if (cleanupBranch && result.branchDeleted && ctx.onProgress) {
-                        ctx.onProgress(`sub_agent: removed worktree and branch ${result.branch}`);
-                    }
-                    else if (cleanupBranch && !result.branchDeleted && ctx.onProgress) {
-                        ctx.onProgress(`sub_agent: removed worktree (kept branch ${result.branch ?? '(detached)'}: still in use)`);
-                    }
+    }
+    finally {
+        // Best-effort cleanup. We always try to remove the worktree,
+        // even on error / abort, so a crashed sub-agent doesn't leak a
+        // directory. Force=true so uncommitted changes don't block us.
+        //
+        // v2.14: also delete the auto-created `forge/<label>-<sha>`
+        // branch unless the caller explicitly turned it off. Most
+        // sub-agents finish their work cleanly, so leaving the branch
+        // behind is pure clutter. The branch-deletion logic in
+        // `WorktreeManager.remove` is safety-checked: it refuses to
+        // delete a branch that another worktree still uses, so two
+        // concurrent sub-agents on the same branch won't collide.
+        if (manager && worktreeInfo) {
+            // Optional with z.boolean().optional() → default true when
+            // the caller omits the key. Using `.default(true)` on the
+            // schema would mismatch ToolDefinition<TArgs>'s expected
+            // input type (the schema's input side stays `boolean |
+            // undefined` while the inferred output becomes `boolean`),
+            // so we keep the default in code.
+            const cleanupBranch = valid.cleanup_branch ?? true;
+            try {
+                const result = await manager.remove(worktreeInfo.path, {
+                    force: true,
+                    deleteBranch: cleanupBranch,
+                });
+                if (cleanupBranch && result.branchDeleted && ctx.onProgress) {
+                    ctx.onProgress(`sub_agent: removed worktree and branch ${result.branch}`);
                 }
-                catch (cleanupErr) {
-                    // Don't mask the agent's actual error with a cleanup error.
-                    // Just surface it through onProgress so the user can see it.
-                    ctx.onProgress?.(`sub_agent: warning: failed to remove worktree ${worktreeInfo.path}: ${cleanupErr.message}`);
+                else if (cleanupBranch && !result.branchDeleted && ctx.onProgress) {
+                    ctx.onProgress(`sub_agent: removed worktree (kept branch ${result.branch ?? '(detached)'}: still in use)`);
                 }
             }
+            catch (cleanupErr) {
+                // Don't mask the agent's actual error with a cleanup error.
+                // Just surface it through onProgress so the user can see it.
+                ctx.onProgress?.(`sub_agent: warning: failed to remove worktree ${worktreeInfo.path}: ${cleanupErr.message}`);
+            }
         }
-        return {
-            task: valid.task,
-            finalText: result.finalText,
-            iterations: result.iterations,
-            reason: result.reason,
-            inputTokens: result.inputTokens,
-            outputTokens: result.outputTokens,
-            durationMs: Date.now() - started,
-            toolsUsed,
-            ...(worktreeInfo
-                ? { worktreePath: worktreeInfo.path, worktreeBranch: worktreeInfo.branch }
-                : {}),
-        };
-    },
-};
+    }
+    return {
+        task: valid.task,
+        finalText: result.finalText,
+        iterations: result.iterations,
+        reason: result.reason,
+        inputTokens: result.inputTokens,
+        outputTokens: result.outputTokens,
+        durationMs: Date.now() - started,
+        toolsUsed,
+        ...(worktreeInfo
+            ? { worktreePath: worktreeInfo.path, worktreeBranch: worktreeInfo.branch }
+            : {}),
+    };
+}
+/**
+ * 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 function childSetupFor(def, tools, ctx, requestedIterations) {
+    const denied = new Set([...FORBIDDEN_TOOLS, ...(def?.deny ?? [])]);
+    const allow = def && def.tools.length > 0 ? new Set(def.tools) : undefined;
+    const base = childModelFor(ctx);
+    let model = base;
+    if (def?.model)
+        model = applyResolved(base, resolveModelAlias(def.model, undefined, base.provider));
+    if (def?.temperature !== undefined)
+        model = { ...model, temperature: def.temperature };
+    return {
+        tools: tools.filter((t) => !denied.has(t.name) && (!allow || allow.has(t.name))),
+        model,
+        maxIterations: Math.min(requestedIterations ?? def?.steps ?? DEFAULT_MAX_ITERATIONS, 50),
+        ...(def?.prompt ? { systemPrompt: def.prompt } : {}),
+    };
+}
+/**
+ * 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 function childAgentConfig(setup, ctx, cwd, auto) {
+    return {
+        model: setup.model,
+        cwd,
+        auto,
+        maxIterations: setup.maxIterations,
+        ...(setup.systemPrompt ? { systemPrompt: setup.systemPrompt } : {}),
+        // A child has no one to ask, so without this every tool that needs approval is refused, even reading a folder.
+        autoApproveTools: childAutoApprove(ctx),
+        ...(ctx.permissionRules ? { permissionRules: ctx.permissionRules } : {}),
+        ...(ctx.toolSandbox ? { toolSandbox: ctx.toolSandbox } : {}),
+        // 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 } : {}),
+        // The child's toolset is the built-in set minus sub_agent, narrowed by the agent file when one is named.
+        disableBuiltins: true,
+        extraTools: setup.tools,
+    };
+}
+/** What a child runs without asking: what the parent does, else the read-only tools. Destructive tools still never run unasked. */
+export function childAutoApprove(ctx) {
+    return ctx.autoApproveTools ? [...ctx.autoApproveTools] : [...READ_ONLY_TOOLS];
+}
+/** The configured sub-agent model, else the parent's, else a last-resort default. */
+export function childModelFor(ctx) {
+    return ctx.subAgentModel ?? ctx.parentModel ?? fallbackModel();
+}
 function fallbackModel() {
     // Best-effort: use whatever the SDK resolves from env. The tool requires
     // a model config to construct an Agent; in practice the parent's config

package/dist/tools/text-encoding.d.ts

@@ -0,0 +1,10 @@
+export type TextEncoding = 'utf8' | 'utf8-bom' | 'utf16le' | 'utf16be';
+/**
+ * Decode a file's bytes by its byte-order mark. Without one the file is read as UTF-8. The mark itself is not part
+ * of the text, and `encodeText` puts it back, so an edit never changes the encoding of a file.
+ */
+export declare function decodeText(buf: Buffer): {
+    text: string;
+    encoding: TextEncoding;
+};
+export declare function encodeText(text: string, encoding: TextEncoding): Buffer;

package/dist/tools/text-encoding.js

@@ -0,0 +1,40 @@
+/**
+ * Decode a file's bytes by its byte-order mark. Without one the file is read as UTF-8. The mark itself is not part
+ * of the text, and `encodeText` puts it back, so an edit never changes the encoding of a file.
+ */
+export function decodeText(buf) {
+    if (buf.length >= 3 && buf[0] === 0xef && buf[1] === 0xbb && buf[2] === 0xbf)
+        return { text: buf.subarray(3).toString('utf8'), encoding: 'utf8-bom' };
+    if (buf.length >= 2 && buf[0] === 0xff && buf[1] === 0xfe)
+        return { text: buf.subarray(2).toString('utf16le'), encoding: 'utf16le' };
+    if (buf.length >= 2 && buf[0] === 0xfe && buf[1] === 0xff) {
+        const body = Buffer.from(buf.subarray(2));
+        // Swap each byte pair to little endian, then decode.
+        for (let i = 0; i + 1 < body.length; i += 2) {
+            const a = body[i];
+            body[i] = body[i + 1];
+            body[i + 1] = a;
+        }
+        return { text: body.toString('utf16le'), encoding: 'utf16be' };
+    }
+    return { text: buf.toString('utf8'), encoding: 'utf8' };
+}
+export function encodeText(text, encoding) {
+    switch (encoding) {
+        case 'utf8-bom':
+            return Buffer.concat([Buffer.from([0xef, 0xbb, 0xbf]), Buffer.from(text, 'utf8')]);
+        case 'utf16le':
+            return Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from(text, 'utf16le')]);
+        case 'utf16be': {
+            const body = Buffer.from(text, 'utf16le');
+            for (let i = 0; i + 1 < body.length; i += 2) {
+                const a = body[i];
+                body[i] = body[i + 1];
+                body[i + 1] = a;
+            }
+            return Buffer.concat([Buffer.from([0xfe, 0xff]), body]);
+        }
+        default:
+            return Buffer.from(text, 'utf8');
+    }
+}

package/dist/tools/todo.d.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import type { TodoItem, ToolDefinition } from '../types.js';
+/**
+ * The agent's own checklist for a multi-step task. `todo_write` replaces the whole list (one call per update, as
+ * in Kilo), `todo_read` returns it. Neither touches the workspace, so neither asks for approval.
+ */
+declare const writeParams: z.ZodObject<{
+    todos: z.ZodArray<z.ZodObject<{
+        content: z.ZodString;
+        status: z.ZodEnum<["pending", "in_progress", "completed"]>;
+    }, "strip", z.ZodTypeAny, {
+        status: "pending" | "in_progress" | "completed";
+        content: string;
+    }, {
+        status: "pending" | "in_progress" | "completed";
+        content: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    todos: {
+        status: "pending" | "in_progress" | "completed";
+        content: string;
+    }[];
+}, {
+    todos: {
+        status: "pending" | "in_progress" | "completed";
+        content: string;
+    }[];
+}>;
+declare const readParams: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export declare const todoWriteTool: ToolDefinition<z.infer<typeof writeParams>, {
+    todos: TodoItem[];
+}>;
+export declare const todoReadTool: ToolDefinition<z.infer<typeof readParams>, {
+    todos: TodoItem[];
+}>;
+export {};

package/dist/tools/todo.js

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+/**
+ * The agent's own checklist for a multi-step task. `todo_write` replaces the whole list (one call per update, as
+ * in Kilo), `todo_read` returns it. Neither touches the workspace, so neither asks for approval.
+ */
+const writeParams = z.object({
+    todos: z
+        .array(z.object({
+        content: z.string().min(1).max(500).describe('What this step is, in the imperative: "Add the README".'),
+        status: z.enum(['pending', 'in_progress', 'completed']).describe('Exactly one item may be in_progress.'),
+    }))
+        .max(50)
+        .describe('The full list, in order. Replaces the previous list; an empty array clears it.'),
+});
+const readParams = z.object({});
+function store(ctx) {
+    if (!ctx.todos)
+        throw new Error('The todo list is not available in this run.');
+    return ctx.todos;
+}
+export const todoWriteTool = {
+    name: 'todo_write',
+    description: 'Create or update the checklist for a task with several steps. Send the complete list every time; mark one step in_progress and completed steps as you finish them. Skip it for simple one-step tasks.',
+    parameters: writeParams,
+    noApproval: true,
+    execute: async (args, ctx) => {
+        const list = store(ctx);
+        if (args.todos.filter((t) => t.status === 'in_progress').length > 1) {
+            throw new Error('Only one item can be in_progress at a time.');
+        }
+        const todos = args.todos.map((t, i) => ({ id: `todo-${i + 1}`, content: t.content, status: t.status }));
+        list.set(todos);
+        return { todos };
+    },
+};
+export const todoReadTool = {
+    name: 'todo_read',
+    description: 'Read the current checklist for this task.',
+    parameters: readParams,
+    noApproval: true,
+    execute: async (_args, ctx) => ({ todos: [...store(ctx).get()] }),
+};

package/dist/tools/write-file.js

@@ -1,7 +1,8 @@
-import { mkdir, stat, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { z } from 'zod';
 import { resolveAndCheckPath } from './shared.js';
+import { decodeText, encodeText } from './text-encoding.js';
 const params = z.object({
     path: z.string().describe('Path of the file to write, relative to the working directory or absolute.'),
     content: z.string().describe('Full file content to write.'),
@@ -13,17 +14,22 @@ export const writeFileTool = {
     destructive: false,
     execute: async (args, ctx) => {
         const resolved = resolveAndCheckPath(args.path, ctx);
-        const existedBefore = await stat(resolved).then(() => true, (err) => {
-            if (err.code === 'ENOENT')
-                return false;
-            throw err;
-        });
+        // Replacing a file keeps its encoding (a BOM, UTF-16), as edit_file and apply_patch do; a new file is UTF-8.
+        let encoding;
+        try {
+            encoding = decodeText(await readFile(resolved)).encoding;
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+        }
         await mkdir(path.dirname(resolved), { recursive: true });
-        await writeFile(resolved, args.content, 'utf8');
+        const bytes = encodeText(args.content, encoding ?? 'utf8');
+        await writeFile(resolved, bytes);
         return {
             path: resolved,
-            bytes: Buffer.byteLength(args.content, 'utf8'),
-            created: !existedBefore,
+            bytes: bytes.length,
+            created: encoding === undefined,
         };
     },
 };

package/dist/tools/write-tools.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The tools that change files. Anything that lists "the write tools" (read-only modes, plan and ask modes, dry
+ * runs, checkpoints, permission rules) must include every one of these; `tests/write-tools-guard.test.ts` scans
+ * the code for lists that do not. Add a new file-changing tool here and in that scan's failures.
+ */
+export declare const FILE_WRITE_TOOL_NAMES: readonly ["write_file", "edit_file", "edit_notebook", "apply_patch"];
+/**
+ * The files a tool call works on: every file of an `apply_patch` (its paths are inside the patch text), else the
+ * call's `path`. Anything that reacts to "a file was written or read" (auto-lint, steering, changed-file lists) uses
+ * this, never `args.path` alone.
+ */
+export declare function filesTouchedBy(toolName: string, args: unknown): string[];

package/dist/tools/write-tools.js

@@ -0,0 +1,18 @@
+import { patchedPaths } from './apply-patch.js';
+/**
+ * The tools that change files. Anything that lists "the write tools" (read-only modes, plan and ask modes, dry
+ * runs, checkpoints, permission rules) must include every one of these; `tests/write-tools-guard.test.ts` scans
+ * the code for lists that do not. Add a new file-changing tool here and in that scan's failures.
+ */
+export const FILE_WRITE_TOOL_NAMES = ['write_file', 'edit_file', 'edit_notebook', 'apply_patch'];
+/**
+ * The files a tool call works on: every file of an `apply_patch` (its paths are inside the patch text), else the
+ * call's `path`. Anything that reacts to "a file was written or read" (auto-lint, steering, changed-file lists) uses
+ * this, never `args.path` alone.
+ */
+export function filesTouchedBy(toolName, args) {
+    const a = (args ?? {});
+    if (toolName === 'apply_patch')
+        return typeof a.patch === 'string' ? patchedPaths(a.patch) : [];
+    return typeof a.path === 'string' ? [a.path] : [];
+}