@sorenllm/opencode-forge 0.4.0 → 0.6.0

package/README.md

@@ -33,8 +33,10 @@ OpenSpec spec workflows remain a third, separate lane.
 - Plan files: `.opencode/plan/<date>-<slug>.md` in your project, frontmatter
   state machine `draft → approved → done` (exit: `abandoned`).
 - While a plan is in draft, `write` / `edit` / `bash` / `task` are **denied
-  at the permission layer** — including your own `allow` config. The only
-  exits are approval and discard. This is deliberate; see Design stance.
+  at the permission layer** — including your own `allow` config, and for
+  every agent in that session (the draft protects shared session state; see
+  Agent partition below). The only exits are approval and discard. This is
+  deliberate; see Design stance.
 - `plan_approve` / `plan_close` are pinned to a confirmation dialog: the
   model can never flip the state itself.
 - Goal files: `.opencode/goal/<date>-<slug>.md`, state machine
@@ -42,9 +44,40 @@ OpenSpec spec workflows remain a third, separate lane.
   session plus a workspace queue. Completion is **verified by the plugin**,
   not attested by the model: `goal_complete` re-executes every check itself
   and refuses (fail-closed) on any failure.
-- The native `build` / `plan` agents are hidden while the plugin is loaded
-  (runtime injection, nothing written to your config). Uninstall restores
-  them automatically; plan and goal files are never deleted.
+- The native `build` / `plan` agents **stay installed and independent**:
+  forge coexists with them in the Tab cycle. The plugin hard-partitions the
+  two worlds (see Agent partition below) instead of hiding anything; plan
+  and goal files are never deleted on uninstall.
+
+## Agent partition (who sees what)
+
+The plugin draws a hard line between two agent families, enforced at the
+tool layer (verified against the host's `tools` filter):
+
+| | **forge family** — `forge` + your forge.json `forge-*` workers | **everyone else** — native `build` / `plan` / `general` / `explore` and your own agents |
+| --- | --- | --- |
+| exec surface | `forge_shell` / `forge_jobs` only; builtin `shell`/`bash` hidden (unconditional, probe-independent; covers user-defined `agent.forge` entries too) | builtin `shell`/`bash`, fully native |
+| forge tools (`plan_*`, `goal_*`, `crew_*`, `forge_shell`, `forge_jobs`) | `forge` sees all; `forge-*` workers only `forge_shell` + `forge_jobs` | none visible |
+| dispatching `forge-*` via `task` | allowed | refused at the tool layer |
+| writing `.opencode/plan/` / `.opencode/goal/` | allowed (state machine governs) | refused at the tool layer (reads stay open) |
+| forge system prompts (job guidance, plan/goal notices) | injected | never injected — zero forge text |
+| watchdog (stuck builtin shell) | governed | untouched — no markers, no kills |
+
+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
+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
+draft-phase write ban binds the **session** (protecting shared state), so a
+non-forge agent is write-blocked until the draft is approved or discarded in
+forge. Running `/plan` `/goal` `/crew` under a non-forge agent redirects to
+forge instead of executing.
+
+**Default subject.** The host otherwise defaults new sessions to `build`
+once a build agent exists — the plugin pins `default_agent: "forge"`
+automatically (a `default_agent` you set yourself always wins), so bare
+runs and fresh sessions still land on forge under coexistence.
 
 ## Install
 
@@ -78,18 +111,19 @@ the plugin never writes them):
     "forge": {
       "model": "provider/model",   // pick any model for forge
       "disable": true              // one-knob return to native: no forge,
-                                   // build/plan restored, no tools/commands
+                                   // no injections at all, no tools/commands
     }
   },
   // per-plugin options ride the plugin entry as a [spec, options] tuple
   "plugin": [
     ["@sorenllm/opencode-forge", {
       "jobs": {
-        "mode": "auto",              // "auto" (default) | "forge" | "native" — see the stage matrix below
-        "keepBuiltinShell": false    // stage 0: keep the builtin shell visible alongside forge_shell
+        "mode": "auto",              // "auto" (default) | "forge" — equivalent, both keep the partition
+                                     // | "native" — retire the supervisor, builtin shell returns
+        "keepBuiltinShell": false    // true: give the forge family the builtin shell back (the one exec escape hatch)
       },
       "watchdog": {
-        "mode": "kill",              // "kill" (default) | "dry-run" | "off"
+        "mode": "kill",              // "kill" (default) | "dry-run" | "off" — forge-family sessions only
         "stallMs": 600000            // stall threshold, min 60000
       }
     }]
@@ -110,7 +144,8 @@ and the plugin's command of that name is not registered.
    `~/.cache/opencode/packages/github_ChengZiiii/opencode-forge/`).
 3. Delete the `agent["forge"]` block from your config if you added one
    (otherwise the name lingers in the agent list).
