@sorenllm/opencode-forge 0.6.0 → 0.8.0

package/README.md

@@ -65,7 +65,11 @@ tool layer (verified against the host's `tools` filter):
 
 Escape hatches: `jobs.keepBuiltinShell: true` gives the forge family the
 builtin shell back; `jobs.mode: "native"` retires `forge_shell`/`forge_jobs`
-entirely (the hide is withdrawn in the same stroke). Mixed sessions (Tab
+entirely (the hide is withdrawn in the same stroke). The forge family is
+prompted to route every shell command through `forge_shell` — on hosts that
+ignore injected tools maps the builtin tool stays visible but is refused at
+call time, and the channel mandate is what keeps the model from trying it
+first (the belt refusal remains the backstop). Mixed sessions (Tab
 between agents in one session): harness state (plans/goals) stays
 session-bound, tool surfaces follow the current speaker, and the goal loop
 parks instead of driving a non-forge turn. One deliberate exception: a
@@ -257,12 +261,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 +278,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

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);
@@ -15407,6 +15436,12 @@ var FORGE_PROMPT = `You are forge — the single general-purpose coding agent. Y
 Workflow modes are strictly user-initiated. Never enter plan or goal mode — and never call a plan_* or goal_* tool — unless the user ran /plan or /goal, unmistakably asked for that mode (e.g. "plan first", "set a goal"), or the session already carries a [forge:plan-notice] / [forge:goal-notice] for a mode they started. Ordinary task requests are normal work. Mode-specific rules arrive with those commands and notices; when a notice is present, follow it.
 
 Subagent dispatch (task tool): when the work suits a scoped worker, prefer a configured \`forge-*\` subagent whose description matches the job. If none matches, say so plainly to the user and dispatch through the native task channel instead.`;
+function forgePromptText(opts) {
+  const mandate = opts.hardRefusal ? "Exec surface: every shell command — quick ones included — runs through the forge_shell tool. The builtin shell/bash tools are refused on this agent; never try them first, not even for trivial commands." : "Exec surface: prefer the forge_shell tool for every shell command — quick ones included; it is this agent's exec surface, and the builtin shell exists only as an explicit escape hatch.";
+  return `${FORGE_PROMPT}
+
+${mandate} Long-running or non-exiting commands: forge_shell with run_in_background, then collect results via forge_jobs.`;
+}
 var PLAN_COMMAND_TEMPLATE = [
   '(forge plan harness routing. Argument: "$ARGUMENTS")',
   "",
@@ -16095,7 +16130,7 @@ var FORGE_SHELL_DESCRIPTION = [
   "Run a shell command without ever blocking the session indefinitely. The call completes on the FIRST of: process exit (bound to the exit event — a detached grandchild holding the stdio pipes cannot suspend the call); success_pattern matching new output (opt-in regex); idle_ms with no new output (default 60000); max_wait_ms hard cap (default 120000, max 600000 — returns still-running, never kills).",
   "Idle/max-wait return `still-running` with a jobId — the process stays alive; keep watching with forge_jobs poll / log, stop it with forge_jobs kill. run_in_background returns {jobId, logPath} immediately.",
   "success_pattern semantics: a match completes the call as success; the process is kept alive by default (server semantics — the thing you just verified keeps running); pass keep_alive=false to kill its tree on match. Common patterns: dev servers `listening on|ready in|Local:`, builds `Compiled successfully|Done in`, test suites `passed|all tests`.",
-  "Long-running or possibly non-exiting commands (dev servers, watchers, installers, anything spawning detached children) MUST use this tool instead of the builtin shell."
+  "This tool is the forge agent's exec surface for every shell command — quick ones included. Long-running or possibly non-exiting commands (dev servers, watchers, installers, anything spawning detached children) should start with run_in_background and collect results via forge_jobs."
 ].join(`
 `);
 var forgeShellTool = tool({
@@ -16169,6 +16204,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)"}`
@@ -16182,7 +16219,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(`
@@ -16205,7 +16242,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)"),
@@ -16230,8 +16267,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)
@@ -16744,7 +16782,7 @@ var server = async (input, options) => {
         ...existing ?? {},
         description: existing?.description ?? "forge — the single general-purpose coding agent: takes implementation tasks directly; planning goes through /plan into the plan harness (plans land in .opencode/plan/, with approve/close confirmation gates and tick discipline enforced by tools and the permission layer).",
         mode: existing?.mode ?? "primary",
-        prompt: existing?.prompt ?? FORGE_PROMPT
+        prompt: existing?.prompt ?? (jobStage() < 2 ? forgePromptText({ hardRefusal: !jobsKeepBuiltinShell }) : FORGE_PROMPT)
       };
       if (!jobsKeepBuiltinShell && jobStage() < 2) {
         const entry = agentSection[FORGE_AGENT];
@@ -17051,7 +17089,7 @@ var server = async (input, options) => {
         output.system.push(`[forge:crew-active] A crew is ACTIVE in this session: "${crewActive.objective}" (started ${crewActive.startedAt}). A second /crew must be refused; finish with crew_close when every subtask has a verdict.`);
       }
       if (!forgeDisabled && jobStage() < 2 && !output.system.some((s) => s.startsWith("[forge:job-guidance]"))) {
-        output.system.push("[forge:job-guidance] Long-running or possibly non-exiting shell commands (dev servers, watchers, installers, anything spawning detached children) go through forge_shell, never the builtin shell: it returns on idle/success/exit with a jobId instead of blocking indefinitely; manage jobs with forge_jobs. Delegated agents: collect your job results with forge_jobs poll before yielding your conclusion.");
+        output.system.push(jobsKeepBuiltinShell ? "[forge:job-guidance] Long-running or possibly non-exiting shell commands (dev servers, watchers, installers, anything spawning detached children) go through forge_shell, never the builtin shell: it returns on idle/success/exit with a jobId instead of blocking indefinitely; manage jobs with forge_jobs. Delegated agents: collect your job results with forge_jobs poll before yielding your conclusion." : "[forge:job-guidance] Every shell command — quick ones included — goes through forge_shell: the builtin shell/bash tools are refused on this agent, so never try them first. forge_shell returns on exit/success/idle with a jobId instead of blocking indefinitely; long-running or non-exiting commands use run_in_background. Manage jobs with forge_jobs. Delegated agents: collect your job results with forge_jobs poll before yielding your conclusion.");
       }
       const state = sessions.get(input2.sessionID);
       if (!state)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sorenllm/opencode-forge",
-  "version": "0.6.0",
+  "version": "0.8.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",