@opencow-ai/opencow-agent-sdk 0.4.18 → 0.4.19

package/dist/client.js

@@ -234734,18 +234734,74 @@ var init_registerFrontmatterHooks = __esm(() => {
 });
 
 // src/session/backgroundAbortRegistry.ts
-function registerBackgroundAgentAbort(agentId, controller) {
-  runs.set(agentId, { controller, stopFired: false });
+function registerBackgroundAgentAbort(agentId, actions) {
+  if (runs.has(agentId)) {
+    throw new Error(`Background agent '${agentId}' is already registered`);
+  }
+  let resolveSettled = () => {};
+  const settled = new Promise((resolve15) => {
+    resolveSettled = resolve15;
+  });
+  runs.set(agentId, {
+    ...actions,
+    stopFired: false,
+    stopPromise: undefined,
+    settled,
+    resolveSettled,
+    shellsStopped: false
+  });
 }
 function unregisterBackgroundAgentAbort(agentId) {
+  const run = runs.get(agentId);
+  if (!run)
+    return;
   runs.delete(agentId);
+  run.resolveSettled();
 }
 function abortBackgroundAgentById(agentId) {
   const run = runs.get(agentId);
   if (!run)
-    return false;
-  run.controller.abort();
-  return true;
+    return Promise.resolve();
+  if (!run.stopPromise) {
+    run.stopPromise = (async () => {
+      const errors4 = [];
+      let abortFailed = false;
+      try {
+        run.abort();
+      } catch (error41) {
+        abortFailed = true;
+        errors4.push(error41);
+      }
+      try {
+        stopBackgroundAgentShells(run);
+      } catch (error41) {
+        errors4.push(error41);
+      }
+      if (abortFailed) {
+        throw new AggregateError(errors4, `Failed to stop background agent '${agentId}'`);
+      }
+      await run.settled;
+      if (errors4.length > 0) {
+        throw new AggregateError(errors4, `Failed to stop background agent '${agentId}'`);
+      }
+    })();
+  }
+  return run.stopPromise;
+}
+function hasBackgroundAgent(agentId) {
+  return runs.has(agentId);
+}
+function stopBackgroundAgentShellsById(agentId) {
+  const run = runs.get(agentId);
+  if (run) {
+    stopBackgroundAgentShells(run);
+  }
+}
+function stopBackgroundAgentShells(run) {
+  if (run.shellsStopped)
+    return;
+  run.shellsStopped = true;
+  run.stopShells();
 }
 function markSubagentStopFired(agentId) {
   const run = runs.get(agentId);
@@ -235703,6 +235759,23 @@ var init_formatting = __esm(() => {
   init_xml();
 });
 
+// src/capabilities/tools/AgentTool/agentLifecycleFinalizer.ts
+function createAgentLifecycleFinalizer(onCleanupError) {
+  let finalization;
+  return (cleanups) => {
+    finalization ??= (async () => {
+      for (const cleanup of cleanups) {
+        try {
+          await cleanup();
+        } catch (error41) {
+          onCleanupError(error41);
+        }
+      }
+    })();
+    return finalization;
+  };
+}
+
 // src/capabilities/tools/AgentTool/runAgent.ts
 import { randomUUID as randomUUID6 } from "crypto";
 async function initializeAgentMcpServers(agentDefinition, parentClients) {
@@ -235725,44 +235798,6 @@ async function initializeAgentMcpServers(agentDefinition, parentClients) {
   const agentClients = [];
   const newlyCreatedClients = [];
   const agentTools = [];
-  for (const spec of agentDefinition.mcpServers) {
-    let config2 = null;
-    let name;
-    let isNewlyCreated = false;
-    if (typeof spec === "string") {
-      name = spec;
-      config2 = getMcpConfigByName(spec);
-      if (!config2) {
-        logForDebugging(`[Agent: ${agentDefinition.agentType}] MCP server not found: ${spec}`, { level: "warn" });
-        continue;
-      }
-    } else {
-      const entries = Object.entries(spec);
-      if (entries.length !== 1) {
-        logForDebugging(`[Agent: ${agentDefinition.agentType}] Invalid MCP server spec: expected exactly one key`, { level: "warn" });
-        continue;
-      }
-      const [serverName, serverConfig] = entries[0];
-      name = serverName;
-      config2 = {
-        ...serverConfig,
-        scope: "dynamic"
-      };
-      isNewlyCreated = true;
-    }
-    const client = await connectToServer(name, config2);
-    agentClients.push(client);
-    if (isNewlyCreated) {
-      newlyCreatedClients.push(client);
-    }
-    if (client.type === "connected") {
-      const tools = await fetchToolsForClient(client);
-      agentTools.push(...tools);
-      logForDebugging(`[Agent: ${agentDefinition.agentType}] Connected to MCP server '${name}' with ${tools.length} tools`);
-    } else {
-      logForDebugging(`[Agent: ${agentDefinition.agentType}] Failed to connect to MCP server '${name}': ${client.type}`, { level: "warn" });
-    }
-  }
   const cleanup = async () => {
     for (const client of newlyCreatedClients) {
       if (client.type === "connected") {
@@ -235774,6 +235809,49 @@ async function initializeAgentMcpServers(agentDefinition, parentClients) {
       }
     }
   };
+  try {
+    for (const spec of agentDefinition.mcpServers) {
+      let config2 = null;
+      let name;
+      let isNewlyCreated = false;
+      if (typeof spec === "string") {
+        name = spec;
+        config2 = getMcpConfigByName(spec);
+        if (!config2) {
+          logForDebugging(`[Agent: ${agentDefinition.agentType}] MCP server not found: ${spec}`, { level: "warn" });
+          continue;
+        }
+      } else {
+        const entries = Object.entries(spec);
+        if (entries.length !== 1) {
+          logForDebugging(`[Agent: ${agentDefinition.agentType}] Invalid MCP server spec: expected exactly one key`, { level: "warn" });
+          continue;
+        }
+        const [serverName, serverConfig] = entries[0];
+        name = serverName;
+        config2 = {
+          ...serverConfig,
+          scope: "dynamic"
+        };
+        isNewlyCreated = true;
+      }
+      const client = await connectToServer(name, config2);
+      agentClients.push(client);
+      if (isNewlyCreated) {
+        newlyCreatedClients.push(client);
+      }
+      if (client.type === "connected") {
+        const tools = await fetchToolsForClient(client);
+        agentTools.push(...tools);
+        logForDebugging(`[Agent: ${agentDefinition.agentType}] Connected to MCP server '${name}' with ${tools.length} tools`);
+      } else {
+        logForDebugging(`[Agent: ${agentDefinition.agentType}] Failed to connect to MCP server '${name}': ${client.type}`, { level: "warn" });
+      }
+    }
+  } catch (error41) {
+    await cleanup();
+    throw error41;
+  }
   return {
     clients: [...parentClients, ...agentClients],
     tools: agentTools,
@@ -235926,121 +236004,140 @@ async function* runAgent({
   const additionalWorkingDirectories = Array.from(appState.toolPermissionContext.additionalWorkingDirectories.keys());
   const agentSystemPrompt = override?.systemPrompt ? override.systemPrompt : asSystemPrompt(await getAgentSystemPrompt(agentDefinition, toolUseContext, resolvedAgentModel, additionalWorkingDirectories, resolvedTools));
   const agentAbortController = override?.abortController ? override.abortController : isAsync2 ? new AbortController : toolUseContext.abortController;
+  const stopOwnedShells = () => {
+    killShellTasksForAgent(agentId, toolUseContext.getAppState, rootSetAppState);
+  };
   if (isAsync2) {
-    registerBackgroundAgentAbort(agentId, agentAbortController);
-  }
-  const additionalContexts = [];
-  for await (const hookResult of executeSubagentStartHooks(agentId, agentDefinition.agentType, agentAbortController.signal, undefined, toolUseContext.toolUseId, isAsync2)) {
-    if (hookResult.additionalContexts && hookResult.additionalContexts.length > 0) {
-      additionalContexts.push(...hookResult.additionalContexts);
-    }
+    registerBackgroundAgentAbort(agentId, {
+      abort: () => {
+        killAsyncAgent(agentId, rootSetAppState);
+        if (!agentAbortController.signal.aborted) {
+          agentAbortController.abort();
+        }
+      },
+      stopShells: stopOwnedShells
+    });
   }
-  if (additionalContexts.length > 0) {
-    const contextMessage = createAttachmentMessage({
-      type: "hook_additional_context",
-      content: additionalContexts,
-      hookName: "SubagentStart",
-      toolUseID: randomUUID6(),
-      hookEvent: "SubagentStart"
+  let agentToolRuntimeContext;
+  let mcpCleanup = async () => {};
+  let lastAssistantForFallback = null;
+  let agentRunError;
+  const finalizeLifecycle = createAgentLifecycleFinalizer((error41) => {
+    logForDebugging(`Agent ${agentId} cleanup failed: ${error41}`, {
+      level: "warn"
     });
-    initialMessages.push(contextMessage);
-  }
-  const hooksAllowedForThisAgent = !isRestrictedToPluginOnly("hooks") || isSourceAdminTrusted(agentDefinition.source);
-  if (agentDefinition.hooks && hooksAllowedForThisAgent) {
-    registerFrontmatterHooks(rootSetAppState, agentId, agentDefinition.hooks, `agent '${agentDefinition.agentType}'`, true);
-  }
-  const skillsToPreload = agentDefinition.skills ?? [];
-  if (skillsToPreload.length > 0) {
-    const allSkills = await getSkillToolCommands(getProjectRoot());
-    const validSkills = [];
-    for (const skillName of skillsToPreload) {
-      const resolvedName = resolveSkillName(skillName, allSkills, agentDefinition);
-      if (!resolvedName) {
-        logForDebugging(`[Agent: ${agentDefinition.agentType}] Warning: Skill '${skillName}' specified in frontmatter was not found`, { level: "warn" });
-        continue;
-      }
-      const skill = getCommand(resolvedName, allSkills);
-      if (skill.type !== "prompt") {
-        logForDebugging(`[Agent: ${agentDefinition.agentType}] Warning: Skill '${skillName}' is not a prompt-based skill`, { level: "warn" });
-        continue;
+  });
+  try {
+    const additionalContexts = [];
+    for await (const hookResult of executeSubagentStartHooks(agentId, agentDefinition.agentType, agentAbortController.signal, undefined, toolUseContext.toolUseId, isAsync2)) {
+      if (hookResult.additionalContexts && hookResult.additionalContexts.length > 0) {
+        additionalContexts.push(...hookResult.additionalContexts);
       }
-      validSkills.push({ skillName, skill });
     }
-    const loaded = await Promise.all(validSkills.map(async ({ skillName, skill }) => ({
-      skillName,
-      skill,
-      content: await skill.getPromptForCommand("", toolUseContext)
-    })));
-    for (const { skillName, skill, content } of loaded) {
-      logForDebugging(`[Agent: ${agentDefinition.agentType}] Preloaded skill '${skillName}'`);
-      const metadata = formatSkillLoadingMetadata(skillName, skill.progressMessage);
-      initialMessages.push(createUserMessage({
-        content: [{ type: "text", text: metadata }, ...content],
-        isMeta: true
-      }));
+    if (additionalContexts.length > 0) {
+      const contextMessage = createAttachmentMessage({
+        type: "hook_additional_context",
+        content: additionalContexts,
+        hookName: "SubagentStart",
+        toolUseID: randomUUID6(),
+        hookEvent: "SubagentStart"
+      });
+      initialMessages.push(contextMessage);
+    }
+    const hooksAllowedForThisAgent = !isRestrictedToPluginOnly("hooks") || isSourceAdminTrusted(agentDefinition.source);
+    if (agentDefinition.hooks && hooksAllowedForThisAgent) {
+      registerFrontmatterHooks(rootSetAppState, agentId, agentDefinition.hooks, `agent '${agentDefinition.agentType}'`, true);
+    }
+    const skillsToPreload = agentDefinition.skills ?? [];
+    if (skillsToPreload.length > 0) {
+      const allSkills = await getSkillToolCommands(getProjectRoot());
+      const validSkills = [];
+      for (const skillName of skillsToPreload) {
+        const resolvedName = resolveSkillName(skillName, allSkills, agentDefinition);
+        if (!resolvedName) {
+          logForDebugging(`[Agent: ${agentDefinition.agentType}] Warning: Skill '${skillName}' specified in frontmatter was not found`, { level: "warn" });
+          continue;
+        }
+        const skill = getCommand(resolvedName, allSkills);
+        if (skill.type !== "prompt") {
+          logForDebugging(`[Agent: ${agentDefinition.agentType}] Warning: Skill '${skillName}' is not a prompt-based skill`, { level: "warn" });
+          continue;
+        }
+        validSkills.push({ skillName, skill });
+      }
+      const loaded = await Promise.all(validSkills.map(async ({ skillName, skill }) => ({
+        skillName,
+        skill,
+        content: await skill.getPromptForCommand("", toolUseContext)
+      })));
+      for (const { skillName, skill, content } of loaded) {
+        logForDebugging(`[Agent: ${agentDefinition.agentType}] Preloaded skill '${skillName}'`);
+        const metadata = formatSkillLoadingMetadata(skillName, skill.progressMessage);
+        initialMessages.push(createUserMessage({
+          content: [{ type: "text", text: metadata }, ...content],
+          isMeta: true
+        }));
+      }
     }
-  }
-  const {
-    clients: mergedMcpClients,
-    tools: agentMcpTools,
-    cleanup: mcpCleanup
-  } = await initializeAgentMcpServers(agentDefinition, toolUseContext.options.mcpClients);
-  const allTools = agentMcpTools.length > 0 ? uniqBy_default([...resolvedTools, ...agentMcpTools], "name") : resolvedTools;
-  const agentOptions = {
-    isNonInteractiveSession: useExactTools ? toolUseContext.options.isNonInteractiveSession : isAsync2 ? true : toolUseContext.options.isNonInteractiveSession ?? false,
-    appendSystemPrompt: toolUseContext.options.appendSystemPrompt,
-    tools: allTools,
-    commands: [],
-    debug: toolUseContext.options.debug,
-    verbose: toolUseContext.options.verbose,
-    mainLoopModel: effectiveModel,
-    providerOverride: providerOverride ?? undefined,
-    thinkingConfig: toolUseContext.options.thinkingConfig,
-    mcpClients: mergedMcpClients,
-    mcpResources: toolUseContext.options.mcpResources,
-    agentDefinitions: toolUseContext.options.agentDefinitions,
-    subagentDisallowedTools: toolUseContext.options.subagentDisallowedTools,
-    ...useExactTools && { querySource }
-  };
-  const agentToolRuntimeContext = createSubagentContext(toolUseContext, {
-    options: agentOptions,
-    agentId,
-    agentType: agentDefinition.agentType,
-    messages: initialMessages,
-    readFileState: agentReadFileState,
-    abortController: agentAbortController,
-    getAppState: agentGetAppState,
-    shareSetAppState: !isAsync2,
-    shareSetResponseLength: true,
-    criticalSystemReminder_EXPERIMENTAL: agentDefinition.criticalSystemReminder_EXPERIMENTAL,
-    contentReplacementState
-  });
-  if (preserveToolUseResults) {
-    agentToolRuntimeContext.preserveToolUseResults = true;
-  }
-  if (onCacheSafeParams) {
-    onCacheSafeParams({
-      systemPrompt: agentSystemPrompt,
-      userContext: resolvedUserContext,
-      systemContext: resolvedSystemContext,
-      toolUseContext: agentToolRuntimeContext,
-      forkContextMessages: initialMessages
+    const mcp = await initializeAgentMcpServers(agentDefinition, toolUseContext.options.mcpClients);
+    const {
+      clients: mergedMcpClients,
+      tools: agentMcpTools
+    } = mcp;
+    mcpCleanup = mcp.cleanup;
+    const allTools = agentMcpTools.length > 0 ? uniqBy_default([...resolvedTools, ...agentMcpTools], "name") : resolvedTools;
+    const agentOptions = {
+      isNonInteractiveSession: useExactTools ? toolUseContext.options.isNonInteractiveSession : isAsync2 ? true : toolUseContext.options.isNonInteractiveSession ?? false,
+      appendSystemPrompt: toolUseContext.options.appendSystemPrompt,
+      tools: allTools,
+      commands: [],
+      debug: toolUseContext.options.debug,
+      verbose: toolUseContext.options.verbose,
+      mainLoopModel: effectiveModel,
+      providerOverride: providerOverride ?? undefined,
+      thinkingConfig: toolUseContext.options.thinkingConfig,
+      mcpClients: mergedMcpClients,
+      mcpResources: toolUseContext.options.mcpResources,
+      agentDefinitions: toolUseContext.options.agentDefinitions,
+      subagentDisallowedTools: toolUseContext.options.subagentDisallowedTools,
+      ...useExactTools && { querySource }
+    };
+    agentToolRuntimeContext = createSubagentContext(toolUseContext, {
+      options: agentOptions,
+      agentId,
+      agentType: agentDefinition.agentType,
+      messages: initialMessages,
+      readFileState: agentReadFileState,
+      abortController: agentAbortController,
+      getAppState: agentGetAppState,
+      shareSetAppState: !isAsync2,
+      shareSetResponseLength: true,
+      criticalSystemReminder_EXPERIMENTAL: agentDefinition.criticalSystemReminder_EXPERIMENTAL,
+      contentReplacementState
     });
-  }
-  recordSidechainTranscript(initialMessages, agentId).catch((_err) => logForDebugging(`Failed to record sidechain transcript: ${_err}`));
-  writeAgentMetadata(agentId, {
-    agentType: agentDefinition.agentType,
-    ...worktreePath && { worktreePath },
-    ...description && { description }
-  }).catch((_err) => logForDebugging(`Failed to write agent metadata: ${_err}`));
-  let lastRecordedUuid = initialMessages.at(-1)?.uuid ?? null;
-  let partialBaseMessage = null;
-  const partialTextByIndex = new Map;
-  const PARTIAL_PROGRESS_HOOK_INTERVAL_MS = 100;
-  let lastPartialProgressHookAt = 0;
-  let lastAssistantForFallback = null;
-  let agentRunError;
-  try {
+    if (preserveToolUseResults) {
+      agentToolRuntimeContext.preserveToolUseResults = true;
+    }
+    if (onCacheSafeParams) {
+      onCacheSafeParams({
+        systemPrompt: agentSystemPrompt,
+        userContext: resolvedUserContext,
+        systemContext: resolvedSystemContext,
+        toolUseContext: agentToolRuntimeContext,
+        forkContextMessages: initialMessages
+      });
+    }
+    recordSidechainTranscript(initialMessages, agentId).catch((_err) => logForDebugging(`Failed to record sidechain transcript: ${_err}`));
+    writeAgentMetadata(agentId, {
+      agentType: agentDefinition.agentType,
+      ...worktreePath && { worktreePath },
+      ...description && { description }
+    }).catch((_err) => logForDebugging(`Failed to write agent metadata: ${_err}`));
+    let lastRecordedUuid = initialMessages.at(-1)?.uuid ?? null;
+    let partialBaseMessage = null;
+    const partialTextByIndex = new Map;
+    const PARTIAL_PROGRESS_HOOK_INTERVAL_MS = 100;
+    let lastPartialProgressHookAt = 0;
     for await (const message of query({
       messages: initialMessages,
       systemPrompt: agentSystemPrompt,
@@ -236130,43 +236227,65 @@ async function* runAgent({
     agentRunError = err2;
     throw err2;
   } finally {
-    const naturalStopAlreadyFired = isAsync2 && hasSubagentStopFired(agentId);
-    if (isAsync2) {
-      unregisterBackgroundAgentAbort(agentId);
-    }
-    if (isAsync2 && agentRunError !== undefined) {
-      logForDebugging(`Background agent ${agentId} crashed: ${errorMessage(agentRunError)}
+    await finalizeLifecycle([
+      async () => {
+        const naturalStopAlreadyFired = isAsync2 && hasSubagentStopFired(agentId);
+        if (isAsync2 && agentRunError !== undefined) {
+          logForDebugging(`Background agent ${agentId} crashed: ${errorMessage(agentRunError)}
 ${agentRunError instanceof Error ? agentRunError.stack ?? "" : ""}`, { level: "error" });
-    }
-    if (isAsync2 && !naturalStopAlreadyFired) {
-      try {
-        const fallbackAppState = agentToolRuntimeContext.getAppState();
-        const terminal = agentAbortController.signal.aborted ? { status: "stopped" } : agentRunError !== undefined ? { status: "failed", errorMessage: errorMessage(agentRunError) } : { status: "completed" };
-        const fallbackStop = executeStopHooks(fallbackAppState.toolPermissionContext.mode, undefined, undefined, false, agentId, agentToolRuntimeContext, lastAssistantForFallback ? [lastAssistantForFallback] : undefined, agentDefinition.agentType, undefined, terminal);
-        for await (const evt of fallbackStop) {}
-      } catch (err2) {
-        logForDebugging(`Fallback SubagentStop failed for ${agentId}: ${err2}`, {
-          level: "warn"
+        }
+        if (isAsync2 && !naturalStopAlreadyFired) {
+          try {
+            const terminalContext = agentToolRuntimeContext ?? toolUseContext;
+            const fallbackAppState = terminalContext.getAppState();
+            const terminal = agentAbortController.signal.aborted ? { status: "stopped" } : agentRunError !== undefined ? { status: "failed", errorMessage: errorMessage(agentRunError) } : { status: "completed" };
+            const fallbackStop = executeStopHooks(fallbackAppState.toolPermissionContext.mode, undefined, undefined, false, agentId, terminalContext, lastAssistantForFallback ? [lastAssistantForFallback] : undefined, agentDefinition.agentType, undefined, terminal);
+            for await (const evt of fallbackStop) {}
+          } catch (err2) {
+            logForDebugging(`Fallback SubagentStop failed for ${agentId}: ${err2}`, {
+              level: "warn"
+            });
+          }
+        }
+      },
+      mcpCleanup,
+      () => {
+        if (agentDefinition.hooks) {
+          clearSessionHooks(rootSetAppState, agentId);
+        }
+      },
+      () => {
+        if (false) {}
+      },
+      () => agentToolRuntimeContext?.readFileState.clear(),
+      () => {
+        initialMessages.length = 0;
+      },
+      () => unregisterAgent(agentId),
+      () => clearAgentTranscriptSubdir(agentId),
+      () => {
+        rootSetAppState((prev) => {
+          if (!(agentId in prev.todos))
+            return prev;
+          const { [agentId]: _removed, ...todos } = prev.todos;
+          return { ...prev, todos };
         });
+      },
+      () => {
+        if (isAsync2) {
+          stopBackgroundAgentShellsById(agentId);
+        } else {
+          stopOwnedShells();
+        }
+      },
+      () => {
+        if (false) {}
+      },
+      () => {
+        if (isAsync2)
+          unregisterBackgroundAgentAbort(agentId);
       }
-    }
-    await mcpCleanup();
-    if (agentDefinition.hooks) {
-      clearSessionHooks(rootSetAppState, agentId);
-    }
-    if (false) {}
-    agentToolRuntimeContext.readFileState.clear();
-    initialMessages.length = 0;
-    unregisterAgent(agentId);
-    clearAgentTranscriptSubdir(agentId);
-    rootSetAppState((prev) => {
-      if (!(agentId in prev.todos))
-        return prev;
-      const { [agentId]: _removed, ...todos } = prev.todos;
-      return { ...prev, todos };
-    });
-    killShellTasksForAgent(agentId, toolUseContext.getAppState, rootSetAppState);
-    if (false) {}
+    ]);
   }
 }
 function filterIncompleteToolCalls(messages) {
@@ -236238,6 +236357,7 @@ var init_runAgent = __esm(() => {
   init_config5();
   init_permissions2();
   init_killShellTasks();
+  init_LocalAgentTask();
   init_attachments();
   init_errors5();
   init_file();
@@ -257722,6 +257842,75 @@ var init_LocalAgentTask = __esm(() => {
   backgroundSignalResolvers = new Map;
 });
 
+// src/session/backgroundTaskScope.ts
+class BackgroundTaskScope {
+  tasks = new Set;
+  stopPromise;
+  stopped = false;
+  register(task) {
+    let registered = true;
+    const unregister = () => {
+      if (!registered)
+        return;
+      registered = false;
+      this.tasks.delete(task);
+    };
+    this.tasks.add(task);
+    task.settled.then(unregister, unregister);
+    if (this.stopped) {
+      this.stopTask(task).finally(unregister).catch(() => {});
+    }
+    return unregister;
+  }
+  stop() {
+    if (!this.stopPromise) {
+      this.stopPromise = this.drain().finally(() => {
+        this.stopped = true;
+      });
+    }
+    return this.stopPromise;
+  }
+  async drain() {
+    const failures = [];
+    while (this.tasks.size > 0) {
+      const tasks = [...this.tasks];
+      const results = await Promise.allSettled(tasks.map((task) => this.stopTask(task)));
+      for (const result of results) {
+        if (result.status === "rejected")
+          failures.push(result.reason);
+      }
+      for (const task of tasks) {
+        this.tasks.delete(task);
+      }
+    }
+    if (failures.length > 0) {
+      throw new AggregateError(failures, "BackgroundTaskScope cleanup failed");
+    }
+  }
+  async stopTask(task) {
+    try {
+      await task.stop();
+    } finally {
+      await task.settled;
+    }
+  }
+}
+function bindBackgroundTaskScope(setAppState, scope) {
+  scopesBySetAppState.set(setAppState, scope);
+  return () => {
+    if (scopesBySetAppState.get(setAppState) === scope) {
+      scopesBySetAppState.delete(setAppState);
+    }
+  };
+}
+function getBackgroundTaskScope(setAppState) {
+  return scopesBySetAppState.get(setAppState);
+}
+var scopesBySetAppState;
+var init_backgroundTaskScope = __esm(() => {
+  scopesBySetAppState = new WeakMap;
+});
+
 // src/tasks/LocalShellTask/LocalShellTask.ts
 function looksLikePrompt(tail) {
   const lastLine = tail.trimEnd().split(`
@@ -257850,26 +258039,9 @@ async function spawnShellTask(input, context3) {
     taskOutput
   } = shellCommand;
   const taskId = taskOutput.taskId;
-  const unregisterCleanup = registerCleanup(async () => {
-    killTask(taskId, setAppState);
-  });
-  const taskState = {
-    ...createTaskStateBase(taskId, "local_bash", description, toolUseId),
-    type: "local_bash",
-    status: "running",
-    command,
-    completionStatusSentInAttachment: false,
-    shellCommand,
-    unregisterCleanup,
-    lastReportedTotalLines: 0,
-    isBackgrounded: true,
-    agentId,
-    kind
-  };
-  registerTask(taskState, setAppState);
-  shellCommand.background(taskId);
-  const cancelStallWatchdog = startStallWatchdog(taskId, description, kind, toolUseId, agentId);
-  shellCommand.result.then(async (result) => {
+  let unregisterCleanup = () => {};
+  let cancelStallWatchdog = () => {};
+  const settled = shellCommand.result.then(async (result) => {
     cancelStallWatchdog();
     await flushAndCleanup(shellCommand);
     let wasKilled = false;
@@ -257892,12 +258064,43 @@ async function spawnShellTask(input, context3) {
     });
     enqueueShellNotification(taskId, description, wasKilled ? "killed" : result.code === 0 ? "completed" : "failed", result.code, setAppState, toolUseId, kind, agentId);
     evictTaskOutput(taskId);
+  }).catch((error41) => {
+    cancelStallWatchdog();
+    logError(error41);
+  }).finally(() => {
+    unregisterCleanup();
   });
+  const stopAndSettle = async () => {
+    killTask(taskId, setAppState);
+    await settled;
+  };
+  const cleanupRegistration = () => {
+    unregisterCleanup();
+  };
+  const taskState = {
+    ...createTaskStateBase(taskId, "local_bash", description, toolUseId),
+    type: "local_bash",
+    status: "running",
+    command,
+    completionStatusSentInAttachment: false,
+    shellCommand,
+    unregisterCleanup: cleanupRegistration,
+    lastReportedTotalLines: 0,
+    isBackgrounded: true,
+    agentId,
+    kind
+  };
+  registerTask(taskState, setAppState);
+  const owner = getBackgroundTaskScope(setAppState);
+  unregisterCleanup = owner ? owner.register({
+    stop: stopAndSettle,
+    settled
+  }) : registerCleanup(stopAndSettle);
+  shellCommand.background(taskId);
+  cancelStallWatchdog = startStallWatchdog(taskId, description, kind, toolUseId, agentId);
   return {
     taskId,
-    cleanup: () => {
-      unregisterCleanup();
-    }
+    cleanup: cleanupRegistration
   };
 }
 function registerForeground(input, setAppState, toolUseId) {
@@ -258026,6 +258229,7 @@ var init_LocalShellTask = __esm(() => {
   init_LocalAgentTask();
   init_killShellTasks();
   init_fsOperations();
+  init_backgroundTaskScope();
   PROMPT_PATTERNS = [
     /\(y\/n\)/i,
     /\[y\/n\]/i,
@@ -280341,6 +280545,9 @@ async function checkPermissionsAndCallTool(tool, toolUseID, input, toolUseContex
       logError(hookError);
     }
   }
+  if (toolUseContext.abortController.signal.aborted) {
+    throw new AbortError;
+  }
   try {
     const result = await tool.call(callInput, {
       ...toolUseContext,
@@ -282618,7 +282825,7 @@ function getAnthropicEnvMetadata() {
 function getBuildAgeMinutes() {
   if (false)
     ;
-  const buildTime = new Date("2026-07-16T03:27:09.740Z").getTime();
+  const buildTime = new Date("2026-07-20T09:45:03.714Z").getTime();
   if (isNaN(buildTime))
     return;
   return Math.floor((Date.now() - buildTime) / 60000);
@@ -329467,8 +329674,9 @@ function registerSdkInlineSkillHandler() {
 }
 
 // src/session/sdkRuntime.ts
-init_LocalAgentTask();
 init_backgroundAbortRegistry();
+init_backgroundTaskScope();
+init_sessionStorage();
 init_hooks2();
 init_debug();
 init_errors5();
@@ -331711,7 +331919,8 @@ async function stopTask(taskId, context4) {
   const appState = getAppState();
   const task = appState.tasks?.[taskId];
   if (!task) {
-    if (abortBackgroundAgentById(taskId)) {
+    if (hasBackgroundAgent(taskId)) {
+      await abortBackgroundAgentById(taskId);
       return { taskId, taskType: "local_agent", command: undefined };
     }
     throw new StopTaskError(`No task found with ID: ${taskId}`, "not_found");
@@ -331723,7 +331932,11 @@ async function stopTask(taskId, context4) {
   if (!taskImpl) {
     throw new StopTaskError(`Unsupported task type: ${task.type}`, "unsupported_type");
   }
-  await taskImpl.kill(taskId, setAppState);
+  if (task.type === "local_agent" && hasBackgroundAgent(taskId)) {
+    await abortBackgroundAgentById(taskId);
+  } else {
+    await taskImpl.kill(taskId, setAppState);
+  }
   if (isLocalShellTask(task)) {
     let suppressed = false;
     setAppState((prev) => {
@@ -331765,6 +331978,7 @@ var DESCRIPTION10 = `
 
 // src/capabilities/tools/TaskStopTool/TaskStopTool.ts
 init_toolUIRegistry();
+init_backgroundAbortRegistry();
 var {
   renderToolResultMessage: renderToolResultMessage17,
   renderToolUseMessage: renderToolUseMessage17
@@ -331810,6 +332024,9 @@ var TaskStopTool = buildToolRuntime({
     const appState = getAppState();
     const task = appState.tasks?.[id];
     if (!task) {
+      if (hasBackgroundAgent(id)) {
+        return { result: true };
+      }
       return {
         result: false,
         message: `No task found with ID: ${id}`,
@@ -334757,34 +334974,63 @@ function optionsWithProviderRoutingEnv(options2) {
   }
   return { ...options2, env: mergedEnv };
 }
-function createQueryLike(generator, runtimeState, onClose) {
+function createQueryLike(generator, runtimeState, finalize) {
+  let finalizePromise;
+  let closePromise;
+  const finalizeOnce = () => {
+    finalizePromise ??= finalize();
+    return finalizePromise;
+  };
+  const stream4 = async function* () {
+    try {
+      yield* generator;
+    } finally {
+      await finalizeOnce();
+    }
+  }();
   return {
     [Symbol.asyncIterator]() {
-      return generator;
+      return stream4;
     },
     async interrupt() {
       runtimeState.abortController.abort();
       runtimeState.abortController = createAbortController();
     },
     killAgent(agentId) {
-      abortBackgroundAgentById(agentId);
-      killAsyncAgent(agentId, runtimeState.setAppState);
+      return abortBackgroundAgentById(agentId);
     },
-    async close() {
-      if (runtimeState.closed)
-        return;
-      runtimeState.closed = true;
-      runtimeState.abortController.abort();
-      try {
-        await generator.return(undefined);
-      } finally {
-        if (onClose) {
-          await onClose();
-        }
+    close() {
+      if (!closePromise) {
+        runtimeState.closed = true;
+        runtimeState.abortController.abort();
+        closePromise = (async () => {
+          try {
+            await stream4.return(undefined);
+          } finally {
+            await finalizeOnce();
+          }
+        })();
       }
+      return closePromise;
     }
   };
 }
+function trackProjectContextId(ownership, sessionId) {
+  ownership.projectContextIds.add(sessionId);
+  if (ownership.kind === "session") {
+    ownership.trackProjectContextId(sessionId);
+  }
+}
+async function closeOwnedQueryResources(scope, projectContextIds) {
+  try {
+    await scope.stop();
+  } finally {
+    for (const sessionId of projectContextIds) {
+      clearProjectForSession(sessionId);
+    }
+    projectContextIds.clear();
+  }
+}
 async function* mergeAskWithStatus(askIterable, statusStream) {
   const askIter = askIterable[Symbol.asyncIterator]();
   let askNext = askIter.next();
@@ -334817,6 +335063,15 @@ function runSdkQueryRuntime(params) {
   const cwd = typeof options2.cwd === "string" && options2.cwd.trim().length > 0 ? options2.cwd : process.cwd();
   const optionsWithProviderRouting = optionsWithProviderRoutingEnv(options2);
   const queryContext = buildQueryContextFromSdk(optionsWithProviderRouting);
+  const ownership = params.resourceOwner ? {
+    ...params.resourceOwner,
+    projectContextIds: new Set
+  } : {
+    kind: "standalone",
+    backgroundTaskScope: new BackgroundTaskScope,
+    projectContextIds: new Set
+  };
+  trackProjectContextId(ownership, queryContext.identity.sessionId);
   const runtimeState = {
     closed: false,
     runningTurn: false,
@@ -334824,6 +335079,7 @@ function runSdkQueryRuntime(params) {
   };
   const fileCheckpointingOnChange = options2.fileCheckpointing?.onFileHistoryChange;
   const appStateStore = buildAppStateStore(applyFileCheckpointingInitialState(applyDisallowedTools(applyPermissionMode(getDefaultAppState(), options2.permissionMode), options2.disallowedTools), options2.fileCheckpointing?.initialState), fileCheckpointingOnChange);
+  const releaseBackgroundTaskScope = bindBackgroundTaskScope(appStateStore.setAppState, ownership.backgroundTaskScope);
   const initialMessagesForReplay = options2.resume ? loadAndRestampHistoricalMessages(options2.resume, queryContext.identity.sessionId, options2.initialMessages) : options2.initialMessages;
   let mutableMessages = normalizeInitialMessages(initialMessagesForReplay);
   let readFileCache = createFileStateCacheWithSizeLimit(DEFAULT_READ_FILE_CACHE_SIZE);
@@ -335066,7 +335322,17 @@ function runSdkQueryRuntime(params) {
     }
   }();
   const generator = bindAsyncGeneratorToScope(rawGenerator, queryContext);
-  return createQueryLike(generator, runtimeState);
+  return createQueryLike(generator, runtimeState, async () => {
+    trackProjectContextId(ownership, queryContext.identity.sessionId);
+    releaseBackgroundTaskScope();
+    try {
+      params.onStreamSettled?.();
+    } finally {
+      if (ownership.kind === "standalone") {
+        await closeOwnedQueryResources(ownership.backgroundTaskScope, ownership.projectContextIds);
+      }
+    }
+  });
 }
 
 // src/session/runtime.ts
@@ -335078,6 +335344,8 @@ init_hooks2();
 init_AppStateStore();
 init_debug();
 init_errors5();
+init_backgroundTaskScope();
+init_sessionStorage();
 function mergeTurnOptions(sessionOptions, turnOptions) {
   if (!turnOptions)
     return sessionOptions;
@@ -335094,6 +335362,10 @@ function mergeTurnOptions(sessionOptions, turnOptions) {
 class SessionRuntime {
   baseOptions;
   closed = false;
+  closePromise;
+  backgroundTaskScope = new BackgroundTaskScope;
+  projectContextIds = new Set;
+  activeQueries = new Set;
   accumulatedFileHistory;
   constructor(options2) {
     this.baseOptions = options2;
@@ -335117,13 +335389,34 @@ class SessionRuntime {
         }
       }
     } : undefined;
-    return runSdkQueryRuntime({
+    let query2;
+    query2 = runSdkQueryRuntime({
       prompt: params.prompt,
       options: {
         ...merged,
         ...fileCheckpointing ? { fileCheckpointing } : {}
+      },
+      resourceOwner: {
+        kind: "session",
+        backgroundTaskScope: this.backgroundTaskScope,
+        trackProjectContextId: (sessionId) => {
+          this.projectContextIds.add(sessionId);
+        }
+      },
+      onStreamSettled: () => {
+        this.activeQueries.delete(query2);
       }
     });
+    this.activeQueries.add(query2);
+    const closeQuery = query2.close.bind(query2);
+    query2.close = async () => {
+      try {
+        await closeQuery();
+      } finally {
+        this.activeQueries.delete(query2);
+      }
+    };
+    return query2;
   }
   async prompt(message, options2) {
     const q = this.query({ prompt: message, options: options2 });
@@ -335138,32 +335431,66 @@ class SessionRuntime {
   async getInfo() {
     return;
   }
-  async close(reason = "normal") {
-    if (this.closed)
-      return;
-    this.closed = true;
-    const ctx = buildRewindQueryContext(this.baseOptions);
-    await runWithQueryContext(ctx, async () => {
-      if (this.baseOptions.hooks) {
-        try {
-          registerHookCallbacks2(this.baseOptions.hooks);
-        } catch (err2) {
-          logForDebugging(`SessionRuntime.close: registerHookCallbacks threw: ${errorMessage(err2)}`, { level: "warn" });
-        }
+  close(reason = "normal") {
+    if (!this.closePromise) {
+      this.closed = true;
+      this.closePromise = this.closeResources(reason);
+    }
+    return this.closePromise;
+  }
+  async closeResources(reason) {
+    const failures = [];
+    try {
+      const activeQueries = [...this.activeQueries];
+      const queryResults = await Promise.allSettled(activeQueries.map(async (query2) => {
+        await query2.close();
+      }));
+      for (const result of queryResults) {
+        if (result.status === "rejected")
+          failures.push(result.reason);
       }
-      let state3 = getDefaultAppState();
+      this.activeQueries.clear();
       try {
-        await executeSessionEndHooks(reason, {
-          getAppState: () => state3,
-          setAppState: (updater) => {
-            state3 = updater(state3);
-          },
-          timeoutMs: getSessionEndHookTimeoutMs()
+        await this.backgroundTaskScope.stop();
+      } catch (err2) {
+        failures.push(err2);
+      }
+      try {
+        const ctx = buildRewindQueryContext(this.baseOptions);
+        this.projectContextIds.add(ctx.identity.sessionId);
+        await runWithQueryContext(ctx, async () => {
+          if (this.baseOptions.hooks) {
+            try {
+              registerHookCallbacks2(this.baseOptions.hooks);
+            } catch (err2) {
+              logForDebugging(`SessionRuntime.close: registerHookCallbacks threw: ${errorMessage(err2)}`, { level: "warn" });
+            }
+          }
+          let state3 = getDefaultAppState();
+          try {
+            await executeSessionEndHooks(reason, {
+              getAppState: () => state3,
+              setAppState: (updater) => {
+                state3 = updater(state3);
+              },
+              timeoutMs: getSessionEndHookTimeoutMs()
+            });
+          } catch (err2) {
+            logForDebugging(`SessionRuntime.close: SessionEnd hooks errored: ${errorMessage(err2)}`, { level: "warn" });
+          }
         });
       } catch (err2) {
-        logForDebugging(`SessionRuntime.close: SessionEnd hooks errored: ${errorMessage(err2)}`, { level: "warn" });
+        logForDebugging(`SessionRuntime.close: SessionEnd context errored: ${errorMessage(err2)}`, { level: "warn" });
       }
-    });
+    } finally {
+      for (const sessionId of this.projectContextIds) {
+        clearProjectForSession(sessionId);
+      }
+      this.projectContextIds.clear();
+    }
+    if (failures.length > 0) {
+      throw new AggregateError(failures, "SessionRuntime cleanup failed");
+    }
   }
   canRewindFiles(state3, messageUuid) {
     const effective = this.accumulatedFileHistory ?? state3;
@@ -336140,4 +336467,4 @@ export {
   AbortError2 as AbortError
 };
 
-//# debugId=AE8C8840D6E2407264756E2164756E21
+//# debugId=96A7445415A37CC164756E2164756E21