@fitchmultz/pi-subagents 0.44.7 → 0.46.0

package/dist/runs/shared/subagent-control.js

@@ -1,11 +1,11 @@
-import {} from "../../shared/types.js";
 import { formatRunAction } from "../../shared/status-format.js";
 import { readStatus } from "../../shared/utils.js";
 import { getRunMetadataDir } from "./supervisor-questions.js";
 export function isObsoleteIdleNotice(details) {
-    const event = details?.event;
-    if (!event || event.reason !== "idle" || event.supervisorQuestion)
+    const event = details.event;
+    if (event.reason !== "idle" || event.supervisorQuestion) {
         return false;
+    }
     let status;
     try {
         status = readStatus(details.asyncDir ?? getRunMetadataDir(event.runId));
@@ -14,14 +14,26 @@ export function isObsoleteIdleNotice(details) {
         // Without readable terminal evidence, retain the actionable notice.
         return false;
     }
-    if (!status || status.runId !== event.runId)
+    if (!status || status.runId !== event.runId) {
+        return false;
+    }
+    return (["complete", "failed", "blocked", "paused"].includes(status.state) ||
+        hasTerminalChild(status, event.index));
+}
+function hasTerminalChild(status, index) {
+    if (index === undefined) {
         return false;
-    const child = event.index === undefined ? undefined : status.steps?.[event.index];
-    return ["complete", "failed", "blocked", "paused"].includes(status.state)
-        || Boolean(child && ["complete", "completed", "failed", "blocked", "paused", "timed-out"].includes(child.status));
+    }
+    const child = status.steps?.[index];
+    return (child !== undefined &&
+        ["complete", "completed", "failed", "blocked", "paused", "timed-out"].includes(child.status));
 }
 const CONTROL_EVENT_TYPES = ["needs_attention"];
-const CONTROL_NOTIFICATION_CHANNELS = ["event", "async", "intercom"];
+const CONTROL_NOTIFICATION_CHANNELS = [
+    "event",
+    "async",
+    "intercom",
+];
 const DEFAULT_NOTIFY_ON = ["needs_attention"];
 export const DEFAULT_CONTROL_CONFIG = {
     enabled: true,
@@ -31,67 +43,119 @@ export const DEFAULT_CONTROL_CONFIG = {
     notifyChannels: CONTROL_NOTIFICATION_CHANNELS,
 };
 function parsePositiveInt(value) {
-    if (typeof value !== "number")
+    if (typeof value !== "number") {
         return undefined;
-    if (!Number.isFinite(value) || !Number.isInteger(value) || value < 1)
+    }
+    if (!Number.isFinite(value) || !Number.isInteger(value) || value < 1) {
         return undefined;
+    }
     return value;
 }
 function parseControlList(value, allowed) {
-    if (!Array.isArray(value))
+    if (!Array.isArray(value)) {
         return undefined;
-    if (value.length === 0)
+    }
+    if (value.length === 0) {
         return [];
-    const allowedSet = new Set(allowed);
-    const parsed = value.filter((entry) => typeof entry === "string" && allowedSet.has(entry));
+    }
+    const entries = value;
+    const parsed = entries.filter((entry) => typeof entry === "string" && allowed.some((candidate) => candidate === entry));
     return parsed.length > 0 ? Array.from(new Set(parsed)) : undefined;
 }
-export function resolveControlConfig(globalConfig, override) {
-    const enabled = override?.enabled ?? globalConfig?.enabled ?? DEFAULT_CONTROL_CONFIG.enabled;
-    const needsAttentionAfterMs = parsePositiveInt(override?.needsAttentionAfterMs)
-        ?? parsePositiveInt(globalConfig?.needsAttentionAfterMs)
-        ?? DEFAULT_CONTROL_CONFIG.needsAttentionAfterMs;
-    const failedToolAttemptsBeforeAttention = parsePositiveInt(override?.failedToolAttemptsBeforeAttention)
-        ?? parsePositiveInt(globalConfig?.failedToolAttemptsBeforeAttention)
-        ?? DEFAULT_CONTROL_CONFIG.failedToolAttemptsBeforeAttention;
-    const notifyOn = parseControlList(override?.notifyOn, CONTROL_EVENT_TYPES)
-        ?? parseControlList(globalConfig?.notifyOn, CONTROL_EVENT_TYPES)
-        ?? DEFAULT_CONTROL_CONFIG.notifyOn;
-    const notifyChannels = parseControlList(override?.notifyChannels, CONTROL_NOTIFICATION_CHANNELS)
-        ?? parseControlList(globalConfig?.notifyChannels, CONTROL_NOTIFICATION_CHANNELS)
-        ?? DEFAULT_CONTROL_CONFIG.notifyChannels;
+function parsedControlConfig(config) {
+    const input = config ?? {};
+    return {
+        enabled: input.enabled,
+        needsAttentionAfterMs: parsePositiveInt(input.needsAttentionAfterMs),
+        failedToolAttemptsBeforeAttention: parsePositiveInt(input.failedToolAttemptsBeforeAttention),
+        notifyOn: parseControlList(input.notifyOn, CONTROL_EVENT_TYPES),
+        notifyChannels: parseControlList(input.notifyChannels, CONTROL_NOTIFICATION_CHANNELS),
+    };
+}
+function controlThresholds(global, override) {
     return {
-        enabled,
-        needsAttentionAfterMs,
-        failedToolAttemptsBeforeAttention,
+        needsAttentionAfterMs: override.needsAttentionAfterMs ??
+            global.needsAttentionAfterMs ??
+            DEFAULT_CONTROL_CONFIG.needsAttentionAfterMs,
+        failedToolAttemptsBeforeAttention: override.failedToolAttemptsBeforeAttention ??
+            global.failedToolAttemptsBeforeAttention ??
+            DEFAULT_CONTROL_CONFIG.failedToolAttemptsBeforeAttention,
+    };
+}
+export function resolveControlConfig(globalConfig, overrideConfig) {
+    const global = parsedControlConfig(globalConfig);
+    const override = parsedControlConfig(overrideConfig);
+    const notifyOn = override.notifyOn ?? global.notifyOn ?? DEFAULT_CONTROL_CONFIG.notifyOn;
+    const notifyChannels = override.notifyChannels ?? global.notifyChannels ?? DEFAULT_CONTROL_CONFIG.notifyChannels;
+    return {
+        enabled: override.enabled ?? global.enabled ?? DEFAULT_CONTROL_CONFIG.enabled,
+        ...controlThresholds(global, override),
         notifyOn: [...notifyOn],
         notifyChannels: [...notifyChannels],
     };
 }
 export function deriveActivityState(input) {
-    if (!input.config.enabled)
+    if (!input.config.enabled) {
         return undefined;
+    }
     const now = input.now ?? Date.now();
     const lastActivity = input.lastActivityAt ?? input.startedAt;
     const ageMs = Math.max(0, now - lastActivity);
     return ageMs > input.config.needsAttentionAfterMs ? "needs_attention" : undefined;
 }
+function controlObservation(input, elapsedSeconds) {
+    if (input.currentTool !== undefined && input.currentTool !== "") {
+        const duration = input.currentToolDurationMs === undefined
+            ? ""
+            : ` for ${Math.floor(input.currentToolDurationMs / 1000)}s`;
+        const elapsed = elapsedSeconds === undefined ? "" : `; no observed output/events for ${elapsedSeconds}s`;
+        return `${input.currentTool} still active${duration}${elapsed}`;
+    }
+    return elapsedSeconds === undefined ? undefined : `no observed activity for ${elapsedSeconds}s`;
+}
+function controlSignal(input) {
+    const question = input.supervisorQuestion;
+    if (!question) {
+        return `${input.agent} needs attention`;
+    }
+    return question.state === "awaiting_input"
+        ? `Waiting for supervisor input (question ${question.questionId})`
+        : `Supervisor answer saved for question ${question.questionId}; delivery unconfirmed`;
+}
+function controlMetrics(input, elapsedMs) {
+    return {
+        ...(input.turns !== undefined ? { turns: input.turns } : {}),
+        ...(input.tokens !== undefined ? { tokens: input.tokens } : {}),
+        ...(input.toolCount !== undefined ? { toolCount: input.toolCount } : {}),
+        ...(input.currentToolDurationMs !== undefined
+            ? { currentToolDurationMs: input.currentToolDurationMs }
+            : {}),
+        ...(elapsedMs !== undefined ? { elapsedMs } : {}),
+    };
+}
+function controlContext(input) {
+    return {
+        ...((input.currentTool ?? "") !== "" ? { currentTool: input.currentTool } : {}),
+        ...((input.currentPath ?? "") !== "" ? { currentPath: input.currentPath } : {}),
+        ...((input.recentFailureSummary ?? "") !== ""
+            ? { recentFailureSummary: input.recentFailureSummary }
+            : {}),
+        ...(input.supervisorQuestion ? { supervisorQuestion: input.supervisorQuestion } : {}),
+    };
+}
+function controlElapsed(input, ts) {
+    return (input.elapsedMs ??
+        (input.lastActivityAt !== undefined ? Math.max(0, ts - input.lastActivityAt) : undefined));
+}
 export function buildControlEvent(input) {
     const ts = input.ts ?? Date.now();
-    const type = input.type ?? "needs_attention";
-    const elapsedMs = input.elapsedMs ?? (input.lastActivityAt !== undefined ? Math.max(0, ts - input.lastActivityAt) : undefined);
-    const elapsedSeconds = elapsedMs !== undefined ? Math.floor(elapsedMs / 1000) : undefined;
-    const question = input.supervisorQuestion;
-    const observation = input.currentTool
-        ? `${input.currentTool} still active${input.currentToolDurationMs !== undefined ? ` for ${Math.floor(input.currentToolDurationMs / 1000)}s` : ""}${elapsedSeconds !== undefined ? `; no observed output/events for ${elapsedSeconds}s` : ""}`
-        : elapsedSeconds !== undefined ? `no observed activity for ${elapsedSeconds}s` : undefined;
-    const signal = question
-        ? question.state === "awaiting_input" ? `Waiting for supervisor input (question ${question.questionId})` : `Supervisor answer saved for question ${question.questionId}; delivery unconfirmed`
-        : `${input.agent} needs attention`;
-    const message = input.message ?? `${signal}${observation ? ` (${observation})` : ""}`;
+    const elapsedMs = controlElapsed(input, ts);
+    const observation = controlObservation(input, elapsedMs === undefined ? undefined : Math.floor(elapsedMs / 1000));
+    const message = input.message ??
+        `${controlSignal(input)}${observation === undefined ? "" : ` (${observation})`}`;
     return {
-        type,
-        ...(input.from ? { from: input.from } : {}),
+        type: input.type ?? "needs_attention",
+        ...(input.from !== undefined ? { from: input.from } : {}),
         to: input.to,
         ts,
         runId: input.runId,
@@ -99,74 +163,77 @@ export function buildControlEvent(input) {
         ...(input.index !== undefined ? { index: input.index } : {}),
         message,
         reason: input.reason ?? "idle",
-        ...(input.turns !== undefined ? { turns: input.turns } : {}),
-        ...(input.tokens !== undefined ? { tokens: input.tokens } : {}),
-        ...(input.toolCount !== undefined ? { toolCount: input.toolCount } : {}),
-        ...(input.currentTool ? { currentTool: input.currentTool } : {}),
-        ...(input.currentToolDurationMs !== undefined ? { currentToolDurationMs: input.currentToolDurationMs } : {}),
-        ...(input.currentPath ? { currentPath: input.currentPath } : {}),
-        ...(elapsedMs !== undefined ? { elapsedMs } : {}),
-        ...(input.recentFailureSummary ? { recentFailureSummary: input.recentFailureSummary } : {}),
-        ...(question ? { supervisorQuestion: question } : {}),
+        ...controlMetrics(input, elapsedMs),
+        ...controlContext(input),
     };
 }
-export function shouldNotifyControlEvent(config, event) {
-    return config.enabled && config.notifyOn.includes(event.type);
+export { shouldNotifyControlEvent, controlNotificationKey } from "./control-event-policy.js";
+export { claimControlNotification } from "./control-notification-owner.js";
+function failureNotice(event, childIntercomTarget) {
+    return [
+        `Subagent failed: ${event.agent}`,
+        `Run: ${event.runId}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
+        `Signal: ${event.message}`,
+        "Next: read the output artifact or session from the subagent result, then retry with a more explicit implementation prompt or handle the fix directly.",
+        childIntercomTarget !== undefined && childIntercomTarget !== ""
+            ? `Run intercom target (may be inactive): ${childIntercomTarget}`
+            : undefined,
+    ]
+        .filter((line) => line !== undefined)
+        .join("\n");
 }
-export function controlNotificationKey(event, childIntercomTarget) {
-    const childKey = childIntercomTarget ?? (event.index !== undefined ? `${event.runId}:${event.index}` : event.runId);
-    return `${childKey}:${event.type}:${event.reason ?? "idle"}`;
+function questionNotice(event, childSafe) {
+    const question = event.supervisorQuestion;
+    if (!question) {
+        return [];
+    }
+    return [
+        `Question ID: ${question.questionId}`,
+        question.state === "answer_pending"
+            ? "The saved answer has not been confirmed delivered. Inspect the child and retry the same answer; do not assume it resumed."
+            : "Answer the saved question so the child can continue.",
+        `Questions: ${formatRunAction("questions", event.runId, {}, childSafe)}`,
+        `Answer: ${formatRunAction("answer", event.runId, { questionId: question.questionId, message: question.answer ?? "..." }, childSafe)}`,
+    ];
 }
-export function claimControlNotification(config, event, seenKeys, childIntercomTarget) {
-    if (!shouldNotifyControlEvent(config, event))
-        return false;
-    const key = controlNotificationKey(event, childIntercomTarget);
-    if (seenKeys.has(key))
-        return false;
-    seenKeys.add(key);
-    return true;
+function liveNotice(event, childIntercomTarget, childSafe) {
+    const nudgeCommand = formatRunAction("nudge", event.runId, {
+        ...(event.index !== undefined ? { index: event.index } : {}),
+        message: "What are you blocked on? Reply with the smallest next step, or state the exact decision you need.",
+    }, childSafe);
+    const ask = childIntercomTarget !== undefined && childIntercomTarget !== ""
+        ? `Ask (blocking wait only; parent must remain alive): intercom({ action: "ask", to: "${childIntercomTarget}", delivery: "steer", message: "What are you blocked on? Reply with the smallest next step, or state the exact decision you need." })`
+        : "Ask (blocking wait only): no child message route registered";
+    return [
+        event.reason === "idle" && (event.currentTool ?? "") !== ""
+            ? "Hint: Inspect command progress. A long-running tool may still be running or hung; elapsed time alone does not prove either."
+            : "Hint: Inspect status first unless the run is clearly blocked.",
+        `Nudge (preferred live coordination): ${nudgeCommand}`,
+        ask,
+    ];
 }
 export function formatControlNoticeMessage(event, childIntercomTarget, childSafe = false) {
-    const runTarget = event.runId;
     if (event.reason === "completion_guard") {
-        return [
-            `Subagent failed: ${event.agent}`,
-            `Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
-            `Signal: ${event.message}`,
-            "Next: read the output artifact or session from the subagent result, then retry with a more explicit implementation prompt or handle the fix directly.",
-            childIntercomTarget ? `Run intercom target (may be inactive): ${childIntercomTarget}` : undefined,
-        ].filter((line) => Boolean(line)).join("\n");
+        return failureNotice(event, childIntercomTarget);
     }
-    const nudgeCommand = formatRunAction("nudge", runTarget, { ...(event.index !== undefined ? { index: event.index } : {}), message: "What are you blocked on? Reply with the smallest next step, or state the exact decision you need." }, childSafe);
-    const question = event.supervisorQuestion;
-    const askCommand = childIntercomTarget
-        ? `intercom({ action: "ask", to: "${childIntercomTarget}", delivery: "steer", message: "What are you blocked on? Reply with the smallest next step, or state the exact decision you need." })`
-        : undefined;
     return [
         `Subagent needs attention: ${event.agent}`,
-        `Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
+        `Run: ${event.runId}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
         `Signal: ${event.message}`,
-        event.recentFailureSummary ? `Recent failures: ${event.recentFailureSummary}` : undefined,
-        ...(question ? [
-            `Question ID: ${question.questionId}`,
-            question.state === "answer_pending" ? "The saved answer has not been confirmed delivered. Inspect the child and retry the same answer; do not assume it resumed." : "Answer the saved question so the child can continue.",
-            `Questions: ${formatRunAction("questions", runTarget, {}, childSafe)}`,
-            `Answer: ${formatRunAction("answer", runTarget, { questionId: question.questionId, message: question.answer ?? "..." }, childSafe)}`,
-        ] : [
-            event.reason === "idle" && event.currentTool ? "Hint: Inspect command progress. A long-running tool may still be running or hung; elapsed time alone does not prove either." : "Hint: Inspect status first unless the run is clearly blocked.",
-            `Nudge (preferred live coordination): ${nudgeCommand}`,
-            childIntercomTarget
-                ? `Ask (blocking wait only; parent must remain alive): ${askCommand}`
-                : "Ask (blocking wait only): no child message route registered",
-        ]),
-        `Status: ${formatRunAction("status", runTarget, {}, childSafe)}`,
-        `${childSafe ? "Interrupt" : "Stop"}: ${formatRunAction("interrupt", runTarget, {}, childSafe)}`,
-    ].filter((line) => Boolean(line)).join("\n");
+        (event.recentFailureSummary ?? "") !== ""
+            ? `Recent failures: ${event.recentFailureSummary ?? ""}`
+            : undefined,
+        ...(event.supervisorQuestion
+            ? questionNotice(event, childSafe)
+            : liveNotice(event, childIntercomTarget, childSafe)),
+        `Status: ${formatRunAction("status", event.runId, {}, childSafe)}`,
+        `${childSafe ? "Interrupt" : "Stop"}: ${formatRunAction("interrupt", event.runId, {}, childSafe)}`,
+    ]
+        .filter((line) => line !== undefined)
+        .join("\n");
 }
 export function formatControlIntercomMessage(event, childIntercomTarget, childSafe = false) {
-    const statusLabel = event.reason === "completion_guard"
-        ? "subagent failed"
-        : "subagent needs attention";
+    const statusLabel = event.reason === "completion_guard" ? "subagent failed" : "subagent needs attention";
     return [
         statusLabel,
         "",

package/dist/runs/shared/subagent-prompt-runtime.js

@@ -1,12 +1,13 @@
 import * as fs from "node:fs";
-import * as path from "node:path";
-import { Type } from "../../shared/native-typebox.js";
-import { SUBAGENT_FANOUT_CHILD_ENV } from "./pi-args.js";
+import { SUBAGENT_FANOUT_CHILD_ENV } from "./child-route-env.js";
 import { setPromptSection } from "../../shared/prompt-sections.js";
 import { loadConfig } from "../../extension/config.js";
 import { registerChildExecutionCwd } from "./child-execution-cwd.js";
-import { STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV, validateStructuredOutputValue } from "./structured-output.js";
-import { SessionEntryCursor } from "../../shared/session-entries.js";
+import { STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV, assertJsonSchemaObject, } from "./structured-output.js";
+import { registerChildStructuredTool } from "./child-structured-tool.js";
+import { ChildNativeObservation } from "./child-native-observation.js";
+import { stripParentOnlySubagentMessages } from "./child-context-filter.js";
+import { nonempty } from "./child-presence.js";
 const SUBAGENT_INHERIT_PROJECT_CONTEXT_ENV = "PI_SUBAGENT_INHERIT_PROJECT_CONTEXT";
 const SUBAGENT_INHERIT_SKILLS_ENV = "PI_SUBAGENT_INHERIT_SKILLS";
 export const SUBAGENT_INTERCOM_SESSION_NAME_ENV = "PI_SUBAGENT_INTERCOM_SESSION_NAME";
@@ -30,135 +31,26 @@ export const CHILD_FANOUT_BOUNDARY_INSTRUCTIONS = [
     "The native allowSubagents and maxSubagentDepth settings still apply.",
     "If you need to edit files, call the actual edit/write tools. Do not print tool-call syntax, patches, or pseudo-tool calls as text.",
 ].join("\n");
-const PARENT_ONLY_CUSTOM_MESSAGE_TYPES = new Set([
-    "subagent-orchestration-instructions",
-    "subagent-slash-result",
-    "subagent-notify",
-    "subagent_control_notice",
-    "subagent-control",
-    "subagent-control-notice",
-]);
-const ORCHESTRATION_TOOLS = new Set(["subagent", "delegate", "agent_runs", "load_subagent"]);
 function readBooleanEnv(name) {
     const value = process.env[name];
-    if (value === undefined)
-        return undefined;
-    return value !== "0";
-}
-function isParentOnlySubagentMessage(message) {
-    const m = message;
-    return m?.role === "custom"
-        && typeof m.customType === "string"
-        && PARENT_ONLY_CUSTOM_MESSAGE_TYPES.has(m.customType);
-}
-function isSubagentExecutionResultMessage(message) {
-    const m = message;
-    return m?.role === "toolResult" && typeof m.toolName === "string" && ORCHESTRATION_TOOLS.has(m.toolName);
-}
-function isSubagentToolCallBlock(block) {
-    const b = block;
-    return b?.type === "toolCall" && typeof b.name === "string" && ORCHESTRATION_TOOLS.has(b.name);
-}
-function stripAssistantSubagentToolCallBlocks(message) {
-    const m = message;
-    if (m?.role !== "assistant" || !Array.isArray(m.content))
-        return message;
-    const filteredContent = m.content.filter((block) => !isSubagentToolCallBlock(block));
-    if (filteredContent.length === m.content.length)
-        return message;
-    if (filteredContent.length === 0)
-        return undefined;
-    return { ...m, content: filteredContent };
-}
-function stripParentOnlySubagentMessages(messages, fanoutChild = false) {
-    let changed = false;
-    const filtered = [];
-    for (const message of messages) {
-        if (isParentOnlySubagentMessage(message) || (!fanoutChild && isSubagentExecutionResultMessage(message))) {
-            changed = true;
-            continue;
-        }
-        const stripped = fanoutChild ? message : stripAssistantSubagentToolCallBlocks(message);
-        if (stripped === undefined) {
-            changed = true;
-            continue;
-        }
-        if (stripped !== message)
-            changed = true;
-        filtered.push(stripped);
-    }
-    return changed ? filtered : messages;
+    return value === undefined ? undefined : value !== "0";
 }
 export default function registerSubagentPromptRuntime(pi) {
     registerChildExecutionCwd(pi);
-    // Print-mode observation uses the existing child runtime. turn_end follows native
-    // message append; message_end itself is deliberately never called a commit receipt.
-    let observedMessages = 0;
-    const cursor = new SessionEntryCursor();
-    let previousIds = new Set();
-    pi.on("session_start", (_event, ctx) => {
-        cursor.reset();
-        observedMessages = 0;
-        const { entries } = cursor.read(ctx.sessionManager);
-        const baseline = process.env.PI_SUBAGENT_NATIVE_BASELINE_COUNT;
-        if (baseline && /^\d+$/.test(baseline))
-            process.stdout.write(`${JSON.stringify({ type: "subagent.native_baseline", sessionId: ctx.sessionManager.getSessionId(), entryIds: entries.slice(0, Number(baseline)).map((entry) => entry.id) })}\n`);
-        const file = ctx.sessionManager.getSessionFile();
-        previousIds = file && fs.existsSync(file) ? new Set(entries.map((entry) => entry.id)) : new Set();
-        if (!file || !fs.existsSync(file))
-            cursor.reset();
-    });
-    pi.on("message_end", (event) => { if (["assistant", "user", "toolResult"].includes(event.message.role))
-        observedMessages++; });
-    const observe = (ctx, boundary) => {
-        if (process.env.PI_SUBAGENT_CHILD !== "1")
-            return;
-        const entries = [];
-        for (const entry of cursor.read(ctx.sessionManager).entries)
-            if (!previousIds.has(entry.id)) {
-                previousIds.add(entry.id);
-                const message = entry.type === "message" ? entry.message : undefined;
-                entries.push({ id: entry.id, type: entry.type, parentId: entry.parentId,
-                    ...("checkpoint" in entry ? { checkpoint: entry.checkpoint } : {}),
-                    ...(entry.type === "usage" || entry.type === "compaction" || entry.type === "branch_summary" ? { usage: entry.usage } : {}),
-                    ...(entry.type === "usage" ? { provider: entry.provider, model: entry.model } : {}),
-                    ...(message ? { message: { role: message.role, timestamp: message.timestamp,
-                            ...("usage" in message ? { usage: message.usage } : {}),
-                            ...(message.role === "assistant" ? { provider: message.provider, model: message.model, responseModel: message.responseModel } : {}),
-                            ...("toolCallId" in message ? { toolCallId: message.toolCallId } : {}) } } : {}) });
-            }
-        const sessionFile = ctx.sessionManager.getSessionFile();
-        process.stdout.write(`${JSON.stringify({ type: "subagent.native", boundary, entries,
-            sessionId: ctx.sessionManager.getSessionId(), sessionFile, leafId: ctx.sessionManager.getLeafId(),
-            persisted: Boolean(sessionFile && fs.existsSync(sessionFile)), messageCount: observedMessages,
-            configuration: { ...(ctx.model ? { model: `${ctx.model.provider}/${ctx.model.id}` } : {}), thinking: pi.getThinkingLevel() } })}\n`);
-    };
-    pi.on("turn_end", (_event, ctx) => observe(ctx, "turn"));
-    pi.on("agent_settled", (_event, ctx) => observe(ctx, "settled"));
+    const observation = new ChildNativeObservation();
+    pi.on("session_start", (_event, ctx) => observation.start(ctx));
+    pi.on("message_end", (event) => observation.message(event.message.role));
+    pi.on("turn_end", (_event, ctx) => observation.publish(ctx, "turn", pi));
+    pi.on("agent_settled", (_event, ctx) => observation.publish(ctx, "settled", pi));
     const structuredOutputPath = process.env[STRUCTURED_OUTPUT_CAPTURE_ENV];
     const structuredSchemaPath = process.env[STRUCTURED_OUTPUT_SCHEMA_ENV];
-    if (structuredOutputPath && structuredSchemaPath) {
+    if (nonempty(structuredOutputPath) && nonempty(structuredSchemaPath)) {
         const schema = JSON.parse(fs.readFileSync(structuredSchemaPath, "utf-8"));
-        const parameters = Type.Object({ value: Type.Unsafe(schema) }, { additionalProperties: false });
-        pi.registerTool({
-            name: "structured_output",
-            label: "Structured Output",
-            description: "Submit the required final structured output for this subagent step. This terminates the step.",
-            parameters,
-            constrainedSampling: { type: "json_schema", strict: "prefer" },
-            async execute(_id, params) {
-                const validation = validateStructuredOutputValue(schema, params.value);
-                if (validation.status === "invalid") {
-                    throw new Error(`Structured output validation failed: ${validation.message}`);
-                }
-                fs.mkdirSync(path.dirname(structuredOutputPath), { recursive: true });
-                fs.writeFileSync(structuredOutputPath, JSON.stringify(params.value), { mode: 0o600 });
-                return {
-                    content: [{ type: "text", text: "Structured output captured." }],
-                    details: { path: structuredOutputPath },
-                    terminate: true,
-                };
-            },
+        assertJsonSchemaObject(schema);
+        registerChildStructuredTool(pi, {
+            schema,
+            schemaPath: structuredSchemaPath,
+            outputPath: structuredOutputPath,
         });
         pi.on("session_start", () => {
             pi.setActiveTools([...new Set([...pi.getActiveTools(), "structured_output"])]);
@@ -168,20 +60,24 @@ export default function registerSubagentPromptRuntime(pi) {
         // Filtering changes the provider prefix, never the saved journal. Fanout children
         // need their own nested calls/results on later turns and resumes, so retain tool history.
         const messages = stripParentOnlySubagentMessages(event.messages, readBooleanEnv(SUBAGENT_FANOUT_CHILD_ENV) === true);
-        if (messages === event.messages)
+        if (messages === undefined) {
             return;
+        }
         return { messages };
     });
     pi.on("before_agent_start", (event) => {
         const intercomSessionName = process.env[SUBAGENT_INTERCOM_SESSION_NAME_ENV]?.trim();
-        if (intercomSessionName && typeof pi.setSessionName === "function") {
+        if (nonempty(intercomSessionName)) {
             pi.setSessionName(intercomSessionName);
         }
         const inheritProjectContext = readBooleanEnv(SUBAGENT_INHERIT_PROJECT_CONTEXT_ENV);
         const inheritSkills = readBooleanEnv(SUBAGENT_INHERIT_SKILLS_ENV);
         const fanoutChild = readBooleanEnv(SUBAGENT_FANOUT_CHILD_ENV);
-        if (inheritProjectContext === undefined && inheritSkills === undefined && fanoutChild === undefined)
+        if (inheritProjectContext === undefined &&
+            inheritSkills === undefined &&
+            fanoutChild === undefined) {
             return;
+        }
         const options = event.systemPromptOptions;
         // --no-skills/--no-context-files govern discovery. Keep explicitly selected
         // skill bodies and context intact; never parse the rendered prompt to remove resources.
@@ -191,7 +87,8 @@ export default function registerSubagentPromptRuntime(pi) {
                 ? "Use subagent({action:'list'}) to discover agents before delegation."
                 : "Use load_subagent({advanced:false}), then agent_runs({action:'profiles'}) to discover agents, delegate for ordinary work, and load_subagent for advanced workflows."}`
             : CHILD_SUBAGENT_BOUNDARY_INSTRUCTIONS);
-        if (structuredOutputPath)
+        if (nonempty(structuredOutputPath)) {
             setPromptSection(options, "subagent_output", STRUCTURED_OUTPUT_INSTRUCTIONS);
+        }
     });
 }