feat: add external editor fallback for plan review

Author: timrichardson

README.md

@@ -1,7 +1,7 @@
 # opencode-planner
 
 `opencode-planner` is an OpenCode plugin that adds a dedicated `plan` agent for read-only planning before implementation. It's based on the experimental plan agent. That is, it likes to use sub-agents and a structured approach to planning.
-It asks clarifying questions, and produces a markdown file. When Plannotator is installed, it can submit the finished plan for richer review. Without Plannotator, it falls back to a normal chat-based review handoff.
+It asks clarifying questions, and produces a markdown file. When Plannotator is installed, it can submit the finished plan for richer review. Without Plannotator, it can open the plan in your configured external editor for review.
 
 After review, the agent can hand back to implementation mode by calling `plan_exit` only when the host runtime exposes that tool. In current OpenCode builds, that means experimental plan mode must be enabled and the client must be `cli`. If it's not enabled, you need to prompt the build agent to start work.
 
@@ -36,9 +36,10 @@ If you want reproducible installs instead of automatic plugin refreshes, pin an
 - injects a system reminder that keeps the planning workflow explicit
 - lets users replace the plugin's base `plan` prompt with their own `agent.plan.prompt`
 - lets users override agent settings such as `agent.plan.model` and provider-specific options like `agent.plan.reasoningEffort`
-- denies `submit_plan` and `plan_exit` to the built-in `general` and `explore` subagents so review and implementation handoff stay on the primary `plan` agent
+- denies `submit_plan`, `edit_plan`, and `plan_exit` to the built-in `general` and `explore` subagents so review and implementation handoff stay on the primary `plan` agent
 - exposes a `plan_prompt` tool so the `plan` agent can reveal the plugin's prompt basis for customization
-- uses `submit_plan` for review when available, otherwise falls back to manual chat review
+- exposes an `edit_plan` tool so the `plan` agent can open the current plan in the configured external editor
+- uses `submit_plan` for review when available, otherwise falls back to external-editor review
 - can leave planner mode with `plan_exit` after approval when experimental plan mode is enabled in the CLI runtime
 
 ## Customize the plan agent
@@ -75,6 +76,37 @@ The tool returns:
 - the injected planner reminder, which is plugin-controlled runtime guidance and is not customized via `agent.plan.prompt`
 - a short note explaining that the final runtime prompt can still differ because of user config, other plugins, or runtime tool availability like `plan_exit`
 
+## Review Without Plannotator
+
+If `submit_plan` is not registered by the runtime, the plugin's `edit_plan` tool gives the `plan` agent a fallback way to open the current plan in your configured external editor.
+
+Example:
+
+```text
+If submit_plan is unavailable, call edit_plan so I can review the plan in my editor.
+```
+
+`edit_plan` uses `VISUAL` first, then `EDITOR`. The command must launch a separate process and block until editing is complete.
+
+Compatible examples:
+
+- `VISUAL="gvim -f"`
+- `EDITOR="gedit --wait"`
+- `EDITOR="kate --block"`
+- `EDITOR="code --wait"`
+
+These work because they open a separate editor process and do not try to take over the OpenCode TUI terminal.
+
+Bare terminal editors like `vim` or `nvim` are not sufficient on their own because the plugin does not hand the current TUI terminal over to the editor. If you want to use them, wrap them in a terminal-emulator command that opens a new window and waits for it to exit.
+
+Examples:
+
+- `EDITOR="gnome-terminal --wait -- nvim"`
+- `EDITOR="kitty --wait nvim"`
+- a small wrapper script for your terminal emulator that launches `vim` or `nvim` in a separate window and blocks until it exits
+
+If `edit_plan` fails, the `plan` agent should fall back to telling you the plan file path and asking for review in chat.
+
 ## Auto-updates
 
 OpenCode installs and updates npm plugins automatically. During the beta phase of this plugin, `opencode-planner@beta` gives the smoothest update path for most users.
