@sorenllm/opencode-forge 0.7.0 → 0.9.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
@@ -261,7 +265,7 @@ the stdio-EOF bug):
 | --- | --- | --- | --- |
 | 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 |
+| `idle_ms` with no new output | default 60000 | early return `still-running` + `jobId`; process stays alive | later exit queues a wake — unless a poll has already read the terminal state (a terminal poll consumes the entry); stays listed until then |
 | `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
@@ -288,7 +292,11 @@ 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".
+instead of "unknown job". The same consumption applies to a poll that
+observes a finished job: the poll itself delivered the exit status and the
+drained output, so the queued wake is dropped and the entry self-clears —
+no duplicate notification, no manual clear. Wakes fire only for
+completions that were never read.
 
 **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

@@ -13449,8 +13449,11 @@ function createJobManager(opts = {}) {
     markTerminal(job, "killed", null);
   }
   function poll(job) {
-    if (isTerminal2(job))
+    if (isTerminal2(job)) {
       job.readAfterEnd = true;
+      jobs.delete(job.id);
+      rememberConsumed(job.id);
+    }
     const cursor = job.outLen;
     const start = job.pollCursor;
     const newOutput = sliceFromCursor(job, start);
@@ -15436,6 +15439,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")',
   "",
@@ -16124,7 +16133,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({
@@ -16236,7 +16245,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 (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.",
+  description: "Manage forge_shell jobs. Actions: list (all jobs, newest first); poll {jobId, waitMs<=30000} — bounded wait for NEW output or exit, drains it (polling a finished job consumes it: the entry self-clears and no wake fires); 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 un-polled early-returned/background jobs need this — synchronously consumed jobs self-clear at completion, and a terminal poll consumes the entry); 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)"),
@@ -16776,7 +16785,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];
@@ -17083,7 +17092,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.7.0",
+  "version": "0.9.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",