Scope OpenCode submit_plan to planning agents

apps/marketing/src/content/docs/getting-started/configuration.md

@@ -57,7 +57,25 @@ OpenCode uses `opencode.json` to load the plugin:
 }
 ```
 
-This registers the `submit_plan` tool. Slash commands (`/plannotator-review`, `/plannotator-annotate`) require the CLI to be installed separately via the install script.
+This uses the default `plan-agent` workflow: `submit_plan` is registered for OpenCode's `plan` agent, while `build` and other primary agents do not see it.
+
+To configure the workflow explicitly:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    ["@plannotator/opencode@latest", {
+      "workflow": "plan-agent",
+      "planningAgents": ["plan"]
+    }]
+  ]
+}
+```
+
+Use `workflow: "manual"` for commands-only mode, or `workflow: "all-agents"` to restore the legacy behavior where primary agents can call `submit_plan`. In `plan-agent` mode, any names listed in `planningAgents` are added alongside OpenCode's built-in `plan` agent. Slash commands (`/plannotator-review`, `/plannotator-annotate`, `/plannotator-last`) require the CLI to be installed separately via the install script.
+
+If you are upgrading from an older OpenCode install, see the [OpenCode 0.19.1 migration guide](/docs/guides/opencode-migration-0-19-1/).
 
 ## Plan saving
 

apps/marketing/src/content/docs/getting-started/installation.md

