glm-5.1
9342dab70c
The built-in OpenCode 'task' tool spawns subagents for work delegation. Naming our plugin 'tasks' would create confusion with two 'task' tools that do completely different things. 'taskgraph' matches the core library, clearly differentiates from the built-in, and describes what the tool actually does. The dispatch field is renamed from 'tool' to 'op' (operation) to avoid collision with OpenCode's 'tool' terminology and match the Rust CLI's subcommand pattern. ADR-001 rewritten for taskgraph/op naming and Zod/TypeBox distinction. ADR-007 added documenting the naming decision and the three 'task' concepts (task, todowrite, taskgraph). Research reports added: - docs/research/opencode-task-tool-deep-dive.md - docs/research/open-coordinator-deep-dive.md Also: fixed SDD process link, resolved open question about 'show' including full body, added todowrite to relationship table, clarified Zod vs TypeBox roles, changed FileSource to async scan.
3.3 KiB
status, last_updated
| status | last_updated |
|---|---|
| draft | 2026-04-28 |
ADR-007: Tool Naming — taskgraph not tasks
Context
OpenCode has a built-in task tool that spawns subagents for work delegation. It creates child sessions, dispatches prompts to specialized agents, and returns results. It is deeply wired into the session, permission, and UI systems.
Our plugin was initially named tasks (plural), which creates three problems:
-
Naming confusion:
task(spawning) vstasks(analysis) — both deal with "tasks" but are fundamentally different. An LLM receiving a request like "look at the tasks" might invoke the wrong one. -
Semantic overlap:
task= delegation ("who should do this work?"),tasks= analysis ("what work exists and in what order?"),todowrite= progress tracking ("what am I working on right now?"). Three concepts, near-identical naming for two of them. -
Plugin shadowing risk: OpenCode resolves tools into an object by ID. If a plugin registers a tool with the same ID as a built-in tool, the plugin wins. Accidentally shadowing the built-in
tasktool would break subagent spawning entirely.
Additionally, the dispatch field was initially named tool (matching open-memory's pattern). But the field name tool is ambiguous in OpenCode's context — every registered function is a "tool." The operation name op is more precise and matches the Rust CLI's subcommand pattern.
Decision
- Tool name:
taskgraph— directly matches the core library (@alkdev/taskgraph), clearly differentiates from the built-intask, and describes what the tool actually does. - Dispatch field:
op(operation) — unambiguous in context, distinguishes from the outer "tool" concept, matches the Rust CLI's subcommand pattern (taskgraph parallel,taskgraph critical, etc.).
Consequences
Positive:
- No naming confusion with built-in
task taskgraph({op: "list"})reads clearly: "run the list operation on the taskgraph"- Matches the Rust CLI naming — users familiar with
taskgraph parallelwill recognizetaskgraph({op: "parallel"}) - The
opfield name is self-documenting: each value is an operation, not a nested tool
Negative:
- Slightly longer tool name (10 chars vs 5 for
tasks) - Deviates from open-memory's
memory({tool: ...})pattern — but memory doesn't have a naming collision with a built-in tool
The Three "Task" Concepts
| Tool | Concept | Scope | Persistence |
|---|---|---|---|
task (built-in) |
Delegation — spawn a subagent | Session-scoped | Ephemeral |
todowrite (built-in) |
Progress tracking — what am I working on | Session-scoped | Ephemeral |
taskgraph (this plugin) |
Analysis — dependencies, risk, cost | Project-scoped | Persistent files |
These are complementary, not competing. Future integration could make taskgraph feed analysis into task (e.g., use parallel groups to drive spawn decisions), but that's a v2 concern.
References
- OpenCode built-in
tasktool:/workspace/opencode/packages/opencode/src/tool/task.ts - Research report: docs/research/opencode-task-tool-deep-dive.md
- Open-coordinator deep dive: docs/research/open-coordinator-deep-dive.md