fix(core): expose valid subagent IDs to the model

[kitlangton]

Summary

The V2 subagent tool does not expose the configured subagent IDs to the model and provides no discovery operation. Models therefore guess plausible IDs, causing valid delegation attempts to fail at execution time.

Environment

• opencode version: 0.0.0-next-15468 when reproduced; current installed version is 0.0.0-next-15472
• OS: macOS 25.5.0, arm64 (Darwin 25.5.0)
• Terminal: WarpTerminal v0.2026.07.01.09.21.stable_01 during reproduction
• Shell: /bin/zsh
• Install/channel: next
• Active plugins: ~/.config/opencode/plugins/share-with-team.ts, packages/opencode/src/control-plane/dev/debug-workspace-plugin.ts, and @warp-dot-dev/opencode-warp

Reproduction

1. Start a V2 session in a location with the built-in explore subagent available.
2. Ask the primary agent to perform work that benefits from codebase exploration.
3. Observe that the model-facing subagent definition describes agent only as "The configured agent to run as the subagent" and does not list valid IDs.
4. The model may infer a plausible name such as explorer and call subagent with it.

Reproduced in session ses_0a2c271f9ffen7aHqd8IiouC7k with model opencode/big-pickle:

{
  "agent": "explorer",
  "description": "Explore how agents are defined in this codebase"
}

Expected Behavior

The model can discover the exact, currently valid subagent IDs before invoking the tool. The surfaced catalog should be Location-specific and account for agent mode and the caller's permissions.

V1 did this during request-specific tool materialization in packages/opencode/src/tool/registry.ts: it listed configured non-primary agents, permission-filtered them for the caller, and appended each exact ID and description to the task tool definition.

A V2 solution could restore a compact permission-filtered catalog in the tool description or provide an explicit list/discovery operation. Exact IDs must be surfaced; display names alone are insufficient.

Actual Behavior

The invocation fails with:

Unknown agent: explorer

The actual built-in ID is explore. The agent then falls back to manually using read, glob, and grep, losing the intended delegation and parallelism.

On origin/v2 at 748b0d8836, packages/core/src/tool/subagent.ts defines a static tool description and a free-form string input:

agent: Schema.String.annotate({ description: "The configured agent to run as the subagent" })

Execution validates the guessed value only after the call:

const agent = yield* agents.resolve(input.agent)
if (agent === undefined) return yield* new ToolFailure({ message: `Unknown agent: ${input.agent}` })

Additional Context

This appears to be a V1-to-V2 regression: execution-time agent resolution was ported, but the model-facing agent catalog was not.

Related: #13188 proposed lazy-loading agent and skill catalogs to avoid repeatedly inlining large descriptions. That issue was auto-closed for inactivity. This report is narrower and demonstrates a correctness failure in V2: there is currently neither a catalog nor an on-demand discovery path.

[rocketmxn]

I saw this issue is currently unassigned, but I also noticed a related mention (#36883) in the activity feed. Is this issue still open for contributions, or is someone already actively working on a fix? If it's available, I'd be happy to pick it up.

[kennyjinhiro]

Hi @rocketmxn and @kitlangton, is it okay if I claim this one as my first open-source issue?
Seems like this is a very interesting issue and I would credit you guys. Thanks!