pi-better-subagents 0.2.0 → 0.4.0

package/index.ts

@@ -37,11 +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 { join } from "node:path";
 import {
+    baseDir,
+    taskWorkspaceDir,
     sessionsDir,
     runDir,
     logPathFor,
@@ -91,6 +95,8 @@ import {
 } from "./capacity.mjs";
 import { buildHealthCallbackDelivery } from "./completion.ts";
 import { cancelCallbackBatch, getCallbackBatcher } from "./shared-callback-batcher.ts";
+import { collectRunFailures, failurePath, failureSummary, formatFailureSummary, markFailureAttentionDelivered, pendingFailureAttention, prependFailureSummary } from "./failures.ts";
+import { failureAttentionHandled, observeFailures } from "./shared-failure-observations.ts";
 import {
     text,
     subagentListTool,
@@ -334,11 +340,15 @@ function enqueueCompletionCallback(pi: ExtensionAPI, id: string): void {
         || meta.completionCallbackSentAt !== undefined
         || meta.completionCallbackSuppressedAt !== undefined) return;
     const label = meta.name ? `${meta.name} (${id})` : id;
+    const observations = Object.values(collectRunFailures(id, meta.cwd, true).observations);
+    const unresolved = observations.filter((observation) => observation.status === "unresolved");
+    const observationStatus = unresolved.some((observation) => observation.category === "observation-incomplete")
+        ? "observation incomplete" : unresolved.length ? "unresolved failure observations" : undefined;
     getCallbackBatcher(pi).enqueue({
         source: "subagent",
         id,
         label,
-        status: meta.status,
+        status: observationStatus ? `${meta.status}; ${observationStatus}` : meta.status,
         detailTool: "subagent_result",
         callback: true,
         isDelivered: () => {
@@ -348,10 +358,18 @@ function enqueueCompletionCallback(pi: ExtensionAPI, id: string): void {
         },
         getSuppressionReason: () => {
             const current = readMeta(id);
-            if (!current) return "subagent metadata is unavailable";
+            if (!current) throw new Error("Subagent metadata is unavailable; defer completion");
             return callbackSuppressionReason(current);
         },
-        onDelivered: (at) => markCompletionCallbackSent(id, at),
+        onDelivered: (at) => {
+            const state = collectRunFailures(id, meta.cwd, true);
+            const due = pendingFailureAttention(state, at, { terminal: true });
+            if (due) {
+                markFailureAttentionDelivered(failurePath(id), due, at);
+                if (due.incidents.some((incident) => pendingFailureAttention(collectRunFailures(id, meta.cwd, true), at, { terminal: true })?.incidents.includes(incident))) return;
+            }
+            markCompletionCallbackSent(id, at);
+        },
         onSuppressed: (reason, at) => markCompletionCallbackSuppressed(id, reason, at),
     });
 }
@@ -364,6 +382,27 @@ function recoverCompletionCallbacks(pi: ExtensionAPI): void {
     }
 }
 
+function deliverFailureAttention(pi: ExtensionAPI | undefined, meta: RunMeta, now: number): void {
+    if (!pi || meta.callback === false || callbackSuppressionReason(meta)) return;
+    if ((meta.status === "orphaned" || meta.status === "lost") && !isHealthCallbackHandled(meta, meta.status)) return;
+    const state = collectRunFailures(meta.id, meta.cwd, meta.status !== "running" && meta.status !== "orphaned");
+    const pending = pendingFailureAttention(state, now);
+    if (!pending || (meta.status !== "running" && meta.status !== "orphaned" && meta.completionCallbackPendingAt !== undefined)) return;
+    const label = meta.name ? `${meta.name} (${meta.id})` : meta.id;
+    void getCallbackBatcher(pi).deliverUrgent({
+        source: "subagent", id: meta.id, label, status: `failure:${pending.key}`,
+        customType: "subagent-failure",
+        content: `${formatFailureSummary(state)}\nInspect: subagent_output id=${JSON.stringify(meta.id)}`,
+        isDelivered: () => failureAttentionHandled(collectRunFailures(meta.id, meta.cwd), pending.incidents),
+        getSuppressionReason: () => {
+            const current = readMeta(meta.id);
+            if (!current) throw new Error("Subagent metadata is unavailable; defer failure notification");
+            return callbackSuppressionReason(current);
+        },
+        onDelivered: (at) => { markFailureAttentionDelivered(failurePath(meta.id), pending, at); },
+    });
+}
+
 function markHealthCallbackSuppressed(meta: RunMeta, status: "orphaned" | "lost", reason: string, now: number): void {
     if (status === "orphaned") {
         if (meta.orphanedCallbackSuppressedAt !== undefined) return;
@@ -532,6 +571,9 @@ function deliverHealthCallback(pi: ExtensionAPI | undefined, meta: RunMeta, stat
 
     const callback = meta.callback !== false;
     const label = meta.name ? `${meta.name} (${meta.id})` : meta.id;
+    const failureState = collectRunFailures(meta.id, meta.cwd, status === "lost");
+    const failureText = formatFailureSummary(failureState);
+    const attention = pendingFailureAttention(failureState, now, { terminal: status === "lost" });
     const delivery = buildHealthCallbackDelivery({ id: meta.id, label, status, callback });
     if (!delivery) {
         // callback:false — model follow-up suppressed; mark handled so recovery
@@ -547,19 +589,24 @@ function deliverHealthCallback(pi: ExtensionAPI | undefined, meta: RunMeta, stat
         label,
         status,
         customType: "subagent-health",
-        content: delivery.content,
+        content: prependFailureSummary(delivery.content, failureText),
         isDelivered: () => {
             const current = readMeta(meta.id);
-            return current ? isHealthCallbackHandled(current, status) : true;
+            if (!current) throw new Error("Subagent metadata is unavailable; defer health notification");
+            return isHealthCallbackHandled(current, status);
         },
         getSuppressionReason: () => {
             const current = readMeta(meta.id);
-            if (!current) return "subagent metadata is unavailable";
+            if (!current) throw new Error("Subagent metadata is unavailable; defer health notification");
             return callbackSuppressionReason(current);
         },
         onDelivered: (at) => {
             const current = readMeta(meta.id);
             if (!current || isHealthCallbackHandled(current, status)) return;
+            if (attention) {
+                markFailureAttentionDelivered(failurePath(meta.id), attention, at);
+                if (attention.incidents.some((incident) => pendingFailureAttention(collectRunFailures(meta.id, meta.cwd), at, { terminal: true })?.incidents.includes(incident))) return;
+            }
             if (status === "orphaned") current.orphanedCallbackSentAt = at;
             else current.lostCallbackSentAt = at;
             writeMeta(current);
@@ -586,12 +633,25 @@ function reconcileHealth(): void {
         if (!meta) continue;
         if (meta.status !== "running" && meta.status !== "orphaned" && meta.status !== "lost") continue;
         const now = Date.now();
+        if (meta.status === "orphaned" || meta.status === "lost") {
+            observeFailures(failurePath(meta.id), [{ id: `supervision:${meta.status}`, operation: `supervision:${meta.status}`, kind: "incomplete",
+                summary: meta.status === "lost" ? "Child supervision was lost; outcome is unknown" : "Child supervision interrupted; related work may still be alive" }], now);
+        }
+        deliverFailureAttention(pi, meta, now);
 
         if (meta.status === "running" || meta.status === "orphaned") {
             const result = reconcileRun(meta, realProcessProbe, now);
             if (result.changed) {
                 Object.assign(meta, result.patch, { status: result.status });
                 writeMeta(meta);
+                if (result.status === "lost") {
+                    observeFailures(failurePath(meta.id), [
+                        { id: "supervision:orphaned-resolved", operation: "supervision:orphaned", kind: "recovered", incidents: ["supervision:orphaned"] },
+                        { id: "supervision:lost", operation: "supervision:lost", kind: "incomplete", summary: "Child supervision was lost; outcome is unknown" },
+                    ], now);
+                } else if (result.status === "orphaned") {
+                    observeFailures(failurePath(meta.id), [{ id: "supervision:orphaned", operation: "supervision:orphaned", kind: "incomplete", summary: "Child supervision interrupted; related work may still be alive" }], now);
+                }
                 if (result.transition) {
                     // Human-visible health (always) on fresh transitions.
                     if (!callbackSuppressionReason(meta)) {
@@ -612,8 +672,13 @@ function reconcileHealth(): void {
             deliverHealthCallback(pi, meta, meta.status, now);
         }
     }
-    // Stop existing the moment nothing current-parent needs monitoring/recovery.
-    if (!needsMonitoring(listMetasForParent(process.pid))) stopHealthTicker();
+    // Completed runs can still have failed completion handoffs to retry.
+    for (const summary of listMetasForParent(process.pid)) {
+        if (!pi || !ownedByThisParent(summary) || summary.status === "running" || summary.status === "orphaned" || summary.status === "lost") continue;
+        const meta = readMeta(summary.id);
+        if (meta && meta.completionCallbackPendingAt !== undefined && meta.completionCallbackSentAt === undefined && meta.completionCallbackSuppressedAt === undefined) enqueueCompletionCallback(pi!, meta.id);
+    }
+    if (!needsMonitoring(listMetasForParent(process.pid)) && !hasPendingFailureCallbacks()) stopHealthTicker();
 }
 
 /**
@@ -669,6 +734,12 @@ function reconcileAbandonedRuns(now: number = Date.now()): number {
     return adopted;
 }
 
+function hasPendingFailureCallbacks(): boolean {
+    return listMetasForParent(process.pid).some((m) => ownedByThisParent(m) && m.callback !== false &&
+        m.completionCallbackPendingAt !== undefined && m.completionCallbackSentAt === undefined && m.completionCallbackSuppressedAt === undefined &&
+        !callbackSuppressionReason(m));
+}
+
 /** Start the reconciliation loop if it isn't already running. */
 function ensureHealthTicker(): void {
     if (healthTicker) return;
@@ -847,6 +918,8 @@ function subagentWorkRows(now: number): BackgroundWorkRow[] {
         if (row.model) bits.push(row.effort ? `${row.model} ${row.effort}` : row.model);
         if (row.tool) bits.push(row.tool);
         if (row.spend) bits.push(row.spend);
+        const failure = failureSummary(row.id, metaById.get(row.id)?.cwd ?? "", row.status !== "running" && row.status !== "orphaned");
+        const firstFailure = failure.split("\n")[0] || "";
         return {
             providerId: "subagents",
             id: row.id,
@@ -859,7 +932,8 @@ function subagentWorkRows(now: number): BackgroundWorkRow[] {
             statusTone: statusTone(row.status),
             kind: "subagent",
             elapsed: row.elapsed,
-            primary: bits.join(" · ") || "subagent run",
+            primary: firstFailure || bits.join(" · ") || "subagent run",
+            secondary: firstFailure ? bits.join(" · ") : undefined,
             facts: row.healthFacts,
             sortStartedAt: metaById.get(row.id)?.startedAt ?? now,
             expiresAt: (() => {
@@ -909,7 +983,9 @@ function subagentWorkDetail(id: string, now: number, options?: { logTailLines?:
     if (!detail) return null;
     void options;
     const transcript = readRunTranscript(id);
+    const failure = failureSummary(id, readMeta(id)?.cwd ?? "", detail.status !== "running" && detail.status !== "orphaned");
     const metadata = [
+        ...(failure ? [{ label: "failure", value: failure.split("\n")[0]! }] : []),
         { label: "provider", value: "Subagents" },
         { label: "id", value: detail.id },
         ...(detail.role ? [{ label: "role", value: String(detail.role) }] : []),
@@ -926,11 +1002,11 @@ function subagentWorkDetail(id: string, now: number, options?: { logTailLines?:
         title: detail.name || detail.id,
         status: detail.status,
         statusTone: statusTone(detail.status),
-        subtitle: detail.currentTool ? `current tool ${detail.currentTool}` : undefined,
+        subtitle: failure.split("\n")[0] || (detail.currentTool ? `current tool ${detail.currentTool}` : undefined),
         metadata,
-        evidence: { label: "transcript", text: detail.output || "(no transcript yet)" },
+        evidence: { label: "transcript", text: prependFailureSummary(detail.output || "(no transcript yet)", failure) },
         transcript: transcript.entries,
-        transcriptDiagnostic: transcript.diagnostic,
+        transcriptDiagnostic: failure ? prependFailureSummary(transcript.diagnostic ?? "", failure) : transcript.diagnostic,
         footerActions: [detail.status === "running" || detail.status === "orphaned" ? "x stop" : "x dismiss"],
     };
 }
@@ -1113,13 +1189,14 @@ function finalizeRun(pi: ExtensionAPI, ctx: ExtensionContext, id: string, code:
     // Host-facing wrapper around first-party finalizer (finalization.ts).
     // Coherent child-exit evidence may supersede provisional orphaned/lost
     // reconciliation; finalization.ts enforces canExitFinalize + lifecycle authority.
-    finalizeRunCore(id, code, {
+    const result = finalizeRunCore(id, code, {
         renderWidget,
         notify: (message, level) => {
             try { ctx.ui.notify(message, level); } catch { /* ignore */ }
         },
         sendMessage: () => enqueueCompletionCallback(pi, id),
     });
+    if (result.applied && hasPendingFailureCallbacks()) ensureHealthTicker();
 }
 
 /** String for one role, or an array when the caller assigns more than one. Arrays reach clarification instead of being rejected. */
@@ -1138,6 +1215,7 @@ export default function (pi: ExtensionAPI) {
     healthPi = pi;
     ensureSubagentProvider();
     registerSubagentsGoalProvider(pi);
+    observeSandboxPermissions(pi);
     let acceptanceResultToolRef: { execute: (toolCallId: string, params: { id: string }) => Promise<unknown> } | undefined;
     function publishAcceptanceHooks(tool?: NonNullable<typeof acceptanceResultToolRef>): void {
         if (process.env.PI_CATALOG_ACCEPTANCE_PROBE !== "1") return;
@@ -1238,6 +1316,7 @@ export default function (pi: ExtensionAPI) {
         sandboxDir?: string;
     }> {
         assertThinkingLevel(p.thinking);
+        const permissionPlan = resolveSubagentPermissions(pi, p.sandbox);
         const cfg = loadConfig();
         let model: string | undefined;
         let thinking: ThinkingLevel | undefined;
@@ -1268,17 +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;
-        const sandboxEnabled = p.sandbox !== false; // default on
+        const sandboxEnabled = permissionPlan.sandboxEnabled;
 
-        mkdirSync(sessionsDir(), { recursive: true });
         const id = nextRunId();
+        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),
@@ -1302,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(", ")}. ` +
@@ -1320,26 +1404,32 @@ export default function (pi: ExtensionAPI) {
 
         const args = [
             "-p", "--mode", "json",
-            "--session-dir", sessionsDir(),
+            "--session-dir", childSessionDir,
             "--session-id", id,
             ...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 sandboxCommand = requestedSandboxDir
-            ? maybeBuildSandboxCommand({
-                profilePath: join(runDir(id), "sandbox.sb"),
-                writableDir: requestedSandboxDir, home: homedir(), piBin, piArgs: args,
-            }, { 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
@@ -1357,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.
@@ -1379,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 };
     }
 
@@ -1403,7 +1493,7 @@ export default function (pi: ExtensionAPI) {
             ...SUBAGENT_ORCHESTRATION_GUIDELINES,
             "The tools param is both the tool allowlist AND what determines which extensions load in the child (e.g. tools='read,bash,web_fetch' loads only the web-tools package). Ask for the tools the task needs and nothing more; clean:true gives a built-ins-only child. Pick a model with the model param (e.g. 'xai/grok-4.5@high'); providerless model patterns are resolved by Pi, while provider/model is deterministic and loads mapped provider extensions.",
             ...CATALOG_GUIDELINES,
-            "By default the subagent is sandboxed (writes confined to its working dir, reads and network open) and triggers completion here on finish. Set callback:false to finish quietly — then read the result on demand via subagent_result.",
+            "By default the subagent is sandboxed. Human settings in /sandbox control file, credential-file, command, and network permissions; sandbox:false cannot override an enabled human profile. Without published settings, legacy write confinement applies. Set callback:false to finish quietly — then read the result on demand via subagent_result.",
             "Use git_clone_workspace:true when the subagent will mutate Git in a sandbox. The parent prepares a disposable, self-contained clone with a real .git/ directory inside the sandbox root, so linked-worktree metadata outside the sandbox cannot stall the child.",
         ],
         parameters: Type.Object({
@@ -1417,7 +1507,7 @@ export default function (pi: ExtensionAPI) {
             tools: Type.Optional(Type.String({ description: "Tool allowlist: comma-separated names the child may use (e.g. 'read,bash,web_fetch'). This ALSO selects which extensions load — only packages backing a requested tool are loaded. Defaults to the configured safe set." })),
             exclude_tools: Type.Optional(Type.String({ description: "Comma-separated tool denylist, applied on top of the allowlist." })),
             clean: Type.Optional(Type.Boolean({ description: "Run a hermetic child with NO extensions at all (only built-ins: read, bash, edit, write). Default false — the extensions backing the requested tools load, so web_fetch and model auth (e.g. xai) work." })),
-            sandbox: Type.Optional(Type.Boolean({ description: "Default TRUE (macOS): kernel-confine the child's file WRITES to its working dir — reads and network stay open, but it cannot write outside, whatever it runs. Set false to allow writes anywhere." })),
+            sandbox: Type.Optional(Type.Boolean({ description: "Use the human Subagents profile from /sandbox. An enabled human profile cannot be bypassed with false. Without published settings, defaults to kernel write confinement; false opts out of that legacy default." })),
             sandbox_dir: Type.Optional(Type.String({ description: "Confine writes to (and run the child in) this directory instead of the working dir. Created if missing." })),
             callback: Type.Optional(Type.Boolean({ description: "Default TRUE: on completion, trigger a turn that calls subagent_result and presents the result. Set false to finish quietly — the result is then read on demand via subagent_result." })),
             cwd: Type.Optional(Type.String({ description: "Working directory (default: current)." })),
@@ -1475,7 +1565,7 @@ export default function (pi: ExtensionAPI) {
                     (p.callback === false
                         ? `Running in the background; the foreground is free. It will finish quietly — read the result with subagent_result id=${id}.\n`
                         : `Running in the background; the foreground is free. Its result will be posted back here when it finishes.\n`) +
-                    (sandboxDir ? `Sandboxed: writes confined to ${sandboxDir}\n` : "") +
+                    (sandboxDir ? `Sandboxed: project root ${sandboxDir}; launch permissions apply.\n` : "") +
                     runtime + warn +
                     `Log: ${logPathFor(id)}`,
                 );
@@ -1518,7 +1608,7 @@ export default function (pi: ExtensionAPI) {
                 thinking: Type.Optional(Type.String({ description: "Reasoning effort applied to every job: off, minimal, low, medium, high, xhigh, or max." })),
                 tools: Type.Optional(Type.String({ description: "Tool allowlist applied to every job." })),
                 exclude_tools: Type.Optional(Type.String({ description: "Comma-separated tool denylist applied to every job." })),
-                sandbox: Type.Optional(Type.Boolean({ description: "Default TRUE: kernel-confine writes to the working dir." })),
+                sandbox: Type.Optional(Type.Boolean({ description: "Use the human Subagents profile; false cannot override an enabled profile. Legacy default is write confinement." })),
                 sandbox_dir: Type.Optional(Type.String({ description: "Writable root for every job." })),
                 callback: Type.Optional(Type.Boolean({ description: "Default TRUE: post result back on completion." })),
                 clean: Type.Optional(Type.Boolean({ description: "Hermetic builtins-only child; no extensions load." })),
@@ -1810,7 +1900,7 @@ export default function (pi: ExtensionAPI) {
         // Resume supervision reconciliation + durable health-callback recovery
         // across /reload while current-parent work still needs the ticker
         // (running/orphaned, or unmarked lost); it stops itself when idle.
-        if (needsMonitoring(listMetasForParent(process.pid))) ensureHealthTicker();
+        if (needsMonitoring(listMetasForParent(process.pid)) || hasPendingFailureCallbacks()) ensureHealthTicker();
     });
 
     pi.on("session_before_switch", () => {

package/list.mjs

@@ -74,10 +74,11 @@ export function formatSubagentListRow(meta, p) {
     const name = meta.name ? `${meta.name} ` : "";
     const stat = `${elapsed}${spend ? ` · ${spend}` : ""}`;
     const health = formatListHealthSuffix(p.health);
+    const failure = p.failure ? `\n    ${p.failure.replace(/\n/g, "\n    ")}` : "";
     const batch = meta.batchId
         ? `  [batch: ${meta.batchName ? `${meta.batchName} ` : ""}${meta.batchId}]`
         : "";
-    return `• ${name}${meta.id}  [${status}]  ${meta.model ?? "?"}  ${stat}${health}${batch}\n    ${promptPreview(meta)}`;
+    return `• ${name}${meta.id}  [${status}]  ${meta.model ?? "?"}  ${stat}${health}${batch}${failure}\n    ${promptPreview(meta)}`;
 }
 
 export function buildSubagentList(p) {
@@ -87,6 +88,7 @@ export function buildSubagentList(p) {
     const statusOf = p.statusOf ?? ((meta) => meta.status);
     const usageById = p.usageById ?? (() => undefined);
     const healthById = p.healthById ?? (() => undefined);
+    const failureById = p.failureById ?? (() => "");
 
     const scoped = (p.metas ?? [])
         .filter((meta) => options.all || meta.spawnPid === parentPid)
@@ -110,6 +112,7 @@ export function buildSubagentList(p) {
         now,
         usage: usageById(row.meta.id),
         health: healthById(row.meta.id),
+        failure: failureById(row.meta.id),
     })));
 
     if (matching.length > displayed.length) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-subagents",
-  "version": "0.2.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",
@@ -51,11 +51,12 @@
     "docs/agent-catalog-operations.md",
     "docs/agent-model-resolution.md",
     "docs/agent-catalog-lifecycle.md",
-    "docs/agent-catalog-acceptance.md"
+    "docs/agent-catalog-acceptance.md",
+    "docs/failure-observations.md"
   ],
   "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

@@ -0,0 +1,104 @@
+/** Optional sandbox-extension policy, mirrored per Pi event bus at launch time. */
+export const SANDBOX_POLICY_CHANNEL = "pi-better-sandbox:policy";
+export const SANDBOX_POLICY_REQUEST_CHANNEL = "pi-better-sandbox:policy-request";
+
+type Access = "off" | "read" | "read-write";
+export type PermissionProfile = Readonly<{
+    enabled: boolean;
+    projectFiles: Access;
+    outsideProject: Access;
+    storedCredentials: Access;
+    commands: boolean;
+    network: boolean;
+}>;
+export type PermissionSnapshot = Readonly<{
+    permissions?: PermissionProfile;
+    subagentPermissions?: PermissionProfile;
+}>;
+
+type EventBus = {
+    on(channel: string, handler: (data: unknown) => void): unknown;
+    emit(channel: string, data: unknown): void;
+};
+const mirrors = new WeakMap<EventBus, { policy?: PermissionSnapshot; error?: Error }>();
+
+function busOf(pi: unknown): EventBus | undefined {
+    const bus = (pi as { events?: unknown } | undefined)?.events;
+    if (!bus || typeof bus !== "object") return undefined;
+    const candidate = bus as Partial<EventBus>;
+    return typeof candidate.on === "function" && typeof candidate.emit === "function" ? candidate as EventBus : undefined;
+}
+
+function profile(value: unknown): PermissionProfile {
+    if (!value || typeof value !== "object") throw new Error("Invalid sandbox permission profile.");
+    const p = value as Record<string, unknown>;
+    const access = (v: unknown): v is Access => v === "off" || v === "read" || v === "read-write";
+    if (typeof p.enabled !== "boolean" || typeof p.commands !== "boolean" || typeof p.network !== "boolean" ||
+        !access(p.projectFiles) || !access(p.outsideProject) || !access(p.storedCredentials)) {
+        throw new Error("Invalid sandbox permission profile; update permissions in the sandbox UI.");
+    }
+    return Object.freeze({
+        enabled: p.enabled, commands: p.commands, network: p.network,
+        projectFiles: p.projectFiles, outsideProject: p.outsideProject, storedCredentials: p.storedCredentials,
+    });
+}
+
+function readPolicy(data: unknown): PermissionSnapshot | undefined {
+    if (!data || typeof data !== "object") return undefined;
+    const p = data as Record<string, unknown>;
+    if (!["inactive", "enabled", "disabled", "unavailable", "failed"].includes(String(p.state))) return undefined;
+    return Object.freeze({
+        ...(p.permissions === undefined ? {} : { permissions: profile(p.permissions) }),
+        ...(p.subagentPermissions === undefined ? {} : { subagentPermissions: profile(p.subagentPermissions) }),
+    });
+}
+
+/** Subscribe before launching; request a replay for either extension load order. */
+export function observeSandboxPermissions(pi: unknown): void {
+    const bus = busOf(pi);
+    if (!bus || mirrors.has(bus)) return;
+    const mirror: { policy?: PermissionSnapshot; error?: Error } = {};
+    mirrors.set(bus, mirror);
+    bus.on(SANDBOX_POLICY_CHANNEL, (data) => {
+        try {
+            const next = readPolicy(data);
+            if (next) { mirror.policy = next; mirror.error = undefined; }
+        } catch (error) {
+            mirror.error = error as Error;
+        }
+    });
+    bus.emit(SANDBOX_POLICY_REQUEST_CHANNEL, undefined);
+}
+
+export function currentSandboxPermissions(pi: unknown): PermissionSnapshot | undefined {
+    observeSandboxPermissions(pi);
+    const bus = busOf(pi);
+    if (!bus) return undefined;
+    bus.emit(SANDBOX_POLICY_REQUEST_CHANNEL, undefined);
+    const mirror = mirrors.get(bus);
+    if (mirror?.error) throw mirror.error;
+    return mirror?.policy;
+}
+
+/** Resolve before allocating a run. Absent settings retain the legacy default-on policy. */
+export function resolveSubagentPermissions(pi: unknown, requestedSandbox: boolean | undefined): {
+    sandboxEnabled: boolean;
+    enforced: boolean;
+    permissions?: Omit<PermissionProfile, "enabled">;
+} {
+    const snapshot = currentSandboxPermissions(pi);
+    if (snapshot?.permissions?.enabled && !snapshot.permissions.commands) {
+        throw new Error("Main sandbox profile disables commands. Enable commands in the sandbox UI before launching a subagent.");
+    }
+    const child = snapshot?.subagentPermissions;
+    if (!child) return { sandboxEnabled: requestedSandbox !== false, enforced: false };
+    if (child.enabled && requestedSandbox === false) {
+        throw new Error("Subagent sandbox is enforced by the human-enabled profile; sandbox:false cannot bypass it. Change Subagents permissions in the sandbox UI.");
+    }
+    const sandboxEnabled = child.enabled || requestedSandbox === true;
+    if (!sandboxEnabled) return { sandboxEnabled: false, enforced: false };
+    // 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);