OpenCode: add manual-review mode and /plannotator-last-plan to avoid eager submit_plan

[backnotprop]

Summary

OpenCode support is currently mixing two different product models:

1. Plannotator owns the planning loop — the agent is expected to call submit_plan automatically.
2. Plannotator is an explicit review tool — users want to call it only when they decide the plan is worth reviewing.

A growing cluster of feedback says the current default is too eager and too broad.

Pain points

Common sentiment:

• "I really enjoy Plannotator when I want to call it, but invoking itself on the OpenCode Plan mode is a bit annoying."
• "The agent eagerly calls it."
• "I don't want the build agent to call it."
• "I'd love a way if I could only manually invoke Plannotator on the last plan submitted by the agent."

What this looks like in practice:

• submit_plan is still available to all primary agents, not just the planning agent.
• The build agent is excluded from extra prompt injection, but it can still access the tool.
• Post-approval behavior is still biased toward implementation handoff, which clashes with users who want to stop, stay in planning, or manually choose the next step.
• The plugin still assumes the planning agent is literally named plan, which makes alternate workflows harder.
• Users who like OpenCode's native planning flow feel like Plannotator is hijacking it instead of layering on top of it.

Why this matters

This is not just prompt tuning.

The complaints around eager invocation, build-agent access, auto-switching, and hardcoded plan-agent behavior all point to the same underlying issue: the OpenCode contract is ambiguous.

Right now the plugin is trying to serve both:

• users who want automatic plan interception
• users who want manual, on-demand review

Those should probably not share one default behavior.

Existing issues this seems to unify

• [FEATURE REQUEST] Option for End planning without implementing #159 - option for ending planning without automatically implementing
• [Fearture request | Opencode Webui BUG] Allow option to stop agent after plan approval since it seems like opencode web/desktop does not auto change the agent. #118 - stop/hold behavior after approval, especially in OpenCode web/desktop
• oh my opencode compatibility issue #139 - oh-my-opencode compatibility around agent switching / workflow assumptions
• submit_plan: replace dual-mode auto-detect with a single deterministic path #365 - submit_plan still feels too prompt-dependent / ambiguous
• opencode plugin: remove hardcoded reliance on agent name "plan", to allow user to connect other agents to plannotator #422 - hardcoded reliance on the agent name plan

I also think this should be resolved before expanding agent-facing OpenCode power further, e.g. #295.

Proposal

Introduce an explicit OpenCode workflow mode instead of relying on one global default.

1. manual-review (recommended default)

Behavior:

• No prompt injection into agent planning.
• No submit_plan tool exposed to agents.
• User lets OpenCode plan normally.
• User explicitly invokes a new slash command such as /plannotator-last-plan to open the most recent plan-like assistant output in the Plannotator UI.

This matches the feedback from users who like Plannotator, but only when they choose to use it.

2. plan-only-auto

Behavior:

• Only configured planning agents can see/call submit_plan.
• build should not see or call it.
• Approval should default to stay or stop, not implicitly hand off to build.
• Planning agent name should be configurable, not hardcoded to plan.

This keeps the automatic review workflow for users who want Plannotator tightly integrated with planning.

3. all-primary-agents (legacy / advanced opt-in)

Behavior:

• Preserves the current broad access model for users who intentionally want any primary agent to call submit_plan.

Why /plannotator-last-plan is promising

We already have /plannotator-last, which proves the plugin can fetch the last assistant message from the current OpenCode session.

That suggests a natural manual-review workflow:

1. Let OpenCode's plan agent work normally.
2. When the user wants review, they run /plannotator-last-plan.
3. Plannotator opens the last plan-like assistant output in the normal plan review UI.
4. The user can annotate, approve, or request changes without the agent eagerly invoking review mid-flow.

This would give users an explicit bridge between native OpenCode planning and Plannotator review, without forcing the two to be the same thing.

Acceptance criteria

• OpenCode exposes a clear workflow setting/mode instead of one implicit default.
• manual-review mode exists and disables eager agent invocation.
• A manual slash command such as /plannotator-last-plan opens the last plan output in the plan review UI.
• plan-only-auto restricts submit_plan to configured planning agents only.
• Planning agent name or names are configurable instead of hardcoded to plan.
• Approval flow can stay/stop instead of always assuming implementation handoff.
• Existing users who rely on the broad current behavior can still opt into it explicitly.

Open question

Should manual-review become the default for OpenCode, with auto-interception as an opt-in mode?

My current read is yes.

[ajoslin]

Yes manual-review is right, very annoying when it pops up when i'm flowing.

[oorestisime]

Yes!!! Having the interceptor as opt in would be much better experience!

[foxytanuki]

I’m using Plannotator with OpenCode + oh-my-opencode-slim.

The current default has been a little annoying for me since the agent often reaches for submit_plan even on small changes where I don’t really want a plan review.

So +1 to manual-review, and I also think keeping the current behavior as a legacy all-primary-agents option makes sense.

For the open question: yes, I think manual-review should be the default for OpenCode.

[antanj]

Yes, exactly what plannotator needs.

[OverHash]

I view Plannotator as a supertool when I want to craft a more extended plan or provide feedback on a large plan generated by the default OpenCode plan tool.

For this reason, I'm often creating small plans in OpenCode and don't find much value in using Plannotator for them. However, for large plans, there is value, and so I'd enjoy manually triggering plannotator and allowing its use then.

[acmookey]

