[FEATURE]: add directory parameter to task tool for monorepo subagent dispatch

[trin4ik]

Feature hasn't been suggested before.

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

Describe the enhancement you want to request

Problem

In a monorepo each subproject can ship its own .opencode/, AGENTS.md and skills. Today there is no way to dispatch a subagent task into a subproject so that those project-local resources are picked up. The task tool always creates the child session inside the parent session's InstanceContext, so the subagent inherits the parent's working directory, agents, skills and AGENTS.md chain — even when the work clearly belongs to a different subproject.

Use case

Layout (simplified):

my-monorepo/
├─ AGENTS.md                          # monorepo-wide guidance
├─ .opencode/
│  └─ agent/
│     └─ orchestrator.md
├─ backend/
│  └─ api/
│     ├─ AGENTS.md                    # api-specific guidance
│     └─ .opencode/
│        └─ skill/
│           ├─ abstract-model/
│           ├─ events/
│           └─ metrics/
└─ frontend/
   └─ web/
      ├─ AGENTS.md
      └─ .opencode/skill/...

Parent session runs from my-monorepo/. The orchestrator needs to delegate a focused task to backend/api. With the current task tool the subagent sees only the monorepo-root AGENTS.md and root-level skills — none of the backend/api/.opencode/skill/* are available, even though they were authored exactly for that subagent's job.

Proposed solution

Add an optional directory: string parameter to the task tool. When set, the subagent runs inside the matching InstanceContext: cwd, agent registry, AGENTS.md walk-up and skills all resolve against that path. When omitted, behavior is identical to today (subagent inherits the parent session's directory) — fully backwards compatible.

This is essentially the same per-request directory routing that the HTTP middleware already applies (workspace-routing.ts + instance-context.ts → InstanceStore.load({ directory }) + Effect.provideService(InstanceRef, ctx)). The proposal is to make that capability reachable from the task tool's args so it can be driven by the LLM, not only by HTTP clients.

Before vs after

Before — subagent inherits parent's InstanceContext:

task({
  subagent_type: "build",
  description: "...",
  prompt: "...",
})
// → subagent cwd = my-monorepo/
// → AGENTS.md: my-monorepo/AGENTS.md
// → skills: only monorepo-root skills

After — subagent gets backend/api's InstanceContext:

task({
  subagent_type: "build",
  description: "...",
  prompt: "...",
  directory: "/abs/path/my-monorepo/backend/api",
})
// → subagent cwd = my-monorepo/backend/api/
// → AGENTS.md: my-monorepo/AGENTS.md + my-monorepo/backend/api/AGENTS.md
// → skills: monorepo-root + backend/api/.opencode/skill/*

Implementation sketch

Single-file change in packages/opencode/src/tool/task.ts:

1. Add directory?: string to Parameters and BaseParameters schemas.
2. Build a scoped helper. When params.directory is set, lazily resolve InstanceStore.Service via Effect.serviceOption and wrap the relevant Effects in store.provide({ directory }, ...). When omitted, pass the Effect through unchanged.
3. Wrap three calls in scoped:
   • agent.get(params.subagent_type) — resolve the subagent from the target project.
   • sessions.create(...) — persist the new session with directory set correctly.
   • ops.prompt(...) — run the prompt loop inside the target InstanceContext.

Using serviceOption keeps TaskTool's declared dependency surface unchanged when directory is omitted, so existing test layers and the ToolRegistry.layer requirement set do not need to change.

Related context

• feat(session): add support for per-session working directories #9365 (feat(session): add support for per-session working directories) — partially overlapping: it makes per-session Session.directory work, but explicitly does not cover Session.create/Session.fork used by the task tool (see comments on that PR about monorepo subagents inheriting the wrong directory). The proposal here addresses that specific gap from the task-tool side.
• Create session with a different root/working directory #1143, [FEATURE]: Allow sessions to have custom working directories #9366 (both closed) — broader "per-session working directory" tracking, related but coarser.
• OPENCODE_EXPERIMENTAL_WORKSPACES — early/buggy alternative, scoped to whole workspaces, does not solve subdirectory dispatch from within a single workspace.

Backwards compatibility

directory is optional. When omitted, the tool behaves exactly as today: the child session inherits the parent session's InstanceContext. No public API or schema changes for existing callers.

Verification plan

Spin up bun dev serve, create a parent session in a monorepo root, drive the subagent with task({ ..., directory: "<repo>/backend/api" }), then ask it to print pwd, the names of skills it can see, and the AGENTS.md paths it has loaded. Expected: cwd matches the target subproject, project-local skills appear, both root and subproject AGENTS.md are loaded. Compare with a no-directory call to confirm default behavior is unchanged.

I have a working patch and a green local run against this exact scenario. Happy to open the PR if the approach sounds right.

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• [FEATURE]:Support for multi-agent orchestration in isolated workspaces #17994: Similar request for multi-agent orchestration in isolated workspaces — that issue also requests the ability to spawn subagents operating in specific working directories within a monorepo structure.

If your proposal is meaningfully different (e.g., specifically targeting the task tool's directory parameter rather than a broader orchestration system), it may help to add a brief note clarifying the distinction from #17994.

[trin4ik]

This issue might be a duplicate of existing issues. Please check:

• [FEATURE]:Support for multi-agent orchestration in isolated workspaces #17994: Similar request for multi-agent orchestration in isolated workspaces — that issue also requests the ability to spawn subagents operating in specific working directories within a monorepo structure.

If your proposal is meaningfully different (e.g., specifically targeting the task tool's directory parameter rather than a broader orchestration system), it may help to add a brief note clarifying the distinction from #17994.

Thanks for pointing this out. I agree this overlaps with #17994 in motivation, but I don't think it is a duplicate.

#17994 is a broader request for native multi-agent orchestration / isolated workspaces / worktree lifecycle management. This issue is intentionally much narrower: expose an optional directory argument on the existing task tool so a child session can run inside the matching InstanceContext.

That means no workspace lifecycle, no worktree creation, no merge strategy, and no new orchestration system. The goal is only to let an existing parent agent dispatch an existing subagent into a specific project directory and have cwd, local .opencode, AGENTS.md walk-up, agents and skills resolve from that directory.

Related PRs I found:

• fix: re-enter Instance context for session routes #17320 fixes re-entering the correct InstanceContext for HTTP session routes once a session already has the right directory. It does not let task create a child session in a different directory or resolve the subagent/skills from that target directory.
• feat(session): add support for per-session working directories #9365 adds per-session working directory support for tools, but task still creates/forks under the parent InstanceContext and resolves the subagent from the parent project.

So this proposal can be a small standalone addition: task({ ..., directory }) wraps agent.get, sessions.create, and ops.prompt in InstanceStore.load/provide({ directory }). When directory is omitted, behavior stays exactly as today.

Happy to open a focused PR for just this if the approach sounds acceptable.