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.
This commit is contained in:
Kit Langton
2026-11-04 15:29:41 -08:00
Unverified
parent 4d5cb17bbb
commit 973548ed37
3 changed files with 35 additions and 19 deletions
+5 -5
View File
@@ -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" })
+27 -12
View File
@@ -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")
})
})
+3 -2
View File
@@ -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.