-4. Done — the hidden native `build`/`plan` agents come back automatically
+4. Done — all runtime injections (agents, tool hiding, commands) are gone
+   with the plugin; nothing was ever written to your config
    (the hide was runtime-only). Your `.opencode/plan/` and `.opencode/goal/`
    files are yours; delete them yourself if you want.
  5. Optional runtime debris: delete `<tmp>/opencode-forge/` (job logs, the
@@ -126,7 +161,7 @@ What this plugin touches, exhaustively:
 | --- | --- | --- |
 | `<project>/.opencode/plan/*.md` | plan files | user data — kept forever, uninstall never deletes |
 | `<project>/.opencode/goal/*.md` | goal files (contract, Check Log, Turn Ledger) | user data — kept forever, uninstall never deletes |
-| merged config object (RAM only) | forge agent, static `forge-<id>` subagents, native build/plan `disable`, `command.plan`, `command.goal`, `command.crew`, goal permission keys, `permission.forge_shell`, `permission.crew_close`, stage-0 builtin shell hide | vanishes when the plugin is removed; nothing is written to disk |
+| merged config object (RAM only) | forge agent, static `forge-<id>` subagents, tool-partition injections (forge family shell hide, non-forge forge-tool hide, native build/plan/general/explore minimal entries), `command.plan`, `command.goal`, `command.crew`, goal permission keys, `permission.forge_shell`, `permission.crew_close` | vanishes when the plugin is removed; nothing is written to disk |
 | `<tmp>/opencode-forge/jobs/<jobId>.log` | job output tee (full output; oldest rotated out above 50 files) | runtime debris — delete freely, also after uninstall |
 | `<tmp>/opencode-forge/jobs/ledger.jsonl` | job registry ledger (bounded: 1 MB reset, 200 entries) | runtime debris — delete freely, also after uninstall |
 | `<tmp>/opencode-forge/jobs/registry.json` | persistent survivor registry (bounded: 100 entries) | runtime debris — after uninstall, kill any still-running `survive` jobs yourself first |
@@ -293,19 +328,20 @@ as usual. Config `jobs.survive: "always"` flips the per-call default; config
 whose pid died are detected at next start, ledgered as orphans, and dropped
 from the registry. Stop survivors explicitly — nothing else will.
 
-### Stage matrix (future compatibility, by design)
+### Mode matrix (supervisor lifecycle)
 
-OpenCode upstream is converging on native backgrounding (PRs #47231 /
-#50276, umbrella #34366). The supervisor degrades ahead of it:
+The old three-stage capability probe is retired: the forge-side partition
+holds regardless of what the host's builtin shell can do, so `auto` and
+`forge` are equivalent. Only the manual `native` mode retires the
+supervisor:
 
-| stage | how you get there | builtin shell | forge_shell / forge_jobs |
+| mode | how you get there | builtin shell (forge family) | forge_shell / forge_jobs |
 | --- | --- | --- | --- |
-| 0 — full forge path | default (`jobs.mode: "auto"`, no native support detected) | hidden on the plugin-created forge agent (runtime injection only) | registered; the exec surface |
-| 1 — native backgrounding detected | automatic: `config.experimental` background flag, or the builtin shell's schema grows `run_in_background` | visible again | still registered as the additive layer (idle/success/wake supervision); its description now points plain backgrounding at the native parameter |
-| 2 — native confirmed complete | manual only: `jobs.mode: "native"` (never auto-detected — completeness is a semantic judgement) | visible | retired; calls throw with a pointer to the native parameter |
+| auto (default) / forge | nothing to do | hidden — the exec surface is forge_shell, always | registered |
+| native | manual only: `jobs.mode: "native"` | restored | retired; calls throw with a pointer to the native parameter |
 
-Pin `jobs.mode: "forge"` to stay on stage 0 forever; `jobs.keepBuiltinShell:
-true` keeps the builtin shell visible at any stage.
+`jobs.keepBuiltinShell: true` gives the forge family the builtin shell back
+in any mode (the watchdog keeps governing those calls).
 
 ### Artifacts and uninstall additions
 
@@ -323,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
@@ -345,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
@@ -364,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
@@ -378,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? |
@@ -453,10 +516,11 @@ delete the directory freely, also after uninstalling.
 ## Hang watchdog (a stuck builtin shell unblocks itself)
 
 `forge_shell` is structurally immune to the stdio-EOF hang, but the builtin
-`shell`/`bash` tool can still hang outside it — user-defined agents keep
-the builtin shell, and the stage matrix above restores it at stage 1/2.
-The watchdog is the independent backstop for those paths, in **every**
-session (primary and delegated subagents alike):
+`shell`/`bash` tool can still hang outside it — under `jobs.mode: "native"`
+or `jobs.keepBuiltinShell: true`, forge-family sessions carry it again. The
+watchdog is the independent backstop for those paths, in **forge-family
+sessions only** (primary and delegated forge-* workers alike) — non-forge
+agents' builtin shells are entirely native: no markers, no timing, no kills:
 
 1. The host's shell environment hook stamps each builtin shell call's
    process with a plugin-namespaced marker (`FORGE_WATCHDOG_MARK`), and the
@@ -519,11 +583,12 @@ read/grep/glob; if you genuinely need a shell command to decide the plan,
 approve the plan first (revising after approval is allowed via a new `/plan`).
 The escape hatches are `plan_approve` and `/plan discard`, by design.
 
-Separately, at stage 0 the builtin shell is hidden on the plugin-created
-forge agent on purpose — `forge_shell` is the exec surface there (see the
-job supervisor chapter above). A **user-defined** `agent.forge` entry,
-`jobs.keepBuiltinShell: true`, or any stage ≥ 1 keeps the builtin shell
-visible.
+Separately, the builtin shell is hidden on the forge agent on purpose —
+`forge_shell` is the exec surface there (see Agent partition and the job
+supervisor chapter above). The hide is unconditional: it covers a
+**user-defined** `agent.forge` entry too. The escape hatches are
+`jobs.keepBuiltinShell: true` (builtin shell back on the forge family) and
+`jobs.mode: "native"` (supervisor retired entirely).
 
 A process restart forgets the session binding: the write-ban soft-disables
 (safety over strictness) and the next session's system notice + `/plan

package/dist/index.js

@@ -14867,6 +14867,7 @@ function validateCrewReport(report, declared) {
 var WORKER_MANDATES = [
   "Mandates (non-negotiable):",
   "- Use workspace-relative paths ONLY. Never write to or read from absolute paths outside this workspace; the workspace root is where you were started, not the filesystem root.",
+  "- Run every shell command through the forge_shell tool (the builtin shell is not part of your toolset by design). Long-running or non-exiting commands: forge_shell with run_in_background, then collect results via forge_jobs poll before yielding.",
   "- If any tool call is refused or denied, report the refusal VERBATIM in your final answer and stop that line of work. Never improvise a workaround around a permission denial.",
   "- End with conclusions backed by evidence references (file:line, command output, or the exact file/content you produced)."
 ].join(`
@@ -14892,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" };
@@ -14903,17 +14905,20 @@ 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,
       role: rolePromptFor(agentId, def)
     }),
-    permission
+    permission,
+    tools: { shell: false, bash: false }
   };
+  if (def.model !== undefined)
+    entry.model = def.model;
+  return entry;
 }
 
 // src/dispatch-depth.ts
@@ -15248,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;
@@ -15363,6 +15383,25 @@ function createForgeConfigLoader(deps) {
 
 // plugin.ts
 var FORGE_AGENT = "forge";
+var FORGE_STATE_TOOLS = [
+  "plan_write",
+  "plan_tick",
+  "plan_approve",
+  "plan_close",
+  "plan_discard",
+  "goal_write",
+  "goal_check",
+  "goal_complete",
+  "goal_pause",
+  "goal_resume",
+  "goal_discard",
+  "crew_begin",
+  "crew_close"
+];
+var FORGE_EXEC_TOOLS = ["forge_shell", "forge_jobs"];
+var FORGE_ALL_TOOLS = [...FORGE_STATE_TOOLS, ...FORGE_EXEC_TOOLS];
+var FORGE_TOOL_SET = new Set(FORGE_ALL_TOOLS);
+var NATIVE_PARTITION_FALLBACKS = ["build", "plan", "general", "explore"];
 var FORGE_PROMPT = `You are forge — the single general-purpose coding agent. You handle every task directly: exploration, planning, implementation, and verification. There is no agent switching.
 
 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.
@@ -15371,6 +15410,8 @@ Subagent dispatch (task tool): when the work suits a scoped worker, prefer a con
 var PLAN_COMMAND_TEMPLATE = [
   '(forge plan harness routing. Argument: "$ARGUMENTS")',
   "",
+  "FAMILY GUARD (step 0, before anything else): if you do not have the plan_write tool in your available tools, you are not in a forge session — STOP now: execute nothing below (including the directory listing), and tell the user that /plan belongs to the forge agent, who should switch to forge (Tab) and rerun it there.",
+  "",
   "Current .opencode/plan/ directory:",
   "!`ls -1 .opencode/plan 2>/dev/null || echo '(empty)'`",
   "",
@@ -15397,6 +15438,8 @@ var PLAN_COMMAND_TEMPLATE = [
 var GOAL_COMMAND_TEMPLATE = [
   '(forge goal harness routing. Argument: "$ARGUMENTS")',
   "",
+  "FAMILY GUARD (step 0, before anything else): if you do not have the goal_write tool in your available tools, you are not in a forge session — STOP now: execute nothing below (including the directory listing), and tell the user that /goal belongs to the forge agent, who should switch to forge (Tab) and rerun it there.",
+  "",
   "Current .opencode/goal/ directory:",
   "!`ls -1 .opencode/goal 2>/dev/null || echo '(empty)'`",
   "",
@@ -15425,6 +15468,23 @@ function effectiveWorktree(worktree, fallback) {
   return (fallback ?? "").trim();
 }
 var sessions = new Map;
+var sessionAgents = new Map;
+function isForgeFamilyAgent(name) {
+  if (typeof name !== "string")
+    return false;
+  const n = name.toLowerCase();
+  return n === FORGE_AGENT || n.startsWith("forge-");
+}
+function sessionIsForgeFamily(sessionID) {
+  if (!sessionID)
+    return false;
+  return isForgeFamilyAgent(sessionAgents.get(sessionID));
+}
+function noteToolAgent(context) {
+  if (context && typeof context.sessionID === "string" && context.sessionID && typeof context.agent === "string" && context.agent) {
+    sessionAgents.set(context.sessionID, context.agent);
+  }
+}
 var forgeDisabled = false;
 var forgeLoader = null;
 var forgeLoaderDir = null;
@@ -15489,13 +15549,10 @@ function ensureJobLifecycle() {
   });
   return { registry: registry2, fence: jobFence };
 }
-var nativeBackgroundSeen = false;
 function jobStage() {
   if (jobsMode === "native")
     return 2;
-  if (jobsMode === "forge")
-    return 0;
-  return nativeBackgroundSeen ? 1 : 0;
+  return 0;
 }
 var jobLogDir = jobsLogDir();
 var jobLedgerPath = join5(jobLogDir, "ledger.jsonl");
@@ -15577,6 +15634,7 @@ function ensureSession(sessionID, worktree) {
   return state;
 }
 function worktreeFor(context) {
+  noteToolAgent(context);
   return effectiveWorktree(context.worktree, hostWorktree) || context.worktree;
 }
 function resolveActivePlan(state) {
@@ -16040,7 +16098,6 @@ var FORGE_SHELL_DESCRIPTION = [
   "Long-running or possibly non-exiting commands (dev servers, watchers, installers, anything spawning detached children) MUST use this tool instead of the builtin shell."
 ].join(`
 `);
-var STAGE1_NOTE = "Stage note: this host's builtin shell already offers a native run_in_background parameter — prefer that for plain backgrounding; keep using forge_shell when you need idle/success_pattern early return or exit wake messages.";
 var forgeShellTool = tool({
   description: FORGE_SHELL_DESCRIPTION,
   args: {
@@ -16159,6 +16216,7 @@ var forgeJobsTool = tool({
   execute: async (args, context) => {
     if (jobStage() >= 2)
       throw new Error("[forge] The job supervisor is retired on this host.");
+    noteToolAgent(context);
     const action = String(args.action ?? "");
     if (!FORGE_JOBS_ACTIONS.includes(action)) {
       throw new Error(`Unknown action "${action}" — use one of: ${FORGE_JOBS_ACTIONS.join(", ")}.`);
@@ -16223,6 +16281,8 @@ ${p.newOutput || "(none in this window)"}`,
 var CREW_INIT_TEMPLATE = [
   '(forge crew orchestration. Argument: "$ARGUMENTS")',
   "",
+  "FAMILY GUARD (step 0, before anything else): if you do not have the crew_begin tool in your available tools, you are not in a forge session — STOP now and tell the user that /crew belongs to the forge agent, who should switch to forge (Tab) and rerun it there.",
+  "",
   "CREW IS NOT INITIALIZED: no forge subagents are configured (no usable forge.json agents). Refuse to enter orchestration and tell the user this feature needs a one-time setup, offering BOTH options:",
   "",
   "1. The user configures it themselves: create ONE of these files (project-level wins, never merged):",
@@ -16230,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."
@@ -16240,6 +16300,8 @@ function crewOrchestrationTemplate(agentIds) {
   return [
     '(forge crew orchestration. Argument: "$ARGUMENTS")',
     "",
+    "FAMILY GUARD (step 0, before anything else): if you do not have the crew_begin tool in your available tools, you are not in a forge session — STOP now and tell the user that /crew belongs to the forge agent, who should switch to forge (Tab) and rerun it there.",
+    "",
     `Configured forge subagents (task-tool vocabulary): ${agentIds.map((id) => `forge-${id}`).join(", ")}`,
     "",
     "You are entering CREW ORCHESTRATION discipline for this session (single subject: do not switch agents). Follow it exactly:",
@@ -16263,6 +16325,7 @@ var crewBeginTool = tool({
     })).describe("The declared subtask plan — decompose the objective into these before any execution; crew_close cross-checks the report against exactly this list")
   },
   execute: async (args, context) => {
+    noteToolAgent(context);
     const state = stateForBan(context.sessionID);
     const active = state ? resolveActivePlan(state) : null;
     if (active && active.doc.status === "draft") {
@@ -16325,6 +16388,7 @@ var crewCloseTool = tool({
     })).describe("The full crew report — one entry per declared subtask")
   },
   execute: async (args, context) => {
+    noteToolAgent(context);
     const crew = crews.get(context.sessionID);
     if (!crew)
       throw new Error("[forge:crew] No active crew in this session (crew state is in-memory and dies on host restart). Start one with /crew <objective>.");
@@ -16509,6 +16573,10 @@ async function continueIfEligible(client, sessionID) {
       goalProbe(`skip: not goal owner session=${sessionID} owner=${goal.doc.session || "(none)"}`);
       return;
     }
+    if (!sessionIsForgeFamily(sessionID)) {
+      goalProbe(`skip: agent switched to non-forge before send session=${sessionID}`);
+      return;
+    }
     if (accountedContinuationTurn) {
       if (turnHadActivity) {
         noProgressStreak.delete(sessionID);
@@ -16574,6 +16642,10 @@ async function continueIfEligible(client, sessionID) {
 function scheduleIdleContinuation(client, sessionID) {
   if (forgeDisabled)
     return;
+  if (!sessionIsForgeFamily(sessionID)) {
+    goalProbe(`skip: non-forge agent at schedule session=${sessionID}`);
+    return;
+  }
   const existing = idleTimers.get(sessionID);
   if (existing)
     clearTimeout(existing);
@@ -16666,23 +16738,15 @@ var server = async (input, options) => {
       forgeDisabled = forgeUserCfg?.disable === true;
       if (forgeDisabled)
         return;
-      for (const native of ["build", "plan"]) {
-        agentSection[native] = { ...agentSection[native] ?? {}, disable: true };
-      }
+      cfg.default_agent ??= FORGE_AGENT;
       const existing = agentSection[FORGE_AGENT];
-      const userDefinedForge = existing !== undefined;
       agentSection[FORGE_AGENT] = {
         ...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
       };
-      try {
-        const exp = JSON.stringify(cfg.experimental ?? "");
-        if (/background/i.test(exp))
-          nativeBackgroundSeen = true;
-      } catch {}
-      if (!userDefinedForge && !jobsKeepBuiltinShell && jobStage() < 1) {
+      if (!jobsKeepBuiltinShell && jobStage() < 2) {
         const entry = agentSection[FORGE_AGENT];
         entry.tools = { ...entry.tools ?? {}, shell: false, bash: false };
       }
@@ -16721,6 +16785,34 @@ var server = async (input, options) => {
         agentSection[id] = entry;
         materializedSnapshot[id] = entry;
       }
+      for (const id of Object.keys(agentSection)) {
+        if (!id.startsWith("forge-"))
+          continue;
+        const entry = agentSection[id];
+        const tools = { ...entry.tools ?? {} };
+        for (const t of FORGE_STATE_TOOLS)
+          if (tools[t] !== true)
+            tools[t] = false;
+        entry.tools = tools;
+      }
+      for (const [id, entry] of Object.entries(agentSection)) {
+        if (id === FORGE_AGENT || id.startsWith("forge-"))
+          continue;
+        const e = entry;
+        const tools = { ...e.tools ?? {} };
+        for (const t of FORGE_ALL_TOOLS)
+          if (tools[t] !== true)
+            tools[t] = false;
+        e.tools = tools;
+      }
+      for (const native of NATIVE_PARTITION_FALLBACKS) {
+        if (agentSection[native] !== undefined)
+          continue;
+        const tools = {};
+        for (const t of FORGE_ALL_TOOLS)
+          tools[t] = false;
+        agentSection[native] = { tools };
+      }
       if (process.env.FORGE_TEST_NO_DISPATCH_FETCH === "1") {
         modelsDevCatalog = null;
       } else {
@@ -16754,7 +16846,7 @@ var server = async (input, options) => {
 `);
         } catch {}
       }
-      if (watchdog.mode !== "off" && (input2.tool === "shell" || input2.tool === "bash")) {
+      if (watchdog.mode !== "off" && (input2.tool === "shell" || input2.tool === "bash") && sessionIsForgeFamily(input2.sessionID)) {
         const a = output?.args ?? {};
         const cmdText = typeof a.command === "string" ? a.command : typeof a.cmd === "string" ? a.cmd : undefined;
         watchdog.track(input2.callID, input2.sessionID, input2.tool, undefined, cmdText !== undefined ? commandNeedle(cmdText) : undefined);
@@ -16765,13 +16857,57 @@ var server = async (input, options) => {
           } catch {}
         }
       }
+      if (input2.tool === "task") {
+        const speaker = sessionAgents.get(input2.sessionID);
+        if (speaker !== undefined && !isForgeFamilyAgent(speaker)) {
+          const a = output?.args ?? {};
+          const target = typeof a.subagent_type === "string" ? a.subagent_type : typeof a.agent === "string" ? a.agent : undefined;
+          if (target && target.toLowerCase().startsWith("forge-")) {
+            throw new Error(`[forge:partition] Dispatch refused: "${target}" is a forge-family worker and the current agent ("${speaker}") is outside the forge family. Use the native general/explore subagents, or switch to the forge agent to dispatch forge-* workers.`);
+          }
+        }
+      }
+      if ((input2.tool === "write" || input2.tool === "edit") && input2.sessionID) {
+        const speaker = sessionAgents.get(input2.sessionID);
+        if (speaker !== undefined && !isForgeFamilyAgent(speaker)) {
+          const a = output?.args ?? {};
+          const raw = typeof a.filePath === "string" ? a.filePath : typeof a.path === "string" ? a.path : undefined;
+          if (raw) {
+            const state = stateForBan(input2.sessionID);
+            const base = state?.worktree ?? hostWorktree ?? "";
+            const abs = (isAbsolute(raw) ? raw : join5(base, raw)).replaceAll("\\", "/").toLowerCase();
+            if (abs.includes("/.opencode/plan/") || abs.includes("/.opencode/goal/")) {
+              throw new Error(`[forge:partition] Write refused: "${raw}" is inside the forge state directories (.opencode/plan, .opencode/goal), which belong to the forge agent in this workspace.`);
+            }
+          }
+        }
+      }
       if (typeof input2.tool === "string" && isWriteTool(input2.tool)) {
         const state = stateForBan(input2.sessionID);
         const active = state ? resolveActivePlan(state) : null;
         if (active && active.doc.status === "draft") {
-          throw new Error(`[forge] A plan is in draft; write operations are denied (${input2.tool}). Present the plan summary and call plan_approve for user approval, or /plan discard to abandon it.`);
+          throw new Error(`[forge] A plan is in draft; write operations are denied (${input2.tool}). Switch back to the forge agent to present it and complete plan approval (plan_approve), or run /plan discard to abandon the plan.`);
         }
       }
+      if (input2.sessionID && typeof input2.tool === "string") {
+        const speaker = sessionAgents.get(input2.sessionID);
+        if (speaker !== undefined) {
+          if (!isForgeFamilyAgent(speaker) && FORGE_TOOL_SET.has(input2.tool)) {
+            throw new Error(`[forge:partition] Tool refused: "${input2.tool}" belongs to the forge agent family and the current agent ("${speaker}") is outside it. Switch to forge (Tab) to use forge tooling.`);
+          }
+          if (isForgeFamilyAgent(speaker) && (input2.tool === "shell" || input2.tool === "bash") && !jobsKeepBuiltinShell && jobStage() < 2) {
+            throw new Error(`[forge:partition] Builtin shell refused: the forge family executes through forge_shell (jobs.keepBuiltinShell or jobs.mode: "native" restores the builtin shell). Re-issue the command through forge_shell.`);
+          }
+        }
+      }
+    },
+    "chat.message": async (input2) => {
+      if (forgeDisabled)
+        return;
+      const raw = input2;
+      if (typeof raw.sessionID === "string" && raw.sessionID && typeof raw.agent === "string" && raw.agent) {
+        sessionAgents.set(raw.sessionID, raw.agent);
+      }
     },
     "chat.params": async (input2, output) => {
       if (forgeDisabled)
@@ -16781,6 +16917,8 @@ var server = async (input, options) => {
       if (!sessionID)
         return;
       const agentName = typeof raw.agent === "string" ? raw.agent : raw.agent?.name;
+      if (typeof agentName === "string" && agentName)
+        sessionAgents.set(sessionID, agentName);
       if (typeof agentName !== "string" || !agentName.startsWith("forge-"))
         return;
       const frozen = sessionDepths.get(sessionID);
@@ -16863,6 +17001,7 @@ var server = async (input, options) => {
         if (typeof info?.id === "string" && info.id) {
           jobManager.onSessionEnd(info.id);
           sessionDepths.delete(info.id);
+          sessionAgents.delete(info.id);
         }
       }
     },
@@ -16871,6 +17010,8 @@ var server = async (input, options) => {
         return;
       if (!input2.callID)
         return;
+      if (!sessionIsForgeFamily(input2.sessionID))
+        return;
       output.env[WATCHDOG_ENV_MARK] = markerValue(input2.callID);
       watchdog.markSeen(input2.callID);
       if (process.env.FORGE_WATCHDOG_PROBE) {
@@ -16900,21 +17041,11 @@ var server = async (input, options) => {
       if (input2.tool === "goal_check")
         act.checks++;
     },
-    "tool.definition": async (input2, output) => {
-      if (input2.toolID === "shell" || input2.toolID === "bash") {
-        const props = output.parameters?.properties;
-        if (props && "run_in_background" in props)
-          nativeBackgroundSeen = true;
-      } else if (input2.toolID === "forge_shell" && jobStage() === 1) {
-        if (!output.description.startsWith(STAGE1_NOTE)) {
-          output.description = `${STAGE1_NOTE}
-${output.description}`;
-        }
-      }
-    },
     "experimental.chat.system.transform": async (input2, output) => {
       if (!input2.sessionID)
         return;
+      if (!sessionIsForgeFamily(input2.sessionID))
+        return;
       const crewActive = crews.get(input2.sessionID);
       if (crewActive && !output.system.some((s) => s.startsWith("[forge:crew-active]"))) {
         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.`);
@@ -16947,6 +17078,8 @@ ${output.description}`;
         return;
       if (!input2.sessionID)
         return;
+      if (!sessionIsForgeFamily(input2.sessionID))
+        return;
       const state = sessions.get(input2.sessionID);
       if (!state)
         return;
@@ -16968,7 +17101,7 @@ Post-compaction turns must keep following this goal and its constraints.`);
       if (!state)
         return;
       const goal = resolveLiveGoal(state);
-      if (goal)
+      if (goal && sessionIsForgeFamily(input2.sessionID))
         output.enabled = false;
     }
   };
@@ -16997,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,64 +1,64 @@
-{
-  "name": "@sorenllm/opencode-forge",
-  "version": "0.4.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.",
-  "type": "module",
-  "main": "./dist/index.js",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js"
-    },
-    "./server": {
-      "import": "./dist/index.js"
-    }
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "scripts": {
-    "bundle": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && bun build ./plugin.ts --outfile ./dist/index.js --target node --format esm",
-    "test": "node --test tests/*.test.mjs",
-    "typecheck": "tsc --noEmit"
-  },
-  "keywords": [
-    "opencode",
-    "opencode-plugin",
-    "subagents",
-    "plan",
-    "planning",
-    "workflow",
-    "single-agent",
-    "goal",
-    "crew",
-    "orchestration",
-    "background-jobs",
-    "shell",
-    "watchdog"
-  ],
-  "license": "MIT",
-  "author": "chengsongren",
-  "homepage": "https://github.com/ChengZiiii/opencode-forge#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ChengZiiii/opencode-forge.git"
-  },
-  "bugs": {
-    "url": "https://github.com/ChengZiiii/opencode-forge/issues"
-  },
-  "peerDependencies": {
-    "@opencode-ai/plugin": "^1.18.0"
-  },
-  "devDependencies": {
-    "@opencode-ai/plugin": "^1.18.0",
-    "@types/node": "^22.13.9",
-    "typescript": "^5.8.2"
-  },
-  "engines": {
-    "opencode": "^1.18.0"
-  },
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  }
-}
+{
+  "name": "@sorenllm/opencode-forge",
+  "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": {
+    ".": {
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "bundle": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && bun build ./plugin.ts --outfile ./dist/index.js --target node --format esm",
+    "test": "node --test tests/*.test.mjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "subagents",
+    "plan",
+    "planning",
+    "workflow",
+    "single-agent",
+    "goal",
+    "crew",
+    "orchestration",
+    "background-jobs",
+    "shell",
+    "watchdog"
+  ],
+  "license": "MIT",
+  "author": "chengsongren",
+  "homepage": "https://github.com/ChengZiiii/opencode-forge#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ChengZiiii/opencode-forge.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ChengZiiii/opencode-forge/issues"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "^1.18.0"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.18.0",
+    "@types/node": "^22.13.9",
+    "typescript": "^5.8.2"
+  },
+  "engines": {
+    "opencode": "^1.18.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}