@sorenllm/opencode-forge 0.17.0 → 0.18.1

package/README.md

@@ -189,7 +189,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 |
 | `<project>/.opencode/crew/*.md` | crew records (declared plan + arm/convert/abandon/close history; written at `crew_begin` registration, appended at each transition; record-only — never a resume mechanism) | user data — kept forever, uninstall never deletes |
-| 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 |
+| merged config object (RAM only) | forge agent, static `forge-<ns>-<id>` subagents (every pool family namespaced; the global fallback family `forge-global-<id>`), 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 |
@@ -417,8 +417,10 @@ complete.
 Forge subagents are **static, user-authored worker agents**: each forge.json
 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`
+session's model at dispatch), materializes as a native `forge-<ns>-<id>`
+subagent — EVERY pool family is namespaced, no exceptions (see
+*Pools on a shared host* below) — 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
@@ -461,12 +463,23 @@ directory it was initialized in, and the **host-wide materialization set**
 is the global layer plus each seen workspace's pool (one pool per
 directory: its walk-up nearest file). Pool membership is re-derived from
 disk truth on every resolve — a deleted pool file disappears at the next
-config hook. The FIRST seen workspace's pool keeps **plain `forge-<id>`
-ids** (a single-project host is unchanged); every other pool materializes
-**namespaced** as `forge-<ns>-<id>` (`ns` = the file's optional `pool`
-field, else the sanitized pool-directory name; the global fallback family
-derives `global`). Namespace and materialized-id collisions resolve
-deterministically with an error finding, never by silent shadowing.
+config hook. EVERY pool family materializes **namespaced** as
+`forge-<ns>-<id>` (`ns` = the file's declared top-level `pool` field, else
+the sanitized pool-directory basename); the **global fallback layer
+materializes under the fixed namespace `global`** as `forge-global-<id>`.
+**No family gets plain ids anywhere** — a materialized id is identical on
+every host regardless of the order workspaces were initialized in, so crew
+plans, rosters, and muscle memory transfer between hosts. Pool resolution
+order is deterministic — families ordered lexicographically by absolute
+pool-file path — and that same order governs cross-family materialized-id
+collisions: the earlier pool's agent wins, the colliding later agent is
+skipped with an error finding naming both files. Every materialized agent's
+task-vocabulary **description carries its pool provenance**: its namespace,
+its origin forge.json path, and — for every family except the global
+fallback — that it is dispatchable only from sessions whose workspace pool
+is that file; the global family names the global fallback layer as its
+origin. The same static text ships to every session — the dispatch gate
+(below) is the dynamic authority, the description is the honest label.
 
 **Dispatch is gated to the session's own pool.** Materializing every pool
 host-wide is a vocabulary necessity (the task tool's agent list is
@@ -492,18 +505,23 @@ a host re-initialization in that workspace materializes it (or move the
 agents into the global layer).
 
 **Id naming**: use plain role words (`research`, `coder`, …) — the plugin
-materializes every id as `forge-<id>` itself (namespaced pools:
-`forge-<ns>-<id>`). A `forge-`-prefixed id in the file would double up
-(`forge-coder` → agent `forge-forge-coder`); the loader auto-strips the
+materializes every id as `forge-<ns>-<id>` under its family's namespace
+(never a plain `forge-<id>`; pool-less workspaces get the fixed `global`
+namespace). A `forge-`-prefixed id in the file would double up
+(`forge-coder` → agent `forge-<ns>-forge-coder`); the loader auto-strips the
 prefix (all repetitions) with a warning so existing files keep working, but
 rename the entries to silence it. The namespace infix is never parsed back
 out of a materialized id.
 
 ```jsonc
 {
-  // non-primary pool files: namespace for this pool's ids (forge-<ns>-<id>).
+  // namespace for this pool's ids (forge-<ns>-<id> — EVERY pool is
+  // namespaced; declare it instead of riding the directory name).
   // Short, stable, [a-z0-9-] up to 24 chars — ids survive directory renames.
-  // Invalid values degrade to a warning + the directory-derived namespace.
+  // REQUIRED for crew-governed dispatch (the /crew compliance gate: no
+  // valid declared `pool` → `crew_begin` refuses and crew `forge-*`
+  // dispatches are blocked until the field is added). Invalid values
+  // degrade to a warning + the directory-derived namespace.
   // "pool": "aa",
   "agents": {
     // PINNED worker: model + thoughtLevel form an ATOMIC PAIR — set BOTH
@@ -551,8 +569,11 @@ A rejected entry costs only itself — its siblings materialize normally.
   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`
+- Each agent materializes as `forge-<ns>-<id>` — a subagent-mode agent
+   visible in the task tool's vocabulary (never hidden), whose description
+   names its **pool provenance** (namespace + origin forge.json path +
+   dispatchability scope; the global family names the global fallback
+   layer), 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
@@ -575,6 +596,28 @@ A rejected entry costs only itself — its siblings materialize normally.
 > error finding naming the missing half. Fix per entry: add the missing
 > `thoughtLevel`, or delete `model` to make it an Auto worker.
 
+> **BREAKING — every materialized id is now namespaced.** The
+> first-registered pool's plain-id privilege is gone: existing plain ids
+> (`forge-coder`) no longer exist, and there are **no compat aliases** —
+> deliberately, because an alias layer would resurrect the two-ids-one-agent
+> ambiguity this change kills (crew records and docs referencing old ids
+> are history artifacts). Migration:
+>
+> - **Single-pool workspaces**: add a short stable top-level `"pool"` field
+>   to your forge.json (`[a-z0-9-]`, 1–24 chars) and dispatch
+>   `forge-<pool>-<id>` from now on.
+> - **Pool-less workspaces** (global fallback roster): dispatch
+>   `forge-global-<id>` — the global layer materializes under the fixed
+>   namespace `global`.
+> - **New crew-governed pool-compliance gate**: `crew_begin` refuses to
+>   register, and every `task` dispatch of a `forge-*` worker from a
+>   crew-governed session is refused, while the workspace pool file lacks a
+>   valid declared top-level `pool` field. The fix is one line — add the
+>   field (the refusal suggests a namespace) — and the gate lifts
+>   hot-apply: the next resolve after the repair admits registration and
+>   dispatch with no host restart. Global-fallback sessions are exempt.
+>   Per-agent fail-soft findings never make the file non-compliant.
+
 **What applies when** — only a real materialization re-reads the pool
 files into the `forge-*` vocabulary. Materialization triggers (2026-10-01
 live finding): host boot (a freshly started CLI process reads the files as
@@ -586,7 +629,7 @@ opencode config file reloads. A NEW session on a long-lived shared host
 | --- | --- |
 | `thoughtLevel` on an existing agent | no (applies to NEW sessions of that agent; running sessions keep their frozen depth) — depth lookups resolve the pool files fresh at every dispatch, independent of materialization |
 | agent added / removed / edited, any pool file created or deleted | no restart — but not at the next session either: the materialized `forge-*` set rebuilds only at the next REAL materialization (host boot, opencode config reload, or a first config build); on a long-lived shared host pool changes wait for that rebuild or a restart. The crew gate, the session-domain dispatch gate, and depth lookups resolve the pool files fresh regardless — a DELETED pool file un-materializes at that next resolve |
-| a NEW directory joining the host (the first session of another project on the shared host) | no restart — that first config build itself re-initializes the plugin and registers that workspace and its pool (existing pools never flip; the first-seen workspace keeps plain ids) |
+| a NEW directory joining the host (the first session of another project on the shared host) | no restart — that first config build itself re-initializes the plugin and registers that workspace and its pool (existing pools never flip — every family namespaces by its own `pool` field or directory name, so ids never depend on arrival order) |
 
 ### Dispatching
 
@@ -725,10 +768,18 @@ requires a plan. The flow:
    alongside the choice — so you can verify the record really landed on
    disk (an earlier output order buried the path line, and the model
    reliably drops what it buries — leading with it is the fix). The
-   output then confirms the roster **grouped by pool with its origins**
-   (which forge.json families the dispatchable set materialized from, the
-   primary marked), presents the three execution-mode choices, and stops
-   the turn. Reconnaissance task calls are free BEFORE registration.
+    output then confirms the roster **grouped by pool with its origins**
+    (which forge.json families the dispatchable set materialized from —
+    every family rendered as `forge-<ns>-*`, no plain-id family),
+    presents the three execution-mode choices, and stops
+    the turn. Registration pre-flights **pool compliance**: the workspace
+    pool file must declare a valid top-level `pool` namespace — a
+    non-compliant file refuses the registration outright (see the BREAKING
+    note above; global-fallback sessions are exempt), and while a crew
+    governs the session every `forge-*` task dispatch re-checks the same
+    compliance (a file degraded mid-crew blocks further crew dispatches
+    until repaired — the fix is the one `"pool": "<suggested>"` line, and
+    it lifts hot-apply). Reconnaissance task calls are free BEFORE registration.
 2. **The pause is mechanical**: while the crew pends, every `task` dispatch is
    refused by an interception belt. The user chooses:
    - **supervised waves now** — `crew_begin {execution: "waves"}` lifts the

package/dist/index.js

@@ -12336,7 +12336,7 @@ tool.schema = exports_external;
 // plugin.ts
 import { execFileSync as execFileSync3 } from "node:child_process";
 import { appendFileSync, existsSync as existsSync3, mkdirSync as mkdirSync5, readdirSync as readdirSync4, readFileSync as readFileSync8, realpathSync, statSync as statSync5, writeFileSync as writeFileSync5 } from "node:fs";
-import { isAbsolute, join as join6, relative } from "node:path";
+import { basename as basename2, dirname as dirname4, isAbsolute, join as join6, relative } from "node:path";
 import { tmpdir as tmpdir3, homedir } from "node:os";
 
 // src/plan-file.ts
@@ -15052,12 +15052,19 @@ function rolePromptFor(agentId, def) {
     return def.prompt;
   return ROLE_PROMPTS[agentId] ?? `You are a ${agentId} worker. Execute the assigned task exactly as scoped.`;
 }
-function agentDescriptionFor(agentId, def) {
+function poolProvenanceLine(provenance) {
+  if ("global" in provenance) {
+    return `Pool 'global' — origin: the global fallback layer.`;
+  }
+  return `Pool '${provenance.ns}' — origin ${provenance.file}; dispatchable only from sessions whose workspace pool is this file.`;
+}
+function agentDescriptionFor(agentId, def, provenance) {
   const shape = def.shape === "readonly" ? "readonly" : "write";
   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}".`;
+  const base = `forge subagent "${agentId}" (${shape}, ${brain}) — dispatch via the task tool with subagent_type "forge-${agentId}".`;
+  return provenance === undefined ? base : `${base} ${poolProvenanceLine(provenance)}`;
 }
-function forgeAgentDef(agentId, def) {
+function forgeAgentDef(agentId, def, provenance) {
   const permission = { task: "deny" };
   const shape = def.shape ?? "write";
   if (shape === "readonly") {
@@ -15067,7 +15074,7 @@ function forgeAgentDef(agentId, def) {
   Object.assign(permission, def.permission ?? {});
   permission.task = "deny";
   const entry = {
-    description: agentDescriptionFor(agentId, def),
+    description: agentDescriptionFor(agentId, def, provenance),
     mode: "subagent",
     prompt: materializeAgentPrompt({
       agent: agentId,
@@ -15801,6 +15808,16 @@ function validatePoolField(v) {
     return { ok: false };
   return { ok: true, ns: trimmed };
 }
+function poolFileCompliance(top) {
+  const pool = isRecord(top) ? top.pool : undefined;
+  if (pool === undefined || pool === null) {
+    return { compliant: false, violation: 'missing top-level pool field — declare "pool": "<namespace>" ([a-z0-9-], 1-24 chars) to make this file crew-compliant' };
+  }
+  if (!validatePoolField(pool).ok) {
+    return { compliant: false, violation: `invalid top-level pool field ${JSON.stringify(String(pool))} — expected a string of [a-z0-9-], 1-24 chars after trim` };
+  }
+  return { compliant: true, violation: "" };
+}
 function dirBasename(dir) {
   let s = dir;
   while (s.length > 1 && (s.endsWith("/") || s.endsWith("\\")))
@@ -15882,30 +15899,32 @@ function createPoolResolver(deps) {
         if (f)
           uniqueFiles.add(f);
       }
-      const anyWorkspacePool = uniqueFiles.size > 0;
       if (globalPath && globalParsed)
         uniqueFiles.add(globalPath);
-      const primaryFile = anchors.length > 0 ? workspacePoolOf(anchors[0]) : null;
-      const plainPoolFile = primaryFile ?? (!anyWorkspacePool && globalParsed !== null && globalPath ? globalPath : null);
-      const orderedFiles = [plainPoolFile, ...[...uniqueFiles].filter((f) => f !== plainPoolFile).sort(codepointCompare)].filter((f) => f !== null);
+      const orderedFiles = [...uniqueFiles].sort(codepointCompare);
       const families = [];
       for (const file2 of orderedFiles) {
         const parsed = readPool(file2);
         if (parsed && file2 !== globalPath)
           findings.push(...parsed.findings);
-        const isPrimary = plainPoolFile !== null && file2 === plainPoolFile;
         let declaredPool = null;
-        if (!isPrimary && parsed) {
-          const v = validatePoolField(parsed.declaredPool);
-          if (parsed.declaredPool !== undefined && parsed.declaredPool !== null) {
-            if (v.ok) {
-              declaredPool = v.ns;
-            } else {
-              findings.push({ level: "warn", code: "pool-field-invalid", message: `${file2}: invalid "pool" field ${JSON.stringify(String(parsed.declaredPool))} (expected [a-z0-9-], 1-24 chars) — falling back to the directory-derived namespace` });
+        if (parsed) {
+          if (file2 === globalPath) {
+            if (parsed.declaredPool !== undefined && parsed.declaredPool !== null) {
+              findings.push({ level: "warn", code: "pool-field-ignored-global", message: `${file2}: the declared "pool" field ${JSON.stringify(String(parsed.declaredPool))} is ignored — the global fallback namespace is fixed to "global"` });
+            }
+          } else {
+            const v = validatePoolField(parsed.declaredPool);
+            if (parsed.declaredPool !== undefined && parsed.declaredPool !== null) {
+              if (v.ok) {
+                declaredPool = v.ns;
+              } else {
+                findings.push({ level: "warn", code: "pool-field-invalid", message: `${file2}: invalid "pool" field ${JSON.stringify(String(parsed.declaredPool))} (expected [a-z0-9-], 1-24 chars) — falling back to the directory-derived namespace` });
+              }
             }
           }
         }
-        families.push({ file: file2, parsed, ns: null, declaredPool, primary: isPrimary });
+        families.push({ file: file2, parsed, ns: "", declaredPool });
       }
       const allDeclared = new Set;
       for (const f of families)
@@ -15913,9 +15932,7 @@ function createPoolResolver(deps) {
           allDeclared.add(f.declaredPool);
       const usedNs = new Map;
       for (const f of families) {
-        if (f.primary)
-          continue;
-        const base = f.declaredPool ?? (f.file === globalPath ? "global" : sanitizeNamespace(dirBasename(parentDirLabel(parentDirLabel(f.file)))));
+        const base = f.file === globalPath ? "global" : f.declaredPool ?? sanitizeNamespace(dirBasename(parentDirLabel(parentDirLabel(f.file))));
         let ns = base;
         let suffix = 2;
         while ((usedNs.has(ns) || ns !== base && allDeclared.has(ns)) && suffix < 100) {
@@ -15934,7 +15951,7 @@ function createPoolResolver(deps) {
         const own = f.parsed?.agents ?? {};
         const ids = [];
         for (const rawId of Object.keys(own)) {
-          const matId = f.ns === null ? rawId : `${f.ns}-${rawId}`;
+          const matId = `${f.ns}-${rawId}`;
           const existing = agents[matId];
           if (existing !== undefined) {
             findings.push({ level: "error", code: "materialized-id-collision", message: `materialized agent forge-${matId} from ${f.file} collides with the one from ${existing.file} — the earlier pool in resolution order wins, this agent is skipped` });
@@ -15943,7 +15960,7 @@ function createPoolResolver(deps) {
           agents[matId] = { materializedId: matId, def: own[rawId], ns: f.ns, file: f.file };
           ids.push(matId);
         }
-        origins.push({ file: f.file, ns: f.ns, declaredPool: f.declaredPool, primary: f.primary, materializedIds: ids });
+        origins.push({ file: f.file, ns: f.ns, declaredPool: f.declaredPool, materializedIds: ids });
       }
       return { families: origins, agents, findings };
     }
@@ -16126,6 +16143,28 @@ function sessionPoolFileOf(anchor) {
     return poolResolver.workspacePoolOf(anchor);
   return loaderForAnchor(anchor).load().projectPath;
 }
+function crewPoolComplianceRefusal(anchor) {
+  const poolFile = sessionPoolFileOf(anchor);
+  if (poolFile === null)
+    return null;
+  let text;
+  try {
+    text = readFileSync8(poolFile, "utf8");
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    return `[forge:crew] Pool compliance refused: this session's workspace pool file (${poolFile}) could not be read (${reason}). ` + `Repair the file so it is readable JSONC declaring a valid top-level "pool" namespace ([a-z0-9-], 1-24 chars) — REQUIRED for crew-governed dispatch. ` + `The gate lifts hot-apply: the next resolve after the repair admits registration/dispatch; no host restart.`;
+  }
+  const parsed = parseForgeJsonc(text);
+  if (!parsed.ok) {
+    return `[forge:crew] Pool compliance refused: this session's workspace pool file (${poolFile}) does not parse (${parsed.error.message} at line ${parsed.error.line}). ` + `Repair the file so it parses and declares a valid top-level "pool" namespace ([a-z0-9-], 1-24 chars) — REQUIRED for crew-governed dispatch. ` + `The gate lifts hot-apply: the next resolve after the repair admits registration/dispatch; no host restart.`;
+  }
+  const verdict = poolFileCompliance(parsed.config);
+  if (verdict.compliant)
+    return null;
+  const fam = resolvePools()?.families.find((f) => foldPath(f.file) === foldPath(poolFile));
+  const suggested = fam?.ns ?? sanitizeNamespace(basename2(dirname4(dirname4(poolFile))));
+  return `[forge:crew] Pool compliance refused: this session's workspace pool file (${poolFile}) is non-compliant — ${verdict.violation}. ` + `Minimal fix: add or repair the top-level "pool": "${suggested}" field (a [a-z0-9-] string, 1-24 chars — REQUIRED for crew-governed dispatch). ` + `The gate lifts hot-apply: the next resolve after the repair admits registration/dispatch; no host restart.`;
+}
 var crews = new Map;
 function crewRecordPathFor(worktree, objective) {
   const dir = join6(worktree, ".opencode", "crew");
@@ -16352,7 +16391,8 @@ function readPlanDir(worktree) {
 function ensureSession(sessionID, worktree) {
   const existing = sessions.get(sessionID);
   if (existing) {
-    existing.worktree = worktree;
+    if (!isRootish(worktree))
+      existing.worktree = worktree;
     return existing;
   }
   const state = { sessionID, worktree };
@@ -17038,9 +17078,9 @@ var CREW_INIT_TEMPLATE = [
   "",
   "Two axes, distinct: POOLS follow workspaces (sole ownership above — dispatch is gated to the session's own pool / the global fallback); SESSION ARTIFACTS (plan/goal/crew records) follow the session. A forge.json in another workspace is not dispatchable from this session.",
   "",
-  '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. When you configure it: name ids as PLAIN role words WITHOUT the `forge-` prefix — the plugin materializes every id as `forge-<id>` automatically (a `forge-`-prefixed id doubles up as `forge-forge-coder` and is auto-stripped with a warning). Give EVERY agent a SHORT prompt derived from the role the user asked for — one or two sentences describing its job (the user trims or extends from there); write a long prompt ONLY when the user explicitly asks for that agent. Give EVERY agent an EXPLICIT `shape`: `readonly` for read-only roles (reviewer/scout/planner — denies write/edit/bash and the patch family), `write` for implementers and build drivers. ALSO include a proposed short stable `pool` namespace (a [a-z0-9-] word up to 24 chars — e.g. "aa" for a specialist pool) so the materialized ids survive directory renames.',
+  '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. When you configure it: name ids as PLAIN role words WITHOUT the `forge-` prefix (a `forge-`-prefixed id doubles up and is auto-stripped with a warning) — every pool materializes as `forge-<ns>-<id>` under its `pool` namespace (the global fallback materializes as `forge-global-<id>`). Give EVERY agent a SHORT prompt derived from the role the user asked for — one or two sentences describing its job (the user trims or extends from there); write a long prompt ONLY when the user explicitly asks for that agent. Give EVERY agent an EXPLICIT `shape`: `readonly` for read-only roles (reviewer/scout/planner — denies write/edit/bash and the patch family), `write` for implementers and build drivers. ALWAYS include the top-level `pool` namespace (a [a-z0-9-] word up to 24 chars — e.g. "aa" for a specialist pool): it is REQUIRED for crew-governed dispatch (the compliance gate) and keeps the materialized ids stable across directory renames.',
   "",
-  "Template (JSONC — comments allowed): ids are plain role words (research, coder, ...) — the plugin adds the `forge-` prefix at materialization; `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. Optional per agent: `prompt` — a short role description; an explicit prompt FULLY overrides the built-in role (only the ids `research` and `review` carry built-ins; any other id without a prompt gets a generic one-liner and will not know its job). Optional per agent: `shape` — an ABSENT shape defaults to WRITE (open permissions — the compatibility-preserving default for existing pools); `shape: \"readonly\"` is the explicit seal that denies the mutating-tool family (write/edit/bash + patch/applypatch/apply/multiedit) for read-only roles. Optional top level: `pool` — the file's namespace.",
+  'Template (JSONC — comments allowed): ids are plain role words (research, coder, ...) — every pool materializes as `forge-<ns>-<id>` (the global fallback materializes as `forge-global-<id>`); `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. Optional per agent: `prompt` — a short role description; an explicit prompt FULLY overrides the built-in role (only the ids `research` and `review` carry built-ins; any other id without a prompt gets a generic one-liner and will not know its job). Optional per agent: `shape` — an ABSENT shape defaults to WRITE (open permissions — the compatibility-preserving default for existing pools); `shape: "readonly"` is the explicit seal that denies the mutating-tool family (write/edit/bash + patch/applypatch/apply/multiedit) for read-only roles. Top level: `pool` — the file\'s namespace, REQUIRED for crew-governed dispatch.',
   "{template}",
   "",
   "After the file is saved: file edits, creations, and deletions apply at the next config hook — NO host restart is needed, and a DELETED pool file un-materializes its agents (deletion is real — no zombie pools survive on disk truth)."
@@ -17050,7 +17090,7 @@ function crewOrchestrationTemplate(resolution) {
   const families = resolution?.families ?? [];
   const globalPath = forgeConfigPaths({ homeDir: process.env.FORGE_TEST_FORGE_HOME ?? homedir() }).global;
   const otherLines = families.map((f) => {
-    const label = f.primary ? "primary pool (plain forge-<id> ids)" : `pool ${f.ns} (forge-${f.ns}-*)`;
+    const label = `pool ${f.ns} (forge-${f.ns}-*)`;
     return `  - ${label} — origin ${f.file} — NOT dispatchable from this session (unless this session's worktree is owned by that pool / it is the global fallback): ${f.materializedIds.map((id) => `forge-${id}`).join(", ") || "no agents"}`;
   });
   return [
@@ -17077,7 +17117,7 @@ function crewOrchestrationTemplate(resolution) {
 `);
 }
 var crewBeginTool = tool({
-  description: `Register this session's crew (from /crew) with its DECLARED subtask plan — the crew starts PENDING: the execution-mode choice (waves / convert to goal / standby) is the user's. Dual-purpose: called with {execution} ONLY (no objective/subtasks) it ARMS the pending crew — "waves" lifts the dispatch belt, "goal" ends the crew as a conversion record (the following goal_write arm dialog is the user's gate). One-call register+arm ({objective, subtasks, execution:"waves"}) is legal ONLY while a live active goal governs the session (born armed, never pends). Refuses: active crew, plan draft, missing/duplicated subtasks. Crew state is in-memory: a host restart ends it honestly.`,
+  description: `Register this session's crew (from /crew) with its DECLARED subtask plan — the crew starts PENDING: the execution-mode choice (waves / convert to goal / standby) is the user's. Dual-purpose: called with {execution} ONLY (no objective/subtasks) it ARMS the pending crew — "waves" lifts the dispatch belt, "goal" ends the crew as a conversion record (the following goal_write arm dialog is the user's gate). One-call register+arm ({objective, subtasks, execution:"waves"}) is legal ONLY while a live active goal governs the session (born armed, never pends). Refuses: active crew, plan draft, missing/duplicated subtasks, a non-compliant workspace pool file (missing/invalid top-level "pool" namespace — required for crew-governed dispatch). Crew state is in-memory: a host restart ends it honestly.`,
   args: {
     objective: tool.schema.string().optional().describe("One-line crew objective (from /crew) — required on registration, ABSENT on the arm call"),
     execution: tool.schema.string().optional().describe('Arm action: "waves" (supervised waves — lifts the belt) or "goal" (convert to a goal contract). Alone = arm the pending crew; with objective+subtasks = one-call born-armed registration, legal only under a governing active goal.'),
@@ -17111,9 +17151,9 @@ var crewBeginTool = tool({
         `[forge:crew] CREW IS NOT INITIALIZED: no forge subagent is materialized for this session's roster (neither the workspace pool nor the global fallback yields an agent). Crew orchestration is unavailable until the user sets it up.`,
         `Two layers, SOLE OWNERSHIP: the workspace pool — the NEAREST .opencode/forge.json walking up from this session's worktree (${paths.project}) — IS the whole roster when it exists; the global layer (${paths.global}) serves only as the fallback when the workspace has none (a fallback, NOT a merge; forge.json files nested deeper in the workspace subtree are ignored — the same workspace-ownership strictness as opencode's native MCP config).`,
         "Two axes, distinct: POOLS follow workspaces (sole ownership above — dispatch is gated to the session's own pool / the global fallback); SESSION ARTIFACTS (plan/goal/crew records) follow the session. A forge.json in another workspace is not dispatchable from this session.",
-        `Template (JSONC): top-level optional "pool" names this file's namespace (short stable [a-z0-9-] up to 24 chars — non-primary pools materialize as forge-<ns>-<id>); {"agents": {"research": {"model": "provider/model", "thoughtLevel": "low", "shape": "readonly", "prompt": "short role description"}}} — an absent shape defaults to WRITE (open permissions); "shape": "readonly" is the explicit seal denying write/edit/bash + the patch family for read-only roles.`,
-        "Agent ids are plain role words WITHOUT the `forge-` prefix — the plugin materializes each id as `forge-<id>` (namespaced pools: `forge-<ns>-<id>`); a prefixed id is auto-stripped with a warning.",
-        "The user may configure it themselves, or ask you to write the file — only on their explicit go-ahead. When you write it: give every agent a SHORT prompt from the role the user asked for (one or two sentences; long only on explicit request), give every agent an EXPLICIT shape (readonly for read-only roles like reviewer/scout/planner; write for implementers and build drivers), and INCLUDE a proposed short stable `pool` namespace so ids survive directory renames. File edits, creations, and deletions apply at the next config hook — no host restart needed, and a DELETED pool file un-materializes its agents (deletion is real)."
+        `Template (JSONC): the top-level "pool" field names this file's namespace (short stable [a-z0-9-] up to 24 chars — REQUIRED for crew-governed dispatch; every pool materializes as forge-<ns>-<id>, the global fallback materializes as forge-global-<id>); {"pool": "short-stable-namespace", "agents": {"research": {"model": "provider/model", "thoughtLevel": "low", "shape": "readonly", "prompt": "short role description"}}} — an absent shape defaults to WRITE (open permissions); "shape": "readonly" is the explicit seal denying write/edit/bash + the patch family for read-only roles.`,
+        "Agent ids are plain role words WITHOUT the `forge-` prefix — every pool materializes as `forge-<ns>-<id>` under its `pool` namespace (the global fallback materializes as `forge-global-<id>`); a prefixed id is auto-stripped with a warning.",
+        "The user may configure it themselves, or ask you to write the file — only on their explicit go-ahead. When you write it: give every agent a SHORT prompt from the role the user asked for (one or two sentences; long only on explicit request), give every agent an EXPLICIT shape (readonly for read-only roles like reviewer/scout/planner; write for implementers and build drivers), and INCLUDE the top-level `pool` namespace — it is REQUIRED for crew-governed dispatch (the compliance gate refuses a missing or invalid field) and keeps ids stable across directory renames. File edits, creations, and deletions apply at the next config hook — no host restart needed, and a DELETED pool file un-materializes its agents (deletion is real)."
       ];
       if (sessionLoaded && Object.keys(sessionLoaded.agents).length > 0 && sessionProject && !sessionCovered) {
         lines2.push(`NOTE: this session's workspace DOES have a forge.json (${sessionProject}) with usable agents — but this host has NOT materialized it (no initialization in that workspace). Re-initialize the host in that workspace, or move the agents into the global layer (${globalPoolPath}).`);
@@ -17195,6 +17235,11 @@ var crewBeginTool = tool({
     if (execution === "goal") {
       throw new Error('[forge:crew] execution:"goal" converts an already-registered PENDING crew — register the plan first (no execution), then convert. Under a governing goal, only "waves" one-call arming is legal (the loop already owns the goal).');
     }
+    if (anchor) {
+      const complianceRefusal = crewPoolComplianceRefusal(anchor);
+      if (complianceRefusal)
+        throw new Error(complianceRefusal);
+    }
     const governed = execution === "waves";
     const lineage = String(args.lineage ?? "").trim();
     const anchorDir = anchor || hostWorktree;
@@ -17228,7 +17273,7 @@ var crewBeginTool = tool({
     for (const f of families.slice(0, 8)) {
       if (f === sessionFamily)
         continue;
-      const label = f.primary ? "primary pool (plain forge-<id> ids)" : `pool ${f.ns} (forge-${f.ns}-*)`;
+      const label = `pool ${f.ns} (forge-${f.ns}-*)`;
       familyLines.push(`   - NOT dispatchable from this session — ${label}: ${f.file} — ${f.materializedIds.map((id) => `forge-${id}`).join(", ") || "no agents"}`);
     }
     if (families.length > 8)
@@ -17565,6 +17610,17 @@ var server = async (input, options) => {
   hostWorktree = effectiveInitDir;
   rememberHostAnchor(effectiveInitDir);
   const client = input.client;
+  const resolveSessionAnchorForPools = async (sessionID) => {
+    if (!sessionID)
+      return "";
+    try {
+      const rec = client?.session?.get ? await client.session.get({ path: { id: sessionID } }) : undefined;
+      const anchor = effectiveWorktree(rec?.worktree, rec?.directory);
+      if (anchor && !isRootish(anchor))
+        return anchor;
+    } catch {}
+    return sessions.get(sessionID)?.worktree ?? "";
+  };
   jobClient = input.client;
   const jobsOpts = options?.jobs;
   if (jobsOpts?.mode === "auto" || jobsOpts?.mode === "forge" || jobsOpts?.mode === "native")
@@ -17680,11 +17736,13 @@ var server = async (input, options) => {
         console.warn(`[forge:config] ${finding.level}: ${finding.message}`);
       }
       materializedSnapshot = {};
+      const globalMaterializationPath = globalPoolPathOf();
       for (const [matId, agent] of Object.entries(resolution?.agents ?? {})) {
         const id = `forge-${matId}`;
         if (agentSection[id] !== undefined)
           continue;
-        const entry = forgeAgentDef(matId, agent.def);
+        const provenance = foldPath(agent.file) === foldPath(globalMaterializationPath) ? { global: true } : { ns: agent.ns, file: agent.file };
+        const entry = forgeAgentDef(matId, agent.def, provenance);
         agentSection[id] = entry;
         materializedSnapshot[id] = entry;
       }
@@ -17732,7 +17790,7 @@ var server = async (input, options) => {
         const agentCount = Object.keys(resolution?.agents ?? {}).length;
         const primaryAnchorDir = hostAnchors[0] ?? undefined;
         const template = agentCount > 0 ? crewOrchestrationTemplate(resolution ?? null) : CREW_INIT_TEMPLATE.replaceAll("{paths}", `   - ${forgeConfigPaths({ projectDir: primaryAnchorDir, homeDir: process.env.FORGE_TEST_FORGE_HOME ?? homedir() }).project}
-   - ${forgeConfigPaths({ projectDir: primaryAnchorDir, homeDir: process.env.FORGE_TEST_FORGE_HOME ?? homedir() }).global}`).replaceAll("{template}", JSON.stringify({ pool: "short-stable-namespace (optional, [a-z0-9-] up to 24 chars — non-primary pools materialize as forge-<ns>-<id>)", agents: { research: { model: "provider/model", thoughtLevel: "low", shape: "readonly", prompt: "short role description — what this agent does" }, coder: { model: "provider/model", thoughtLevel: "low", shape: "write", prompt: "short role description — what this agent does" } } }, null, 2).split(`
+   - ${forgeConfigPaths({ projectDir: primaryAnchorDir, homeDir: process.env.FORGE_TEST_FORGE_HOME ?? homedir() }).global}`).replaceAll("{template}", JSON.stringify({ pool: "namespace (REQUIRED for crew-governed dispatch, [a-z0-9-] up to 24 chars — every pool materializes as forge-<ns>-<id>; the global fallback materializes as forge-global-<id>)", agents: { research: { model: "provider/model", thoughtLevel: "low", shape: "readonly", prompt: "short role description — what this agent does" }, coder: { model: "provider/model", thoughtLevel: "low", shape: "write", prompt: "short role description — what this agent does" } } }, null, 2).split(`
 `).map((l) => "   " + l).join(`
 `));
         const description = agentCount > 0 ? "forge crew orchestration: register a declared subtask plan, execute it in waves of parallel native task calls, close with an evidence-checked report" : "forge crew orchestration — NOT INITIALIZED: no forge subagents configured; invoking it shows the one-time setup guidance";
@@ -17775,8 +17833,7 @@ var server = async (input, options) => {
           const agentId = target.slice("forge-".length);
           const entry = resolution?.agents[agentId];
           if (resolution && entry) {
-            const bound = sessions.get(input2.sessionID);
-            const anchor = bound?.worktree ?? "";
+            const anchor = await resolveSessionAnchorForPools(input2.sessionID);
             if (!anchor) {
               if (!poolGateUnknownNotes.has(input2.sessionID)) {
                 poolGateUnknownNotes.add(input2.sessionID);
@@ -17795,6 +17852,17 @@ var server = async (input, options) => {
         if (pendingCrew && pendingCrew.mode === "pending") {
           throw new Error(`[forge:crew] Dispatch refused: the crew "${pendingCrew.objective}" is PENDING (registered, not armed). Present the execution-mode choice to the user — supervised waves now / convert to a goal contract / standby — then arm per their choice with crew_begin {execution: "waves" | "goal"}. Reconnaissance task calls are free only BEFORE registration.`);
         }
+        if (target && target.toLowerCase().startsWith("forge-") && input2.sessionID) {
+          const crew = crews.get(input2.sessionID);
+          if (crew && (crew.mode === "pending" || crew.mode === "executing")) {
+            const anchor = await resolveSessionAnchorForPools(input2.sessionID);
+            if (anchor) {
+              const complianceRefusal = crewPoolComplianceRefusal(anchor);
+              if (complianceRefusal)
+                throw new Error(complianceRefusal);
+            }
+          }
+        }
       }
       if ((input2.tool === "write" || input2.tool === "edit") && input2.sessionID) {
         const speaker = sessionAgents.get(input2.sessionID);
@@ -18129,11 +18197,13 @@ async function v2Setup(ctx) {
       try {
         const resolver = createPoolResolver({ homeDir: process.env.FORGE_TEST_FORGE_HOME ?? homedir() });
         const resolution = resolver.resolve([process.cwd()]);
+        const v2GlobalPath = forgeConfigPaths({ homeDir: process.env.FORGE_TEST_FORGE_HOME ?? homedir() }).global;
         for (const [matId, agent] of Object.entries(resolution.agents)) {
           const id = `forge-${matId}`;
           if (draft.get(id) !== undefined)
             continue;
-          const v1def = forgeAgentDef(matId, agent.def);
+          const provenance = foldPath(agent.file) === foldPath(v2GlobalPath) ? { global: true } : { ns: agent.ns, file: agent.file };
+          const v1def = forgeAgentDef(matId, agent.def, provenance);
           draft.update(id, (agentDraft) => {
             agentDraft.description = v1def.description;
             agentDraft.system = v1def.prompt;

package/package.json

@@ -1,64 +1,64 @@
-{
-  "name": "@sorenllm/opencode-forge",
-  "version": "0.17.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/"
-  }
-}
+{
+  "name": "@sorenllm/opencode-forge",
+  "version": "0.18.1",
+  "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/"
+  }
+}