opencode-resolve 0.1.0 → 0.1.2

package/README.md

@@ -3,28 +3,67 @@
 [![npm version](https://img.shields.io/npm/v/opencode-resolve.svg)](https://www.npmjs.com/package/opencode-resolve)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
-Lightweight OpenCode plugin for focused task resolution with minimal agents and native `plan`/`build` preservation.
+Small OpenCode plugin that turns a single instruction into a finished, verified change.
 
-`opencode-resolve` keeps native OpenCode `plan` and `build` behavior intact. It only injects a small set of optional agents so you can keep the useful early Oh My OpenCode-style persistence without a heavy multi-agent swarm.
+`opencode-resolve` ships three roles by default — **resolver** (orchestrator), **coder** (implementer), and **reviewer** (read-only auditor) — and runs them with auto-approved permissions so a task drives to completion without prompting at every step. It defines roles, not model providers: agents inherit your OpenCode default model unless you pin them.
 
-## Features
+---
 
-- Preserves native OpenCode `plan` and `build` behavior.
-- Injects only `coder` and `reviewer` by default.
-- Uses GLM-style defaults for coding and GPT-style defaults for review.
-- Adds a Context7 MCP preset only when one is not already configured.
-- Validates config strictly so typos fail fast.
-- Keeps Telegram notifications and remote control as companion-plugin concerns.
+## Table of Contents
 
-## Install From npm
+- [Roles at a glance](#roles-at-a-glance)
+- [Quick Start](#quick-start)
+- [Drop-in setup (give to an LLM)](#drop-in-setup-give-to-an-llm)
+- [Default Behavior](#default-behavior)
+- [Configuration](#configuration)
+- [Configuration Reference](#configuration-reference)
+- [Auto Approval](#auto-approval)
+- [Parallel Subagent Limit](#parallel-subagent-limit)
+- [Upgrade & Migration](#upgrade--migration)
+- [Model Setup](#model-setup)
+- [Agent Reference](#agent-reference)
+- [Optional Commands](#optional-commands)
+- [Local Development](#local-development)
+- [Verification](#verification)
+- [Release](#release)
+- [Design Rules](#design-rules)
 
-Install this where OpenCode resolves plugins from. For most users, a global install is the simplest option:
+---
+
+## Roles at a glance
+
+| Role | Default | Can edit? | Can run shell? | Purpose |
+|---|:---:|:---:|:---:|---|
+| `resolver` | Yes | Yes (auto) | Yes (auto) | Primary orchestrator. Plans, dispatches `coder` (one at a time), verifies, iterates. |
+| `coder` | Yes | Yes (auto) | Yes (auto) | Focused implementer. Makes the smallest correct change and verifies. |
+| `reviewer` | Yes | **Never** | **Never** | Read-only auditor. Inspects only — recommends fixes for `coder` or `resolver` to apply. |
+
+Hard rule: **the reviewer cannot modify the project by any means.** Both `edit` and `bash` are denied for the reviewer regardless of `autoApprove`. Any required fix is routed back through `coder` or `resolver`.
+
+---
+
+## Quick Start
+
+Install from npm:
 
 ```sh
 npm install -g opencode-resolve
 ```
 
-Then add it to your OpenCode config:
+The package `postinstall` step:
+
+1. Adds `opencode-resolve` to `~/.config/opencode/opencode.json` `plugin` array.
+2. Creates `~/.config/opencode/resolve.json` from [`opencode-resolve.example.json`](./opencode-resolve.example.json) when missing.
+
+Restart OpenCode after installation.
+
+To skip automatic registration:
+
+```sh
+OPENCODE_RESOLVE_SKIP_POSTINSTALL=1 npm install -g opencode-resolve
+```
+
+Manual fallback: add the plugin to `~/.config/opencode/opencode.json` yourself:
 
 ```json
 {
@@ -32,150 +71,390 @@ Then add it to your OpenCode config:
 }
 ```
 
-The default model IDs assume your OpenCode provider configuration can access Z.AI/GLM and OpenAI/GPT models. Override `models` if your provider IDs differ.
+---
 
-## Defaults
+## Drop-in setup (give to an LLM)
 
-Enabled by default:
+Hand the block below to any reasonably capable LLM along with the instruction _"set up opencode-resolve on this machine"_ and it can finish the install end-to-end. Everything below is the entire required configuration — no other MCP servers, environment variables, or files are needed.
 
-- `coder`: GLM-based implementation agent for edits, tests, and iteration.
-- `reviewer`: GPT-based Oracle-style review agent for requirements fit, correctness, security, tests, and maintainability.
+**Step 1 — install the plugin:**
 
-Available but disabled unless configured:
+```sh
+npm install -g opencode-resolve
+```
 
-- `architect`: GPT-based design and task decomposition.
-- `gpt-coder`: GPT-based difficult implementation fallback.
-- `debugger`: failure reproduction and root-cause analysis.
-- `researcher`: codebase and documentation research.
+**Step 2 — `~/.config/opencode/opencode.json`** (the only required keys; merge into an existing file rather than replacing if one exists):
 
-The plugin also adds a `context7` MCP preset when one is not already configured.
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "model": "<your-default-model-id>",
+  "plugin": ["opencode-resolve"]
+}
+```
 
-## Develop Locally
+**Step 3 — `~/.config/opencode/resolve.json`** (created automatically by `postinstall`; the file below is the canonical default):
 
-From this repository:
+```json
+{
+  "enabled": ["coder", "reviewer", "resolver"],
+  "preserveNative": true,
+  "context7": true,
+  "commands": false,
+  "autoApprove": true,
+  "maxParallelSubagents": 1
+}
+```
 
-```sh
-npm install
-npm test
-npm run install:local
+**Step 4 — restart OpenCode.**
+
+That is the entire setup. `context7` is the only MCP server the plugin needs (auto-registered when the key above is `true`) — no other MCP entries are required for `opencode-resolve` itself. Models are inherited from your top-level OpenCode `model` unless you pin per-role models under `models` (see [Model Setup](#model-setup)).
+
+If you want stricter behavior, flip `autoApprove` to `false` (every action prompts for approval) and/or raise `maxParallelSubagents` to let the resolver fan out independent subtasks.
+
+---
+
+## Default Behavior
+
+| Item | Default |
+|---|---|
+| Enabled agents | `coder`, `reviewer`, `resolver` |
+| Primary agent for new tasks | `resolver` (`mode: "all"`) |
+| Agent model | Inherits top-level OpenCode `model` |
+| Native `plan` / `build` | Preserved untouched |
+| Context7 MCP preset | Added if absent |
+| Optional commands | Disabled |
+| `autoApprove` | `true` (no per-action prompts on coder/resolver) |
+| Reviewer modification | Denied (cannot be auto-approved) |
+
+---
+
+## Configuration
+
+The plugin reads the first config file it finds:
+
+| Priority | Path |
+|---:|---|
+| 1 | `.opencode/resolve.json` (project) |
+| 2 | `opencode-resolve.json` (project) |
+| 3 | `~/.config/opencode/resolve.json` |
+| 4 | `~/.config/opencode/opencode-resolve.json` |
+
+Inline plugin options in `opencode.json` override file config.
+
+Config precedence:
+
+```text
+built-in defaults -> first config file found -> inline plugin options
 ```
 
-`install:local` builds the plugin, links it into the OpenCode global plugin directory, and creates `~/.config/opencode/resolve.json` if it does not exist.
+Minimal config (matches defaults):
 
-Manual equivalent:
+```json
+{
+  "enabled": ["coder", "reviewer", "resolver"],
+  "autoApprove": true,
+  "context7": true,
+  "commands": false
+}
+```
 
-```sh
-npm run build
-mkdir -p ~/.config/opencode/plugins
-ln -sf "$PWD/dist/index.js" ~/.config/opencode/plugins/opencode-resolve.js
+Inline form inside `opencode.json`:
+
+```json
+{
+  "plugin": [
+    [
+      "opencode-resolve",
+      {
+        "enabled": ["coder", "reviewer", "resolver"],
+        "autoApprove": true,
+        "context7": true,
+        "commands": false
+      }
+    ]
+  ]
+}
 ```
 
-Local plugin files are loaded automatically by OpenCode.
+Strict validation rejects unknown agent names, misspelled keys, invalid modes, invalid permission values, and wrong value types — typos fail fast.
+
+---
+
+## Configuration Reference
+
+Every accepted top-level option:
+
+| Key | Type | Default | Purpose |
+|---|---|---|---|
+| `enabled` | `string[]` | `["coder", "reviewer", "resolver"]` | Which resolve agents to inject. Per-agent `agents.<name>.enabled` overrides this. |
+| `preserveNative` | `boolean` | `true` | Native `plan`/`build` are always preserved. Accepted for readability. |
+| `context7` | `boolean` | `true` | When true, registers the Context7 MCP server unless already configured. |
+| `commands` | `boolean` | `false` | When true, adds `resolve`, `resolve-code`, `resolve-review` commands. |
+| `autoApprove` | `boolean` | `true` | Flips default `"ask"` permissions to `"allow"` on enabled agents. Never touches `"deny"` or user-set keys. |
+| `maxParallelSubagents` | `positive integer` | `1` | Cap on simultaneous subagents the resolver dispatches across coder, reviewer, etc. |
+| `models` | `object` | `{}` | Alias map. Keys are agent names or `glm`/`gpt`. Values are model ids or other aliases. |
+| `agents` | `object` | `{}` | Per-agent overrides (see below). |
+| `config` | `string` | _none_ | Custom path to a config file (relative to the project or absolute). |
+
+Per-agent options inside `agents.<name>`:
+
+| Key | Type | Notes |
+|---|---|---|
+| `enabled` | `boolean` | Force-enable or force-disable this agent regardless of top-level `enabled`. |
+| `model` | `string` | Model id or alias. Resolved against the top-level `models` map. |
+| `mode` | `"subagent" \| "primary" \| "all"` | OpenCode agent mode. |
+| `description` | `string` | Override the default description shown to other agents. |
+| `prompt` | `string` | Override the default system prompt. (For `resolver`, this also disables the templated parallel-rule prompt.) |
+| `color` | `string` | UI color. |
+| `maxSteps` | `positive integer` | Per-invocation step budget. |
+| `tools` | `Record<string, boolean>` | Toggle individual OpenCode tools. |
+| `permission` | `object` | Permission overrides — see below. |
+
+Permission keys (each takes `"ask"`, `"allow"`, or `"deny"`):
 
-After publishing/installing from npm, add the package to your OpenCode config:
+`edit`, `bash`, `webfetch`, `doom_loop`, `external_directory`.
+
+`permission.bash` may also be a per-command map:
 
 ```json
 {
-  "plugin": ["opencode-resolve"]
+  "permission": {
+    "bash": { "npm test": "allow", "rm -rf": "deny" }
+  }
 }
 ```
 
-## Configuration
+A fully-annotated reference config ships with the package as
+[`opencode-resolve.reference.jsonc`](./opencode-resolve.reference.jsonc) — copy
+the keys you need into your `resolve.json` (without the comments).
 
-The plugin reads the first config file it finds:
+---
+
+## Auto Approval
+
+`autoApprove` (default `true`) flips every `"ask"` permission on the **enabled** agents to `"allow"`, so coder and resolver work continuously without per-action prompts. It never touches `"deny"` and never overrides a permission key the user explicitly set.
+
+| Permission state | autoApprove: true | autoApprove: false |
+|---|---|---|
+| Default `"ask"` | becomes `"allow"` | stays `"ask"` |
+| Default `"deny"` | stays `"deny"` | stays `"deny"` |
+| User explicit `"ask"` | stays `"ask"` | stays `"ask"` |
+| User explicit `"allow"` | stays `"allow"` | stays `"allow"` |
+| User explicit `"deny"` | stays `"deny"` | stays `"deny"` |
+
+Reviewer permissions for `edit` and `bash` are `"deny"` in the defaults, so `autoApprove` cannot grant the reviewer modification rights.
+
+Turn it off when you want the conservative ask-every-time behavior:
 
-- `.opencode/resolve.json`
-- `opencode-resolve.json`
-- `~/.config/opencode/resolve.json`
-- `~/.config/opencode/opencode-resolve.json`
+```json
+{
+  "autoApprove": false
+}
+```
+
+Trust note: `autoApprove: true` assumes you trust the workspace and the model you have configured. Use a sandbox or VM for untrusted code, and keep `autoApprove: false` if you want to inspect every action.
+
+---
 
-Example:
+## Parallel Subagent Limit
+
+`maxParallelSubagents` (default `1`) caps how many subagents the **resolver** may dispatch in parallel — across `coder`, `reviewer`, or any other subagent. The default of `1` enforces strictly serial dispatch: resolver waits for each subagent to finish before launching the next.
+
+Raise it when you want resolver to fan out independent subtasks:
 
 ```json
 {
-  "enabled": ["coder", "reviewer"],
+  "maxParallelSubagents": 3
+}
+```
+
+The limit is woven into the resolver's prompt at config-load time, so changing it does not require any code changes — restart OpenCode to pick up the new limit. If you provide a custom `agents.resolver.prompt`, the templated rule is skipped and your prompt wins.
+
+---
+
+## Upgrade & Migration
+
+When you upgrade to a newer version of `opencode-resolve`, the `postinstall` script runs an **additive migration** on your existing `~/.config/opencode/resolve.json`:
+
+- Adds new top-level keys (e.g. `autoApprove`, `maxParallelSubagents`) with their defaults if they are absent.
+- **Never** modifies keys you have already set.
+- **Never** rewrites your `enabled` list, `models` map, or `agents` overrides.
+- If `enabled` is set and does not include `"resolver"`, prints a one-line tip suggesting you add it. Your file is left untouched.
+
+Skip the migration entirely with:
+
+```sh
+OPENCODE_RESOLVE_SKIP_POSTINSTALL=1 npm install -g opencode-resolve
+```
+
+---
+
+## Model Setup
+
+`opencode-resolve` does not ship a provider-specific role default.
+
+Model resolution order for each resolve agent:
+
+1. `agents.<name>.model`
+2. `models.<name>` alias mapping
+3. top-level OpenCode `model`
+4. OpenCode's own fallback when no model is configured
+
+Use the default config when all resolve roles should follow your current OpenCode model.
+
+Pin models only when you intentionally want fixed role behavior, such as fast coding on one model and deeper review on another.
+
+Role-specific aliases:
+
+```json
+{
+  "enabled": ["coder", "reviewer", "resolver"],
   "models": {
-    "glm": "zai-coding-plan/glm-5",
-    "gpt": "openai/gpt-5",
+    "glm": "zai-coding-plan/glm-5.1",
+    "gpt": "openai/gpt-5.5",
     "coder": "glm",
+    "resolver": "gpt",
     "reviewer": "gpt"
-  },
-  "preserveNative": true,
-  "context7": true,
-  "commands": false,
+  }
+}
+```
+
+Pin one role directly:
+
+```json
+{
   "agents": {
-    "architect": {
-      "enabled": false
-    },
-    "gpt-coder": {
-      "enabled": false,
-      "model": "gpt"
+    "reviewer": {
+      "model": "openai/gpt-5.5"
     }
   }
 }
 ```
 
-You can also pass options directly from `opencode.json`:
+Native OpenCode agents such as `plan` and `build` are configured through the top-level OpenCode `agent`, not through `opencode-resolve`.
+
+Mixed setup example:
 
 ```json
 {
+  "model": "zai-coding-plan/glm-5.1",
+  "agent": {
+    "plan": {
+      "model": "openai/gpt-5.5"
+    }
+  },
   "plugin": [
     [
       "opencode-resolve",
       {
-        "enabled": ["coder", "reviewer", "debugger"],
-        "config": "~/.config/opencode/resolve.json"
+        "enabled": ["coder", "reviewer", "resolver"],
+        "models": {
+          "glm": "zai-coding-plan/glm-5.1",
+          "gpt": "openai/gpt-5.5",
+          "coder": "glm",
+          "resolver": "gpt",
+          "reviewer": "gpt"
+        }
       }
     ]
   ]
 }
 ```
 
-Options in `opencode.json` override file config.
+In this setup, `plan`, `resolver`, and `reviewer` use `openai/gpt-5.5`; native `build` and resolve `coder` use `zai-coding-plan/glm-5.1`.
+
+---
+
+## Agent Reference
+
+| Agent | Default | Mode | Edit | Bash | WebFetch | Purpose |
+|---|:---:|---|---|---|---|---|
+| `resolver` | Yes | `all` | ask → allow | ask → allow | ask → allow | Primary orchestrator. Plans, dispatches `coder` (one at a time), verifies, iterates to completion. |
+| `coder` | Yes | `subagent` | ask → allow | ask → allow | ask → allow | Focused implementer. Smallest correct change. |
+| `reviewer` | Yes | `subagent` | **deny** | **deny** | ask → allow | Read-only auditor. Cannot modify by any means. |
+| `architect` | No | `subagent` | deny | ask → allow | ask → allow | Design and task decomposition. |
+| `gpt-coder` | No | `subagent` | ask → allow | ask → allow | ask → allow | Stronger-reasoning implementation fallback. |
+| `debugger` | No | `subagent` | ask → allow | ask → allow | ask → allow | Reproduction and root-cause analysis. |
+| `researcher` | No | `subagent` | deny | ask → allow | ask → allow | Codebase and documentation research. |
+
+`ask → allow` means the default is `"ask"` and `autoApprove` (default on) flips it to `"allow"`. Set `autoApprove: false` to keep them as `"ask"`.
+
+Supported modes:
+
+| Mode | Meaning |
+|---|---|
+| `subagent` | Available only as a subagent |
+| `primary` | Available as a primary agent |
+| `all` | Available as both primary and subagent |
+
+Supported permission values: `ask`, `allow`, `deny`.
+
+Supported model alias keys: `glm`, `gpt`, and every supported agent name. Aliases only resolve when defined in `models`.
+
+`preserveNative` is accepted for readability, but native `plan` and `build` are always preserved. The plugin never rewrites built-in OpenCode agents.
+
+### Resolver orchestration rules
 
-Config precedence is: built-in defaults, then the first config file found, then inline plugin options from `opencode.json`.
+The resolver's prompt enforces the following behavior:
 
-The config is validated on load. Unknown agent names, misspelled keys, invalid modes, invalid permission values, and wrong value types fail fast with a clear error instead of silently changing behavior.
+- Plan the smallest correct change before dispatching.
+- Dispatch **only one `coder` subagent at a time**. Never call coders in parallel.
+- After each coder run, verify (tests, type checks, targeted checks) when practical.
+- Optionally consult `reviewer` for an independent read-only audit on risky changes; route any required fixes back through `coder`.
+- Iterate until the task is resolved or clearly blocked, then return a concise summary.
 
-Supported agents:
+---
 
-- `coder`
-- `reviewer`
-- `architect`
-- `gpt-coder`
-- `debugger`
-- `researcher`
+## Optional Commands
 
-Supported model aliases:
+Set `commands: true` to add helper subtask commands:
 
-- `glm`
-- `gpt`
-- every supported agent name
+| Command | Description |
+|---|---|
+| `resolve` | Run the `resolver` agent end-to-end on the current task |
+| `resolve-code` | Run the `coder` agent for focused implementation |
+| `resolve-review` | Run the `reviewer` agent for a read-only audit |
 
-Supported agent modes are `subagent`, `primary`, and `all`. Supported permission values are `ask`, `allow`, and `deny`.
+---
 
-`preserveNative` is accepted for readability, but native `plan` and `build` are always preserved. The plugin never iterates or rewrites those built-in agents.
+## Local Development
 
-`enabled` selects the default active agents. A per-agent `agents.<name>.enabled` value overrides that list.
+From this repository:
 
-Set `context7` to `false` to disable the Context7 MCP preset.
+```sh
+npm install
+npm test
+npm run install:local
+```
 
-Set `commands` to `true` to add optional subtask commands:
+`install:local` builds the plugin, links it into the OpenCode global plugin directory, and creates `~/.config/opencode/resolve.json` if it does not exist.
 
-- `resolve-code`: run the `coder` agent for focused implementation.
-- `resolve-review`: run the `reviewer` agent for requirement/risk review.
+Manual local install:
+
+```sh
+npm run build
+mkdir -p ~/.config/opencode/plugins
+ln -sf "$PWD/dist/index.js" ~/.config/opencode/plugins/opencode-resolve.js
+```
+
+Local plugin files are loaded automatically by OpenCode.
+
+---
 
 ## Verification
 
+Run the normal checks:
+
 ```sh
 npm run typecheck
 npm test
 npm run build
 ```
 
-The test suite executes the built plugin and verifies default agent injection, model aliases, file config, plugin option overrides, optional commands, Context7 preservation, and native `plan`/`build` preservation.
+The test suite executes the built plugin and verifies default agent injection, `autoApprove` behavior, model aliases, file config, plugin option overrides, optional commands, Context7 preservation, and native `plan`/`build` preservation.
 
-Before publishing, run:
+Before publishing:
 
 ```sh
 npm run typecheck
@@ -186,13 +465,17 @@ npm publish --dry-run
 
 `npm pack` and `npm publish` run `npm test` first through the `prepack` script.
 
+---
+
 ## Release
 
 Releases are published by GitHub Actions when a version tag is pushed.
 
 Required repository secret:
 
-- `NPM_TOKEN`: npm automation token with publish access.
+| Secret | Description |
+|---|---|
+| `NPM_TOKEN` | npm automation token with publish access |
 
 Tag release flow:
 
@@ -205,32 +488,12 @@ You can also run the `Publish to npm` workflow manually from GitHub Actions and
 
 The release workflow runs `npm ci`, `npm run typecheck`, `npm test`, and `npm publish --access public --provenance`.
 
+---
+
 ## Design Rules
 
 - Do not overwrite native `plan` or `build` agents.
-- Keep default subagent count small.
-- Search and inspect before editing.
-- Make the smallest correct change.
-- Verify when practical.
-- Use reviewer for final requirement/risk checks instead of running many agents by default.
-
-## Companion Plugins
-
-`opencode-resolve` intentionally stays focused on agent injection and task resolution. Use notification or remote-control plugins alongside it instead of baking those concerns into this package.
-
-Recommended companion:
-
-- [`@jshsakura/opencode-telegram-bot-plugin`](https://github.com/jshsakura/opencode-telegram-bot-plugin): Telegram notifications and permission-response support for OpenCode sessions.
-
-Install and configure the Telegram plugin separately. It needs its own bot token/chat setup; see that plugin's README for details.
-
-Example:
-
-```json
-{
-  "plugin": [
-    "opencode-resolve",
-    "@jshsakura/opencode-telegram-bot-plugin"
-  ]
-}
-```
+- Keep the default agent set small and role-clear: `resolver` orchestrates, `coder` modifies, `reviewer` only reads.
+- The reviewer never modifies anything — fixes always go through `coder` or `resolver`.
+- The resolver dispatches at most one coder at a time.
+- Search and inspect before editing. Make the smallest correct change. Verify when practical.

package/dist/index.js

@@ -1,18 +1,9 @@
 import { access, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, isAbsolute, join, resolve } from "node:path";
-const DEFAULT_MODELS = {
-    glm: "zai-coding-plan/glm-5",
-    gpt: "openai/gpt-5",
-    coder: "zai-coding-plan/glm-5",
-    reviewer: "openai/gpt-5",
-    architect: "openai/gpt-5",
-    "gpt-coder": "openai/gpt-5",
-    debugger: "zai-coding-plan/glm-5",
-    researcher: "zai-coding-plan/glm-5",
-};
-const DEFAULT_ENABLED = ["coder", "reviewer"];
-const VALID_AGENT_NAMES = ["coder", "reviewer", "architect", "gpt-coder", "debugger", "researcher"];
+const DEFAULT_MODELS = {};
+const DEFAULT_ENABLED = ["coder", "reviewer", "resolver"];
+const VALID_AGENT_NAMES = ["coder", "reviewer", "resolver", "architect", "gpt-coder", "debugger", "researcher"];
 const VALID_AGENT_NAME_SET = new Set(VALID_AGENT_NAMES);
 const VALID_MODEL_ALIASES = [...VALID_AGENT_NAMES, "glm", "gpt"];
 const VALID_MODEL_ALIAS_SET = new Set(VALID_MODEL_ALIASES);
@@ -25,8 +16,11 @@ const VALID_TOP_LEVEL_KEYS = new Set([
     "preserveNative",
     "context7",
     "commands",
+    "autoApprove",
+    "maxParallelSubagents",
     "config",
 ]);
+const DEFAULT_MAX_PARALLEL_SUBAGENTS = 1;
 const VALID_AGENT_KEYS = new Set([
     "enabled",
     "model",
@@ -38,6 +32,26 @@ const VALID_AGENT_KEYS = new Set([
     "tools",
     "permission",
 ]);
+function buildResolverPrompt(maxParallelSubagents) {
+    const limit = Math.max(1, Math.trunc(maxParallelSubagents));
+    const parallelRule = limit === 1
+        ? "CRITICAL: Dispatch only ONE subagent at a time. Never call multiple subagents (coder, reviewer, or any other) in parallel. Wait for the current subagent to finish and evaluate its result before dispatching the next one."
+        : `CRITICAL: Dispatch at most ${limit} subagents in parallel. Never exceed this limit across coder, reviewer, or any other subagent. Wait for in-flight subagents to finish and evaluate their results before launching new ones.`;
+    return [
+        "You are Resolver, the primary orchestrator agent for OpenCode Resolve.",
+        "Your job is to drive the user's task to a verified resolution end-to-end without unnecessary stops.",
+        "Workflow:",
+        "1. Understand the requirement. Inspect the relevant files briefly before planning.",
+        "2. Plan the smallest correct change.",
+        "3. Dispatch the coder subagent to implement the change. Pass a focused instruction with the exact files and behavior.",
+        `4. ${parallelRule}`,
+        "5. After implementation, verify when practical (run tests, type checks, or targeted checks).",
+        "6. If issues remain, dispatch the coder again with a focused fix, or apply a small direct edit yourself when it is clearly trivial.",
+        "7. Optionally consult the reviewer subagent for an independent read-only review on risky changes. The reviewer cannot modify anything; treat its output as advice and route any required fixes back through the coder. The same parallel-dispatch limit applies to the reviewer.",
+        "8. Repeat until the task is resolved or clearly blocked.",
+        "Return a concise summary of what changed, verification results, and any remaining blockers.",
+    ].join("\n");
+}
 const DEFAULT_AGENT_CONFIG = {
     coder: {
         mode: "subagent",
@@ -61,16 +75,29 @@ const DEFAULT_AGENT_CONFIG = {
         mode: "subagent",
         color: "#8A7CFF",
         maxSteps: 8,
-        description: "Use for Oracle-style review of requirements fit, correctness, security, tests, and maintainability risks.",
+        description: "Read-only Oracle-style reviewer. Inspects code for requirements fit, correctness, security, tests, and maintainability risks. Never modifies anything.",
         prompt: [
-            "You are Reviewer, an Oracle-style review subagent for OpenCode Resolve.",
-            "Review the work against the user's actual requirements and the repository's existing patterns.",
+            "You are Reviewer, a strictly read-only review subagent for OpenCode Resolve.",
+            "You MUST NOT modify the project by any means: no file edits, no writes, no shell commands that change state, no git commits, no package installs.",
+            "Use read-only tools (read, grep, glob, list, web fetch for documentation) to inspect the work against the user's requirements and the repository's existing patterns.",
             "Prioritize concrete bugs, behavioral regressions, security risks, missing tests, and maintainability issues.",
-            "Do not rewrite code unless explicitly asked; return findings ordered by severity with file and line references when available.",
-            "If there are no findings, say so and mention residual risks or verification gaps.",
+            "Return findings ordered by severity with file and line references when available. If there are no findings, say so and mention residual risks or verification gaps.",
+            "If a fix is needed, describe it precisely and recommend dispatching the coder or resolver agent. Never apply fixes yourself.",
         ].join("\n"),
         permission: {
             edit: "deny",
+            bash: "deny",
+            webfetch: "ask",
+        },
+    },
+    resolver: {
+        mode: "all",
+        color: "#FF7AC6",
+        maxSteps: 30,
+        description: "Primary orchestrator. Drives a task to completion by planning, dispatching subagents (one at a time by default), and verifying results. Iterates until the task is resolved or clearly blocked.",
+        prompt: buildResolverPrompt(DEFAULT_MAX_PARALLEL_SUBAGENTS),
+        permission: {
+            edit: "ask",
             bash: "ask",
             webfetch: "ask",
         },
@@ -166,6 +193,9 @@ async function loadResolveConfig(directory, opencodeConfig, options) {
 function applyResolveConfig(config, resolveConfig) {
     const enabled = new Set(resolveConfig.enabled ?? DEFAULT_ENABLED);
     const models = { ...DEFAULT_MODELS, ...resolveConfig.models };
+    const defaultModel = typeof config.model === "string" ? config.model : undefined;
+    const autoApprove = resolveConfig.autoApprove !== false;
+    const maxParallelSubagents = resolveConfig.maxParallelSubagents ?? DEFAULT_MAX_PARALLEL_SUBAGENTS;
     config.agent ??= {};
     for (const name of Object.keys(DEFAULT_AGENT_CONFIG)) {
         const override = resolveConfig.agents?.[name];
@@ -173,13 +203,21 @@ function applyResolveConfig(config, resolveConfig) {
         if (!isEnabled)
             continue;
         const base = DEFAULT_AGENT_CONFIG[name];
-        const { enabled: _enabled, ...agentOverride } = override ?? {};
-        const model = resolveModel(agentOverride.model ?? models[name], models);
-        config.agent[name] = {
+        const { enabled: _enabled, model: requestedModel, permission: userPermission, ...agentOverride } = override ?? {};
+        const model = resolveModel(requestedModel ?? models[name] ?? defaultModel, models);
+        const permission = buildPermission(base.permission, userPermission, autoApprove);
+        const agentConfig = {
             ...base,
             ...agentOverride,
-            model,
         };
+        if (name === "resolver" && agentOverride.prompt === undefined) {
+            agentConfig.prompt = buildResolverPrompt(maxParallelSubagents);
+        }
+        if (permission)
+            agentConfig.permission = permission;
+        if (model)
+            agentConfig.model = model;
+        config.agent[name] = agentConfig;
     }
     if (resolveConfig.context7 !== false) {
         config.mcp ??= {};
@@ -190,9 +228,15 @@ function applyResolveConfig(config, resolveConfig) {
     }
     if (resolveConfig.commands) {
         config.command ??= {};
+        config.command["resolve"] ??= {
+            template: "Drive this task to a verified resolution end-to-end. Plan, dispatch one coder at a time, verify, and iterate. $ARGUMENTS",
+            description: "Run the OpenCode Resolve resolver agent end-to-end",
+            agent: "resolver",
+            subtask: true,
+        };
         config.command["resolve-review"] ??= {
-            template: "Review the current implementation against the user's requirements. Focus on correctness, tests, security, and maintainability.",
-            description: "Run the OpenCode Resolve reviewer agent",
+            template: "Review the current implementation against the user's requirements. Focus on correctness, tests, security, and maintainability. Do not modify anything.",
+            description: "Run the OpenCode Resolve reviewer agent (read-only)",
             agent: "reviewer",
             subtask: true,
         };
@@ -207,11 +251,13 @@ function applyResolveConfig(config, resolveConfig) {
 function defaultResolveConfig() {
     return {
         enabled: DEFAULT_ENABLED,
-        models: DEFAULT_MODELS,
+        models: {},
         agents: {},
         preserveNative: true,
         context7: true,
         commands: false,
+        autoApprove: true,
+        maxParallelSubagents: DEFAULT_MAX_PARALLEL_SUBAGENTS,
     };
 }
 function mergeResolveConfig(...configs) {
@@ -223,6 +269,8 @@ function mergeResolveConfig(...configs) {
         result.preserveNative = config.preserveNative ?? result.preserveNative;
         result.context7 = config.context7 ?? result.context7;
         result.commands = config.commands ?? result.commands;
+        result.autoApprove = config.autoApprove ?? result.autoApprove;
+        result.maxParallelSubagents = config.maxParallelSubagents ?? result.maxParallelSubagents;
         result.models = { ...result.models, ...config.models };
         result.agents = mergeAgents(result.agents, config.agents);
     }
@@ -240,6 +288,27 @@ function resolveModel(model, models) {
         return undefined;
     return models[model] ?? model;
 }
+function buildPermission(basePermission, userPermission, autoApprove) {
+    const merged = {
+        ...(basePermission ?? {}),
+        ...(userPermission ?? {}),
+    };
+    if (Object.keys(merged).length === 0)
+        return undefined;
+    if (!autoApprove)
+        return merged;
+    const userKeys = new Set(Object.keys(userPermission ?? {}));
+    const result = { ...merged };
+    for (const key of Object.keys(result)) {
+        if (userKeys.has(key))
+            continue;
+        const value = result[key];
+        if (value === "ask") {
+            result[key] = "allow";
+        }
+    }
+    return result;
+}
 function getPluginOptions(config) {
     for (const entry of config.plugin ?? []) {
         if (Array.isArray(entry) && isResolvePluginEntry(entry[0])) {
@@ -310,6 +379,15 @@ function normalizeResolveConfig(value, source) {
         result.context7 = expectBoolean(config.context7, `${source}.context7`);
     if (config.commands !== undefined)
         result.commands = expectBoolean(config.commands, `${source}.commands`);
+    if (config.autoApprove !== undefined)
+        result.autoApprove = expectBoolean(config.autoApprove, `${source}.autoApprove`);
+    if (config.maxParallelSubagents !== undefined) {
+        const limit = expectNumber(config.maxParallelSubagents, `${source}.maxParallelSubagents`);
+        if (!Number.isInteger(limit) || limit < 1) {
+            throw new Error(`${source}.maxParallelSubagents must be a positive integer`);
+        }
+        result.maxParallelSubagents = limit;
+    }
     if (config.config !== undefined)
         result.config = expectString(config.config, `${source}.config`);
     return result;

package/opencode-resolve.example.json

@@ -1,19 +1,21 @@
 {
-  "enabled": ["coder", "reviewer"],
-  "models": {
-    "glm": "zai-coding-plan/glm-5",
-    "gpt": "openai/gpt-5",
-    "coder": "glm",
-    "reviewer": "gpt",
-    "architect": "gpt",
-    "gpt-coder": "gpt",
-    "debugger": "glm",
-    "researcher": "glm"
-  },
+  "enabled": ["coder", "reviewer", "resolver"],
   "preserveNative": true,
   "context7": true,
   "commands": false,
+  "autoApprove": true,
+  "maxParallelSubagents": 1,
+  "models": {},
   "agents": {
+    "coder": {
+      "enabled": true
+    },
+    "reviewer": {
+      "enabled": true
+    },
+    "resolver": {
+      "enabled": true
+    },
     "architect": {
       "enabled": false
     },

package/opencode-resolve.reference.jsonc

@@ -0,0 +1,164 @@
+// opencode-resolve.reference.jsonc
+//
+// This file documents EVERY option opencode-resolve accepts. It is NOT loaded
+// by the plugin (the plugin only reads .json). Copy what you need into
+// `~/.config/opencode/resolve.json`, `.opencode/resolve.json`, or
+// `opencode-resolve.json` (without the comments).
+//
+// Config file lookup order (first one found wins):
+//   1. <project>/.opencode/resolve.json
+//   2. <project>/opencode-resolve.json
+//   3. ~/.config/opencode/resolve.json
+//   4. ~/.config/opencode/opencode-resolve.json
+//
+// Inline plugin options inside opencode.json override the file config.
+//
+// Validation is strict: unknown keys, misspellings, invalid modes, invalid
+// permission values, and wrong types throw an error at load time.
+
+{
+  // -----------------------------------------------------------------------
+  // enabled (string[])
+  // Which resolve agents to inject. Default: ["coder", "reviewer", "resolver"].
+  // Native OpenCode agents (plan, build) are always preserved and never
+  // touched by this list. Per-agent `agents.<name>.enabled` overrides this.
+  // -----------------------------------------------------------------------
+  "enabled": ["coder", "reviewer", "resolver"],
+
+  // -----------------------------------------------------------------------
+  // preserveNative (boolean)
+  // Always true in practice — plan/build are never rewritten. Accepted for
+  // readability. Default: true.
+  // -----------------------------------------------------------------------
+  "preserveNative": true,
+
+  // -----------------------------------------------------------------------
+  // context7 (boolean)
+  // When true, registers the Context7 MCP server unless `mcp.context7` is
+  // already configured. Default: true.
+  // -----------------------------------------------------------------------
+  "context7": true,
+
+  // -----------------------------------------------------------------------
+  // commands (boolean)
+  // When true, adds three optional commands: `resolve`, `resolve-code`,
+  // `resolve-review`. Default: false.
+  // -----------------------------------------------------------------------
+  "commands": false,
+
+  // -----------------------------------------------------------------------
+  // autoApprove (boolean)
+  // When true, every default `"ask"` permission on enabled agents is flipped
+  // to `"allow"`. Never touches `"deny"`. Never overrides a permission key
+  // you set explicitly under `agents.<name>.permission`. Default: true.
+  //
+  // Set to false for the conservative ask-every-time behavior.
+  // -----------------------------------------------------------------------
+  "autoApprove": true,
+
+  // -----------------------------------------------------------------------
+  // maxParallelSubagents (positive integer)
+  // Maximum number of subagents the resolver may dispatch in parallel
+  // (across coder, reviewer, etc.). Default: 1 — strictly serial.
+  // Increase if you want resolver to fan out independent subtasks.
+  // -----------------------------------------------------------------------
+  "maxParallelSubagents": 1,
+
+  // -----------------------------------------------------------------------
+  // models (object)
+  // Alias map. Keys are either an agent name (coder, reviewer, resolver,
+  // architect, gpt-coder, debugger, researcher) OR one of the well-known
+  // aliases (`glm`, `gpt`). Values are model identifiers OR another alias.
+  //
+  // Resolution order for a given agent:
+  //   1. agents.<name>.model
+  //   2. models.<name> (resolved through the alias map)
+  //   3. top-level OpenCode `model`
+  //   4. OpenCode's own fallback
+  // -----------------------------------------------------------------------
+  "models": {
+    "glm": "zai-coding-plan/glm-5.1",
+    "gpt": "openai/gpt-5.5",
+    "coder": "glm",
+    "resolver": "gpt",
+    "reviewer": "gpt"
+  },
+
+  // -----------------------------------------------------------------------
+  // agents (object)
+  // Per-agent overrides. Each key MUST be a valid agent name. Each entry
+  // accepts: enabled, model, mode, description, prompt, color, maxSteps,
+  // tools, permission. Unknown keys throw.
+  //
+  //   mode: "subagent" | "primary" | "all"
+  //   permission.edit | bash | webfetch | doom_loop | external_directory:
+  //     "ask" | "allow" | "deny"
+  //   permission.bash may also be a per-command map:
+  //     { "npm test": "allow", "rm -rf": "deny" }
+  // -----------------------------------------------------------------------
+  "agents": {
+    "coder": {
+      "enabled": true,
+      "model": "glm",
+      "mode": "subagent",
+      "maxSteps": 20,
+      "permission": {
+        "edit": "allow",
+        "bash": "allow",
+        "webfetch": "allow"
+      }
+    },
+
+    "reviewer": {
+      "enabled": true,
+      "model": "gpt",
+      "mode": "subagent",
+      "maxSteps": 8,
+      // Reviewer is read-only by design. edit and bash are denied even when
+      // autoApprove is true.
+      "permission": {
+        "edit": "deny",
+        "bash": "deny",
+        "webfetch": "allow"
+      }
+    },
+
+    "resolver": {
+      "enabled": true,
+      "model": "gpt",
+      "mode": "all",
+      "maxSteps": 30,
+      "permission": {
+        "edit": "allow",
+        "bash": "allow",
+        "webfetch": "allow"
+      }
+    },
+
+    // Optional agents — disabled by default. Flip enabled:true to use them.
+    "architect": {
+      "enabled": false,
+      "model": "gpt",
+      "mode": "subagent",
+      "maxSteps": 10
+    },
+    "gpt-coder": {
+      "enabled": false,
+      "model": "gpt",
+      "mode": "subagent",
+      "maxSteps": 20
+    },
+    "debugger": {
+      "enabled": false,
+      "model": "glm",
+      "mode": "subagent",
+      "maxSteps": 14
+    },
+    "researcher": {
+      "enabled": false,
+      "model": "glm",
+      "mode": "subagent",
+      "maxSteps": 8
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-resolve",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "OpenCode plugin that adds a small coder/reviewer agent set while preserving native plan/build behavior.",
   "type": "module",
   "homepage": "https://github.com/jshsakura/opencode-resolve#readme",
@@ -23,12 +23,14 @@
     "dist",
     "scripts",
     "opencode-resolve.example.json",
+    "opencode-resolve.reference.jsonc",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "install:local": "npm run build && node scripts/install-local.mjs",
+    "postinstall": "node scripts/postinstall.mjs",
     "prepack": "npm test",
     "test": "npm run build && node --test test/*.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit"

package/scripts/postinstall.mjs

@@ -0,0 +1,158 @@
+import { constants } from "node:fs"
+import { access, copyFile, mkdir, readFile, writeFile } from "node:fs/promises"
+import { homedir } from "node:os"
+import { dirname, join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const packageName = "opencode-resolve"
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..")
+const configDir = process.env.OPENCODE_CONFIG_HOME || join(homedir(), ".config", "opencode")
+const opencodeConfigPath = join(configDir, "opencode.json")
+const resolveConfigPath = join(configDir, "resolve.json")
+const exampleConfigPath = join(root, "opencode-resolve.example.json")
+
+const ADDITIVE_DEFAULTS = {
+  autoApprove: true,
+  maxParallelSubagents: 1,
+}
+
+if (process.env.OPENCODE_RESOLVE_SKIP_POSTINSTALL === "1") {
+  process.exit(0)
+}
+
+try {
+  await registerPlugin()
+} catch (error) {
+  console.warn(`[${packageName}] automatic OpenCode registration skipped: ${formatError(error)}`)
+  console.warn(`[${packageName}] add "${packageName}" to your OpenCode plugin list manually if needed.`)
+}
+
+async function registerPlugin() {
+  await mkdir(configDir, { recursive: true })
+
+  const config = await readOpenCodeConfig()
+  const changed = addPlugin(config)
+
+  if (changed) {
+    await writeFile(opencodeConfigPath, `${JSON.stringify(config, null, 2)}\n`)
+    console.log(`[${packageName}] registered in ${opencodeConfigPath}`)
+  } else {
+    console.log(`[${packageName}] already registered in ${opencodeConfigPath}`)
+  }
+
+  if (!(await exists(resolveConfigPath))) {
+    await assertReadable(exampleConfigPath)
+    await copyFile(exampleConfigPath, resolveConfigPath)
+    console.log(`[${packageName}] created ${resolveConfigPath}`)
+    return
+  }
+
+  await migrateResolveConfig()
+}
+
+async function migrateResolveConfig() {
+  let raw
+  try {
+    raw = await readFile(resolveConfigPath, "utf8")
+  } catch (error) {
+    console.warn(`[${packageName}] could not read ${resolveConfigPath} for migration: ${formatError(error)}`)
+    return
+  }
+
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch (error) {
+    console.warn(`[${packageName}] ${resolveConfigPath} is not valid JSON; skipping migration: ${formatError(error)}`)
+    return
+  }
+
+  if (!isObject(parsed)) {
+    console.warn(`[${packageName}] ${resolveConfigPath} must contain a JSON object; skipping migration`)
+    return
+  }
+
+  const updated = { ...parsed }
+  const added = []
+  for (const [key, value] of Object.entries(ADDITIVE_DEFAULTS)) {
+    if (updated[key] === undefined) {
+      updated[key] = value
+      added.push(`${key}=${JSON.stringify(value)}`)
+    }
+  }
+
+  if (added.length > 0) {
+    await writeFile(resolveConfigPath, `${JSON.stringify(updated, null, 2)}\n`)
+    console.log(`[${packageName}] migrated ${resolveConfigPath}: added ${added.join(", ")}`)
+  } else {
+    console.log(`[${packageName}] ${resolveConfigPath} already up to date`)
+  }
+
+  if (Array.isArray(updated.enabled) && !updated.enabled.includes("resolver")) {
+    console.log(
+      `[${packageName}] tip: add "resolver" to "enabled" in ${resolveConfigPath} to use the new orchestrator agent.`,
+    )
+  }
+}
+
+async function readOpenCodeConfig() {
+  if (!(await exists(opencodeConfigPath))) {
+    return {
+      $schema: "https://opencode.ai/config.json",
+      plugin: [],
+    }
+  }
+
+  const raw = await readFile(opencodeConfigPath, "utf8")
+  const parsed = JSON.parse(raw)
+  if (!isObject(parsed)) throw new Error(`${opencodeConfigPath} must contain a JSON object`)
+  return parsed
+}
+
+function addPlugin(config) {
+  config.plugin ??= []
+  if (!Array.isArray(config.plugin)) {
+    throw new Error(`${opencodeConfigPath}.plugin must be an array`)
+  }
+
+  if (config.plugin.some(isRegisteredPluginEntry)) return false
+  config.plugin.push(packageName)
+  return true
+}
+
+function isRegisteredPluginEntry(entry) {
+  if (typeof entry === "string") return isResolvePluginName(entry)
+  if (Array.isArray(entry) && typeof entry[0] === "string") return isResolvePluginName(entry[0])
+  return false
+}
+
+function isResolvePluginName(value) {
+  const name = value.split("/").pop() || value
+  return name === packageName || name.startsWith(`${packageName}@`)
+}
+
+async function assertReadable(path) {
+  await access(path, constants.R_OK)
+}
+
+async function exists(path) {
+  try {
+    await access(path)
+    return true
+  } catch (error) {
+    if (isMissingFileError(error)) return false
+    throw error
+  }
+}
+
+function isMissingFileError(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT"
+}
+
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function formatError(error) {
+  return error instanceof Error ? error.message : String(error)
+}