pi-better-subagents 0.4.1 → 0.5.0

package/incident-model.ts

@@ -0,0 +1,320 @@
+/**
+ * Pure incident model shared by the parent's log scanner (failures.ts) and the child's
+ * `failure_disposition` tool (child-incidents.ts). Both fold the same structured tool
+ * records in the same order, so a disposition the child accepts is re-validated
+ * identically by the parent before it is journaled (#315).
+ *
+ * Nothing here reads prose. Operation identity is either an explicit caller-declared
+ * `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, REJECTED_INTENT_CATEGORY,
+    type FailureEvent, type FailureState, type IncidentDisposition } from "./shared-failure-observations.ts";
+
+export const DISPOSITION_TOOL = "failure_disposition";
+/** Caller-chosen identifiers: short, printable, no whitespace. */
+export const INTENT_ID_PATTERN = "^[A-Za-z0-9][A-Za-z0-9._:/-]{0,63}$";
+const INTENT_ID = new RegExp(INTENT_ID_PATTERN);
+export const MAX_EXPECTED_EXIT_CODES = 16;
+
+export interface CommandIntent {
+    /** Stable across caller-declared modified retries of one logical operation. */
+    operationId?: string;
+    /** Names one concrete execution; evidence identity, never an operation match. */
+    attemptId?: string;
+    /** Non-zero exit codes declared intentional before execution. */
+    expectedExitCodes?: number[];
+}
+
+/** Validate structured intent fields. Absent fields are fine; malformed ones are an error. */
+export function readCommandIntent(args: unknown): { intent: CommandIntent; error?: string } {
+    const input = (args && typeof args === "object" ? args : {}) as Record<string, unknown>;
+    const intent: CommandIntent = {};
+    for (const key of ["operationId", "attemptId"] as const) {
+        const value = input[key];
+        if (value === undefined) continue;
+        if (typeof value !== "string" || !INTENT_ID.test(value)) {
+            return { intent: {}, error: `${key} must match ${INTENT_ID_PATTERN}` };
+        }
+        intent[key] = value;
+    }
+    const codes = input.expectedExitCodes;
+    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: `expectedExitCodes must be 1-${MAX_EXPECTED_EXIT_CODES} distinct integers from 1 to 255` };
+        }
+        intent.expectedExitCodes = [...codes] as number[];
+    }
+    return { intent };
+}
+
+function stable(value: unknown): unknown {
+    if (Array.isArray(value)) return value.map(stable);
+    if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => [k, stable(v)]));
+    return value;
+}
+/** Exact identity: tool name, full arguments, and working directory. */
+export function toolOperation(name: string, args: unknown, cwd: string): string {
+    return failureIdentity("tool", name, stable(args ?? {}), cwd);
+}
+/** Declared identity when an operationId is present, otherwise the exact rule. attemptId never affects identity. */
+export function attemptOperation(name: string, args: unknown, cwd: string, intent: CommandIntent): string {
+    if (intent.operationId) return failureIdentity("operation", name, intent.operationId, cwd);
+    if (args && typeof args === "object" && !Array.isArray(args) && "attemptId" in args) {
+        const { attemptId: _attemptId, ...rest } = args as Record<string, unknown>;
+        return toolOperation(name, rest, cwd);
+    }
+    return toolOperation(name, args, cwd);
+}
+
+export function evidenceText(value: unknown): string | undefined {
+    if (value == null) return undefined;
+    const raw = typeof value === "string" ? value : JSON.stringify(value);
+    return raw?.replace(/[\x00-\x1f\x7f]/g, " ").slice(0, 300);
+}
+function resultError(result: any): string | undefined {
+    if (result?.isError === true || (typeof result?.exitCode === "number" && result.exitCode !== 0)) {
+        return evidenceText(result?.content?.find?.((x: any) => x?.type === "text")?.text ?? result?.stderr ?? result?.error ?? result);
+    }
+    return undefined;
+}
+function time(row: any): number | undefined {
+    return typeof row.at === "number" && Number.isFinite(row.at) ? row.at :
+        typeof row.message?.timestamp === "number" && Number.isFinite(row.message.timestamp) ? row.message.timestamp : undefined;
+}
+
+interface Attempt {
+    toolCallId: string;
+    toolName: string;
+    operation: string;
+    intent: CommandIntent;
+    startSequence: number;
+    /** The confined intent bash refused this attempt before running anything. */
+    rejectedIntent?: string;
+}
+interface Finished extends Attempt {
+    ok: boolean;
+    endSequence: number;
+    evidence: string;
+    incident?: string;
+}
+export interface IncidentModel {
+    /** Honour operationId / attemptId / expectedExitCodes / dispositions (confined runtime only). */
+    structuredIntent: boolean;
+    sequence: number;
+    open: Map<string, Attempt>;
+    finished: Map<string, Finished>;
+    /** attemptId → toolCallId of the accepted declaration. */
+    attemptIds: Map<string, string>;
+    /** Every attemptId any bash start has named, accepted or rejected. */
+    namedAttempts: Set<string>;
+    /** operationId → operation identity. */
+    operationIds: Map<string, string>;
+    /** Current unresolved incident per operation, for exact retry recovery. */
+    failed: Map<string, { id: string; sequence: number }>;
+    /** Incident → last failure sequence, for ordering evidence. */
+    incidentSequence: Map<string, number>;
+    /** Disposition requests resolved at their start position (parent) or execute time (child). */
+    pendingDispositions: Map<string, { event?: FailureEvent; error?: string }>;
+}
+/**
+ * `structuredIntent` is true only for runs whose tools are the trusted task runtime's
+ * (intent bash + failure_disposition). Anywhere else the intent fields and disposition
+ * requests are ignored and the exact-retry identity rule applies.
+ */
+export function newIncidentModel(structuredIntent = false): IncidentModel {
+    return { structuredIntent, sequence: 0, open: new Map(), finished: new Map(), attemptIds: new Map(), namedAttempts: new Set(), operationIds: new Map(),
+        failed: new Map(), incidentSequence: new Map(), pendingDispositions: new Map() };
+}
+export interface IncidentSink {
+    /** Reduce/journal ordinary observations; returns the resulting state. */
+    observe(events: FailureEvent[]): FailureState;
+    /** Journal an already validated disposition. */
+    dispose(event: FailureEvent): void;
+    /** Current state for validation. */
+    state(): FailureState;
+}
+
+export interface DispositionRequest {
+    disposition: IncidentDisposition;
+    targets: string[];
+    reason: string;
+    evidence?: string;
+}
+export function readDispositionRequest(args: unknown): { request?: DispositionRequest; error?: string } {
+    const input = (args && typeof args === "object" ? args : {}) as Record<string, unknown>;
+    const disposition = input.disposition;
+    if (typeof disposition !== "string" || !INCIDENT_DISPOSITIONS.includes(disposition as IncidentDisposition)) {
+        return { error: `disposition must be one of ${INCIDENT_DISPOSITIONS.join(", ")}` };
+    }
+    const targets = input.targets;
+    if (!Array.isArray(targets) || targets.length === 0 || targets.length > 20 || !targets.every((x) => typeof x === "string" && x.length > 0 && x.length <= 200)) {
+        return { error: "targets must name 1-20 incidents, attempt ids, or operation ids" };
+    }
+    if (typeof input.reason !== "string" || !input.reason.trim()) return { error: "reason is required" };
+    if (input.evidence !== undefined && (typeof input.evidence !== "string" || !input.evidence.trim())) return { error: "evidence must be an attempt id" };
+    return { request: { disposition: disposition as IncidentDisposition, targets: [...targets] as string[], reason: input.reason.trim(),
+        ...(typeof input.evidence === "string" ? { evidence: input.evidence.trim() } : {}) } };
+}
+
+function attemptRef(model: IncidentModel, ref: string): Finished | undefined {
+    const toolCallId = model.attemptIds.get(ref) ?? ref;
+    return model.finished.get(toolCallId);
+}
+function attemptLabel(attempt: Finished): string {
+    return attempt.intent.attemptId ? `attempt ${attempt.intent.attemptId}` : `tool call ${attempt.toolCallId}`;
+}
+
+/**
+ * Resolve a disposition request against the model and reduced state. Targets may be incident ids,
+ * failed attempt ids / tool call ids, or declared operation ids with a current incident. Recovery
+ * and supersession need evidence naming a successful attempt that started after the failures;
+ * recovery additionally needs the same operation. Everything else fails closed.
+ */
+export function resolveDisposition(model: IncidentModel, state: FailureState, request: DispositionRequest, requestId: string): { event?: FailureEvent; error?: string } {
+    const incidents: string[] = [];
+    for (const target of request.targets) {
+        let id: string | undefined;
+        if (findIncident(state, target) || Object.hasOwn(state.history ?? {}, target)) id = target;
+        else {
+            const attempt = attemptRef(model, target);
+            if (attempt) {
+                if (!attempt.incident) return { error: `${attemptLabel(attempt)} did not fail; it has no incident` };
+                id = attempt.incident;
+            } else if (model.operationIds.has(target)) {
+                const current = state.observations[failureIdentity(model.operationIds.get(target)!)];
+                if (!current) return { error: `Operation ${target} has no incident` };
+                id = current.id;
+            }
+        }
+        if (!id) return { error: `Unknown incident, attempt, or operation "${target}"` };
+        if (!incidents.includes(id)) incidents.push(id);
+    }
+    let evidence: string | undefined;
+    if (request.disposition === "recovered" || request.disposition === "superseded") {
+        if (!request.evidence) return { error: `A ${request.disposition} disposition requires evidence: the attempt id (or tool call id) of a successful later attempt` };
+        const proof = attemptRef(model, request.evidence);
+        if (!proof) return { error: `Unknown evidence attempt "${request.evidence}"` };
+        if (!proof.ok) return { error: `Evidence ${attemptLabel(proof)} did not succeed` };
+        for (const id of incidents) {
+            const failedAt = model.incidentSequence.get(id);
+            if (failedAt === undefined || proof.startSequence <= failedAt) {
+                return { error: `Evidence ${attemptLabel(proof)} did not start after incident ${id} failed` };
+            }
+            if (request.disposition === "recovered") {
+                const incident = findIncident(state, id);
+                if (!incident || incident.operation !== proof.operation) {
+                    return { error: `Evidence ${attemptLabel(proof)} is a different operation; use superseded for a different verification` };
+                }
+            }
+        }
+        evidence = `${attemptLabel(proof)} succeeded · ${proof.evidence}`;
+    } else if (request.evidence) {
+        const proof = attemptRef(model, request.evidence);
+        evidence = proof ? `${attemptLabel(proof)} · ${proof.evidence}` : request.evidence.slice(0, 200);
+    }
+    const event: FailureEvent = { id: `disposition:${requestId}`, operation: "incident-disposition", kind: "disposition",
+        disposition: request.disposition, incidents, reason: request.reason, ...(evidence ? { evidence } : {}) };
+    const error = validateDisposition(state, event);
+    return error ? { error } : { event };
+}
+
+/** Fold one tool execution start. Disposition requests are resolved here, at their start position. */
+export function foldToolStart(model: IncidentModel, row: any, cwd: string, sink: IncidentSink): void {
+    const toolCallId = String(row.toolCallId);
+    const toolName = String(row.toolName ?? "unknown");
+    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 });
+        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);
+    const rejectedIntent = parsed.error ?? (reused ? `attemptId ${intent.attemptId} was already used` : undefined);
+    const operation = attemptOperation(toolName, row.args, cwd, intent);
+    model.open.set(toolCallId, { toolCallId, toolName, operation, intent: rejectedIntent ? {} : intent, startSequence: seq,
+        ...(rejectedIntent ? { rejectedIntent } : {}) });
+    if (rejectedIntent) return;
+    if (intent.attemptId) model.attemptIds.set(intent.attemptId, toolCallId);
+    if (intent.operationId && !model.operationIds.has(intent.operationId)) model.operationIds.set(intent.operationId, operation);
+    if (toolName === DISPOSITION_TOOL) {
+        const parsed = readDispositionRequest(row.args);
+        model.pendingDispositions.set(toolCallId, parsed.request
+            ? resolveDisposition(model, sink.state(), parsed.request, toolCallId)
+            : { error: parsed.error });
+    }
+}
+
+/** Fold one tool execution end: failures, declared expected exits, exact retry recovery, dispositions. */
+export function foldToolEnd(model: IncidentModel, row: any, cwd: string, evidence: string, sink: IncidentSink): void {
+    const toolCallId = String(row.toolCallId);
+    const toolName = String(row.toolName ?? "unknown");
+    const seq = ++model.sequence;
+    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 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;
+    const error = row.isError === true ? evidenceText(row.result) ?? "Tool returned an error" : resultError(row.result);
+    const finished: Finished = { ...(attempt ?? { toolCallId, toolName, operation, intent, startSequence: seq }),
+        ok: !error && declaredExit === undefined, endSequence: seq, evidence };
+    model.finished.set(toolCallId, finished);
+    if (attempt?.rejectedIntent && (row.isError === true || error)) {
+        // Nothing ran: visible, but never grouped with (or escalating) the operation it named.
+        const failureId = `tool:${toolCallId}`;
+        sink.observe([{ id: failureId, operation: failureIdentity("rejected-intent", toolCallId), kind: "failure", at: time(row),
+            category: REJECTED_INTENT_CATEGORY, evidence, summary: `${toolName} not run: invalid command intent (${attempt.rejectedIntent})` }]);
+        finished.incident = failureId;
+        return;
+    }
+    if (toolName === DISPOSITION_TOOL && model.structuredIntent) {
+        const pending = model.pendingDispositions.get(toolCallId);
+        model.pendingDispositions.delete(toolCallId);
+        if (!error && pending?.event && !validateDisposition(sink.state(), pending.event)) sink.dispose(pending.event);
+        return;
+    }
+    if (declaredExit !== undefined || error) {
+        const failureId = `tool:${toolCallId}`;
+        const event: FailureEvent = declaredExit !== undefined
+            ? { id: failureId, operation, kind: "failure", at: time(row), category: "tool", expected: true, evidence,
+                summary: `${toolName} exited with declared expected code ${declaredExit}` }
+            : { id: failureId, operation, kind: "failure", at: time(row), category: "tool", evidence,
+                summary: `${toolName} failed: ${error!.slice(0, 180)}`, expected: row.expected === true || row.result?.expected === true };
+        const state = sink.observe([event]);
+        const incident = state.observations[failureIdentity(operation)]?.id ?? failureId;
+        finished.incident = incident;
+        model.incidentSequence.set(incident, seq);
+        model.failed.set(operation, { id: incident, sequence: seq });
+        return;
+    }
+    if (attempt) {
+        const failed = model.failed.get(operation);
+        if (failed && attempt.startSequence > failed.sequence) {
+            sink.observe([{ id: `recovered:${toolCallId}`, operation, kind: "recovered", at: time(row), incidents: [failed.id] }]);
+            model.failed.delete(operation);
+        }
+    }
+}
+
+/** Open incidents a child can name, for actionable rejection messages. */
+export function describeOpenTargets(model: IncidentModel, state: FailureState, limit = 10): string[] {
+    const rows: string[] = [];
+    for (const attempt of model.finished.values()) {
+        if (!attempt.incident) continue;
+        const incident = findIncident(state, attempt.incident);
+        if (!incident || incident.status !== "unresolved" || incident.category === "observation-incomplete") continue;
+        const names = [incident.id, attempt.intent.attemptId, attempt.intent.operationId].filter(Boolean).join(" / ");
+        const row = `${names} · ${incident.summary.slice(0, 120)}`;
+        if (!rows.some((x) => x.startsWith(incident.id))) rows.push(row);
+        if (rows.length >= limit) break;
+    }
+    return rows;
+}

