fix(background-task): clarify task id contracts

src/tools/delegate-task/task-schema.test.ts

@@ -42,11 +42,25 @@ function createDelegateTask(...args: Parameters<typeof import("./tools").createD
 
 		//#then
 		expect(description).toContain("subagent_type: Use specific agent directly")
-		expect(description).toContain("task_id: Existing task to continue")
+		expect(description).toContain("task_id: Continuation session id")
 		expect(description).not.toContain("sisyphus")
 		expect(description).not.toContain("hephaestus")
 		expect(description).not.toContain("prometheus")
 	})
+
+	test("#given task schema #when describing async mode #then it names background task ids explicitly", () => {
+		//#given
+		const toolDefinition = createDelegateTask({ manager: {} as never, client: {} as never, directory: "/tmp/test" })
+
+		//#when
+		const runInBackgroundSchema = unsafeTestValue<{ description?: string }>(toolDefinition.args.run_in_background)
+
+		//#then
+		expect(runInBackgroundSchema.description).toContain("background task ID")
+		expect(runInBackgroundSchema.description).toContain("bg_")
+		expect(runInBackgroundSchema.description).toContain("background_output")
+		expect(runInBackgroundSchema.description).not.toContain("returns task_id")
+	})
 })
 
 export {}

src/tools/delegate-task/tool-description.test.ts

@@ -15,4 +15,18 @@ describe("createDelegateTaskPresentation", () => {
     expect(description).toContain("busy/retry/running")
     expect(description).toContain("not a total wall-clock limit")
   })
+
+  test("#given continuation usage #when description is rendered #then task_id is described as a session id", () => {
+    //#given
+    const presentation = createDelegateTaskPresentation({})
+
+    //#when
+    const description = presentation.description
+
+    //#then
+    expect(description).toContain("task_id: Continuation session id")
+    expect(description).toContain("ses_")
+    expect(description).toContain("not the background task id")
+    expect(description).toContain("bg_")
+  })
 })

src/tools/delegate-task/tool-description.ts

@@ -66,15 +66,15 @@ export function createDelegateTaskPresentation(options: DelegateTaskToolOptions)
     Available categories:
   ${categoryList}
   - subagent_type: Use specific agent directly (explore, librarian, oracle, metis, momus)
-  - run_in_background: REQUIRED. true=async (returns task_id), false=sync (waits). Use background=true ONLY for parallel exploration with 5+ independent queries.
+  - run_in_background: REQUIRED. true=async (returns a background task ID like \`bg_...\` for \`background_output\`), false=sync (waits). Use background=true ONLY for parallel exploration with 5+ independent queries.
     Sync waits use a 30-minute inactivity window: OpenCode busy/retry/running status resets the window, so this is not a total wall-clock limit.
-  - task_id: Existing task to continue (from previous task output). Continues the same subagent session with FULL CONTEXT PRESERVED.
+  - task_id: Continuation session id (\`ses_...\`) from task metadata. Continues the same subagent session with FULL CONTEXT PRESERVED; not the background task id (\`bg_...\`).
   - command: The command that triggered this task (optional, for slash command tracking).
   
   **WHEN TO USE task_id:**
-  - Task failed/incomplete → task_id with "fix: [specific issue]"
-  - Need follow-up on previous result → task_id with additional question
-  - Multi-turn conversation with same agent → always task_id instead of new task
+  - Task failed/incomplete → \`task(task_id="ses_...", prompt="fix: [specific issue]")\`
+  - Need follow-up on previous result → \`task(task_id="ses_...", prompt="Also: [question]")\`
+  - Multi-turn conversation with same agent → always \`task(task_id="ses_...")\` instead of new task
   
   Prompts MUST be in English.`
 

src/tools/delegate-task/tools.ts

@@ -24,10 +24,15 @@ const delegateTaskArgsSchema = {
   load_skills: tool.schema.array(tool.schema.string()).describe("Skill names to inject. REQUIRED - pass [] if no skills needed."),
   description: tool.schema.string().optional().describe("Short task description (3-5 words). Auto-generated from prompt if omitted."),
   prompt: tool.schema.string().describe("Full detailed prompt for the agent"),
-  run_in_background: tool.schema.boolean().describe("REQUIRED. true=async (returns task_id), false=sync (waits). Use false for task delegation, true ONLY for parallel exploration."),
+  run_in_background: tool.schema
+    .boolean()
+    .describe("REQUIRED. true=async (returns background task ID `bg_...` for background_output), false=sync (waits). Use false for task delegation, true ONLY for parallel exploration."),
   category: tool.schema.string().optional().describe("REQUIRED if subagent_type not provided. Do NOT provide both category and subagent_type."),
   subagent_type: tool.schema.string().optional().describe("REQUIRED if category not provided. Do NOT provide both category and subagent_type."),
-  task_id: tool.schema.string().optional().describe("Existing task to continue. Canonical resume identifier."),
+  task_id: tool.schema
+    .string()
+    .optional()
+    .describe("Continuation session id (`ses_...`) from task metadata; not a background task id (`bg_...`)."),
   command: tool.schema.string().optional().describe("The command that triggered this task"),
 }