@@ -106,7 +106,7 @@ Add the plugin to your `opencode.json`:
 }
 ```
 
-Restart OpenCode. The `submit_plan` tool is now available.
+Restart OpenCode. By default, `submit_plan` is available to OpenCode's `plan` agent only. Use the [OpenCode guide](/docs/guides/opencode/) if you want commands-only mode or the legacy all-agents behavior.
 
 For slash commands (`/plannotator-review`, `/plannotator-annotate`), also run the install script:
 

apps/marketing/src/content/docs/guides/opencode-migration-0-19-1.md

@@ -0,0 +1,147 @@
+---
+title: "OpenCode Migration (0.19.1)"
+description: "What changes for existing OpenCode users in Plannotator 0.19.1, and how to keep or change the old behavior."
+sidebar:
+  order: 6
+section: "Getting Started"
+---
+
+Plannotator `0.19.1` changes the default OpenCode workflow.
+
+Before `0.19.1`, OpenCode behavior was effectively broad automatic access: primary agents could see `submit_plan`, and users could run into cases where `build` or another non-planning agent reached for it.
+
+Starting in `0.19.1`, the default becomes `plan-agent`.
+
+## What changes on upgrade
+
+If you already use `@plannotator/opencode` and upgrade to `0.19.1` without adding any new config:
+
+- `submit_plan` stays available to OpenCode's planning agent, default `plan`
+- any agents you list in `planningAgents` are added alongside `plan`
+- `build` and other non-planning primary agents stop seeing or calling `submit_plan` by default
+- the broad reminder that nudged non-plan primary agents toward `submit_plan` goes away
+- `/plannotator-last`, `/plannotator-annotate`, `/plannotator-review`, and `/plannotator-archive` still work
+
+This is the new omitted-config default:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    ["@plannotator/opencode@latest", {
+      "workflow": "plan-agent",
+      "planningAgents": ["plan"]
+    }]
+  ]
+}
+```
+
+## Why the default changed
+
+OpenCode feedback was consistent on two points:
+
+- users still want Plannotator integrated with OpenCode plan mode
+- users do not want `submit_plan` exposed broadly enough that `build` or other implementation agents eagerly call it
+
+`plan-agent` is the compromise default:
+
+- it keeps OpenCode plan-mode integration through the built-in `plan` agent
+- it narrows `submit_plan` access to `plan` plus any extra planning agents you configure
+- it avoids forcing everyone all the way into commands-only mode
+
+## If you want the old behavior
+
+If you want the pre-`0.19.1` broad behavior back, opt into `all-agents`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    ["@plannotator/opencode@latest", {
+      "workflow": "all-agents"
+    }]
+  ]
+}
+```
+
+Use this if you intentionally want primary agents other than `plan` to see and call `submit_plan`.
+
+## If you want commands only
+
+If you do not want automatic plan review at all, switch to `manual`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    ["@plannotator/opencode@latest", {
+      "workflow": "manual"
+    }]
+  ]
+}
+```
+
+In `manual` mode:
+
+- `submit_plan` is not registered
+- OpenCode planning stays native
+- you use Plannotator explicitly through:
+  - `/plannotator-last`
+  - `/plannotator-annotate`
+  - `/plannotator-review`
+  - `/plannotator-archive`
+
+## Recommended upgrade path
+
+Choose one of these:
+
+### Keep the new default
+
+Do nothing if you want:
+
+- Plannotator in OpenCode plan mode
+- no broad `build` access to `submit_plan`
+
+### Restore the legacy model
+
+Set `workflow` to `all-agents` if your team already depends on broad primary-agent access.
+
+### Move to manual review
+
+Set `workflow` to `manual` if you prefer OpenCode's native planning flow and only want Plannotator when you invoke it yourself.
+
+## Common questions
+
+### Does this remove OpenCode plan integration?
+
+No. The default still keeps Plannotator integrated with OpenCode planning through the planning agent.
+
+### Does this break `/plannotator-last` or `/plannotator-annotate`?
+
+No. Manual commands continue to work across all workflow modes.
+
+### What if my planning agent is not named `plan`?
+
+Add it explicitly. OpenCode's built-in `plan` agent stays enabled in `plan-agent` mode:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    ["@plannotator/opencode@latest", {
+      "workflow": "plan-agent",
+      "planningAgents": ["planner"]
+    }]
+  ]
+}
+```
+
+### I upgraded but OpenCode still looks stale
+
+Restart OpenCode after upgrading. If a cached plugin version is still being used, rerun the install script or clear the OpenCode cache and restart.
+
+See also:
+
+- [OpenCode guide](/docs/guides/opencode/)
+- [Configuration](/docs/getting-started/configuration/)
+- [Troubleshooting](/docs/guides/troubleshooting/)

apps/marketing/src/content/docs/guides/opencode.md

@@ -6,18 +6,68 @@ sidebar:
 section: "Getting Started"
 ---
 
-Plannotator integrates with OpenCode as an npm plugin that registers a `submit_plan` tool. When the agent calls `submit_plan`, Plannotator opens the review UI in your browser.
+Plannotator integrates with OpenCode as an npm plugin. By default it makes `submit_plan` available to OpenCode's `plan` agent only, so OpenCode plan mode can use Plannotator without exposing the tool to `build`.
+
+If you are upgrading from an older OpenCode setup, read the [0.19.1 migration guide](/docs/guides/opencode-migration-0-19-1/) first.
 
 ## How the plugin works
 
 The OpenCode plugin (`@plannotator/opencode`) hooks into OpenCode's plugin system:
 
-1. The plugin registers a `submit_plan` tool that the agent can call
+1. The plugin registers a `submit_plan` tool for OpenCode's built-in `plan` agent and any extra planning agents you configure
 2. When `submit_plan` is called with a plan, Plannotator starts a local server and opens the browser
 3. The user reviews and annotates the plan
 4. On approval, the plugin returns a success response to the agent
 5. On denial, the plugin returns the feedback for the agent to revise
 
+## Workflow modes
+
+OpenCode support has three explicit modes:
+
+- **`plan-agent`** (default): `submit_plan` is available to OpenCode's built-in `plan` agent plus any extra agents listed in `planningAgents`.
+- **`manual`**: `submit_plan` is not registered. Use `/plannotator-last`, `/plannotator-annotate`, `/plannotator-review`, and `/plannotator-archive` when you want Plannotator.
+- **`all-agents`**: legacy broad behavior. Primary agents can see and call `submit_plan`.
+
+Default config:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    ["@plannotator/opencode@latest", {
+      "workflow": "plan-agent",
+      "planningAgents": ["plan"]
+    }]
+  ]
+}
+```
+
+If you want the old broad behavior:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    ["@plannotator/opencode@latest", {
+      "workflow": "all-agents"
+    }]
+  ]
+}
+```
+
+If you want commands only:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    ["@plannotator/opencode@latest", {
+      "workflow": "manual"
+    }]
+  ]
+}
+```
+
 ## Approve with annotations
 
 Unlike Claude Code, OpenCode supports feedback on approval. This means:
@@ -40,7 +90,7 @@ If the configured agent isn't found in the current OpenCode session, Plannotator
 
 ## Slash commands
 
-The plugin registers three slash commands:
+The plugin registers slash commands that work in every workflow mode:
 
 ### `/plannotator-review`
 
