feat: support PLAN_VISUAL override for plan review

Author: timrichardson

README.md

@@ -86,10 +86,11 @@ Example:
 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.
+`edit_plan` uses `PLAN_VISUAL` first, then `VISUAL`, then `EDITOR`. `PLAN_VISUAL` is useful when you want planner review to use a different editor from the rest of your shell tools. The command must launch a separate process and block until editing is complete.
 
 Compatible examples:
 
+- `PLAN_VISUAL="gvim -f"`
 - `VISUAL="gvim -f"`
 - `EDITOR="gedit --wait"`
 - `EDITOR="kate --block"`

index.js

@@ -133,14 +133,14 @@ function restrictPlannerSubagent(input = {}) {
 }
 
 function editorCommand() {
-  return process.env.VISUAL?.trim() || process.env.EDITOR?.trim() || ""
+  return process.env.PLAN_VISUAL?.trim() || 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.",
+      "None of `PLAN_VISUAL`, `VISUAL`, or `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.",
     )
   }
 
@@ -168,7 +168,7 @@ function runEditor(target) {
       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.`,
+          `The external editor command exited with status ${code}${suffix}. Configure PLAN_VISUAL, VISUAL, or EDITOR to launch a separate process that waits until editing is complete.`,
         ),
       )
     })

test/plugin.test.js

@@ -6,6 +6,9 @@ import plannerPlugin from "../index.js"
 
 async function withEnv(env, fn) {
   const previous = {
+    PLAN_VISUAL: process.env.PLAN_VISUAL,
+    VISUAL: process.env.VISUAL,
+    EDITOR: process.env.EDITOR,
     OPENCODE_EXPERIMENTAL: process.env.OPENCODE_EXPERIMENTAL,
     OPENCODE_EXPERIMENTAL_PLAN_MODE: process.env.OPENCODE_EXPERIMENTAL_PLAN_MODE,
     OPENCODE_CLIENT: process.env.OPENCODE_CLIENT,
@@ -159,6 +162,7 @@ test("config hook denies review handoff tools for planner subagents", async () =
 test("edit_plan opens the current session plan in the configured editor", async () => {
   await withEnv(
     {
+      PLAN_VISUAL: undefined,
       VISUAL: "true",
       EDITOR: "false",
     },
@@ -183,9 +187,37 @@ test("edit_plan opens the current session plan in the configured editor", async
   )
 })
 
+test("edit_plan prefers PLAN_VISUAL over VISUAL and EDITOR", async () => {
+  await withEnv(
+    {
+      PLAN_VISUAL: "true",
+      VISUAL: "false",
+      EDITOR: "false",
+    },
+    async () => {
+      await withPlanFile(
+        ".opencode/plans/ses_edit_override.md",
+        "# Edited with PLAN_VISUAL\n",
+        async () => {
+          const plugin = await plannerPlugin()
+          const output = await plugin.tool.edit_plan.execute(
+            {},
+            {
+              sessionID: "ses_edit_override",
+            },
+          )
+
+          assert.match(output, /# Edited with PLAN_VISUAL/)
+        },
+      )
+    },
+  )
+})
+
 test("edit_plan reports when no blocking editor command is configured", async () => {
   await withEnv(
     {
+      PLAN_VISUAL: undefined,
       VISUAL: undefined,
       EDITOR: undefined,
     },
@@ -198,7 +230,7 @@ test("edit_plan reports when no blocking editor command is configured", async ()
             sessionID: "ses_edit",
           },
         ),
-        /Neither `VISUAL` nor `EDITOR` is set/i,
+        /None of `PLAN_VISUAL`, `VISUAL`, or `EDITOR` is set/i,
       )
     },
   )