chore(release): publish 0.3.1

Author: timrichardson

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.3.1
+
+- add a `planner_config` diagnostic tool and `/planner-config` command for inspecting planner runtime and editor configuration
+
 ## 0.3.0
 
 - add an `/edit-plan` command that routes to the `plan` agent and reuses the existing `edit_plan` tool flow

README.md

@@ -37,7 +37,7 @@ If you want reproducible installs instead of automatic plugin refreshes, pin an
 
 ```json
 {
-  "plugin": ["opencode-planner@0.3.0"]
+  "plugin": ["opencode-planner@0.3.1"]
 }
 ```
 
@@ -49,9 +49,11 @@ If you want reproducible installs instead of automatic plugin refreshes, pin an
 - 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`, `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 `planner_config` tool so the `plan` agent can inspect planner-specific runtime and editor configuration
 - exposes a `plan_prompt` tool so the `plan` agent can reveal the plugin's prompt basis for customization
 - exposes an `edit_plan` tool so the `plan` agent can open the current plan in the configured external editor
 - registers an `/edit-plan` command that routes to the `plan` agent and asks it to call `edit_plan`
+- registers a `/planner-config` command that routes to the `plan` agent and asks it to call `planner_config`
 - uses `submit_plan` for review when available, otherwise falls back to external-editor review
 - keeps the agent in planner mode if the plan file changed after `submit_plan`; the revised plan must be resubmitted before `plan_exit`
 - can leave planner mode with `plan_exit` after approval when experimental plan mode is enabled in the CLI runtime (because the plan_exit tool is only available with `EXPERIMENTAL_PLAN_MODE` enabled; se OpenCode docs for Experiments)
@@ -90,6 +92,30 @@ 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`
 
+## Diagnose planner configuration
+
+The plugin also adds a read-only `planner_config` tool. Use it when you want to inspect planner-specific configuration, especially editor selection precedence across `PLAN_VISUAL`, `VISUAL`, and `EDITOR`.
+
+In the TUI, `/planner-config` is the shortcut for this diagnostic flow.
+
+Example:
+
+```text
+/planner-config
+```
+
+The output includes:
+
+- the current session plan path
+- planner tool availability from the plugin's perspective
+- whether `submit_plan` is available for Plannotator review and `edit_plan` is available as the local-editor fallback
+- editor precedence: `PLAN_VISUAL` -> `VISUAL` -> `EDITOR`
+- which editor variable won
+- the resolved editor command
+- relevant runtime flags that affect planner behavior, such as `OPENCODE_EXPERIMENTAL_PLAN_MODE` and `OPENCODE_CLIENT`
+
+This is the quickest way to understand why `edit_plan` is using a specific editor command before you try `/edit-plan`.
+
 ## Review Without Plannotator
 
 In the TUI, you can use `/edit-plan` as a shortcut to ask the `plan` agent to reopen the current plan in your configured external editor. This routes through the existing `edit_plan` tool behavior.
@@ -161,7 +187,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`, `edit_plan`, `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 `planner_config`, `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:
 
@@ -181,7 +207,7 @@ It starts OpenCode with an isolated temporary home/config, keeps the local repo
 1. Update `CHANGELOG.md`.
 2. Bump the version in `package.json`.
 3. Commit the release.
-4. Create and push a git tag like `v0.3.0` for the release.
+4. Create and push a git tag like `v0.3.1` for the release.
 5. Let GitHub Actions publish to npm `latest`.
 6. Publish matching GitHub release notes.
 
@@ -198,7 +224,7 @@ Configure npm Trusted Publishing for this package:
    - Repository: `opencode-planner`
    - Workflow filename: `release.yml`
 
-The release workflow publishes stable tags like `v0.3.0` to npm `latest` and creates matching GitHub release notes automatically.
+The release workflow publishes stable tags like `v0.3.1` to npm `latest` and creates matching GitHub release notes automatically.
 
 Trusted Publishing uses GitHub OIDC and does not require an `NPM_TOKEN` secret for publishing.
 

index.js

@@ -13,6 +13,12 @@ const editPlanCommand = {
   template:
     "Reopen the current markdown plan in the configured external editor by calling the edit_plan tool. If the tool reports that the user changed the plan externally, treat those edits as review feedback, summarize what changed, and continue planning from the updated plan.",
 }
+const plannerConfigCommand = {
+  description: "Show planner configuration details",
+  agent,
+  template:
+    "Call the planner_config tool for the current session and return its output so the user can inspect planner tool availability, editor resolution, and relevant runtime flags.",
+}
 
 function truthy(key) {
   const value = process.env[key]?.toLowerCase()
@@ -136,14 +142,38 @@ function restrictPlannerSubagent(input = {}) {
     ...input,
     permission: merge(input?.permission, {
       edit_plan: "deny",
+      planner_config: "deny",
       plan_exit: "deny",
       submit_plan: "deny",
     }),
   }
 }
 
+function editorConfig() {
+  const variables = ["PLAN_VISUAL", "VISUAL", "EDITOR"].map((key) => {
+    const value = process.env[key]?.trim() ?? ""
+    return {
+      key,
+      value,
+      set: Boolean(value),
+    }
+  })
+
+  const selected = variables.find((entry) => entry.set) ?? null
+
+  return {
+    variables,
+    selected,
+    command: selected?.value ?? "",
+  }
+}
+
 function editorCommand() {
-  return process.env.PLAN_VISUAL?.trim() || process.env.VISUAL?.trim() || process.env.EDITOR?.trim() || ""
+  return editorConfig().command
+}
+
+function formatSetting(value) {
+  return value ? `\`${value}\`` : "<unset>"
 }
 
 function hashPlan(content) {
@@ -284,6 +314,39 @@ async function editPlan(sessionID) {
   ].join("\n")
 }
 