I’ve found that disabling submit_plan works better when combining openspec and plannotator in OpenCode. Using /plannotator-last for quick reviews is much smoother, as automatic submission fragments the SDD process.

Since the plan should focus on the openspec artifact implementation rather than code, being forced into a feedback/approval loop by submit_plan is too restrictive. Without an exit mechanism, I cannot proceed with the artifact-based workflow effectively.

[backnotprop]

I think the thread is pointing to a mode split rather than removing OpenCode plan integration.

The important distinction is that Plannotator should still integrate with OpenCode planning, but it should not expose submit_plan broadly or push non-plan agents toward it by default.

Proposed workflows

plan-agent

First migration default.

Behavior:

• Register submit_plan.
• Expose submit_plan only to configured planning agents.
• Hide or deny submit_plan for non-planning agents through OpenCode agent permissions where possible.
• Also reject calls inside submit_plan.execute() if context.agent is not one of the configured planning agents.
• Inject Plannotator planning guidance only for configured planning agents.
• Do not inject the lightweight submit_plan reminder into arbitrary primary agents.

This keeps Plannotator integrated with OpenCode plan mode, while stopping build and other implementation agents from calling it.

manual

Commands-only review.

Behavior:

• Do not register submit_plan.
• Do not inject Plannotator plan-submission prompts.
• Do not rewrite plan_exit or todowrite.
• Keep manual commands available:
  • /plannotator-last
  • /plannotator-annotate
  • /plannotator-review
  • /plannotator-archive
• Let OpenCode planning behave natively.

This does not mean Plannotator is not part of planning. It means Plannotator does not automatically interrupt planning. Users can still run /plannotator-last on a plan message or /plannotator-annotate on a spec, plan file, directory, or URL.

This lines up with the feedback from people who use Plannotator like a review surface, especially for large plans, OpenSpec artifacts, URLs, files, or the last assistant response.

all-agents

Legacy broad automatic behavior.

Behavior:

• Preserve the current broad behavior as much as practical.
• Register submit_plan.
• Allow primary agents to call submit_plan.
• Keep the existing subagent hiding behavior unless explicitly overridden.

This exists for users who intentionally rely on the current broad access model.

Config shape

Based on OpenCode source, plugin-specific options should live in the plugin tuple, not as arbitrary top-level config.

{
  "plugin": [
    ["@plannotator/opencode@latest", {
      "workflow": "plan-agent",
      "planningAgents": ["plan"]
    }]
  ]
}

Fields:

• workflow: "manual" | "plan-agent" | "all-agents"
• planningAgents: string array, default ["plan"]

Why this should work cleanly

OpenCode source answers the important implementation points:

• Plugins can conditionally register tools at startup. If we do not return tool.submit_plan, the model does not see the tool.
• OpenCode filters tools through active agent permissions, and plugin tool names can be controlled through permissions. That lets us deny submit_plan for non-planning agents in plan-agent mode.
• Plugin tool execution receives the invoking agent as context.agent, so we can keep a runtime guard even if visibility filtering misses something.
• session.prompt({ agent }) selects the agent for that prompt, but does not generally mutate the TUI selected agent.
• There is no native plugin primitive for “approve but do not continue”. If we want approve and stop, we should simply not call session.prompt().

Migration

First migration should be conservative: default to plan-agent, not manual.

That means OpenCode plan-mode users keep Plannotator integration, while non-plan primary agents stop seeing or being prompted toward submit_plan.

Default behavior with omitted config:

{
  "workflow": "plan-agent",
  "planningAgents": ["plan"]
}

Keep current broad behavior by opting in:

{
  "plugin": [
    ["@plannotator/opencode@latest", {
      "workflow": "all-agents"
    }]
  ]
}

Use commands only by opting in:

{
  "plugin": [
    ["@plannotator/opencode@latest", {
      "workflow": "manual"
    }]
  ]
}

Implementation plan

Phase 1: Mode gate

• Parse plugin tuple options.
• Default to plan-agent.
• Gate submit_plan registration by workflow.
• Gate prompt injection and tool-description rewrites by workflow.
• Remove the generic submit_plan reminder for non-plan primary agents in the default mode.
• Preserve current behavior under all-agents.
• Support manual as commands-only mode.
• Update docs and migration notes.

Phase 2: plan-agent hardening

• Add configured planning-agent matching.
• Hide or deny submit_plan for non-planning agents through OpenCode permissions.
• Add runtime context.agent guard.

Phase 3: Approval behavior

• Revisit the default approval handoff.
• In plan-agent, prefer stay or stop by default.
• Preserve the existing implementation handoff in all-agents for compatibility.
• Make continuation behavior explicit in UI copy and docs.

Notes on /plannotator-last-plan

I do not think /plannotator-last-plan needs to block this work.

The stronger signal from Pi and OpenCode users is that /plannotator-last and /plannotator-annotate are already core manual workflows. A separate plan-specific command might still be useful later if users need approve/deny and plan-history semantics for the last plan, but the immediate fix is the workflow mode split.

[backnotprop]

opencode-workflow-update.mp4

[oorestisime]

I like the direction this is going. I have also shifted my workflow to not use plan mode and just stay in build mode and use annotate last message to discuss with the agent or just work on a markdown file in build mode since i can control better all the steps!

[backnotprop]

Does anyone want to help me PR review:

#571

[backnotprop]

Now released.

Migration notes:
https://plannotator.ai/docs/guides/opencode-migration-0-19-1/

[foxytanuki]

Awesome work, Thank you so much!