refactor(core): extract ExecutionLifecycleService for tool backgrounding (#21717)

packages/core/src/tools/shell.ts

@@ -18,6 +18,7 @@ import {
   Kind,
   type ToolInvocation,
   type ToolResult,
+  type BackgroundExecutionData,
   type ToolCallConfirmationDetails,
   type ToolExecuteConfirmationDetails,
   type PolicyUpdateOptions,
@@ -150,7 +151,7 @@ export class ShellToolInvocation extends BaseToolInvocation<
     signal: AbortSignal,
     updateOutput?: (output: ToolLiveOutput) => void,
     shellExecutionConfig?: ShellExecutionConfig,
-    setPidCallback?: (pid: number) => void,
+    setExecutionIdCallback?: (executionId: number) => void,
   ): Promise<ToolResult> {
     const strippedCommand = stripShellWrapper(this.params.command);
 
@@ -281,8 +282,8 @@ export class ShellToolInvocation extends BaseToolInvocation<
         );
 
       if (pid) {
-        if (setPidCallback) {
-          setPidCallback(pid);
+        if (setExecutionIdCallback) {
+          setExecutionIdCallback(pid);
         }
 
         // If the model requested to run in the background, do so after a short delay.
@@ -324,7 +325,7 @@ export class ShellToolInvocation extends BaseToolInvocation<
         }
       }
 
-      let data: Record<string, unknown> | undefined;
+      let data: BackgroundExecutionData | undefined;
 
       let llmContent = '';
       let timeoutMessage = '';

packages/core/src/tools/tools.ts

@@ -61,12 +61,14 @@ export interface ToolInvocation<
    * Executes the tool with the validated parameters.
    * @param signal AbortSignal for tool cancellation.
    * @param updateOutput Optional callback to stream output.
+   * @param setExecutionIdCallback Optional callback for tools that expose a background execution handle.
    * @returns Result of the tool execution.
    */
   execute(
     signal: AbortSignal,
     updateOutput?: (output: ToolLiveOutput) => void,
     shellExecutionConfig?: ShellExecutionConfig,
+    setExecutionIdCallback?: (executionId: number) => void,
   ): Promise<TResult>;
 
   /**
@@ -78,6 +80,40 @@ export interface ToolInvocation<
   ): PolicyUpdateOptions | undefined;
 }
 
+/**
+ * Structured payload used by tools to surface background execution metadata to
+ * the CLI UI.
+ *
+ * NOTE: `pid` is used as the canonical identifier for now to stay consistent
+ * with existing types (ExecutingToolCall.pid, ExecutionHandle.pid, etc.).
+ * A future rename to `executionId` is planned once the codebase is fully
+ * migrated — not done in this PR to keep the diff focused on the abstraction.
+ */
+export interface BackgroundExecutionData extends Record<string, unknown> {
+  pid?: number;
+  command?: string;
+  initialOutput?: string;
+}
+
+export function isBackgroundExecutionData(
+  data: unknown,
+): data is BackgroundExecutionData {
+  if (typeof data !== 'object' || data === null) {
+    return false;
+  }
+
+  const pid = 'pid' in data ? data.pid : undefined;
+  const command = 'command' in data ? data.command : undefined;
+  const initialOutput =
+    'initialOutput' in data ? data.initialOutput : undefined;
+
+  return (
+    (pid === undefined || typeof pid === 'number') &&
+    (command === undefined || typeof command === 'string') &&
+    (initialOutput === undefined || typeof initialOutput === 'string')
+  );
+}
+
 /**
  * Options for policy updates that can be customized by tool invocations.
  */