Background Agents Plugin

Async background delegation with persistent results that survive context compaction

Overview

A plugin for OpenCode that enables async background delegation. Fire off research tasks, continue brainstorming or coding, and retrieve results when you need them. Results survive context compaction.

Why This Exists

Context windows fill up. When that happens, compaction kicks in and your AI loses track of research it just did. Background agents solve this:

• Keep working — Delegate research and continue your conversation.
• Survive compaction — Results are saved to disk as markdown.
• Fire and forget — A notification arrives when your research is ready.

Installation

ocx add kdco/background-agents --from https://registry.kdco.dev

Or install the full Workspace bundle:

ocx add kdco/workspace --from https://registry.kdco.dev

How It Works

1. Delegate    →  "Research OAuth2 PKCE best practices"
2. Continue    →  Keep coding, brainstorming, reviewing
3. Notified    →  <task-notification> arrives on terminal state
4. Retrieve    →  AI calls delegation_read() to get the result

Results are persisted to ~/.local/share/opencode/delegations/ as markdown files. Each delegation is automatically tagged with a title and summary.

Lifecycle Behavior

The plugin now follows Claude Code’s background-agent lifecycle as closely as possible within plugin boundaries:

• Stable task IDs across in-memory state, markdown artifact filename, notifications, and retrieval.
• Explicit lifecycle transitions (registered → running → terminal state).
• Terminal-state protection (late progress/idle events cannot overwrite terminal status).
• Persistence-before-notify (terminal markdown artifact is written before model-facing completion notification).
• Blocking retrieval (delegation_read(id) waits for terminal/timeout, then returns persisted output or deterministic terminal info).
• Compaction carry-forward for running and unread completed delegations with retrieval instructions.

Tools

Tool	Purpose
delegate(prompt, agent)	Launch a background task
delegation_read(id)	Retrieve a specific result
delegation_list()	List all delegations with titles and summaries

Limitations

Read-Only Sub-Agents Only

Only read-only sub-agents (permissions: edit=deny, write=deny, bash={"*":"deny"}) can use delegate. Any write-capable sub-agent (any write/edit/bash allow) must use the native task tool.

Why? Background delegations run in isolated sessions outside OpenCode’s session tree. The undo/branching system cannot track changes made in background sessions.

Timeout

Delegations timeout after 15 minutes.

Claude Parity Boundaries

This is plugin-level parity, not runtime-internal parity. The plugin does not reproduce OpenCode/Claude runtime internals such as:

• internal AppState/task queue processors
• runtime notification priority controls
• write-capable background sessions with native undo/branching parity

Write-capable sub-agents still use native task. Read-only sub-agents use delegate.

Real-Time Monitoring

View active and completed sub-agents using OpenCode’s navigation shortcuts:

Shortcut	Action
Ctrl+X Up	Jump to parent session
Ctrl+X Left	Previous sub-agent
Ctrl+X Right	Next sub-agent

See Also

• Workspace Integration — Full multi-agent workspace bundle.
• Notify Plugin — Get notified when delegations complete.
• Worktree Plugin — Isolated development environments.
• KDCO Workspace Guide — Installation walkthrough.