pi-better-subagents 0.2.0 → 0.4.0

package/shared-task-files.ts

@@ -0,0 +1,246 @@
+// Generated from packages/task-sandbox/files.ts. Do not edit directly.
+/** 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 type { ReadOperations, WriteOperations, EditOperations } from "@earendil-works/pi-coding-agent";
+import {
+    canonicalizePath, compileWritePolicy, evaluateReadAccess, evaluateWriteAccess, maybeBuildSandboxCommand,
+    type SandboxWritePolicy,
+} from "./shared-sandbox-core.ts";
+
+export interface TaskFileController {
+    requireLaunchPlan(): { confined: false } | { confined: true; policy: SandboxWritePolicy; profilePath: string };
+}
+
+// The SDK truncates display output after reading. This separate operation cap
+// bounds worker memory and pipe traffic, and rejects rather than truncates files.
+const MAX_FILE_BYTES = 8 * 1024 * 1024;
+const MAX_REQUEST_BYTES = 12 * 1024 * 1024;
+const MAX_RESPONSE_BYTES = 12 * 1024 * 1024;
+
+// Fixed program: tool-supplied path/content are JSON on stdin, never argv/code.
+const FILE_WORKER = String.raw`
+const fs = require('node:fs/promises');
+const { constants } = require('node:fs');
+const MAX = 8 * 1024 * 1024;
+let input = Buffer.alloc(0);
+process.stdin.on('data', chunk => {
+  if (input.length + chunk.length > 12 * 1024 * 1024) {
+    process.stdout.write(JSON.stringify({error:'File operation request exceeds 12 MiB',code:'EFBIG'}));
+    process.exit(1);
+  }
+  input = Buffer.concat([input, chunk]);
+});
+process.stdin.on('end', async () => {
+  try {
+    const { operation, path, content } = JSON.parse(input.toString('utf8'));
+    if (typeof path !== 'string') throw new Error('Invalid file path');
+    let data;
+    switch (operation) {
+      case 'read':
+      case 'mime': {
+        const handle = await fs.open(path, 'r');
+        try {
+          if (operation === 'mime') {
+            const sample = Buffer.alloc(4100);
+            const { bytesRead } = await handle.read(sample, 0, sample.length, 0);
+            data = sample.subarray(0, bytesRead).toString('base64');
+          } else {
+            const chunks = [];
+            let size = 0;
+            for (;;) {
+              const chunk = Buffer.alloc(Math.min(65536, MAX + 1 - size));
+              const { bytesRead } = await handle.read(chunk, 0, chunk.length, null);
+              if (!bytesRead) break;
+              size += bytesRead;
+              if (size > MAX) throw Object.assign(new Error('File exceeds 8 MiB operation limit'), {code:'EFBIG'});
+              chunks.push(chunk.subarray(0, bytesRead));
+            }
+            data = Buffer.concat(chunks, size).toString('base64');
+          }
+        } finally { await handle.close(); }
+        break;
+      }
+      case 'access-read': await fs.access(path, constants.R_OK); break;
+      case 'access-edit': await fs.access(path, constants.R_OK | constants.W_OK); break;
+      case 'existing-directory':
+        if (!(await fs.stat(path)).isDirectory()) throw new Error('Not an existing directory');
+        break;
+      case 'mkdir': await fs.mkdir(path, {recursive:true}); break;
+      case 'write':
+        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;
+      default: throw new Error('Unknown file operation');
+    }
+    process.stdout.write(JSON.stringify({ok:true, data}));
+  } catch (error) {
+    process.stdout.write(JSON.stringify({error: String(error.message || error), code: error.code}));
+    process.exitCode = 1;
+  }
+});`;
+
+type Operation = "read" | "mime" | "access-read" | "access-edit" | "mkdir" | "existing-directory" | "write";
+
+function mimeType(data: Buffer): string | null {
+    const ascii = (at: number, text: string) => data.toString("ascii", at, at + text.length) === text;
+    if (data.length >= 4 && data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff) {
+        return data[3] === 0xf7 ? null : "image/jpeg";
+    }
+    if (data.length >= 16 && data.subarray(0, 8).equals(Buffer.from("89504e470d0a1a0a", "hex")) &&
+        data.readUInt32BE(8) === 13 && ascii(12, "IHDR")) {
+        for (let offset = 8; offset + 8 <= data.length;) {
+            if (ascii(offset + 4, "acTL")) return null;
+            if (ascii(offset + 4, "IDAT")) break;
+            const next = offset + 12 + data.readUInt32BE(offset);
+            if (next <= offset || next > data.length) break;
+            offset = next;
+        }
+        return "image/png";
+    }
+    if (ascii(0, "GIF87a") || ascii(0, "GIF89a")) return "image/gif";
+    if (ascii(0, "RIFF") && ascii(8, "WEBP")) return "image/webp";
+    if (ascii(0, "BM") && data.length >= 30) {
+        const size = data.readUInt32LE(2);
+        const offset = data.readUInt32LE(10);
+        const dib = data.readUInt32LE(14);
+        const planes = dib === 12 ? data.readUInt16LE(22) : data.readUInt16LE(26);
+        const bits = dib === 12 ? data.readUInt16LE(24) : data.readUInt16LE(28);
+        if ((size === 0 || size >= 26) && offset >= 14 + dib && (size === 0 || offset < size) &&
+            (dib === 12 || (dib >= 40 && dib <= 124)) && planes === 1 && [1, 4, 8, 16, 24, 32].includes(bits)) {
+            return "image/bmp";
+        }
+    }
+    return null;
+}
+
+export function createTaskFileOperations(controller: TaskFileController): {
+    read: ReadOperations; write: WriteOperations; edit: EditOperations;
+} {
+    async function run(operation: Operation, path: string, content?: string): Promise<Buffer | void> {
+        const plan = controller.requireLaunchPlan();
+        if (!plan.confined) {
+            switch (operation) {
+                case "read": return readFile(path);
+                case "mime": {
+                    const handle = await open(path, "r");
+                    try {
+                        const sample = Buffer.alloc(4100);
+                        const { bytesRead } = await handle.read(sample, 0, sample.length, 0);
+                        return sample.subarray(0, bytesRead);
+                    } finally { await handle.close(); }
+                }
+                case "access-read": return access(path, constants.R_OK);
+                case "access-edit": return access(path, constants.R_OK | constants.W_OK);
+                case "existing-directory":
+                    if (!(await stat(path)).isDirectory()) throw new Error("Not an existing directory");
+                    return;
+                case "mkdir": await mkdir(path, { recursive: true }); return;
+                case "write": return writeFile(path, content!, "utf8");
+            }
+        }
+
+        const policy = compileWritePolicy(plan.policy);
+        const writing = operation === "write" || operation === "mkdir" || operation === "access-edit";
+        const decision = writing ? evaluateWriteAccess(path, policy) : evaluateReadAccess(path, policy);
+        if (!decision.allowed && operation !== "existing-directory") {
+            if (operation === "mkdir" && decision.reason === "permission-denied") {
+                // SDK write prepares the parent even when it already exists.
+                // Confirm that no-op inside confinement; never grant mkdir.
+                try { await run("existing-directory", path); return; } catch { /* Preserve the original refusal. */ }
+            }
+            const detail = "deniedBy" in decision ? ` (protected by ${decision.deniedBy})` : "";
+            throw new Error(`Task sandbox refused to ${writing ? "write" : "read"} ${decision.path}: ${decision.reason}${detail}.`);
+        }
+        if (operation === "access-edit") {
+            const readable = evaluateReadAccess(path, policy);
+            if (!readable.allowed) throw new Error(`Task sandbox refused to read ${readable.path}: ${readable.reason}.`);
+        }
+        if (content !== undefined && Buffer.byteLength(content, "utf8") > MAX_FILE_BYTES) {
+            throw new Error("File exceeds 8 MiB operation limit");
+        }
+        const payload = Buffer.from(JSON.stringify({ operation, path, content }), "utf8");
+        if (payload.length > MAX_REQUEST_BYTES) throw new Error("File operation request exceeds 12 MiB");
+
+        // Internal helper privilege only: never alter file/credential rules.
+        const helperPolicy: SandboxWritePolicy = {
+            ...plan.policy,
+            permissions: {
+                projectFiles: "read-write", outsideProject: "read", storedCredentials: "read",
+                ...plan.policy.permissions,
+                commands: true, network: false,
+            },
+        };
+        const profilePath = `${plan.profilePath}.${randomUUID()}.files.sb`;
+        let command;
+        try {
+            command = maybeBuildSandboxCommand({
+                execPath: canonicalizePath(process.execPath), execArgs: ["-e", FILE_WORKER], internalHelperExecutable: true,
+                profilePath, policy: helperPolicy,
+            }, { sandboxEnabled: true, explicitSandbox: true });
+        } catch (error) {
+            void unlink(profilePath).catch(() => {});
+            throw error;
+        }
+        if (!command) throw new Error("Task file sandbox backend unavailable");
+
+        return new Promise<Buffer | void>((resolve, reject) => {
+            const child = spawn(command.file, command.fileArgs, {
+                stdio: ["pipe", "pipe", "pipe"],
+                env: { PATH: process.env.PATH ?? "", HOME: plan.policy.home },
+            });
+            const chunks: Buffer[] = [];
+            let size = 0;
+            let stderr = "";
+            let finished = false;
+            const timer = setTimeout(() => child.kill(), 30_000);
+            child.stdout.on("data", (chunk: Buffer) => {
+                size += chunk.length;
+                if (size > MAX_RESPONSE_BYTES) child.kill();
+                else chunks.push(chunk);
+            });
+            child.stderr.on("data", (chunk: Buffer) => { stderr = (stderr + chunk.toString()).slice(-2048); });
+            child.stdin.on("error", () => {}); // An early sandbox failure may close stdin.
+            child.on("error", (error) => {
+                if (!finished) { finished = true; clearTimeout(timer); void unlink(profilePath).catch(() => {}); reject(error); }
+            });
+            child.on("close", (code) => {
+                void unlink(profilePath).catch(() => {});
+                if (finished) return;
+                finished = true;
+                clearTimeout(timer);
+                if (size > MAX_RESPONSE_BYTES) return reject(new Error("File operation response exceeds 12 MiB"));
+                let result: { ok?: boolean; data?: string; error?: string; code?: string };
+                try { result = JSON.parse(Buffer.concat(chunks).toString("utf8")); }
+                catch { return reject(new Error(`Task file sandbox failed (${code}): ${stderr || "no worker response"}`)); }
+                if (!result.ok) {
+                    const error = new Error(result.error ?? `Task file sandbox failed (${code})`) as NodeJS.ErrnoException;
+                    error.code = result.code;
+                    return reject(error);
+                }
+                if (code !== 0) return reject(new Error(`Task file sandbox exited ${code}: ${stderr}`));
+                resolve(result.data === undefined ? undefined : Buffer.from(result.data, "base64"));
+            });
+            child.stdin.end(payload);
+        });
+    }
+
+    return {
+        read: {
+            readFile: (path) => run("read", path) as Promise<Buffer>,
+            access: (path) => run("access-read", path) as Promise<void>,
+            detectImageMimeType: async (path) => mimeType(await run("mime", path) as Buffer),
+        },
+        write: {
+            mkdir: (path) => run("mkdir", path) as Promise<void>,
+            writeFile: (path, content) => run("write", path, content) as Promise<void>,
+        },
+        edit: {
+            readFile: (path) => run("read", path) as Promise<Buffer>,
+            access: (path) => run("access-edit", path) as Promise<void>,
+            writeFile: (path, content) => run("write", path, content) as Promise<void>,
+        },
+    };
+}

