Add background agent task tools for concurrent sub-agent dispatch (#863) by jfrey · Pull Request #1908 · docker/cagent

jfrey · 2026-03-03T21:17:43Z

Summary

Implements concurrent sub-agent orchestration from #863 by adding a family of four background agent tools that mirror the existing shell background job pattern (run_background_job / list_background_jobs / etc.):

run_background_agent — dispatch a named sub-agent task asynchronously, returns a task ID immediately
list_background_agents — show all tasks with status and runtime
view_background_agent — inspect live buffered output or final result by task ID
stop_background_agent — cancel a running task

Tools are registered automatically for any agent that has sub_agents configured, alongside the existing transfer_task tool.

Key design decisions

Async / fire-and-forget — caller gets a task ID back immediately and polls with view_background_agent, matching the UX of shell background jobs the LLM already knows
ToolsApproved=true for background sessions — no user present to answer approval prompts; documented with a TODO for per-session permission scoping
Resource caps — max 20 concurrent tasks, 100 total; completed tasks auto-pruned when cap is approached; live output buffer capped at 10 MB per task

Notable fixes applied during review

Agent identity (SEC-003): goroutine now calls setCurrentAgent(params.Agent) before RunStream so the background task uses the sub-agent's model/tools/RAG rather than the parent's
Elicitation channel race (SEC-002): setElicitationEventsChannel / clearElicitationEventsChannel are now guarded with !sess.ToolsApproved so background task teardown doesn't null out the parent session's pending MCP auth channel
currentAgent data race: added currentAgentMu sync.RWMutex with getter/setter; all 26 read sites updated
concurrent.Map Range/Delete deadlock: two-pass delete in pruneCompleted
CAS completion race: CompareAndSwap(running, completed) prevents overwriting a stopped status
sync.WaitGroup in stopAll for clean goroutine shutdown

Known limitations (tracked as TODOs in code)

Concurrent background tasks still race on the shared currentAgent field — proper fix requires passing the agent through the session rather than shared runtime state
RunStream has other shared fields (registerDefaultTools map, resumeChan) that are unsafe for truly concurrent calls — documented in code

Test plan

35 unit tests in pkg/runtime/background_agent_test.go covering all four handlers, caps, error paths, and concurrent access
Run with race detector: go test -race ./pkg/runtime/ -run TestHandler_Concurrent
Manual test: build ./cagent and exercise background agent dispatch in a team with sub-agents configured

🤖 Generated with Claude Code

Introduces four new built-in tools available to any agent with sub_agents, mirroring the existing run_background_job/view_background_job shell tool pattern: - run_background_agent: dispatch a sub-agent task asynchronously, returns a task ID - list_background_agents: list all background agent tasks with status and runtime - view_background_agent: view live output or final result of a task by ID - stop_background_agent: cancel a running task via context cancellation This enables an orchestrating agent to fan out work to multiple sub-agents concurrently, check in on progress, and collect results when ready — without blocking on each sub-agent sequentially. Closes docker#863 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

R001 - Fix data race on r.currentAgent: add currentAgentMu RWMutex, thread-safe CurrentAgentName()/setCurrentAgent() accessors, update all 26 read/write sites in runtime.go. R002 - Add 21 tests covering task lifecycle, all four handler methods, input validation, concurrency cap enforcement, and goroutine cleanup. R003 - Remove ReadOnlyHint:true from run_background_agent; the tool spawns agents that can execute write operations. R004 - Fix completed task memory leak: pruneCompleted() collects IDs in a first pass then deletes to avoid holding Range lock during Delete. R005 - Enforce maxConcurrentAgentTasks (20) and maxTotalAgentTasks (100) caps with clear error messages. R006 - Add sync.WaitGroup to backgroundAgentHandler; stopAll() now waits for all goroutines to exit before returning. R007 - Background tasks run with WithToolsApproved(true); they execute asynchronously with no user present to respond to approval prompts. R008 - Call sess.AddSubSession(s) on completion for cost/token tracking. Also: use crypto/rand for non-guessable task IDs; store actual error message from ErrorEvent in task.errMsg. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

SEC-003: set currentAgent to sub-agent before RunStream in the background goroutine so it uses the correct model, tools, and RAG config rather than the parent agent's identity. SEC-002: guard setElicitationEventsChannel / clearElicitationEventsChannel with !sess.ToolsApproved so background tasks (which never need elicitation) don't overwrite or null out the parent session's pending MCP auth channel. Tests: add concurrent-access test (race detector), output buffer truncation test, and dead-code documentation test for the non-prunable total cap path. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Lint: - context.Background() → t.Context() in all test functions (forbidigo) - for loops converted to integer range form (intrange, Go 1.22+) - toolCall() pre-computed in main goroutine before spawning goroutines to avoid require.FailNow from non-test goroutines (testifylint) - newRuntimeWithSubAgent unused *agent.Agent return removed (unparam) - gofmt: align map keys to longest entry in registerDefaultTools - teamloader: combine two consecutive appends into one (gocritic) E2E: - Update TestA2AServer_MultiAgent cassette to include the four new background agent tools in the recorded request body; the root agent in multi.yaml has sub_agents configured so it now receives all five tools Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

dgageot

LGTM in general! Sorry, I left a few nit-picky comments. Feel free to ignore.
One of the things that could be better is that most of the code lives in the runtime package that we wish would be simpler. Do you think most of it could be extracted?

dgageot · 2026-03-03T21:27:31Z

pkg/runtime/background_agent.go

+const (
+	agentTaskRunning   int32 = iota
+	agentTaskCompleted int32 = iota
+	agentTaskStopped   int32 = iota
+	agentTaskFailed    int32 = iota
+)


Suggested change

const (

agentTaskRunning int32 = iota

agentTaskCompleted int32 = iota

agentTaskStopped int32 = iota

agentTaskFailed int32 = iota

)

const (

agentTaskRunning int32 = iota

agentTaskCompleted

agentTaskStopped

agentTaskFailed

)

dgageot · 2026-03-03T21:28:22Z

pkg/runtime/background_agent.go

+
+// agent task status constants — mirrors backgroundJob in shell.go
+const (
+	agentTaskRunning   int32 = iota


We should maybe introduce a type for the enum rather than int32?

dgageot · 2026-03-03T21:30:12Z

pkg/runtime/background_agent.go

+}
+
+// newTaskID generates a unique, non-guessable ID for a background agent task.
+func newTaskID() (string, error) {


Maybe use github.com/google/uuid?

dgageot · 2026-03-03T21:31:23Z

pkg/runtime/background_agent.go

+
+// runningTaskCount returns the number of currently running tasks.
+func (h *backgroundAgentHandler) runningTaskCount() int {
+	count := 0


Suggested change

count := 0

var count int

dgageot · 2026-03-04T12:41:00Z

docs/plans/parallel-task-863.md

@@ -0,0 +1,179 @@
+# Plan: Background Agent Tasks (Issue #863)


FWIW, we usually try to avoid committing those plans

jfrey and others added 4 commits March 3, 2026 10:31

dgageot reviewed Mar 4, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add background agent task tools for concurrent sub-agent dispatch (#863)#1908

Add background agent task tools for concurrent sub-agent dispatch (#863)#1908
jfrey wants to merge 4 commits intodocker:mainfrom
jfrey:feature/parallel-task-863

jfrey commented Mar 3, 2026

Uh oh!

dgageot left a comment

Uh oh!

dgageot Mar 3, 2026

Uh oh!

dgageot Mar 3, 2026

Uh oh!

dgageot Mar 3, 2026

Uh oh!

dgageot Mar 3, 2026

Uh oh!

dgageot Mar 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		@@ -0,0 +1,179 @@
		# Plan: Background Agent Tasks (Issue #863)

Conversation

jfrey commented Mar 3, 2026

Summary

Key design decisions

Notable fixes applied during review

Known limitations (tracked as TODOs in code)

Test plan

Uh oh!

dgageot left a comment

Choose a reason for hiding this comment

Uh oh!

dgageot Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

dgageot Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

dgageot Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

dgageot Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

dgageot Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants