Summary

Fix 3 contract mismatches between delegate-task background output metadata and OpenCode TUI's Task component expectations, preventing broken session syncing and ambiguous task ID semantics.

Problem

When delegate-task launches a background task, the output metadata sent to OpenCode's TUI had several issues:

1. Fake sessionId: "pending" — When the background manager hasn't resolved the subagent session yet, we emitted metadata.sessionId = "pending", causing TUI to call sync.session.sync("pending") on a non-existent session.
2. Missing task_id field — OpenCode's built-in task tool emits task_id: <sessionId> in its output, but our background path omitted it entirely.
3. Ambiguous task_id semantics — Our background flow has two distinct IDs (background manager task ID vs session ID), but the output conflated them.

Root Cause Analysis (with OpenCode source references)

TUI Contract: metadata.sessionId

OpenCode's TUI Task component uses props.metadata.sessionId to sync the child session and count toolcalls:

• Sync trigger (index.tsx:1952-1955):

  onMount(() => {
    if (props.metadata.sessionId && !sync.data.message[props.metadata.sessionId]?.length)
      sync.session.sync(props.metadata.sessionId)
  })

• Toolcall counting (index.tsx:1957-1965):

  const messages = createMemo(() => sync.data.message[props.metadata.sessionId ?? ""] ?? [])
  const tools = createMemo(() => {
    return messages().flatMap((msg) =>
      (sync.data.part[msg.id] ?? [])
        .filter((part): part is ToolPart => part.type === "tool")
        .map((part) => ({ tool: part.tool, state: part.state })),
    )
  })

TUI Contract: task_id output

OpenCode's built-in task tool emits task_id: <sessionId> as a session resumption key (task.ts:147-153):

`task_id: ${session.id} (for resuming to continue this task if needed)`,
"",
"<task_result>",
result,
"</task_result>",

TUI Permission rendering

TUI permission dialog reads data.subagent_type for task display (permission.tsx:300-313).

Changes

Commit 1: fix(task): avoid pending sessionId metadata in background delegate output

• Problem: metadata.sessionId was set to "pending" when session wasn't yet created, causing TUI sync failures.
• Fix: Only include sessionId in metadata when a real session ID is available. Conditionally emit <task_metadata> block.
• Files: src/tools/delegate-task/background-task.ts, src/tools/delegate-task/background-task.test.ts (new)

Commit 2: fix(task): align background output task_id with opencode contract

• Problem: Output lacked task_id field that OpenCode's TUI and agents expect for session resumption.
• Fix: Add task_id: <sessionId> to <task_metadata> block (matching upstream contract). Rename human-readable label to Background Task ID to distinguish from session-based task_id.
• Files: same as above

Commit 3: fix(task): disambiguate background task_id metadata

• Problem: task_id (session ID) vs background manager task ID were ambiguous in output.
• Fix: Add background_task_id: <bg_task_id> to <task_metadata> block alongside task_id: <sessionId>, making both IDs explicit.
• Files: same as above

Test Coverage

New test file src/tools/delegate-task/background-task.test.ts with 3 test cases:

Verification

• bun test src/tools/delegate-task/background-task.test.ts src/tools/delegate-task/tools.test.ts — 112 pass, 0 fail
• bun run typecheck — clean
• bun run build — clean

Summary by cubic

Aligns delegate-task background output with OpenCode TUI’s Task contract to fix session syncing and clarify task ID semantics. Background output now emits session metadata only when a real or late-resolved session is available and distinguishes between session and background task IDs.

• Bug Fixes
  • Stop emitting metadata.sessionId="pending"; only include sessionId when resolved (including late-resolved via polling).
  • Emit <task_metadata> only when sessionId is present; add task_id: to match TUI’s resume contract.
  • Add background_task_id: <bg_task_id> and rename visible label to “Background Task ID” to avoid confusion.

^{Written for commit 39d94a4. Summary will update on new commits.}