pi-better-subagents 0.5.1 → 0.6.0

package/README.md

@@ -16,6 +16,7 @@ Use `pi-better-subagents` when you want Pi to launch independent agent work with
 - Explicit tool allowlists for child sessions.
 - Durable logs, result retrieval, and [failure observations](docs/failure-observations.md) independent of lifecycle status. A live child handles its own tool errors; the parent is woken only for actionable incidents, and children can classify handled failures with `failure_disposition`.
 - Live background-work navigator for active runs.
+- Harness-owned run timing: every run gets a soft deadline (30 min, then a wrap-up steer into the child and one parent wake, stopped after 5 min grace), a hard ceiling (90 min), and a no-progress wake (10 min). Override per spawn with `deadline_minutes`, `grace_minutes`, `max_minutes`, `stuck_minutes`, or globally in `config.json` / `PI_SUBAGENT_*_MINUTES`. See [usage notes](docs/usage.md#run-timing-deadline-ceiling-stuck).
 
 ## Install
 
@@ -29,7 +30,18 @@ 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 Read. Currently confined children admit `read`, `write`, `edit`, and `bash`; unsupported requested tools are reported as unavailable. See [usage notes](https://github.com/1aboveio/pi-better-harness/blob/main/packages/pi-better-subagents/docs/usage.md#write-sandbox) for the runtime boundary and supported configurations.
+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.
+
+## Delegation Modes
+
+`config.json` sets `delegationMode` to `manual`, `adaptive` (default), or
+`coordinator`. `/subagents` displays the active mode, and
+`/subagents mode manual|adaptive|coordinator` changes it for the current
+session without changing config. Manual delegates only on explicit user or workflow request, even with a
+plan. Adaptive delegates substantial independent work when useful. Coordinator
+uses `agents_catalog` to discover current role descriptions and delegates every
+nontrivial role-owned task, while the foreground coordinates, integrates, and
+verifies. See [usage notes](docs/usage.md#delegation-mode).
 
 ## When To Use
 

package/agent-commands.ts

@@ -10,6 +10,7 @@ import { existsSync, lstatSync, readFileSync, readdirSync, statSync } from "node
 import { isAbsolute, resolve } from "node:path";
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { presentCatalog, presentCatalogEntry, type LaunchEnricher, type OperationView } from "./agent-inspection.ts";
+import { createCatalogComponent } from "./catalog-ui.ts";
 import {
     CATALOG_SCHEMA_VERSION,
     DiagnosticCodes,
@@ -80,6 +81,7 @@ export interface AgentCommandUi {
     editor(title: string, prefill?: string): Promise<string | undefined>;
     notify(message: string, type?: "info" | "warning" | "error"): void;
     setWidget?(key: string, content: string[] | undefined): void;
+    custom?<T>(factory: (tui: { requestRender(): void }, theme: { fg(color: string, text: string): string }, keybindings: unknown, done: (value: T) => void) => unknown, options?: { overlay: boolean }): Promise<T>;
 }
 
 export interface AgentCommandHost {
@@ -157,8 +159,8 @@ export async function executeAgentsCommand(args: string, host: AgentCommandHost,
     }
     const command = parsed.positionals[0]!;
     const loc = location(host, deps);
-    if (command === "list") return finish(host, await runList(parsed, loc, deps));
-    if (command === "show" || command === "inspect") return finish(host, await runShow(command, parsed, host, loc, deps));
+    if (command === "list") return finishInspection(host, await runList(parsed, loc, deps));
+    if (command === "show" || command === "inspect") return finishInspection(host, await runShow(command, parsed, host, loc, deps));
     if (command === "reload") return finish(host, await runReload(parsed, loc, deps));
     if (command === "create") return finish(host, await runCreate(parsed, host, loc, deps));
     if (command === "import-codex") return finish(host, await runImport(parsed, host, loc, deps));
@@ -232,6 +234,10 @@ async function runShow(
         if (!host.hasUI) {
             return clarification(command, `${command} needs an id. UI is unavailable, so none was selected. Run /agents list and pass the id. Nothing was written.`);
         }
+        if (host.mode === "tui" && host.ui.custom) {
+            const listed = presentCatalog(readCatalog(loc), deps.enrich);
+            return { ...result("ok", command, false, listed.text), diagnostics: listed.diagnostics, data: listed };
+        }
         const ids = listCatalog(readCatalog(loc)).map((entry) => entry.id);
         if (ids.length === 0) return result("error", command, false, "The catalog has no definitions to inspect.");
         const selected = await host.ui.select("Inspect a role or agent", ids);
@@ -696,14 +702,27 @@ function finish(host: AgentCommandHost, commandResult: AgentCommandResult): Agen
     } catch {
         /* Notification is not a write. */
     }
-    try {
-        host.ui.setWidget?.("agents-catalog", commandResult.message.split("\n").slice(0, 40));
-    } catch {
-        /* Widget rendering is TUI-only. */
-    }
     return commandResult;
 }
 
+async function finishInspection(host: AgentCommandHost, commandResult: AgentCommandResult): Promise<AgentCommandResult> {
+    if (commandResult.ok && host.mode === "tui" && host.hasUI && host.ui.custom) {
+        const catalog = commandResult.data && typeof commandResult.data === "object" && "entries" in commandResult.data
+            ? commandResult.data as ReturnType<typeof presentCatalog> : undefined;
+        const view = catalog ? undefined : commandResult.data as OperationView;
+        const entries = catalog ?? { entries: [view], diagnostics: commandResult.diagnostics, revision: "", text: "" };
+        try {
+            host.ui.setWidget?.("agents-catalog", undefined);
+            await host.ui.custom<void>((tui, theme, _keys, done) =>
+                createCatalogComponent(entries, theme, () => tui.requestRender(), () => done(), view?.id), { overlay: true });
+            return commandResult;
+        } catch {
+            // A non-interactive host may expose custom() without supporting overlays.
+        }
+    }
+    return finish(host, commandResult);
+}
+
 function tokenize(input: string): string[] {
     const tokens: string[] = [];
     for (const match of input.matchAll(/"([^"]*)"|'([^']*)'|(\S+)/g)) tokens.push(match[1] ?? match[2] ?? match[3] ?? "");

package/agent-inspection.ts

@@ -207,7 +207,10 @@ export function presentCatalog(snapshot: CatalogSnapshot, enrich?: LaunchEnriche
         `Catalog revision ${snapshot.digest}.`,
         "Definition validity is not launchability. Model availability is decided only by the injected resolver.",
         ...snapshot.diagnostics.map((diagnostic) => formatDiagnostic(diagnostic)),
-        ...entries.map((entry) => entry.text.split("\n")[0] ?? entry.id),
+        ...entries.flatMap((entry) => [
+            entry.text.split("\n")[0] ?? entry.id,
+            `  description: ${JSON.stringify(entry.identity.description ?? "")}`,
+        ]),
     ];
     return { revision: snapshot.digest, entries, diagnostics: [...snapshot.diagnostics], text: lines.join("\n") };
 }

package/batch.mjs

@@ -10,6 +10,7 @@
 import { BUILTIN_TOOLS } from "./extensions.mjs";
 import { SAFE_CLEAN_TOOLS } from "./config.ts";
 import { assertThinkingLevel } from "./thinking.ts";
+import { assertTimingParams } from "./timing.ts";
 
 const VALID_CAPACITY_MODES = new Set(["reject", "launch-available"]);
 
@@ -35,6 +36,11 @@ export function mergeJobOptions(shared, job) {
         git_clone_workspace: job.git_clone_workspace ?? shared?.git_clone_workspace,
         approve: job.approve ?? shared?.approve,
         allow_nested: job.allow_nested ?? shared?.allow_nested,
+        // Harness timing; an explicit null means "not set", so it falls through to shared.
+        deadline_minutes: job.deadline_minutes ?? shared?.deadline_minutes,
+        grace_minutes: job.grace_minutes ?? shared?.grace_minutes,
+        max_minutes: job.max_minutes ?? shared?.max_minutes,
+        stuck_minutes: job.stuck_minutes ?? shared?.stuck_minutes,
         // A per-job agent or role replaces the shared selector pair. Mixing
         // shared.agent with job.role would invent an ambiguous run.
         ...catalogSelector(shared, job),
@@ -97,6 +103,7 @@ export function validateBatchPlan({ shared, jobs, onCapacity, config }) {
 
         const merged = mergeJobOptions(shared, job);
         assertThinkingLevel(merged.thinking, `job ${i + 1} thinking`);
+        assertTimingParams(merged, `job ${i + 1} `);
         if (merged.clean === true) {
             // Validate the effective tool allowlist, which resolves in this order:
             // per-job tools → shared tools → config.defaultTools → clean-safe built-ins.

package/callback-fields.ts

@@ -10,6 +10,7 @@ import type { CallbackBatchEvent, UrgentCallbackEvent } from "./shared-callback-
 import { activeFailures, pendingAttentionNote, pendingAttentionRows, requiresAction, terminalFailureParts,
     type FailureState } from "./shared-failure-observations.ts";
 import type { RunMeta } from "./registry.ts";
+import { describeTiming } from "./timing.ts";
 
 export function runLabel(meta: Pick<RunMeta, "id" | "name">): string {
     return meta.name ? `${meta.name} (${meta.id})` : meta.id;
@@ -43,11 +44,13 @@ function observationStatus(state: FailureState): string | undefined {
 export function completionCallbackFields(meta: RunMeta, state: FailureState, incidents: readonly string[] = []): CompletionFields {
     const status = observationStatus(state);
     const { failureRows, incidentCount, notes } = terminalFields(state, incidents);
+    // Harness timing reason (deadline / ceiling / stuck) is a lifecycle fact, shown next to the status.
+    const timing = describeTiming({ ...meta, status: meta.status });
     return {
         source: "subagent",
         id: meta.id,
         label: runLabel(meta),
-        status: status ? `${meta.status}; ${status}` : meta.status,
+        status: [meta.status, timing?.short, status].filter(Boolean).join("; "),
         detailTool: "subagent_result",
         outcome: meta.status,
         failureRows,

package/catalog-ui.ts

@@ -0,0 +1,167 @@
+import { matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import type { OperationField, OperationList, OperationView } from "./agent-inspection.ts";
+
+type Theme = { fg(color: string, text: string): string };
+
+function stateLabel(entry: OperationView): string {
+    if (entry.launchable === false) return "blocked";
+    if (entry.launchable === true) return "ready";
+    return "unresolved";
+}
+
+function fieldLine(label: string, field: OperationField): string {
+    return `${label.padEnd(8)} ${field.value ?? "(unset)"}  ${field.source === "role-default" ? "inherited" : field.source === "agent-override" ? "override" : "absent"}`;
+}
+
+function modelLabel(entry: OperationView): string {
+    return entry.actualModel ?? entry.requestedModel ?? entry.fields?.model.value ?? "not resolved";
+}
+
+function cell(value: string, width: number): string {
+    const clipped = truncateToWidth(value.replace(/[\r\n\t]+/g, " "), width);
+    return clipped + " ".repeat(Math.max(0, width - visibleWidth(clipped)));
+}
+
+export function catalogColumns(entry: OperationView | null, width: number): string {
+    const available = Math.max(1, width - 2);
+    const sourceWidth = available >= 70 ? 11 : 0;
+    const stateWidth = available >= 48 ? 10 : 0;
+    const gaps = (sourceWidth ? 2 : 0) + (stateWidth ? 2 : 0) + 2;
+    const modelWidth = Math.min(Math.max(1, available - gaps - 1), Math.min(28, Math.max(20, Math.floor(available * 0.3))));
+    const nameWidth = Math.max(1, available - modelWidth - sourceWidth - stateWidth - gaps);
+    const name = entry ? entry.identity.name || entry.id : "NAME";
+    const model = entry ? modelLabel(entry) : "MODEL";
+    const source = entry ? entry.identity.scope ?? "unknown" : "SOURCE";
+    const status = entry ? stateLabel(entry) : "STATE";
+    return [cell(name, nameWidth), cell(model, modelWidth), ...(sourceWidth ? [cell(source, sourceWidth)] : []), ...(stateWidth ? [cell(status, stateWidth)] : [])].join("  ").trimEnd();
+}
+
+function wrapLine(text: string, width: number): string[] {
+    const rows: string[] = [];
+    let row = "";
+    for (const { segment } of new Intl.Segmenter(undefined, { granularity: "grapheme" }).segment(text)) {
+        if (row && visibleWidth(row + segment) > width) {
+            rows.push(row);
+            row = "";
+        }
+        row += segment;
+    }
+    rows.push(row);
+    return rows;
+}
+
+export function catalogDetailLines(entry: OperationView): string[] {
+    const lines = [
+        `${entry.identity.name || entry.id}  ·  ${entry.identity.kind ?? "unknown"}`,
+        entry.id,
+        "",
+        `Status    ${stateLabel(entry)}  ·  ${entry.launchabilityReason}`,
+        `Source    ${entry.identity.scope ?? "unknown"}  ·  ${entry.identity.path ?? "(none)"}`,
+        ...(entry.identity.description ? [`About     ${entry.identity.description}`] : []),
+        ...(entry.role ? [`Base role ${entry.role.id ?? "(missing)"}${entry.role.found ? "" : "  ·  missing"}`] : []),
+        ...(entry.instructionMode ? [`Instructions ${entry.instructionMode}`] : []),
+        "",
+        "Configuration",
+        ...(entry.fields ? [
+            fieldLine("Model", entry.fields.model),
+            fieldLine("Effort", entry.fields.effort),
+            fieldLine("Tier", entry.fields.tier),
+        ] : []),
+        `Actual   ${entry.actualModel ?? "not resolved"}${entry.actualEffort ? `  ·  ${entry.actualEffort}` : ""}`,
+        ...(entry.validation.length ? ["", "Diagnostics", ...entry.validation.map((item) => `${item.blocking ? "!" : "·"} ${item.message}`)] : []),
+        ...(entry.shadowed.length ? ["", "Shadowed sources", ...entry.shadowed.map((source) => `${source.scope}  ${source.path}`)] : []),
+        ...(entry.restrictions.length ? ["", "Execution restrictions", ...entry.restrictions.map((item) => `${item.honored ? "honored" : "not honored"}  ${item.name}`)] : []),
+        "",
+        "Effective prompt",
+        "Press p to read the complete resolved instructions.",
+    ];
+    return lines;
+}
+
+export function createCatalogComponent(
+    catalog: OperationList,
+    theme: Theme,
+    requestRender: () => void,
+    close: () => void,
+    initialId?: string,
+) {
+    let selectedId = initialId ?? catalog.entries[0]?.id;
+    let mode: "list" | "detail" | "prompt" = initialId ? "detail" : "list";
+    let query = "";
+    let scroll = 0;
+    const filtered = () => catalog.entries.filter((entry) =>
+        [entry.id, entry.identity.name, entry.identity.description, entry.role?.id]
+            .some((value) => value?.toLowerCase().includes(query.toLowerCase())));
+    const selected = () => filtered().find((entry) => entry.id === selectedId);
+    const detailRows = (entry: OperationView, width: number) => (mode === "prompt"
+        ? [`${entry.identity.name || entry.id}  ·  effective instructions`, "", ...(entry.instructions?.split("\n") ?? ["(none)"])]
+        : catalogDetailLines(entry))
+        .flatMap((text) => text ? wrapLine(text, Math.max(1, width - 2)) : [""]);
+    let lastDetailWidth = 80;
+
+    return {
+        render(width: number): string[] {
+            const safeWidth = Math.max(1, width);
+            lastDetailWidth = safeWidth;
+            const line = (text: string) => truncateToWidth(text, safeWidth);
+            const rows = filtered();
+            const current = selected();
+            const detailLines = current ? detailRows(current, safeWidth) : [];
+            const selectedIndex = rows.findIndex((entry) => entry.id === selectedId);
+            const start = Math.max(0, Math.min(selectedIndex - 6, rows.length - 14));
+            const lines = mode !== "list" && current ? [
+                theme.fg("accent", mode === "prompt" ? "Agents / prompt" : "Agents / inspect"),
+                theme.fg("dim", mode === "prompt" ? "← details  ·  ↑↓ scroll  ·  Esc close" : "p prompt  ·  ← list  ·  ↑↓ scroll  ·  Esc close"),
+                "",
+                ...detailLines.slice(scroll, scroll + 22).map((text, i) =>
+                    i === 0 && scroll === 0 ? theme.fg("accent", text) : text),
+                "",
+                theme.fg("dim", `Showing ${scroll + 1}-${Math.min(scroll + 22, detailLines.length)} of ${detailLines.length} lines`),
+            ] : [
+                theme.fg("accent", `Agents  ·  ${catalog.entries.length} definitions`),
+                theme.fg("dim", "Type to filter  ·  ↑↓ select  ·  Enter inspect  ·  Esc close"),
+                `Search  ${query || "(all roles and agents)"}`,
+                "",
+                theme.fg("dim", `  ${catalogColumns(null, safeWidth)}`),
+                ...rows.slice(start, start + 14).map((entry) => {
+                    const active = selectedId === entry.id;
+                    const marker = active ? "›" : " ";
+                    const text = `${marker} ${catalogColumns(entry, safeWidth)}`;
+                    return active ? theme.fg("accent", text) : text;
+                }),
+                ...(rows.length === 0 ? ["  No matching definitions"] : []),
+                ...(rows.length > 14 ? [theme.fg("dim", `  ${start + 1}-${Math.min(start + 14, rows.length)} of ${rows.length}`)] : []),
+                ...catalog.diagnostics.slice(0, 2).map((diagnostic) => theme.fg("warning", `! ${diagnostic.message}`)),
+                ...(catalog.diagnostics.length > 2 ? [theme.fg("warning", `! ${catalog.diagnostics.length - 2} more catalog diagnostics`)] : []),
+            ];
+            return lines.map(line);
+        },
+        handleInput(data: string): void {
+            const rows = filtered();
+            if (matchesKey(data, "escape") || matchesKey(data, "left")) {
+                if (mode === "prompt") { mode = "detail"; scroll = 0; }
+                else if (mode === "detail") { mode = "list"; scroll = 0; }
+                else if (query) { query = ""; selectedId = catalog.entries[0]?.id; }
+                else { close(); return; }
+            } else if (matchesKey(data, "up") || matchesKey(data, "down")) {
+                const delta = matchesKey(data, "down") ? 1 : -1;
+                if (mode !== "list" && selected()) scroll = Math.max(0, Math.min(detailRows(selected()!, lastDetailWidth).length - 1, scroll + delta));
+                else if (rows.length) selectedId = rows[Math.max(0, Math.min(rows.length - 1, rows.findIndex((entry) => entry.id === selectedId) + delta))]?.id;
+            } else if (matchesKey(data, "enter") && mode === "list" && selected()) {
+                mode = "detail";
+                scroll = 0;
+            } else if ((data === "p" || data === "P") && mode === "detail" && selected()) {
+                mode = "prompt";
+                scroll = 0;
+            } else if (mode === "list" && matchesKey(data, "backspace")) {
+                query = query.slice(0, -1);
+                selectedId = filtered()[0]?.id;
+            } else if (mode === "list" && data.length === 1 && !/\p{C}/u.test(data)) {
+                query += data;
+                selectedId = filtered()[0]?.id;
+            }
+            requestRender();
+        },
+        invalidate() {},
+    };
+}

package/child-incidents.ts

@@ -17,19 +17,33 @@ import { DISPOSITION_TOOL, INTENT_ID_PATTERN, MAX_EXPECTED_EXIT_CODES, describeO
 
 const { createBashToolDefinition } = PiCodingAgent;
 
+// Each intent field also admits `null`, which means "not declared" (withoutAbsentIntent). Models send
+// optional fields as explicit null; accepting it in the schema means Pi hands execute the same raw
+// arguments the process log and session record keep, on every Pi version (0.82 rejected a null
+// before execute, 0.87 silently drops it), so the child and the parent's replay read one input.
+// `anyOf` rather than a `type` array: Pi 0.82's TypeBox compiler crashes on `["array", "null"]` + `items`.
+const nullable = (schema: Record<string, unknown>) => ({ anyOf: [schema, { type: "null" }] });
 const intentProperties = {
-    operationId: { type: "string", pattern: INTENT_ID_PATTERN,
+    operationId: { ...nullable({ type: "string", pattern: INTENT_ID_PATTERN }),
         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: { type: "string", pattern: INTENT_ID_PATTERN,
+    attemptId: { ...nullable({ type: "string", pattern: INTENT_ID_PATTERN }),
         description: "Optional unique id for this execution, for use as evidence in failure_disposition." },
-    expectedExitCodes: { type: "array", items: { type: "integer", minimum: 1, maximum: 255 }, minItems: 1, maxItems: MAX_EXPECTED_EXIT_CODES,
+    expectedExitCodes: { ...nullable({ type: "array", items: { type: "integer", minimum: 1, 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." },
 };
 
+/**
+ * Every tool call the child session has recorded, in append order, across all branches (#325).
+ * The parent scans the child's whole process log, not one session branch, so the child reads the
+ * whole session too: after a branch switch or compaction the two views still agree. Session
+ * entries are a superset of the log's tool starts (an assistant message is recorded before its
+ * tools run), so a reuse the parent sees is always one the child also saw and refused.
+ */
 function sessionToolCalls(ctx: ExtensionContext | undefined): Array<{ type: string; [key: string]: unknown }> {
-    const branch = (ctx?.sessionManager?.getBranch?.() ?? []) as any[];
+    const manager = ctx?.sessionManager;
+    const branch = (manager?.getEntries?.() ?? manager?.getBranch?.() ?? []) as any[];
     const rows: Array<{ type: string; [key: string]: unknown }> = [];
     let pendingEnds: any[] = [];
     const flush = () => { rows.push(...pendingEnds); pendingEnds = []; };
@@ -52,7 +66,7 @@ function sessionToolCalls(ctx: ExtensionContext | undefined): Array<{ type: stri
     return rows;
 }
 
-/** Rebuild the child's view of its own incidents from the durable session branch. */
+/** Rebuild the child's view of its own incidents from the durable session record (every branch). */
 export function childIncidentView(ctx: ExtensionContext | undefined, cwd: string): { model: IncidentModel; state: FailureState } {
     let state = emptyFailureState();
     let at = 0;

package/child-steer.ts

@@ -0,0 +1,102 @@
+/**
+ * Child-side harness control: deliver a parent steer into the running child session.
+ *
+ * Loaded into every subagent child (`--extension`) by the parent. It registers no
+ * tools and performs no command I/O. The parent writes a request file (path in
+ * PI_SUBAGENT_STEER_FILE) under the run directory; this extension polls it and
+ * hands the text to Pi's own steering queue (`sendUserMessage` with
+ * `deliverAs: "steer"`), which the agent loop reads after the current tool call
+ * finishes. When the steer actually enters the conversation (its user
+ * `message_end`), it writes a receipt file next to the request, so the parent
+ * can start the grace period from real delivery rather than from the moment the
+ * steer was queued behind a long tool call. A file, not a log line: in print
+ * mode an extension's stdout writes are not flushed to the log until exit.
+ * This extension runs in the trusted Pi process; the child's confined tools
+ * cannot write the run directory, so they cannot forge a receipt.
+ *
+ * Each request id is delivered at most once per child process, and only while
+ * the agent is working: an idle print-mode child is about to exit, and a new
+ * prompt there would start work instead of steering it.
+ */
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+
+export const STEER_FILE_ENV = "PI_SUBAGENT_STEER_FILE";
+const POLL_MS = 2_000;
+
+type SteerApi = {
+    on(event: string, handler: (event: any, ctx: { isIdle?: () => boolean }) => unknown): void;
+    sendUserMessage(content: string, options?: { deliverAs?: "steer" | "followUp" }): void;
+};
+
+/** Where the child records that a steer entered its conversation. */
+export function steerReceiptPath(requestPath: string): string {
+    return `${requestPath}.delivered`;
+}
+
+export function readSteerReceipt(requestPath: string): { id: string; at: number } | undefined {
+    try {
+        const value = JSON.parse(readFileSync(steerReceiptPath(requestPath), "utf8")) as { id?: unknown; at?: unknown };
+        return typeof value?.id === "string" && typeof value.at === "number" && Number.isFinite(value.at) ? { id: value.id, at: value.at } : undefined;
+    } catch {
+        return undefined;
+    }
+}
+
+export function readSteerRequest(path: string): { id: string; text: string } | undefined {
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8")) as { id?: unknown; text?: unknown };
+        return typeof value?.id === "string" && typeof value.text === "string" && value.text.trim() !== ""
+            ? { id: value.id, text: value.text }
+            : undefined;
+    } catch {
+        return undefined;
+    }
+}
+
+export default function childSteer(pi: SteerApi): void {
+    const path = process.env[STEER_FILE_ENV];
+    if (!path) return;
+    const delivered = new Set<string>();
+    /** Queued steer text → request id, until the steer shows up as a user message. */
+    const queued = new Map<string, string>();
+    let timer: ReturnType<typeof setInterval> | undefined;
+    let isIdle: (() => boolean) | undefined;
+    const check = () => {
+        const request = readSteerRequest(path);
+        if (!request || delivered.has(request.id)) return;
+        try { if (isIdle?.() === true) return; } catch { return; }
+        delivered.add(request.id);
+        try {
+            queued.set(request.text, request.id);
+            pi.sendUserMessage(request.text, { deliverAs: "steer" });
+        } catch {
+            queued.delete(request.text);
+            delivered.delete(request.id);
+        }
+    };
+    pi.on("message_end", (event) => {
+        const message = event?.message;
+        if (message?.role !== "user" || queued.size === 0) return;
+        const content = message.content;
+        const text = typeof content === "string" ? content
+            : Array.isArray(content) ? content.filter((part: any) => part?.type === "text").map((part: any) => part.text).join("\n") : "";
+        const id = queued.get(text);
+        if (id === undefined) return;
+        queued.delete(text);
+        try {
+            const receipt = steerReceiptPath(path);
+            writeFileSync(`${receipt}.tmp`, JSON.stringify({ id, at: Date.now() }));
+            renameSync(`${receipt}.tmp`, receipt);
+        } catch { /* the parent falls back to grace from the request */ }
+    });
+    pi.on("session_start", (_event, ctx) => {
+        isIdle = typeof ctx?.isIdle === "function" ? () => ctx.isIdle!() : undefined;
+        if (timer) clearInterval(timer);
+        timer = setInterval(check, POLL_MS);
+        timer.unref?.();
+    });
+    pi.on("session_shutdown", () => {
+        if (timer) clearInterval(timer);
+        timer = undefined;
+    });
+}

package/cleanup.ts

@@ -12,8 +12,11 @@ import {
     baseDir,
     listMetas,
     ownedByThisParent,
+    orphanedTaskRuntimeProvenance,
     readMeta,
     removeMetaArtifacts,
+    removeRunDirectory,
+    removeTaskRuntimeProvenance,
     runDir,
     sessionsDir,
     type RunMeta,
@@ -166,6 +169,17 @@ function safeStatMtime(path: string): number | undefined {
     }
 }
 
+/** A metadata-less run directory, with its provenance record (#325). */
+function removeRun(id: string, errors: string[]): boolean {
+    try {
+        removeRunDirectory(id);
+        return true;
+    } catch (err) {
+        errors.push(`${runDir(id)}: ${err instanceof Error ? err.message : String(err)}`);
+        return false;
+    }
+}
+
 function removePath(path: string, errors: string[]): boolean {
     try {
         rmSync(path, { recursive: true, force: true });
@@ -197,8 +211,10 @@ function cleanRunDirs(cutoff: number, errors: string[]): number {
         }
 
         const mtimeMs = safeStatMtime(dir);
-        if (mtimeMs !== undefined && mtimeMs < cutoff && removePath(dir, errors)) removed += 1;
+        if (mtimeMs !== undefined && mtimeMs < cutoff && removeRun(id, errors)) removed += 1;
     }
+    // Provenance whose run is already gone (#325).
+    for (const id of orphanedTaskRuntimeProvenance()) removeTaskRuntimeProvenance(id);
     return removed;
 }
 
@@ -382,7 +398,7 @@ export function enforceRegistrySizeCapOnce(options: SizeCapOptions = {}): SizeCa
     const removed: string[] = [];
     for (const id of plan.remove) {
         const meta = readMeta(id);
-        if (meta ? removeMetaArtifacts(meta) : removePath(runDir(id), errors)) removed.push(id);
+        if (meta ? removeMetaArtifacts(meta) : removeRun(id, errors)) removed.push(id);
         else if (meta) errors.push(`${runDir(id)}: could not remove run artifacts`);
     }
 

package/config.json

@@ -2,6 +2,7 @@
   "defaultModel": null,
   "defaultTools": "read, bash, edit, write, web_search, web_fetch",
   "maxConcurrent": 4,
+  "delegationMode": "adaptive",
 
   "toolExtensions": {
     "web_search": "npm:@juicesharp/rpiv-web-tools",

package/config.ts

@@ -13,8 +13,12 @@ import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { SELF_SPEC } from "./extensions.ts";
+import type { DelegationMode } from "./delegation.ts";
+import type { TimingSettings } from "./timing.ts";
 
-export interface SubagentConfig {
+export interface SubagentConfig extends TimingSettings {
+    /** Foreground delegation policy; /subagents mode overrides this for the current session. */
+    delegationMode?: DelegationMode | null;
     defaultModel?: string | null;
     defaultTools?: string | null;
     /** Max subagents allowed to run at once. */

package/delegation.ts

@@ -0,0 +1,22 @@
+export type DelegationMode = "manual" | "adaptive" | "coordinator";
+
+export const DELEGATION_MODE_REQUEST = "pi-better-subagents:delegation-mode-request";
+
+export function isDelegationMode(value: unknown): value is DelegationMode {
+    return value === "manual" || value === "adaptive" || value === "coordinator";
+}
+
+export function normalizeDelegationMode(value: unknown): DelegationMode {
+    return isDelegationMode(value) ? value : "adaptive";
+}
+
+export function delegationPrompt(mode: DelegationMode): string {
+    switch (mode) {
+        case "manual":
+            return "Delegation mode: manual. Do not proactively delegate work. Use subagents only when the user explicitly asks for delegation or an active workflow explicitly requires it. A structured plan or plan mode does not override this restriction; perform planned work in the foreground unless explicitly required otherwise.";
+        case "coordinator":
+            return "Delegation mode: coordinator. The foreground coordinates, integrates, and verifies. Call agents_catalog to discover current available roles and inspect their descriptions. Delegate every nontrivial task covered by an available role according to its current description; do not assume bundled roles are unchanged. Keep orchestration, cross-role decisions, unowned or ambiguous work, integration, and final verification in the foreground. Inspect results and failures before concluding; do not poll for running children.";
+        case "adaptive":
+            return "Delegation mode: adaptive. Delegate bounded, substantial independent work when a suitable subagent is available and useful; continue unblocked foreground work. Keep small, tightly coupled, or interactive work in the foreground. Inspect and integrate delegated results before final verification; do not poll.";
+    }
+}

package/docs/agent-catalog-operations.md

@@ -6,6 +6,8 @@ Commands, the read-only discovery tool, and the Codex importer for `pi-agent/v1`
 
 `/agents` is one Pi command. Dialogs use `ctx.ui.select`, `confirm`, `input`, and `editor`. `ctx.hasUI` is false in print and JSON mode. When a choice or confirmation is required there, the command returns `clarification-needed` and writes nothing.
 
+In an interactive TUI, `/agents list` and `/agents show` open a focused catalog view instead of leaving the listing in a persistent widget. Rows align name, effective model, source, and launch state; narrow terminals retain name and model. The model is the resolved actual model when available, otherwise the requested or inherited preference, or `not resolved`. Type to filter by id, name, description, or base role; use Up/Down and Enter to inspect. The detail view puts launchability and its reason first, then source, inherited/overridden settings, and diagnostics. Press `p` in detail to read the complete effective instructions (role plus agent in add mode, agent text in replace mode); this is not the task-specific launch prompt. Up/Down scrolls detail or prompt; Left or Escape returns to detail, then list, clears the filter, then closes. `/agents show <id>` opens that definition directly. Print/JSON callers still receive the complete text and structured result.
+
 | Invocation | Effect |
 | --- | --- |
 | `/agents list` | Fresh read of project, personal, and bundled definitions. One bad file does not hide the others. |

package/docs/agent-catalog.md

@@ -105,6 +105,15 @@ Model availability, same-tier fallback, and nearest-effort adjustment are not de
 | `role.reviewer` | Reviewer | `openai/gpt-6-astra` | medium | frontier |
 | `role.architect` | Architect | `openai/gpt-6-astra` | high | frontier |
 
+Bundled descriptions are routing boundaries for coordinator mode. Researcher owns
+external and documentary evidence; Explorer maps repository code paths; Product
+Manager owns user-visible requirements; Architect owns technical boundaries;
+Developer owns implementation and focused tests; Reviewer owns independent change
+review. Each role's instruction body names excluded work and the neighboring role
+that owns it. Project and personal definitions may replace these bundled roles, so
+coordinators inspect the current effective descriptions rather than assuming this
+table is unchanged.
+
 The product table's short model names are the model ids. The provider prefix is `openai`, matching explicit `provider/model` ids already used at launch. No cross-provider substitute is implied. Tier candidate lists are not invented here.
 
 ## Parser