@sorenllm/opencode-forge 0.5.0 → 0.6.0

package/README.md

@@ -359,8 +359,10 @@ complete.
 ## Forge subagents (static worker agents in forge.json)
 
 Forge subagents are **static, user-authored worker agents**: each forge.json
-entry pins a model and an optional reasoning depth, materializes as a native
-`forge-<id>` subagent, and is dispatched through the host's **native `task`
+entry is either **pinned** (a model + a reasoning depth, bound at
+materialization) or an **Auto worker** (no model — it inherits the parent
+session's model at dispatch), materializes as a native `forge-<id>`
+subagent, and is dispatched through the host's **native `task`
 tool** — which means every run is visible in the TUI, expandable and
 monitorable, exactly like any native subagent. There is no dispatch tool, no
 child-session engine, and no configuration invitation anywhere: the session
@@ -381,17 +383,33 @@ cascade with a single winning source (never merged):
 {
   // forge subagents — definitions; see the restart table below for apply timing
   "agents": {
+    // PINNED worker: model + thoughtLevel form an ATOMIC PAIR — set BOTH
     "research": {
-      "model": "zai-coding-plan/glm-5.3", // exact "provider/model" string — REQUIRED
-      "thoughtLevel": "low",              // optional: none/low/medium/high/max or a native level name
+      "model": "zai-coding-plan/glm-5.3", // exact "provider/model" string
+      "thoughtLevel": "low",              // none/low/medium/high/max or a native level name
       // "prompt": "optional role prompt; built-in research/review defaults exist",
       // "shape": "write",   // default readonly denies write/edit/bash
       // "permission": { "bash": "deny" } // optional override; "task" is ALWAYS denied
-    }
+    },
+    // AUTO worker: set NEITHER — inherits the parent session's model at
+    // dispatch (snapshot semantics: later primary model switches affect only
+    // future dispatches), runs at the provider's default depth
+    "scout": {}
   }
 }
 ```
 
+**The atomic pair — the one rule that matters:**
+
+| `model` | `thoughtLevel` | result |
+| --- | --- | --- |
+| set | set | pinned worker (brain + depth bound at materialization) |
+| — | — | **Auto worker** (inherits the parent session's model; provider-default depth) |
+| set | — | ✗ rejected: entry skipped, error finding names the missing `thoughtLevel` |
+| — | set | ✗ rejected: entry skipped, error finding names the missing `model` |
+
+A rejected entry costs only itself — its siblings materialize normally.
+
 - **The plugin only ever reads this file.** It never creates, writes, or
   migrates it. The old AI-authored onboarding path (seed placeholder +
   error recipe) is gone: an unconfigured host is inert and silent, and the
@@ -400,13 +418,17 @@ cascade with a single winning source (never merged):
   offered to YOU and happens only on your explicit go-ahead.
 - **Parsing is field-level fail-soft** (ZCode-style): a semantically bad
   agent entry is skipped with an error finding while its siblings apply; a
-  mistyped optional field is ignored with a warning; a syntactically broken
-  file empties the agent set with one parse-location error. There is no seed
-  in any failure path. Findings surface in the plugin diagnostics log.
+  mistyped optional field is ignored with a warning (and counts as absent
+  for the atomic pair — so a pinned `model` with a typo'd `thoughtLevel`
+  skips the whole entry); a syntactically broken file empties the agent set
+  with one parse-location error. There is no seed in any failure path.
+  Findings surface in the plugin diagnostics log.
 - **`depths` is deprecated**: the array is ignored with a warning finding.
   Pin ONE `thoughtLevel` per agent instead.
 - Each agent materializes as `forge-<id>` — a subagent-mode agent visible in
-  the task tool's vocabulary (never hidden), carrying the pinned `model`,
+  the task tool's vocabulary (never hidden), carrying the pinned `model`
+  (pinned workers) or NO model key at all (Auto workers — the description
+  says "inherits the parent session's model" instead of naming a brain),
   the worker discipline (workspace-relative paths only, verbatim reporting
   of tool refusals, evidence-bearing conclusions) around its role prompt,
   and a deny-style permission: `shape: "readonly"` (the default) denies
@@ -414,6 +436,11 @@ cascade with a single winning source (never merged):
   `permission` map overrides the shape default — and `task` is ALWAYS
   denied (recursive spawning stays physically impossible).
 
+> **Upgrading from ≤ 0.5.0 (breaking):** agent entries that pinned `model`
+> without `thoughtLevel` used to be accepted; they are now SKIPPED with an
+> error finding naming the missing half. Fix per entry: add the missing
+> `thoughtLevel`, or delete `model` to make it an Auto worker.
+
 **What applies when** — edits take hold per field:
 
 | change | needs a host restart? |

package/dist/index.js

@@ -14893,7 +14893,8 @@ function rolePromptFor(agentId, def) {
 }
 function agentDescriptionFor(agentId, def) {
   const shape = def.shape === "write" ? "write" : "readonly";
-  return `forge subagent "${agentId}" (${shape}, pinned ${def.model}) — dispatch via the task tool with subagent_type "forge-${agentId}".`;
+  const brain = def.model !== undefined ? `pinned ${def.model}` : "auto — inherits the parent session's model at dispatch";
+  return `forge subagent "${agentId}" (${shape}, ${brain}) — dispatch via the task tool with subagent_type "forge-${agentId}".`;
 }
 function forgeAgentDef(agentId, def) {
   const permission = { task: "deny" };
@@ -14904,10 +14905,9 @@ function forgeAgentDef(agentId, def) {
   }
   Object.assign(permission, def.permission ?? {});
   permission.task = "deny";
-  return {
+  const entry = {
     description: agentDescriptionFor(agentId, def),
     mode: "subagent",
-    model: def.model,
     prompt: materializeAgentPrompt({
       agent: agentId,
       shape,
@@ -14916,6 +14916,9 @@ function forgeAgentDef(agentId, def) {
     permission,
     tools: { shell: false, bash: false }
   };
+  if (def.model !== undefined)
+    entry.model = def.model;
+  return entry;
 }
 
 // src/dispatch-depth.ts
@@ -15250,21 +15253,36 @@ function validateAgentSet(raw) {
       findings.push({ level: "error", code: "agent-not-object", message: `${label}: definition must be an object — entry skipped` });
       continue;
     }
-    if (!nonEmptyString(entry.model)) {
-      findings.push({ level: "error", code: "agent-model-missing", message: `${label}.model: a non-empty "provider/model" string is required — entry skipped, siblings still apply` });
-      continue;
-    }
-    const def = { model: entry.model.trim() };
     if (entry.depths !== undefined) {
       findings.push({ level: "warn", code: "depths-deprecated", message: `${label}.depths is no longer used (static agents pin one thoughtLevel) — ignored; set "thoughtLevel" instead` });
     }
+    let model;
+    if (entry.model !== undefined) {
+      if (nonEmptyString(entry.model)) {
+        model = entry.model.trim();
+      } else {
+        findings.push({ level: "warn", code: "model-invalid", message: `${label}.model must be a non-empty string — field ignored (counts as absent for the model/thoughtLevel pair)` });
+      }
+    }
+    let thoughtLevel;
     if (entry.thoughtLevel !== undefined) {
       if (nonEmptyString(entry.thoughtLevel)) {
-        def.thoughtLevel = entry.thoughtLevel.trim();
+        thoughtLevel = entry.thoughtLevel.trim();
       } else {
-        findings.push({ level: "warn", code: "thoughtlevel-invalid", message: `${label}.thoughtLevel must be a non-empty string — field ignored, the agent still materializes` });
+        findings.push({ level: "warn", code: "thoughtlevel-invalid", message: `${label}.thoughtLevel must be a non-empty string — field ignored (counts as absent for the model/thoughtLevel pair)` });
       }
     }
+    if (model === undefined !== (thoughtLevel === undefined)) {
+      const presentHalf = model !== undefined ? "model" : "thoughtLevel";
+      const missingHalf = model !== undefined ? "thoughtLevel" : "model";
+      findings.push({ level: "error", code: "agent-half-configured", message: `${label}: model and thoughtLevel form an atomic pair — ${presentHalf} is set but ${missingHalf} is missing; set BOTH to pin the brain and depth, or NEITHER for an Auto worker — entry skipped, siblings still apply` });
+      continue;
+    }
+    const def = {};
+    if (model !== undefined) {
+      def.model = model;
+      def.thoughtLevel = thoughtLevel;
+    }
     if (entry.prompt !== undefined) {
       if (nonEmptyString(entry.prompt)) {
         def.prompt = entry.prompt;
@@ -16272,7 +16290,7 @@ var CREW_INIT_TEMPLATE = [
   "",
   "2. Or, ONLY if the user explicitly asks you to configure it in this conversation, you may write the file yourself through the normal write path. NEVER write forge.json without that explicit go-ahead.",
   "",
-  "Template (JSONC — comments allowed; `model` is the exact provider/model identity, `thoughtLevel` is optional: none/low/medium/high/max or a native level name):",
+  "Template (JSONC — comments allowed): `model` + `thoughtLevel` are an ATOMIC PAIR — set BOTH to pin the brain and depth (model = exact provider/model identity; thoughtLevel = none/low/medium/high/max or a native level name), or NEITHER for an Auto worker that inherits the parent session's model; exactly one of the two is rejected.",
   "{template}",
   "",
   "After the file is saved: NEW agents require a host restart to appear in the task tool; thoughtLevel edits on existing agents apply without restart. Until then, crew stays unavailable."
@@ -17112,7 +17130,8 @@ async function v2Setup(ctx) {
             agent.description = v1def.description;
             agent.system = v1def.prompt;
             agent.mode = v1def.mode;
-            agent.model = v1def.model;
+            if (v1def.model !== undefined)
+              agent.model = v1def.model;
             agent.permission = v1def.permission;
           });
         }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sorenllm/opencode-forge",
-  "version": "0.5.0",
-  "description": "Single general-purpose forge agent for opencode: static worker subagents defined in forge.json (pinned model + optional reasoning depth, dispatched through the native task tool — TUI-visible), a plan harness (file-backed plans with approve/close confirmation gates and a hard draft write-ban), a goal harness (autonomous, host-verified objectives), a /crew orchestration command (declared-plan waves with an evidence-checked close gate), a job supervisor (forge_shell with exit-bound completion, idle/success early return, background jobs with poll/log/kill/handoff), and a builtin-shell hang watchdog.",
+  "version": "0.6.0",
+  "description": "Single general-purpose forge agent for opencode: static worker subagents defined in forge.json (pinned model + thoughtLevel pair, or an Auto worker inheriting the parent model; dispatched through the native task tool — TUI-visible), a plan harness (file-backed plans with approve/close confirmation gates and a hard draft write-ban), a goal harness (autonomous, host-verified objectives), a /crew orchestration command (declared-plan waves with an evidence-checked close gate), a job supervisor (forge_shell with exit-bound completion, idle/success early return, background jobs with poll/log/kill/handoff), and a builtin-shell hang watchdog.",
   "type": "module",
   "main": "./dist/index.js",
   "exports": {