fix(background-task): clarify task id contracts

src/tools/background-task/constants.ts

@@ -1,4 +1,4 @@
-export const BACKGROUND_TASK_DESCRIPTION = `Run agent task in background. Returns task_id immediately; notifies on completion.
+export const BACKGROUND_TASK_DESCRIPTION = `Run agent task in background. Returns a background task ID (\`bg_...\`) immediately; notifies on completion.
 
 Use \`background_output\` to get results. Prompts MUST be in English.`
 

src/tools/background-task/create-background-output.metadata.test.ts

@@ -4,7 +4,9 @@ import type { ToolContext } from "@opencode-ai/plugin/tool"
 import { describe, expect, test } from "bun:test"
 import type { BackgroundTask } from "../../features/background-agent"
 import { clearPendingStore, consumeToolMetadata } from "../../features/tool-metadata-store"
+import { unsafeTestValue } from "../../../test-support/unsafe-test-value"
 import type { BackgroundOutputClient, BackgroundOutputManager } from "./clients"
+import { BACKGROUND_TASK_DESCRIPTION } from "./constants"
 import { createBackgroundOutput } from "./create-background-output"
 
 const projectDir = "/Users/yeongyu/local-workspaces/oh-my-opencode"
@@ -14,6 +16,38 @@ type ToolContextWithCallID = ToolContext & {
 }
 
 describe("createBackgroundOutput metadata", () => {
+  test("describes background task launch output as a bg id", () => {
+    // #given, #when
+    const description = BACKGROUND_TASK_DESCRIPTION
+
+    // #then
+    expect(description).toContain("background task ID")
+    expect(description).toContain("bg_")
+    expect(description).not.toContain("Returns task_id")
+  })
+
+  test("describes task_id as a background task id instead of a session id", () => {
+    // #given
+    const manager: BackgroundOutputManager = {
+      getTask: () => undefined,
+    }
+    const client: BackgroundOutputClient = {
+      session: {
+        messages: async () => ({ data: [] }),
+      },
+    }
+    const tool = createBackgroundOutput(manager, client)
+
+    // #when
+    const taskIdArg = unsafeTestValue<{ description?: string }>(tool.args.task_id)
+
+    // #then
+    expect(taskIdArg.description).toContain("background task ID")
+    expect(taskIdArg.description).toContain("bg_")
+    expect(taskIdArg.description).toContain("not a session ID")
+    expect(taskIdArg.description).toContain("ses_")
+  })
+
   test("omits sessionId metadata when task session is not yet assigned", async () => {
     // #given
     clearPendingStore()

src/tools/background-task/create-background-output.ts

@@ -93,7 +93,9 @@ export function createBackgroundOutput(manager: BackgroundOutputManager, client:
   return tool({
     description: BACKGROUND_OUTPUT_DESCRIPTION,
     args: {
-      task_id: tool.schema.string().describe("Task ID to get output from"),
+      task_id: tool.schema
+        .string()
+        .describe("background task ID (`bg_...`) from launch/completion; not a session ID (`ses_...`)."),
       block: tool.schema
         .boolean()
         .optional()

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"),
 }