fix(agents): add usage guidance to sessions_spawn tool description (fixes #91814) (#91824)

* fix(agents): add usage guidance to sessions_spawn tool description (fixes #91814)

* fix(agents): tighten sessions spawn guidance

---------

Co-authored-by: Vincent Koc <vincentkoc@ieee.org>

src/agents/tool-description-presets.ts

@@ -45,6 +45,13 @@ export function describeSessionsSpawnTool(options?: {
     options?.acpAvailable === false
       ? 'Spawn clean child session; default `runtime="subagent"`.'
       : 'Spawn clean child session; default `runtime="subagent"`; set `runtime="acp"` explicitly for ACP.';
+  const sessionCompletionGuidance =
+    options?.acpAvailable === false
+      ? "After spawning, do non-overlapping work; run-mode results return, session-mode output stays in thread."
+      : 'After spawning, do non-overlapping work; run-mode results return, session-mode output stays in thread unless ACP uses `streamTo="parent"`.';
+  const completionGuidance = options?.threadAvailable
+    ? sessionCompletionGuidance
+    : "After spawning, do non-overlapping work while run-mode results return.";
   const baseDescription = [
     runtimeDescription,
     options?.threadAvailable
@@ -54,6 +61,9 @@ export function describeSessionsSpawnTool(options?: {
     "Native subagents get task in first visible `[Subagent Task]` message.",
     'Native only: `context="fork"` only when child needs current transcript; else omit or `isolated`.',
     "Use for fresh child-session work.",
+    "Delegate sidecar/parallel tasks: batch file reads, multi-step searches, data collection.",
+    "Avoid delegating quick lookups or single-file reads unless policy prefers delegation.",
+    completionGuidance,
   ];
   if (options?.acpAvailable === false) {
     return baseDescription.join(" ");

src/agents/tools/sessions-spawn-tool.test.ts

@@ -132,7 +132,19 @@ describe("sessions_spawn tool", () => {
   it("advertises ACP runtime affordances when an ACP backend is loaded", () => {
     registerAcpBackendForTest();
 
-    const tool = createSessionsSpawnTool();
+    const tool = createSessionsSpawnTool({
+      agentChannel: "discord",
+      agentAccountId: "default",
+      config: {
+        channels: {
+          discord: {
+            threadBindings: {
+              spawnSessions: true,
+            },
+          },
+        },
+      },
+    });
     const schema = tool.parameters as {
       properties?: {
         runtime?: { enum?: string[] };
@@ -143,6 +155,7 @@ describe("sessions_spawn tool", () => {
 
     expect(tool.displaySummary).toBe("Spawn subagent or ACP session.");
     expect(tool.description).toContain('runtime="acp"');
+    expect(tool.description).toContain('unless ACP uses `streamTo="parent"`');
     expect(schema.properties?.runtime?.enum).toEqual(["subagent", "acp"]);
     const resumeSessionId = requireSchemaProperty(schema.properties, "resumeSessionId");
     const streamTo = requireSchemaProperty(schema.properties, "streamTo");
@@ -259,6 +272,7 @@ describe("sessions_spawn tool", () => {
     expect(schema.properties?.thread).toBeUndefined();
     expect(schema.properties?.mode?.enum).toEqual(["run"]);
     expect(tool.description).not.toContain("thread-bound");
+    expect(tool.description).not.toContain("session-mode output stays in thread");
   });
 
   it("shows thread-bound spawn fields when current channel allows spawnSessions", () => {

test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/codex-dynamic-tools.discord-group.json

@@ -1095,7 +1095,7 @@
   },
   {
     "deferLoading": true,
-    "description": "Spawn clean child session; default `runtime=\"subagent\"`. `mode=\"run\"` one-shot; `mode=\"session\"` persistent/thread-bound, only when requester channel supports thread bindings. Subagents inherit parent workspace. Native subagents get task in first visible `[Subagent Task]` message. Native only: `context=\"fork\"` only when child needs current transcript; else omit or `isolated`. Use for fresh child-session work.",
+    "description": "Spawn clean child session; default `runtime=\"subagent\"`. `mode=\"run\"` one-shot; `mode=\"session\"` persistent/thread-bound, only when requester channel supports thread bindings. Subagents inherit parent workspace. Native subagents get task in first visible `[Subagent Task]` message. Native only: `context=\"fork\"` only when child needs current transcript; else omit or `isolated`. Use for fresh child-session work. Delegate sidecar/parallel tasks: batch file reads, multi-step searches, data collection. Avoid delegating quick lookups or single-file reads unless policy prefers delegation. After spawning, do non-overlapping work; run-mode results return, session-mode output stays in thread.",
     "inputSchema": {
       "properties": {
         "agentId": {

test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/codex-dynamic-tools.heartbeat-turn.json

@@ -1131,7 +1131,7 @@
   },
   {
     "deferLoading": true,
-    "description": "Spawn clean child session; default `runtime=\"subagent\"`. `mode=\"run\"` one-shot background work. Subagents inherit parent workspace. Native subagents get task in first visible `[Subagent Task]` message. Native only: `context=\"fork\"` only when child needs current transcript; else omit or `isolated`. Use for fresh child-session work.",
+    "description": "Spawn clean child session; default `runtime=\"subagent\"`. `mode=\"run\"` one-shot background work. Subagents inherit parent workspace. Native subagents get task in first visible `[Subagent Task]` message. Native only: `context=\"fork\"` only when child needs current transcript; else omit or `isolated`. Use for fresh child-session work. Delegate sidecar/parallel tasks: batch file reads, multi-step searches, data collection. Avoid delegating quick lookups or single-file reads unless policy prefers delegation. After spawning, do non-overlapping work while run-mode results return.",
     "inputSchema": {
       "properties": {
         "agentId": {

test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/codex-dynamic-tools.telegram-direct.json

@@ -1095,7 +1095,7 @@
   },
   {
     "deferLoading": true,
-    "description": "Spawn clean child session; default `runtime=\"subagent\"`. `mode=\"run\"` one-shot background work. Subagents inherit parent workspace. Native subagents get task in first visible `[Subagent Task]` message. Native only: `context=\"fork\"` only when child needs current transcript; else omit or `isolated`. Use for fresh child-session work.",
+    "description": "Spawn clean child session; default `runtime=\"subagent\"`. `mode=\"run\"` one-shot background work. Subagents inherit parent workspace. Native subagents get task in first visible `[Subagent Task]` message. Native only: `context=\"fork\"` only when child needs current transcript; else omit or `isolated`. Use for fresh child-session work. Delegate sidecar/parallel tasks: batch file reads, multi-step searches, data collection. Avoid delegating quick lookups or single-file reads unless policy prefers delegation. After spawning, do non-overlapping work while run-mode results return.",
     "inputSchema": {
       "properties": {
         "agentId": {

test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/discord-group-codex-message-tool.md

@@ -223,8 +223,8 @@ This is the deterministic model-bound layer stack OpenClaw can snapshot for the
     "roughTokens": 0
   },
   "dynamicToolsJson": {
-    "chars": 44966,
-    "roughTokens": 11242
+    "chars": 45244,
+    "roughTokens": 11311
   },
   "openClawDeveloperInstructions": {
     "chars": 2988,
@@ -235,8 +235,8 @@ This is the deterministic model-bound layer stack OpenClaw can snapshot for the
     "roughTokens": 6925
   },
   "totalWithDynamicToolsJson": {
-    "chars": 72668,
-    "roughTokens": 18167
+    "chars": 72946,
+    "roughTokens": 18237
   },
   "userInputText": {
     "chars": 1629,

test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/telegram-direct-codex-message-tool.md

@@ -223,8 +223,8 @@ This is the deterministic model-bound layer stack OpenClaw can snapshot for the
     "roughTokens": 0
   },
   "dynamicToolsJson": {
-    "chars": 44687,
-    "roughTokens": 11172
+    "chars": 44933,
+    "roughTokens": 11234
   },
   "openClawDeveloperInstructions": {
     "chars": 1964,
@@ -235,8 +235,8 @@ This is the deterministic model-bound layer stack OpenClaw can snapshot for the
     "roughTokens": 6544
   },
   "totalWithDynamicToolsJson": {
-    "chars": 70865,
-    "roughTokens": 17717
+    "chars": 71111,
+    "roughTokens": 17778
   },
   "userInputText": {
     "chars": 1129,

test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/telegram-heartbeat-codex-tool.md

@@ -224,8 +224,8 @@ This is the deterministic model-bound layer stack OpenClaw can snapshot for the
     "roughTokens": 0
   },
   "dynamicToolsJson": {
-    "chars": 45782,
-    "roughTokens": 11446
+    "chars": 46028,
+    "roughTokens": 11507
   },
   "openClawDeveloperInstructions": {
     "chars": 1983,
@@ -236,8 +236,8 @@ This is the deterministic model-bound layer stack OpenClaw can snapshot for the
     "roughTokens": 6780
   },
   "totalWithDynamicToolsJson": {
-    "chars": 72903,
-    "roughTokens": 18226
+    "chars": 73149,
+    "roughTokens": 18288
   },
   "userInputText": {
     "chars": 1367,