pi-better-subagents 0.6.0 → 0.7.0

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

@@ -28,10 +28,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." },
 };
 
 /**

package/docs/failure-observations.md

@@ -49,7 +49,7 @@ Sandboxed children (the task runtime) get two structured additions. The parent h
 
 - `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,27 @@ 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: `run-metadata-readable:${gap.id}`, operation: "run-metadata", kind: "recovered", incidents: [gap.id] }]);
+    scan.gap = 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);
@@ -127,9 +155,13 @@ export function collectRunFailures(id: string, cwd: string, terminal = false): F
             } 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: new Set(Object.values(prior.observations).filter((x) => x.category === "tool" && x.status === "unresolved").map((x) => x.id)) };
             }
         }
         scan.head = head;
@@ -178,6 +210,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 +233,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

@@ -202,7 +202,9 @@ 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 };
@@ -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

@@ -74,7 +74,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 +408,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);
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-subagents",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "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

package/shared-failure-observations.ts

@@ -104,24 +104,60 @@ export interface CommandIntent {
 export type CommandIntentField = keyof CommandIntent;
 const INTENT_FIELDS: readonly CommandIntentField[] = ["operationId", "attemptId", "expectedExitCodes"];
 /**
- * The one normalization of intent-bearing arguments: an explicit `null` intent field means
- * "not declared", exactly like an omitted one. Models routinely send optional fields as null, and
- * Pi's argument validation (0.87+) drops optional nulls before a tool runs, while the process log
- * and session record keep the raw arguments. Every reader of intent, the executing tool and the
- * replay alike, goes through this so both sides see the same declaration from the same input.
+ * Pi's own argument coercion for the intent fields (pi-ai `validateToolArguments` against the confined
+ * bash schema, where each field is `anyOf: [field schema, null]`). Pi applies it before execute, but the
+ * process log and session record keep the raw arguments; mirroring it lets the parent's replay read
+ * the declaration the child executed with (#332).
+ * - ids: a number or boolean becomes its string; `""` fails the pattern and falls through to null.
+ * - exit codes: array items that read as integers become integers (null -> 0, true -> 1);
+ *   a scalar `0`, `""`, or `false` falls through to null.
+ */
+function coerceInteger(value: unknown): unknown {
+  if (value === null) return 0;
+  if (typeof value === "string" && value.trim() !== "" && Number.isInteger(Number(value))) return Number(value);
+  if (typeof value === "boolean") return value ? 1 : 0;
+  return value;
+}
+function normalizeIntentField(key: CommandIntentField, value: unknown): unknown {
+  if (value == null) return undefined;
+  if (key === "expectedExitCodes") {
+    if (value === 0 || value === "" || value === false) return undefined;
+    if (!Array.isArray(value)) return value;
+    // 0 is a no-op declaration: exit 0 is already success. A list of only zeros declares nothing.
+    const codes = value.map(coerceInteger).filter((code) => code !== 0);
+    if (codes.length === 0 && value.length > 0) return undefined;
+    return codes.length === value.length && codes.every((code, index) => code === value[index]) ? value : codes;
+  }
+  if (value === "") return undefined;
+  return typeof value === "number" || typeof value === "boolean" ? String(value) : value;
+}
+/**
+ * The one normalization of intent-bearing arguments. An explicit `null` intent field means "not
+ * declared", exactly like an omitted one: models routinely send optional fields as null, and Pi's
+ * argument validation drops or nulls them before a tool runs, while the process log and session
+ * record keep the raw arguments. Values Pi would coerce are coerced the same way, and `0` is dropped
+ * from `expectedExitCodes`. Every reader of intent, the executing tool and the replay alike, and the
+ * exact operation identity go through this, so all see the same declaration from the same input.
+ * Malformed values are kept as they are for the validator to refuse.
  */
 export function withoutAbsentIntent<T>(args: T): T {
   if (!args || typeof args !== "object" || Array.isArray(args)) return args;
   const input = args as Record<string, unknown>;
-  if (!INTENT_FIELDS.some((key) => key in input && input[key] == null)) return args;
-  const out = { ...input };
-  for (const key of INTENT_FIELDS) if (key in out && out[key] == null) delete out[key];
-  return out as T;
+  let out: Record<string, unknown> | undefined;
+  for (const key of INTENT_FIELDS) {
+    if (!(key in input)) continue;
+    const value = normalizeIntentField(key, input[key]);
+    if (value === input[key]) continue;
+    out ??= { ...input };
+    if (value === undefined) delete out[key];
+    else out[key] = value;
+  }
+  return (out ?? args) as T;
 }
 /**
- * Validate structured intent fields. Absent fields (omitted, undefined, or null) are fine; malformed
+ * Validate structured intent fields after `withoutAbsentIntent`. Absent fields are fine; malformed
  * ones are an error, and the caller must not run the command. `names` renames fields in the error
- * (e.g. snake_case parameters).
+ * (e.g. snake_case parameters). `0` in `expectedExitCodes` is accepted and dropped (#332).
  */
 export function readCommandIntent(args: unknown, names: Partial<Record<CommandIntentField, string>> = {}): { intent: CommandIntent; error?: string } {
   const input = withoutAbsentIntent((args && typeof args === "object" ? args : {}) as Record<string, unknown>);
@@ -138,7 +174,7 @@ export function readCommandIntent(args: unknown, names: Partial<Record<CommandIn
   if (codes !== undefined) {
     if (!Array.isArray(codes) || codes.length === 0 || codes.length > MAX_EXPECTED_EXIT_CODES ||
       !codes.every((code) => Number.isInteger(code) && code >= 1 && code <= 255) || new Set(codes).size !== codes.length) {
-      return { intent: {}, error: `${names.expectedExitCodes ?? "expectedExitCodes"} must be 1-${MAX_EXPECTED_EXIT_CODES} distinct integers from 1 to 255` };
+      return { intent: {}, error: `${names.expectedExitCodes ?? "expectedExitCodes"} must be 1-${MAX_EXPECTED_EXIT_CODES} distinct integers from 1 to 255 (0 is allowed and ignored)` };
     }
     intent.expectedExitCodes = [...codes] as number[];
   }

package/shared-log-utils.ts

@@ -819,29 +819,22 @@ export interface OutputControls {
   maxBytes?: unknown;
   /** Raw requested line count (canonical `lines`, else deprecated `tail_lines`). */
   lines?: unknown;
-  /** Deprecated alias names the caller used (whether or not the canonical name won). */
-  deprecated: string[];
 }
 
 /**
  * Resolve output-control parameters. Both spellings work; when both are given
- * the canonical name wins. Values are returned unvalidated so each surface
- * keeps its own defaults and hard caps.
+ * the canonical name wins. An explicit `null` is "not given", so a null
+ * canonical value never hides an alias value (#332). Values are returned
+ * unvalidated so each surface keeps its own defaults and hard caps.
  */
 export function readOutputControls(params: unknown): OutputControls {
   const p = (params && typeof params === "object" ? params : {}) as Record<string, unknown>;
-  const deprecated: string[] = [];
-  const pick = (canonical: keyof typeof OUTPUT_CONTROL_ALIASES): unknown => {
-    const alias = OUTPUT_CONTROL_ALIASES[canonical];
-    if (p[alias] !== undefined) deprecated.push(alias);
-    return p[canonical] !== undefined ? p[canonical] : p[alias];
-  };
+  const pick = (canonical: keyof typeof OUTPUT_CONTROL_ALIASES): unknown => p[canonical] ?? p[OUTPUT_CONTROL_ALIASES[canonical]] ?? undefined;
   const maxBytes = pick("max_bytes");
   const lines = pick("lines");
   return {
     ...(maxBytes !== undefined ? { maxBytes } : {}),
     ...(lines !== undefined ? { lines } : {}),
-    deprecated,
   };
 }
 
@@ -851,7 +844,8 @@ export type OutputInclude = (typeof OUTPUT_INCLUDE_VALUES)[number];
 
 /** Parse an `include` request into known values and unknown ones (both deduplicated). */
 export function readOutputInclude(value: unknown): { include: Set<OutputInclude>; unknown: string[] } {
-  const raw = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : [];
+  // Any other non-null value (a number, boolean, or object) is one unknown entry, never silently nothing (#332).
+  const raw = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : value == null ? [] : [value];
   const include = new Set<OutputInclude>();
   const unknown: string[] = [];
   for (const entry of raw) {