@@ -54,7 +104,7 @@ Requires the CLI to be installed (the slash command runs `plannotator review` un
 
 ### `/plannotator-annotate <file.md>`
 
-Opens a markdown file in the annotation UI. Also requires the CLI.
+Opens a markdown file, directory, or URL in the annotation UI. Also requires the CLI.
 
 ### `/plannotator-last`
 
@@ -79,7 +129,7 @@ Add to your `opencode.json`:
 }
 ```
 
-Restart OpenCode. The `submit_plan` tool is now available. See the [installation guide](/docs/getting-started/installation/) for full details.
+Restart OpenCode. With the default workflow, `submit_plan` is available to the `plan` agent. If you need `build` or another primary agent to call it, set `workflow` to `all-agents`. See the [installation guide](/docs/getting-started/installation/) for full details.
 
 ## Devcontainer / Docker
 

apps/marketing/src/content/docs/guides/troubleshooting.md

@@ -63,3 +63,22 @@ If `ExitPlanMode` doesn't trigger Plannotator:
 2. Restart Claude Code after installing (hooks load on startup)
 3. Verify `plannotator` is on your PATH: `which plannotator`
 4. Check that plan mode is enabled in your Claude Code session
+
+## OpenCode build agent cannot call `submit_plan`
+
+This is expected with the default OpenCode workflow. Plannotator now defaults to `plan-agent`, which keeps `submit_plan` available to OpenCode's `plan` agent and hides or denies it for `build` and other non-planning primary agents.
+
+If you want the old broad behavior, opt in from `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    ["@plannotator/opencode@latest", {
+      "workflow": "all-agents"
+    }]
+  ]
+}
+```
+
+If you do not want automatic plan review at all, use `workflow: "manual"` and run `/plannotator-last` or `/plannotator-annotate` when you want Plannotator.

apps/opencode-plugin/README.md

@@ -28,17 +28,65 @@ Add to your `opencode.json`:
 }
 ```
 
-Restart OpenCode. The `submit_plan` tool is now available.
+Restart OpenCode. By default, the `submit_plan` tool is available to OpenCode's `plan` agent, not to `build` or other primary agents.
 
 > **Slash commands:** Run the install script to get `/plannotator-review`, `/plannotator-annotate`, and `/plannotator-last`:
 > ```bash
 > curl -fsSL https://plannotator.ai/install.sh | bash
 > ```
 > This also clears any cached plugin versions.
 
+## Workflow Modes
+
+Plannotator supports three OpenCode workflows:
+
+- **`plan-agent`** (default): `submit_plan` is available to OpenCode's built-in `plan` agent plus any extra agents listed in `planningAgents`. This keeps Plannotator integrated with OpenCode plan mode without nudging `build` to call it.
+- **`manual`**: `submit_plan` is not registered. Use `/plannotator-last`, `/plannotator-annotate`, `/plannotator-review`, and `/plannotator-archive` when you want Plannotator.
+- **`all-agents`**: legacy broad behavior. Primary agents can see and call `submit_plan`.
+
+Default config:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    ["@plannotator/opencode@latest", {
+      "workflow": "plan-agent",
+      "planningAgents": ["plan"]
+    }]
+  ]
+}
+```
+
+Restore the old broad behavior:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    ["@plannotator/opencode@latest", {
+      "workflow": "all-agents"
+    }]
+  ]
+}
+```
+
+Use commands only:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    ["@plannotator/opencode@latest", {
+      "workflow": "manual"
+    }]
+  ]
+}
+```
+
 ## How It Works
 
-1. Agent calls `submit_plan` → Plannotator opens in your browser
+1. The configured planning agent calls `submit_plan` → Plannotator opens in your browser
 2. Select text → annotate (delete, replace, comment)
 3. **Approve** → Agent proceeds with implementation
 4. **Request changes** → Annotations sent back as structured feedback
@@ -50,6 +98,7 @@ Restart OpenCode. The `submit_plan` tool is now available.
 - **Private sharing**: Plans and annotations compress into the URL itself—share a link, no accounts or backend required
 - **Plan Diff**: See what changed when the agent revises a plan after feedback
 - **Annotate last message**: Run `/plannotator-last` to annotate the agent's most recent response
+- **Annotate files, folders, and URLs**: Run `/plannotator-annotate` when you want manual review of an artifact
 - **Obsidian integration**: Auto-save approved plans to your vault with frontmatter and tags
 
 ## Environment Variables