pi-better-subagents 0.2.0 → 0.3.0

package/README.md

@@ -14,7 +14,7 @@ Use `pi-better-subagents` when you want Pi to launch independent agent work with
 - Non-blocking subagent launches, with an optional role and named-agent catalog (`docs/agent-catalog.md`, `docs/agent-catalog-lifecycle.md`).
 - Default OS write sandboxing on macOS and Linux.
 - Explicit tool allowlists for child sessions.
-- Durable logs and result retrieval across reloads.
+- Durable logs, result retrieval, and [failure observations](docs/failure-observations.md) independent of lifecycle status.
 - Live background-work navigator for active runs.
 
 ## Install
@@ -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`. It is the same shared mechanism [`pi-better-sandbox`](https://github.com/1aboveio/pi-better-harness/tree/main/packages/pi-better-sandbox#readme) applies to Pi's foreground tools: writes only, reads and network untouched. See [usage notes](https://github.com/1aboveio/pi-better-harness/blob/main/packages/pi-better-subagents/docs/usage.md#write-sandbox).
+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).
 
 ## When To Use
 

package/docs/failure-observations.md

@@ -0,0 +1,11 @@
+# Failure observations
+
+Structured tool, model, exit, and supervision failures are collected separately from lifecycle status. A child may still be `running`, or finish its agent loop, while checks remain unresolved. List, output, result, navigator, and completion notifications expose these observations before assistant progress can suggest that the work is healthy.
+
+Each run retains a `failures.jsonl` journal. A later successful tool attempt clears an incident only when tool name, arguments, and working directory match and the retry began after the failure. Parallel or unrelated successes cannot clear it. Expected failures require explicit `expected: true` event/result metadata; prose such as “this test should fail” is not interpreted as metadata.
+
+Running failures become eligible for attention after 60 seconds. Observation gaps are eligible immediately, and terminal runs use the existing completion callback. Delivery receipts are independent of recovery and are written after handoff; `callback:false` suppresses notifications without hiding inspection evidence.
+
+The collector scans complete structured records independently of the finite progress tail. Missing terminal logs, unreadable records, and detected truncation are shown as **observation incomplete**. Failure classification uses structured error and exit fields; output text and domain-specific status codes are not failure signals.
+
+A `.observed` companion marker makes missing journals detectable after restart. Failed writes retain evidence and receipts in memory and retry on subsequent reads, with an observation-incomplete warning until storage recovers. This pending memory cannot survive process loss while persistence is unavailable. Journals and markers follow existing run retention and explicit cleanup.

package/failures.ts

@@ -0,0 +1,188 @@
+import { closeSync, fstatSync, openSync, readSync } from "node:fs";
+import { join } from "node:path";
+import { logPathFor, runDir } from "./registry.ts";
+import { failureIdentity, formatFailureSummary, markFailureAttentionDelivered,
+    observeFailures, pendingFailureAttention, readFailureState, type FailureState } from "./shared-failure-observations.ts";
+
+export { formatFailureSummary, pendingFailureAttention, markFailureAttentionDelivered };
+export const failurePath = (id: string) => join(runDir(id), "failures.jsonl");
+export const readRunFailures = (id: string): FailureState => readFailureState(failurePath(id));
+interface Attempt { operation: string; sequence: number }
+interface Scan { offset: number; head: string; identity: string; attempts: Map<string, Attempt>; failed: Map<string, { id: string; sequence: number }>; sequence: number; retry?: number }
+const scans = new Map<string, Scan>();
+/** Drop an in-memory scan cursor (e.g. on reload); the journal remains authoritative. */
+export function resetFailureScanCursor(id?: string): void {
+    if (id === undefined) scans.clear();
+    else scans.delete(id);
+}
+const CHUNK = 64 * 1024;
+const MAX_LINE = 2 * 1024 * 1024;
+function stable(value: unknown): unknown {
+    if (Array.isArray(value)) return value.map(stable);
+    if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => [k, stable(v)]));
+    return value;
+}
+export function toolOperation(name: string, args: unknown, cwd: string): string {
+    return failureIdentity("tool", name, stable(args ?? {}), cwd);
+}
+function evidence(value: unknown): string | undefined {
+    if (value == null) return undefined;
+    const raw = typeof value === "string" ? value : JSON.stringify(value);
+    return raw?.replace(/[\x00-\x1f\x7f]/g, " ").slice(0, 300);
+}
+function resultError(result: any): string | undefined {
+    if (result?.isError === true || (typeof result?.exitCode === "number" && result.exitCode !== 0)) {
+        return evidence(result?.content?.find?.((x: any) => x?.type === "text")?.text ?? result?.stderr ?? result?.error ?? result);
+    }
+    return undefined;
+}
+function time(event: any): number | undefined {
+    return typeof event.at === "number" && Number.isFinite(event.at) ? event.at :
+        typeof event.message?.timestamp === "number" && Number.isFinite(event.message.timestamp) ? event.message.timestamp : undefined;
+}
+function fold(id: string, scan: Scan, row: any, offset: number, cwd: string): void {
+    const eventId = typeof row.toolCallId === "string" ? row.toolCallId : `offset:${offset}`;
+    const seq = ++scan.sequence;
+    const path = failurePath(id);
+    if (row.type === "tool_execution_start") {
+        scan.attempts.set(eventId, { operation: toolOperation(String(row.toolName ?? "unknown"), row.args, cwd), sequence: seq });
+    } else if (row.type === "tool_execution_end") {
+        const attempt = scan.attempts.get(eventId);
+        if (attempt) scan.attempts.delete(eventId);
+        const operation = attempt?.operation ?? toolOperation(String(row.toolName ?? "unknown"), row.args, cwd);
+        const error = row.isError === true ? evidence(row.result) ?? "Tool returned an error" : resultError(row.result);
+        if (error) {
+            const failureId = `tool:${eventId}`;
+            const state = observeFailures(path, [{ id: failureId, operation, kind: "failure", at: time(row), category: "tool",
+                summary: `${row.toolName ?? "Tool"} failed: ${error.slice(0, 180)}`, evidence: `${logPathFor(id)}#byte=${offset}`,
+                expected: row.expected === true || row.result?.expected === true }]);
+            scan.failed.set(operation, { id: state.observations[failureIdentity(operation)]?.id ?? failureId, sequence: seq });
+        } else if (attempt) {
+            const failed = scan.failed.get(operation);
+            if (failed && attempt.sequence > failed.sequence) {
+                observeFailures(path, [{ id: `recovered:${eventId}`, operation, kind: "recovered", at: time(row), incidents: [failed.id] }]);
+                scan.failed.delete(operation);
+            }
+        }
+    } else if (row.type === "message_end" && row.message?.role === "assistant" &&
+        (row.message.stopReason === "error" || typeof row.message.errorMessage === "string")) {
+        const message = evidence(row.message.errorMessage) ?? "Model response failed";
+        const failureId = `model:${offset}`;
+        const state = observeFailures(path, [{ id: failureId, operation: "model-call", kind: "failure", at: time(row), category: "model", summary: message }]);
+        scan.failed.set("model-call", { id: state.observations[failureIdentity("model-call")]?.id ?? failureId, sequence: seq });
+    } else if (row.type === "auto_retry_start") {
+        if (typeof row.errorMessage === "string") {
+            const failureId = `model-retry:${offset}`;
+            const state = observeFailures(path, [{ id: failureId, operation: "model-call", kind: "failure", at: time(row), category: "model", summary: row.errorMessage }]);
+            scan.failed.set("model-call", { id: state.observations[failureIdentity("model-call")]?.id ?? failureId, sequence: seq - 1 });
+        }
+        scan.retry = seq;
+    } else if (row.type === "auto_retry_end" && row.success === false) {
+        const failureId = `model-exhausted:${offset}`;
+        const state = observeFailures(path, [{ id: failureId, operation: "model-call", kind: "failure", at: time(row), category: "model",
+            summary: evidence(row.finalError) ?? "Model retry exhausted" }]);
+        scan.failed.set("model-call", { id: state.observations[failureIdentity("model-call")]?.id ?? failureId, sequence: seq });
+        scan.retry = undefined;
+    } else if (row.type === "auto_retry_end" && row.success === true && scan.retry !== undefined) {
+        const failed = scan.failed.get("model-call");
+        if (failed && scan.retry > failed.sequence) {
+            observeFailures(path, [{ id: `model-recovered:${offset}`, operation: "model-call", kind: "recovered", at: time(row), incidents: [failed.id] }]);
+            scan.failed.delete("model-call");
+        }
+        scan.retry = undefined;
+    }
+}
+/** Scan complete source records, independent of the finite progress/transcript tail. */
+export function collectRunFailures(id: string, cwd: string, terminal = false): FailureState {
+    const path = failurePath(id);
+    let fd: number;
+    try { fd = openSync(logPathFor(id), "r"); }
+    catch (error) {
+        const prior = readRunFailures(id);
+        if ((error as NodeJS.ErrnoException).code === "ENOENT" && !terminal && !scans.has(id) && prior.seen.length === 0) return prior;
+        const access = prior.observations[failureIdentity("child-log-access")];
+        if (access && access.status !== "resolved") return prior;
+        return observeFailures(path, [{ id: failureIdentity("source-unreadable", access?.id ?? "initial"), operation: "child-log-access", kind: "incomplete",
+            summary: "Child log is unavailable; observations may be incomplete" }]);
+    }
+    try {
+        const stat = fstatSync(fd);
+        const size = stat.size;
+        const identity = `${stat.dev}:${stat.ino}`;
+        const prefix = Buffer.alloc(Math.min(256, size));
+        readSync(fd, prefix, 0, prefix.length, 0);
+        const head = prefix.toString("latin1");
+        let scan = scans.get(id);
+        const shared = scan ? Math.min(head.length, scan.head.length) : 0;
+        if (scan && (identity !== scan.identity || size < scan.offset || head.slice(0, shared) !== scan.head.slice(0, shared))) {
+            observeFailures(path, [{ id: failureIdentity("log-rewritten", scan.head, scan.offset), operation: "child-log", kind: "incomplete", summary: "Child log was truncated or rewritten; observations may be incomplete" }]);
+            scan = undefined;
+        }
+        if (!scan) scan = { offset: 0, head, identity, attempts: new Map(), failed: new Map(), sequence: 0 };
+        scan.head = head;
+        let position = scan.offset;
+        let start = position;
+        let fragments: Buffer[] = [];
+        let length = 0;
+        let oversized = false;
+        const buffer = Buffer.alloc(CHUNK);
+        while (position < size) {
+            const count = readSync(fd, buffer, 0, Math.min(CHUNK, size - position), position);
+            if (!count) break;
+            let from = 0;
+            for (let i = 0; i < count; i++) {
+                if (buffer[i] !== 10) continue;
+                const part = buffer.subarray(from, i);
+                length += part.length;
+                if (!oversized && length <= MAX_LINE) {
+                    const line = Buffer.concat([...fragments, part]).toString("utf8").trim();
+                    if (line.startsWith("{")) {
+                        try {
+                            const row = JSON.parse(line);
+                            if (["tool_execution_start", "tool_execution_end", "message_end", "auto_retry_start", "auto_retry_end"].includes(row?.type)) {
+                                if ((row.type.startsWith("tool_execution_") &&
+                                    (typeof row.toolCallId !== "string" || !row.toolCallId || typeof row.toolName !== "string")) ||
+                                    (row.type === "tool_execution_end" && typeof row.isError !== "boolean" && typeof row.result?.isError !== "boolean" && typeof row.result?.exitCode !== "number") ||
+                                    (row.type === "message_end" && (!row.message || typeof row.message.role !== "string")) ||
+                                    (row.type === "auto_retry_end" && typeof row.success !== "boolean")) throw new Error("invalid structured event");
+                                fold(id, scan, row, start, cwd);
+                            }
+                        } catch {
+                            observeFailures(path, [{ id: `malformed:${start}`, operation: "child-log", kind: "incomplete", summary: "Child log contains malformed structured events; observations may be incomplete" }]);
+                        }
+                    }
+                } else {
+                    observeFailures(path, [{ id: `oversized:${start}`, operation: "child-log", kind: "incomplete", summary: "Child log contains an oversized event; observations may be incomplete" }]);
+                }
+                start = position + i + 1;
+                from = i + 1;
+                fragments = []; length = 0; oversized = false;
+            }
+            const rest = buffer.subarray(from, count);
+            length += rest.length;
+            if (length > MAX_LINE) oversized = true;
+            if (!oversized && rest.length) fragments.push(Buffer.from(rest));
+            position += count;
+        }
+        scan.offset = start;
+        scans.delete(id);
+        scans.set(id, scan);
+        while (scans.size > 64) scans.delete(scans.keys().next().value!);
+        const access = readRunFailures(id).observations[failureIdentity("child-log-access")];
+        if (access && access.status !== "resolved") observeFailures(path, [{ id: `source-readable:${access.id}:${identity}:${size}`,
+            operation: "child-log-access", kind: "recovered", incidents: [access.id] }]);
+        if (terminal && position > start) observeFailures(path, [{ id: `partial:${start}`, operation: "child-log", kind: "incomplete", summary: "Child log ends with a partial event; observations may be incomplete" }]);
+    } catch {
+        observeFailures(path, [{ id: "log-read-error", operation: "child-log", kind: "incomplete", summary: "Child log could not be fully scanned; observations may be incomplete" }]);
+    } finally { closeSync(fd); }
+    return readRunFailures(id);
+}
+export function failureSummary(id: string, cwd: string, terminal = false): string {
+    return formatFailureSummary(collectRunFailures(id, cwd, terminal));
+}
+export function prependFailureSummary(body: string, summary: string): string {
+    if (!summary) return body;
+    // Keep the established status header first; failure evidence still precedes assistant progress.
+    const header = /^(\[[^\n]+\])\n/.exec(body);
+    return header ? `${header[1]}\n${summary}\n${body.slice(header[0].length)}` : `${summary}\n${body}`;
+}