+function plannerConfig(sessionID) {
+  const target = file(sessionID ?? "<session-id>")
+  const permission = mode().permission
+  const editor = editorConfig()
+  const planExitEnabled = hasPlanExit()
+
+  return [
+    "# opencode-planner configuration",
+    "## Planner files",
+    `- Current session plan path: \`${target}\``,
+    `- Default plan path pattern: \`${defaultPlanTarget}\``,
+    "",
+    "## Planner tools",
+    `- plan_prompt: ${permission.plan_prompt === "allow" ? "allowed by the `plan` agent" : "not allowed by the `plan` agent"}`,
+    `- edit_plan: ${permission.edit_plan === "allow" ? "allowed by the `plan` agent as the fallback local-editor review tool" : "not allowed by the `plan` agent"}`,
+    `- planner_config: ${permission.planner_config === "allow" ? "allowed by the `plan` agent" : "not allowed by the `plan` agent"}`,
+    `- submit_plan: ${permission.submit_plan === "allow" ? "allowed by the `plan` agent and required for Plannotator review; availability still depends on the host runtime" : "not allowed by the `plan` agent"}`,
+    `- plan_exit: ${planExitEnabled ? "enabled by the current runtime flags when the host runtime provides it" : "not enabled by the current runtime flags"}`,
+    "",
+    "## Editor resolution",
+    "- Precedence: `PLAN_VISUAL` -> `VISUAL` -> `EDITOR`",
+    ...editor.variables.map((entry) => `- ${entry.key}: ${formatSetting(entry.value)}`),
+    `- Selected source: ${editor.selected ? `\`${editor.selected.key}\`` : "none"}`,
+    `- Selected command: ${formatSetting(editor.command)}`,
+    "",
+    "## Runtime flags",
+    `- OPENCODE_EXPERIMENTAL: ${formatSetting(process.env.OPENCODE_EXPERIMENTAL?.trim() ?? "")}`,
+    `- OPENCODE_EXPERIMENTAL_PLAN_MODE: ${formatSetting(process.env.OPENCODE_EXPERIMENTAL_PLAN_MODE?.trim() ?? "")}`,
+    `- OPENCODE_CLIENT: ${formatSetting(process.env.OPENCODE_CLIENT?.trim() ?? "")}`,
+    `- plan_exit expected: ${planExitEnabled ? "yes" : "no"}`,
+  ].join("\n")
+}
+
 function mode(input = {}) {
   const base = {
     mode: "primary",
@@ -311,6 +374,7 @@ function mode(input = {}) {
       codesearch: "allow",
       batch: "allow",
       edit_plan: "allow",
+      planner_config: "allow",
       plan_prompt: "allow",
       submit_plan: "allow",
       ...(hasPlanExit() ? { plan_exit: "allow" } : {}),
@@ -356,10 +420,18 @@ export default async function plannerPlugin() {
           return editPlan(context.sessionID)
         },
       },
+      planner_config: {
+        description: "Show planner configuration details for the current session",
+        args: {},
+        async execute(_, context) {
+          return plannerConfig(context.sessionID)
+        },
+      },
     },
     async config(cfg) {
       cfg.agent ??= {}
       cfg.command = {
+        "planner-config": plannerConfigCommand,
         "edit-plan": editPlanCommand,
         ...cfg.command,
       }

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-planner",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Experimental OpenCode plugin that adds a dedicated planning agent with read-only planning constraints.",
   "type": "module",
   "author": "Tim Richardson",

package.json

@@ -42,12 +42,15 @@ const tools = plan.tools ?? {}
 const prompt = plan.prompt ?? ""
 
 const editPlanCommandConfigured = Boolean(commands["edit-plan"])
+const plannerConfigCommandConfigured = Boolean(commands["planner-config"])
 const planPromptAllowed = hasAllowedPermission("plan_prompt", permissions)
 const editPlanAllowed = hasAllowedPermission("edit_plan", permissions)
+const plannerConfigAllowed = hasAllowedPermission("planner_config", 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 plannerConfigTool = Boolean(tools.planner_config)
 const planExitTool = Boolean(tools.plan_exit)
 const submitPlanTool = Boolean(tools.submit_plan)
 const usingLocalPlugin = plugins.includes(localPlugin)
@@ -57,10 +60,13 @@ console.log("OpenCode plan runtime check")
 console.log("")
 line("Repo plugin loaded", usingLocalPlugin ? "yes" : "no")
 line("/edit-plan command", editPlanCommandConfigured ? "yes" : "no")
+line("/planner-config command", plannerConfigCommandConfigured ? "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("planner_config allowed", plannerConfigAllowed ? "yes" : "no")
+line("planner_config tool", plannerConfigTool ? "yes" : "no")
 line("submit_plan allowed", submitPlanAllowed ? "yes" : "no")
 line("plan_exit allowed", planExitAllowed ? "yes" : "no")
 line("submit_plan tool", submitPlanTool ? "yes" : "no")
@@ -84,12 +90,18 @@ if (!usingLocalPlugin) {
 if (!editPlanCommandConfigured) {
   console.log("- /edit-plan is not configured in the resolved command list.")
 }
+if (!plannerConfigCommandConfigured) {
+  console.log("- /planner-config is not configured in the resolved command list.")
+}
 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 (!plannerConfigTool) {
+  console.log("- planner_config is not registered as a runtime tool.")
+}
 if (!submitPlanTool) {
   console.log("- submit_plan is not registered as a runtime tool.")
 }