Apply PR #24174: feat(core): add background subagent support

Author: opencode-agent[bot]

packages/opencode/src/cli/cmd/tui/routes/session/index.tsx

@@ -1997,7 +1997,9 @@ function Task(props: ToolProps<typeof TaskTool>) {
 
   const content = createMemo(() => {
     if (!props.input.description) return ""
-    let content = [`${Locale.titlecase(props.input.subagent_type ?? "General")} Task — ${props.input.description}`]
+    const description =
+      props.metadata.background === true ? `${props.input.description} (background)` : props.input.description
+    let content = [`${Locale.titlecase(props.input.subagent_type ?? "General")} Task — ${description}`]
 
     if (isRunning() && tools().length > 0) {
       // content[0] += ` · ${tools().length} toolcalls`

packages/opencode/src/session/prompt.ts

@@ -118,6 +118,10 @@ export const layer = Layer.effect(
         cancel: (sessionID: SessionID) => run.fork(cancel(sessionID)),
         resolvePromptParts: (template: string) => resolvePromptParts(template),
         prompt: (input: PromptInput) => prompt(input),
+        loop: (input: LoopInput) => loop(input),
+        fork: (effect: Effect.Effect<void, never, never>) => {
+          run.fork(effect)
+        },
       } satisfies TaskPromptOps
     })
 

packages/opencode/src/tool/registry.ts

@@ -7,6 +7,7 @@ import { GlobTool } from "./glob"
 import { GrepTool } from "./grep"
 import { ReadTool } from "./read"
 import { TaskTool } from "./task"
+import { TaskStatusTool } from "./task_status"
 import { TodoWriteTool } from "./todo"
 import { WebFetchTool } from "./webfetch"
 import { WriteTool } from "./write"
@@ -49,6 +50,7 @@ import { Agent } from "../agent/agent"
 import { Git } from "@/git"
 import { Skill } from "../skill"
 import { Permission } from "@/permission"
+import { SessionStatus } from "@/session/status"
 
 const log = Log.create({ service: "tool.registry" })
 
@@ -81,6 +83,7 @@ export const layer: Layer.Layer<
   | Agent.Service
   | Skill.Service
   | Session.Service
+  | SessionStatus.Service
   | Provider.Service
   | Git.Service
   | LSP.Service
@@ -119,6 +122,7 @@ export const layer: Layer.Layer<
     const greptool = yield* GrepTool
     const patchtool = yield* ApplyPatchTool
     const skilltool = yield* SkillTool
+    const taskstatus = yield* TaskStatusTool
     const agent = yield* Agent.Service
 
     const state = yield* InstanceState.make<State>(
@@ -199,6 +203,7 @@ export const layer: Layer.Layer<
           edit: Tool.init(edit),
           write: Tool.init(writetool),
           task: Tool.init(task),
+          taskstatus: Tool.init(taskstatus),
           fetch: Tool.init(webfetch),
           todo: Tool.init(todo),
           search: Tool.init(websearch),
@@ -223,6 +228,7 @@ export const layer: Layer.Layer<
             tool.edit,
             tool.write,
             tool.task,
+            tool.taskstatus,
             tool.fetch,
             tool.todo,
             tool.search,
@@ -341,6 +347,7 @@ export const defaultLayer = Layer.suspend(() =>
     Layer.provide(Skill.defaultLayer),
     Layer.provide(Agent.defaultLayer),
     Layer.provide(Session.defaultLayer),
+    Layer.provide(SessionStatus.defaultLayer),
     Layer.provide(Provider.defaultLayer),
     Layer.provide(Git.defaultLayer),
     Layer.provide(LSP.defaultLayer),

packages/opencode/src/tool/task.ts

@@ -1,17 +1,22 @@
 import * as Tool from "./tool"
 import DESCRIPTION from "./task.txt"
 import { Session } from "@/session/session"
+import { Bus } from "../bus"
 import { SessionID, MessageID } from "../session/schema"
 import { MessageV2 } from "../session/message-v2"
 import { Agent } from "../agent/agent"
 import type { SessionPrompt } from "../session/prompt"
 import { Config } from "@/config/config"
-import { Effect, Schema } from "effect"
+import { SessionStatus } from "../session/status"
+import { TuiEvent } from "@/cli/cmd/tui/event"
+import { Cause, Effect, Option, Schema } from "effect"
 
 export interface TaskPromptOps {
   cancel(sessionID: SessionID): void
   resolvePromptParts(template: string): Effect.Effect<SessionPrompt.PromptInput["parts"]>
   prompt(input: SessionPrompt.PromptInput): Effect.Effect<MessageV2.WithParts>
+  loop(input: SessionPrompt.LoopInput): Effect.Effect<MessageV2.WithParts>
+  fork(effect: Effect.Effect<void, never, never>): void
 }
 
 const id = "task"
@@ -20,24 +25,65 @@ export const Parameters = Schema.Struct({
   description: Schema.String.annotate({ description: "A short (3-5 words) description of the task" }),
   prompt: Schema.String.annotate({ description: "The task for the agent to perform" }),
   subagent_type: Schema.String.annotate({ description: "The type of specialized agent to use for this task" }),
-  task_id: Schema.optional(Schema.String).annotate({
+  task_id: Schema.optional(SessionID).annotate({
     description:
       "This should only be set if you mean to resume a previous task (you can pass a prior task_id and the task will continue the same subagent session as before instead of creating a fresh one)",
   }),
   command: Schema.optional(Schema.String).annotate({ description: "The command that triggered this task" }),
+  background: Schema.optional(Schema.Boolean).annotate({
+    description: "When true, launch the subagent in the background and return immediately",
+  }),
 })
 
+function output(sessionID: SessionID, text: string) {
+  return [
+    `task_id: ${sessionID} (for resuming to continue this task if needed)`,
+    "",
+    "<task_result>",
+    text,
+    "</task_result>",
+  ].join("\n")
+}
+
+function backgroundOutput(sessionID: SessionID) {
+  return [
+    `task_id: ${sessionID} (for polling this task with task_status)`,
+    "state: running",
+    "",
+    "<task_result>",
+    "Background task started. Continue your current work and call task_status when you need the result.",
+    "</task_result>",
+  ].join("\n")
+}
+
+function backgroundMessage(input: { sessionID: SessionID; description: string; state: "completed" | "error"; text: string }) {
+  const tag = input.state === "completed" ? "task_result" : "task_error"
+  const title =
+    input.state === "completed"
+      ? `Background task completed: ${input.description}`
+      : `Background task failed: ${input.description}`
+  return [title, `task_id: ${input.sessionID}`, `state: ${input.state}`, `<${tag}>`, input.text, `</${tag}>`].join(
+    "\n",
+  )
+}
+
+function errorText(error: unknown) {
+  if (error instanceof Error) return error.message
+  return String(error)
+}
+
 export const TaskTool = Tool.define(
   id,
   Effect.gen(function* () {
     const agent = yield* Agent.Service
+    const bus = yield* Bus.Service
     const config = yield* Config.Service
     const sessions = yield* Session.Service
+    const status = yield* SessionStatus.Service
 
-    const run = Effect.fn("TaskTool.execute")(function* (
-      params: Schema.Schema.Type<typeof Parameters>,
-      ctx: Tool.Context,
-    ) {
+    const run = Effect.fn(
+      "TaskTool.execute",
+    )(function* (params: Schema.Schema.Type<typeof Parameters>, ctx: Tool.Context) {
       const cfg = yield* config.get()
 
       if (!ctx.extra?.bypassAgentCheck) {
@@ -62,7 +108,7 @@ export const TaskTool = Tool.define(
 
       const taskID = params.task_id
       const session = taskID
-        ? yield* sessions.get(SessionID.make(taskID)).pipe(Effect.catchCause(() => Effect.succeed(undefined)))
+        ? yield* sessions.get(taskID).pipe(Effect.catchCause(() => Effect.succeed(undefined)))
         : undefined
       const parent = yield* sessions.get(ctx.sessionID)
       const nextSession =
@@ -107,19 +153,107 @@ export const TaskTool = Tool.define(
         modelID: msg.info.modelID,
         providerID: msg.info.providerID,
       }
+      const parentModel = {
+        modelID: msg.info.modelID,
+        providerID: msg.info.providerID,
+      }
+      const background = params.background === true
+
+      const metadata = {
+        sessionId: nextSession.id,
+        model,
+        ...(background ? { background: true } : {}),
+      }
 
       yield* ctx.metadata({
         title: params.description,
-        metadata: {
-          sessionId: nextSession.id,
-          model,
-        },
+        metadata,
       })
 
       const ops = ctx.extra?.promptOps as TaskPromptOps
       if (!ops) return yield* Effect.fail(new Error("TaskTool requires promptOps in ctx.extra"))
 
-      const messageID = MessageID.ascending()
+      const runTask = Effect.fn("TaskTool.runTask")(function* () {
+        const parts = yield* ops.resolvePromptParts(params.prompt)
+        const result = yield* ops.prompt({
+          messageID: MessageID.ascending(),
+          sessionID: nextSession.id,
+          model: {
+            modelID: model.modelID,
+            providerID: model.providerID,
+          },
+          agent: next.name,
+          tools: {
+            ...(canTodo ? {} : { todowrite: false }),
+            ...(canTask ? {} : { task: false }),
+            ...Object.fromEntries((cfg.experimental?.primary_tools ?? []).map((item) => [item, false])),
+          },
+          parts,
+        })
+        return result.parts.findLast((item) => item.type === "text")?.text ?? ""
+      })
+
+      const continueIfIdle = Effect.fn("TaskTool.continueIfIdle")(function* (input: {
+        userID: MessageID
+        state: "completed" | "error"
+      }) {
+        if ((yield* status.get(ctx.sessionID)).type !== "idle") return
+        const latest = yield* sessions.findMessage(ctx.sessionID, (item) => item.info.role === "user")
+        if (Option.isNone(latest)) return
+        if (latest.value.info.id !== input.userID) return
+        yield* bus.publish(TuiEvent.ToastShow, {
+          title: input.state === "completed" ? "Background task complete" : "Background task failed",
+          message:
+            input.state === "completed"
+              ? `Background task \"${params.description}\" finished. Resuming the main thread.`
+              : `Background task \"${params.description}\" failed. Resuming the main thread.`,
+          variant: input.state === "completed" ? "success" : "error",
+          duration: 5000,
+        })
+        yield* ops.loop({ sessionID: ctx.sessionID }).pipe(Effect.ignore)
+      })
+
+      if (background) {
+        const inject = Effect.fn("TaskTool.injectBackgroundResult")(function* (state: "completed" | "error", text: string) {
+          const message = yield* ops.prompt({
+            sessionID: ctx.sessionID,
+            noReply: true,
+            model: parentModel,
+            agent: ctx.agent,
+            parts: [
+              {
+                type: "text",
+                synthetic: true,
+                text: backgroundMessage({
+                  sessionID: nextSession.id,
+                  description: params.description,
+                  state,
+                  text,
+                }),
+              },
+            ],
+          })
+          yield* continueIfIdle({ userID: message.info.id, state })
+        })
+
+        ops.fork(
+          runTask().pipe(
+            Effect.matchCauseEffect({
+              onSuccess: (text) => inject("completed", text),
+              onFailure: (cause) =>
+                inject("error", errorText(Cause.squash(cause))).pipe(Effect.catchCause(() => Effect.void)),
+            }),
+            Effect.catchCause(() => Effect.void),
+            Effect.asVoid,
+          ),
+        )
+
+        return {
+          title: params.description,
+          metadata,
+          output: backgroundOutput(nextSession.id),
+        }
+      }
 
       function cancel() {
         ops.cancel(nextSession.id)
@@ -131,50 +265,24 @@ export const TaskTool = Tool.define(
         }),
         () =>
           Effect.gen(function* () {
-            const parts = yield* ops.resolvePromptParts(params.prompt)
-            const result = yield* ops.prompt({
-              messageID,
-              sessionID: nextSession.id,
-              model: {
-                modelID: model.modelID,
-                providerID: model.providerID,
-              },
-              agent: next.name,
-              tools: {
-                ...(canTodo ? {} : { todowrite: false }),
-                ...(canTask ? {} : { task: false }),
-                ...Object.fromEntries((cfg.experimental?.primary_tools ?? []).map((item) => [item, false])),
-              },
-              parts,
-            })
-
+            const text = yield* runTask()
             return {
               title: params.description,
-              metadata: {
-                sessionId: nextSession.id,
-                model,
-              },
-              output: [
-                `task_id: ${nextSession.id} (for resuming to continue this task if needed)`,
-                "",
-                "<task_result>",
-                result.parts.findLast((item) => item.type === "text")?.text ?? "",
-                "</task_result>",
-              ].join("\n"),
+              metadata,
+              output: output(nextSession.id, text),
             }
           }),
         () =>
           Effect.sync(() => {
             ctx.abort.removeEventListener("abort", cancel)
           }),
       )
-    })
+    }, Effect.orDie)
 
     return {
       description: DESCRIPTION,
       parameters: Parameters,
-      execute: (params: Schema.Schema.Type<typeof Parameters>, ctx: Tool.Context) =>
-        run(params, ctx).pipe(Effect.orDie),
+      execute: run,
     }
   }),
 )

packages/opencode/src/tool/task.txt

@@ -14,11 +14,13 @@ When NOT to use the Task tool:
 
 Usage notes:
 1. Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses
-2. When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result. The output includes a task_id you can reuse later to continue the same subagent session.
-3. Each agent invocation starts with a fresh context unless you provide task_id to resume the same subagent session (which continues with its previous messages and tool outputs). When starting fresh, your prompt should contain a highly detailed task description for the agent to perform autonomously and you should specify exactly what information the agent should return back to you in its final and only message to you.
-4. The agent's outputs should generally be trusted
-5. Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, web fetches, etc.), since it is not aware of the user's intent. Tell it how to verify its work if possible (e.g., relevant test commands).
-6. If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first. Use your judgement.
+2. By default, task waits for completion and returns the result immediately, along with a task_id you can reuse later to continue the same subagent session.
+3. Set background=true to launch asynchronously. In background mode, continue your current work without waiting.
+4. For background runs, use task_status(task_id=..., wait=false) to poll, or wait=true to block until done (optionally with timeout_ms).
+5. Each agent invocation starts with a fresh context unless you provide task_id to resume the same subagent session (which continues with its previous messages and tool outputs). When starting fresh, your prompt should contain a highly detailed task description for the agent to perform autonomously and you should specify exactly what information the agent should return back to you in its final and only message to you.
+6. The agent's outputs should generally be trusted
+7. Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, web fetches, etc.), since it is not aware of the user's intent. Tell it how to verify its work if possible (e.g., relevant test commands).
+8. If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first. Use your judgement.
 
 Example usage (NOTE: The agents below are fictional examples for illustration only - use the actual agents listed above):