pi-better-subagents 0.6.0 → 0.7.0

package/shared-task-apply-patch.ts

@@ -0,0 +1,409 @@
+// Generated from packages/task-sandbox/apply-patch.ts. Do not edit directly.
+/**
+ * A guarded `apply_patch`: the Codex patch format, applied only through the
+ * task's guarded file operations.
+ *
+ * Same tool name, parameter schema and patch format as the Codex tool (and
+ * `@vanillagreen/pi-codex-minimal-tools`, MIT), so models' habits work. The
+ * implementation is this harness's own: it never touches the filesystem
+ * directly, so the Project files / Outside project levels, credential rules and
+ * protected paths govern it exactly as they govern write, edit and bash.
+ *
+ * The whole patch is validated first (syntax, file rules, every hunk against
+ * the current content). Only then is anything written, one whole file at a
+ * time, so no file is ever left half-patched. A failure during the write phase
+ * restores what it can and reports exactly what was and was not applied.
+ */
+import { dirname, isAbsolute, resolve } from "node:path";
+
+export type PatchAction =
+    | { kind: "add"; path: string; lines: string[] }
+    | { kind: "delete"; path: string }
+    | { kind: "update"; path: string; moveTo?: string; hunks: PatchHunk[] };
+
+export interface PatchHunk {
+    /** Text after `@@ `: a line to find before this hunk's context. */
+    anchor?: string;
+    /** Lines with their one-character prefix: " " context, "-" removed, "+" added. */
+    lines: string[];
+    /** `*** End of File`: the hunk's context must end at the file's last line. */
+    endOfFile: boolean;
+}
+
+const BEGIN = "*** Begin Patch";
+const END = "*** End Patch";
+const ADD = "*** Add File: ";
+const DELETE = "*** Delete File: ";
+const UPDATE = "*** Update File: ";
+const MOVE = "*** Move to: ";
+const EOF_MARKER = "*** End of File";
+
+export class PatchError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = "PatchError";
+    }
+}
+
+function isHeader(line: string): boolean {
+    const t = line.trim();
+    return t === END || t.startsWith(ADD) || t.startsWith(DELETE) || t.startsWith(UPDATE);
+}
+
+function headerPath(line: string, prefix: string, at: number): string {
+    const path = line.trim().slice(prefix.length).trim();
+    if (!path) throw new PatchError(`Line ${at}: '${prefix.trim()}' needs a path.`);
+    return path;
+}
+
+/** Parse Codex patch text. Throws a PatchError naming the offending line. */
+export function parsePatch(input: string): PatchAction[] {
+    if (typeof input !== "string" || !input.trim()) throw new PatchError("apply_patch needs a non-empty patch in `input`.");
+    const lines = input.replace(/\r\n?/g, "\n").split("\n");
+    let i = 0;
+    while (i < lines.length && !lines[i]!.trim()) i++;
+    if (lines[i]?.trim() !== BEGIN) throw new PatchError(`The patch must start with '${BEGIN}'.`);
+    i++;
+    const actions: PatchAction[] = [];
+    let ended = false;
+    while (i < lines.length) {
+        const line = lines[i]!;
+        const at = i + 1;
+        const trimmed = line.trim();
+        if (trimmed === END) { ended = true; i++; break; }
+        if (!trimmed) { i++; continue; }
+        if (trimmed.startsWith(ADD)) {
+            const path = headerPath(line, ADD, at);
+            const body: string[] = [];
+            let bare = 0; // Trailing bare empty lines separate sections; inner ones are empty lines.
+            i++;
+            while (i < lines.length && !isHeader(lines[i]!)) {
+                const bodyLine = lines[i]!;
+                if (bodyLine === "") { body.push(""); bare++; i++; continue; }
+                if (!bodyLine.startsWith("+")) throw new PatchError(`Line ${i + 1}: every line of an added file starts with '+' (${path}).`);
+                body.push(bodyLine.slice(1));
+                bare = 0;
+                i++;
+            }
+            body.splice(body.length - bare);
+            actions.push({ kind: "add", path, lines: body });
+        } else if (trimmed.startsWith(DELETE)) {
+            actions.push({ kind: "delete", path: headerPath(line, DELETE, at) });
+            i++;
+        } else if (trimmed.startsWith(UPDATE)) {
+            const path = headerPath(line, UPDATE, at);
+            i++;
+            let moveTo: string | undefined;
+            if (i < lines.length && lines[i]!.trim().startsWith(MOVE)) {
+                moveTo = headerPath(lines[i]!, MOVE, i + 1);
+                i++;
+            }
+            const hunks: PatchHunk[] = [];
+            let current: PatchHunk | undefined;
+            let bare = 0; // Trailing bare empty lines: separators unless more hunk lines follow.
+            while (i < lines.length && !isHeader(lines[i]!)) {
+                const bodyLine = lines[i]!;
+                if (bodyLine.startsWith("@@")) {
+                    if (current) current.lines.splice(current.lines.length - bare);
+                    bare = 0;
+                    const anchor = bodyLine.slice(2).trim();
+                    current = { ...(anchor ? { anchor } : {}), lines: [], endOfFile: false };
+                    hunks.push(current);
+                } else if (bodyLine.trim() === EOF_MARKER) {
+                    if (!current) throw new PatchError(`Line ${i + 1}: '${EOF_MARKER}' outside a hunk in ${path}.`);
+                    current.lines.splice(current.lines.length - bare);
+                    bare = 0;
+                    current.endOfFile = true;
+                } else {
+                    if (!current) { current = { lines: [], endOfFile: false }; hunks.push(current); }
+                    else if (current.endOfFile && bodyLine !== "") throw new PatchError(`Line ${i + 1}: lines after '${EOF_MARKER}' in ${path}.`);
+                    if (bodyLine === "") {
+                        // A bare empty line is an empty context line (models often drop the space).
+                        if (!current.endOfFile) { current.lines.push(" "); bare++; }
+                    } else if (" +-".includes(bodyLine[0]!)) {
+                        current.lines.push(bodyLine);
+                        bare = 0;
+                    } else throw new PatchError(`Line ${i + 1}: hunk lines start with ' ', '+' or '-' (${path}).`);
+                }
+                i++;
+            }
+            if (current) current.lines.splice(current.lines.length - bare);
+            if (hunks.some((hunk) => hunk.lines.length === 0)) throw new PatchError(`Empty hunk in ${path}.`);
+            if (!hunks.length && !moveTo) throw new PatchError(`'${UPDATE.trim()} ${path}' has no changes.`);
+            actions.push({ kind: "update", path, ...(moveTo ? { moveTo } : {}), hunks });
+        } else {
+            throw new PatchError(`Line ${at}: expected '${ADD.trim()}', '${UPDATE.trim()}', '${DELETE.trim()}' or '${END}', got: ${line.slice(0, 80)}`);
+        }
+    }
+    if (!ended) throw new PatchError(`The patch must end with '${END}'.`);
+    if (lines.slice(i).some((line) => line.trim())) throw new PatchError(`Text after '${END}'.`);
+    if (!actions.length) throw new PatchError("The patch has no file operations.");
+    return actions;
+}
+
+// ---- content ----------------------------------------------------------------
+
+type Text = { lines: string[]; eol: string; finalNewline: boolean };
+
+function splitText(content: string): Text {
+    const eol = content.includes("\r\n") ? "\r\n" : "\n";
+    const lines = content.split(/\r?\n/);
+    const finalNewline = lines.length > 1 && lines.at(-1) === "";
+    if (finalNewline || content === "") lines.pop();
+    return { lines, eol, finalNewline };
+}
+
+function joinText(text: Text): string {
+    return text.lines.join(text.eol) + (text.finalNewline && text.lines.length ? text.eol : "");
+}
+
+const normalizers: ((line: string) => string)[] = [
+    (line) => line,
+    (line) => line.trimEnd(),
+    (line) => line.trim(),
+    // Typographic punctuation models sometimes substitute for ASCII.
+    (line) => line.trim().replace(/[‐-―−]/g, "-").replace(/[‘’‛]/g, "'")
+        .replace(/[“”‟]/g, "\"").replace(/[  -   　]/g, " "),
+];
+
+/** First index at or after `from` where `needle` matches, trying stricter comparisons first. */
+function seek(lines: string[], needle: string[], from: number, endOfFile: boolean): number {
+    if (!needle.length) return endOfFile ? lines.length : -1;
+    for (const normalize of normalizers) {
+        const want = needle.map(normalize);
+        const matches = (start: number) => want.every((line, k) => normalize(lines[start + k]!) === line);
+        if (endOfFile) {
+            const start = lines.length - needle.length;
+            if (start >= from && matches(start)) return start;
+            continue;
+        }
+        for (let start = from; start + needle.length <= lines.length; start++) if (matches(start)) return start;
+    }
+    return -1;
+}
+
+/** Apply every hunk to `content` in order, or throw naming the hunk that does not fit. */
+export function applyHunks(content: string, hunks: readonly PatchHunk[], path: string): string {
+    const text = splitText(content);
+    let cursor = 0;
+    hunks.forEach((hunk, index) => {
+        const label = `hunk ${index + 1} of ${path}`;
+        if (hunk.anchor !== undefined) {
+            const found = seek(text.lines, [hunk.anchor], cursor, false);
+            if (found < 0) throw new PatchError(`${label}: could not find the '@@ ${hunk.anchor}' line.`);
+            cursor = found + 1;
+        }
+        const before = hunk.lines.filter((line) => line[0] !== "+").map((line) => line.slice(1));
+        const after = hunk.lines.filter((line) => line[0] !== "-").map((line) => line.slice(1));
+        let start: number;
+        if (!before.length) {
+            // Pure insertion: after the anchor, or at the end of the file.
+            start = hunk.anchor !== undefined && !hunk.endOfFile ? cursor : text.lines.length;
+        } else {
+            start = seek(text.lines, before, cursor, hunk.endOfFile);
+            if (start < 0) {
+                const preview = before.slice(0, 3).join("\\n");
+                throw new PatchError(`${label}: the context/removed lines were not found${hunk.endOfFile ? " at the end of the file" : ""} (starting "${preview.slice(0, 120)}").`);
+            }
+        }
+        text.lines.splice(start, before.length, ...after);
+        cursor = start + after.length;
+    });
+    if (!content.length && text.lines.length) text.finalNewline = true;
+    return joinText(text);
+}
+
+// ---- planning and applying --------------------------------------------------
+
+/** The guarded operations the tool is allowed to use. Nothing else touches the disk. */
+export interface PatchFileOperations {
+    /** Rejects with code ENOENT when the file does not exist. */
+    readFile(path: string): Promise<Buffer>;
+    writeFile(path: string, content: string): Promise<void>;
+    mkdir(path: string): Promise<void>;
+    remove(path: string): Promise<void>;
+    /** Policy pre-checks without I/O: throw the refusal the operation itself would. */
+    checkWrite(path: string): void;
+    checkRemove(path: string): void;
+}
+
+type FileState = { original: string | null; current: string | null };
+type Step = { kind: "write" | "remove"; path: string; original: string | null; content?: string };
+
+export interface ApplyPatchResult {
+    summary: string;
+    changes: { kind: "add" | "update" | "delete" | "move"; path: string; moveTo?: string }[];
+}
+
+function stripPathQuotes(path: string): string {
+    const quoted = /^(["'`]).*\1$/.test(path) ? path.slice(1, -1) : path;
+    return quoted.startsWith("@") ? quoted.slice(1) : quoted;
+}
+
+export function resolvePatchPath(cwd: string, path: string): string {
+    const cleaned = stripPathQuotes(path.trim());
+    return isAbsolute(cleaned) ? resolve(cleaned) : resolve(cwd, cleaned);
+}
+
+function describe(action: PatchAction): string {
+    if (action.kind === "add") return `add ${action.path}`;
+    if (action.kind === "delete") return `delete ${action.path}`;
+    return action.moveTo ? `update ${action.path} → ${action.moveTo}` : `update ${action.path}`;
+}
+
+/**
+ * Validate the whole patch against the guarded operations and current files,
+ * then write it. Throws a PatchError before any write when anything is wrong.
+ */
+export async function applyPatch(input: string, cwd: string, ops: PatchFileOperations): Promise<ApplyPatchResult> {
+    const actions = parsePatch(input);
+    const files = new Map<string, FileState>();
+    const load = async (path: string): Promise<FileState> => {
+        let state = files.get(path);
+        if (state) return state;
+        let original: string | null;
+        try {
+            original = (await ops.readFile(path)).toString("utf8");
+        } catch (error) {
+            if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+            original = null;
+        }
+        state = { original, current: original };
+        files.set(path, state);
+        return state;
+    };
+    const fail = (action: PatchAction, error: unknown): never => {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new PatchError(`apply_patch rejected (${describe(action)}): ${message} Nothing was changed.`);
+    };
+
+    // 1. Validate everything. No write happens in this phase.
+    for (const action of actions) {
+        try {
+            const path = resolvePatchPath(cwd, action.path);
+            if (action.kind === "add") {
+                ops.checkWrite(path);
+                const state = await load(path);
+                state.current = action.lines.length ? action.lines.join("\n") + "\n" : "";
+            } else if (action.kind === "delete") {
+                ops.checkRemove(path);
+                const state = await load(path);
+                if (state.current === null) throw new PatchError(`${action.path} does not exist.`);
+                state.current = null;
+            } else {
+                ops.checkWrite(path);
+                const state = await load(path);
+                if (state.current === null) throw new PatchError(`${action.path} does not exist.`);
+                const updated = action.hunks.length ? applyHunks(state.current, action.hunks, action.path) : state.current;
+                const destination = action.moveTo ? resolvePatchPath(cwd, action.moveTo) : path;
+                if (destination === path) {
+                    state.current = updated;
+                } else {
+                    ops.checkRemove(path);
+                    ops.checkWrite(destination);
+                    const target = await load(destination);
+                    target.current = updated;
+                    state.current = null;
+                }
+            }
+        } catch (error) {
+            fail(action, error);
+        }
+    }
+
+    // 2. Write whole files first, removals last: a failure part-way then leaves
+    // extra files behind rather than losing content.
+    const steps: Step[] = [];
+    for (const [path, state] of files) {
+        if (state.current === state.original) continue;
+        if (state.current !== null) steps.push({ kind: "write", path, original: state.original, content: state.current });
+    }
+    for (const [path, state] of files) {
+        if (state.current === null && state.original !== null) steps.push({ kind: "remove", path, original: state.original });
+    }
+    const done: Step[] = [];
+    try {
+        for (const step of steps) {
+            if (step.kind === "write") {
+                if (step.original === null) await ops.mkdir(dirname(step.path));
+                await ops.writeFile(step.path, step.content!);
+            } else {
+                await ops.remove(step.path);
+            }
+            done.push(step);
+        }
+    } catch (error) {
+        const failed = steps[done.length]!;
+        const restored: string[] = [];
+        const left: string[] = [];
+        for (const step of [...done].reverse()) {
+            try {
+                if (step.original === null) await ops.remove(step.path);
+                else await ops.writeFile(step.path, step.original);
+                restored.push(step.path);
+            } catch (undo) {
+                left.push(`${step.kind === "write" ? (step.original === null ? "created" : "rewrote") : "removed"} ${step.path} (${undo instanceof Error ? undo.message : String(undo)})`);
+            }
+        }
+        const pending = steps.slice(done.length + 1).map((step) => `${step.kind} ${step.path}`);
+        throw new PatchError([
+            `apply_patch failed to ${failed.kind} ${failed.path}: ${error instanceof Error ? error.message : String(error)}`,
+            `Applied then restored: ${restored.join(", ") || "none"}.`,
+            `Still applied (could not restore): ${left.join("; ") || "none"}.`,
+            `Not applied: ${[`${failed.kind} ${failed.path}`, ...pending].join(", ")}.`,
+        ].join("\n"));
+    }
+
+    const changes = actions.map((action) => action.kind === "update" && action.moveTo
+        ? { kind: "move" as const, path: action.path, moveTo: action.moveTo }
+        : { kind: action.kind, path: action.path });
+    return { summary: `Applied patch: ${actions.map(describe).join(", ")}.`, changes };
+}
+
+// ---- tool definition --------------------------------------------------------
+
+export const APPLY_PATCH_TOOL = "apply_patch";
+
+/** Same schema as the Codex tool: one `input` string. */
+export const applyPatchParameters = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        input: { type: "string", description: "Codex apply_patch text beginning with *** Begin Patch and ending with *** End Patch." },
+    },
+    required: ["input"],
+} as const;
+
+/** Every path a patch reads or changes, for serializing with other file tools. */
+export function patchTargets(input: string, cwd: string): string[] {
+    const paths = new Set<string>();
+    for (const action of parsePatch(input)) {
+        paths.add(resolvePatchPath(cwd, action.path));
+        if (action.kind === "update" && action.moveTo) paths.add(resolvePatchPath(cwd, action.moveTo));
+    }
+    return [...paths].sort();
+}
+
+type MutationQueue = <T>(path: string, fn: () => Promise<T>) => Promise<T>;
+
+export function createApplyPatchToolDefinition(cwd: string, ops: PatchFileOperations, queue?: MutationQueue) {
+    return {
+        name: APPLY_PATCH_TOOL,
+        label: "Apply Patch",
+        description: "Apply a Codex-style patch (*** Begin Patch … *** End Patch) with Add File, Update File (optionally *** Move to), and Delete File operations. " +
+            "Paths are relative to the working directory. The patch follows the same sandbox file rules as write and edit, is validated in full before anything is written, and never leaves a file half-patched.",
+        promptSnippet: "Apply Codex-style multi-file patches using the input argument.",
+        promptGuidelines: ["Use apply_patch for multi-file or multi-hunk edits when a Codex-style patch is clearer than separate edit/write calls."],
+        parameters: applyPatchParameters,
+        async execute(_toolCallId: string, params: { input?: unknown }) {
+            if (!params || typeof params.input !== "string") throw new PatchError("apply_patch requires an `input` string.");
+            const input = params.input;
+            // Hold every target's mutation slot so a parallel edit/write cannot interleave.
+            const run = (targets: string[]): Promise<ApplyPatchResult> => queue && targets.length
+                ? queue(targets[0]!, () => run(targets.slice(1)))
+                : applyPatch(input, cwd, ops);
+            const result = await run(patchTargets(input, cwd));
+            return { content: [{ type: "text" as const, text: `${result.summary}\nFiles changed: ${result.changes.length}` }], details: result };
+        },
+    };
+}

