pi-better-background-tasks 0.3.0 → 0.4.0

package/src/runtime.ts

@@ -8,7 +8,8 @@ import { DEFAULT_TMUX_BOOTSTRAP_TIMEOUT_MS, expandSshRemoteTaskPreset } from "./
 import type { RemoteRunner, ResolvedSshRemoteTask } from "./remote-task-preset.js";
 import { ensureTaskDir, logPathFor, nextTaskId, readMeta, sandboxProfilePathFor, writeMeta } from "./registry.js";
 import { confineCommandSpec, resolveForegroundSandboxPlan } from "./sandbox.js";
-import { failurePath, recordFailure, recoverFailure, scheduleFailureAttention, stopFailureAttention, terminalFailureAttention } from "./failures.js";
+import { takeRecoverySnapshot } from "./shared-sandbox-core.js";
+import { failurePath, readTaskIntent, recordExitFailure, recordFailure, recoverDeclaredOperation, recoverFailure, resumeFailureAttention, scheduleFailureAttention, stopFailureAttention, suspendFailureAttention, terminalFailureAttention } from "./failures.js";
 import { markFailureAttentionDelivered } from "./shared-failure-observations.js";
 import { getCallbackBatcher } from "./shared-callback-batcher.js";
 import { formatCallbackFacts } from "./output.js";
@@ -33,16 +34,68 @@ const remoteSessionStarts = new Map<string, Promise<CommandResult>>();
 const activePolls = new Set<string>();
 const logRetentionTimers = new Map<string, ReturnType<typeof setInterval>>();
 const LOG_RETENTION_CHECK_MS = 1000;
+const handoffTimers = new Map<string, ReturnType<typeof setInterval>>();
+const HANDOFF_CHECK_MS = 250;
+const HANDOFF_LOST_GRACE_MS = 5_000;
+let scheduledWorkSuspended = false;
 const REMOTE_SESSION_POLL_MS = 100;
 
 export const DEFAULT_WATCH_TIMEOUT_SECONDS = 15 * 60;
 
