pi-better-subagents 0.6.0 → 0.7.1

package/README.md

@@ -30,7 +30,7 @@ Try it for one run:
 pi -e npm:pi-better-subagents
 ```
 
-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 Write: tasks write across home and temp but can remove files outside the workspace only in temp, hidden home directories, and worktree folders (Linux keeps ordinary home folders read-only instead). 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.
+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 Write: tasks write across home and temp but can remove files outside the workspace only in temp, hidden home directories, and worktree folders (Linux keeps ordinary home folders read-only instead). Confined children admit `read`, `write`, `edit`, and `bash`, the guarded `apply_patch` (Codex patches that follow the file rules), and the trusted tools ticked in `/sandbox` → Subagents · Tools (default `web_fetch` and `web_search`), which run outside the file rules. Other requested tools are reported as unavailable, with the reason. 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.
 
 ## Delegation Modes
 

package/child-incidents.ts

@@ -11,9 +11,11 @@
  */
 import * as PiCodingAgent from "@earendil-works/pi-coding-agent";
 import type { BashOperations, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { emptyFailureState, reduceFailure, type FailureEvent, type FailureState } from "./shared-failure-observations.ts";
-import { DISPOSITION_TOOL, INTENT_ID_PATTERN, MAX_EXPECTED_EXIT_CODES, describeOpenTargets, foldToolEnd, foldToolStart,
-    newIncidentModel, readCommandIntent, readDispositionRequest, resolveDisposition, type IncidentModel, type IncidentSink } from "./incident-model.ts";
+// The intent validator is shared with background tasks through the vendored failure-observations module (#325).
+import { emptyFailureState, reduceFailure, INTENT_ID_PATTERN, MAX_EXPECTED_EXIT_CODES, readCommandIntent, withoutAbsentIntent,
+    type FailureEvent, type FailureState } from "./shared-failure-observations.ts";
+import { DISPOSITION_TOOL, describeOpenTargets, foldToolEnd, foldToolStart,
+    newIncidentModel, readDispositionRequest, resolveDisposition, type IncidentModel, type IncidentSink } from "./incident-model.ts";
 
 const { createBashToolDefinition } = PiCodingAgent;
 
@@ -28,10 +30,10 @@ const intentProperties = {
         description: "Optional stable id for one logical operation. Reuse it on a modified retry (changed scope, timeout, or flags) so a later success recovers the earlier failure." },
     attemptId: { ...nullable({ type: "string", pattern: INTENT_ID_PATTERN }),
         description: "Optional unique id for this execution, for use as evidence in failure_disposition." },
-    expectedExitCodes: { ...nullable({ type: "array", items: { type: "integer", minimum: 1, maximum: 255 }, minItems: 1, maxItems: MAX_EXPECTED_EXIT_CODES }),
+    expectedExitCodes: { ...nullable({ type: "array", items: { type: "integer", minimum: 0, maximum: 255 }, minItems: 1, maxItems: MAX_EXPECTED_EXIT_CODES }),
         // Distinctness is enforced by readCommandIntent, not `uniqueItems`: OpenAI rejects that keyword
         // in function schemas, which failed every confined child's first request.
-        description: "Optional distinct non-zero exit codes that are intentional for this command (for example [1] for an rg/grep no-match or git diff --exit-code probe). Declared before the command runs; the final shell exit code is what is classified." },
+        description: "Optional distinct non-zero exit codes that are intentional for this command (for example [1] for an rg/grep no-match or git diff --exit-code probe). 0 is allowed and ignored: exit 0 is already success. Declared before the command runs; the final shell exit code is what is classified." },
 };
 
 /**
@@ -95,7 +97,7 @@ export function intentBashDefinition(cwd: string, operations: BashOperations) {
             if (error) throw new Error(`Invalid command intent: ${error}. The command was not run.`);
             if (intent.attemptId) {
                 const reused = sessionToolCalls(ctx).some((row) => row.type === "tool_execution_start" && row.toolName === "bash" &&
-                    row.toolCallId !== toolCallId && (row.args as any)?.attemptId === intent.attemptId);
+                    row.toolCallId !== toolCallId && (withoutAbsentIntent(row.args) as any)?.attemptId === intent.attemptId);
                 if (reused) throw new Error(`Invalid command intent: attemptId ${intent.attemptId} was already used. The command was not run.`);
             }
             const { operationId: _o, attemptId: _a, expectedExitCodes: _e, ...command } = params ?? {};

package/docs/failure-observations.md

@@ -47,9 +47,11 @@ Automatic recovery still requires an exact retry: the same tool name, arguments,
 
 Sandboxed children (the task runtime) get two structured additions. The parent honours them only for runs it launched on the task runtime: `meta.taskRuntime` and a parent-authored provenance record written before the child starts, outside the run directory, where the confined child cannot write. For any other run, intent-looking arguments are ordinary arguments and `failure_disposition` calls are ignored. If the metadata cannot be read for a moment, the parent waits and reads it again rather than falling back to the exact rule for the rest of the run. The wait is bounded: when the run ends, or after 30 seconds, the log is scanned under the exact-retry rule so real failures stay visible, with an `Observation incomplete` note that the metadata could not be read.
 
+Trust is decided once per scan, when the scan begins. A running trusted run whose metadata later becomes unreadable (a corrupt `meta.json`, say) keeps its trusted scan for as long as the parent keeps that scan in memory. Only after a parent restart, a `/reload`, or an eviction from the scan cache does the bounded wait apply again, and the scan after it uses the exact-retry rule with the same note. When the metadata is readable again, a later trusted scan closes the note once the incidents that the exact-rule scan left unresolved are resolved. Failures from the trusted period never hold it open, however often the scan is rebuilt.
+
 - `bash` accepts optional `operationId`, `attemptId`, and `expectedExitCodes`, validated before the command runs.
   - `operationId` names one logical operation across modified retries. A later success with the same `operationId` (a changed scope, timeout, or flag) recovers the earlier failure automatically. Without it, the exact rule applies. `attemptId` names one execution for use as evidence and never changes operation identity.
-  - `expectedExitCodes` (distinct integers 1–255) declares intentional non-zero exits, such as `[1]` for an `rg`/`grep` no-match or a `git diff --exit-code` probe. Only the final shell exit code is classified, taken from the tool's structured result, never from output text. Timeouts, aborts, and undeclared codes stay ordinary failures.
+  - `expectedExitCodes` (distinct integers 1–255; a `0` is ignored, since exit 0 is already success) declares intentional non-zero exits, such as `[1]` for an `rg`/`grep` no-match or a `git diff --exit-code` probe. Only the final shell exit code is classified, taken from the tool's structured result, never from output text. Timeouts, aborts, and undeclared codes stay ordinary failures.
 - `failure_disposition({ disposition, targets, reason, evidence? })` records an explicit classification of the child's own incidents:
   - `recovered`: the same operation later passed. Evidence must be a successful attempt of that operation that started after the failure.
   - `superseded`: a different verification or remediation established the outcome, such as resolving a merge conflict and continuing. Evidence must be a successful attempt that started after the failure.

package/failures.ts

@@ -1,14 +1,21 @@
 import { closeSync, fstatSync, openSync, readSync } from "node:fs";
 import { join } from "node:path";
 import { logPathFor, runDir, taskRuntimeTrust } from "./registry.ts";
-import { activeFailures, disposeIncidents, failureIdentity, formatFailureSummary, formatTerminalFailureFacts, markFailureAttentionDelivered,
+import { activeFailures, actionableFailures, disposeIncidents, failureIdentity, findIncident, formatFailureSummary, formatTerminalFailureFacts, markFailureAttentionDelivered,
     observeFailures, pendingFailureAttention, readFailureState, type FailureState } from "./shared-failure-observations.ts";
 import { evidenceText, foldToolEnd, foldToolStart, newIncidentModel, toolOperation, type IncidentModel, type IncidentSink } from "./incident-model.ts";
 
 export { formatFailureSummary, pendingFailureAttention, markFailureAttentionDelivered, toolOperation };
 export const failurePath = (id: string) => join(runDir(id), "failures.jsonl");
 export const readRunFailures = (id: string): FailureState => readFailureState(failurePath(id));
-interface Scan { offset: number; head: string; identity: string; model: IncidentModel; retry?: number }
+interface Scan {
+    offset: number; head: string; identity: string; model: IncidentModel; retry?: number;
+    /**
+     * A "run metadata could not be read" gap this trusted rescan inherited, with the tool incidents
+     * that were unresolved when it began (the earlier exact-rule scan's). Re-checked after every scan.
+     */
+    gap?: { id: string; before: Set<string> };
+}
 const scans = new Map<string, Scan>();
 /** When each run's trust first could not be read, for the bounded wait (#325). */
 const trustUnknownSince = new Map<string, number>();
@@ -74,6 +81,73 @@ function fold(id: string, scan: Scan, row: any, offset: number, cwd: string): vo
         ++model.sequence;
     }
 }
+/**
+ * Close an inherited metadata gap unless an exact-rule leftover still needs it. A leftover counts only
+ * when its attempt declared intent (operationId, attemptId, or expectedExitCodes): its event id is
+ * already consumed under the exact rule, so this trusted scan cannot re-key it, and a declared retry
+ * or expected exit cannot resolve it. A plain failure reads the same under either rule and never
+ * holds the gap. Once the leftover is resolved (an exact retry or a disposition), the gap closes.
+ */
+function settleMetadataGap(id: string, scan: Scan): void {
+    const gap = scan.gap!;
+    const state = readRunFailures(id);
+    const current = state.observations[failureIdentity("run-metadata")];
+    if (!current || current.id !== gap.id || current.status !== "unresolved") { scan.gap = undefined; return; }
+    const intentBearing = new Set<string>();
+    for (const attempt of scan.model.finished.values()) {
+        if (attempt.incident && gap.before.has(attempt.incident) && Object.keys(attempt.intent).length) intentBearing.add(attempt.incident);
+    }
+    const held = [...intentBearing].some((incident) => findIncident(state, incident)?.status === "unresolved");
+    if (held) return;
+    observeFailures(failurePath(id), [{ id: failureIdentity("run-metadata-readable", gap.id), operation: "run-metadata", kind: "recovered", incidents: [gap.id] }]);
+    scan.gap = undefined;
+}
+/**
+ * Scan-period markers (#332). While a "run metadata could not be read" gap is open, each scan that
+ * starts under a different rule from the last marked one journals a no-op marker (a `delivered`
+ * event naming no incident) whose id records the rule: `run-metadata-scan:<rule>:<journal length>`.
+ * The ids are read back by prefix, so they are plain strings, not `failureIdentity` hashes.
+ */
+const SCAN_MARKER_PREFIX = "run-metadata-scan:";
+type ScanRule = "exact" | "trusted";
+function scanRuleAt(marker: string): ScanRule | undefined {
+    if (!marker.startsWith(SCAN_MARKER_PREFIX)) return undefined;
+    const rule = marker.slice(SCAN_MARKER_PREFIX.length).split(":")[0];
+    return rule === "exact" || rule === "trusted" ? rule : undefined;
+}
+/** Journal that a scan under `rule` begins, unless the last marked period already used it. */
+function markScanPeriod(path: string, state: FailureState, rule: ScanRule): FailureState {
+    let last: ScanRule | undefined;
+    for (let i = state.seen.length - 1; i >= 0 && !last; i -= 1) last = scanRuleAt(state.seen[i]!);
+    if (last === rule) return state;
+    return observeFailures(path, [{ id: `${SCAN_MARKER_PREFIX}${rule}:${state.seen.length}`, operation: "run-metadata", kind: "delivered", incidents: [] }]);
+}
+/**
+ * The unresolved tool incidents first journaled by an exact-rule scan, which a trusted scan cannot
+ * re-key. Each incident belongs to the period of the last marker before it, so a failure from a
+ * trusted period is never mistaken for a leftover, however often the scan is rebuilt (a parent
+ * restart, `/reload`, or cache eviction), and a later exact-rule period's failures always are. An
+ * incident before every marker is a leftover only when the journal has no exact-rule marker at all
+ * (the first trusted scan of a gap, or a journal from before the markers existed).
+ */
+function exactRuleLeftovers(path: string, prior: FailureState): Set<string> {
+    const state = markScanPeriod(path, prior, "trusted");
+    const period = new Map<string, ScanRule | undefined>();
+    let current: ScanRule | undefined;
+    let sawExact = false;
+    for (const id of state.seen) {
+        const rule = scanRuleAt(id);
+        if (rule) { current = rule; sawExact ||= rule === "exact"; continue; }
+        period.set(id, current);
+    }
+    const leftover = (id: string) => {
+        if (!period.has(id)) return false;
+        const rule = period.get(id);
+        return rule === "exact" || (rule === undefined && !sawExact);
+    };
+    return new Set(Object.values(state.observations)
+        .filter((x) => x.category === "tool" && x.status === "unresolved" && leftover(x.id)).map((x) => x.id));
+}
 /** 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);
@@ -123,13 +197,17 @@ export function collectRunFailures(id: string, cwd: string, terminal = false): F
                         summary: "Run metadata could not be read; tool failures are scanned under the exact-retry rule" }]);
                 }
                 if (!waited) return prior;
+                markScanPeriod(path, readRunFailures(id), "exact");
                 scan = { offset: 0, head, identity, model: newIncidentModel(false) };
             } else {
                 trustUnknownSince.delete(id);
                 scan = { offset: 0, head, identity, model: newIncidentModel(trust === "trusted") };
-                const deferred = readRunFailures(id).observations[failureIdentity("run-metadata")];
-                if (deferred && deferred.status === "unresolved") observeFailures(path, [{ id: `run-metadata-readable:${deferred.id}`,
-                    operation: "run-metadata", kind: "recovered", incidents: [deferred.id] }]);
+                // The gap is settled after this scan has folded the log (settleMetadataGap), and again after
+                // every later scan, once no leftover of the exact-rule scan that trust would have read
+                // differently is still unresolved (#332).
+                const prior = readRunFailures(id);
+                const deferred = prior.observations[failureIdentity("run-metadata")];
+                if (deferred && deferred.status === "unresolved") scan.gap = { id: deferred.id, before: exactRuleLeftovers(path, prior) };
             }
         }
         scan.head = head;
@@ -178,6 +256,7 @@ export function collectRunFailures(id: string, cwd: string, terminal = false): F
             position += count;
         }
         scan.offset = start;
+        if (scan.gap) settleMetadataGap(id, scan);
         scans.delete(id);
         scans.set(id, scan);
         while (scans.size > 64) scans.delete(scans.keys().next().value!);
@@ -200,7 +279,16 @@ export function runFailureFacts(state: FailureState, terminal: boolean): string
     return formatTerminalFailureFacts(state, activeFailures(state).map((x) => x.id));
 }
 export function failureSummary(id: string, cwd: string, terminal = false): string {
-    return runFailureFacts(collectRunFailures(id, cwd, terminal), terminal);
+    return failureView(id, cwd, terminal).text;
+}
+/**
+ * The failure facts plus whether anything needs action. A navigator row leads with failure text only
+ * when something does; a quiet "No failures need action · … (history)" line never displaces the
+ * row's model, tool, and spend columns (#332).
+ */
+export function failureView(id: string, cwd: string, terminal = false): { text: string; actionable: boolean } {
+    const state = collectRunFailures(id, cwd, terminal);
+    return { text: runFailureFacts(state, terminal), actionable: actionableFailures(state).length > 0 };
 }
 export function prependFailureSummary(body: string, summary: string): string {
     if (!summary) return body;

package/incident-model.ts

@@ -8,12 +8,10 @@
  * `operationId` or the exact tool/arguments/cwd hash; expected exits require a code
  * declared on the attempt before it ran and a structured exit code from the tool.
  */
-import { failureIdentity, findIncident, validateDisposition, INCIDENT_DISPOSITIONS, INTENT_ID_PATTERN, MAX_EXPECTED_EXIT_CODES,
+import { failureIdentity, findIncident, validateDisposition, INCIDENT_DISPOSITIONS,
     REJECTED_INTENT_CATEGORY, readCommandIntent, withoutAbsentIntent, type CommandIntent, type FailureEvent, type FailureState, type IncidentDisposition } from "./shared-failure-observations.ts";
 
 export const DISPOSITION_TOOL = "failure_disposition";
-// The intent validator is shared with background tasks through the vendored failure-observations module (#325).
-export { INTENT_ID_PATTERN, MAX_EXPECTED_EXIT_CODES, readCommandIntent, withoutAbsentIntent, type CommandIntent };
 
 function stable(value: unknown): unknown {
     if (Array.isArray(value)) return value.map(stable);
@@ -202,15 +200,19 @@ export function foldToolStart(model: IncidentModel, row: any, cwd: string, sink:
     const seq = ++model.sequence;
     if (!model.structuredIntent) {
         // Unconfined: intent-looking fields are ordinary arguments; exact identity only.
-        model.open.set(toolCallId, { toolCallId, toolName, operation: toolOperation(toolName, row.args, cwd), intent: {}, startSequence: seq });
+        // An explicit-null intent-named field is still normalized away, as on the confined path, so
+        // `{command, expectedExitCodes: null}` and `{command}` are one command (#332).
+        model.open.set(toolCallId, { toolCallId, toolName, operation: toolOperation(toolName, withoutAbsentIntent(row.args), cwd), intent: {}, startSequence: seq });
         return;
     }
     const parsed = toolName === "bash" ? readCommandIntent(row.args) : { intent: {} as CommandIntent };
     const intent = parsed.intent;
-    // Mirrors the child's check: any earlier bash start that named this attemptId, valid or not.
-    const rawAttemptId = toolName === "bash" && typeof row.args?.attemptId === "string" ? row.args.attemptId as string : undefined;
-    const reused = rawAttemptId !== undefined && model.namedAttempts.has(rawAttemptId);
-    if (rawAttemptId !== undefined) model.namedAttempts.add(rawAttemptId);
+    // Mirrors the child's check: any earlier bash start that named this attemptId, valid or not. The name
+    // is read after the same normalization the child applies, so `attemptId: ""` or `null` names nothing (#332).
+    const namedArgs = toolName === "bash" ? withoutAbsentIntent(row.args) : undefined;
+    const namedAttemptId = typeof namedArgs?.attemptId === "string" ? namedArgs.attemptId as string : undefined;
+    const reused = namedAttemptId !== undefined && model.namedAttempts.has(namedAttemptId);
+    if (namedAttemptId !== undefined) model.namedAttempts.add(namedAttemptId);
     const predictedRejection = parsed.error ?? (reused ? `attemptId ${intent.attemptId} was already used` : undefined);
     // A predicted refusal falls back to exact identity: if the child ran the command after all, it is
     // an ordinary failure of exactly that command, never a failure of the operation it named.
@@ -238,8 +240,13 @@ export function foldToolStart(model: IncidentModel, row: any, cwd: string, sink:
 
 /** The confined intent bash's own pre-run refusal (child-incidents.ts), matched as the whole result text. */
 const INTENT_REFUSAL = /^Invalid command intent: ([\s\S]+)\. The command was not run\.$/;
-/** Pi's pre-execution schema rejection; it names the tool, and nothing ran. */
-const SCHEMA_REFUSAL = /^Validation failed for tool "/;
+/**
+ * Pi's pre-execution schema rejection of the bash call (pi-ai `validateToolArguments`), matched as its
+ * whole shape: the header, one or more `  - path: message` lines, and the received arguments as
+ * pretty-printed JSON ending the text, so a command that ran (and ends "Command exited with code N")
+ * can never match. Nothing ran.
+ */
+const SCHEMA_REFUSAL = /^Validation failed for tool "bash":\n(?:  - [^\n]*\n)+\nReceived arguments:\n(?:\{\}|\{(?:\n {2,}[^\n]*)*\n\})$/;
 
 /**
  * Why the child refused this bash call before running it, read from the end row the child
@@ -266,7 +273,7 @@ export function foldToolEnd(model: IncidentModel, row: any, cwd: string, evidenc
     const attempt = model.open.get(toolCallId);
     if (attempt) model.open.delete(toolCallId);
     const intent = attempt?.intent ?? {};
-    const operation = attempt?.operation ?? toolOperation(toolName, row.args, cwd);
+    const operation = attempt?.operation ?? toolOperation(toolName, withoutAbsentIntent(row.args), cwd);
     const details = row.result?.details;
     const declaredExit = row.isError === false && details?.expectedExit === true && typeof details.exitCode === "number" &&
         (intent.expectedExitCodes ?? []).includes(details.exitCode) ? details.exitCode as number : undefined;

package/index.ts

@@ -12,7 +12,7 @@
  */
 
 import { execSync } from "node:child_process";
-import { writeFileSync, mkdirSync, renameSync, rmSync, statSync } from "node:fs";
+import { writeFileSync, mkdirSync, renameSync, statSync } from "node:fs";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import * as PiCodingAgent from "@earendil-works/pi-coding-agent";
 import * as PiTui from "@earendil-works/pi-tui";
@@ -57,6 +57,7 @@ import { resolveExtensions, extensionArgs } from "./extensions.ts";
 import { prepareTaskRuntime } from "./task-policy.ts";
 import { canonicalizePath, takeRecoverySnapshot } from "./shared-sandbox-core.ts";
 import { TASK_BUILTINS } from "./shared-task-sandbox.ts";
+import { APPLY_PATCH, describeTaskTools, planTaskTools } from "./subagent-tools.ts";
 import { observeSandboxPermissions, resolveSubagentPermissions } from "./permission-policy.ts";
 import { resolveSubagentWorkspace } from "./git-workspace.ts";
 import { join } from "node:path";
@@ -66,7 +67,7 @@ import {
     sessionsDir,
     runDir,
     recordTaskRuntimeProvenance,
-    removeRunDirectory,
+    discardFailedLaunch,
     logPathFor,
     promptPathFor,
     nextRunId,
@@ -115,7 +116,7 @@ import {
 import { buildHealthCallbackDelivery } from "./completion.ts";
 import { cancelCallbackBatch, getCallbackBatcher } from "./shared-callback-batcher.ts";
 import { completionCallbackFields, failureAttentionFields, healthCallbackFields } from "./callback-fields.ts";
-import { collectRunFailures, failurePath, failureSummary, markFailureAttentionDelivered, pendingFailureAttention, prependFailureSummary } from "./failures.ts";
+import { collectRunFailures, failurePath, failureView, markFailureAttentionDelivered, pendingFailureAttention, prependFailureSummary } from "./failures.ts";
 import { failureAttentionHandled, observeFailures } from "./shared-failure-observations.ts";
 import {
     text,
@@ -1132,8 +1133,9 @@ 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] || "";
+        const failure = failureView(row.id, metaById.get(row.id)?.cwd ?? "", row.status !== "running" && row.status !== "orphaned");
+        // Only a failure that needs action replaces the row's columns; history stays in the detail view.
+        const firstFailure = failure.actionable ? failure.text.split("\n")[0] || "" : "";
         return {
             providerId: "subagents",
             id: row.id,
@@ -1197,7 +1199,8 @@ 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 view = failureView(id, readMeta(id)?.cwd ?? "", detail.status !== "running" && detail.status !== "orphaned");
+    const failure = view.text;
     const metadata = [
         ...(failure ? [{ label: "failure", value: failure.split("\n")[0]! }] : []),
         { label: "provider", value: "Subagents" },
@@ -1216,7 +1219,7 @@ function subagentWorkDetail(id: string, now: number, options?: { logTailLines?:
         title: detail.name || detail.id,
         status: detail.status,
         statusTone: statusTone(detail.status),
-        subtitle: failure.split("\n")[0] || (detail.currentTool ? `current tool ${detail.currentTool}` : undefined),
+        subtitle: (view.actionable && failure.split("\n")[0]) || (detail.currentTool ? `current tool ${detail.currentTool}` : undefined),
         metadata,
         evidence: { label: "transcript", text: prependFailureSummary(detail.output || "(no transcript yet)", failure) },
         transcript: transcript.entries,
@@ -1587,13 +1590,15 @@ export default function (pi: ExtensionAPI) {
 
         const id = nextRunId();
         const childSessionDir = sandboxEnabled ? join(sessionsDir(), id) : sessionsDir();
+        // The disposable clone this launch owns (removed if the spawn fails); a caller's sandbox_dir is not ours.
+        const ownedCloneWorkspace = !p.sandbox_dir && sandboxEnabled && p.git_clone_workspace ? taskWorkspaceDir(id) : undefined;
         mkdirSync(childSessionDir, { recursive: true });
         mkdirSync(runDir(id), { recursive: true });
 
         const workspace = resolveSubagentWorkspace({
             ctxCwd: ctx.cwd,
             cwd: p.cwd,
-            sandboxDir: p.sandbox_dir ?? (sandboxEnabled && p.git_clone_workspace ? taskWorkspaceDir(id) : undefined),
+            sandboxDir: p.sandbox_dir ?? ownedCloneWorkspace,
             gitCloneWorkspace: p.git_clone_workspace,
             runId: id,
             runDirPath: runDir(id),
@@ -1616,14 +1621,32 @@ export default function (pi: ExtensionAPI) {
                 .filter(Boolean).join(",");
         }
 
+        // A confined child gets extension tools only through /sandbox Subagents · Tools (ADR 0009):
+        // the guarded apply_patch adapter, and trusted tools admitted by name and package.
+        const requestedExcludes = new Set((p.exclude_tools ?? "").split(",").map((t) => t.trim()).filter(Boolean));
+        if (sandboxEnabled && !clean) {
+            const names = allow.split(",").filter(Boolean);
+            // Models reach for apply_patch whenever they may edit; ticked trusted tools join the default set.
+            if (permissionPlan.tools.applyPatch && names.some((name) => name === "edit" || name === "write")) names.push(APPLY_PATCH);
+            if (p.tools === undefined) names.push(...permissionPlan.tools.trusted.map((entry) => entry.name));
+            allow = [...new Set(names)].join(",");
+        }
+        const taskTools = sandboxEnabled ? planTaskTools({
+            requested: allow.split(",").filter((name) => name && !requestedExcludes.has(name)),
+            settings: permissionPlan.tools, network: permissionPlan.permissions?.network ?? true,
+            builtins: TASK_BUILTINS, registered: pi.getAllTools?.() ?? [],
+            toolExtensions: cfg.toolExtensions, resolvePath: resolveExtensionPath,
+        }) : undefined;
         const resolution = resolveExtensions({
             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: resolvedExtArgs, missing } = extensionArgs(resolution, resolveExtensionPath);
+        const trustedExtArgs = [...new Set(taskTools?.trusted.map((tool) => tool.loadPath) ?? [])]
+            .filter((path) => !resolvedExtArgs.includes(path)).flatMap((path) => ["--extension", path]);
         // The harness's own child control extension (no tools, no command I/O) rides along in every
         // mode, including clean: it is how a soft-deadline steer reaches the child session.
-        const extArgs = [...resolvedExtArgs, "--extension", childSteerExtensionPath()]
+        const extArgs = [...resolvedExtArgs, ...trustedExtArgs, "--extension", childSteerExtensionPath()]
             .map((value, index, all) => sandboxEnabled && all[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.");
@@ -1656,13 +1679,16 @@ export default function (pi: ExtensionAPI) {
 
         const piBin = resolvePiBinary();
         const selectedTools = allow.split(",").filter((name) => name && !excludes.has(name));
-        const unavailableTools = sandboxEnabled ? selectedTools.filter((name) => !(TASK_BUILTINS as readonly string[]).includes(name)) : [];
+        const unavailable = taskTools?.refused.filter((tool) => selectedTools.includes(tool.name)) ?? [];
+        const unavailableTools = unavailable.map((tool) => tool.name);
         if (sandboxEnabled && selectedTools.length && unavailableTools.length === selectedTools.length) {
-            throw new Error(`No requested tool has a verified task sandbox adapter: ${unavailableTools.join(", ")}.`);
+            throw new Error(`No requested tool has a verified task sandbox adapter: ${unavailable.map((tool) => `${tool.name} (${tool.reason})`).join(", ")}.`);
         }
         const taskRuntime = sandboxEnabled && requestedSandboxDir ? prepareTaskRuntime({
             root: requestedSandboxDir, controlDir: join(runDir(id), "control"), piBin,
             tools: selectedTools, permissions: permissionPlan.permissions,
+            applyPatch: taskTools?.applyPatch === true,
+            extensionTools: taskTools?.trusted.map(({ loadPath: _loadPath, ...tool }) => tool) ?? [],
             extensionPaths: extArgs.flatMap((arg, index) => arg === "--extension" && extArgs[index + 1] ? [extArgs[index + 1]!] : []),
             runtimeRoots: [baseDir()],
         }) : undefined;
@@ -1686,10 +1712,10 @@ export default function (pi: ExtensionAPI) {
             spawned = spawnDetached({ file: cmd.file, fileArgs: cmd.fileArgs, cwd, logPath: logPathFor(id),
                 env: { [STEER_FILE_ENV]: steerPathFor(id) } });
         } catch (error) {
-            // Nothing references the run yet (no metadata): drop its directory (prompt, control/),
-            // its provenance record, and the task scratch, so a failed launch leaves nothing behind (#325).
-            try { removeRunDirectory(id); } catch { /* best effort */ }
-            if (taskRuntime?.policy.scratch) rmSync(taskRuntime.policy.scratch, { recursive: true, force: true });
+            // Nothing references the run yet (no metadata): drop its directory (prompt, control/), its
+            // provenance record, its session directory, its clone workspace, and the task scratch, so a
+            // failed launch leaves nothing behind (#325, #332).
+            discardFailedLaunch(id, { sessionDir: childSessionDir, workspaceDir: ownedCloneWorkspace, scratch: taskRuntime?.policy.scratch });
             throw error;
         }
         // Record process identity (pgid, start-time token) so health
@@ -1726,13 +1752,16 @@ export default function (pi: ExtensionAPI) {
         // Footer hint: a visible run now exists, so `← background work · N` shows.
         updateNavigatorFooter(ctx);
 
+        const toolSummary = taskTools ? describeTaskTools(taskTools) : undefined;
         const runtime = resolution.mode === "inherit"
             ? `Runtime: ALL installed extensions (inheritExtensions) — mid-turn drain risk\n`
-            : resolution.specs.length
+            : toolSummary
+                ? `Runtime: isolated · ${toolSummary}${resolution.specs.length ? ` · extensions ${resolution.specs.join(", ")}` : ""}\n`
+                : resolution.specs.length
                 ? `Runtime: isolated · extensions ${resolution.specs.join(", ")}\n`
                 : `Runtime: isolated · built-in tools only\n`;
-        const warn = (unavailableTools.length ? `Task sandbox: unavailable adapters for ${unavailableTools.join(", ")}; these tools are disabled.\n` : "") +
-            (resolution.unmapped.length
+        const warn = (unavailable.length ? `Task sandbox: ${unavailable.map((tool) => `${tool.name} disabled (${tool.reason})`).join("; ")}.\n` : "") +
+            (!sandboxEnabled && 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`