package/index.ts

@@ -95,7 +95,8 @@ import {
 } from "./capacity.mjs";
 import { buildHealthCallbackDelivery } from "./completion.ts";
 import { cancelCallbackBatch, getCallbackBatcher } from "./shared-callback-batcher.ts";
-import { collectRunFailures, failurePath, failureSummary, formatFailureSummary, markFailureAttentionDelivered, pendingFailureAttention, prependFailureSummary } from "./failures.ts";
+import { completionCallbackFields, failureAttentionFields, healthCallbackFields } from "./callback-fields.ts";
+import { collectRunFailures, failurePath, failureSummary, markFailureAttentionDelivered, pendingFailureAttention, prependFailureSummary } from "./failures.ts";
 import { failureAttentionHandled, observeFailures } from "./shared-failure-observations.ts";
 import {
     text,
@@ -262,6 +263,17 @@ function callbackOriginFromContext(ctx: ExtensionContext): RunCallbackOrigin {
     return { cwd: ctx.cwd, sessionId };
 }
 
+/** Origin with a readable session id, or undefined when identity is unavailable. */
+function verifiedOriginFromContext(ctx: ExtensionContext | undefined): RunCallbackOrigin | undefined {
+    if (!ctx?.sessionManager || typeof ctx.cwd !== "string") return undefined;
+    try {
+        const sessionId = ctx.sessionManager.getSessionId();
+        return sessionId ? { cwd: ctx.cwd, sessionId } : undefined;
+    } catch {
+        return undefined;
+    }
+}
+
 function callbackSuppressionReason(meta: RunMeta, active: RunCallbackOrigin | undefined = activeCallbackOrigin): string | undefined {
     const origin = meta.callbackOrigin;
     if (origin) {
@@ -339,17 +351,11 @@ function enqueueCompletionCallback(pi: ExtensionAPI, id: string): void {
         || meta.completionCallbackPendingAt === undefined
         || meta.completionCallbackSentAt !== undefined
         || meta.completionCallbackSuppressedAt !== undefined) return;
-    const label = meta.name ? `${meta.name} (${id})` : id;
-    const observations = Object.values(collectRunFailures(id, meta.cwd, true).observations);
-    const unresolved = observations.filter((observation) => observation.status === "unresolved");
-    const observationStatus = unresolved.some((observation) => observation.category === "observation-incomplete")
-        ? "observation incomplete" : unresolved.length ? "unresolved failure observations" : undefined;
+    const state = collectRunFailures(id, meta.cwd, true);
+    // Lifecycle, current actionability, and retained history are separate facts (#315).
+    const due = pendingFailureAttention(state, Date.now(), { terminal: true });
     getCallbackBatcher(pi).enqueue({
-        source: "subagent",
-        id,
-        label,
-        status: observationStatus ? `${meta.status}; ${observationStatus}` : meta.status,
-        detailTool: "subagent_result",
+        ...completionCallbackFields(meta, state, due?.incidents ?? []),
         callback: true,
         isDelivered: () => {
             const current = readMeta(id);
@@ -386,13 +392,13 @@ function deliverFailureAttention(pi: ExtensionAPI | undefined, meta: RunMeta, no
     if (!pi || meta.callback === false || callbackSuppressionReason(meta)) return;
     if ((meta.status === "orphaned" || meta.status === "lost") && !isHealthCallbackHandled(meta, meta.status)) return;
     const state = collectRunFailures(meta.id, meta.cwd, meta.status !== "running" && meta.status !== "orphaned");
-    const pending = pendingFailureAttention(state, now);
+    // Evidence gaps (oversized or malformed log records) are not something the parent can act on
+    // while the child runs; they ride the completion or health callback instead (#315).
+    const pending = pendingFailureAttention(state, now, { deferObservationGaps: true });
     if (!pending || (meta.status !== "running" && meta.status !== "orphaned" && meta.completionCallbackPendingAt !== undefined)) return;
-    const label = meta.name ? `${meta.name} (${meta.id})` : meta.id;
+    // Only the pending incidents are rendered; earlier deliveries are counted, not repeated (#315).
     void getCallbackBatcher(pi).deliverUrgent({
-        source: "subagent", id: meta.id, label, status: `failure:${pending.key}`,
-        customType: "subagent-failure",
-        content: `${formatFailureSummary(state)}\nInspect: subagent_output id=${JSON.stringify(meta.id)}`,
+        ...failureAttentionFields(meta, state, pending),
         isDelivered: () => failureAttentionHandled(collectRunFailures(meta.id, meta.cwd), pending.incidents),
         getSuppressionReason: () => {
             const current = readMeta(meta.id);
@@ -572,7 +578,6 @@ function deliverHealthCallback(pi: ExtensionAPI | undefined, meta: RunMeta, stat
     const callback = meta.callback !== false;
     const label = meta.name ? `${meta.name} (${meta.id})` : meta.id;
     const failureState = collectRunFailures(meta.id, meta.cwd, status === "lost");
-    const failureText = formatFailureSummary(failureState);
     const attention = pendingFailureAttention(failureState, now, { terminal: status === "lost" });
     const delivery = buildHealthCallbackDelivery({ id: meta.id, label, status, callback });
     if (!delivery) {
@@ -584,12 +589,7 @@ function deliverHealthCallback(pi: ExtensionAPI | undefined, meta: RunMeta, stat
         return;
     }
     void getCallbackBatcher(pi).deliverUrgent({
-        source: "subagent",
-        id: meta.id,
-        label,
-        status,
-        customType: "subagent-health",
-        content: prependFailureSummary(delivery.content, failureText),
+        ...healthCallbackFields(meta, status, failureState, delivery.content, attention?.incidents ?? []),
         isDelivered: () => {
             const current = readMeta(meta.id);
             if (!current) throw new Error("Subagent metadata is unavailable; defer health notification");
@@ -1785,9 +1785,14 @@ export default function (pi: ExtensionAPI) {
     // the factories return, so tests invoke the same execute handlers the
     // model reaches (no drift-prone second copy). Stop's only UI side effect
     // (widget redraw after a kill) is injected as onStopped.
-    pi.registerTool(subagentListTool(Type));
-    pi.registerTool(subagentOutputTool(Type));
-    const acceptanceResultTool = subagentResultTool(Type);
+    // The foreground origin from session_start; otherwise the calling context's
+    // own session. An unreadable session id stays unavailable (never cwd-wide).
+    const toolSession = {
+        getActiveOrigin: (ctx?: unknown) => activeCallbackOrigin ?? verifiedOriginFromContext(ctx as ExtensionContext | undefined),
+    };
+    pi.registerTool(subagentListTool(Type, toolSession));
+    pi.registerTool(subagentOutputTool(Type, toolSession));
+    const acceptanceResultTool = subagentResultTool(Type, toolSession);
     pi.registerTool(acceptanceResultTool);
     publishAcceptanceHooks(acceptanceResultTool);
     const acceptanceStopTool = subagentStopTool(Type, { onStopped: renderWidget });

package/lifecycle.ts

@@ -299,7 +299,8 @@ export interface FormatSubagentResultInput {
     status: string;
     exitCode: string | number;
     statSeg: string;
-    toolsSeg: string;
+    /** @deprecated Ordinary tool-name sequences are omitted from result heads (#312). */
+    toolsSeg?: string;
     run: ParsedRun;
     rawLogTail: string;
     lifecycle: LifecycleValidation;
@@ -312,8 +313,9 @@ export interface FormatSubagentResultInput {
  * consistent with the registered tool path.
  */
 export function formatSubagentResult(input: FormatSubagentResultInput): string {
-    const { id, status, exitCode, statSeg, toolsSeg, run, rawLogTail, lifecycle } = input;
-    const head = `[${id} · ${status} · exit ${exitCode}${statSeg}${toolsSeg} · lifecycle ${lifecycle.classification}]`;
+    const { id, status, exitCode, statSeg, run, rawLogTail, lifecycle } = input;
+    // Ordinary ordered tool histories are omitted from the head (#312).
+    const head = `[${id} · ${status} · exit ${exitCode}${statSeg} · lifecycle ${lifecycle.classification}]`;
     if (lifecycle.incomplete) {
         return `${head}\n${formatIncompleteResult(run, rawLogTail, lifecycle)}`;
     }
@@ -325,9 +327,8 @@ export function formatSubagentResult(input: FormatSubagentResultInput): string {
         || (run.lastActivity
             ? `(no final answer parsed; latest activity)\n${run.lastActivity}`
             : `(no final answer parsed)\n\n--- raw log tail ---\n${rawLogTail}`);
-    return [
-        head,
-        formatLifecycleDiagnostics(lifecycle),
-        body,
-    ].join("\n");
+    const exceptional = lifecycle.classification !== "complete" || lifecycle.incomplete;
+    return exceptional
+        ? [head, formatLifecycleDiagnostics(lifecycle), body].join("\n")
+        : [head, body].join("\n");
 }

package/list.mjs

@@ -1,7 +1,7 @@
-import { fmtElapsed, fmtSpend } from "./widget.mjs";
+import { fmtElapsed } from "./widget.mjs";
 import { formatListHealthSuffix } from "./health-surface.mjs";
 
-export const SUBAGENT_LIST_DEFAULT_LIMIT = 20;
+export const SUBAGENT_LIST_DEFAULT_LIMIT = 10;
 export const SUBAGENT_LIST_MAX_LIMIT = 100;
 /** Effective + durable supervision statuses accepted by subagent_list filters. */
 export const SUBAGENT_LIST_STATUSES = [
@@ -65,60 +65,83 @@ export function normalizeSubagentListOptions(params = {}) {
     };
 }
 
+function bounded(value, max) {
+    const single = String(value ?? "").replace(/\s+/g, " ").trim();
+    return single.length <= max ? single : `${single.slice(0, Math.max(0, max - 1))}…`;
+}
+
+/**
+ * One compact row. Free text (name, model, batch) is bounded so the id and
+ * status always sit within the row's first ~80 characters and survive clipping.
+ */
 export function formatSubagentListRow(meta, p) {
     const status = p.status;
     const now = p.now ?? Date.now();
-    const usage = p.usage;
     const elapsed = fmtElapsed((meta.endedAt ?? now) - meta.startedAt);
-    const spend = fmtSpend(usage);
-    const name = meta.name ? `${meta.name} ` : "";
-    const stat = `${elapsed}${spend ? ` · ${spend}` : ""}`;
+    const name = meta.name ? `${bounded(meta.name, 60)} ` : "";
     const health = formatListHealthSuffix(p.health);
-    const failure = p.failure ? `\n    ${p.failure.replace(/\n/g, "\n    ")}` : "";
+    const failure = p.failure ? ` · ${bounded(p.failure, 60)}` : "";
     const batch = meta.batchId
-        ? `  [batch: ${meta.batchName ? `${meta.batchName} ` : ""}${meta.batchId}]`
+        ? `  [batch: ${meta.batchName ? `${bounded(meta.batchName, 40)} ` : ""}${bounded(meta.batchId, 60)}]`
         : "";
-    return `• ${name}${meta.id}  [${status}]  ${meta.model ?? "?"}  ${stat}${health}${batch}${failure}\n    ${promptPreview(meta)}`;
+    return `• ${name}${meta.id}  [${status}]  ${bounded(meta.model ?? "?", 60)}  ${elapsed}${health}${batch}${failure}\n    ${promptPreview(meta)}`;
 }
 
-export function buildSubagentList(p) {
+export function collectSubagentList(p) {
     const options = normalizeSubagentListOptions(p.params ?? {});
     const now = p.now ?? Date.now();
     const parentPid = p.parentPid ?? process.pid;
     const statusOf = p.statusOf ?? ((meta) => meta.status);
-    const usageById = p.usageById ?? (() => undefined);
     const healthById = p.healthById ?? (() => undefined);
     const failureById = p.failureById ?? (() => "");
+    const inScope = p.inScope ?? ((meta) => options.all || meta.spawnPid === parentPid);
+    const offset = Math.max(0, Math.floor(Number(p.offset) || 0));
 
     const scoped = (p.metas ?? [])
-        .filter((meta) => options.all || meta.spawnPid === parentPid)
+        .filter((meta) => inScope(meta, options))
         .sort((a, b) => b.startedAt - a.startedAt)
         .map((meta) => ({ meta, status: statusOf(meta) }));
 
-    const matching = options.statuses === null
+    const items = options.statuses === null
         ? scoped
         : scoped.filter((row) => options.statuses.has(row.status));
 
-    const displayed = matching.slice(0, options.limit);
-    const lines = [...options.warnings];
+    const displayed = items.slice(offset, offset + options.limit);
+    const rows = displayed.map((row) => formatSubagentListRow(row.meta, {
+        status: row.status,
+        now,
+        health: healthById(row.meta.id),
+        failure: failureById(row.meta.id),
+    }));
 
-    if (matching.length === 0) {
+    return {
+        warnings: options.warnings,
+        items,
+        rows,
+        matching: items.length,
+        displayed: displayed.length,
+        offset,
+        limit: options.limit,
+        all: options.all,
+        empty: items.length === 0,
+    };
+}
+
+export function buildSubagentList(p) {
+    const collected = collectSubagentList(p);
+    const lines = [...collected.warnings];
+
+    if (collected.empty) {
         lines.push("No subagent runs match filters.");
         return lines.join("\n");
     }
 
-    lines.push(...displayed.map((row) => formatSubagentListRow(row.meta, {
-        status: row.status,
-        now,
-        usage: usageById(row.meta.id),
-        health: healthById(row.meta.id),
-        failure: failureById(row.meta.id),
-    })));
+    lines.push(...collected.rows);
 
-    if (matching.length > displayed.length) {
+    if (collected.matching > collected.displayed + collected.offset) {
         lines.push(
-            `Showing ${displayed.length} of ${matching.length} matching subagent runs ` +
-            `(limit ${options.limit}). Increase limit up to ${SUBAGENT_LIST_MAX_LIMIT} to see more.`,
+            `Showing ${collected.displayed} of ${collected.matching} matching subagent runs ` +
+            `(limit ${collected.limit}). Increase limit up to ${SUBAGENT_LIST_MAX_LIMIT} to see more.`,
         );
     }
 

package/list.ts

@@ -4,6 +4,7 @@ export {
     SUBAGENT_LIST_STATUSES,
     normalizeSubagentListOptions,
     formatSubagentListRow,
+    collectSubagentList,
     buildSubagentList,
 } from "./list.mjs";