Background Agents

Relevant source files

The following files were used as context for generating this wiki page:

• facades/opencode-background-agents/README.md
• workers/kdco-registry/files/plugin/workspace-plugin.ts
• workers/kdco-registry/files/agent/researcher.md
• workers/kdco-registry/files/agent/coder.md
• workers/kdco-registry/files/skill/plan-protocol/SKILL.md
• workers/kdco-registry/README.md
• facades/opencode-workspace/README.md

Background Agents enable asynchronous delegation within the OpenCode environment, allowing specialist agents to perform research and complex tasks without blocking the main orchestrator or the user. This system addresses the issue of context window compaction by persisting research results to disk as markdown, ensuring findings survive session restarts or context clearing.

Sources: facades/opencode-background-agents/README.md:5-13, facades/opencode-workspace/README.md:37-43

Core Mechanism: The Waiter Model

The Background Agent system operates on a "waiter model." Instead of following a sub-agent through its execution, the orchestrator delegates a task and continues its primary workflow (brainstorming, coding, or architecture discussion). Once the background task is finished, the orchestrator is notified via a system reminder and can retrieve the results.

Sources: facades/opencode-background-agents/README.md:16-32

The diagram above illustrates the asynchronous flow between the primary orchestrator and the background process, highlighting the persistence layer that prevents data loss during context compaction.
Sources: facades/opencode-background-agents/README.md:34-40, workers/kdco-registry/files/plugin/workspace-plugin.ts:400-415

Toolset and API

The background delegation system provides a specific set of tools to the orchestrator to manage and retrieve asynchronous work.

Tool	Purpose	Key Parameters
delegate	Launches a background task in an isolated session.	prompt, agent
delegation_read	Retrieves the full markdown results of a specific task.	id
delegation_list	Lists all past delegations with their titles and summaries.	N/A

Sources: facades/opencode-background-agents/README.md:46-52

Result Persistence

Findings are persisted to ~/.local/share/opencode/delegations/ as markdown files. This ensures that even if a session crashes or the context window is compacted, the orchestrator can still access the research results using the delegation_read() tool.
Sources: facades/opencode-background-agents/README.md:41-43, facades/opencode-background-agents/README.md:85-88

Agent Roles and Scope

In the Background Agent architecture, agents are strictly categorized based on their capabilities and access levels.

Specialist Agent Boundaries

• Researcher Agent: Focused on external knowledge gathering (documentation, APIs, web search). It is read-only and cannot modify the local filesystem.
• Coder Agent: Technical implementation specialist. It has full file and bash access but is forbidden from performing external research.
• Explore Agent: Internal codebase specialist. It performs git and filesystem inspection but cannot access external resources.

Sources: workers/kdco-registry/files/agent/researcher.md:14-17, workers/kdco-registry/files/agent/coder.md:21-28, workers/kdco-registry/files/plugin/workspace-plugin.ts:315-325

The flowchart demonstrates the strict boundaries between internal and external specialists and how the orchestrator interacts with them.
Sources: facades/opencode-workspace/README.md:20-33, workers/kdco-registry/files/plugin/workspace-plugin.ts:340-360

Implementation Planning and Citations

The Background Agent system is deeply integrated with the plan-protocol skill. Orchestrators must cite research findings in their implementation plans using unique delegation IDs.

Citation Format

When research informs an architectural decision or task, the orchestrator appends the delegation ID:
ref:word-word-word (e.g., ref:swift-amber-falcon).

Plan Schema Rules

The workspace-plugin enforces plan validity, requiring citations for any choices based on background research. The plugin also tracks "current" tasks to ensure only one task is active at any time.

Sources: workers/kdco-registry/files/skill/plan-protocol/SKILL.md:110-120, workers/kdco-registry/files/plugin/workspace-plugin.ts:16-30

// Sources: [workers/kdco-registry/files/plugin/workspace-plugin.ts:24-29]
const TaskSchema = z.object({
	id: z.string().regex(/^\d+\.\d+$/, "Task ID must be hierarchical"),
	checked: z.boolean(),
	content: z.string().min(1),
	isCurrent: z.boolean().optional(),
	citation: z.string().regex(/^ref:[a-z]+-[a-z]+-[a-z]+$/).optional(),
})

Constraints and Technical Limitations

• Read-Only Restriction: Only read-only agents like researcher and explore can use the delegate tool. Agents capable of writing to the filesystem (coder, scribe) must use the native task tool to ensure the undo/branching system can track changes.
• Timeout: Background delegations are subject to a 15-minute timeout.
• Isolated Sessions: Background tasks run in entirely separate session trees, meaning they do not share the same context window as the main orchestrator until the results are explicitly retrieved.

Sources: facades/opencode-background-agents/README.md:58-69, facades/opencode-background-agents/README.md:73

Background Agents provide a scalable way to manage complex AI development workflows by offloading intensive research tasks to specialized, asynchronous sub-processes that persist their findings for long-term reliability.