[FEATURE]: Let custom primary agents participate in plan mode (plan file path + configurable plan_exit handoff target) #31868

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

What I'm trying to do

I ship a pair of custom primary agents as part of a governance plugin: a read-only planner (archgate-planner) and a developer (archgate-developer). I want the planner to participate in OpenCode's native plan infrastructure — write the session plan file, call plan_exit, and hand off to my developer agent.

Current behavior

The plan infrastructure is hardcoded to agents literally named plan and build:

1. The canonical plan path is unknowable to custom agents. Session.plan() derives it from session metadata ({time.created}-{slug}.md), and the system reminder that reveals it is only injected when agent.name === "plan" (packages/opencode/src/session/reminders.ts:70). A custom planning agent never learns the path.
2. plan_exit references that canonical path (packages/opencode/src/tool/plan.ts:29). When a custom agent calls it, the approval question and the synthetic handoff message point to a file the agent never wrote — the receiving agent is told to execute a plan that doesn't exist.
3. plan_exit hardcodes the handoff to build (plan.ts:58, agent: "build"). There's no way to route the approved plan to a custom implementation agent. (Related: [BUG] plan_exit throws error when build agent is disabled #9822 — plan_exit even errors when build is disabled; [FEATURE]: allow plugins to switch active primary agent (custom primary agent handoff) #14528 asks for the TUI side of custom handoffs.)

The only workaround today is to avoid plan_exit entirely: write a self-named plan file into .opencode/plans/ and tell the user to switch agents manually — losing the approval flow and the automatic switch.

Proposal

Two orthogonal, backward-compatible additions:

A. Opt-in plan-mode participation per agent. An agent config flag, e.g.:

{ "agent": { "my-planner": { "mode": "primary", "plan": true } } }

Agents with plan: true get the same treatment as the built-in plan agent in reminders.ts (plan-mode reminder with the canonical path, dir creation) and in the successor-agent reminder (reminders.ts:52, "A plan file exists at …").

B. Configurable plan_exit handoff target. E.g.:

{ "agent": { "my-planner": { "plan": true, "handoff": "my-developer" } } }

plan_exit would use handoff (defaulting to "build") for the question text and the synthetic agent: message. This also fixes #9822 cleanly (validate the target exists instead of assuming build).

With A + B, plugin-provided planning agents get the full native flow — incremental plan file, approval prompt, agent switch — without each plugin reinventing a broken parallel version.

Since plan mode is still behind OPENCODE_EXPERIMENTAL_PLAN_MODE, now seems like the right time to make it extensible before the behavior stabilizes.

References

• packages/opencode/src/session/session.ts:377 (Session.plan())
• packages/opencode/src/session/reminders.ts:52,70 (name-gated reminders)
• packages/opencode/src/tool/plan.ts:29,58 (canonical path + hardcoded build)
• Related: [FEATURE]: allow plugins to switch active primary agent (custom primary agent handoff) #14528, [FEATURE]: Inject current session ID into Plan/Build agent system prompts #12324, [BUG] plan_exit throws error when build agent is disabled #9822, Plan Mode Injection #27449