Subagents: restore announce chain + fix nested retry/drop regressions (#22223)

* Subagents: restore announce flow and fix nested delivery retries

* fix: prep subagent announce + docs alignment (#22223) (thanks @tyler6204)

src/agents/openclaw-tools.subagents.sessions-spawn.lifecycle.e2e.test.ts

@@ -133,35 +133,6 @@ const waitFor = async (predicate: () => boolean, timeoutMs = 2000) => {
   );
 };
 
-function expectSingleCompletionSend(
-  calls: GatewayRequest[],
-  expected: { sessionKey: string; channel: string; to: string; message: string },
-) {
-  const sendCalls = calls.filter((call) => call.method === "send");
-  expect(sendCalls).toHaveLength(1);
-  const send = sendCalls[0]?.params as
-    | { sessionKey?: string; channel?: string; to?: string; message?: string }
-    | undefined;
-  expect(send?.sessionKey).toBe(expected.sessionKey);
-  expect(send?.channel).toBe(expected.channel);
-  expect(send?.to).toBe(expected.to);
-  expect(send?.message).toBe(expected.message);
-}
-
-function createDeleteCleanupHooks(setDeletedKey: (key: string | undefined) => void) {
-  return {
-    onAgentSubagentSpawn: (params: unknown) => {
-      const rec = params as { channel?: string; timeout?: number } | undefined;
-      expect(rec?.channel).toBe("discord");
-      expect(rec?.timeout).toBe(1);
-    },
-    onSessionsDelete: (params: unknown) => {
-      const rec = params as { key?: string } | undefined;
-      setDeletedKey(rec?.key);
-    },
-  };
-}
-
 describe("openclaw-tools: subagents (sessions_spawn lifecycle)", () => {
   beforeEach(() => {
     resetSessionsSpawnConfigOverride();
@@ -184,7 +155,6 @@ describe("openclaw-tools: subagents (sessions_spawn lifecycle)", () => {
     const tool = await getSessionsSpawnTool({
       agentSessionKey: "main",
       agentChannel: "whatsapp",
-      agentTo: "+123",
     });
 
     const result = await tool.execute("call2", {
@@ -213,7 +183,7 @@ describe("openclaw-tools: subagents (sessions_spawn lifecycle)", () => {
 
     await waitFor(() => ctx.waitCalls.some((call) => call.runId === child.runId));
     await waitFor(() => patchCalls.some((call) => call.label === "my-task"));
-    await waitFor(() => ctx.calls.filter((c) => c.method === "send").length >= 1);
+    await waitFor(() => ctx.calls.filter((c) => c.method === "agent").length >= 2);
 
     const childWait = ctx.waitCalls.find((call) => call.runId === child.runId);
     expect(childWait?.timeoutMs).toBe(1000);
@@ -222,21 +192,22 @@ describe("openclaw-tools: subagents (sessions_spawn lifecycle)", () => {
     expect(labelPatch?.key).toBe(child.sessionKey);
     expect(labelPatch?.label).toBe("my-task");
 
-    // Subagent spawn call plus direct outbound completion send.
+    // Two agent calls: subagent spawn + main agent trigger
     const agentCalls = ctx.calls.filter((c) => c.method === "agent");
-    expect(agentCalls).toHaveLength(1);
+    expect(agentCalls).toHaveLength(2);
 
     // First call: subagent spawn
     const first = agentCalls[0]?.params as { lane?: string } | undefined;
     expect(first?.lane).toBe("subagent");
 
-    // Direct send should route completion to the requester channel/session.
-    expectSingleCompletionSend(ctx.calls, {
-      sessionKey: "agent:main:main",
-      channel: "whatsapp",
-      to: "+123",
-      message: "✅ Subagent main finished\n\ndone",
-    });
+    // Second call: main agent trigger (not "Sub-agent announce step." anymore)
+    const second = agentCalls[1]?.params as { sessionKey?: string; message?: string } | undefined;
+    expect(second?.sessionKey).toBe("main");
+    expect(second?.message).toContain("subagent task");
+
+    // No direct send to external channel (main agent handles delivery)
+    const sendCalls = ctx.calls.filter((c) => c.method === "send");
+    expect(sendCalls.length).toBe(0);
     expect(child.sessionKey?.startsWith("agent:main:subagent:")).toBe(true);
   });
 
@@ -245,15 +216,20 @@ describe("openclaw-tools: subagents (sessions_spawn lifecycle)", () => {
     callGatewayMock.mockReset();
     let deletedKey: string | undefined;
     const ctx = setupSessionsSpawnGatewayMock({
-      ...createDeleteCleanupHooks((key) => {
-        deletedKey = key;
-      }),
+      onAgentSubagentSpawn: (params) => {
+        const rec = params as { channel?: string; timeout?: number } | undefined;
+        expect(rec?.channel).toBe("discord");
+        expect(rec?.timeout).toBe(1);
+      },
+      onSessionsDelete: (params) => {
+        const rec = params as { key?: string } | undefined;
+        deletedKey = rec?.key;
+      },
     });
 
     const tool = await getSessionsSpawnTool({
       agentSessionKey: "discord:group:req",
       agentChannel: "discord",
-      agentTo: "discord:dm:u123",
     });
 
     const result = await tool.execute("call1", {
@@ -291,7 +267,7 @@ describe("openclaw-tools: subagents (sessions_spawn lifecycle)", () => {
     expect(childWait?.timeoutMs).toBe(1000);
 
     const agentCalls = ctx.calls.filter((call) => call.method === "agent");
-    expect(agentCalls).toHaveLength(1);
+    expect(agentCalls).toHaveLength(2);
 
     const first = agentCalls[0]?.params as
       | {
@@ -307,12 +283,19 @@ describe("openclaw-tools: subagents (sessions_spawn lifecycle)", () => {
     expect(first?.sessionKey?.startsWith("agent:main:subagent:")).toBe(true);
     expect(child.sessionKey?.startsWith("agent:main:subagent:")).toBe(true);
 
-    expectSingleCompletionSend(ctx.calls, {
-      sessionKey: "agent:main:discord:group:req",
-      channel: "discord",
-      to: "discord:dm:u123",
-      message: "✅ Subagent main finished",
-    });
+    const second = agentCalls[1]?.params as
+      | {
+          sessionKey?: string;
+          message?: string;
+          deliver?: boolean;
+        }
+      | undefined;
+    expect(second?.sessionKey).toBe("discord:group:req");
+    expect(second?.deliver).toBe(true);
+    expect(second?.message).toContain("subagent task");
+
+    const sendCalls = ctx.calls.filter((c) => c.method === "send");
+    expect(sendCalls.length).toBe(0);
 
     expect(deletedKey?.startsWith("agent:main:subagent:")).toBe(true);
   });
@@ -323,16 +306,21 @@ describe("openclaw-tools: subagents (sessions_spawn lifecycle)", () => {
     let deletedKey: string | undefined;
     const ctx = setupSessionsSpawnGatewayMock({
       includeChatHistory: true,
-      ...createDeleteCleanupHooks((key) => {
-        deletedKey = key;
-      }),
+      onAgentSubagentSpawn: (params) => {
+        const rec = params as { channel?: string; timeout?: number } | undefined;
+        expect(rec?.channel).toBe("discord");
+        expect(rec?.timeout).toBe(1);
+      },
+      onSessionsDelete: (params) => {
+        const rec = params as { key?: string } | undefined;
+        deletedKey = rec?.key;
+      },
       agentWaitResult: { status: "ok", startedAt: 3000, endedAt: 4000 },
     });
 
     const tool = await getSessionsSpawnTool({
       agentSessionKey: "discord:group:req",
       agentChannel: "discord",
-      agentTo: "discord:dm:u123",
     });
 
     const result = await tool.execute("call1b", {
@@ -350,27 +338,29 @@ describe("openclaw-tools: subagents (sessions_spawn lifecycle)", () => {
       throw new Error("missing child runId");
     }
     await waitFor(() => ctx.waitCalls.some((call) => call.runId === child.runId));
-    await waitFor(() => ctx.calls.filter((call) => call.method === "send").length >= 1);
+    await waitFor(() => ctx.calls.filter((call) => call.method === "agent").length >= 2);
     await waitFor(() => Boolean(deletedKey));
 
     const childWait = ctx.waitCalls.find((call) => call.runId === child.runId);
     expect(childWait?.timeoutMs).toBe(1000);
     expect(child.sessionKey?.startsWith("agent:main:subagent:")).toBe(true);
 
-    // One agent call for spawn, then direct completion send.
+    // Two agent calls: subagent spawn + main agent trigger
     const agentCalls = ctx.calls.filter((call) => call.method === "agent");
-    expect(agentCalls).toHaveLength(1);
+    expect(agentCalls).toHaveLength(2);
 
     // First call: subagent spawn
     const first = agentCalls[0]?.params as { lane?: string } | undefined;
     expect(first?.lane).toBe("subagent");
 
-    expectSingleCompletionSend(ctx.calls, {
-      sessionKey: "agent:main:discord:group:req",
-      channel: "discord",
-      to: "discord:dm:u123",
-      message: "✅ Subagent main finished\n\ndone",
-    });
+    // Second call: main agent trigger
+    const second = agentCalls[1]?.params as { sessionKey?: string; deliver?: boolean } | undefined;
+    expect(second?.sessionKey).toBe("discord:group:req");
+    expect(second?.deliver).toBe(true);
+
+    // No direct send to external channel (main agent handles delivery)
+    const sendCalls = ctx.calls.filter((c) => c.method === "send");
+    expect(sendCalls.length).toBe(0);
 
     // Session should be deleted
     expect(deletedKey?.startsWith("agent:main:subagent:")).toBe(true);