[FEATURE]: Per-agent isolation: worktree config field for automatic subagent worktree provisioning #34216

• I have verified this feature I'm about to request hasn't been suggested before.

Summary

Add a per-agent isolation config field (mirroring Claude Code's isolation: worktree subagent frontmatter) that makes child sessions spawned by that agent automatically provision a git worktree and run inside it, with automatic cleanup on session end.

This is the narrow, surgical version of the broader ask tracked in #17994 ("multi-agent orchestration in isolated workspaces"). #17994 covers the full conductor/orchestration surface; this issue is specifically about the one primitive that makes conductor-style workflows safe by default: a single config field that flips a subagent from "runs in parent's directory" to "runs in its own worktree."

Problem

Today, Session.create with parentID inherits the parent's directory from InstanceState.context. Child sessions run in the parent's working directory. The AGENTS.md guidance ("Parallel code edits conflict (no native worktree isolation). Sequence them, or git worktree add per worker.") is a workaround for exactly this gap.

OpenCode already ships a built-in Worktree.Service (packages/opencode/src/worktree/index.ts) with create / remove / list / reset, including Windows-specific retry handling. The plumbing exists; it's just not wired to the subagent spawn path.

Proposed

Add an isolation field to the agent config schema (both opencode.json agent block and .opencode/agents/*.md frontmatter):

{
  "agent": {
    "core-engineer": {
      "mode": "subagent",
      "isolation": "worktree"
    }
  }
}

# .opencode/agents/core-engineer.md
---
mode: subagent
isolation: worktree
---

Behavior when isolation: "worktree" is set on an agent and that agent is spawned as a child via the task tool:

1. Session.create detects parentID + child agent's isolation === "worktree".
2. Calls Worktree.create({ name: <slug from session/agent/track> }) to provision a worktree.
3. Sets the child session's directory to the worktree's directory (instead of inheriting the parent's).
4. On child session end/idle with no changes, calls Worktree.remove for auto-cleanup (Claude Code's "auto-removed if the subagent makes no changes" behavior).
5. On child session end with changes, leaves the worktree in place for the parent to merge/inspect.

Default: isolation unset -> current behavior (child inherits parent's directory). No breaking change.

Storage location

Two options, both consistent with existing OpenCode conventions:

1. Default (matches Worktree.Service today): ~/.local/share/opencode/worktree/<project-id>/<name>/ -- outside the repo, already the path the built-in service uses.
2. Optional repo-local mode: .agents/worktrees/<name>/ at the project root. This mirrors Claude Code's .claude/worktrees/<name>/ location, and OpenCode already recognizes .agents/ as a cross-tool-compatible directory -- packages/opencode/src/skill/index.ts scans .agents/skills/**/SKILL.md (and ~/.agents/skills/ globally) as an external skill source, alongside .claude/. Extending the same .agents/ convention to worktrees keeps worktree state out of the OpenCode-specific .opencode/ namespace and aligns with the cross-tool agent ecosystem (Codex, Cursor, Copilot, etc.) that already use .agents/ for shared agent configuration.

A config flag could select between them, e.g. worktree.location: "data" | "project", defaulting to "data". This is secondary to the isolation field itself but worth deciding in the same pass.

Note: .agents/ is not currently in the agent-config resolution path (agents load from .opencode/agents/ and ~/.config/opencode/agents/), and the existing Worktree.Service stores outside the repo. Using .agents/worktrees/ for the repo-local mode would be a new use of an already-recognized directory, not a change to how agents or worktrees are loaded today.

Why this shape

• Small surface area. One schema field, one branch in Session.create, one cleanup hook. ~50-100 LOC against code that already exists. Reviewable in a single PR.
• Composable with [FEATURE]:Support for multi-agent orchestration in isolated workspaces #17994 and [FEATURE]: Nested sub-agent spawning (up to 5 levels) + multi-agent workflow orchestration — reference implementation, requesting design review #32166. Those issues cover orchestration; this issue is the isolation primitive orchestration builds on. Either can land first; they don't block each other.
• Proven model. Claude Code shipped isolation: worktree as a subagent frontmatter field (see their sub-agents docs and issue [DOCS] Subagents documentation missing isolation: "worktree" configuration anthropics/claude-code#27023). Users coming from Claude Code expect this knob and currently have no equivalent in OpenCode.
• Plugin-compatible. Doesn't preclude plugins from doing fancier orchestration; just makes the common case safe by default.

What this does not do

• No new orchestration tool, no team/workflow tool, no inter-agent messaging. Those belong to [FEATURE]:Support for multi-agent orchestration in isolated workspaces #17994 / [FEATURE]: Ephemeral Sub-Agent Teams (parallel multi-agent orchestration) #19999 / [FEATURE]: Nested sub-agent spawning (up to 5 levels) + multi-agent workflow orchestration — reference implementation, requesting design review #32166.
• No change to primary-agent behavior. Primary agents already have a worktree (the project itself).
• No new terminal spawning. This is about the session's working directory, not process isolation. Users who want a separate terminal per worktree can use kdcokenny/opencode-worktree or similar.

Cross-references

• [FEATURE]:Support for multi-agent orchestration in isolated workspaces #17994 -- broad multi-agent orchestration in isolated workspaces (umbrella)
• [FEATURE]: Ephemeral Sub-Agent Teams (parallel multi-agent orchestration) #19999 -- ephemeral sub-agent teams
• [FEATURE]: Nested sub-agent spawning (up to 5 levels) + multi-agent workflow orchestration — reference implementation, requesting design review #32166 -- nested sub-agent spawning + workflow layer (reference implementation, in design review)
• [FEATURE] Parallel Workflow Support via Git Worktrees and Tabbed Sessions #12896 -- earlier (closed) parallel-workflow request
• packages/opencode/src/worktree/index.ts -- existing Worktree.Service to call
• packages/opencode/src/session/session.ts -- Session.create where the directory is currently inherited