From 973548ed37d3814b5897c8c63c5f6535b02da342 Mon Sep 17 00:00:00 2001 From: Kit Langton Date: Wed, 4 Nov 2026 15:29:41 -0800 Subject: [PATCH] feat(core): default the subagent tool to background Foreground becomes background plus a wait: an explicit background=false starts the same job and blocks on it, returning the child result inline. The tool description and docs now lead with background. --- packages/core/src/tool/plugin/subagent.ts | 10 +++--- packages/core/test/tool-subagent.test.ts | 39 ++++++++++++++++------- services/www/src/docs/content/tools.mdx | 5 +-- 3 files changed, 35 insertions(+), 19 deletions(-) diff --git a/packages/core/src/tool/plugin/subagent.ts b/packages/core/src/tool/plugin/subagent.ts index 503c96d2206..4982234ad23 100644 --- a/packages/core/src/tool/plugin/subagent.ts +++ b/packages/core/src/tool/plugin/subagent.ts @@ -43,7 +43,7 @@ export const Input = Schema.Struct({ }), background: Schema.optionalKey(Schema.Boolean).annotate({ description: - "Run the subagent in the background and return immediately. You will be notified when it completes. DO NOT sleep, poll, or proactively check on its progress.", + "Defaults to true: launch the subagent in the background and return immediately, and you are notified when it completes. Set false to run it to completion and return the final response inline; do not sleep, poll, or proactively check on background progress.", }), notify: Schema.optionalKey(Schema.Boolean).annotate({ description: @@ -60,9 +60,9 @@ export const description = [ "Spawns an agent in a child session to work on the specified task.", "The output includes a sessionID you can pass back later to continue that specific conversation with the subagent.", "New child sessions start with fresh context, so include all relevant context and instructions when you don't pass a sessionID.", - "Foreground (default) runs the subagent to completion and returns its final response.", - "Background mode (background=true) launches it asynchronously and returns immediately; you are notified when it finishes.", - "Use background only for independent work that can run while you continue elsewhere.", + "Background mode (default) launches the subagent asynchronously and returns immediately; you are notified when it finishes.", + "Use it for independent work that can run while you continue elsewhere, or briefly tell the user what you launched and end your response.", + "Set background=false to run the subagent to completion and return its final response inline, only when you need the result before your next step.", "Set notify=false to run a background subagent silently when you expect to read its session yourself later.", ].join("\n") @@ -202,7 +202,7 @@ export const Plugin = { ), )) - const background = input.background === true + const background = input.background !== false const notify = input.notify !== false yield* context.progress({ sessionID: child.id, status: "running" }) diff --git a/packages/core/test/tool-subagent.test.ts b/packages/core/test/tool-subagent.test.ts index cf37e473ae8..3c9e15730c4 100644 --- a/packages/core/test/tool-subagent.test.ts +++ b/packages/core/test/tool-subagent.test.ts @@ -1,4 +1,4 @@ -import { describe, expect } from "bun:test" +import { describe, expect, test } from "bun:test" import { Deferred, Effect, Fiber, Layer, Schema, Stream } from "effect" import { LanguageModel } from "@opencode/ai/effect" import { OpenAIChat } from "@opencode/ai/protocols" @@ -407,7 +407,7 @@ describe("SubagentTool", () => { type: "tool-call", id: "call-foreground-completion", name: SubagentTool.name, - input: { agent: "reviewer", description: "foreground review", prompt: "review" }, + input: { agent: "reviewer", description: "foreground review", prompt: "review", background: false }, }, }) expect(result).toMatchObject({ status: "completed", metadata: { status: "completed" } }) @@ -511,7 +511,7 @@ describe("SubagentTool", () => { type: "tool-call", id: "call-configured-nested-subagent", name: SubagentTool.name, - input: { agent: "reviewer", description: "nested", prompt: "should run" }, + input: { agent: "reviewer", description: "nested", prompt: "should run", background: false }, }, }) @@ -550,7 +550,14 @@ describe("SubagentTool", () => { type: "tool-call", id: "call-subagent", name: SubagentTool.name, - input: { agent: "reviewer", description: "review", prompt: "review this", model: "", sessionID: "" }, + input: { + agent: "reviewer", + description: "review", + prompt: "review this", + model: "", + sessionID: "", + background: false, + }, }, }) @@ -580,7 +587,7 @@ describe("SubagentTool", () => { type: "tool-call", id: "call-subagent-fallback", name: SubagentTool.name, - input: { agent: "fallback", description: "fallback", prompt: "fallback" }, + input: { agent: "fallback", description: "fallback", prompt: "fallback", background: false }, }, }) const fallbackChild = yield* sessions.get(outputSessionID(fallback.metadata)) @@ -608,7 +615,7 @@ describe("SubagentTool", () => { type: "tool-call", id: "call-subagent-first", name: SubagentTool.name, - input: { agent: "reviewer", description: "review", prompt: "review this" }, + input: { agent: "reviewer", description: "review", prompt: "review this", background: false }, }, }) const childID = outputSessionID(first.metadata) @@ -625,6 +632,7 @@ describe("SubagentTool", () => { prompt: "continue this", sessionID: childID, model: "", + background: false, }, }, }) @@ -735,7 +743,8 @@ describe("SubagentTool", () => { const launched = yield* followUp("call-launch", { background: true }) const steered = yield* followUp("call-steer", { background: true }) - const unflagged = yield* followUp("call-steer-foreground", {}) + // No flag: background is the default, so it still returns a running handle. + const unflagged = yield* followUp("call-default", {}) ;[launched, steered, unflagged].forEach((result) => expect(result).toMatchObject({ metadata: { sessionID: child.id, status: "running" } }), ) @@ -778,7 +787,7 @@ describe("SubagentTool", () => { type: "tool-call" as const, id, name: SubagentTool.name, - input: { agent, description: "follow up", prompt: "continue", sessionID }, + input: { agent, description: "follow up", prompt: "continue", sessionID, background: false }, }, }) @@ -859,7 +868,7 @@ describe("SubagentTool", () => { type: "tool-call" as const, id, name: SubagentTool.name, - input: { agent: "reviewer", description: "review", prompt: "review this", ...input }, + input: { agent: "reviewer", description: "review", prompt: "review this", background: false, ...input }, }, }) @@ -922,7 +931,7 @@ describe("SubagentTool", () => { type: "tool-call", id: "call-subagent-failure", name: SubagentTool.name, - input: { agent: "reviewer", description: "fail review", prompt: "please fail" }, + input: { agent: "reviewer", description: "fail review", prompt: "please fail", background: false }, }, }), ).toEqual({ @@ -937,7 +946,7 @@ describe("SubagentTool", () => { ), ) - it.live("notifies once when background work completes", () => + it.live("defaults to background and notifies once when the work completes", () => tmpdirScoped().pipe( Effect.flatMap((dir) => Effect.gen(function* () { @@ -962,7 +971,7 @@ describe("SubagentTool", () => { type: "tool-call", id: "call-background-subagent", name: SubagentTool.name, - input: { agent: "reviewer", description: "background review", prompt: "review", background: true }, + input: { agent: "reviewer", description: "background review", prompt: "review" }, }, }) const childID = outputSessionID(settled.metadata) @@ -1106,4 +1115,10 @@ describe("SubagentTool", () => { ), ), ) + + test("describes background as the default mode", () => { + expect(SubagentTool.description).toContain("Background mode (default)") + expect(SubagentTool.description).not.toContain("Foreground (default)") + expect(SubagentTool.description).toContain("Set background=false") + }) }) diff --git a/services/www/src/docs/content/tools.mdx b/services/www/src/docs/content/tools.mdx index 25ee3b0d6c9..88eb6cc7f5a 100644 --- a/services/www/src/docs/content/tools.mdx +++ b/services/www/src/docs/content/tools.mdx @@ -215,8 +215,9 @@ ID, a short `description`, and a complete `prompt`. Ask the explore subagent to map the authentication flow and return the key files. ``` -Foreground calls wait for the result. `background: true` returns immediately -and notifies the parent when the child finishes. Pass the returned `sessionID` +Subagents run in the background by default: the tool returns immediately with a +`sessionID`, and the parent is notified when the child finishes. Set +`background: false` to wait for the result instead. Pass the returned `sessionID` to continue that same child conversation. Only subagent-mode agents can be used, and the default nesting depth is one.