package/shared-task-sandbox.ts

@@ -0,0 +1,189 @@
+// Generated from packages/task-sandbox/index.ts. Do not edit directly.
+/** The task boundary: trusted Pi owns the runtime; every admitted task tool uses this executor. */
+import * as PiCodingAgent from "@earendil-works/pi-coding-agent";
+import type { BashOperations, ExtensionAPI } from "@earendil-works/pi-coding-agent";
+const { createBashToolDefinition, createReadToolDefinition, createWriteToolDefinition,
+    createEditToolDefinition, createLocalBashOperations, getShellConfig } = PiCodingAgent;
+import { pathToFileURL } from "node:url";
+import { spawn } from "node:child_process";
+import { accessSync, constants, lstatSync, mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import { canonicalizePath, maybeBuildSandboxCommand } from "./shared-sandbox-core.ts";
+import { createTaskFileOperations, type TaskFileController } from "./shared-task-files.ts";
+
+export const TASK_BUILTINS = Object.freeze(["read", "write", "edit", "bash"] as const);
+
+/** Loaded code and its installed dependencies must remain task-read-only. */
+export function runtimeCodeRoot(path: string): string {
+    const canonical = canonicalizePath(path);
+    let current = dirname(canonical);
+    while (dirname(current) !== current) {
+        if (basename(current) === "node_modules") return current;
+        current = dirname(current);
+    }
+    return dirname(canonical);
+}
+
+export function writableRuntimeAlias(path: string, root: string, permissions: {
+    projectFiles: string; outsideProject: string; storedCredentials: string;
+}): string | undefined {
+    for (let current = resolve(path); dirname(current) !== current; current = dirname(current)) {
+        try {
+            if (!lstatSync(current).isSymbolicLink()) continue;
+            const entry = join(canonicalizePath(dirname(current)), basename(current));
+            accessSync(dirname(entry), constants.W_OK);
+            const inProject = entry === root || entry.startsWith(root + sep);
+            const access = inProject ? permissions.projectFiles : permissions.outsideProject;
+            if (access === "read-write" || permissions.storedCredentials === "read-write") return entry;
+        } catch { /* Nonexistent or OS-protected entries cannot be replaced by the task. */ }
+    }
+    return undefined;
+}
+
+export function harnessRuntimeDirectories(): string[] {
+    const names = ["pi-better-subagents", "pi-better-background-tasks"];
+    const pool = process.env.VITEST_POOL_ID;
+    if (pool && /^\d+$/.test(pool)) names.push(`pi-better-background-tasks-vitest-${pool}`);
+    return names.map((name) => canonicalizePath(join(tmpdir(), name)));
+}
+
+export function ensureHarnessRuntimeDirectories(): string[] {
+    const directories = harnessRuntimeDirectories();
+    for (const path of directories) mkdirSync(path, { recursive: true, mode: 0o700 });
+    return directories;
+}
+
+export function createTaskScratch(): { path: string; anchor: string } {
+    const path = canonicalizePath(mkdtempSync(join(tmpdir(), "pi-task-scratch-")));
+    const anchor = join(path, ".sandbox-anchor");
+    writeFileSync(anchor, "", { flag: "wx", mode: 0o400 });
+    // Denying the anchor also prevents renaming/replacing its parent directory.
+    return { path, anchor };
+}
+
+export function createTaskBashOperations(
+    controller: TaskFileController,
+    shellPath: () => string | undefined = () => undefined,
+): BashOperations {
+    return {
+        async exec(command, cwd, options) {
+            const configuredShell = shellPath();
+            const local = createLocalBashOperations(configuredShell ? { shellPath: configuredShell } : {});
+            const plan = controller.requireLaunchPlan();
+            if (!plan.confined) return local.exec(command, cwd, options);
+            if (plan.policy.permissions?.commands === false) throw new Error("Sandbox: Run commands & applications is Off.");
+            // An explicit path avoids SDK fallback spawning PATH-resolved `which`.
+            const shell = getShellConfig(configuredShell ?? "/bin/bash");
+            const sdkUtils = join(PiCodingAgent.getPackageDir(), "dist", "utils");
+            const { waitForChildProcess } = await import(pathToFileURL(join(sdkUtils, "child-process.js")).href);
+            const { trackDetachedChildPid, untrackDetachedChildPid } = await import(pathToFileURL(join(sdkUtils, "shell.js")).href);
+            if (shell.commandTransport === "stdin") throw new Error("Sandbox: this shell cannot be confined by the available backend.");
+            const scratch = plan.policy.runtimeWrite?.[0];
+            const taskEnv = { ...process.env, ...options.env,
+                ...(scratch ? { TMPDIR: scratch, TMP: scratch, TEMP: scratch } : {}) };
+            const wrapped = maybeBuildSandboxCommand({
+                policy: plan.policy, profilePath: plan.profilePath,
+                execPath: "/usr/bin/env", execArgs: ["-i", "--", ...Object.entries(taskEnv)
+                    .filter((entry): entry is [string, string] => entry[1] !== undefined)
+                    .map(([key, value]) => `${key}=${value}`), shell.shell, ...shell.args, command],
+            }, { sandboxEnabled: true, explicitSandbox: true });
+            if (!wrapped) throw new Error("Sandbox: no task execution backend is available.");
+            if (options.signal?.aborted) throw new Error("aborted");
+            if (options.timeout !== undefined && (!Number.isFinite(options.timeout) || options.timeout <= 0 || options.timeout * 1000 > 2147483647)) {
+                throw new Error("Invalid timeout: must be a positive, supported number of seconds");
+            }
+            // No shell or caller-controlled loader environment runs before the boundary.
+            return new Promise((resolve, reject) => {
+                const child = spawn(wrapped.file, wrapped.fileArgs, { cwd, detached: true,
+                    env: { PATH: "/usr/bin:/bin", HOME: plan.policy.home }, stdio: ["ignore", "pipe", "pipe"] });
+                let timedOut = false;
+                const kill = () => { if (child.pid) { try { process.kill(-child.pid, "SIGKILL"); } catch { child.kill("SIGKILL"); } } };
+                const timer = options.timeout === undefined ? undefined : setTimeout(() => { timedOut = true; kill(); }, options.timeout * 1000);
+                if (child.pid) trackDetachedChildPid(child.pid);
+                const cleanup = () => {
+                    if (child.pid) untrackDetachedChildPid(child.pid);
+                    if (timer) clearTimeout(timer);
+                    options.signal?.removeEventListener("abort", kill);
+                };
+                child.stdout.on("data", options.onData);
+                child.stderr.on("data", options.onData);
+                options.signal?.addEventListener("abort", kill, { once: true });
+                if (options.signal?.aborted) kill();
+                void waitForChildProcess(child).then((exitCode: number | null) => {
+                    cleanup();
+                    if (options.signal?.aborted) reject(new Error("aborted"));
+                    else if (timedOut) reject(new Error(`timeout:${options.timeout}`));
+                    else resolve({ exitCode });
+                }, (error: unknown) => { cleanup(); reject(error); });
+            });
+        },
+    };
+}
+
+/**
+ * Only definitions installed here are admitted as builtins. A distinct schema
+ * identity detects later replacement, including overrides using SDK factories.
+ * Other tool implementations need an explicit, host-owned admission function;
+ * knowing a tool's name or enabling network access never makes it confined.
+ */
+export function installTaskTools(pi: ExtensionAPI, options: {
+    controller: TaskFileController;
+    cwd: string;
+    shellPath?: () => string | undefined;
+    trustedSources: readonly string[];
+    admitExtensionTool?: (name: string, input: unknown, sourcePath: string | undefined) => boolean;
+}) {
+    const { controller } = options;
+    const sourceKey = (path: string) => path.startsWith("<") ? path : canonicalizePath(path);
+    const trustedSources = new Set(options.trustedSources.map(sourceKey));
+    const trustedSource = (path: string | undefined) => path !== undefined && trustedSources.has(sourceKey(path));
+    const files = createTaskFileOperations(controller);
+    const bash = createTaskBashOperations(controller, options.shellPath);
+    const schemas = new Map<string, unknown>();
+    let currentCwd: string | undefined;
+    const register = (cwd: string) => {
+        if (cwd === currentCwd) return;
+        currentCwd = cwd;
+        const own = <T extends { name: string; parameters: object }>(definition: T): T => {
+            const parameters = { ...definition.parameters };
+            schemas.set(definition.name, parameters);
+            return { ...definition, parameters };
+        };
+        pi.registerTool(own(createReadToolDefinition(cwd, { operations: files.read })));
+        pi.registerTool(own(createWriteToolDefinition(cwd, { operations: files.write })));
+        pi.registerTool(own(createEditToolDefinition(cwd, { operations: files.edit })));
+        pi.registerTool(own(createBashToolDefinition(cwd, { operations: bash })));
+    };
+    register(options.cwd);
+    pi.on("user_bash", () => ({ operations: bash }));
+    pi.on("tool_call", (event) => {
+        try {
+            const plan = controller.requireLaunchPlan();
+            if (!plan.confined) return;
+            const tool = pi.getAllTools().find((candidate) => candidate.name === event.toolName);
+            if (schemas.has(event.toolName)) {
+                if (!tool || tool.parameters !== schemas.get(event.toolName) || !trustedSource(tool.sourceInfo?.path)) {
+                    return { block: true, reason: `Sandbox: ${event.toolName} was replaced by an unverified implementation.` };
+                }
+                if (event.toolName === "bash" && plan.policy.permissions?.commands === false) {
+                    return { block: true, reason: "Sandbox: Run commands & applications is Off." };
+                }
+                return;
+            }
+            if (options.admitExtensionTool?.(event.toolName, event.input, tool?.sourceInfo?.path)) return;
+            return { block: true, reason: `Sandbox: ${event.toolName} has no verified task execution adapter. Use a guarded file tool or confined bash command.` };
+        } catch (error) {
+            return { block: true, reason: error instanceof Error ? error.message : String(error) };
+        }
+    });
+    return { register, bash, assertInstalled(names: readonly string[]) {
+        const inventory = pi.getAllTools();
+        for (const name of names) {
+            const tool = inventory.find((candidate) => candidate.name === name);
+            if (!schemas.has(name) || tool?.parameters !== schemas.get(name) || !trustedSource(tool?.sourceInfo?.path)) {
+                throw new Error(`Sandbox: ${name} is missing or was replaced by an unverified implementation.`);
+            }
+        }
+    } };
+}

package/task-guard.ts

@@ -0,0 +1,47 @@
+/** Installed as the final inline extension by the trusted native launcher. */
+import { SettingsManager, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { describeSandboxSupport } from "./shared-sandbox-core.ts";
+import { installTaskTools, TASK_BUILTINS } from "./shared-task-sandbox.ts";
+import { parseTaskPolicy } from "./task-policy.ts";
+import { SANDBOX_POLICY_CHANNEL, SANDBOX_POLICY_REQUEST_CHANNEL } from "./permission-policy.ts";
+
+export default function taskGuard(pi: ExtensionAPI, input: unknown, fatal: (error: unknown) => never): void {
+    const policy = parseTaskPolicy(input);
+    const support = describeSandboxSupport();
+    if (!support.supported) throw new Error(`Task sandbox unavailable: ${support.reason}`);
+    const plan = Object.freeze({
+        confined: true as const, profilePath: policy.profilePath,
+        policy: Object.freeze({ writableRoot: policy.root, home: policy.home, permissions: policy.permissions, denyWrite: policy.denyWrite,
+            runtimeWrite: Object.freeze([policy.scratch]) }),
+    });
+    const controller = Object.freeze({ requireLaunchPlan: () => plan });
+    let shellPath: string | undefined;
+    const boundary = installTaskTools(pi, { controller, cwd: process.cwd(), shellPath: () => shellPath,
+        trustedSources: ["<inline:task-sandbox>"],
+    });
+    const profile = Object.freeze({ enabled: true, ...policy.permissions });
+    const status = Object.freeze({
+        state: "enabled", projectRoot: policy.root, writableRoot: policy.root,
+        denyWrite: policy.denyWrite, platform: process.platform, backend: support.backend, executable: support.executable,
+        permissions: profile, subagentPermissions: profile,
+        readPolicy: "restricted", networkPolicy: policy.permissions.network ? "unrestricted" : "blocked",
+        reason: "Immutable child task policy; Pi runtime operations remain trusted.",
+    });
+    pi.events.on(SANDBOX_POLICY_REQUEST_CHANNEL, () => pi.events.emit(SANDBOX_POLICY_CHANNEL, status));
+    pi.on("session_start", (_event, ctx) => {
+        try {
+            shellPath = SettingsManager.create(ctx.cwd, policy.agentDir, { projectTrusted: false }).getShellPath();
+            boundary.register(ctx.cwd);
+            const selected = policy.tools.filter((name) => (TASK_BUILTINS as readonly string[]).includes(name));
+            boundary.assertInstalled(selected);
+            pi.setActiveTools(selected);
+            const active = new Set(pi.getActiveTools());
+            if (active.size !== selected.length || selected.some((name) => !active.has(name))) {
+                throw new Error("SDK did not activate the guarded tool set; refusing to start the task.");
+            }
+            pi.events.emit(SANDBOX_POLICY_CHANNEL, status);
+            // A typed lifecycle marker, never inferred from assistant prose.
+            process.stdout.write(`${JSON.stringify({ type: "task_sandbox_ready", root: policy.root, tools: selected })}\n`);
+        } catch (error) { fatal(error); }
+    });
+}

package/task-policy.ts

@@ -0,0 +1,97 @@
+/** Immutable launch contract. This file contains policy, never credentials. */
+import { realpathSync, readFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir, tmpdir } from "node:os";
+import * as PiCodingAgent from "@earendil-works/pi-coding-agent";
+import { canonicalizePath, compileWritePolicy, describeSandboxSupport, type SandboxPermissions } from "./shared-sandbox-core.ts";
+import { createTaskScratch, ensureHarnessRuntimeDirectories, runtimeCodeRoot, writableRuntimeAlias } from "./shared-task-sandbox.ts";
+
+export type TaskPolicy = Readonly<{
+    version: 1;
+    root: string;
+    home: string;
+    agentDir: string;
+    profilePath: string;
+    scratch: string;
+    permissions: Readonly<SandboxPermissions>;
+    denyWrite: readonly string[];
+    tools: readonly string[];
+}>;
+
+export const DEFAULT_TASK_PERMISSIONS: Readonly<SandboxPermissions> = Object.freeze({
+    projectFiles: "read-write", outsideProject: "read", storedCredentials: "read", commands: true, network: true,
+});
+
+export function parseTaskPolicy(value: unknown): TaskPolicy {
+    if (!value || typeof value !== "object") throw new Error("Task sandbox policy is missing.");
+    const v = value as Record<string, unknown>;
+    const absolute = (key: string) => {
+        const path = v[key];
+        if (typeof path !== "string" || !isAbsolute(path)) throw new Error(`Task sandbox ${key} must be absolute.`);
+        return path;
+    };
+    if (v.version !== 1 || !v.permissions || typeof v.permissions !== "object") throw new Error("Unsupported task sandbox policy.");
+    const p = v.permissions as Record<string, unknown>;
+    for (const key of ["projectFiles", "outsideProject", "storedCredentials"]) {
+        if (!["off", "read", "read-write"].includes(String(p[key]))) throw new Error(`Invalid task sandbox ${key}.`);
+    }
+    if (typeof p.commands !== "boolean" || typeof p.network !== "boolean") throw new Error("Invalid task sandbox capabilities.");
+    if (!Array.isArray(v.denyWrite) || !v.denyWrite.every((path) => typeof path === "string" && isAbsolute(path))) throw new Error("Invalid task sandbox protected paths.");
+    if (!Array.isArray(v.tools) || !v.tools.every((name) => typeof name === "string" && name.length > 0)) throw new Error("Invalid task sandbox tool selection.");
+    return Object.freeze({
+        version: 1, root: absolute("root"), home: absolute("home"), agentDir: absolute("agentDir"), profilePath: absolute("profilePath"), scratch: absolute("scratch"),
+        permissions: Object.freeze({ ...p } as SandboxPermissions),
+        denyWrite: Object.freeze([...v.denyWrite]), tools: Object.freeze([...v.tools]),
+    });
+}
+
+export function prepareTaskRuntime(options: {
+    root: string; controlDir: string; tools: readonly string[]; piBin: string;
+    permissions?: SandboxPermissions; extensionPaths?: readonly string[]; runtimeRoots?: readonly string[];
+}): { file: string; fileArgs: string[]; policy: TaskPolicy; policyPath: string } {
+    if (typeof PiCodingAgent.getAgentDir !== "function" || typeof PiCodingAgent.getPackageDir !== "function") {
+        throw new Error("Task sandbox requires a supported active Pi SDK; refusing an unguarded child.");
+    }
+    const support = describeSandboxSupport();
+    if (!support.supported) throw new Error(`Task sandbox unavailable: ${support.reason}`);
+    const root = realpathSync(options.root);
+    const home = homedir();
+    if (root === dirname(root) || root === canonicalizePath(home)) throw new Error("Task sandbox requires a project directory, not the filesystem or home root.");
+    const permissions = options.permissions ?? DEFAULT_TASK_PERMISSIONS;
+    const alias = [PiCodingAgent.getAgentDir(), PiCodingAgent.getPackageDir(), tmpdir()]
+        .map((path) => writableRuntimeAlias(path, root, permissions)).find(Boolean);
+    if (alias) throw new Error(`Task sandbox runtime path uses a task-writable symlink (${alias}); restart Pi with canonical runtime paths.`);
+    const runtimeDirectories = ensureHarnessRuntimeDirectories();
+    const agentDir = canonicalizePath(PiCodingAgent.getAgentDir());
+    const controlDir = canonicalizePath(options.controlDir);
+    mkdirSync(controlDir, { recursive: true });
+    const sdkEntry = canonicalizePath(join(PiCodingAgent.getPackageDir(), "dist", "index.js"));
+    const cliPaths = ["cli.js", join("bundle", "cli.js")].map((entry) => canonicalizePath(join(PiCodingAgent.getPackageDir(), "dist", entry)));
+    if (!cliPaths.includes(canonicalizePath(options.piBin))) {
+        throw new Error("Task sandbox requires the active Pi SDK CLI; a different pi executable is on PATH.");
+    }
+    const ownEntry = fileURLToPath(import.meta.url);
+    const scratch = createTaskScratch();
+    const policy = parseTaskPolicy({
+        version: 1, root, home, agentDir, profilePath: join(controlDir, "task.sb"), scratch: scratch.path,
+        permissions,
+        denyWrite: [...new Set([
+            controlDir, scratch.anchor, agentDir, ...runtimeDirectories, ...(options.runtimeRoots ?? []), join(root, ".pi"), join(root, ".git", "hooks"), join(root, ".env"), join(root, ".env.local"),
+            runtimeCodeRoot(sdkEntry), runtimeCodeRoot(ownEntry), ...(options.extensionPaths ?? []).map(runtimeCodeRoot),
+        ])],
+        tools: options.tools,
+    });
+    compileWritePolicy({ writableRoot: root, home, permissions: policy.permissions, denyWrite: policy.denyWrite });
+    const policyPath = join(controlDir, "task-policy.json");
+    writeFileSync(policyPath, JSON.stringify(policy), { mode: 0o600 });
+    return {
+        file: process.execPath,
+        fileArgs: [canonicalizePath(fileURLToPath(new URL("./task-runtime.mjs", import.meta.url))), sdkEntry, policyPath],
+        policy, policyPath,
+    };
+}
+
+export function readTaskPolicy(path: string): TaskPolicy {
+    return parseTaskPolicy(JSON.parse(readFileSync(path, "utf8")));
+}

package/task-runtime.mjs

@@ -0,0 +1,39 @@
+/** Trusted native entry point. Any failure before/inside guard installation is fatal. */
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, isAbsolute, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const fail = (error) => {
+  process.stderr.write(`Task sandbox bootstrap failed: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(1);
+};
+
+try {
+  const [sdkEntry, policyPath, ...args] = process.argv.slice(2);
+  if (!sdkEntry || !policyPath || !isAbsolute(sdkEntry) || !isAbsolute(policyPath)) throw new Error("Missing trusted runtime paths.");
+  const policy = JSON.parse(readFileSync(policyPath, "utf8"));
+  if (typeof policy.agentDir !== "string" || !isAbsolute(policy.agentDir)) throw new Error("Invalid runtime agent directory.");
+  process.env.PI_CODING_AGENT_DIR = policy.agentDir;
+  const sdkRequire = createRequire(sdkEntry);
+  const { version } = JSON.parse(readFileSync(join(dirname(sdkEntry), "..", "package.json"), "utf8"));
+  const [major, minor, patch] = version.split(".").map(Number);
+  if (!(major > 0 || minor > 82 || (minor === 82 && patch >= 1))) throw new Error("Task confinement requires Pi SDK 0.82.1 or newer.");
+  const { createJiti } = await import(pathToFileURL(sdkRequire.resolve("jiti")).href);
+  const load = createJiti(import.meta.url, {
+    tryNative: false, fsCache: false, moduleCache: false, interopDefault: true,
+    alias: { "@earendil-works/pi-coding-agent": sdkEntry },
+  });
+  // Import the complete guard before invoking Pi. Unlike an ordinary CLI -e
+  // extension, an import error here cannot be downgraded to a startup warning.
+  const guard = await load.import(fileURLToPath(new URL("./task-guard.ts", import.meta.url)), { default: true });
+  if (typeof guard !== "function") throw new Error("Task guard has no extension factory.");
+  const { main } = await import(pathToFileURL(join(dirname(sdkEntry), "main.js")).href);
+  await main(args, {
+    extensionFactories: [{ name: "task-sandbox", factory: async (pi) => {
+      try { await guard(pi, policy, fail); } catch (error) { fail(error); }
+    } }],
+  });
+} catch (error) {
+  fail(error);
+}