AGENTS.md

1# src/tools/delegate-task/ — Task Delegation Engine
2 
3**Generated:** 2026-05-15
4 
5## OVERVIEW
6 
7The `task` tool implementation delegates work to subagents via background or sync sessions. It resolves categories, models, skills, and manages both async and synchronous execution flows. Harness-neutral task selection and retry primitives are extracted to [`packages/delegate-core/`](../../../../../packages/delegate-core); this directory keeps OpenCode session/tool execution wiring. Built-in categories are defined alongside user category overrides.
8 
9## TWO EXECUTION MODES
10 
11| Mode | Flow | Use Case |
12|------|------|----------|
13| **Background** (`run_in_background=true`) | Launch → BackgroundManager → poll → notify parent | Explore, librarian, parallel work |
14| **Sync** (`run_in_background=false`) | Create session → send prompt → poll until idle → return result | Sequential tasks needing immediate result |
15 
16## KEY FILES
17 
18| File | Purpose |
19|------|---------|
20| `tools.ts` | `createDelegateTask()` factory — main entry point |
21| `executor.ts` | Route to background or sync execution |
22| `types.ts` | `DelegateTaskArgs`, `DelegateTaskToolOptions`, `ToolContextWithMetadata` |
23| `category-resolver.ts` | Map category name → model + config |
24| `subagent-resolver.ts` | Map subagent_type → agent + model |
25| `model-selection.ts` | Model availability checking + fallback |
26| `skill-resolver.ts` | Resolve `load_skills[]` → skill content for injection |
27| `prompt-builder.ts` | Build system/user prompt with skill content, categories |
28 
29## SYNC EXECUTION CHAIN
30 
31```
32sync-task.ts → sync-session-creator.ts → sync-prompt-sender.ts → sync-session-poller.ts → sync-result-fetcher.ts
33```
34 
35Each file handles one step. `sync-continuation.ts` handles session continuation (resume with task_id).
36 
37## BACKGROUND EXECUTION
38 
39```
40background-task.ts → BackgroundManager.launch() → (async polling) → background-continuation.ts
41```
42 
43`background-continuation.ts` handles `task_id` resume for existing background tasks.
44 
45## CATEGORY RESOLUTION
46 
471. Check user-defined categories (`pluginConfig.categories`)
482. Fall back to built-in 8 categories
493. Resolve model from category config
504. Check model availability → fallback if unavailable
51 
52## MODEL STRING PARSER
53 
54`model-string-parser.ts` handles `"model variant"` format (e.g., `"gpt-5.5 medium"` → model=`gpt-5.5`, variant=`medium`).
55 
56## UNSTABLE AGENT TRACKING
57 
58`unstable-agent-task.ts` marks tasks from categories/agents known to be unstable (e.g., free models). Enables `unstableAgentBabysitter` hook monitoring.
59