pi-better-subagents 0.3.0 → 0.4.0

package/README.md

@@ -29,7 +29,7 @@ Try it for one run:
 pi -e npm:pi-better-subagents
 ```
 
-Linux sandboxing uses `bubblewrap` when available, for example from `sudo apt-get install bubblewrap`. With [`pi-better-sandbox`](https://github.com/1aboveio/pi-better-harness/tree/main/packages/pi-better-sandbox#readme) installed, `/sandbox` controls the independent Subagents profile. Each launch snapshots that profile; `sandbox:false` cannot bypass a human-enabled sandbox. Commands Off or Network access Off prevents a detached Pi launch, because the child runtime still needs its provider connection. Session/temp writes use a private directory for that run. Without published permission settings, the legacy default remains write confinement with unrestricted reads and network. See [usage notes](https://github.com/1aboveio/pi-better-harness/blob/main/packages/pi-better-subagents/docs/usage.md#write-sandbox).
+Linux confinement requires a usable `bubblewrap` backend and Pi SDK 0.82.1 or newer. `/sandbox` controls the independent Subagents profile, which each launch freezes. Pi handles its own startup, authentication, and provider connection; task tools obey the selected file, command, and network permissions. Outside project defaults to Read. Currently confined children admit `read`, `write`, `edit`, and `bash`; unsupported requested tools are reported as unavailable. See [usage notes](https://github.com/1aboveio/pi-better-harness/blob/main/packages/pi-better-subagents/docs/usage.md#write-sandbox) for the runtime boundary and supported configurations.
 
 ## When To Use
 

package/index.ts

@@ -37,12 +37,15 @@ import { parseRun, readRunTranscript, resetParseRunCursor, type Usage } from "./
 import { finalizeRun as finalizeRunCore } from "./finalization.ts";
 import { loadConfig, normalizeTools, resolveExtensionPath, SAFE_DEFAULT_TOOLS, SAFE_CLEAN_TOOLS, DEFAULT_MAX_CONCURRENT } from "./config.ts";
 import { resolveExtensions, extensionArgs } from "./extensions.ts";
-import { maybeBuildSandboxCommand } from "./sandbox.ts";
+import { prepareTaskRuntime } from "./task-policy.ts";
+import { canonicalizePath } from "./shared-sandbox-core.ts";
+import { TASK_BUILTINS } from "./shared-task-sandbox.ts";
 import { observeSandboxPermissions, resolveSubagentPermissions } from "./permission-policy.ts";
 import { resolveSubagentWorkspace } from "./git-workspace.ts";
-import { homedir } from "node:os";
-import { isAbsolute, join, relative } from "node:path";
+import { join } from "node:path";
 import {
+    baseDir,
+    taskWorkspaceDir,
     sessionsDir,
     runDir,
     logPathFor,
@@ -1344,18 +1347,17 @@ export default function (pi: ExtensionAPI) {
         // Sandbox is ON by default. sandbox_dir moves the confinement + working
         // dir elsewhere. git_clone_workspace prepares a disposable clone with
         // .git/ inside the writable root for Git-mutating sandboxed subagents.
-        const explicitSandbox = p.sandbox === true || typeof p.sandbox_dir === "string" || p.git_clone_workspace === true || permissionPlan.enforced;
         const sandboxEnabled = permissionPlan.sandboxEnabled;
 
         const id = nextRunId();
-        const childSessionDir = permissionPlan.permissions ? join(sessionsDir(), id) : sessionsDir();
+        const childSessionDir = sandboxEnabled ? join(sessionsDir(), id) : sessionsDir();
         mkdirSync(childSessionDir, { recursive: true });
         mkdirSync(runDir(id), { recursive: true });
 
         const workspace = resolveSubagentWorkspace({
             ctxCwd: ctx.cwd,
             cwd: p.cwd,
-            sandboxDir: p.sandbox_dir,
+            sandboxDir: p.sandbox_dir ?? (sandboxEnabled && p.git_clone_workspace ? taskWorkspaceDir(id) : undefined),
             gitCloneWorkspace: p.git_clone_workspace,
             runId: id,
             runDirPath: runDir(id),
@@ -1379,9 +1381,14 @@ export default function (pi: ExtensionAPI) {
         }
 
         const resolution = resolveExtensions({
-            tools: allow, model, clean, allowNested: p.allow_nested, config: cfg,
+            tools: sandboxEnabled ? allow.split(",").filter((name) => (TASK_BUILTINS as readonly string[]).includes(name)).join(",") : allow,
+            model, clean, allowNested: sandboxEnabled ? false : p.allow_nested, config: cfg,
         });
-        const { args: extArgs, missing } = extensionArgs(resolution, resolveExtensionPath);
+        const { args: resolvedExtArgs, missing } = extensionArgs(resolution, resolveExtensionPath);
+        const extArgs = resolvedExtArgs.map((value, index) => sandboxEnabled && resolvedExtArgs[index - 1] === "--extension" ? canonicalizePath(value) : value);
+        if (sandboxEnabled && resolution.mode === "inherit") {
+            throw new Error("Task confinement requires explicit extensions; inheritExtensions is unsupported while sandboxing is enabled.");
+        }
         if (missing.length) {
             throw new Error(
                 `Subagent needs extension(s) that are not installed: ${missing.join(", ")}. ` +
@@ -1402,33 +1409,27 @@ export default function (pi: ExtensionAPI) {
             ...extArgs,
             ...(model ? ["--model", model] : []),
             ...(thinking ? ["--thinking", thinking] : []),
-            ...(allow ? ["--tools", allow] : []),
+            ...(allow && !sandboxEnabled ? ["--tools", allow] : []),
             ...(excludes.size ? ["--exclude-tools", [...excludes].join(",")] : []),
-            ...(p.approve ? ["--approve"] : []),
+            ...(sandboxEnabled ? ["--no-builtin-tools", "--no-approve"] : p.approve ? ["--approve"] : []),
             p.prompt,
         ];
 
         const piBin = resolvePiBinary();
-        const writableContainsRunDir = requestedSandboxDir && (() => {
-            const rel = relative(runDir(id), requestedSandboxDir);
-            return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
-        })();
-        const denyWrite = permissionPlan.enforced ? [
-            join(PiCodingAgent.getAgentDir?.() ?? process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent"), "extensions"),
-            ...(writableContainsRunDir ? [
-                join(runDir(id), "meta.json"), join(runDir(id), ".launch.json"),
-                promptPathFor(id), join(runDir(id), "sandbox.sb"),
-            ] : [runDir(id)]),
-        ] : undefined;
-        const sandboxCommand = requestedSandboxDir
-            ? maybeBuildSandboxCommand({
-                profilePath: join(runDir(id), "sandbox.sb"),
-                writableDir: requestedSandboxDir, home: homedir(), piBin, piArgs: args,
-                ...(permissionPlan.permissions ? { permissions: permissionPlan.permissions, denyWrite, runtimeDir: childSessionDir } : {}),
-            }, { sandboxEnabled, explicitSandbox })
-            : undefined;
-        const cmd = sandboxCommand ?? { file: piBin, fileArgs: args };
-        const sandboxDir = sandboxCommand ? requestedSandboxDir : undefined;
+        const selectedTools = allow.split(",").filter((name) => name && !excludes.has(name));
+        const unavailableTools = sandboxEnabled ? selectedTools.filter((name) => !(TASK_BUILTINS as readonly string[]).includes(name)) : [];
+        if (sandboxEnabled && selectedTools.length && unavailableTools.length === selectedTools.length) {
+            throw new Error(`No requested tool has a verified task sandbox adapter: ${unavailableTools.join(", ")}.`);
+        }
+        const taskRuntime = sandboxEnabled && requestedSandboxDir ? prepareTaskRuntime({
+            root: requestedSandboxDir, controlDir: join(runDir(id), "control"), piBin,
+            tools: selectedTools, permissions: permissionPlan.permissions,
+            extensionPaths: extArgs.flatMap((arg, index) => arg === "--extension" && extArgs[index + 1] ? [extArgs[index + 1]!] : []),
+            runtimeRoots: [baseDir()],
+        }) : undefined;
+        if (sandboxEnabled && !taskRuntime) throw new Error("Task sandbox has no workspace; refusing an unconfined child.");
+        const cmd = taskRuntime ? { file: taskRuntime.file, fileArgs: [...taskRuntime.fileArgs, ...args] } : { file: piBin, fileArgs: args };
+        const sandboxDir = taskRuntime ? requestedSandboxDir : undefined;
 
         const spawned = spawnDetached({ file: cmd.file, fileArgs: cmd.fileArgs, cwd, logPath: logPathFor(id) });
         // Record process identity (pgid, start-time token) so health
@@ -1446,7 +1447,7 @@ export default function (pi: ExtensionAPI) {
             promptPreview: p.prompt.slice(0, 200),
             startedAt: Date.now(), logPath: logPathFor(id), sessionId: id,
             callbackOrigin,
-            sandbox: sandboxDir, callback: p.callback !== false,
+            sandbox: sandboxDir, taskRuntime: Boolean(taskRuntime), taskScratch: taskRuntime?.policy.scratch, callback: p.callback !== false,
             ...batchInfo,
             // The launch record is JSON. Registry freezes that value; it does not
             // require the resolver's nominal type to carry an index signature.
@@ -1468,11 +1469,11 @@ export default function (pi: ExtensionAPI) {
             : resolution.specs.length
                 ? `Runtime: isolated · extensions ${resolution.specs.join(", ")}\n`
                 : `Runtime: isolated · built-in tools only\n`;
-        const warn = resolution.unmapped.length
+        const warn = (unavailableTools.length ? `Task sandbox: unavailable adapters for ${unavailableTools.join(", ")}; these tools are disabled.\n` : "") + (resolution.unmapped.length
             ? `NOTE: no extension mapped for ${resolution.unmapped.join(", ")} — ` +
               `${resolution.unmapped.length > 1 ? "these tools" : "this tool"} will NOT exist in the child. ` +
               `Add a toolExtensions entry in config.json.\n`
-            : "";
+            : "");
         return { id, meta, spawned, runtime, warn, sandboxDir };
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-subagents",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Pi extension for detached, sandboxed subagent runs that keep the foreground session free.",
   "license": "MIT",
   "type": "module",
@@ -30,9 +30,9 @@
     "access": "public"
   },
   "scripts": {
-    "pretest": "node ../../scripts/sync-shared-log-utils.mjs && node ../../scripts/sync-shared-sandbox-core.mjs",
-    "prepack": "node ../../scripts/sync-shared-log-utils.mjs && node ../../scripts/sync-shared-sandbox-core.mjs",
-    "typecheck": "node -e \"console.log('pi-better-subagents: typecheck skipped for legacy mixed TS/MJS package')\"",
+    "pretest": "node ../../scripts/sync-shared-log-utils.mjs && node ../../scripts/sync-shared-sandbox-core.mjs && node ../../scripts/sync-task-sandbox.mjs",
+    "prepack": "node ../../scripts/sync-shared-log-utils.mjs && node ../../scripts/sync-shared-sandbox-core.mjs && node ../../scripts/sync-task-sandbox.mjs",
+    "typecheck": "tsc -p tsconfig.task-runtime.json",
     "test": "node --import tsx --test tests/*.test.mjs",
     "test:cross-session": "node --import tsx --test --test-name-pattern \"callback session isolation\" tests/extension_health_lifecycle.test.mjs",
     "pretest:macos-sandbox": "node ../../scripts/sync-shared-sandbox-core.mjs",
@@ -56,7 +56,7 @@
   ],
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-coding-agent": ">=0.82.1",
     "@earendil-works/pi-tui": "*"
   },
   "dependencies": {

package/permission-policy.ts

@@ -97,10 +97,8 @@ export function resolveSubagentPermissions(pi: unknown, requestedSandbox: boolea
     }
     const sandboxEnabled = child.enabled || requestedSandbox === true;
     if (!sandboxEnabled) return { sandboxEnabled: false, enforced: false };
-    if (!child.commands) throw new Error("Subagents profile disables commands. Enable commands in the sandbox UI before launching a subagent.");
-    if (!child.network) {
-        throw new Error("Subagents profile disables network, including model requests. Child provider isolation is not available; enable network in the sandbox UI before launching a subagent.");
-    }
+    // Starting Pi is runtime work. These capabilities constrain task tools;
+    // they do not disable provider transport or the fixed file-operation worker.
     const { enabled: _enabled, ...permissions } = child;
     return { sandboxEnabled: true, enforced: true, permissions };
 }

package/registry.ts

@@ -14,10 +14,10 @@
 
 import { execFileSync } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
-import { closeSync, fsyncSync, linkSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { closeSync, fsyncSync, linkSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { processExists } from "./spawn.ts";
 import type { LifecycleClassification } from "./lifecycle.ts";
 
@@ -149,6 +149,9 @@ export interface RunMeta {
     lostCallbackSuppressedReason?: string;
     /** Writable dir the child is OS-sandboxed to, if any. */
     sandbox?: string;
+    /** Pi is trusted; model task operations use an immutable kernel policy. */
+    taskRuntime?: boolean;
+    taskScratch?: string;
     /** Whether completion posts the result back to the main session (default true). */
     callback?: boolean;
     /** Batch ID for runs launched via subagent_spawn_batch. */
@@ -176,11 +179,16 @@ export interface RunMeta {
 
 /** Root runtime dir, deliberately OUTSIDE any repo. */
 export function baseDir(): string {
-    return join(tmpdir(), "pi-better-subagents");
+    return join(realpathSync(tmpdir()), "pi-better-subagents");
 }
 export function sessionsDir(): string {
     return join(baseDir(), "sessions");
 }
+export function taskWorkspaceDir(id: string): string {
+    if (!/^sa_[a-z0-9]+_[a-z0-9]+$/i.test(id)) throw new Error("Invalid task workspace run ID.");
+    return join(realpathSync(tmpdir()), "pi-better-subagent-workspaces", id);
+}
+
 export function runDir(id: string): string {
     return join(baseDir(), "runs", id);
 }
@@ -837,6 +845,12 @@ export function readMeta(id: string): RunMeta | undefined {
 export function removeMetaArtifacts(meta: RunMeta): boolean {
     try {
         rmSync(runDir(meta.id), { recursive: true, force: true });
+        if (meta.taskRuntime && /^sa_[a-z0-9]+_[a-z0-9]+$/i.test(meta.id) && meta.cwd === taskWorkspaceDir(meta.id)) {
+            rmSync(taskWorkspaceDir(meta.id), { recursive: true, force: true });
+        }
+        if (meta.taskRuntime && meta.taskScratch && dirname(meta.taskScratch) === realpathSync(tmpdir()) && /^pi-task-scratch-[a-z0-9]{6}$/i.test(basename(meta.taskScratch))) {
+            rmSync(meta.taskScratch, { recursive: true, force: true });
+        }
         metaCache.delete(meta.id);
         removeIndexEntry(join(baseDir(), "by-parent", String(meta.spawnPid)), meta.id);
         removeIndexEntry(join(baseDir(), "by-parent-active", String(meta.spawnPid)), meta.id);

package/shared-sandbox-core.ts

@@ -79,6 +79,8 @@ export type SandboxCommandArgs = SandboxTarget & {
     /** Where the macOS backend writes its generated SBPL profile. */
     profilePath: string;
     policy: SandboxWritePolicy;
+    /** Fixed internal helper only: expose its executable in a hidden Linux root. */
+    internalHelperExecutable?: boolean;
 };
 
 /** The wrapper command to spawn: the backend executable and its full argv. */
@@ -410,7 +412,21 @@ const macOSSandboxBackend: SandboxBackend = {
     buildCommand: buildMacOSSandboxCommand,
 };
 
-/** Resolve an executable from PATH without starting it or probing namespaces. */
+/** Resolve only a root-owned system executable; never inspect task PATH. */
+function systemSandboxExecutable(name: string): string | undefined {
+    // Never resolve the host-side confinement launcher through task-influenced PATH.
+    for (const directory of ["/usr/bin", "/bin"]) {
+        const candidate = join(directory, name);
+        try {
+            const info = statSync(candidate);
+            if (!info.isFile() || info.uid !== 0 || (info.mode & 0o022) !== 0) continue;
+            accessSync(candidate, constants.X_OK);
+            return candidate;
+        } catch { /* Try the next system location. */ }
+    }
+    return undefined;
+}
+
 export function executableFromPath(name: string): string | undefined {
     const path = process.env.PATH;
     if (!path) return undefined;
@@ -592,6 +608,12 @@ function buildLinuxPermissionCommand(
             if (existsSync(root)) mounts.push("--ro-bind", root, root);
         }
         mounts.push("--tmpfs", "/tmp");
+        if (args.internalHelperExecutable) {
+            const executable = canonicalizePath(args.execPath, seams);
+            if (!RUNTIME_ROOTS.some((root) => contains(canonicalizePath(root, seams), executable))) {
+                mounts.push("--ro-bind", executable, executable);
+            }
+        }
     } else {
         mounts.push(permissions.outsideProject === "read" ? "--ro-bind" : "--bind", "/tmp", "/tmp");
     }
@@ -605,17 +627,18 @@ function buildLinuxPermissionCommand(
         }
     }
     for (const path of policy.runtimeWrite ?? []) {
-        if ([...credentials, ...policy.denyWrite].some((protectedPath) => contains(path, protectedPath) || contains(protectedPath, path))) {
+        if (credentials.some((protectedPath) => contains(path, protectedPath) || contains(protectedPath, path)) ||
+            policy.denyWrite.some((protectedPath) => contains(protectedPath, path))) {
             throw new Error("Runtime directory overlaps protected credentials or control paths.");
         }
         mounts.push("--bind", path, path);
     }
     const protectedPaths = [...policy.denyWrite,
         ...(permissions.storedCredentials !== "read-write" ? overlappingCredentials : [])];
-    if (writableProject) {
+    for (const writableRoot of [...(writableProject ? [project] : []), ...(policy.runtimeWrite ?? [])]) {
         const materialize = seams.materializeDenyPath ?? materializeDenyPath;
-        const leaves = protectedPaths.filter((path) => contains(project, path) && materialize(path));
-        for (const parent of protectedAncestors(leaves).filter((path) => contains(project, path) && path !== project)) {
+        const leaves = protectedPaths.filter((path) => contains(writableRoot, path) && materialize(path));
+        for (const parent of protectedAncestors(leaves).filter((path) => contains(writableRoot, path) && path !== writableRoot)) {
             mounts.push("--bind", parent, parent);
         }
         for (const path of leaves) mounts.push("--ro-bind", path, path);
@@ -628,7 +651,7 @@ function buildLinuxPermissionCommand(
 }
 
 function linuxSandboxBackend(seams: SandboxSeams): SandboxBackend | undefined {
-    const bwrap = (seams.lookupExecutable ?? executableFromPath)("bwrap");
+    const bwrap = (seams.lookupExecutable ?? systemSandboxExecutable)("bwrap");
     if (!bwrap) return undefined;
     return {
         id: "linux-bubblewrap",
@@ -651,7 +674,7 @@ function selectedSandboxBackend(seams: SandboxSeams): SandboxBackend | undefined
  */
 function unavailableMessage(platform: string): string {
     if (platform === "linux") {
-        return "Linux sandbox requires executable bubblewrap (bwrap) on PATH. Install bubblewrap to enable it.";
+        return "Linux sandbox requires executable bubblewrap (bwrap) in /usr/bin or /bin. Install bubblewrap to enable it.";
     }
     if (platform === "darwin") {
         return "macOS sandbox requires /usr/bin/sandbox-exec, which is missing here.";

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);
+}