Feature hasn't been suggested before.
Describe the enhancement you want to request
Problem
OpenCode2 is often started from the root of a monorepo, while implementation work belongs to individual services.
A large monorepo may contain 50+ services. Many services have their own AGENTS.md, local agents, skills, and OpenCode configuration because they are effectively separate projects:
mono/
├── AGENTS.md
├── .opencode/agents/orchestrator.md
└── services/
├── billing/
│ ├── AGENTS.md
│ └── .opencode/skills/...
├── orders/
│ ├── AGENTS.md
│ └── .opencode/skills/...
└── ...
The primary agent works best as an orchestrator: it understands a task spanning several services, prepares a rough implementation plan, and delegates the actual work to focused subagents.
Today the V2 subagent tool creates its child session at the parent session's Location. A subagent delegated to services/billing therefore does not start from that service directory and does not naturally receive its local instructions, agents, skills, and configuration.
Requested behavior
Allow a subagent to start at an explicit directory or Location:
subagent({
agent: "implementer",
description: "Implement billing changes",
prompt: "Implement the billing part of the plan",
directory: "/repo/mono/services/billing"
})The child session should:
- retain its relationship to the parent session;
- use the requested Location;
- load the target service's local
AGENTS.md, agents, skills, and configuration;
- preserve current behavior when
directory is omitted;
- make events from its linked child-session tree available to the parent session subscription even across Locations, so the parent UI can show live child activity and let the user navigate into the child session.
This would allow a root orchestrator to launch separate implementation subagents for several services while preserving the local context of each service.
This request does not involve creating worktrees, isolating working copies, or managing merges. The target service directories already exist inside the monorepo.
Native or plugin support
Native support in the V2 subagent tool would be ideal.
A plugin-based solution would also work if the public V2 plugin API can:
- create a child session with both
parentID and an explicit Location;
- run it in the foreground or background and wait for it when needed;
- propagate cancellation;
- preserve the same parent-child event visibility and session navigation as the native subagent tool.
Field experience
I have been using a fork containing the implementation from #32351 for about a month. It provides this behavior for the legacy task tool.
During that period, the local SQLite database recorded more than 1,400 sessions. Of those, 409 child sessions ran in a directory different from their parent, across 155 target directories. These cross-directory children processed approximately 84 million input/output/reasoning tokens and 2.77 billion recorded token units including cache traffic.
In daily use, the feature completely solved the problem: the root orchestrator delegates implementation into individual service directories, and subagents automatically receive the relevant local instructions and skills. Existing behavior remains unchanged when directory is omitted, and I have not observed regressions in unrelated workflows.
This is not a substitute for formal testing, but it represents substantial real-world usage and suggests that the behavior itself is stable.
Related
This issue is specifically about a V2 contract for launching linked subagents in service-specific Locations, rather than porting the legacy implementation.
Feature hasn't been suggested before.
Describe the enhancement you want to request
Problem
OpenCode2 is often started from the root of a monorepo, while implementation work belongs to individual services.
A large monorepo may contain 50+ services. Many services have their own
AGENTS.md, local agents, skills, and OpenCode configuration because they are effectively separate projects:The primary agent works best as an orchestrator: it understands a task spanning several services, prepares a rough implementation plan, and delegates the actual work to focused subagents.
Today the V2
subagenttool creates its child session at the parent session's Location. A subagent delegated toservices/billingtherefore does not start from that service directory and does not naturally receive its local instructions, agents, skills, and configuration.Requested behavior
Allow a subagent to start at an explicit directory or Location:
The child session should:
AGENTS.md, agents, skills, and configuration;directoryis omitted;This would allow a root orchestrator to launch separate implementation subagents for several services while preserving the local context of each service.
This request does not involve creating worktrees, isolating working copies, or managing merges. The target service directories already exist inside the monorepo.
Native or plugin support
Native support in the V2
subagenttool would be ideal.A plugin-based solution would also work if the public V2 plugin API can:
parentIDand an explicit Location;Field experience
I have been using a fork containing the implementation from #32351 for about a month. It provides this behavior for the legacy
tasktool.During that period, the local SQLite database recorded more than 1,400 sessions. Of those, 409 child sessions ran in a directory different from their parent, across 155 target directories. These cross-directory children processed approximately 84 million input/output/reasoning tokens and 2.77 billion recorded token units including cache traffic.
In daily use, the feature completely solved the problem: the root orchestrator delegates implementation into individual service directories, and subagents automatically receive the relevant local instructions and skills. Existing behavior remains unchanged when
directoryis omitted, and I have not observed regressions in unrelated workflows.This is not a substitute for formal testing, but it represents substantial real-world usage and suggests that the behavior itself is stable.
Related
taskarchitecture.This issue is specifically about a V2 contract for launching linked subagents in service-specific Locations, rather than porting the legacy implementation.