@sorenllm/opencode-forge 0.5.0 → 0.7.0

package/README.md

@@ -257,12 +257,12 @@ Subagents have it worse: the native task tool has no timeout at all.
 exit condition is bound to the actual exit event (structural immunity to
 the stdio-EOF bug):
 
-| condition | knob | on trigger |
-| --- | --- | --- |
-| process exit | — | final; exit code + output tail returned |
-| `success_pattern` regex matches new output | opt-in | completes as success; process kept alive by default (server semantics), `keep_alive: false` kills its tree |
-| `idle_ms` with no new output | default 60000 | early return `still-running` + `jobId`; process stays alive |
-| `max_wait_ms` hard cap | default 120000, max 600000 | early return `still-running`; never kills |
+| condition | knob | on trigger | completion behavior |
+| --- | --- | --- | --- |
+| process exit | — | final; exit code + output tail returned | **terminal evidence** — output delivered in full; the job self-clears from the registry (no wake, no clear needed) |
+| `success_pattern` regex matches new output | opt-in | completes as success; process kept alive by default (server semantics), `keep_alive: false` kills its tree | kept alive → later exit still wakes (the server dying is real news); killed inline → self-clears |
+| `idle_ms` with no new output | default 60000 | early return `still-running` + `jobId`; process stays alive | later exit queues a wake; entry stays listed until cleared |
+| `max_wait_ms` hard cap | default 120000, max 600000 | early return `still-running`; never kills | same as idle |
 
 `run_in_background: true` skips all waiting and returns
 `{jobId, logPath}` immediately. Every run pops one permission dialog
@@ -274,14 +274,21 @@ disagrees with that line, the line wins.
 **`forge_jobs`** manages the registry: `list` / `poll {jobId, waitMs≤30s}`
 (bounded wait for new output or exit, drains it) / `log {jobId, offset?,
 limit?}` (line paging over the on-disk log) / `kill` (whole process tree) /