package/output-payload.ts

@@ -48,6 +48,7 @@ import {
 import {
     actionableFailures,
     failureJournalFingerprint,
+    fileChangeIdentity,
     failureRevision,
     formatIncidentSummary,
     formatTerminalIncidentSummary,
@@ -74,7 +75,6 @@ export interface PayloadRequest {
     mode?: unknown;
     all?: unknown;
     lines?: unknown;
-    tail_lines?: unknown;
     limit?: unknown;
     /** Explicit opt-in facts: `cost` (token/cost spend) and/or `tools` (tool-call count). */
     include?: unknown;
@@ -409,12 +409,12 @@ function answerReserve(maxBytes: number, cursor: string | undefined): number {
 }
 
 function outputLineCap(request: PayloadRequest): number {
-    return positiveInt(request.lines) ?? positiveInt(request.tail_lines) ?? OUTPUT_PAGE_DEFAULTS.logLines;
+    return positiveInt(request.lines) ?? OUTPUT_PAGE_DEFAULTS.logLines;
 }
 
 /** Answer-page line cap for subagent_result: only an explicit `lines` request caps it. */
 function answerLineCap(request: PayloadRequest): number | undefined {
-    return positiveInt(request.lines) ?? positiveInt(request.tail_lines);
+    return positiveInt(request.lines);
 }
 
 /**
@@ -778,16 +778,7 @@ const LIST_INCIDENT_CACHE_MAX = 4096;
 let listIncidentComputations = 0;
 
 function listIncidentKey(id: string, terminal: boolean): string {
-    return JSON.stringify([terminal, logIdentityKey(logPathFor(id)), failureJournalFingerprint(failurePath(id))]);
-}
-
-function logIdentityKey(path: string): string {
-    try {
-        const stats = statSync(path, { bigint: true });
-        return `${stats.dev}:${stats.ino}:${stats.size}:${stats.mtimeNs}:${stats.ctimeNs}`;
-    } catch (error) {
-        return `unreadable:${(error as NodeJS.ErrnoException).code ?? "error"}`;
-    }
+    return JSON.stringify([terminal, fileChangeIdentity(logPathFor(id)), failureJournalFingerprint(failurePath(id))]);
 }
 
 export function listIncidentCount(id: string, cwd: string, terminal: boolean): ListIncidentCount {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-subagents",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Pi extension for detached, sandboxed subagent runs that keep the foreground session free.",
   "license": "MIT",
   "type": "module",

package/permission-policy.ts

@@ -1,4 +1,5 @@
 /** Optional sandbox-extension policy, mirrored per Pi event bus at launch time. */
+import { defaultSubagentTools, parseSubagentTools, type SubagentToolSettings } from "./shared-task-tools.ts";
 export const SANDBOX_POLICY_CHANNEL = "pi-better-sandbox:policy";
 export const SANDBOX_POLICY_REQUEST_CHANNEL = "pi-better-sandbox:policy-request";
 
@@ -15,6 +16,7 @@ export type PermissionProfile = Readonly<{
 export type PermissionSnapshot = Readonly<{
     permissions?: PermissionProfile;
     subagentPermissions?: PermissionProfile;
+    subagentTools?: SubagentToolSettings;
 }>;
 
 type EventBus = {
@@ -52,6 +54,7 @@ function readPolicy(data: unknown): PermissionSnapshot | undefined {
     return Object.freeze({
         ...(p.permissions === undefined ? {} : { permissions: profile(p.permissions) }),
         ...(p.subagentPermissions === undefined ? {} : { subagentPermissions: profile(p.subagentPermissions) }),
+        ...(p.subagentTools === undefined ? {} : { subagentTools: parseSubagentTools(p.subagentTools) }),
     });
 }
 
@@ -87,20 +90,23 @@ export function resolveSubagentPermissions(pi: unknown, requestedSandbox: boolea
     sandboxEnabled: boolean;
     enforced: boolean;
     permissions?: Omit<PermissionProfile, "enabled">;
+    /** Which extension tools a confined child may use; defaults when no settings are published. */
+    tools: SubagentToolSettings;
 } {
     const snapshot = currentSandboxPermissions(pi);
+    const tools = snapshot?.subagentTools ?? defaultSubagentTools();
     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) return { sandboxEnabled: requestedSandbox !== false, enforced: false, tools };
     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 };
+    if (!sandboxEnabled) return { sandboxEnabled: false, enforced: false, tools };
     // 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 };
+    return { sandboxEnabled: true, enforced: true, permissions, tools };
 }

package/registry.ts

@@ -235,16 +235,33 @@ export function removeRunDirectory(id: string): void {
     rmSync(runDir(id), { recursive: true, force: true });
     removeTaskRuntimeProvenance(id);
 }
+/**
+ * Undo everything a launch prepared before its child failed to spawn (#325, #332). Nothing references
+ * the run yet (no metadata), so its run directory and provenance go, plus the per-run session
+ * directory and disposable clone workspace of a sandboxed launch and the task scratch. Only the
+ * run's own paths are removed: a shared sessions directory or a caller-chosen sandbox_dir is kept.
+ */
+export function discardFailedLaunch(id: string, prepared: { sessionDir?: string; workspaceDir?: string; scratch?: string } = {}): void {
+    try { removeRunDirectory(id); } catch { /* best effort */ }
+    const remove = (path: string) => { try { rmSync(path, { recursive: true, force: true }); } catch { /* best effort */ } };
+    if (prepared.sessionDir && prepared.sessionDir === join(sessionsDir(), id)) remove(prepared.sessionDir);
+    if (prepared.workspaceDir && /^sa_[a-z0-9]+_[a-z0-9]+$/i.test(id) && prepared.workspaceDir === taskWorkspaceDir(id)) remove(prepared.workspaceDir);
+    if (prepared.scratch) remove(prepared.scratch);
+}
 /** Best-effort removal of a run's provenance record (e.g. after a failed launch). */
 export function removeTaskRuntimeProvenance(id: string): void {
     try { rmSync(taskRuntimeProvenancePath(id), { force: true }); } catch { /* invalid id or already gone */ }
 }
-/** Provenance records whose run directory no longer exists (e.g. removed by an older version). */
+/**
+ * Provenance records whose run directory no longer exists (e.g. removed by an older version). Only a
+ * definite ENOENT counts as gone: any other stat error (permissions, I/O) keeps the record, since
+ * deleting a live run's provenance would silently drop it to the exact-retry rule (#332).
+ */
 export function orphanedTaskRuntimeProvenance(): string[] {
     let names: string[];
     try { names = readdirSync(join(baseDir(), "task-runtime")); } catch { return []; }
     return names.filter((name) => name.endsWith(".json")).map((name) => name.slice(0, -5))
-        .filter((id) => { try { statSync(runDir(id)); return false; } catch { return true; } });
+        .filter((id) => { try { statSync(runDir(id)); return false; } catch (error) { return (error as NodeJS.ErrnoException).code === "ENOENT"; } });
 }
 /**
  * Whether the parent may honour structured intent for this run. `unknown` means the answer could