Repository navigation
PRD: Per-project SWE Manager session (delegation-only primary agent + worktree tools) #217
Description
Problem
Long-running coding tasks today fall into two failure modes:
- Single session sprawl — one agent does plan + edit + review in the same context window; context bloat degrades reasoning and hides parallelism.
- Manual fan-out — humans open N terminals, juggle worktrees, copy-paste prompts between them. The bottleneck is coordination, not the models.
opencode already has the primitives (primary agents, task tool, child sessions, parent/child IDs), but there is no first-class per-project supervisor that owns the project's mental model and dispatches work. Users have to assemble one from opencode.json, external orchestrators (CAO, oh-my-opencode), and ad-hoc worktree scripts.
Proposal
Ship a built-in primary agent — manager — that acts as the project's Software Engineering Manager. It owns no execution tools; it owns delegation, worktrees, and session bookkeeping.
Manager capabilities
| Tool | Purpose |
|---|---|
task |
spawn subagents in child sessions (existing) |
worktree_create / worktree_delete |
isolate each subagent on its own branch |
session_list / session_attach |
enumerate and re-enter active child sessions |
todo |
maintain the project punch list across turns |
read, glob, grep |
read-only repo inspection for routing decisions |
Explicitly denied: edit, write, bash, patch. The manager cannot mutate the repo directly — only via subagents.
Default subagent roster (overridable per project)
@planner— read-only, produces task breakdowns@implementor— full edit/bash, scoped to one worktree@reviewer— read-only, runs after@implementorreturns@test-author— write access restricted to test paths
Worktree contract
- Each
taskinvocation that needs to mutate code MUST run inside a worktree created by the manager. - Worktrees live at `~/.local/share/opencode/worktree///` (matches existing convention).
- On subagent completion the manager decides: merge → PR, keep open for iteration, or discard.
Session hierarchy
- Manager session is pinned per project (one per `projectID`), survives restarts.
- All spawned child sessions inherit `parentID = manager.sessionID` and a name prefix `|`.
- TUI: `+m` jumps to the project's manager session from anywhere.
Design decisions
- Manager is a primary agent, not a new agent class. Reuses existing `permission.task` / `permission.edit` machinery. No runtime changes required for the agent itself — only config + a few new tools.
- Worktree management lives in opencode core, not a plugin. Plugin-based worktree tooling (`kdcokenny/opencode-worktree`) proves the pattern but fragments UX. Bring it in-tree behind a `worktree` permission gate.
- No tmux dependency. Visualization (oh-my-opencode style pane-per-subagent) is a separate optional integration; the manager itself must work headless and over `opencode serve`.
- Bounded recursion. Manager-spawned subagents get `task: deny` by default to prevent the unbounded recursion seen in upstream Subagents can infinitely recurse via Task tool — no max depth limit anomalyco/opencode#18100. Opt-in per agent if a workflow genuinely needs two-level delegation.
- REST-safe. Manager flows must not regress on upstream Sessions hang indefinitely when Task tool spawns subagents via REST API (opencode serve) anomalyco/opencode#6573 (Task tool hangs over `opencode serve`). Add an integration test that spawns a child subagent via the HTTP API and asserts completion.
Out of scope
- Cross-project orchestration (manager is per-project).
- Linear/Jira integration — leave to user-defined `@pm` subagents.
- Cloud-hosted supervisor / multi-user collaboration.
- Replacement for the existing `build` / `plan` primary agents.
Open questions
- Does the manager auto-spawn on `opencode` startup in a project, or is it user-invoked (`opencode manager`)?
- Should the manager persist its TODO list to disk (`.opencode/manager-state.json`) for resumability across restarts?
- How does the manager surface a stuck/hung subagent? Heartbeats from the session-status reconciler (in flight on `fix/session-status-reconciler-v2`) are the natural signal.
- Permissions UX: should denying `edit`/`bash` on a primary agent be a single-flag preset (`role: "manager"`) instead of three separate denies?
Prior art
- opencode docs — Agents, Session Management
- Upstream PR #7756 — subagent-to-subagent delegation with budgets
- agnusdei1207/opencode-orchestrator — Commander/Planner/Worker/Reviewer hub-and-spoke
- kdcokenny/opencode-worktree — worktree tools as a plugin
- awslabs/cli-agent-orchestrator — supervisor/worker over MCP + tmux
- ppries autonomous workflow gist — Linear → worktree → plan → TDD → PR
Known upstream blockers
- Sessions hang indefinitely when Task tool spawns subagents via REST API (opencode serve) anomalyco/opencode#6573 — Task tool hangs over REST in `opencode serve`
- Subagents can infinitely recurse via Task tool — no max depth limit anomalyco/opencode#18100 — no max-depth on Task recursion
- [Feature] Mirror parent session name to child sessions anomalyco/opencode#5579 — child sessions don't inherit parent name
- [FEATURE]: Navigation to parent session from child/subagent sessions anomalyco/opencode#3291 — no parent-session navigation in TUI
Activity
OpenCodeEngineer commentedon May 20, 2026
Code audit (2026-05-20)
Audited the proposal against the codebase before promoting to TDD. Most of the PRD is already supported by existing primitives — actual new work is small.
What already exists
worktree_create/deletetoolsWorktree.Service: create/list/remove/reset, exposed via control planepackages/opencode/src/worktree/index.ts:164-630;control-plane/adapters/worktree.ts:20-69~/.local/share/opencode/worktree/<project>/<branch>/worktree/index.ts:231Agent.Info.permission: Permission.Ruleset;Permission.merge(defaults, user, agent)composes themagent/agent.ts:33-56;config/permission.ts:24-45parentID,agent,permissionserver/routes/instance/session.ts:221-246server/routes/instance/session.ts:908-948session.ts:99-122,156-188;httpapi/groups/v2/session.ts:111-121session.ts:419-449routes/instance/event.ts:12-90;bus/index.ts:14-19Corrections to the original PRD
`parentID` is not "for attribution only." It triggers three side effects the PRD assumed away:
"Top-level visible worker with a manager link" therefore requires decoupling at least two of these behaviors (visibility + cascade) — likely via an `isWorker: true` flag or per-session opt-outs.
`@planner` / `@implementor` invocation syntax does not exist. No `@agent-name` parser anywhere in the codebase. Subagents are invoked only via the `task` tool with `subagent_type`. Either the manager LLM calls `task({subagent_type: "planner", ...})` explicitly, or `@` parsing becomes a separate feature ticket — out of scope here.
`task` cannot be reused as `worker_spawn`. `task` is synchronous: yields on `ops.prompt()` (`tool/task.ts:138`) and joins the child's last text into `<task_result>` (`tool/task.ts:160-166`). A worker tool must return a session id immediately and never join output. The reusable internals are `Session.create()` + `POST /prompt_async`, not the `task` tool itself.
No built-in `planner` / `implementor` / `reviewer` / `test-author` agents. Built-ins are `build`, `autopilot`, `plan`, `general`, `explore`, `scout`, `compaction`, `title`, `summary` (`agent/agent.ts:128-320`). The PRD roster ships either as new built-ins or as a documented `opencode.json` example.
No worker→manager push channel. The bus is per-instance and `/event` SSE has no per-session filter. Cheapest add: a new bus event type (`worker.update` or similar) emitted by a `notify_manager` tool — manager picks it up from the existing SSE. ~50 LOC, no new endpoint.
Re-scoped proposal — four real deltas
Recommendation on next doc
Skip the TDD. Remaining design surface is small enough that a TDD would be more text than implementation. Right move: amend this PRD with the above, then open four follow-up issues — one per delta. Each delta is a single-PR-sized piece.
dzianisv commentedon Jun 22, 2026
All 4 deltas implemented:
45481e5a5c128b602a1238b144dManager agent can now spawn workers in worktrees, delegate to planner/implementor/reviewer/test-author subagents, and workers have proper lifecycle (visible in session list, survive parent deletion).