package/finalization.ts

@@ -6,6 +6,8 @@
  */
 
 import { buildCompletionDelivery } from "./completion.ts";
+import { collectRunFailures, failurePath } from "./failures.ts";
+import { observeFailures } from "./shared-failure-observations.ts";
 import {
     classifyChildExit,
     formatSubagentResult,
@@ -57,6 +59,18 @@ export function finalizeRun(
     // Lifecycle authority streams the complete NDJSON log; result text stays bounded.
     const r = parseRunForLifecycle(id);
     const outcome = classifyChildExit(code, r);
+    collectRunFailures(id, meta.cwd, true);
+    if (!outcome.incomplete && code !== null) {
+        observeFailures(failurePath(id), ["orphaned", "lost"].map((status) => ({
+            id: `supervision:${status}:exit-recovered`, operation: `supervision:${status}`,
+            kind: "recovered" as const, incidents: [`supervision:${status}`],
+        })));
+    }
+    if (code !== 0 || outcome.incomplete) {
+        observeFailures(failurePath(id), [{ id: `exit:${code ?? "unknown"}:${outcome.classification}`,
+            operation: "child-exit", kind: outcome.incomplete ? "incomplete" : "failure",
+            category: "exit", summary: outcome.incomplete ? "Child exit evidence is incomplete" : `Child exited with code ${code}` }]);
+    }
     meta.status = outcome.status;
     meta.lifecycleClassification = outcome.classification;
     if (outcome.incomplete) meta.failureReason = "incomplete-stream";

package/index.ts

@@ -38,9 +38,10 @@ 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 { observeSandboxPermissions, resolveSubagentPermissions } from "./permission-policy.ts";
 import { resolveSubagentWorkspace } from "./git-workspace.ts";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { isAbsolute, join, relative } from "node:path";
 import {
     sessionsDir,
     runDir,
@@ -91,6 +92,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 +337,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 +355,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 +379,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 +568,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 +586,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 +630,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 +669,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 +731,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 +915,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 +929,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 +980,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 +999,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 +1186,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 +1212,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 +1313,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,11 +1344,12 @@ 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 explicitSandbox = p.sandbox === true || typeof p.sandbox_dir === "string" || p.git_clone_workspace === true || permissionPlan.enforced;
+        const sandboxEnabled = permissionPlan.sandboxEnabled;
 
-        mkdirSync(sessionsDir(), { recursive: true });
         const id = nextRunId();
+        const childSessionDir = permissionPlan.permissions ? join(sessionsDir(), id) : sessionsDir();
+        mkdirSync(childSessionDir, { recursive: true });
         mkdirSync(runDir(id), { recursive: true });
 
         const workspace = resolveSubagentWorkspace({
@@ -1320,7 +1397,7 @@ export default function (pi: ExtensionAPI) {
 
         const args = [
             "-p", "--mode", "json",
-            "--session-dir", sessionsDir(),
+            "--session-dir", childSessionDir,
             "--session-id", id,
             ...extArgs,
             ...(model ? ["--model", model] : []),
@@ -1332,10 +1409,22 @@ export default function (pi: ExtensionAPI) {
         ];
 
         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 };
@@ -1403,7 +1492,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 +1506,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 +1564,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 +1607,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 +1899,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) {