-`clear` (drop a finished entry) / `handoff` (rebind ownership to the root
-session so a subagent's job survives the subagent). Delegated agents are
-instructed to poll their jobs before yielding a conclusion.
-
-**Exit wakes.** A job that exits after its `forge_shell` call already
-returned queues a single `[forge:job-complete]` message, delivered into the
-owning session via `promptAsync` the next time it goes idle (exactly once;
-`notify: false` opts out per job).
+`clear` (drop a finished entry — only early-returned/background jobs need
+this; synchronously consumed jobs self-clear at completion) / `handoff`
+(rebind ownership to the root session so a subagent's job survives the
+subagent). Delegated agents are instructed to poll their jobs before
+yielding a conclusion.
+
+**Exit wakes.** A job whose caller last saw it before completion —
+`run_in_background` starts and `still-running`/kept-alive `success` early
+returns — queues a single `[forge:job-complete]` message when it finishes,
+delivered into the owning session via `promptAsync` the next time it goes
+idle (exactly once; `notify: false` opts out per job). A foreground call
+resolved on the exit event is terminal evidence: the caller already holds
+the complete output, so no wake fires and the registry entry self-clears —
+a stale `poll`/`kill`/`clear` on such an id answers "already consumed"
+instead of "unknown job".
 
 **Ownership.** Jobs belong to the session that created them. Session
 deleted → its live session-scoped jobs are killed and the event is recorded
@@ -359,8 +366,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 +390,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 +425,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 +443,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

@@ -13416,12 +13416,30 @@ function createJobManager(opts = {}) {
     job.state = state;
     job.exitCode = exitCode;
     job.endedAt = now();
-    if (job.notify && job.wakeState === "none") {
+    if (job.notify && job.wakeState === "none" && !job.terminalEvidence) {
       job.wakeState = "queued";
       job.wakeQueuedAt = now();
     }
+    if (job.terminalEvidence) {
+      jobs.delete(job.id);
+      rememberConsumed(job.id);
+    }
     enforceCaps();
   }
+  const consumedIds = new Set;
+  function rememberConsumed(id) {
+    if (consumedIds.has(id))
+      return;
+    consumedIds.add(id);
+    if (consumedIds.size > maxFinishedJobs) {
+      const oldest = consumedIds.values().next().value;
+      if (oldest !== undefined)
+        consumedIds.delete(oldest);
+    }
+  }
+  function consumed(id) {
+    return consumedIds.has(id);
+  }
   function kill(job) {
     if (isTerminal2(job))
       return;
@@ -13533,6 +13551,7 @@ function createJobManager(opts = {}) {
     deliverWakesFor,
     abandonStaleWakes,
     ledgerEntries,
+    consumed,
     size: () => jobs.size
   };
 }
@@ -13640,6 +13659,11 @@ function startJob(manager, opts) {
     clearTimeout(maxWaitTimer);
   };
   const firstOutputHooks = [];
+  const foregroundWatch = !opts.runInBackground;
+  const stampTerminalEvidence = () => {
+    if (foregroundWatch && !settled)
+      job.terminalEvidence = true;
+  };
   function resolveStillRunning() {
     if (settled)
       return;
@@ -13675,6 +13699,7 @@ function startJob(manager, opts) {
         closeSync(wfd);
       } catch {}
     }
+    stampTerminalEvidence();
     manager.markTerminal(job, "killed", null);
     maxWaitTimer && clearTimeout(maxWaitTimer);
     resolveSettle({ status: "exited", exitCode: null, outputTail: "", spawnError: String(err) });
@@ -13726,6 +13751,8 @@ function startJob(manager, opts) {
           killTree(child);
           if (opts.survive)
             opts.registry?.remove(id);
+          if (foregroundWatch)
+            job.terminalEvidence = true;
           manager.markTerminal(job, "succeeded", null);
         }
         resolveSettle({ status: "succeeded", matched: m[0], outputTail: job.tail, keptAlive });
@@ -13747,6 +13774,7 @@ function startJob(manager, opts) {
       tail.flush();
       tail.stop();
       liveTails.delete(id);
+      stampTerminalEvidence();
       manager.markTerminal(job, "exited", code);
       if (opts.survive)
         opts.registry?.remove(id);
@@ -13765,6 +13793,7 @@ function startJob(manager, opts) {
     if (opts.survive)
       opts.registry?.remove(id);
     if (!settled) {
+      stampTerminalEvidence();
       settled = true;
       stopTimers();
       manager.markTerminal(job, "killed", null);
@@ -14893,7 +14922,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 +14934,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 +14945,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 +15282,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;
@@ -16151,6 +16198,8 @@ var forgeShellTool = tool({
         output: [
           `[forge:job] Command finished (exit=${r.exitCode ?? "none"}).`,
           `cwd: ${cwd}`,
+          `jobId: ${started.job.id}`,
+          `Output was delivered in full above — terminal evidence: the job self-cleared from the registry (no wake fires, no forge_jobs clear needed).`,
           ...r.spawnError ? [`spawn error: ${r.spawnError}`] : [],
           `output:
 ${r.outputTail || "(none)"}`
@@ -16164,7 +16213,7 @@ ${r.outputTail || "(none)"}`
         output: [
           `[forge:job] Success pattern matched: "${r.matched}".`,
           `cwd: ${cwd}`,
-          r.keptAlive ? `The process was kept alive as job ${started.job.id} (stop it with forge_jobs kill when done).` : "The process tree was terminated (keep_alive=false).",
+          r.keptAlive ? `The process was kept alive as job ${started.job.id} (stop it with forge_jobs kill when done).` : `The process tree was terminated (keep_alive=false) — terminal evidence: job ${started.job.id} self-cleared from the registry (no wake, no clear needed).`,
           `output:
 ${r.outputTail}`
         ].join(`
@@ -16187,7 +16236,7 @@ ${r.outputTail || "(none yet)"}`,
 });
 var FORGE_JOBS_ACTIONS = ["list", "poll", "log", "kill", "clear", "handoff"];
 var forgeJobsTool = tool({
-  description: "Manage forge_shell jobs. Actions: list (all jobs, newest first); poll {jobId, waitMs<=30000} — bounded wait for NEW output or exit, drains it; log {jobId, offset?, limit?} — line paging over the on-disk log (omitted offset = tail window, default 200 lines); kill {jobId} — terminate the job's whole process tree; clear {jobId} — drop a finished job from the registry; handoff {jobId} — rebind ownership to the root session so the job survives this (sub)session's end. A delegated agent MUST poll its jobs before yielding its conclusion.",
+  description: "Manage forge_shell jobs. Actions: list (all jobs, newest first); poll {jobId, waitMs<=30000} — bounded wait for NEW output or exit, drains it; log {jobId, offset?, limit?} — line paging over the on-disk log (omitted offset = tail window, default 200 lines); kill {jobId} — terminate the job's whole process tree; clear {jobId} — drop a finished job from the registry (only early-returned/background jobs need this — synchronously consumed jobs self-clear at completion); handoff {jobId} — rebind ownership to the root session so the job survives this (sub)session's end. A delegated agent MUST poll its jobs before yielding its conclusion.",
   args: {
     action: tool.schema.string().describe(`One of: ${FORGE_JOBS_ACTIONS.join(", ")}`),
     jobId: tool.schema.string().optional().describe("Job id from forge_shell (required for every action except list)"),
@@ -16212,8 +16261,9 @@ var forgeJobsTool = tool({
     if (!args.jobId)
       throw new Error(`Action "${action}" requires jobId.`);
     const job = jobManager.get(args.jobId);
-    if (!job)
-      throw new Error(`No job ${args.jobId} in the registry (finished jobs age out; the on-disk log may still exist).`);
+    if (!job) {
+      throw new Error(jobManager.consumed(args.jobId) ? `Job ${args.jobId} was already consumed: a terminal-evidence foreground return delivered its complete output inline, so it self-cleared from the registry — no wake fires and no clear is needed.` : `No job ${args.jobId} in the registry (finished jobs age out; the on-disk log may still exist).`);
+    }
     if (action === "poll") {
       const p = await pollJob(jobManager, args.jobId, args.waitMs ?? 0);
       if (!p)
@@ -16272,7 +16322,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 +17162,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.7.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": {