+/**
+ * Stop this extension instance's scheduled work when its session shuts down (#324).
+ *
+ * Pi emits session_shutdown for /reload, /new, /resume, fork, session switch,
+ * and quit, and the next session loads a fresh extension instance. Work left in
+ * the old instance runs with no active session, so a task finishing there used to
+ * have its completion callback durably suppressed ("active session identity is
+ * unavailable") and the next session never heard about it.
+ *
+ * After suspension this instance schedules nothing and notifies nothing. Work
+ * already in flight (a child's close listener, a remote tmux bootstrap/start, a
+ * timeout kill) still records its result in metadata, but leaves the callback to
+ * the instance that resumes the task. Processes are not stopped.
+ *
+ * Resume is per callback origin: session_start resumes only tasks whose origin
+ * (cwd and session id) matches the new session. After /reload that is every task
+ * of the session. After switching to another session, the previous session's
+ * tasks keep running, but their watches do not poll, remote tmux output is not
+ * collected, and their `timeout_seconds` deadlines are not enforced until that
+ * session is active again; an overdue deadline is enforced immediately on resume.
+ * A local process that exits meanwhile is recorded as terminal and its callback
+ * is delivered when its session resumes.
+ */
+export function suspendScheduledWork(): void {
+  scheduledWorkSuspended = true;
+  for (const timer of watcherTimers.values()) clearTimeout(timer);
+  for (const timer of remoteSessionTimers.values()) clearTimeout(timer);
+  for (const timer of processTimeoutTimers.values()) clearTimeout(timer);
+  for (const timer of logRetentionTimers.values()) clearInterval(timer);
+  for (const timer of handoffTimers.values()) clearInterval(timer);
+  handoffTimers.clear();
+  watcherTimers.clear();
+  remoteSessionTimers.clear();
+  processTimeoutTimers.clear();
+  logRetentionTimers.clear();
+  suspendFailureAttention();
+}
+
+/** Allow scheduling again; called at session_start before running tasks are resumed. */
+export function resumeScheduledWork(): void {
+  scheduledWorkSuspended = false;
+  resumeFailureAttention();
+}
+
 
 
 export type ActiveSessionProvider = () => BackgroundTaskCallbackOrigin | undefined;
 
 export interface SpawnTaskParams extends CommandSpec {
   name?: string;
+  /** Structured intent (#325): stable id shared by modified retries of one operation. */
+  operation_id?: string | null;
+  /** Structured intent (#325): non-zero exit codes declared intentional before launch. */
+  expected_exit_codes?: number[] | null;
   callback?: boolean;
   timeout_seconds?: number;
   max_log_bytes?: number;
@@ -52,6 +105,10 @@ export interface SpawnTaskParams extends CommandSpec {
 
 export interface WatchTaskParams extends CommandSpec {
   name?: string;
+  /** Structured intent (#325): stable id shared by modified retries of one operation. */
+  operation_id?: string | null;
+  /** Structured intent (#325): non-zero exit codes declared intentional before launch. */
+  expected_exit_codes?: number[] | null;
   callback?: boolean;
   interval_seconds?: number;
   timeout_seconds?: number;
@@ -78,6 +135,7 @@ export function spawnTask(
 ): BackgroundTaskMeta {
   // Resolved before any task directory, log, or metadata exists so a blocked
   // launch leaves nothing behind. Structured SSH must also honor launch restrictions.
+  const intent = readTaskIntent(params);
   const sandboxPlan = resolveForegroundSandboxPlan(pi, !!params.ssh);
   const id = nextTaskId();
   const cwd = params.cwd ?? defaultCwd;
@@ -99,11 +157,21 @@ export function spawnTask(
     ? commandSpec
     : confineCommandSpec(commandSpec, sandboxPlan, sandboxProfilePathFor(id));
   const tmuxBacked = remoteTask?.metadata.remote.session === "tmux";
+  // Outside project = Write or Write & delete can change files outside the
+  // project: start an APFS local snapshot (macOS, background, never blocks).
+  const snapshot = !remoteTask && sandboxPlan.confined ? takeRecoverySnapshot(sandboxPlan.permissions) : undefined;
   const spawned = tmuxBacked
     ? undefined
     : remoteTask
       ? remoteTask.spawn(logPath, true)
       : spawnCommand(launchSpec, logPath, true);
+  if (snapshot?.started) {
+    void snapshot.done.then((outcome) => {
+      if (!outcome.ok) {
+        try { appendLine(logPath, `--- recovery snapshot failed (task continues): ${outcome.detail} ---`); } catch { /* log gone */ }
+      }
+    });
+  }
   const now = Date.now();
   const meta: BackgroundTaskMeta = {
     id,
@@ -130,6 +198,7 @@ export function spawnTask(
     spawnPidStartTime: currentProcessStartToken(),
     ssh: remoteTask?.metadata.ssh,
     remote: remoteTask?.metadata.remote,
+    ...intent,
   };
   writeMeta(meta);
   scheduleLogRetention(id);
@@ -146,8 +215,11 @@ export function spawnTask(
       if (!latest) return;
       enforceLogRetention(latest);
       if (isTerminalStatus(latest.status)) return;
-      if (exitCode !== 0) recordFailure(latest, "execution", `Process exited with code ${exitCode ?? "unknown"}${signal ? ` (${signal})` : ""}`, "close", { category: "exit", at: Date.now() });
-      else recoverFailure(latest, "execution", "close");
+      if (exitCode !== 0) recordExitFailure(latest, "execution", `Process exited with code ${exitCode ?? "unknown"}${signal ? ` (${signal})` : ""}`, exitCode, "close", { at: Date.now() });
+      else {
+        recoverFailure(latest, "execution", "close");
+        recoverDeclaredOperation(latest);
+      }
       latest.status = exitCode === 0 ? "succeeded" : "failed";
       latest.endedAt = Date.now();
       latest.lastExitCode = exitCode;
@@ -227,6 +299,7 @@ function scheduleRemoteSessionPoll(
   getActiveSession?: ActiveSessionProvider,
 ): void {
   clearRemoteSessionTimer(id);
+  if (scheduledWorkSuspended) return;
   const timer = setTimeout(() => void pollRemoteSession(pi, id, getActiveSession), delayMs);
   timer.unref();
   remoteSessionTimers.set(id, timer);
@@ -250,6 +323,7 @@ async function pollRemoteSession(
     const remoteTask = activeRemoteTasks.get(id);
     if (!meta || meta.status !== "running" || meta.remote?.session !== "tmux" || !remoteTask) return;
     const poll = await remoteTask.pollTmuxSession(meta.remote.logOffset ?? 0, remainingDeadlineMs(meta.deadlineAt));
+    if (scheduledWorkSuspended) return;
     appendTaskOutput(meta.logPath, poll.output);
     if (poll.status === "timed_out") {
       clearProcessTimeout(id);
@@ -280,7 +354,7 @@ async function pollRemoteSession(
     }
     const commandResult = { ...poll.commandResult, exitCode: poll.status, stdout: poll.output };
     latest.lastExitCode = poll.status;
-    if (poll.status !== 0) recordFailure(latest, "execution", `Remote command exited with code ${poll.status}`, "exit", { category: "exit" });
+    if (poll.status !== 0) recordExitFailure(latest, "execution", `Remote command exited with code ${poll.status}`, poll.status, "exit");
     else recoverFailure(latest, "execution", "exit");
     finalize(latest, {
       status: poll.status === 0 ? "succeeded" : "failed",
@@ -326,6 +400,7 @@ export function startWatchTask(
     const error = condition && validateCondition(condition);
     if (error) throw new Error(`${name}: ${error}`);
   }
+  const intent = readTaskIntent(params);
   const sandboxPlan = resolveForegroundSandboxPlan(pi, !!params.ssh);
   const id = nextTaskId();
   const cwd = params.cwd ?? defaultCwd;
@@ -371,6 +446,7 @@ export function startWatchTask(
     notifyOn: "terminal",
     ssh: remoteTask?.metadata.ssh,
     remote: remoteTask?.metadata.remote,
+    ...intent,
   };
   ensureTaskDir(id);
   appendLine(meta.logPath, `--- watch ${new Date(now).toISOString()} interval_ms=${meta.intervalMs} ---`);
@@ -399,6 +475,9 @@ export function resumeRunningTask(
   }
   scheduleFailureAttention(pi, meta.id, getActiveSession);
 
+  // Same Pi process: an earlier (reloaded or switched-away) extension instance may
+  // still hold this task's child or in-flight remote work and record its result.
+  const ownedByThisProcess = meta.spawnPid === process.pid && meta.spawnPidStartTime === currentProcessStartToken();
   if (meta.spawnPid !== process.pid || meta.spawnPidStartTime !== currentProcessStartToken()) {
     meta.spawnPid = process.pid;
     meta.spawnPidStartTime = currentProcessStartToken();
@@ -418,22 +497,86 @@ export function resumeRunningTask(
     activeRemoteTasks.set(meta.id, remoteTask);
     scheduleRemoteSessionPoll(pi, meta.id, 0, getActiveSession);
     if (meta.deadlineAt) scheduleProcessTimeout(pi, meta.id, meta.deadlineAt, getActiveSession);
+    // An earlier instance's in-flight timeout kill may still finalize it.
+    if (ownedByThisProcess) scheduleHandoff(pi, meta.id, getActiveSession);
     return meta;
   }
-  if (meta.pid && !processExists(meta.pid)) {
-    meta.status = "failed";
-    meta.endedAt = Date.now();
-    meta.error = "process is no longer alive; exit result was not captured by this pi session";
-    meta.result = { reason: meta.error };
-    recordFailure(meta, "execution", meta.error, "lost", { incomplete: true });
-    writeMeta(meta);
-    void notifyTerminal(pi, meta, getActiveSession);
+  if (ownedByThisProcess) {
+    // A dead pid is not yet "lost" here: the earlier instance's close listener may
+    // still record the real exit. The handoff marks it lost after a grace period.
+    scheduleHandoff(pi, meta.id, getActiveSession, remoteTask);
+  } else if (meta.pid && !processExists(meta.pid)) {
+    markProcessLost(pi, meta, getActiveSession);
     return meta;
   }
   if (meta.deadlineAt) scheduleProcessTimeout(pi, meta.id, meta.deadlineAt, getActiveSession);
   return meta;
 }
 
+/**
+ * Watch a task whose driver may still be an earlier instance in this process: a
+ * local child's close listener, or a remote tmux launch that was mid-bootstrap.
+ * Deliver the completion once it is recorded terminal, and take over remote
+ * polling once the tmux session is recorded as started (#324).
+ */
+function scheduleHandoff(
+  pi: ExtensionAPI,
+  id: string,
+  getActiveSession?: ActiveSessionProvider,
+  remoteTask?: ResolvedSshRemoteTask,
+): void {
+  stopHandoff(id);
+  if (scheduledWorkSuspended) return;
+  let deadSince: number | undefined;
+  const timer = setInterval(() => {
+    const meta = readMeta(id);
+    if (!meta) {
+      stopHandoff(id);
+      return;
+    }
+    if (meta.status !== "running") {
+      stopHandoff(id);
+      clearProcessTimeout(id);
+      stopLogRetention(id);
+      void notifyTerminal(pi, meta, getActiveSession);
+      return;
+    }
+    if (meta.remote?.session === "tmux" && meta.remote.sessionStarted === true && remoteTask && !activeRemoteTasks.has(id)) {
+      stopHandoff(id);
+      activeRemoteTasks.set(id, remoteTask);
+      scheduleRemoteSessionPoll(pi, id, 0, getActiveSession);
+      return;
+    }
+    if (meta.remote?.session !== "tmux" && meta.pid && !processExists(meta.pid)) {
+      deadSince ??= Date.now();
+      if (Date.now() - deadSince >= HANDOFF_LOST_GRACE_MS) {
+        stopHandoff(id);
+        clearProcessTimeout(id);
+        stopLogRetention(id);
+        markProcessLost(pi, meta, getActiveSession);
+      }
+    }
+  }, HANDOFF_CHECK_MS);
+  timer.unref();
+  handoffTimers.set(id, timer);
+}
+
+function stopHandoff(id: string): void {
+  const timer = handoffTimers.get(id);
+  if (timer) clearInterval(timer);
+  handoffTimers.delete(id);
+}
+
+function markProcessLost(pi: ExtensionAPI, meta: BackgroundTaskMeta, getActiveSession?: ActiveSessionProvider): void {
+  meta.status = "failed";
+  meta.endedAt = Date.now();
+  meta.error = "process is no longer alive; exit result was not captured by this pi session";
+  meta.result = { reason: meta.error };
+  recordFailure(meta, "execution", meta.error, "lost", { incomplete: true });
+  writeMeta(meta);
+  void notifyTerminal(pi, meta, getActiveSession);
+}
+
 function resolvePersistedRemoteTask(
   meta: BackgroundTaskMeta,
   remoteRunner?: RemoteRunner,
@@ -550,6 +693,7 @@ function scheduleWatch(
   runOnce?: WatchPollRunner,
 ): void {
   clearWatchTimer(id);
+  if (scheduledWorkSuspended) return;
   const timer = setTimeout(() => void pollWatch(pi, id, getActiveSession, runOnce), delayMs);
   timer.unref();
   watcherTimers.set(id, timer);
@@ -581,6 +725,8 @@ async function pollWatch(
     const result = runOnce
       ? await runOnce(timeoutMs)
       : await runCommandOnce(commandSpecFromMeta(meta), undefined, timeoutMs);
+    // A poll that was in flight when the session shut down belongs to a stale instance.
+    if (scheduledWorkSuspended) return;
     appendWatchResult(meta.logPath, result);
     const latest = readMeta(id);
     if (!latest || latest.status !== "running") return;
@@ -604,8 +750,8 @@ async function pollWatch(
       const error = condition && validateCondition(condition);
       if (error) {
         latest.error = `${name}: ${error}`;
-        if (result.exitCode !== 0) recordFailure(latest, "watch-poll", `Watch poll exited with code ${result.exitCode ?? "unknown"}`, pollKey,
-          { category: "exit", at: result.endedAt });
+        if (result.exitCode !== 0) recordExitFailure(latest, "watch-poll", `Watch poll exited with code ${result.exitCode ?? "unknown"}`, result.exitCode, pollKey,
+          { at: result.endedAt });
         recordFailure(latest, name, latest.error, pollKey, { incomplete: true, at: result.endedAt });
         finalize(latest, { status: "failed", reason: latest.error, commandResult: result }, pi, getActiveSession);
         return;
@@ -628,8 +774,8 @@ async function pollWatch(
       success?.matched === true && latest.successWhen?.type === "exit_code";
     if (expectedPollExit) recoverFailure(latest, "watch-poll", pollKey, result.endedAt);
     if (transportFailure) recordFailure(latest, "watch-poll", transportFailure, pollKey, { category: "ssh", at: result.endedAt });
-    else if (result.exitCode !== 0) recordFailure(latest, "watch-poll", `Watch poll exited with code ${result.exitCode ?? "unknown"}`, pollKey,
-      { category: "exit", expected: expectedPollExit, at: result.endedAt });
+    else if (result.exitCode !== 0) recordExitFailure(latest, "watch-poll", `Watch poll exited with code ${result.exitCode ?? "unknown"}`, result.exitCode, pollKey,
+      { expected: expectedPollExit, at: result.endedAt });
     else recoverFailure(latest, "watch-poll", pollKey, result.endedAt);
     if (conditionErrors.length) latest.error = conditionErrors.join("; ");
     if (failure?.matched) {
@@ -692,6 +838,7 @@ function finalize(
 ): void {
   stopFailureAttention(meta.id);
   if (terminal.status === "timed_out") recordFailure(meta, "timeout", terminal.reason, "deadline", { category: "timeout" });
+  if (terminal.status === "succeeded") recoverDeclaredOperation(meta);
   meta.status = terminal.status;
   meta.endedAt = Date.now();
   meta.result = {
@@ -750,6 +897,7 @@ function scheduleProcessTimeout(
   getActiveSession?: ActiveSessionProvider,
 ): void {
   clearProcessTimeout(id);
+  if (scheduledWorkSuspended) return;
   const delay = Math.max(0, deadlineAt - Date.now());
   const timer = setTimeout(() => void timeoutProcess(pi, id, getActiveSession), delay);
   timer.unref();
@@ -839,6 +987,9 @@ async function notifyTerminal(
   meta: BackgroundTaskMeta,
   getActiveSession?: ActiveSessionProvider,
 ): Promise<void> {
+  // A suspended instance has no active session: delivering or suppressing here would
+  // be wrong either way. The instance that resumes the task delivers it (#324).
+  if (scheduledWorkSuspended) return;
   if (meta.callback === false || meta.callbackSentAt || meta.callbackSuppressedAt) return;
   const latest = readMeta(meta.id) ?? meta;
   if (latest.callback === false || latest.callbackSentAt || latest.callbackSuppressedAt) return;
@@ -858,7 +1009,11 @@ async function notifyTerminal(
     source: "background-task",
     id: latest.id,
     label,
-    status: pending ? `${latest.status}: ${pending.summary}` : latest.status,
+    // Lifecycle plus an attention count; the incident text rides failureRows
+    // with exact counts, so the status field is never a clipped summary (#323).
+    status: pending
+      ? `${latest.status}; ${pending.incidents.length} incident${pending.incidents.length === 1 ? "" : "s"} need${pending.incidents.length === 1 ? "s" : ""} attention`
+      : latest.status,
     detailTool: "bg_task_status",
     outcome: facts.outcome,
     failureRows: facts.failureRows,
@@ -939,6 +1094,7 @@ function launchArgvOf(commandSpec: CommandSpec, launchSpec: CommandSpec): string
 
 function scheduleLogRetention(id: string): void {
   stopLogRetention(id);
+  if (scheduledWorkSuspended) return;
   const timer = setInterval(() => {
     const meta = readMeta(id);
     if (!meta || meta.status !== "running" || meta.kind !== "process") {

package/src/sandbox.ts

@@ -32,8 +32,9 @@ import { baseDir } from "./registry.js";
 import { compileWritePolicy, maybeBuildSandboxCommand, type SandboxSeams } from "./shared-sandbox-core.js";
 
 type SandboxPermissions = {
-  projectFiles: "off" | "read" | "read-write";
-  outsideProject: "off" | "read" | "read-write";
+  /** `write` = read, create and overwrite in place; `read-write` = Write & delete. */
+  projectFiles: "off" | "read" | "write" | "read-write";
+  outsideProject: "off" | "read" | "write" | "read-write";
   storedCredentials: "off" | "read" | "read-write";
   commands: boolean;
   network: boolean;
@@ -160,10 +161,11 @@ function readPolicy(data: unknown): ForegroundSandboxPolicy | undefined {
 function readPermissions(value: unknown): ForegroundSandboxPolicy["permissions"] | undefined {
   if (!value || typeof value !== "object") return undefined;
   const p = value as Record<string, unknown>;
-  const access = (v: unknown) => v === "off" || v === "read" || v === "read-write";
+  const credential = (v: unknown) => v === "off" || v === "read" || v === "read-write";
+  const access = (v: unknown) => credential(v) || v === "write";
   if (typeof p.enabled !== "boolean" || typeof p.commands !== "boolean" ||
       typeof p.network !== "boolean" || !access(p.projectFiles) ||
-      !access(p.outsideProject) || !access(p.storedCredentials)) return undefined;
+      !access(p.outsideProject) || !credential(p.storedCredentials)) return undefined;
   return Object.freeze({
     enabled: p.enabled, commands: p.commands, network: p.network,
     projectFiles: p.projectFiles as SandboxPermissions["projectFiles"],

package/src/shared-callback-batcher.ts

@@ -102,7 +102,11 @@ const DEFAULT_WINDOW_MS = 100;
 const DEFAULT_RETRY_MS = 1_000;
 const MAX_LABEL_BYTES = 160;
 const MAX_ID_BYTES = 200;
-const MAX_STATUS_BYTES = 80;
+/**
+ * Status field bound. Long statuses keep whole `; `-separated notes and say
+ * how many were left out, instead of cutting mid-word (#323).
+ */
+const MAX_STATUS_BYTES = 160;
 const MAX_FAILURE_BYTES = 400;
 const MAX_DECISION_BYTES = 400;
 const encoder = new TextEncoder();
@@ -169,6 +173,33 @@ function boundedField(value: unknown, maxBytes: number): string {
   return `${clipUtf8Prefix(oneLine, Math.max(0, maxBytes - utf8ByteLength(ellipsis)))}${ellipsis}`;
 }
 
+/**
+ * The status field under MAX_STATUS_BYTES without losing meaning: the leading
+ * lifecycle note is always kept, later `; `-separated notes are kept whole
+ * while they fit, and anything left out is named with a count and the inspect
+ * tool rather than an ellipsis.
+ */
+function boundedStatus(value: unknown): string {
+  const status = String(value ?? "").replace(/\s+/g, " ").trim();
+  if (utf8ByteLength(status) <= MAX_STATUS_BYTES) return status;
+  const notes = status.split(/;\s+/).filter(Boolean);
+  const omission = (count: number) => ` (+${count} more status note${count === 1 ? "" : "s"}; see inspect)`;
+  const reserve = utf8ByteLength(omission(notes.length));
+  let kept = notes[0] ?? "";
+  if (utf8ByteLength(kept) + reserve > MAX_STATUS_BYTES) {
+    const suffix = " (clipped; see inspect)";
+    return `${clipUtf8Prefix(kept, MAX_STATUS_BYTES - utf8ByteLength(suffix))}${suffix}`;
+  }
+  let count = 1;
+  for (const note of notes.slice(1)) {
+    const next = `${kept}; ${note}`;
+    if (utf8ByteLength(next) + reserve > MAX_STATUS_BYTES) break;
+    kept = next;
+    count += 1;
+  }
+  return count < notes.length ? `${kept}${omission(notes.length - count)}` : kept;
+}
+
 function inspectFor(event: Pick<CallbackBatchEvent, "id" | "detailTool">): string {
   const id = boundedField(event.id, MAX_ID_BYTES);
   return event.detailTool === "bg_task_status"
@@ -232,7 +263,7 @@ function formatRow(event: CallbackBatchEvent, detailBytes = MAX_FAILURE_BYTES +
   const source = boundedField(event.source, 40);
   const id = boundedField(event.id, MAX_ID_BYTES);
   const label = boundedField(event.label, MAX_LABEL_BYTES);
-  const status = boundedField(event.status, MAX_STATUS_BYTES);
+  const status = boundedStatus(event.status);
   const inspect = inspectFor(event);
   const lines = [
     `- source=${source} | id=${id} | label=${JSON.stringify(label)} | status=${status} | inspect: ${inspect}`,
@@ -291,7 +322,7 @@ export function formatUrgentCallback(
   const target = event.inspectId ?? event.id;
   const id = boundedField(target, MAX_ID_BYTES);
   const label = boundedField(event.label, MAX_LABEL_BYTES);
-  const status = boundedField(event.status, MAX_STATUS_BYTES);
+  const status = boundedStatus(event.status);
   const tool = event.detailTool
     ?? (event.source === "background-task" ? "bg_task_status" : "subagent_result");
   const inspectTarget = tool === "bg_task_status" ? `bg_task_status id=${id}` : `subagent_result id=${JSON.stringify(id)}`;