package/shared-task-files.ts

@@ -2,12 +2,13 @@
 /** Kernel-confined operations for Pi's built-in file tools. */
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { constants } from "node:fs";
-import { access, mkdir, open, readFile, stat, unlink, writeFile } from "node:fs/promises";
+import { constants, realpathSync } from "node:fs";
+import { access, lstat, mkdir, open, readFile, stat, unlink, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
 import type { ReadOperations, WriteOperations, EditOperations } from "@earendil-works/pi-coding-agent";
 import {
-    canonicalizePath, compileWritePolicy, evaluateReadAccess, evaluateWriteAccess, maybeBuildSandboxCommand,
-    type SandboxWritePolicy,
+    canonicalizePath, compileWritePolicy, evaluateDeleteAccess, evaluateReadAccess, evaluateWriteAccess, maybeBuildSandboxCommand,
+    type CompiledSandboxWritePolicy, type SandboxSeams, type SandboxWritePolicy, type WriteAccessDecision,
 } from "./shared-sandbox-core.ts";
 
 export interface TaskFileController {
@@ -73,6 +74,9 @@ process.stdin.on('end', async () => {
         if (typeof content !== 'string' || Buffer.byteLength(content, 'utf8') > MAX)
           throw Object.assign(new Error('File exceeds 8 MiB operation limit'), {code:'EFBIG'});
         await fs.writeFile(path, content, 'utf8'); break;
+      case 'unlink':
+        if ((await fs.lstat(path)).isDirectory()) throw Object.assign(new Error('Refusing to remove a directory'), {code:'EISDIR'});
+        await fs.unlink(path); break;
       default: throw new Error('Unknown file operation');
     }
     process.stdout.write(JSON.stringify({ok:true, data}));
@@ -82,7 +86,48 @@ process.stdin.on('end', async () => {
   }
 });`;
 
-type Operation = "read" | "mime" | "access-read" | "access-edit" | "mkdir" | "existing-directory" | "write";
+type Operation = "read" | "mime" | "access-read" | "access-edit" | "mkdir" | "existing-directory" | "write" | "unlink";
+
+/** Guarded removal of one file (never a directory). Follows the same launch policy as writes. */
+export interface TaskRemoveOperations {
+    remove(path: string): Promise<void>;
+}
+
+/**
+ * Policy pre-checks with no I/O, so a multi-file tool can validate a whole
+ * request before changing anything. Each throws the same refusal the operation
+ * itself would; unconfined plans allow everything.
+ */
+export interface TaskAccessChecks {
+    write(path: string): void;
+    remove(path: string): void;
+}
+
+function refusal(verb: string, decision: WriteAccessDecision): Error {
+    const detail = !decision.allowed && decision.deniedBy ? ` (protected by ${decision.deniedBy})` : "";
+    return new Error(`Task sandbox refused to ${verb} ${decision.path}: ${decision.allowed ? "" : decision.reason}${detail}.`);
+}
+
+/**
+ * Removing an entry is judged on both its resolved target and its own directory
+ * entry, so a link can neither remove a protected file nor hide a protected entry.
+ * The entry is evaluated without following its final component: the parent is
+ * canonicalized, the leaf is taken literally. Otherwise a link planted in
+ * `~/.ssh` or a sibling repository would be judged by its (deletable) target.
+ */
+export function removeDecision(path: string, policy: CompiledSandboxWritePolicy): WriteAccessDecision {
+    const target = evaluateDeleteAccess(path, policy);
+    if (!target.allowed) return target;
+    const entry = join(canonicalizePath(dirname(path)), basename(path));
+    if (entry === target.path) return target;
+    const literalLeaf: SandboxSeams = {
+        canonicalize: (candidate) => {
+            if (candidate === entry) throw new Error("the leaf entry is judged literally");
+            return realpathSync(candidate);
+        },
+    };
+    return evaluateDeleteAccess(entry, policy, literalLeaf);
+}
 
 function mimeType(data: Buffer): string | null {
     const ascii = (at: number, text: string) => data.toString("ascii", at, at + text.length) === text;
@@ -117,7 +162,7 @@ function mimeType(data: Buffer): string | null {
 }
 
 export function createTaskFileOperations(controller: TaskFileController): {
-    read: ReadOperations; write: WriteOperations; edit: EditOperations;
+    read: ReadOperations; write: WriteOperations; edit: EditOperations; remove: TaskRemoveOperations; check: TaskAccessChecks;
 } {
     async function run(operation: Operation, path: string, content?: string): Promise<Buffer | void> {
         const plan = controller.requireLaunchPlan();
@@ -139,11 +184,18 @@ export function createTaskFileOperations(controller: TaskFileController): {
                     return;
                 case "mkdir": await mkdir(path, { recursive: true }); return;
                 case "write": return writeFile(path, content!, "utf8");
+                case "unlink":
+                    if ((await lstat(path)).isDirectory()) throw Object.assign(new Error("Refusing to remove a directory"), { code: "EISDIR" });
+                    return unlink(path);
             }
         }
 
         const policy = compileWritePolicy(plan.policy);
-        const writing = operation === "write" || operation === "mkdir" || operation === "access-edit";
+        if (operation === "unlink") {
+            const decision = removeDecision(path, policy);
+            if (!decision.allowed) throw refusal("remove", decision);
+        }
+        const writing = operation === "write" || operation === "mkdir" || operation === "access-edit" || operation === "unlink";
         const decision = writing ? evaluateWriteAccess(path, policy) : evaluateReadAccess(path, policy);
         if (!decision.allowed && operation !== "existing-directory") {
             if (operation === "mkdir" && decision.reason === "permission-denied") {
@@ -227,7 +279,17 @@ export function createTaskFileOperations(controller: TaskFileController): {
         });
     }
 
+    const check = (verb: "write" | "remove") => (path: string) => {
+        const plan = controller.requireLaunchPlan();
+        if (!plan.confined) return;
+        const policy = compileWritePolicy(plan.policy);
+        const decision = verb === "write" ? evaluateWriteAccess(path, policy) : removeDecision(path, policy);
+        if (!decision.allowed) throw refusal(verb, decision);
+    };
+
     return {
+        remove: { remove: (path) => run("unlink", path) as Promise<void> },
+        check: { write: check("write"), remove: check("remove") },
         read: {
             readFile: (path) => run("read", path) as Promise<Buffer>,
             access: (path) => run("access-read", path) as Promise<void>,

package/shared-task-sandbox.ts

@@ -11,8 +11,11 @@ import { homedir, tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, parse, resolve, sep } from "node:path";
 import { canonicalizePath, compileWritePolicy, isRemovableUnderWrite, maybeBuildSandboxCommand, type SandboxPermissions } from "./shared-sandbox-core.ts";
 import { createTaskFileOperations, type TaskFileController } from "./shared-task-files.ts";
+import { APPLY_PATCH_TOOL, createApplyPatchToolDefinition } from "./shared-task-apply-patch.ts";
 
 export const TASK_BUILTINS = Object.freeze(["read", "write", "edit", "bash"] as const);
+/** Harness adapters that follow the file rules; each is a task builtin only when the profile enables it. */
+export const GUARDED_TASK_TOOLS = Object.freeze([APPLY_PATCH_TOOL] as const);
 
 /** Loaded code and its installed dependencies must remain task-read-only. */
 export function runtimeCodeRoot(path: string): string {
@@ -165,6 +168,8 @@ export function installTaskTools(pi: ExtensionAPI, options: {
     shellPath?: () => string | undefined;
     trustedSources: readonly string[];
     admitExtensionTool?: (name: string, input: unknown, sourcePath: string | undefined) => boolean;
+    /** Register the guarded apply_patch adapter as a task builtin. */
+    applyPatch?: boolean;
     /** Build the admitted bash definition from the confined operations (default: the SDK bash tool). */
     bashDefinition?: (cwd: string, operations: BashOperations) => ReturnType<typeof createBashToolDefinition>;
 }) {
@@ -188,6 +193,12 @@ export function installTaskTools(pi: ExtensionAPI, options: {
         pi.registerTool(own(createWriteToolDefinition(cwd, { operations: files.write })));
         pi.registerTool(own(createEditToolDefinition(cwd, { operations: files.edit })));
         pi.registerTool(own(options.bashDefinition ? options.bashDefinition(cwd, bash) : createBashToolDefinition(cwd, { operations: bash })));
+        if (options.applyPatch) {
+            pi.registerTool(own(createApplyPatchToolDefinition(cwd, {
+                readFile: files.read.readFile, writeFile: files.write.writeFile, mkdir: files.write.mkdir,
+                remove: files.remove.remove, checkWrite: files.check.write, checkRemove: files.check.remove,
+            }, PiCodingAgent.withFileMutationQueue)) as any);
+        }
     };
     register(options.cwd);
     pi.on("user_bash", () => ({ operations: bash }));