agentbox-sdk 0.1.514 → 0.1.516

package/dist/{chunk-D33LRRN7.js → chunk-SERVEWIE.js}

@@ -2,7 +2,7 @@ import {
   createNormalizedEvent,
   normalizeRawAgentEvent,
   toAISDKStream
-} from "./chunk-775FIGGL.js";
+} from "./chunk-V4M4LPPT.js";
 import {
   AgentBoxError,
   AsyncQueue,
@@ -1857,6 +1857,9 @@ var BackgroundTaskTracker = class {
   wakeups = /* @__PURE__ */ new Map();
   // tool_use seen, tool_result not yet: a failed schedule adds nothing.
   pendingWakeups = /* @__PURE__ */ new Map();
+  // task_started seen while the command was still in the foreground, kept so
+  // a later "moved to the background" patch can name the task it promotes.
+  foreground = /* @__PURE__ */ new Map();
   afterResult = false;
   seenBackgroundWork = false;
   hasTaskSnapshot = false;
@@ -1878,6 +1881,20 @@ var BackgroundTaskTracker = class {
   hasSeenBackgroundWork() {
     return this.seenBackgroundWork;
   }
+  /**
+   * Prime a run that attaches to a parked harness with what was live when it
+   * was parked: that run never saw the work start, and would otherwise take
+   * its first `result` for the end of the run and tear the harness down.
+   * Snapshots and schedule events replayed afterwards supersede it.
+   */
+  restore(tasks) {
+    for (const task of tasks) {
+      if (!task.id) continue;
+      this.seenBackgroundWork = true;
+      if (task.type === "scheduled_wakeup") this.wakeups.set(task.id, task);
+      else this.tasks.set(task.id, { task, ambient: false });
+    }
+  }
   /** Feed one SDKMessage. Returns true when it started a follow-up turn. */
   ingest(message) {
     const m = asRecord2(message);
@@ -1916,6 +1933,7 @@ var BackgroundTaskTracker = class {
     switch (m.subtype) {
       case "background_tasks_changed":
         this.hasTaskSnapshot = true;
+        this.foreground.clear();
         this.tasks.clear();
         for (const entry of asArray(m.tasks)) {
           const task = asRecord2(entry);
@@ -1923,15 +1941,31 @@ var BackgroundTaskTracker = class {
         }
         return false;
       case "task_started":
-        if (!this.hasTaskSnapshot && m.is_backgrounded === true && !m.owned_by_subagent) this.addTask(m);
+        if (this.hasTaskSnapshot || m.owned_by_subagent) return false;
+        if (m.is_backgrounded === true) this.addTask(m);
+        else if (id) this.foreground.set(id, m);
         return false;
       case "task_notification":
-        if (!this.hasTaskSnapshot) this.tasks.delete(id);
+        if (!this.hasTaskSnapshot) {
+          this.tasks.delete(id);
+          this.foreground.delete(id);
+        }
         return false;
-      case "task_updated":
-        if (!this.hasTaskSnapshot && DONE_STATUSES.has(String(asRecord2(m.patch)?.status)))
+      case "task_updated": {
+        if (this.hasTaskSnapshot) return false;
+        const patch = asRecord2(m.patch);
+        if (DONE_STATUSES.has(String(patch?.status))) {
           this.tasks.delete(id);
+          this.foreground.delete(id);
+          return false;
+        }
+        const started = this.foreground.get(id);
+        if (patch?.is_backgrounded === true && started) {
+          this.foreground.delete(id);
+          this.addTask(started);
+        }
         return false;
+      }
       case "init":
         return this.startTurn();
       default:
@@ -2020,6 +2054,10 @@ var BackgroundWait = class {
     }
     this.grace ??= setTimeout(() => this.expire("grace"), this.graceMs);
   }
+  /** End the wait now on the host's request ({@link BackgroundWaitFinish}). */
+  finish() {
+    this.expire("finished");
+  }
   elapsedMs() {
     return Date.now() - this.startedAt;
   }
@@ -2028,9 +2066,23 @@ var BackgroundWait = class {
     clearTimeout(this.ceiling);
   }
 };
+var BackgroundWaitFinish = class {
+  requested = false;
+  wait;
+  request() {
+    this.requested = true;
+    this.wait?.finish();
+  }
+  /** Follow the run's current wait; a latched request ends a new one at once. */
+  watch(wait) {
+    this.wait = wait;
+    if (this.requested) wait?.finish();
+    return wait;
+  }
+};
 
 // src/agents/providers/claude-code.ts
-var DAEMON_PROTOCOL_VERSION = "8";
+var DAEMON_PROTOCOL_VERSION = "10";
 var DAEMON_PORT = 43180;
 var DAEMON_PATH = "/tmp/agentbox/claude-code/daemon.mjs";
 var DAEMON_LOG_PATH = "/tmp/agentbox/claude-code/daemon.log";
@@ -2040,7 +2092,11 @@ var DAEMON_READY_TIMEOUT_MS = 3e4;
 var DAEMON_READY_POLL_INTERVAL_MS = 250;
 function claudeConfigDir(options) {
   return path8.join(
-    agentboxRoot(AgentProvider.ClaudeCode, Boolean(options.sandbox), options.stateDirectory),
+    agentboxRoot(
+      AgentProvider.ClaudeCode,
+      Boolean(options.sandbox),
+      options.stateDirectory
+    ),
     ".claude"
   );
 }
@@ -2061,7 +2117,9 @@ function buildClaudeQueryOptions(params) {
   }
   const includeHookEvents = provider?.includeHookEvents ?? false;
   if (run.reasoning === "max" || run.reasoning === "ultra") {
-    throw new Error(`Reasoning effort "${run.reasoning}" is only supported by Codex.`);
+    throw new Error(
+      `Reasoning effort "${run.reasoning}" is only supported by Codex.`
+    );
   }
   const effort = provider?.ultracode ? "xhigh" : run.reasoning;
   return {
@@ -2072,7 +2130,10 @@ function buildClaudeQueryOptions(params) {
     ...params.request.options.configuration === "native" && provider?.fastMode !== void 0 ? { settings: { fastMode: provider.fastMode } } : {},
     ...params.request.options.configuration === "native" ? {
       settingSources: ["user", "project", "local"],
-      systemPrompt: { type: "preset", preset: "claude_code" }
+      systemPrompt: {
+        type: "preset",
+        preset: "claude_code"
+      }
     } : {},
     extraArgs,
     includePartialMessages: true,
@@ -2164,6 +2225,199 @@ function isAuthorized(req) {
 
 const liveRuns = new Map();
 
+// A parked run keeps its CLI, and the background work that CLI owns, alive
+// after the host settled the run and left. Its output is buffered until a
+// later run for the same session attaches through /start; a turn the CLI
+// starts on its own (a task finished, a schedule fired) wakes the host.
+const NDJSON_HEADERS = { "content-type": "application/x-ndjson", "transfer-encoding": "chunked", "x-daemon-version": VERSION };
+const PARK_BUFFER_LIMIT = 16 * 1024 * 1024;
+// A host may answer "busy" (non-2xx) for far longer than a fixed ladder: the
+// run that parked this work may still be finalizing, another job may hold the
+// task, a deploy may be rolling. Back off to WAKE_RETRY_CEILING_MS and then
+// keep asking for as long as the park lives \u2014 the park's own TTL is the bound,
+// not the ladder. A run attaching, or the park ending, stops the retries.
+const WAKE_RETRY_MS = [0, 1000, 2000, 4000, 8000, 16000, 30000, 60000];
+const WAKE_RETRY_CEILING_MS = 60000;
+
+function findParkedRun(sessionId) {
+  for (const run of liveRuns.values()) {
+    if (run.parked && !run.sink && run.sessionId === sessionId) return run;
+  }
+  return undefined;
+}
+
+// A run's own teardown. The liveRuns entry is only removed when it is still
+// ours: hosts reuse a runId across retry attempts, and a successor
+// registered while our CLI winds down must not be evicted by our exit.
+function releaseRun(run) {
+  clearInterval(run.heartbeat);
+  clearTimeout(run.parked?.timer);
+  run.parked = null;
+  run.clearPermissions();
+  if (liveRuns.get(run.id) === run) liveRuns.delete(run.id);
+  run.prompt.end();
+}
+
+// End the prompt so the CLI winds down with its background work.
+function endRun(run) {
+  releaseRun(run);
+  run.query?.interrupt().catch(() => {});
+}
+
+function writeFrame(run, message) {
+  const line = JSON.stringify(message) + "\\n";
+  if (run.sink && !run.sink.writableEnded) { run.sink.write(line); return; }
+  // Nobody is attached. Partial deltas are rebuilt from the final messages.
+  if (message.type === "stream_event") return;
+  // byteLength, not .length: JSON.stringify keeps non-ASCII verbatim, so
+  // UTF-16 units under-count the bytes this buffer actually holds.
+  const size = Buffer.byteLength(line);
+  if (run.bufferedBytes + size > PARK_BUFFER_LIMIT) {
+    // Out of room while nobody is attached. Keep what the CLI already
+    // produced and drop the rest rather than killing the CLI: the
+    // background work goes on, and the run that attaches learns from the
+    // notice that its transcript is incomplete. Turn accounting is
+    // unaffected \u2014 observeFrame counts results before we are called.
+    if (!run.bufferOverflowed) {
+      run.bufferOverflowed = true;
+      run.buffer.push(JSON.stringify({ _notice: "park_buffer_overflow" }) + "\\n");
+      if (run.parked) wakeHost(run);
+    }
+    return;
+  }
+  run.bufferedBytes += size;
+  run.buffer.push(line);
+}
+
+function attachSink(run, res) {
+  clearInterval(run.heartbeat);
+  run.sink = res;
+  // Heartbeat: write a blank NDJSON line every 15s so HTTPS proxies
+  // (Modal/Daytona tunnels, intermediate LBs) don't idle-kill the
+  // stream during long blocking tool calls (e.g. TaskOutput block:true).
+  // The host's parseNdjsonStream skips empty lines, so this is a no-op
+  // for consumers but keeps the underlying TCP stream warm.
+  run.heartbeat = setInterval(() => {
+    if (run.sink === res && !res.writableEnded) res.write("\\n");
+  }, 15000);
+  if (typeof run.heartbeat.unref === "function") run.heartbeat.unref();
+  // Host gone (settled, cancelled or crashed) \u2192 end the prompt so the CLI
+  // winds down instead of living on with its background work, unless the
+  // host parked the run first. Detected on the response: \`req\` emits
+  // "close" as soon as its body is consumed (Node >= 16), long before any
+  // disconnect, while the response only closes early when the socket dies
+  // before the stream finished.
+  res.on("close", () => {
+    if (run.sink !== res) return;
+    run.sink = null;
+    clearInterval(run.heartbeat);
+    if (run.parked) {
+      // The CLI survives, but a permission left outstanding would wedge it:
+      // nobody is attached to decide, and a blocked tool call never ends the
+      // turn, so the host would never be woken either. Decline without
+      // interrupting so the background work carries on.
+      run.declinePermissions();
+      return;
+    }
+    if (res.writableFinished) return;
+    run.clientGone = true;
+    endRun(run);
+  });
+}
+
+// Track turn boundaries so an attaching run knows how many results precede
+// its own, and so a turn nobody is watching wakes the host.
+function observeFrame(run, message) {
+  const state = message.type === "system" && message.subtype === "session_state_changed"
+    ? message.state : undefined;
+  const started = message.type === "system" &&
+    (message.subtype === "init" || state === "running");
+  if (started) run.turnActive = true;
+  // A turn ends at its result \u2014 but a turn that dies without one (a CLI
+  // error, a killed subagent) would otherwise leave turnActive stuck true
+  // and inflate the turn count adoptRun hands to the next run, which would
+  // then skip its own result. Idle means no turn is running, whatever the
+  // reason, so it clears the flag too.
+  if (message.type === "result" || state === "idle") run.turnActive = false;
+  if (message.type === "result" && !run.sink) run.bufferedResults++;
+  // Anything a parked, unattended CLI produces on its own is news for the
+  // host: the start of a turn, and equally the result of a turn that was
+  // already in flight when the park landed (whose start edge was consumed
+  // while the host was still attached, so it never announced itself).
+  if (run.parked && !run.sink && (started || message.type === "result")) {
+    wakeHost(run);
+  }
+}
+
+async function wakeHost(run) {
+  const parked = run.parked;
+  if (!parked || !parked.wakeUrl || parked.waking) return;
+  // A wake the host accepted stands until a run attaches. The job it started
+  // takes a while to boot its side, and every frame the CLI emits meanwhile
+  // calls us again \u2014 without this, one chatty turn is one POST per frame.
+  // Retry only once it is plain that no run is coming.
+  if (parked.wokeAt && Date.now() - parked.wokeAt < WAKE_RETRY_CEILING_MS) return;
+  parked.waking = true;
+  try {
+    for (let attempt = 0; ; attempt++) {
+      const delay = attempt < WAKE_RETRY_MS.length
+        ? WAKE_RETRY_MS[attempt]
+        : WAKE_RETRY_CEILING_MS;
+      if (delay) await new Promise((resolve) => setTimeout(resolve, delay));
+      // Attached or torn down meanwhile: someone is already listening, or
+      // the park's TTL ended it. Either way, stop asking.
+      if (run.parked !== parked || run.sink) return;
+      try {
+        const response = await fetch(parked.wakeUrl, {
+          method: "POST",
+          headers: { "content-type": "application/json", authorization: "Bearer " + parked.wakeToken },
+          body: JSON.stringify({ runId: run.id, sessionId: run.sessionId }),
+          signal: AbortSignal.timeout(10000),
+        });
+        if (response.ok) { parked.wokeAt = Date.now(); return; }
+      } catch {}
+    }
+  } finally {
+    parked.waking = false;
+  }
+}
+
+// A later run for a parked session takes the CLI over instead of starting a
+// second one on the same session: replay what was buffered, then stream.
+function adoptRun(run, res, runId, prompt, attachOnly, settings) {
+  const turns = run.bufferedResults + (run.turnActive ? 1 : 0);
+  res.writeHead(200, NDJSON_HEADERS);
+  // Nothing happened while parked: leave it for the wake that will.
+  if (attachOnly && turns === 0) {
+    res.end(JSON.stringify({ _notice: "no_parked_turn", sessionId: run.sessionId }) + "\\n");
+    return;
+  }
+  const parked = run.parked;
+  clearTimeout(parked.timer);
+  run.parked = null;
+  // The adopting run's permission settings govern its own turn: a CLI parked
+  // by a full-access run must not keep auto-approving once the task is back
+  // in ask or plan mode. An attach-only run sends no input of its own, so it
+  // leaves the settings of the turn already in flight alone.
+  if (settings) run.settings = settings;
+  liveRuns.delete(run.id);
+  run.id = runId;
+  liveRuns.set(runId, run);
+  attachSink(run, res);
+  // What is left of the background budget, so a run that adopts and parks
+  // again inherits the deadline instead of restarting it.
+  const budgetLeftMs = Number.isFinite(run.parkDeadline)
+    ? Math.max(0, run.parkDeadline - Date.now())
+    : null;
+  res.write(JSON.stringify({ _parked: { tasks: parked.tasks, turns, budgetLeftMs } }) + "\\n");
+  for (const line of run.buffer) res.write(line);
+  run.buffer = [];
+  run.bufferedBytes = 0;
+  run.bufferedResults = 0;
+  run.bufferOverflowed = false;
+  if (prompt) run.prompt.push(prompt);
+}
+
 // The SDK's default spawn does \`existsSync(pathToClaudeCodeExecutable)\`
 // before invoking child_process.spawn \u2014 that check fails on bare names
 // like "claude" because existsSync doesn't do PATH lookup. Resolve to an
@@ -2247,7 +2501,36 @@ async function handleStart(req, res, runId) {
     res.end(JSON.stringify({ error: String(e?.message ?? e) }));
     return;
   }
-  const { prompt, options } = body || {};
+  const { prompt, options, attach } = body || {};
+  const opts = { ...(options || {}) };
+  // Permission shaping belongs to the request, not to the CLI process that
+  // happens to serve it: read it before the adopt branch so a run taking over
+  // a parked CLI applies its own mode rather than inheriting the parking
+  // run's. The rest of \`opts\` configures the CLI at spawn and cannot change
+  // under a live query.
+  const settings = {
+    autoApprove: !!opts.autoApproveTools,
+    interactiveQuestions: !!opts.interactiveQuestions,
+    planning: opts.permissionMode === "plan",
+  };
+  delete opts.autoApproveTools;
+  delete opts.interactiveQuestions;
+  const parkedRun = opts.resume ? findParkedRun(opts.resume) : undefined;
+  if (parkedRun && opts.forkSession) {
+    // The conversation is being rewound: work started on the abandoned
+    // branch goes with it.
+    endRun(parkedRun);
+  } else if (parkedRun) {
+    adoptRun(parkedRun, res, runId, prompt, !!attach, attach ? undefined : settings);
+    return;
+  }
+  // An attach-only request streams the turn a parked CLI started on its own;
+  // without one there is nothing to run.
+  if (attach) {
+    res.writeHead(200, NDJSON_HEADERS);
+    res.end(JSON.stringify({ _notice: "no_parked_run", sessionId: opts.resume ?? "" }) + "\\n");
+    return;
+  }
   if (!prompt) {
     res.writeHead(400);
     res.end("missing prompt");
@@ -2257,70 +2540,63 @@ async function handleStart(req, res, runId) {
   const promptStream = createPromptStream();
   promptStream.push(prompt);
 
-  res.writeHead(200, {
-    "content-type": "application/x-ndjson",
-    "transfer-encoding": "chunked",
-    "x-daemon-version": VERSION,
-  });
-
-  // Heartbeat: write a blank NDJSON line every 15s so HTTPS proxies
-  // (Modal/Daytona tunnels, intermediate LBs) don't idle-kill the
-  // stream during long blocking tool calls (e.g. TaskOutput block:true).
-  // The host's parseNdjsonStream skips empty lines, so this is a no-op
-  // for consumers but keeps the underlying TCP stream warm.
-  const heartbeat = setInterval(() => {
-    if (!res.writableEnded) res.write("\\n");
-  }, 15000);
-  if (typeof heartbeat.unref === "function") heartbeat.unref();
+  res.writeHead(200, NDJSON_HEADERS);
 
-  const opts = { ...(options || {}) };
-  const autoApprove = !!opts.autoApproveTools;
-  delete opts.autoApproveTools;
-  const interactiveQuestions = !!opts.interactiveQuestions;
-  delete opts.interactiveQuestions;
-  let planning = opts.permissionMode === "plan";
   const permissions = new Map();
-  const clearPermissions = () => { for (const resolve of permissions.values()) resolve({ behavior: "deny", message: "Run ended", interrupt: true }); permissions.clear(); };
+  const denyAll = (response) => { for (const resolve of permissions.values()) resolve(response); permissions.clear(); };
+  const clearPermissions = () => denyAll({ behavior: "deny", message: "Run ended", interrupt: true });
+  // Nobody is attached to decide. Declining without \`interrupt\` lets the CLI
+  // report and carry on with its background work instead of blocking forever
+  // on a tool call \u2014 a blocked call never ends the turn, so the host would
+  // never be woken to answer it either.
+  const declinePermissions = () => denyAll({ behavior: "deny", message: "No user is attached to approve this request." });
   const canUseTool = async (toolName, input, context) => {
     const isQuestion = toolName === "AskUserQuestion";
     const isPlan = toolName === "ExitPlanMode";
+    const mode = run.settings;
     if (context.signal.aborted) return { behavior: "deny", message: "Run cancelled", interrupt: true };
-    if ((isQuestion || isPlan) && !interactiveQuestions) return { behavior: "deny", message: "No interactive user is available." };
-    if (!isQuestion && !isPlan && planning && toolName !== "EnterPlanMode") return { behavior: "deny", message: "Finish planning before requesting write access." };
-    if (!isQuestion && !isPlan && autoApprove) return { behavior: "allow", updatedInput: input };
+    if ((isQuestion || isPlan) && !mode.interactiveQuestions) return { behavior: "deny", message: "No interactive user is available." };
+    if (!isQuestion && !isPlan && mode.planning && toolName !== "EnterPlanMode") return { behavior: "deny", message: "Finish planning before requesting write access." };
+    if (!isQuestion && !isPlan && mode.autoApprove) return { behavior: "allow", updatedInput: input };
+    // Parked with nobody attached: there is no one to ask, and waiting would
+    // wedge the CLI out of reach of any wake.
+    if (run.parked && !run.sink) return { behavior: "deny", message: "No user is attached to approve this request." };
     return new Promise((resolve) => {
       const abort = () => { permissions.delete(context.toolUseID); resolve({ behavior: "deny", message: "Run cancelled", interrupt: true }); };
-      permissions.set(context.toolUseID, (response) => { context.signal.removeEventListener("abort", abort); if (isPlan && response.behavior === "allow") planning = false; resolve(response); });
+      permissions.set(context.toolUseID, (response) => { context.signal.removeEventListener("abort", abort); if (isPlan && response.behavior === "allow") run.settings.planning = false; resolve(response); });
       context.signal.addEventListener("abort", abort, { once: true });
-      res.write(JSON.stringify({ _permission: { requestId: context.toolUseID, toolName, input, title: context.title } }) + "\\n");
+      // Buffered while parked: the run that attaches answers it.
+      writeFrame(run, { _permission: { requestId: context.toolUseID, toolName, input, title: context.title } });
     });
   };
   opts.pathToClaudeCodeExecutable = resolveClaudeBinary(
     opts.pathToClaudeCodeExecutable,
   );
 
-  let queryHandle;
-  let clientGone = false;
-  // This run's own teardown. The liveRuns entry is only removed when it is
-  // still ours: hosts reuse a runId across retry attempts, and a successor
-  // registered while our CLI winds down must not be evicted by our exit.
-  const releaseRun = () => {
-    clearInterval(heartbeat);
-    clearPermissions();
-    if (liveRuns.get(runId)?.query === queryHandle) liveRuns.delete(runId);
-    promptStream.end();
+  const run = {
+    id: runId,
+    sessionId: opts.resume || opts.sessionId || "",
+    query: undefined,
+    prompt: promptStream,
+    permissions,
+    clearPermissions,
+    declinePermissions,
+    // Replaced by each run that adopts this CLI out of a park.
+    settings,
+    sink: null,
+    heartbeat: undefined,
+    clientGone: false,
+    parked: null,
+    // Absolute end of the background budget, carried across parks so a CLI
+    // that is adopted and parked again cannot extend its own ceiling.
+    parkDeadline: Infinity,
+    buffer: [],
+    bufferedBytes: 0,
+    bufferedResults: 0,
+    bufferOverflowed: false,
+    turnActive: false,
   };
-  // Host gone (settled, cancelled or crashed) \u2192 end the prompt so the CLI
-  // winds down instead of living on with its background work. Detected on
-  // the response: \`req\` emits "close" as soon as its body is consumed (Node
-  // >= 16), long before any disconnect, while the response only closes
-  // early when the socket dies before the stream finished.
-  res.on("close", () => {
-    if (res.writableFinished) return;
-    clientGone = true;
-    releaseRun();
-    queryHandle?.interrupt().catch(() => {});
-  });
+  attachSink(run, res);
 
   // Resume-if-exists gate. \`claude --resume <id>\` errors hard with "No
   // conversation found with session ID" when the local session jsonl is
@@ -2353,44 +2629,94 @@ async function handleStart(req, res, runId) {
   }
 
   // Nobody left to stream to: do not start a CLI for it.
-  if (clientGone) { res.end(); return; }
+  if (run.clientGone) { res.end(); return; }
   try {
-    queryHandle = query({
+    run.query = query({
       prompt: promptStream,
       options: {
         ...opts,
         canUseTool,
         hooks: { PreToolUse: [{ hooks: [async (input) => {
-          planning = input.permission_mode === "plan";
-          return interactiveQuestions && ["AskUserQuestion", "ExitPlanMode"].includes(input.tool_name)
+          run.settings.planning = input.permission_mode === "plan";
+          return run.settings.interactiveQuestions && ["AskUserQuestion", "ExitPlanMode"].includes(input.tool_name)
             ? { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "ask" } } : {};
         }] }] },
       },
     });
   } catch (e) {
-    clearInterval(heartbeat);
+    clearInterval(run.heartbeat);
     res.write(JSON.stringify({ _error: String(e?.message ?? e) }) + "\\n");
     res.end();
     return;
   }
 
-  liveRuns.set(runId, { query: queryHandle, prompt: promptStream, permissions });
+  liveRuns.set(runId, run);
 
   // Forward every SDKMessage, not just up to the first result: in
   // streaming-input mode the CLI keeps running after a turn ends and
   // re-prompts the model when background work finishes. The host decides
-  // when the run is over and disconnects (res "close" above), which ends
-  // the prompt and lets the CLI wind down.
+  // when the run is over and disconnects (the sink's "close"), which ends
+  // the prompt and lets the CLI wind down, or parks the run first, which
+  // keeps it. Frames go to whichever run is attached, else to the buffer.
   try {
-    for await (const message of queryHandle) {
-      res.write(JSON.stringify(message) + "\\n");
+    for await (const message of run.query) {
+      observeFrame(run, message);
+      writeFrame(run, message);
     }
   } catch (e) {
-    res.write(JSON.stringify({ _error: String(e?.message ?? e) }) + "\\n");
+    writeFrame(run, { _error: String(e?.message ?? e) });
   } finally {
-    releaseRun();
-    res.end();
+    const sink = run.sink;
+    releaseRun(run);
+    sink?.end();
+  }
+}
+
+// The host settled a run whose background work is still live and is about
+// to leave: keep the CLI instead of winding it down. \`tasks\` is what the
+// host saw live (handed back to the run that attaches), \`ttlMs\` what is
+// left of its background budget, so unattended work never outlives it.
+async function handlePark(req, res, runId) {
+  let body;
+  try { body = await readJsonBody(req); }
+  catch { res.writeHead(400); res.end(); return; }
+  const run = liveRuns.get(runId);
+  if (!run || !run.query || run.clientGone) {
+    res.writeHead(404, { "content-type": "application/json" });
+    res.end(JSON.stringify({ parked: false }));
+    return;
   }
+  clearTimeout(run.parked?.timer);
+  const parked = {
+    wakeUrl: /^https?:\\/\\//.test(String(body?.wakeUrl ?? "")) ? String(body.wakeUrl) : "",
+    wakeToken: String(body?.wakeToken ?? ""),
+    tasks: Array.isArray(body?.tasks) ? body.tasks : [],
+    waking: false,
+    wokeAt: 0,
+    timer: undefined,
+  };
+  // \`ttlMs: null\` is how the host says "no bound" (backgroundTaskTimeoutMs
+  // of Infinity). Number(null) is 0, so the raw value has to be typed \u2014
+  // coercing it would arm an immediate teardown for an unbounded park.
+  const ttlMs = body?.ttlMs;
+  const requested = typeof ttlMs === "number" && Number.isFinite(ttlMs) && ttlMs >= 0
+    ? ttlMs
+    : Infinity;
+  // Never past a deadline inherited from an earlier park: the ceiling bounds
+  // the work, not each park, so a CLI that is adopted and re-parked on every
+  // wake-up cannot hold the sandbox open forever.
+  run.parkDeadline = Math.min(
+    run.parkDeadline ?? Infinity,
+    requested === Infinity ? Infinity : Date.now() + requested,
+  );
+  if (Number.isFinite(run.parkDeadline)) {
+    const delay = Math.max(0, run.parkDeadline - Date.now());
+    parked.timer = setTimeout(() => { if (run.parked === parked) endRun(run); }, Math.min(delay, 2147483647));
+    if (typeof parked.timer.unref === "function") parked.timer.unref();
+  }
+  run.parked = parked;
+  res.writeHead(200, { "content-type": "application/json" });
+  res.end(JSON.stringify({ parked: true }));
 }
 
 async function handleSendMessage(req, res, runId) {
@@ -2423,6 +2749,14 @@ async function handleAbort(_req, res, runId) {
     res.end();
     return;
   }
+  // Stop means stop: a parked CLI kept for background work must not survive
+  // the abort and wake the host with a new turn after the user pressed it.
+  if (run.parked) {
+    endRun(run);
+    res.writeHead(204);
+    res.end();
+    return;
+  }
   await run.query.interrupt().catch(() => {});
   res.writeHead(204);
   res.end();
@@ -2431,9 +2765,9 @@ async function handleAbort(_req, res, runId) {
 async function handleDelete(_req, res, runId) {
   const run = liveRuns.get(runId);
   if (run) {
-    liveRuns.delete(runId);
-    run.prompt.end();
-    await run.query.interrupt().catch(() => {});
+    // Also drops a park: an explicit delete ends the background work too.
+    releaseRun(run);
+    await run.query?.interrupt().catch(() => {});
   }
   res.writeHead(204);
   res.end();
@@ -2472,6 +2806,10 @@ const server = http.createServer((req, res) => {
     handleAbort(req, res, decodeURIComponent(m[1]));
     return;
   }
+  if (req.method === "POST" && (m = url.match(/^\\/runs\\/([^/]+)\\/park$/))) {
+    handlePark(req, res, decodeURIComponent(m[1])).catch(() => { if (!res.headersSent) res.writeHead(400); res.end(); });
+    return;
+  }
   if (req.method === "DELETE" && (m = url.match(/^\\/runs\\/([^/]+)$/))) {
     handleDelete(req, res, decodeURIComponent(m[1]));
     return;
@@ -2724,7 +3062,16 @@ var ClaudeCodeAgentAdapter = class {
       };
       const mcpConfigJson = buildClaudeMcpConfig(options.mcps) ?? JSON.stringify({ mcpServers: {} }, null, 2);
       const artifacts = [
-        ...!sandbox ? [{ path: path8.join(target.layout.claudeDir, ".claude-plugin", "plugin.json"), content: JSON.stringify({ name: "agentbox", version: "1.0.0" }) }] : [],
+        ...!sandbox ? [
+          {
+            path: path8.join(
+              target.layout.claudeDir,
+              ".claude-plugin",
+              "plugin.json"
+            ),
+            content: JSON.stringify({ name: "agentbox", version: "1.0.0" })
+          }
+        ] : [],
         ...skillArtifacts,
         ...buildClaudeCommandArtifacts(options.commands, target.layout),
         ...buildClaudeSubagentArtifacts(options.subAgents, target.layout),
@@ -2790,7 +3137,8 @@ var ClaudeCodeAgentAdapter = class {
       env.ANTHROPIC_CUSTOM_HEADERS = env.ANTHROPIC_CUSTOM_HEADERS ? `${env.ANTHROPIC_CUSTOM_HEADERS}
 ${serialized}` : serialized;
     }
-    const inputParts = await time(
+    const attachOnly = request.run.resumeParked === true;
+    const inputParts = attachOnly ? [] : await time(
       debugClaude,
       "validateProviderUserInput",
       () => validateProviderUserInput(request.provider, request.run.input)
@@ -2814,13 +3162,15 @@ ${serialized}` : serialized;
     });
     const autoApproveTools = shouldAutoApproveClaudeTools(request.options);
     const requestBody = {
-      prompt: {
-        type: "user",
-        message: {
-          role: "user",
-          content: userContent
-        },
-        parent_tool_use_id: null
+      ...attachOnly ? { attach: true } : {
+        prompt: {
+          type: "user",
+          message: {
+            role: "user",
+            content: userContent
+          },
+          parent_tool_use_id: null
+        }
       },
       options: {
         ...sdkOptions,
@@ -2836,11 +3186,18 @@ ${serialized}` : serialized;
     const runUrl = `${baseUrl}/runs/${encodeURIComponent(request.runId)}`;
     const cleanup = async () => {
       try {
-        await fetch(`${runUrl}/abort`, { method: "POST", headers: authHeaders });
+        await fetch(`${runUrl}/abort`, {
+          method: "POST",
+          headers: authHeaders
+        });
       } catch {
       }
       try {
-        await fetch(runUrl, { method: "DELETE", headers: authHeaders, signal: AbortSignal.timeout(3e3) });
+        await fetch(runUrl, {
+          method: "DELETE",
+          headers: authHeaders,
+          signal: AbortSignal.timeout(3e3)
+        });
       } catch {
       }
       fetchAbort.abort();
@@ -2911,12 +3268,84 @@ ${serialized}` : serialized;
         const ask = control._permission;
         const isQuestion = ask.toolName === "AskUserQuestion";
         const isPlan = ask.toolName === "ExitPlanMode";
-        const answer = await sink.requestPermission({ type: "permission.requested", provider: request.provider, runId: request.runId, timestamp: (/* @__PURE__ */ new Date()).toISOString(), requestId: ask.requestId, kind: isQuestion ? "question" : isPlan ? "plan" : "tool", toolName: ask.toolName, title: isQuestion ? "Your input is needed" : isPlan ? "Review the plan" : ask.title ?? `Allow ${ask.toolName}?`, input: ask.input, ...isQuestion ? { questions: normalizeUserQuestions("claude-code", ask.input) } : {} });
-        const reply = await fetch(`${baseUrl}/runs/${encodeURIComponent(request.runId)}/permission`, { method: "POST", headers: { "content-type": "application/json", ...authHeaders }, signal: fetchAbort.signal, body: JSON.stringify({ requestId: ask.requestId, response: answer.decision === "allow" ? { behavior: "allow", updatedInput: isQuestion ? { ...ask.input, answers: questionReply("claude-code", ask.input, answer.answers ?? []) } : ask.input } : { behavior: "deny", message: "The user declined this request." } }) });
-        if (!reply.ok) throw new Error(`Claude permission response failed: ${reply.status}`);
+        const answer = await sink.requestPermission({
+          type: "permission.requested",
+          provider: request.provider,
+          runId: request.runId,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          requestId: ask.requestId,
+          kind: isQuestion ? "question" : isPlan ? "plan" : "tool",
+          toolName: ask.toolName,
+          title: isQuestion ? "Your input is needed" : isPlan ? "Review the plan" : ask.title ?? `Allow ${ask.toolName}?`,
+          input: ask.input,
+          ...isQuestion ? { questions: normalizeUserQuestions("claude-code", ask.input) } : {}
+        });
+        const reply = await fetch(
+          `${baseUrl}/runs/${encodeURIComponent(request.runId)}/permission`,
+          {
+            method: "POST",
+            headers: { "content-type": "application/json", ...authHeaders },
+            signal: fetchAbort.signal,
+            body: JSON.stringify({
+              requestId: ask.requestId,
+              response: answer.decision === "allow" ? {
+                behavior: "allow",
+                updatedInput: isQuestion ? {
+                  ...ask.input,
+                  answers: questionReply(
+                    "claude-code",
+                    ask.input,
+                    answer.answers ?? []
+                  )
+                } : ask.input
+              } : {
+                behavior: "deny",
+                message: "The user declined this request."
+              }
+            })
+          }
+        );
+        if (!reply.ok)
+          throw new Error(`Claude permission response failed: ${reply.status}`);
       }
     };
-    await consumeClaudeMessages(request, sink, permissionMessages(), executeStartedAt, cleanup, () => cancelled, {}, tracker);
+    const parking = request.options.provider?.parkBackgroundWork;
+    await consumeClaudeMessages(
+      request,
+      sink,
+      permissionMessages(),
+      executeStartedAt,
+      cleanup,
+      () => cancelled,
+      {
+        attachOnly,
+        ...parking ? {
+          // The daemon keeps the CLI once told to; only then may the stream be
+          // dropped without the wind-down that `cleanup` asks for.
+          park: async (tasks, ttlMs) => {
+            const response2 = await fetch(`${runUrl}/park`, {
+              method: "POST",
+              headers: {
+                "content-type": "application/json",
+                ...authHeaders
+              },
+              signal: AbortSignal.timeout(1e4),
+              body: JSON.stringify({
+                wakeUrl: parking.wakeUrl,
+                wakeToken: parking.wakeToken,
+                tasks,
+                ttlMs: Number.isFinite(ttlMs) ? ttlMs : null
+              })
+            });
+            return response2.ok && (await response2.json()).parked === true;
+          },
+          detach: async () => {
+            fetchAbort.abort();
+          }
+        } : {}
+      },
+      tracker
+    );
     return async () => void 0;
   }
   /**
@@ -2987,28 +3416,63 @@ async function consumeClaudeMessages(request, sink, messages, executeStartedAt,
   let lastTerminalReason;
   let lastIsError = false;
   const rawPayloads = [];
-  const timeoutMs = resolveBackgroundTaskTimeoutMs(request.options.backgroundTaskTimeoutMs);
+  const timeoutMs = resolveBackgroundTaskTimeoutMs(
+    request.options.backgroundTaskTimeoutMs
+  );
   const graceMs = wait.graceMs ?? BACKGROUND_TASK_GRACE_MS;
   let pendingWait;
   let waitedMs = 0;
   let expiry;
-  let lastTasksKey = JSON.stringify({ tasks: [], waiting: false });
-  const emitTasks = (tasks, waiting) => {
-    const key = JSON.stringify({ tasks, waiting });
+  const finishWait = new BackgroundWaitFinish();
+  sink.setFinishBackgroundWait?.(() => finishWait.request());
+  let parked = false;
+  let leave = cleanup;
+  let foreignResults = 0;
+  let nothingParked = false;
+  let lastTasksKey = JSON.stringify({
+    tasks: [],
+    waiting: false,
+    isParked: false
+  });
+  const emitTasks = (tasks, waiting, isParked = false) => {
+    const key = JSON.stringify({ tasks, waiting, isParked });
     if (key === lastTasksKey) return;
     lastTasksKey = key;
-    sink.emitEvent(createNormalizedEvent("background.tasks", { provider: request.provider, runId: request.runId }, { tasks, waiting }));
+    sink.emitEvent(
+      createNormalizedEvent(
+        "background.tasks",
+        { provider: request.provider, runId: request.runId },
+        { tasks, waiting, ...isParked ? { parked: true } : {} }
+      )
+    );
+  };
+  const budgetLeftMs = () => Math.max(0, timeoutMs - waitedMs - (pendingWait?.elapsedMs() ?? 0));
+  const tryPark = async () => {
+    const live = tracker.liveTasks();
+    const ttlMs = budgetLeftMs();
+    if (!wait.park || live.length === 0 || isAborted() || ttlMs <= 0)
+      return false;
+    parked = await wait.park(live, ttlMs).catch(() => false);
+    if (parked)
+      debugClaude(
+        "\u2605 parked the harness with %d background task(s); settling",
+        live.length
+      );
+    return parked;
   };
   const isAborted = () => wasCancelled() || lastTerminalReason === "aborted_streaming" || lastTerminalReason === "aborted_tools";
   const endWait = () => {
     if (!pendingWait) return;
     waitedMs += pendingWait.elapsedMs();
     pendingWait.clear();
-    pendingWait = void 0;
+    pendingWait = finishWait.watch(void 0);
   };
   const settleOnFailure = (error) => {
     if (!pendingWait || !sawResult || lastIsError) return false;
-    debugClaude("\u2605 transport failed during background wait; settling on the last result: %o", error);
+    debugClaude(
+      "\u2605 transport failed during background wait; settling on the last result: %o",
+      error
+    );
     expiry = "transport";
     return true;
   };
@@ -3026,7 +3490,8 @@ async function consumeClaudeMessages(request, sink, messages, executeStartedAt,
         break;
       }
       if ("reason" in step) {
-        expiry = step.reason;
+        if (!(step.reason === "finished" && await tryPark()))
+          expiry = step.reason;
         break;
       }
       if (step.result.done) break;
@@ -3038,7 +3503,28 @@ async function consumeClaudeMessages(request, sink, messages, executeStartedAt,
           if (!settleOnFailure(error)) throw error;
           break;
         }
+        if ("_parked" in ctrl) {
+          const info = ctrl._parked;
+          tracker.restore(Array.isArray(info?.tasks) ? info.tasks : []);
+          foreignResults = Math.max(
+            0,
+            Number(info?.turns ?? 0) - (wait.attachOnly ? 1 : 0)
+          );
+          const budgetLeft = info?.budgetLeftMs;
+          if (typeof budgetLeft === "number" && Number.isFinite(timeoutMs)) {
+            waitedMs = Math.max(0, timeoutMs - Math.max(0, budgetLeft));
+          }
+          debugClaude(
+            "\u2605 attached to a parked harness: %d task(s) live, %d earlier result(s)",
+            tracker.liveTasks().length,
+            foreignResults
+          );
+          emitTasks(tracker.liveTasks(), false);
+          continue;
+        }
         if ("_notice" in ctrl) {
+          if (ctrl._notice === "no_parked_run" || ctrl._notice === "no_parked_turn")
+            nothingParked = true;
           debugClaude("daemon notice: %o", ctrl);
           sink.emitRaw(
             toRawEvent(
@@ -3054,21 +3540,31 @@ async function consumeClaudeMessages(request, sink, messages, executeStartedAt,
       rawPayloads.push(message);
       sink.emitRaw(toRawEvent(request.runId, message, message.type));
       if (tracker.ingest(message) && pendingWait) {
-        debugClaude("\u2605 follow-up turn started; background wait over (%dms since execute start)", Date.now() - executeStartedAt);
+        debugClaude(
+          "\u2605 follow-up turn started; background wait over (%dms since execute start)",
+          Date.now() - executeStartedAt
+        );
         endWait();
       }
       emitTasks(tracker.liveTasks(), pendingWait !== void 0);
       const sessionState = message.type === "system" && message.subtype === "session_state_changed" ? message.state : void 0;
       if (sessionState) sawSessionState = true;
-      pendingWait?.setIdle(!sawSessionState && tracker.liveTasks().length === 0);
-      if (sessionState === "idle" && pendingWait && tracker.liveTasks().length === 0) break;
+      pendingWait?.setIdle(
+        !sawSessionState && tracker.liveTasks().length === 0
+      );
+      if (sessionState === "idle" && pendingWait && (tracker.liveTasks().length === 0 || await tryPark()))
+        break;
       if (message.type === "system") {
         const sub = message.subtype;
         if (sub === "init") {
           const sys = message;
-          if (request.run.goal && !sys.slash_commands.some((command) => command.replace(/^\//, "") === "goal")) {
+          if (request.run.goal && !sys.slash_commands.some(
+            (command) => command.replace(/^\//, "") === "goal"
+          )) {
             await cleanup();
-            throw new Error("This Claude Code installation does not expose the native /goal command.");
+            throw new Error(
+              "This Claude Code installation does not expose the native /goal command."
+            );
           }
           if (sys.session_id) {
             debugClaude(
@@ -3170,6 +3666,12 @@ async function consumeClaudeMessages(request, sink, messages, executeStartedAt,
         continue;
       }
       if (message.type === "result") {
+        if (foreignResults > 0) {
+          foreignResults--;
+          accumulatedText = "";
+          streamedThinkingChars = 0;
+          continue;
+        }
         sawResult = true;
         const result = message;
         lastTerminalReason = result.terminal_reason;
@@ -3179,30 +3681,55 @@ async function consumeClaudeMessages(request, sink, messages, executeStartedAt,
           accumulatedText = resultText;
         }
         const live = tracker.liveTasks();
-        if (timeoutMs === 0 || !tracker.hasSeenBackgroundWork() || isAborted()) break;
-        debugClaude("\u2605 turn ended with %d background task(s); waiting", live.length);
+        if (timeoutMs === 0 || !tracker.hasSeenBackgroundWork() || isAborted())
+          break;
+        debugClaude(
+          "\u2605 turn ended with %d background task(s); waiting",
+          live.length
+        );
         endWait();
-        pendingWait = new BackgroundWait(graceMs, Math.max(0, timeoutMs - waitedMs));
+        pendingWait = finishWait.watch(
+          new BackgroundWait(graceMs, Math.max(0, timeoutMs - waitedMs))
+        );
         pendingWait.setIdle(!sawSessionState && live.length === 0);
         emitTasks(live, true);
         continue;
       }
     }
-    if (expiry === "ceiling") {
+    if (expiry === "ceiling" || expiry === "finished") {
       const ids = tracker.liveTasks().filter((task) => task.type !== "scheduled_wakeup").map((task) => task.id);
-      debugClaude("\u2605 background wait ceiling (%dms) hit; stopping %d task(s)", timeoutMs, ids.length);
+      if (expiry === "ceiling")
+        debugClaude(
+          "\u2605 background wait ceiling (%dms) hit; stopping %d task(s)",
+          timeoutMs,
+          ids.length
+        );
+      else
+        debugClaude(
+          "\u2605 host finished the background wait; stopping %d task(s)",
+          ids.length
+        );
       if (wait.stopTasks) {
-        await withTimeout(wait.stopTasks(ids), wait.stopTimeoutMs ?? STOP_TASKS_TIMEOUT_MS).catch(() => void 0);
+        await withTimeout(
+          wait.stopTasks(ids),
+          wait.stopTimeoutMs ?? STOP_TASKS_TIMEOUT_MS
+        ).catch(() => void 0);
       }
     } else if (expiry === "grace") {
       debugClaude("\u2605 background set emptied with no follow-up turn; settling");
     }
     if (pendingWait) {
       endWait();
-      emitTasks([], false);
-    }
-    await cleanup();
-    if (!sawResult && !wasCancelled()) throw new Error("Claude Code closed before reporting a result");
+      if (parked) emitTasks(tracker.liveTasks(), false, true);
+      else emitTasks([], false);
+    }
+    if (parked && wait.detach) {
+      await wait.detach();
+      leave = wait.detach;
+    } else await cleanup();
+    if (nothingParked && !sawResult) sawResult = true;
+    if (!sawResult && !wasCancelled())
+      throw new Error("Claude Code closed before reporting a result");
     const finalText = accumulatedText;
     const isCancelled = isAborted();
     const isError = !isCancelled && lastIsError;
@@ -3242,18 +3769,25 @@ async function consumeClaudeMessages(request, sink, messages, executeStartedAt,
       );
       sink.complete({
         text: finalText,
-        costData: extractClaudeCostData(rawPayloads)
+        costData: extractClaudeCostData(rawPayloads),
+        // Told, not guessed: an attach that found nothing parked ran no turn
+        // at all, which from the outside looks exactly like a real tool-only
+        // turn that produced no answer text and no usage.
+        ...nothingParked ? { nothingParked: true } : {}
       });
     }
   } finally {
     pendingWait?.clear();
-    await cleanup();
+    await leave();
   }
 }
 async function executeNativeClaude(request, sink, wait = {}) {
   const { query } = await import("@anthropic-ai/claude-agent-sdk");
   const claudeDir = claudeConfigDir(request.options);
-  const input = await validateProviderUserInput(request.provider, request.run.input);
+  const input = await validateProviderUserInput(
+    request.provider,
+    request.run.input
+  );
   const prompt = new AsyncQueue();
   const sessionId = request.run.resumeSessionId ?? randomUUID();
   const controller = new AbortController();
@@ -3274,13 +3808,30 @@ async function executeNativeClaude(request, sink, wait = {}) {
   });
   sink.setSessionId(sessionId);
   const messageId = randomUUID();
-  prompt.push({ type: "user", uuid: messageId, message: { role: "user", content: mapToClaudeUserContent(input) }, parent_tool_use_id: null });
-  const hostEnv = Object.fromEntries(Object.entries({ ...process.env, ...request.options.env }).filter((entry) => entry[1] !== void 0));
+  prompt.push({
+    type: "user",
+    uuid: messageId,
+    message: {
+      role: "user",
+      content: mapToClaudeUserContent(
+        input
+      )
+    },
+    parent_tool_use_id: null
+  });
+  const hostEnv = Object.fromEntries(
+    Object.entries({ ...process.env, ...request.options.env }).filter(
+      (entry) => entry[1] !== void 0
+    )
+  );
   applyCliBackgroundWaitCeiling(hostEnv);
   hostEnv.CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS ??= "1";
   if (request.options.customHeaders) {
     const headers = Object.entries(request.options.customHeaders).map(([name, value]) => `${name}: ${value}`).join("\n");
-    hostEnv.ANTHROPIC_CUSTOM_HEADERS = [hostEnv.ANTHROPIC_CUSTOM_HEADERS, headers].filter(Boolean).join("\n");
+    hostEnv.ANTHROPIC_CUSTOM_HEADERS = [
+      hostEnv.ANTHROPIC_CUSTOM_HEADERS,
+      headers
+    ].filter(Boolean).join("\n");
   }
   const options = buildClaudeQueryOptions({
     request,
@@ -3296,71 +3847,143 @@ async function executeNativeClaude(request, sink, wait = {}) {
   const interactiveQuestions = hasInteractiveQuestions(request.options);
   let planning = options.permissionMode === "plan";
   try {
-    handle = query({ prompt, options: {
-      ...options,
-      // Use the SDK-matched CLI by default; an installed CLI is an explicit override.
-      pathToClaudeCodeExecutable: request.options.provider?.binary,
-      abortController: controller,
-      // `sessionId` is rejected alongside `resume` unless `forkSession` is
-      // set, where it names the forked session. Stamping it on forks keeps
-      // the pre-minted id reported via `sink.setSessionId` truthful, so a
-      // later run can resume the fork.
-      ...request.run.resumeSessionId ? {} : { sessionId },
-      ...request.options.configuration === "native" ? {} : { plugins: [{ type: "local", path: claudeDir }] },
-      spawnClaudeCodeProcess(spawnOptions) {
-        if (cancelled || controller.signal.aborted) throw new Error("Local run was cancelled before startup");
-        processHandle = spawnCommand({ ...spawnOptions, processGroup: request.options.processGroup !== "inherited" });
-        return processHandle.child;
-      },
-      hooks: { ...options.hooks, PreToolUse: [...options.hooks?.PreToolUse ?? [], { hooks: [async (input2) => {
-        if (input2.hook_event_name !== "PreToolUse") return {};
-        planning = input2.permission_mode === "plan";
-        return interactiveQuestions && ["AskUserQuestion", "ExitPlanMode"].includes(input2.tool_name) ? { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "ask" } } : {};
-      }] }] },
-      async canUseTool(toolName, input2, context) {
-        if (cancelled || context.signal.aborted) return { behavior: "deny", message: "Run cancelled", interrupt: true };
-        const isQuestion = toolName === "AskUserQuestion";
-        const isPlan = toolName === "ExitPlanMode";
-        if ((isQuestion || isPlan) && !interactiveQuestions) return { behavior: "deny", message: "No interactive user is available." };
-        if (!isQuestion && !isPlan && planning && toolName !== "EnterPlanMode") return { behavior: "deny", message: "Finish planning before requesting write access." };
-        if (!isQuestion && !isPlan && autoApprove) return { behavior: "allow", updatedInput: input2 };
-        try {
-          const response = await sink.requestPermission({
-            type: "permission.requested",
-            provider: request.provider,
-            runId: request.runId,
-            timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-            requestId: context.toolUseID,
-            kind: isQuestion ? "question" : isPlan ? "plan" : "tool",
-            toolName,
-            ...isQuestion ? { questions: normalizeUserQuestions("claude-code", input2) } : {},
-            title: isQuestion ? "Your input is needed" : isPlan ? "Review the plan" : context.title ?? `Allow ${toolName}?`,
-            message: context.description ?? context.decisionReason,
-            input: input2,
-            canRemember: false
+    handle = query({
+      prompt,
+      options: {
+        ...options,
+        // Use the SDK-matched CLI by default; an installed CLI is an explicit override.
+        pathToClaudeCodeExecutable: request.options.provider?.binary,
+        abortController: controller,
+        // `sessionId` is rejected alongside `resume` unless `forkSession` is
+        // set, where it names the forked session. Stamping it on forks keeps
+        // the pre-minted id reported via `sink.setSessionId` truthful, so a
+        // later run can resume the fork.
+        ...request.run.resumeSessionId ? {} : { sessionId },
+        ...request.options.configuration === "native" ? {} : { plugins: [{ type: "local", path: claudeDir }] },
+        spawnClaudeCodeProcess(spawnOptions) {
+          if (cancelled || controller.signal.aborted)
+            throw new Error("Local run was cancelled before startup");
+          processHandle = spawnCommand({
+            ...spawnOptions,
+            processGroup: request.options.processGroup !== "inherited"
           });
-          if (isPlan && response.decision === "allow") planning = false;
-          if (!cancelled && !context.signal.aborted && response.decision === "allow") return {
-            behavior: "allow",
-            updatedInput: isQuestion ? { ...input2, answers: questionReply("claude-code", input2, response.answers ?? []) } : input2
-          };
-          return { behavior: "deny", message: "The user denied this action" };
-        } catch {
-          return { behavior: "deny", message: "Run cancelled", interrupt: true };
+          return processHandle.child;
+        },
+        hooks: {
+          ...options.hooks,
+          PreToolUse: [
+            ...options.hooks?.PreToolUse ?? [],
+            {
+              hooks: [
+                async (input2) => {
+                  if (input2.hook_event_name !== "PreToolUse") return {};
+                  planning = input2.permission_mode === "plan";
+                  return interactiveQuestions && ["AskUserQuestion", "ExitPlanMode"].includes(
+                    input2.tool_name
+                  ) ? {
+                    hookSpecificOutput: {
+                      hookEventName: "PreToolUse",
+                      permissionDecision: "ask"
+                    }
+                  } : {};
+                }
+              ]
+            }
+          ]
+        },
+        async canUseTool(toolName, input2, context) {
+          if (cancelled || context.signal.aborted)
+            return {
+              behavior: "deny",
+              message: "Run cancelled",
+              interrupt: true
+            };
+          const isQuestion = toolName === "AskUserQuestion";
+          const isPlan = toolName === "ExitPlanMode";
+          if ((isQuestion || isPlan) && !interactiveQuestions)
+            return {
+              behavior: "deny",
+              message: "No interactive user is available."
+            };
+          if (!isQuestion && !isPlan && planning && toolName !== "EnterPlanMode")
+            return {
+              behavior: "deny",
+              message: "Finish planning before requesting write access."
+            };
+          if (!isQuestion && !isPlan && autoApprove)
+            return { behavior: "allow", updatedInput: input2 };
+          try {
+            const response = await sink.requestPermission({
+              type: "permission.requested",
+              provider: request.provider,
+              runId: request.runId,
+              timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+              requestId: context.toolUseID,
+              kind: isQuestion ? "question" : isPlan ? "plan" : "tool",
+              toolName,
+              ...isQuestion ? { questions: normalizeUserQuestions("claude-code", input2) } : {},
+              title: isQuestion ? "Your input is needed" : isPlan ? "Review the plan" : context.title ?? `Allow ${toolName}?`,
+              message: context.description ?? context.decisionReason,
+              input: input2,
+              canRemember: false
+            });
+            if (isPlan && response.decision === "allow") planning = false;
+            if (!cancelled && !context.signal.aborted && response.decision === "allow")
+              return {
+                behavior: "allow",
+                updatedInput: isQuestion ? {
+                  ...input2,
+                  answers: questionReply(
+                    "claude-code",
+                    input2,
+                    response.answers ?? []
+                  )
+                } : input2
+              };
+            return { behavior: "deny", message: "The user denied this action" };
+          } catch {
+            return {
+              behavior: "deny",
+              message: "Run cancelled",
+              interrupt: true
+            };
+          }
         }
       }
-    } });
+    });
     const live = handle;
     sink.setRaw({ query: live, claudeDir, runId: request.runId });
-    sink.emitEvent(createNormalizedEvent("run.started", { provider: request.provider, runId: request.runId }));
-    sink.emitEvent(createNormalizedEvent("message.started", { provider: request.provider, runId: request.runId }, { messageId }));
-    await consumeClaudeMessages(request, sink, live, Date.now(), stop, () => cancelled, {
-      ...wait,
-      // Native owns the CLI: ask it to stop leftover tasks before closing it.
-      stopTasks: async (ids) => {
-        await Promise.all(ids.map((id) => live.stopTask(id).catch(() => void 0)));
-      }
-    }, tracker);
+    sink.emitEvent(
+      createNormalizedEvent("run.started", {
+        provider: request.provider,
+        runId: request.runId
+      })
+    );
+    sink.emitEvent(
+      createNormalizedEvent(
+        "message.started",
+        { provider: request.provider, runId: request.runId },
+        { messageId }
+      )
+    );
+    await consumeClaudeMessages(
+      request,
+      sink,
+      live,
+      Date.now(),
+      stop,
+      () => cancelled,
+      {
+        ...wait,
+        // Native owns the CLI: ask it to stop leftover tasks before closing it.
+        stopTasks: async (ids) => {
+          await Promise.all(
+            ids.map((id) => live.stopTask(id).catch(() => void 0))
+          );
+        }
+      },
+      tracker
+    );
   } catch (error) {
     await stop();
     if (cancelled) sink.cancel();
@@ -4623,6 +5246,8 @@ var CodexAgentAdapter = class {
     const isRootThread = (params) => !params?.threadId || params.threadId === rootThreadId;
     let goalStatus = request.run.goal ? "active" : void 0;
     let pendingWait;
+    const finishWait = new BackgroundWaitFinish();
+    sink.setFinishBackgroundWait?.(() => finishWait.request());
     let waitedMs = 0;
     let turnMessageText = "";
     let lastTurn;
@@ -4636,7 +5261,7 @@ var CodexAgentAdapter = class {
       if (!pendingWait) return;
       waitedMs += pendingWait.elapsedMs();
       pendingWait.clear();
-      pendingWait = void 0;
+      pendingWait = finishWait.watch(void 0);
       emitGoalWaiting(false);
     };
     const completion = new Promise((resolve, reject) => {
@@ -4807,7 +5432,7 @@ var CodexAgentAdapter = class {
             }
             debugCodex("\u2605 turn ended with an active goal; waiting for native continuation");
             endWait();
-            pendingWait = new BackgroundWait(BACKGROUND_TASK_GRACE_MS, Math.max(0, timeoutMs - waitedMs));
+            pendingWait = finishWait.watch(new BackgroundWait(BACKGROUND_TASK_GRACE_MS, Math.max(0, timeoutMs - waitedMs)));
             pendingWait.setIdle(true);
             emitGoalWaiting(true);
           }
@@ -5665,6 +6290,8 @@ var OpenCodeAgentAdapter = class {
     let pendingWait;
     let waitedMs = 0;
     let expiry;
+    const finishWait = new BackgroundWaitFinish();
+    sink.setFinishBackgroundWait?.(() => finishWait.request());
     let sawParentIdle = false;
     let lastTasksKey = JSON.stringify({ tasks: [], waiting: false });
     const emitTasks = (tasks, waiting) => {
@@ -5683,7 +6310,7 @@ var OpenCodeAgentAdapter = class {
       if (!pendingWait) return;
       waitedMs += pendingWait.elapsedMs();
       pendingWait.clear();
-      pendingWait = void 0;
+      pendingWait = finishWait.watch(void 0);
     };
     const onChildrenChanged = () => {
       if (!pendingWait) return;
@@ -5751,6 +6378,7 @@ var OpenCodeAgentAdapter = class {
         expiry = reason;
         resolveSessionTerminal();
       });
+      finishWait.watch(wait);
       emitTasks(live, true);
     };
     const onParentBusy = () => {
@@ -6224,7 +6852,7 @@ var OpenCodeAgentAdapter = class {
       }
       sseAbort.abort();
       await sseTask;
-      if (expiry === "ceiling" || (sessionErrorFromSse || dispatchError) && liveChildren().length > 0) {
+      if (expiry === "ceiling" || expiry === "finished" || (sessionErrorFromSse || dispatchError) && liveChildren().length > 0) {
         debugOpencode(
           "\u2605 run over (%s) with %d subagent(s) live; aborting them",
           expiry ?? "failure",
@@ -6457,6 +7085,8 @@ var AgentRunController = class {
   sessionIdReady;
   abortHandler = async () => void 0;
   abortRequested = false;
+  finishBackgroundWaitHandler;
+  finishBackgroundWaitRequested = false;
   eventQueue = new AsyncQueue();
   rawQueue = new AsyncQueue();
   events = [];
@@ -6498,6 +7128,12 @@ var AgentRunController = class {
       void abort();
     }
   }
+  setFinishBackgroundWait(finish) {
+    this.finishBackgroundWaitHandler = finish;
+    if (this.finishBackgroundWaitRequested) {
+      finish();
+    }
+  }
   setSessionId(sessionId) {
     if (this.sessionId) {
       return;
@@ -6614,6 +7250,7 @@ var AgentRunController = class {
       return;
     }
     this.settled = true;
+    const nothingParked = result?.nothingParked === true;
     this.clearPendingPermissions(
       new Error(
         "Agent run completed before pending permission requests resolved."
@@ -6639,7 +7276,8 @@ var AgentRunController = class {
         events: [...this.events],
         costData: this.costData,
         isCancelled: false,
-        error: errorMsg
+        error: errorMsg,
+        ...nothingParked ? { nothingParked: true } : {}
       });
       return;
     }
@@ -6651,7 +7289,8 @@ var AgentRunController = class {
       rawEvents: [...this.rawEventsList],
       events: [...this.events],
       costData: this.costData,
-      isCancelled: false
+      isCancelled: false,
+      ...nothingParked ? { nothingParked: true } : {}
     });
   }
   cancel(result) {
@@ -6735,6 +7374,10 @@ var AgentRunController = class {
     this.clearPendingPermissions(new Error("Agent run cancelled"));
     await this.abortHandler();
   }
+  async finishBackgroundWait() {
+    this.finishBackgroundWaitRequested = true;
+    this.finishBackgroundWaitHandler?.();
+  }
   rawEvents() {
     return this.rawQueue;
   }
@@ -6848,6 +7491,14 @@ var Agent = class {
     if (runConfig.forkAtMessageId && !runConfig.forkSessionId) {
       throw new Error("AgentRunConfig.forkAtMessageId requires forkSessionId.");
     }
+    if (runConfig.resumeParked) {
+      if (this.provider !== AgentProvider.ClaudeCode || !this.options.sandbox) {
+        throw new Error("AgentRunConfig.resumeParked is only supported for claude-code sandbox runs.");
+      }
+      if (!runConfig.resumeSessionId) {
+        throw new Error("AgentRunConfig.resumeParked requires resumeSessionId.");
+      }
+    }
     const runId = runConfig.runId ?? randomUUID3();
     const streamCalledAt = Date.now();
     debugAgent("stream() provider=%s runId=%s", this.provider, runId);