@@ -95,7 +127,7 @@ npm run debug:plan
 npm run opencode:no-plannotator -- debug config
 ```
 
-`npm run debug:plan` checks the active OpenCode runtime and reports whether the local repo plugin is loaded, whether `plan_prompt`, `submit_plan`, and `plan_exit` are allowed by the `plan` agent, and whether they are actually registered as runtime tools.
+`npm run debug:plan` checks the active OpenCode runtime and reports whether the local repo plugin is loaded, whether `plan_prompt`, `edit_plan`, `submit_plan`, and `plan_exit` are allowed by the `plan` agent, and whether they are actually registered as runtime tools.
 
 This is the fastest way to distinguish:
 

index.js

@@ -1,4 +1,7 @@
+import { spawn } from "node:child_process"
+import { readFile } from "node:fs/promises"
 import path from "path"
+import process from "node:process"
 
 const agent = "plan"
 const root = ".opencode/plans"
@@ -22,7 +25,7 @@ function file(id) {
 function reviewInstruction(target) {
   return [
     `When the plan is complete, if the submit_plan tool is available, use it to submit the plan for review.`,
-    `Otherwise, tell the user the plan is ready at ${target} and ask for review in chat.`,
+    `Otherwise, call edit_plan to open the markdown plan in the configured external editor for review. If edit_plan fails, tell the user the plan is ready at ${target} and ask for review in chat.`,
   ].join(" ")
 }
 
@@ -122,12 +125,76 @@ function restrictPlannerSubagent(input = {}) {
   return {
     ...input,
     permission: merge(input?.permission, {
+      edit_plan: "deny",
       plan_exit: "deny",
       submit_plan: "deny",
     }),
   }
 }
 
+function editorCommand() {
+  return process.env.VISUAL?.trim() || process.env.EDITOR?.trim() || ""
+}
+
+function runEditor(target) {
+  const editor = editorCommand()
+  if (!editor) {
+    throw new Error(
+      "Neither `VISUAL` nor `EDITOR` is set, so edit_plan cannot open the plan. Configure a blocking editor command such as `code --wait`, or a terminal launcher that opens your editor in a separate window and waits.",
+    )
+  }
+
+  const shell = process.env.SHELL ?? "sh"
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(shell, ["-lc", `${editor} "$1"`, "opencode-editor", target], {
+      stdio: ["ignore", "ignore", "pipe"],
+      env: process.env,
+    })
+
+    let stderr = ""
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString()
+    })
+
+    child.on("error", reject)
+    child.on("exit", (code) => {
+      if (code === 0) {
+        resolve()
+        return
+      }
+
+      const detail = stderr.trim()
+      const suffix = detail ? `: ${detail}` : ""
+      reject(
+        new Error(
+          `The external editor command exited with status ${code}${suffix}. Configure VISUAL or EDITOR to launch a separate process that waits until editing is complete.`,
+        ),
+      )
+    })
+  })
+}
+
+async function editPlan(sessionID) {
+  const target = file(sessionID ?? "<session-id>")
+  await runEditor(target)
+
+  let content = ""
+
+  try {
+    content = await readFile(target, "utf8")
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      throw new Error(`The plan file \`${target}\` does not exist yet. Finish writing the plan first.`)
+    }
+
+    throw error
+  }
+
+  const rendered = content.trim() ? content : `The plan file \`${target}\` is empty.`
+  return [`The plan was edited in your external editor.`, `File: ${target}`, "", rendered].join("\n")
+}
+
 function mode(input = {}) {
   const base = {
     mode: "primary",
@@ -154,6 +221,7 @@ function mode(input = {}) {
       websearch: "allow",
       codesearch: "allow",
       batch: "allow",
+      edit_plan: "allow",
       plan_prompt: "allow",
       submit_plan: "allow",
       ...(hasPlanExit() ? { plan_exit: "allow" } : {}),
@@ -191,6 +259,13 @@ export default async function plannerPlugin() {
           return promptDisclosure(context.sessionID ? file(context.sessionID) : defaultPlanTarget)
         },
       },
+      edit_plan: {
+        description: "Open the current plan in the configured external editor",
+        args: {},
+        async execute(_, context) {
+          return editPlan(context.sessionID)
+        },
+      },
     },
     async config(cfg) {
       cfg.agent ??= {}

scripts/debug-plan-runtime.js

@@ -41,9 +41,11 @@ const tools = plan.tools ?? {}
 const prompt = plan.prompt ?? ""
 
 const planPromptAllowed = hasAllowedPermission("plan_prompt", permissions)
+const editPlanAllowed = hasAllowedPermission("edit_plan", permissions)
 const planExitAllowed = hasAllowedPermission("plan_exit", permissions)
 const submitPlanAllowed = hasAllowedPermission("submit_plan", permissions)
 const planPromptTool = Boolean(tools.plan_prompt)
+const editPlanTool = Boolean(tools.edit_plan)
 const planExitTool = Boolean(tools.plan_exit)
 const submitPlanTool = Boolean(tools.submit_plan)
 const usingLocalPlugin = plugins.includes(localPlugin)
@@ -54,6 +56,8 @@ console.log("")
 line("Repo plugin loaded", usingLocalPlugin ? "yes" : "no")
 line("plan_prompt allowed", planPromptAllowed ? "yes" : "no")
 line("plan_prompt tool", planPromptTool ? "yes" : "no")
+line("edit_plan allowed", editPlanAllowed ? "yes" : "no")
+line("edit_plan tool", editPlanTool ? "yes" : "no")
 line("submit_plan allowed", submitPlanAllowed ? "yes" : "no")
 line("plan_exit allowed", planExitAllowed ? "yes" : "no")
 line("submit_plan tool", submitPlanTool ? "yes" : "no")
@@ -77,6 +81,9 @@ if (!usingLocalPlugin) {
 if (!planPromptTool) {
   console.log("- plan_prompt is not registered as a runtime tool.")
 }
+if (!editPlanTool) {
+  console.log("- edit_plan is not registered as a runtime tool.")
+}
 if (!submitPlanTool) {
   console.log("- submit_plan is not registered as a runtime tool.")
 }

test/plugin.test.js

@@ -1,5 +1,6 @@
 import test from "node:test"
 import assert from "node:assert/strict"
+import { mkdir, rm, writeFile } from "node:fs/promises"
 
 import plannerPlugin from "../index.js"
 
@@ -25,6 +26,17 @@ async function withEnv(env, fn) {
   }
 }
 
+async function withPlanFile(filePath, content, fn) {
+  await mkdir(new URL("../.opencode/plans/", import.meta.url), { recursive: true })
+  await writeFile(new URL(`../${filePath}`, import.meta.url), content)
+
+  try {
+    await fn()
+  } finally {
+    await rm(new URL(`../${filePath}`, import.meta.url), { force: true })
+  }
+}
+
 test("config hook registers the plan agent without plan_exit by default", async () => {
   await withEnv(
     {
@@ -40,10 +52,12 @@ test("config hook registers the plan agent without plan_exit by default", async
 
       assert.equal(cfg.agent.plan.mode, "primary")
       assert.equal(cfg.agent.plan.permission.bash, "deny")
+      assert.equal(cfg.agent.plan.permission.edit_plan, "allow")
       assert.equal(cfg.agent.plan.permission.plan_prompt, "allow")
       assert.equal(cfg.agent.plan.permission.submit_plan, "allow")
       assert.equal(cfg.agent.plan.permission.plan_exit, undefined)
       assert.match(cfg.agent.plan.prompt, /if the submit_plan tool is available/i)
+      assert.match(cfg.agent.plan.prompt, /call edit_plan to open the markdown plan/i)
       assert.match(cfg.agent.plan.prompt, /ask for review in chat/i)
       assert.doesNotMatch(cfg.agent.plan.prompt, /plan_exit/)
     },
@@ -100,7 +114,7 @@ test("config hook enables plan_exit when experimental plan mode is active", asyn
   )
 })
 
-test("config hook denies submit_plan and plan_exit for planner subagents", async () => {
+test("config hook denies review handoff tools for planner subagents", async () => {
   await withEnv(
     {
       OPENCODE_EXPERIMENTAL: undefined,
@@ -113,13 +127,15 @@ test("config hook denies submit_plan and plan_exit for planner subagents", async
         agent: {
           general: {
             permission: {
+              edit_plan: "allow",
               plan_exit: "allow",
               submit_plan: "allow",
               webfetch: "deny",
             },
           },
           explore: {
             permission: {
+              edit_plan: "allow",
               plan_exit: "allow",
               submit_plan: "allow",
             },
@@ -129,15 +145,65 @@ test("config hook denies submit_plan and plan_exit for planner subagents", async
 
       await plugin.config(cfg)
 
+      assert.equal(cfg.agent.general.permission.edit_plan, "deny")
       assert.equal(cfg.agent.general.permission.plan_exit, "deny")
       assert.equal(cfg.agent.general.permission.submit_plan, "deny")
       assert.equal(cfg.agent.general.permission.webfetch, "deny")
+      assert.equal(cfg.agent.explore.permission.edit_plan, "deny")
       assert.equal(cfg.agent.explore.permission.plan_exit, "deny")
       assert.equal(cfg.agent.explore.permission.submit_plan, "deny")
     },
   )
 })
 
+test("edit_plan opens the current session plan in the configured editor", async () => {
+  await withEnv(
+    {
+      VISUAL: "true",
+      EDITOR: "false",
+    },
+    async () => {
+      await withPlanFile(
+        ".opencode/plans/ses_edit.md",
+        "# Edited plan\n\n- reviewed\n",
+        async () => {
+          const plugin = await plannerPlugin()
+          const output = await plugin.tool.edit_plan.execute(
+            {},
+            {
+              sessionID: "ses_edit",
+            },
+          )
+
+          assert.match(output, /edited in your external editor/i)
+          assert.match(output, /# Edited plan/)
+        },
+      )
+    },
+  )
+})
+
+test("edit_plan reports when no blocking editor command is configured", async () => {
+  await withEnv(
+    {
+      VISUAL: undefined,
+      EDITOR: undefined,
+    },
+    async () => {
+      const plugin = await plannerPlugin()
+      await assert.rejects(
+        plugin.tool.edit_plan.execute(
+          {},
+          {
+            sessionID: "ses_edit",
+          },
+        ),
+        /Neither `VISUAL` nor `EDITOR` is set/i,
+      )
+    },
+  )
+})
+
 test("chat.message injects a planner reminder part", async () => {
   await withEnv(
     {
@@ -166,6 +232,7 @@ test("chat.message injects a planner reminder part", async () => {
       assert.match(output.parts[0].id, /^prt_/)
       assert.match(output.parts[0].text, /Planner mode is active\./)
       assert.match(output.parts[0].text, /if the submit_plan tool is available/i)
+      assert.match(output.parts[0].text, /call edit_plan to open the markdown plan/i)
       assert.match(output.parts[0].text, /ask for review in chat/i)
       assert.match(output.parts[0].text, /plan_exit/)
     },
@@ -204,6 +271,7 @@ test("system transform only applies after planner messages", async () => {
 
       assert.equal(system.system.length, 1)
       assert.match(system.system[0], /if the submit_plan tool is available/i)
+      assert.match(system.system[0], /call edit_plan to open the markdown plan/i)
       assert.match(system.system[0], /ask for review in chat/i)
       assert.match(system.system[0], /plan_exit/)
     },
@@ -231,6 +299,7 @@ test("plan_prompt tool returns the plugin prompt basis without plan_exit by defa
       assert.match(output, /## Planner reminder/)
       assert.match(output, /injected by the plugin at runtime/i)
       assert.match(output, /not customized through `agent\.plan\.prompt`/i)
+      assert.match(output, /call edit_plan to open the markdown plan/i)
       assert.match(output, /```json/)
       assert.match(output, /"agent": \{/)
       assert.match(output, /\.opencode\/plans\/ses_tool\.md/)