fix: notify agent session on background exec completion by default

wenkang-xie · wenkang-xie · commit 043d64062703 · 2026-03-16T15:17:11.000+08:00
Previously, successful background exec processes with empty output would silently complete without notifying the parent agent session. This caused a major UX gap in multi-agent orchestration workflows where an orchestrator agent dispatches coding agents (Claude Code, Codex) in background — the orchestrator was never woken up on completion, leaving users waiting indefinitely. Changes: - Default notifyOnExitEmptySuccess to true (was false) Background processes that complete successfully now always enqueue a system event, even when stdout is empty. Agents should always know when their dispatched work finishes. - Align runExecProcess default with createExecTool (both use !== false) - Reduce exec exit wake coalesce delay to 50ms (was 250ms) Exec completion is time-sensitive for orchestration flows. - Update tests and config docs to reflect new defaults Users who want the old behavior can set: tools.exec.notifyOnExitEmptySuccess: false Fixes #18237
diff --git a/src/agents/bash-tools.exec-runtime.ts b/src/agents/bash-tools.exec-runtime.ts
@@ -222,7 +222,10 @@ function maybeNotifyOnExit(session: ProcessSession, status: "completed" | "faile
     : `Exec ${status} (${session.id.slice(0, 8)}, ${exitLabel})`;
   enqueueSystemEvent(summary, { sessionKey });
   requestHeartbeatNow(
-    scopedHeartbeatWakeOptions(sessionKey, { reason: `exec:${session.id}:exit` }),
+    scopedHeartbeatWakeOptions(sessionKey, {
+      reason: `exec:${session.id}:exit`,
+      coalesceMs: 50,
+    }),
   );
 }
 
@@ -321,7 +324,7 @@ export async function runExecProcess(opts: {
     scopeKey: opts.scopeKey,
     sessionKey: opts.sessionKey,
     notifyOnExit: opts.notifyOnExit,
-    notifyOnExitEmptySuccess: opts.notifyOnExitEmptySuccess === true,
+    notifyOnExitEmptySuccess: opts.notifyOnExitEmptySuccess !== false,
     exitNotified: false,
     child: undefined,
     stdin: undefined,
diff --git a/src/agents/bash-tools.exec.ts b/src/agents/bash-tools.exec.ts
@@ -191,7 +191,7 @@ export function createExecTool(
     );
   }
   const notifyOnExit = defaults?.notifyOnExit !== false;
-  const notifyOnExitEmptySuccess = defaults?.notifyOnExitEmptySuccess === true;
+  const notifyOnExitEmptySuccess = defaults?.notifyOnExitEmptySuccess !== false;
   const notifySessionKey = defaults?.sessionKey?.trim() || undefined;
   const approvalRunningNoticeMs = resolveApprovalRunningNoticeMs(defaults?.approvalRunningNoticeMs);
   // Derive agentId only when sessionKey is an agent session key.
diff --git a/src/agents/bash-tools.test.ts b/src/agents/bash-tools.test.ts
@@ -268,10 +268,12 @@ type NotifyNoopCase = LabeledCase & {
   notifyOnExitEmptySuccess: boolean;
 };
 const NOOP_NOTIFY_CASES: NotifyNoopCase[] = [
-  withLabel("default behavior skips no-op completion events", { notifyOnExitEmptySuccess: false }),
-  withLabel("explicitly enabling no-op completion emits completion events", {
+  withLabel("default behavior emits completion events for empty-output success", {
     notifyOnExitEmptySuccess: true,
   }),
+  withLabel("explicitly disabling no-op completion skips events", {
+    notifyOnExitEmptySuccess: false,
+  }),
 ];
 const DISALLOWED_ELEVATION_CASES: DisallowedElevationCase[] = [
   withLabel("rejects elevated requests when not allowed", {
@@ -398,7 +400,7 @@ const runLongLogExpectationCase = async ({
 };
 const runNotifyNoopCase = async ({ label, notifyOnExitEmptySuccess }: NotifyNoopCase) => {
   const tool = createNotifyOnExitExecTool(
-    notifyOnExitEmptySuccess ? { notifyOnExitEmptySuccess: true } : {},
+    notifyOnExitEmptySuccess ? {} : { notifyOnExitEmptySuccess: false },
   );
 
   const { status } = await runBackgroundCommandToCompletion(tool, shortDelayCmd);
diff --git a/src/config/schema.help.ts b/src/config/schema.help.ts
@@ -551,7 +551,7 @@ export const FIELD_HELP: Record<string, string> = {
   "tools.exec.notifyOnExit":
     "When true (default), backgrounded exec sessions on exit and node exec lifecycle events enqueue a system event and request a heartbeat.",
   "tools.exec.notifyOnExitEmptySuccess":
-    "When true, successful backgrounded exec exits with empty output still enqueue a completion system event (default: false).",
+    "When true (default), successful backgrounded exec exits with empty output still enqueue a completion system event. Set to false to suppress these notifications.",
   "tools.exec.pathPrepend": "Directories to prepend to PATH for exec runs (gateway/sandbox).",
   "tools.exec.safeBins":
     "Allow stdin-only safe binaries to run without explicit allowlist entries.",
diff --git a/src/config/types.tools.ts b/src/config/types.tools.ts
@@ -254,7 +254,8 @@ export type ExecToolConfig = {
   notifyOnExit?: boolean;
   /**
    * Also emit success exit notifications when a backgrounded exec has no output.
-   * Default false to reduce context noise.
+   * Default true — agents should always be notified when background tasks complete.
+   * Set to false to suppress empty-success notifications and reduce context noise.
    */
   notifyOnExitEmptySuccess?: boolean;
   /** apply_patch subtool configuration (experimental). */

Original file line number	Diff line number	Diff line change
`@@ -191,7 +191,7 @@ export function createExecTool(`
`191`	`191`	`);`
`192`	`192`	`}`
`193`	`193`	`const notifyOnExit = defaults?.notifyOnExit !== false;`
`194`		`- const notifyOnExitEmptySuccess = defaults?.notifyOnExitEmptySuccess === true;`
	`194`	`+ const notifyOnExitEmptySuccess = defaults?.notifyOnExitEmptySuccess !== false;`
`195`	`195`	`const notifySessionKey = defaults?.sessionKey?.trim() \|\| undefined;`
`196`	`196`	`const approvalRunningNoticeMs = resolveApprovalRunningNoticeMs(defaults?.approvalRunningNoticeMs);`
`197`	`197`	`// Derive agentId only when sessionKey is an agent session key.`